# Class: CircleGrinGlass

## sceneObjs.CircleGrinGlass()

Gradient-index glass of the shape of a circle.

Tools -> Glass -> Gradient-index Circle

## Constructor

#### new CircleGrinGlass()

##### Properties:

Name | Type | Description
--- | --- | ---
`p1` | Point | The center of the circle.
`p2` | Point | A point on the boundary of the circle.
`refIndexFn` | string | The refractive index function in x and y in LaTeX format.
`origin` | Point | The origin of the (x,y) coordinates used in the refractive index function.
`stepSize` | number | The step size for the ray trajectory equation.
`intersectTol` | number | The epsilon for the intersection calculations.

Source:
  - sceneObjs/glass/CircleGrinGlass.js, line 36

### Extends

- BaseGrinGlass

### Members

#### error

##### Properties:

Name | Type | Description
--- | --- | ---
`error` | string | null | The error message of the object.

Overrides:
  - BaseGrinGlass#error
Source:
  - sceneObjs/BaseSceneObj.js, line 46

#### isOptical

Whether the object is optical (i.e. is a light source, interacts with rays, or detects rays).

Overrides:
  - BaseGrinGlass#isOptical
Source:
  - sceneObjs/BaseSceneObj.js, line 111

#### scene

##### Properties:

Name | Type | Description
--- | --- | ---
`scene` | Scene | The scene the object belongs to.

Inherited From:
  - BaseSceneObj#scene
Source:
  - sceneObjs/BaseSceneObj.js, line 44

#### serializableDefaults

The default values of the properties of the object which are to be serialized. The keys are the property names and the values are the default values. If some properties is default, they will not be serialized and will be deserialized to the default values.

Overrides:
  - BaseGrinGlass#serializableDefaults
Source:
  - sceneObjs/BaseSceneObj.js, line 106

#### supportsSurfaceMerging

Whether the object supports surface merging. (This is currently only for glasses, where the surfaces of two glasses are merged to form a single surface if the surfaces overlap.)

Overrides:
  - BaseGrinGlass#supportsSurfaceMerging
Source:
  - sceneObjs/BaseSceneObj.js, line 116

#### type

The type of the object.

Overrides:
  - BaseGrinGlass#type
Source:
  - sceneObjs/BaseSceneObj.js, line 101

#### warning

##### Properties:

Name | Type | Description
--- | --- | ---
`warning` | string | null | The warning message of the object.

Inherited From:
  - BaseSceneObj#warning
Source:
  - sceneObjs/BaseSceneObj.js, line 48

### Methods

#### arePropertiesDefault(propertyNames) → {boolean}

Check whether the given properties of the object are all the default values.

##### Parameters:

Name | Type | Description
--- | --- | ---
`propertyNames` | Array.<string> | The property names to be checked.

Inherited From:
  - BaseSceneObj#arePropertiesDefault
Source:
  - sceneObjs/BaseSceneObj.js, line 86

##### Returns:

Whether the properties are all the default values.

Type
  boolean

#### checkMouseOver(mouse) → {DragContext|null}

