Class: Simulator

Simulator(scene, ctxMain, ctxBelowLight, ctxAboveLight, ctxGrid, ctxVirtual, enableTimer, rayCountLimitopt, glMain, glVirtual)

The simulator class, which simulates the optical system described by the Scene class and renders the scene (optical elements, decorations, rays, etc) on the canvas layers.

When a ray interacts with an object (optical element) in the scene, the object itself is responsible for handling the interaction, and the simulator only call the related methods of the object. See onSimulationStart, checkRayIntersects and onRayIncident in the BaseSceneObj class for more information. The rendering of the object is also a method draw of the object itself called by the simulator.

In the Ray Optics Simulator web app, a single instance of this class is used in the entire session to simulate the scene interactively. updateSimulation is called whenever the scene is updated. If the simulation is too long, the simulator will automatically pause and resume to prevent the browser from not responding, and emit the simulationPause event to notify the UI to update the simulation status. When exporting the scene to PNG or SVG, a new instance of this class is created and updateSimulation is called once to render the scene without pausing.

This class can also be used by other projects, including those running in a standalone environment (e.g. Node.js) to simulate and render the scene without the UI. Note however that even if one is only interested in the numerical results (e.g. detector readings), the canvas layers are still required for the simulator to work properly. In the future, a headless mode may be implemented to allow the simulator to run without the canvas layers.

Constructor

new Simulator(scene, ctxMain, ctxBelowLight, ctxAboveLight, ctxGrid, ctxVirtual, enableTimer, rayCountLimitopt, glMain, glVirtual)

Creates a new Simulator instance.

Parameters:
Name Type Attributes Default Description
scene Scene

The scene to be simulated.
ctxMain CanvasRenderingContext2D | C2S

The default context for drawing the scene.
ctxBelowLight CanvasRenderingContext2D | C2S

The context for drawing the scene below the light layer.
ctxAboveLight CanvasRenderingContext2D | C2S

The context for drawing the scene above the light layer.
ctxGrid CanvasRenderingContext2D | C2S

The context for drawing the grid layer.
ctxVirtual CanvasRenderingContext2D

The virtual context for color adjustment.
enableTimer boolean

Whether to enable the timer for the simulation.
rayCountLimit number <optional>
 Infinity

The maximum number of processed rays in the simulation.
glMain WebGLRenderingContext | null

The default WebGL context for drawing the scene (used only if the colorMode is not 'default').
glVirtual WebGLRenderingContext | null

Additional WebGL context.
Source:

Members

MIN_RAY_SEGMENT_LENGTH

The minimal length between two interactions with rays (when smaller than this, the interaction will be ignored). Also the threshold for surface merging.

Source:

brightnessScale

Properties:
Name Type Description
brightnessScale number

The brightness scale of the simulation. 0 if undetermined, -1 if inconsistent.
Source:

ctxAboveLight

Properties:
Name Type Description
ctxAboveLight CanvasRenderingContext2D | C2S

The context for drawing the this.scene above the light layer.
Source:

ctxBelowLight

Properties:
Name Type Description
ctxBelowLight CanvasRenderingContext2D | C2S

The context for drawing the this.scene below the light layer.
Source:

ctxGrid

Properties:
Name Type Description
ctxGrid CanvasRenderingContext2D | C2S

The context for drawing the grid layer.
Source:

ctxMain

Properties:
Name Type Description
ctxMain CanvasRenderingContext2D | C2S

The default context for drawing the this.scene. If other layers are present, this is the context for drawing the light layer only.
Source:

ctxVirtual

Properties:
Name Type Description
ctxVirtual CanvasRenderingContext2D

The virtual context for color adjustment.
Source:

dpr

Properties:
Name Type Description
dpr number

The device pixel ratio of the canvases.
Source:

enableTimer

Properties:
Name Type Description
enableTimer boolean

Whether to enable the timer for the simulation so that it automatically pauses and resumes when the simulation is too long.
Source:

error

Properties:
Name Type Description
error string

The error message of the simulation.
Source:

eventListeners

Properties:
Name Type Description
eventListeners object

The event listeners of the simulator.
Source:

glMain

Properties:
Name Type Description
glMain WebGLRenderingContext | null

The default WebGL context for drawing the this.scene (used only if the colorMode is not 'default').
Source:

glVirtual

Properties:
Name Type Description
glVirtual WebGLRenderingContext | null

Additional WebGL context.
Source:

isSVG

Properties:
Name Type Description
isSVG boolean

Whether the canvas is being exported to SVG.
Source:

pendingRays

Properties:
Name Type Description
pendingRays Array.<Ray>

The rays to be processed.
Source:

processedRayCount

Properties:
Name Type Description
processedRayCount number

The number of rays processed in the simulation.
Source:

rayCountLimit

Properties:
Name Type Description
rayCountLimit number

The maximum number of processed rays in the simulation. When this limit is reached, the simulation will stop.
Source:

scene

Properties:
Name Type Description
scene Scene

The scene to be simulated.
Source:

shouldSimulatorStop

Properties:
Name Type Description
shouldSimulatorStop boolean

Whether the simulation should stop immediately in the next step of the timer.
Source:

simulationStartTime

Properties:
Name Type Description
simulationStartTime Date

The time when the simulation starts.
Source:

simulationTimerId

Properties:
Name Type Description
simulationTimerId number

The ID of the timer for the simulation.
Source:

totalTruncation

Properties:
Name Type Description
totalTruncation number

The total truncated brightness of rays in the infinite series of internal reflection during the simulation.
Source:

warning

Properties:
Name Type Description
warning string

The warning message of the simulation.
Source:

Methods

emit(eventName, data)

Emit an event.

Parameters:
Name Type Description
eventName string

The name of the event.
data any

The data to be passed to the callback functions.
Source:

on(eventName, callback)

Add an event listener to the simulator.

Parameters:
Name Type Description
eventName string

The name of the event.
callback function

The callback function.
Source:

stopSimulation() → {void}

Stop the simulation.

Source:
Returns:
Type
void

updateSimulation(skipLight, skipGrid) → {void}

Run the simulation and draw the this.scene on the canvases.

Parameters:
Name Type Description
skipLight boolean

Whether to skip the light layer.
skipGrid boolean

Whether to skip the grid layer.
Source:
Returns:
Type
void

validate() → {void}

Check the simulation and display warnings or errors if necessary.

Source:
Returns:
Type
void

Events

simulationComplete

The event emitted when the simulation completes (all the rays are processed completely).

Source:

simulationPause

The event emitted when the simulation pauses (when the timer is enabled and the maximum continue running time is exceeded).

Source:

simulationStart

The event emitted when the simulation starts.

Source:

simulationStop

The event emitted when the simulation stops (when the maximum number of processed rays is reached or if the user force stop the simulation).

Source: