# Tutorial para fazer Módulos da Óptica de Raios

Este tutorial vai te guiar pelo processi básico de criação de um módulo personalizado, que pode ser completamente feito dentro do app web, sem necessidade de qualquer ambiente de desenvolvimento externo.

O recurso "Módulo" da Simulação de Óptica de Raios permite a criação de combinações modulares de objetos com parâmetros personalizados, pontos de controle personalizados, e malhas de objetos. Esse recurso extende a capacidade deste simulador ao combinar, especializar, ou reparametrizar objetos criados por ferramentas existentes para criar novas ferramentas. Por exemplo, o módulo `CircleSource` (ver Ferramentas -> Outros -> Importar módulo) combina uma série de fontes pontuais criadas pela ferramenta existente "Fonte pontual (<360°)" ao redor de um círculo, para fazer uma ferramenta "fonte circular" que não existia no simulador. O módulo `FresnelLens` especializa a ferramenta "Glass->Custom equation", para que a equação represente uma curva específica da lente Fresnel parametrizada pelo número de fatias, assim fazendo uma ferramenta especializada "Lente Fresnel", que tambem não existia anteriormente. Além de fazer novas ferramentas, esse recurso também pode fazer algumas demonstrações de óptica mais interativas. Por exemplo, ao arrastar o terceiro ponto de controle do módulo `BeamExpander`, pode-se ver diretamente como a posição do ponto focal em comum das duas lentes afeta a largura do raio, sem necessitar ajustar os comprimentos focais das duas lentes individualmente.

Note que nem todos pontos de controle personalizados requerem um módulo. Alguns casos simples podem ser feitos com o recurso "ponto de mauseio" (ver a seção "Agrupar, rotacionar e ajustar escala de objetos" no popup de ajuda no canto inferior direito do simulador). Já que fazer um módulo é muito mais complicado que criar um ponto de manuseio, deve-se primeiro checar se o seu caso oise ser feito pelo recurso "ponto de manuseio" antes de considerar fazer um módulo. Veja aqui para um exemplo não trivial de um ponto de controle personalizado (mover dois sacos plásticos pra fora da água) sem utilizar um módulo.

## O editor JSON incluso

Este app atualmente não possui uma interface visual para criação de módulos, então é preciso diretamente editar o JSON da cena.

Você pode habilitar o editor JSON incluso ao clicar no menu "configurações" no canto superior direito do app, e então marcar "Exibir editor JSON". O editor de código deve aparecer no lado esquerdo do app, com o código JSON da cena atual. Certifique-se que a sua tela é grande o suficiente, já que este recurso não funciona bem em dispositivos móveis.

Conforme você edita a cena utilizando o editor visual de cena, o código no editor JSON vai atualizar automaticamente, com a parte modificada destacada. Do mesmo modo, editar o código no editor JSON diretamente vai atualizar a cena automaticamente. Se você não for familiar com JSON ou qualquer tipo de formato de dados à base de texto, pode ser útil brincar com isso por um tempo.

Em particular, quando se adiciona um objeto à cena, ele é adicionado à lista `objs`. E se você modificar algumas de suas propriedades para um valor não padrão, elas aparecem como pares chave-valor nesse objeto.

IMPORTANTE: Nessa página de tutorial, se você não ver o editor de código JSON nos iframes abaixo, por favor habilite-o e recarregue esta página, pois vocÊ precisará de ver o código para entender como funciona.

## O básico de um módulo

Vamos ver o nosso primeiro exemplo de módulo.

Você deve ver quatro linhas de texto. Olhando no editor JSON, você verá que as primeira duas estão diretamente na lista `objs` de nível superior como normal, mas as últimas duas estão em `modules.ExampleModule.objs` ao invés disso.

O `module` é um dicionário onde a chave é o nome do módulo (neste caso `ExampleModule`), e o valor é a definição do módulo. Em específico, a lista `modules.ExampleModule.objs` descreve (o padrão de) objetos dentro desse módulo, que é diferente do `objs` do nível superior que descreve objetos na cena.

To put the objects within the module to the scene, we need a "module object" in the top-level `objs` array, which is `objs[2]` in this example, whose type is `ModuleObj` and whose `module` property is the name of the module.

The module definition in the `modules` dictionary is not editable by the visual scene editor. So when you click any of the last two texts in this example, you are just selecting the module object, and not the objects in the module. Since the coordinates of the texts in the module definition in this example are absolute coordinates, the last two texts are not draggable. We will learn how to make them draggable by using control points later.

If you select a module object, there is a "Demodulize" button on the object bar. Clicking it will "expand" the module object into its constituent, and `objs` will now contain all the four texts. This operation is not reversible (but of course you can click "undo").

The suggested way of creating a module currently is to first create an empty module using the JSON editor, create some objects using the visual scene editor, and then cut and paste the objects from `objs` to `modules.ModuleName.objs` using the JSON editor.

## Adding parameters

The objects within the module can be defined by a set of parameters. Let’s look at a simple example

Here `modules.ModuleName.params` is an array of strings `"name=start:step:end:default"` defining the name of the variables and the range of the sliders. The sliders appear on the object bar when the module object is selected.

Within the `modules.ExampleModule.objs` array, any values can be expressed using those parameters. Within a string (such as the `text` property of a `TextLabel`), the equations of the variables are enclosed by a pair of backticks. For number parameters (such as the `fontSize` property of a `TextLabel`), you need to make it a string so that you can use the backtick format in it, so each equation is sandwiched by a pair of backticks and a pair of quotes. The equation are evaluated with math.js (syntax). See there for the available syntax and functions you can use in the equations.

The actual values of the parameters are stored in the `params` property of the module object, which, unlike the module definition, can be directly edited by the scene editor using the slider.

## Adding control points

To make the module object draggable, we need to parametrize the objects within the module using a set of control points. Let’s look at the example

Here `modules.ModuleName.numPoints` defines the number of control points. The coordinates of the control points are (`x_1`, `y_1`), (`x_2`, `y_2`), etc, and are used in the same ways as the parameters within `modules.ExampleModule.objs` as described by the previous section. Note that the index starts from 1.

The actual values of the coordinates of the control points are stored in the `points` property of the module object, which, unlike the hard-coded coordinates in Example 1, can be edited by the visual scene editor by dragging the control points, each shown as two concentric gray circles in the scene. If you drag elsewhere in the module object (such as dragging the text labels), all the control points will move together.

Since our module object can now move, it is now quite easy to create multiple instances as in usual tools. The name of the module is shown in the Tools -> Other menu, and you can select that and then click two points in the blank space in sequence for the two control points to create another instance of the module. You can also use the “duplicate” button on the object bar.

## Arrays and conditionals

More complicated module can be built using arrays and conditionals. Let’s look at the example

Within `modules.ExampleModule.objs`, any objects in an array can have two special keys: `"for"` and `"if"`. The value of the `"for"` key is either a string of the format `"name=start:step:end"` defining a loop variable, or an array of several strings of this format describing a multidimensional loop. Such an object in the array is duplicated several times according to the loop variables. The value of the `"if"` key is a string representing a math.js expression that evaluates to a boolean, and such an object is included in the array if and only if the boolean is true.

To prevent accidental infinite loop, the total number of iteration of each `"for"` loop is limited by the `maxLoopLength` property of the module definition, whose default value is 1000. You can set this property to a larger value if needed.

## Objects with built-in custom equations

For objects that already have custom equation input (such as Mirror -> Custom Equation), the equation property in the JSON is a string representing a LaTeX equation, rather than a math.js expression. To include custom parameters in the equation, you must use the same template syntax as if the LaTeX equation were a regular text. So the part enclosed by the backticks is in math.js expression, while the part outside is in LaTeX. The module parameters can only be accessed in the math.js part, and the independent variables of the custom equation (e.g. \(x\)) can only be accessed in the LaTeX part. Here is an example of generating a mirror with equation \(y=\cos(2\pi x+\phi)\), where \(\phi\) is a module parameter

In the future, there may be a way to unified the equation input.

## Objects with built-in shape parametrization

For objects that already support different ways to define its shape (currently only Glass -> Spherical lens). There are special JSON syntax for such objects that can be used within the module definition, even if they are always defined by shape in the top level `objs` array. Here is an example