Check whether the mouse is over the object, which is called when the user moves the mouse over the scene. This is used for deciding the highlighting of the object, and also for deciding that if the user starts dragging at this position, which part of the object should be dragged.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mouse` | Mouse | The mouse object.

Inherited From:
  - BaseSceneObj#checkMouseOver
Source:
  - sceneObjs/BaseSceneObj.js, line 206

##### Returns:

The drag context if the user starts dragging at this position, or null if the mouse is not over the object.

Type
  DragContext | null

#### checkRayIntersects(ray) → {Point|null}

Check whether the object intersects with the given ray. Called during the ray tracing when `ray` is to be tested whether it intersects with the object. Find whether they intersect and find the nearset intersection if so. Implemented only by optical elements that affects or detect rays.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray.

Overrides:
  - BaseGrinGlass#checkRayIntersects
Source:
  - sceneObjs/BaseSceneObj.js, line 238

##### Returns:

- The intersection (closest to the beginning of the ray) if they intersect.

Type
  Point | null

#### devRefIndex(bodyMergingObj) → {BodyMergingObj}

Receives a bodyMerging object and returns a new bodyMerging object for the region of `bodyMergingObj` excluding current GRIN glass.

##### Parameters:

Name | Type | Description
--- | --- | ---
`bodyMergingObj` | BodyMergingObj |

Inherited From:
  - BaseGrinGlass#devRefIndex
Source:
  - sceneObjs/BaseGrinGlass.js, line 213

##### Returns:

Type
  BodyMergingObj

#### draw(canvasRenderer, isAboveLight, isHovered)

Draw the object on the canvas. Called once before the simulator renders the light with `isAboveLight === false` and once after with `isAboveLight === true`. Due to historical reason, some objects use this function to do some initialization. This should be avoided in the future.

##### Parameters:

Name | Type | Description
--- | --- | ---
`canvasRenderer` | CanvasRenderer | The canvas renderer.
`isAboveLight` | boolean | Whether the rendering layer is above the light layer.
`isHovered` | boolean | Whether the object is hovered by the mouse, which determines the style of the object to be drawn, e.g., with lighlighted color.

Overrides:
  - BaseGrinGlass#draw
Source:
  - sceneObjs/BaseSceneObj.js, line 144

#### fillGlass(canvasRenderer, isAboveLight, isHovered)

Fill the glass with the color that represents the refractive index. To be called in `draw` of a subclass when the path has been set up with `canvasRenderer.ctx.beginPath()`, etc.

##### Parameters:

Name | Type | Description
--- | --- | ---
`canvasRenderer` | CanvasRenderer | The canvas renderer.
`isAboveLight` | boolean | Whether the rendering layer is above the light layer.
`isHovered` | boolean | Whether the object is hovered by the mouse, which determines the style of the object to be drawn, e.g., with lighlighted color.

Inherited From:
  - BaseGlass#fillGlass
Source:
  - sceneObjs/BaseGlass.js, line 57

#### getError() → {string|null}

Get the error message of the object.

Inherited From:
  - BaseSceneObj#getError
Source:
  - sceneObjs/BaseSceneObj.js, line 264

##### Returns:

The error message.

Type
  string | null

#### getIncidentType(ray) → {number}

Get whether the ray is incident from inside to outside or from outside to inside.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray to be checked.

Overrides:
  - BaseGrinGlass#getIncidentType
Source:
  - sceneObjs/BaseGlass.js, line 267

##### Returns:

- 1 if the ray is incident from inside to outside, -1 if the ray is incident from outside to inside, 0 if the ray is equivalent to not intersecting the glass (e.g. intersecting with two overlapping surfaces of the glass), and NaN for other situations (e.g. parallel to a surface).

Type
  number

#### getRefIndexAt(point, ray) → {number}

Get the refractive index at a point for a ray

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Point | The point to get the refractive index. For normal glasses, this parameter is not used. But it will be used in GRIN glasses.
`ray` | Ray | The ray to be refracted.

Inherited From:
  - BaseGlass#getRefIndexAt
Source:
  - sceneObjs/BaseGlass.js, line 251

##### Returns:

- The refractive index at the point.

Type
  number

#### getWarning() → {string|null}

Get the warning message of the object.

Inherited From:
  - BaseSceneObj#getWarning
Source:
  - sceneObjs/BaseSceneObj.js, line 272

##### Returns:

The warning message.

Type
  string | null

#### getZIndex() → {number}

Get the z-index of the object for the sequence of drawing. Called before the simulator starts to draw the scene.

Inherited From:
  - BaseSceneObj#getZIndex
Source:
  - sceneObjs/BaseSceneObj.js, line 132

##### Returns:

The z-index. The smaller the number is, the earlier `draw` is called.

Type
  number

#### initFns()

Do the partial derivatives of the refractive index function and parse the functions.

Inherited From:
  - BaseGrinGlass#initFns
Source:
  - sceneObjs/BaseGrinGlass.js, line 139

#### initRefIndex(ray) → {BodyMergingObj}

Receives a ray, and returns a bodyMerging object for the point ray.p1

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray |

Inherited From:
  - BaseGrinGlass#initRefIndex
Source:
  - sceneObjs/BaseGrinGlass.js, line 254

##### Returns:

Type
  BodyMergingObj

#### isInsideGlass(point)

Returns `true` if `point` is inside the glass, otherwise returns `false`

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Point |

Overrides:
  - BaseGrinGlass#isInsideGlass
Source:
  - sceneObjs/BaseGrinGlass.js, line 316

#### isOnBoundary(point)

Returns `true` if `point` is on the boundary of the glass, otherwise returns `false`

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Point |

Overrides:
  - BaseGrinGlass#isOnBoundary
Source:
  - sceneObjs/BaseGrinGlass.js, line 324

#### isOutsideGlass(point)

Returns `true` if `point` is outside the glass, otherwise returns `false`

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Point |

Overrides:
  - BaseGrinGlass#isOutsideGlass
Source:
  - sceneObjs/BaseGrinGlass.js, line 308

#### move(diffX, diffY)

Move the object by the given displacement. Called when the user use arrow keys to move the object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`diffX` | number | The x-coordinate displacement.
`diffY` | number | The y-coordinate displacement.

Inherited From:
  - BaseSceneObj#move
Source:
  - sceneObjs/BaseSceneObj.js, line 154

#### multRefIndex(bodyMergingObj) → {BodyMergingObj}

Receives a bodyMerging object and returns a new bodyMerging object for the overlapping region of `bodyMergingObj` and the current GRIN glass.

##### Parameters:

Name | Type | Description
--- | --- | ---
`bodyMergingObj` | BodyMergingObj |

Inherited From:
  - BaseGrinGlass#multRefIndex
Source:
  - sceneObjs/BaseGrinGlass.js, line 172

##### Returns:

Type
  BodyMergingObj

#### onConstructMouseDown(mouse, ctrl, shift) → {ConstructReturn}

Mouse down event when the object is being constructed by the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mouse` | Mouse | The mouse object.
`ctrl` | boolean | Whether the control key is pressed.
`shift` | boolean | Whether the shift key is pressed.

Overrides:
  - BaseGrinGlass#onConstructMouseDown
Source:
  - sceneObjs/BaseSceneObj.js, line 165

##### Returns:

The return value.

Type
  ConstructReturn

#### onConstructMouseMove(mouse, ctrl, shift) → {ConstructReturn}

Mouse move event when the object is being constructed by the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mouse` | Mouse | The mouse object.
`ctrl` | boolean | Whether the control key is pressed.
`shift` | boolean | Whether the shift key is pressed.

Inherited From:
  - BaseSceneObj#onConstructMouseMove
Source:
  - sceneObjs/BaseSceneObj.js, line 176

##### Returns:

The return value.

Type
  ConstructReturn

#### onConstructMouseUp(mouse, ctrl, shift) → {ConstructReturn}

Mouse up event when the object is being constructed by the user.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mouse` | Mouse | The mouse object.
`ctrl` | boolean | Whether the control key is pressed.
`shift` | boolean | Whether the shift key is pressed.

Inherited From:
  - BaseSceneObj#onConstructMouseUp
Source:
  - sceneObjs/BaseSceneObj.js, line 187

##### Returns:

The return value.

Type
  ConstructReturn

#### onConstructUndo() → {ConstructReturn}

Undo event when the object is being constructed by the user.

Inherited From:
  - BaseSceneObj#onConstructUndo
Source:
  - sceneObjs/BaseSceneObj.js, line 195

##### Returns:

The return value.

Type
  ConstructReturn

#### onDrag(mouse, dragContext, ctrl, shift)

