Class: Simulator

Simulator(scene, ctxMainopt, ctxBelowLightopt, ctxAboveLightopt, ctxGridopt, ctxVirtualopt, enableTimeropt, rayCountLimitopt, glMainopt, glVirtualopt)

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. See integrations/README.md for an easy way to do this from other programming languages.

Constructor

new Simulator(scene, ctxMainopt, ctxBelowLightopt, ctxAboveLightopt, ctxGridopt, ctxVirtualopt, enableTimeropt, rayCountLimitopt, glMainopt, glVirtualopt)

Creates a new Simulator instance.

Parameters:
Name Type Attributes Default Description
scene Scene

The scene to be simulated.
ctxMain CanvasRenderingContext2D | C2S <optional>
 null

The default context for drawing the scene.
ctxBelowLight CanvasRenderingContext2D | C2S <optional>
 null

The context for drawing the scene below the light layer.
ctxAboveLight CanvasRenderingContext2D | C2S <optional>
 null

The context for drawing the scene above the light layer.
ctxGrid CanvasRenderingContext2D | C2S <optional>
 null

The context for drawing the grid layer.
ctxVirtual CanvasRenderingContext2D <optional>
 null

The virtual context for color adjustment.
enableTimer boolean <optional>
 false

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

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

The default WebGL context for drawing the scene (used only if the colorMode is not 'default').
glVirtual WebGLRenderingContext | null <optional>
 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:

UNDEFINED_BEHAVIOR_THRESHOLD

The threshold for the total brightness of rays where an undefined behavior is encountered. Above this threshold, a warning will be shown.

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:

isLightLayerSynced

Properties:
Name Type Description
isLightLayerSynced boolean

Whether the light layer is in sync with the scene.
Source:

isSVG

Properties:
Name Type Description
isSVG boolean

Whether the canvas is being exported to SVG.
Source:

lastOrigin

Properties:
Name Type Description
lastOrigin Point

The origin of the scene during the last redraw.
Source:

lastScale

Properties:
Name Type Description
lastScale number

The scale of the scene during the last redraw.
Source:

manualLightRedraw

Properties:
Name Type Description
manualLightRedraw boolean

Whether to manually redraw the light layer. True if the user turns off "Auto refresh".
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:

totalUndefinedBehavior

Properties:
Name Type Description
totalUndefinedBehavior number

The total brightness of rays where an undefined behavior is encountered.
Source:

undefinedBehaviorObjs

Properties:
Name Type Description
undefinedBehaviorObjs Array.<BaseSceneObj>

The objects causing the first undefined behavior.
Source:

warning

Properties:
Name Type Description
warning string

The warning message of the simulation.
Source:

Methods

declareUndefinedBehavior(ray, objs) → {void}

Declare that the ray encounters an undefined behavior due to the objects in objs.

Parameters:
Name Type Description
ray Ray

The ray.
objs Array.<BaseSceneObj>

The objects causing the undefined behavior.
Source:
Returns:
Type
void

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:

getThemeImageColor(imageType, alpha) → {Array.<number>}

Get the theme-based color for an image type.

Parameters:
Name Type Description
imageType string

The type of image ('realImage', 'virtualImage', 'virtualObject', 'colorRealImage', 'colorVirtualImage', 'colorVirtualObject')
alpha number

The alpha value
Source:
Returns:

RGBA color array

Type
Array.<number>

getThemeImageSize(imageType) → {number}

Get the theme-based size for an image type.

Parameters:
Name Type Description
imageType string

The type of image ('realImage', 'virtualImage', 'virtualObject', 'colorRealImage', 'colorVirtualImage', 'colorVirtualObject')
Source:
Returns:

Image size

Type
number

getThemeRayColor(rayType, alpha) → {Array.<number>}

Get the theme-based color for a ray type.

Parameters:
Name Type Description
rayType string

The type of ray ('ray', 'extendedRay', 'forwardExtendedRay', 'colorRay', 'colorExtendedRay', 'colorForwardExtendedRay')
alpha number

The alpha value
Source:
Returns:

RGBA color array

Type
Array.<number>

getThemeRayDash(rayType) → {Array.<number>}

Get the theme-based dash pattern for a ray type.

Parameters:
Name Type Description
rayType string

The type of ray ('ray', 'extendedRay', 'forwardExtendedRay', 'colorRay', 'colorExtendedRay', 'colorForwardExtendedRay')
Source:
Returns:

Dash pattern array

Type
Array.<number>

manualRedrawLightLayer() → {void}

Manually redraw the light layer.

Source:
Returns:
Type
void

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, forceRedraw) → {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.
forceRedraw boolean

Whether to force redraw the light layer (when the user choose to manually redraw the light layer).
Source:
Returns:
Type
void

validate() → {void}

Check the simulation and display warnings or errors if necessary.

Source:
Returns:
Type
void

Events

lightLayerSyncChange

The event emitted when the sync status of the light layer changes.

Type:
  • object
Properties:
Name Type Description
isSynced boolean

Whether the light layer is in sync with the scene.
Source:

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:

update

The event emitted when the simulation is to be updated. Fired even if the light layer and/or grid layer are not going to be redrawn.

Source: