# Class: Scene

## Scene()

Represents the optical scene for simulation. The scene contains the instances of scene objects (from `sceneObjs`) and the settings of the simulation. Scene objects include optical elements (e.g. mirrors, lenses), detectors, decorations (e.g. rulers, text labels), and special objects (e.g. handles, cropboxes). It also contains the module definitions used in the scene. Since the settings of the scene may affect the behavior of the scene objects, a reference to the scene is also stored in each scene object.

The data represented by the scene can be serialized to JSON and deserialized from JSON. The JSON data format of the scene is versioned, and the version number is stored in the JSON data. The scene is backward-compatible with older versions of the JSON data format, and the scene is converted to the current version when loaded. Note that the background image of the scene is not serialized, and the viewport size is adapted to the current viewport when deserialized.

In the Ray Optics Simulator web app, a single instance is used, representing the current scene being edited and simulated, and is the main data structure of the app. The scene is serialized or deserialized to/from JSON when saving, loading, sync with URL, or undo/redo. Some scene-unrelated settings for the app (e.g. whether to show the status box) are not stored in the scene but in the browser's local storage.

This class can also be used by other projects, including those running in a standalone environment (e.g. Node.js).

## Constructor

#### new Scene()

##### Properties:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the scene.
`modules` | Object.<string, ModuleDef> | The definitions of modules used in the scene.
`objs` | Array.<BaseSceneObj> | The objects (optical elements and/or decorations created by the user with "Tools") in the scene.
`mode` | string | The mode of the scene. Possible values: 'rays' (Rays), 'extended' (Extended Rays), 'images' (All Images), 'observer' (Seen by Observer).
`rayModeDensity` | number | The density of rays in 'rays' and 'extended' modes.
`imageModeDensity` | number | The density of rays in 'images' and 'observer' modes.
`showGrid` | boolean | The "Grid" option indicating if the grid is visible.
`snapToGrid` | boolean | The "Snap to Grid" option indicating if mouse actions are snapped to the grid.
`lockObjs` | boolean | The "Lock Objects" option indicating if the objects are locked.
`gridSize` | number | The size of the grid.
`observer` | Circle | null | The observer of the scene, null if not set.
`lengthScale` | number | The length scale used in line width, default font size, etc in the scene.
`origin` | Point | The origin of the scene in the viewport.
`scale` | number | The scale factor (the viewport CSS pixel per internal length unit) of the scene.
`width` | number | The width (in CSS pixels) of the viewport.
`height` | number | The height (in CSS pixels) of the viewport.
`simulateColors` | boolean | The "Simulate Color" option indicating if the color (wavelength) of the rays is simulated (also affecting whether the options of color filtering or Cauchy coefficients of some objects are shown.)
`colorMode` | string | The mode of rendering the color of rays (color mapping functions, etc, including the brightness behavior when `simulateColors` is false). This represents the intended behavior for the scene, but the hardware or renderer may or may not support it. Possible values are 'legacy' (Legacy), 'linear' (Linear Value), 'linearRGB' (Linear RGB), 'reinhard' (Reinhard), and 'colorizedIntensity' (Color-coded Intensity).
`showRayArrows` | boolean | The "Show Ray Arrows" option indicating if the arrows are shown on the rays indicating its direction.
`symbolicBodyMerging` | boolean | The "Symbolic body-merging" option in the gradient-index glass objects (which is a global option), indicating if the symbolic math is used to calculate the effective refractive index resulting from the "body-merging" of several gradient-index glass objects.
`randomSeed` | string | null | The seed for the random number generator used in the simulation, null if using randomly generated seed. Using a seed allows the simulation to be deterministic for the same version of this app when randomness is used. However, reproducibility is only guaranteed if the scene is just loaded (that is, no other editing has been done on the scene). Also, reproducibility is not guaranteed across different versions of the app.
`rng` | function | The random number generator.
`backgroundImage` | Object | null | The background image of the scene, null if not set.

Source:
  - Scene.js, line 66

### Members

#### opticalObjs

##### Properties:

Name | Type | Description
--- | --- | ---
`opticalObjs` | Array.<BaseSceneObj> | The objects in the scene which are optical. Module objects are expanded recursively. If the user edits only the non-optical part of the scene, then the content of this array will not change.

Source:
  - Scene.js, line 125

#### rayDensity

##### Properties:

Name | Type | Description
--- | --- | ---
`rayDensity` | number | The mode-dependent ray density.

Source:
  - Scene.js, line 112

### Methods

#### addModule(moduleName, moduleDef) → {boolean}

Add a module definition.

##### Parameters:

Name | Type | Description
--- | --- | ---
`moduleName` | string |
`moduleDef` | ModuleDef |

Source:
  - Scene.js, line 366

##### Returns:

Whether the module is successfully added.

Type
  boolean

#### cloneObj(index) → {BaseSceneObj}

Clone the object at an index.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

Source:
  - Scene.js, line 330

##### Returns:

The cloned object

Type
  BaseSceneObj

#### cloneObjsByHandle(index)

Clone the objects bound to the handle at an index.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

Source:
  - Scene.js, line 340

#### loadJSON(json, callback)

Load the scene from JSON.

##### Parameters:

Name | Type | Description
--- | --- | ---
`json` | string |
`callback` | loadJSONCallback | The callback function when the entire scene or a resource (e.g. image) is loaded.

Source:
  - Scene.js, line 153

#### pushObj(obj)

Add an object to the scene.

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | BaseSceneObj |

Source:
  - Scene.js, line 276

#### removeModule(moduleName)

Remove a given module and demodulize all corresponding module objects.

##### Parameters:

Name | Type | Description
--- | --- | ---
`moduleName` | string |

Source:
  - Scene.js, line 383

#### removeObj(index)

Remove the object at an index.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

Source:
  - Scene.js, line 303

#### setScaleWithCenter(value, centerX, centerY)

Set the scale of the scene while keeping a given center point fixed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | number | The new scale factor.
`centerX` | number | The x-coordinate of the center point.
`centerY` | number | The y-coordinate of the center point.

Source:
  - Scene.js, line 403

#### unshiftObj(obj)

Add an object to the scene at the beginning of the list.

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | BaseSceneObj |

Source:
  - Scene.js, line 285

#### validateDelayed()

Perform an delayed validation on the scene and generate warnings if necessary. This method should not be called when the editing is in progress.

Source:
  - Scene.js, line 415