The event when the user drags the object, which is fired on every step during the dragging. The object should be updated according to `DragContext` which is returned by `checkMouseOver`. `dragContext` can be modified during the dragging.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mouse` | Mouse | The mouse object.
`dragContext` | DragContext | The drag context.
`ctrl` | boolean | Whether the control key is pressed.
`shift` | boolean | Whether the shift key is pressed.

Inherited From:
  - BaseSceneObj#onDrag
Source:
  - sceneObjs/BaseSceneObj.js, line 217

#### onRayEnter(ray)

Handle the event when a ray enters the glass. This is called during the surface merging process, and is called by the glass object who is handling the surface merging, rather than by the simulator. Unlike `onRayIncident` which is only called for one representative object who is responsible for handling the surface merging, this function is called for every object that consistute the merged surface. For notmal glasses nothing needs to be done in this function, but for GRIN glasses, the body-merging object in the ray should be updated here, so that the ray knows that it now feels a different refractive index gradient.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray that enters the glass.

Inherited From:
  - BaseGlass#onRayEnter
Source:
  - sceneObjs/BaseGlass.js, line 275

#### onRayExit(ray)

Handle the event when a ray exits the glass. This is called during the surface merging process, and is called by the glass object who is handling the surface merging, rather than by the simulator. Unlike `onRayIncident` which is only called for one representative object who is responsible for handling the surface merging, this function is called for every object that consistute the merged surface. For notmal glasses nothing needs to be done in this function, but for GRIN glasses, the body-merging object in the ray should be updated here, so that the ray knows that it now feels a different refractive index gradient.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray that exits the glass.

Inherited From:
  - BaseGlass#onRayExit
Source:
  - sceneObjs/BaseGlass.js, line 283

#### onRayIncident(ray, rayIndex, incidentPoint, surfaceMergingObjs) → {SimulationReturn|null}

The event when a ray is incident on the object. Called during the ray tracing when `ray` has been calculated to be incident on the object at the `incidentPoint`. Perform the interaction between `ray` and the object. Implemented only by optical elements that affects or detect rays. If `ray` is absorbed by the object, return `{ isAbsorbed: true }`. If there is a primary outgoing ray, directly modify `ray` to be the outgoing ray. This includes the case when the object is a detector that does not modify the direction of the ray. If there are secondary rays to be emitted, return `{ newRays: [ray1, ray2, ...] }`. Note that if there are more than one secondary rays, image detection does not work in the current version, and `rayN.gap` should be set to `true`. But for future support, the secondary ray which is to be of the same continuous bunch or rays should have consistent index in the `newRays` array. Sometimes keeping tracks of all the rays may result in infinite loop (such as in a glass). Depending on the situation, some rays with brightness below a certain threshold (such as 0.01) may be truncated. In this case, the brightness of the truncated rays should be returned as `truncation`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray.
`rayIndex` | number | The index of the ray in the array of all rays currently in the scene in the simulator. In particular, in a bunch of continuous rays, the rays are ordered by the time they are emitted, and the index is the order of emission. This can be used to downsample the rays and increase the individual brightness if it is too low.
`incidentPoint` | Point | The point where the ray is incident on the object, which is the intersection point found by `checkRayIntersects`.
`surfaceMergingObjs` | Array.<BaseSceneObj> | The objects that are merged with the current object. If two or more objects with `supportsSurfaceMerging === true` has overlapping surfaces (often acheived by using the grid), and if a ray is incident on those surfaces together, only one of the object will be have `onRayIncident` being called, and the other objects will be in `surfaceMergingObjs`. In this case, this function must also deal with the combination of the surface before doing the actual interaction. Note that treating them as two very close surfaces may not give the correct result due to an essential discontinuity of ray optics (which is smoothed out at the scale of the wavelength in reality).

Overrides:
  - BaseGrinGlass#onRayIncident
Source:
  - sceneObjs/BaseSceneObj.js, line 256

##### Returns:

The return value.

Type
  SimulationReturn | null

#### onSimulationStart() → {SimulationReturn|null}

The event when the simulation starts. If this object is a light source, it should emit rays here by setting `newRays`. If the object is a detector, it may do some initialization here.

Inherited From:
  - BaseSceneObj#onSimulationStart
Source:
  - sceneObjs/BaseSceneObj.js, line 226

##### Returns:

The return value.

Type
  SimulationReturn | null

#### populateObjBar(objBar)

Populate the object bar. Called when the user selects the object (it is selected automatically when the user creates it, so the construction may not be completed at this stage).

##### Parameters:

Name | Type | Description
--- | --- | ---
`objBar` | ObjBar | The object bar to be populated.

Overrides:
  - BaseGrinGlass#populateObjBar
Source:
  - sceneObjs/BaseSceneObj.js, line 123

#### refract(ray, rayIndex, incidentPoint, normal, n1, surfaceMergingObjs, bodyMergingObj) → {SimulationReturn}

Do the refraction calculation at the surface of the glass.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ray` | Ray | The ray to be refracted.
`rayIndex` | number | The index of the ray in the ray array.
`incidentPoint` | Point | The incident point.
`normal` | Point | The normal vector at the incident point.
`n1` | number | The effective refractive index of the current object (after determining the direction of incident of the current object, but before merging the surface with other objects).
`surfaceMergingObjs` | Array.<BaseSceneObj> | The objects that are to be merged with the current object.
`bodyMergingObj` | BaseGrinGlass | The object that is to be merged with the current object.

Inherited From:
  - BaseGlass#refract
Source:
  - sceneObjs/BaseGlass.js, line 141

##### Returns:

The return value for `onRayIncident`.

Type
  SimulationReturn

#### serialize() → {Object}

Serializes the object to a JSON object.

Inherited From:
  - BaseSceneObj#serialize
Source:
  - sceneObjs/BaseSceneObj.js, line 66

##### Returns:

The serialized JSON object.

Type
  Object

#### shiftOrigin(equation) → {string}

Shifts the x and y variables in `equation` from related to `this.origin` to the absolute coordinates.

##### Parameters:

Name | Type | Description
--- | --- | ---
`equation` | string |

Inherited From:
  - BaseGrinGlass#shiftOrigin
Source:
  - sceneObjs/BaseGrinGlass.js, line 163

##### Returns:

Type
  string

#### step(p1, p2, ray)

Receives two points inside this lens, and returns the next point to where the ray, connecting these two points, will travel, based on the ray trajectory equation (equation 11.1 in the cited text below) Using Euler's method to solve the ray trajectory equation (based on sections 11.1 and 11.2, in the following text: https://doi.org/10.1007/BFb0012092) x_der_s and x_der_s_prev are the x-coordinate derivatives with respect to the arc-length parameterization, at two different points (similarly for y_der_s and y_der_s_prev)

##### Parameters:

Name | Type | Description
--- | --- | ---
`p1` | Point |
`p2` | Point |
`ray` | Ray |

Inherited From:
  - BaseGrinGlass#step
Source:
  - sceneObjs/BaseGrinGlass.js, line 283