CustomPatternSensor

new Cesium.CustomPatternSensor(options)

Visualizes a custom sensor volume taking into account occlusion of an ellipsoid, i.e., the globe, or the environment, i.e., terrain and models. The sensor's shape is defined by CustomPatternSensor#directions, which is an array of clock and cone angles, and a radius (CustomPatternSensor#radius). The sensor's principal direction is along the positive z-axis. Clock angles are angles around the z-axis, rotating x into y. Cone angles are angles from the z-axis towards the xy plane.

Directions must conform to the following restrictions:

  • Duplicate vertices are not allowed.
  • Consecutive vertices should be less than 180 degrees apart.

The shape also depends on if the sensor intersects the ellipsoid, as shown in examples 3 and 4 below, and what surfaces are shown using properties such as CustomPatternSensor#showDomeSurfaces.
Code Example 1 below
Code Example 2 below
Code Example 3 below
Code Example 4 below

A sensor points along the local positive z-axis and is positioned and oriented using CustomPatternSensor#modelMatrix.


Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
ellipsoid Ellipsoid Ellipsoid.WGS84 optional The ellipsoid that the sensor potentially intersects.
show Boolean true optional Determines if the sensor will be shown.
portionToDisplay SensorVolumePortionToDisplay SensorVolumePortionToDisplay.COMPLETE optional Indicates what portion of the sensor is shown.
modelMatrix Matrix4 Matrix4.IDENTITY optional The 4x4 transformation matrix that transforms the sensor from model to world coordinates.
radius Number Number.POSITIVE_INFINITY optional The distance from the sensor origin to any point on the sensor dome.
directions Number optional An array of objects with clock and cone angles, in radians, defining the sensor volume.
lateralSurfaceMaterial Material Material.ColorType optional The surface appearance of the sensor lateral surface, i.e., the outer sides of the sensor.
showLateralSurfaces Boolean true optional Determines if the lateral surfaces, i.e., the outer sides of the sensor, are shown.
ellipsoidHorizonSurfaceMaterial Material Material.ColorType optional The surface appearance of the ellipsoid horizon surfaces, i.e., the sides formed from occlusion due to the ellipsoid hoirzon.
showEllipsoidHorizonSurfaces Boolean true optional Determines if the ellipsoid horizon surfaces, i.e., the sides formed from occlusion due to the ellipsoid hoirzon, are shown.
ellipsoidSurfaceMaterial Material Material.ColorType optional The appearance of the ellipsoid surface where the sensor intersects.
showEllipsoidSurfaces Boolean true optional Determines if the ellipsoid/sensor intersection surfaces are shown.
domeSurfaceMaterial Material Material.ColorType optional The appearance of the sensor dome surfaces.
showDomeSurfaces Boolean true optional Determines if the sensor dome surfaces are shown.
showIntersection Boolean true optional Determines if a polyline is shown where the sensor intersections the ellipsoid.
intersectionColor Color Color.WHITE optional The color of the polyline where the sensor intersects the ellipsoid.
intersectionWidth Number 5.0 optional The approximate pixel width of the polyline where the sensor intersects the ellipsoid.
showThroughEllipsoid Boolean false optional Determines if a sensor intersecting the ellipsoid is drawn through the ellipsoid and potentially out to the other side.
environmentConstraint Boolean false optional Determines if the sensor will be occluded by the environment, e.g. terrain or models.
showEnvironmentOcclusion Boolean false optional Determines if the portion of the sensor occluded by the environment is shown.
environmentOcclusionMaterial Material Material.ColorType optional The appearance of the surface that is occluded by the environment.
showEnvironmentIntersection Boolean false optional Determines if the line intersecting the sensor and the environment is shown.
environmentIntersectionColor Color Color.WHITE optional The color of the line intersecting the sensor and the environment.
environmentIntersectionWidth Number 5.0 optional The width of the line intersecting the sensor and the environment in meters.
id Object optional User-defined object returned when the sensors is picked.
debugShowCrossingPoints Boolean false optional For debugging only. Determines if the points where the sensor boundary crosses off of and onto the ellipsoid are shown.
debugShowProxyGeometry Boolean false optional For debugging only. Determines if the proxy geometry used for shading the dome and ellipsoid horizon surfaces of the sensor boundary are shown.
debugShowBoundingVolume Boolean false optional For debugging only. Determines if this primitive's commands' bounding spheres are shown.
debugShowShadowMap Boolean false optional For debugging only. Determines if this primitive's shadow map's bounding volume and contents are shown.
Examples:
// Example 1. Sensor on the ground pointing straight up
var sensor = scene.primitives.add(new Cesium.CustomPatternSensor({
  modelMatrix : Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706)),
  radius : 1000000.0,
  directions : [{
    clock : Cesium.Math.toRadians(0.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(90.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(180.0),
    cone : Cesium.Math.toRadians(30.0)
  }]
}));
// Example 2. Star-pattern sensor pointing straight down with its lateral surface intersecting the ellipsoid.
var sensor = scene.primitives.add(new Cesium.CustomPatternSensor({
  modelMatrix : Cesium.Transforms.northEastDownToFixedFrame(Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 700000.0)),
  radius : 1000000.0,
  directions : [{
    clock : Cesium.Math.toRadians(0.0),
    cone : Cesium.Math.toRadians(40.0)
  }, {
    clock : Cesium.Math.toRadians(45.0),
    cone : Cesium.Math.toRadians(20.0)
  }, {
    clock : Cesium.Math.toRadians(90.0),
    cone : Cesium.Math.toRadians(40.0)
  }, {
    clock : Cesium.Math.toRadians(135.0),
    cone : Cesium.Math.toRadians(20.0)
  }, {
    clock : Cesium.Math.toRadians(180.0),
    cone : Cesium.Math.toRadians(40.0)
  }, {
    clock : Cesium.Math.toRadians(225.0),
    cone : Cesium.Math.toRadians(20.0)
  }, {
    clock : Cesium.Math.toRadians(270.0),
    cone : Cesium.Math.toRadians(40.0)
  }, {
    clock : Cesium.Math.toRadians(315.0),
    cone : Cesium.Math.toRadians(20.0)
  }],
}));
// Example 3. Sensor pointing straight down with its dome intersecting the ellipsoid
var sensor = scene.primitives.add(new Cesium.CustomPatternSensor({
  modelMatrix : Cesium.Transforms.northEastDownToFixedFrame(Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 900000.0)),
  radius : 1000000.0,
  directions : [{
    clock : Cesium.Math.toRadians(270.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(0.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(90.0),
    cone : Cesium.Math.toRadians(30.0)
  }],
  lateralSurfaceMaterial : Cesium.Material.fromType(Cesium.Material.StripeType),
  intersectionColor :  Cesium.Color.YELLOW
}));
// Example 4. Sensor with custom materials for each surface.  Switch to 2D to see the ellipsoid surface material.
var sensor = scene.primitives.add(new Cesium.CustomPatternSensor({
  modelMatrix : Cesium.Transforms.northEastDownToFixedFrame(Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 9000000.0)),
  radius : 20000000.0,
  directions : [{
    clock : Cesium.Math.toRadians(270.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(0.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(90.0),
    cone : Cesium.Math.toRadians(30.0)
  }],
  lateralSurfaceMaterial : Cesium.Material.fromType(Cesium.Material.ColorType, { color : new Cesium.Color(1.0, 0.0, 0.0, 0.5) }),
  ellipsoidHorizonSurfaceMaterial : Cesium.Material.fromType(Cesium.Material.ColorType, { color : new Cesium.Color(0.0, 1.0, 0.0, 0.5) }),
  ellipsoidSurfaceMaterial : Cesium.Material.fromType(Cesium.Material.ColorType, { color : new Cesium.Color(0.0, 0.0, 1.0, 0.5) }),
  domeSurfaceMaterial : Cesium.Material.fromType(Cesium.Material.ColorType, { color : new Cesium.Color(1.0, 1.0, 1.0, 0.5) })
}));
See:

Members

debugShowBoundingVolume : Boolean

This property is for debugging only; it is not for production use nor is it optimized.

When true, draws the bounding sphere for each DrawCommand in the sensor.

Default Value: false

debugShowCrossingPoints : Boolean

This property is for debugging only; it is not for production use nor is it optimized.

When true, draws the points where the sensor boundary crosses off of and onto the ellipsoid.

Default Value: false

debugShowProxyGeometry : Boolean

This property is for debugging only; it is not for production use nor is it optimized.

When true, draws the proxy geometry used for shading the dome and ellipsoid horizon surfaces of the sensor boundary.

Default Value: false

debugShowShadowMap : Boolean

This property is for debugging only; it is not for production use nor is it optimized.

When true, draws a bounding volume around the light source for the shadow map used for environment intersections. Also, the contents of the shadow map are drawn to a viewport quad.

Default Value: false

directions : Object

Gets or sets the directions which define the sensor volume. As shown in the example, each direction is defined by a clock and cone angle in radians. The resulting volume may be convex or concave.

The sensor's principal direction is along the positive z-axis. Clock angles are angles around the z-axis, rotating x into y. Cone angles are angles from the z-axis towards the xy plane.

Directions must conform to the following restrictions:

  • Duplicate vertices are not allowed.
  • Consecutive vertices should be less than 180 degrees apart.

Example:
// Create a triangular sensor projection
sensor.directions = [{
    clock : Cesium.Math.toRadians(0.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(90.0),
    cone : Cesium.Math.toRadians(30.0)
  }, {
    clock : Cesium.Math.toRadians(180.0),
    cone : Cesium.Math.toRadians(30.0)
}]
The surface appearance of the sensor dome. This can be one of several built-in Material objects or a custom material, scripted with Fabric.

When undefined, CustomPatternSensor#lateralSurfaceMaterial is used.

Default Value: undefined
Examples:
// Change the color of the dome surface material to yellow
sensor.domeSurfaceMaterial.uniforms.color = Cesium.Color.YELLOW;
// Change material to horizontal stripes
sensor.domeSurfaceMaterial = Material.fromType(Material.StripeType);
See:
Gets the ellipsoid that the sensor potentially intersects.
Default Value: Ellipsoid.WGS84

ellipsoidHorizonSurfaceMaterial : Material

The surface appearance of the ellipsoid horizon surfaces, i.e., the sides formed from occlusion due to the ellipsoid hoirzon. This can be one of several built-in Material objects or a custom material, scripted with Fabric.

When undefined, CustomPatternSensor#lateralSurfaceMaterial is used.

Default Value: undefined
Examples:
// Change the color of the ellipsoid horizon surface material to yellow
sensor.ellipsoidHorizonSurfaceMaterial.uniforms.color = Cesium.Color.YELLOW;
// Change material to horizontal stripes
sensor.ellipsoidHorizonSurfaceMaterial = Cesium.Material.fromType(Cesium.Material.StripeType);
See:

ellipsoidSurfaceMaterial : Material

The appearance of the ellipsoid surface where the sensor intersects. This can be one of several built-in Material objects or a custom material, scripted with Fabric.

When undefined, CustomPatternSensor#lateralSurfaceMaterial is used.

Default Value: undefined
Examples:
// Change the color of the ellipsoid surface material to yellow
sensor.ellipsoidSurfaceMaterial.uniforms.color = new Cesium.Color.YELLOW;
// Change material to horizontal stripes
sensor.ellipsoidSurfaceMaterial = Material.fromType(Material.StripeType);
See:

environmentConstraint : Boolean

When true, a sensor intersecting the environment, e.g. terrain or models, will discard the portion of the sensor that is occluded.
Default Value: false

environmentIntersectionColor : Color

The color of the line intersecting the environment.
Default Value: Color.WHITE

environmentIntersectionWidth : Number

The approximate width in meters of the line intersecting the environment.
Default Value: 5.0

environmentOcclusionMaterial : Material

The surface appearance of the portion of the sensor occluded by the environment.
Default Value: Material.ColorType
User-defined object returned when the sensors is picked.
Default Value: undefined
See:
The color of the polyline where the sensor intersects the ellipsoid.
Default Value: Color.WHITE
See:

intersectionWidth : Number

The approximate pixel width of the polyline where the sensor intersects the ellipsoid.
Default Value: 5.0
See:

lateralSurfaceMaterial : Material

The surface appearance of the lateral surfaces, i.e., the outer sides of the sensor. This can be one of several built-in Material objects or a custom material, scripted with Fabric.
Default Value: Material.ColorType
Examples:
// Change the color of the default material to yellow
sensor.lateralSurfaceMaterial.uniforms.color = Cesium.Color.YELLOW;
// Change material to horizontal stripes
sensor.lateralSurfaceMaterial = Cesium.Material.fromType(Cesium.Material.StripeType);
See:
The 4x4 transformation matrix that transforms the sensor from model to world coordinates. In its model coordinates, the sensor's principal direction is along the positive z-axis. Clock angles are angles around the z-axis, rotating x into y. Cone angles are angles from the z-axis towards the xy plane.


Default Value: Matrix4.IDENTITY
Example:
// The sensor's origin is located on the surface at -75.59777 degrees longitude and 40.03883 degrees latitude.
// The sensor opens upward, along the surface normal.
var center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
sensor.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
Indicates what portion of the sensor is shown.
COMPLETE
BELOW_ELLIPSOID_HORIZON
ABOVE_ELLIPSOID_HORIZON
Default Value: SensorVolumePortionToDisplay.COMPLETE
The distance from the sensor origin to any point on the sensor dome. Informally, this is the length of the sensor.
Default Value: Number.POSITIVE_INFINITY
When true, the sensor is shown.
Default Value: true

showDomeSurfaces : Boolean

When true, the sensor dome surfaces are shown.

These surfaces are only shown in 3D (see Scene#mode).

Full sensor
Dome only
Default Value: true
See:

showEllipsoidHorizonSurfaces : Boolean

When true, the ellipsoid horizon surfaces, i.e., the sides formed from occlusion due to the ellipsoid hoirzon, are shown.

These surfaces are only shown in 3D (see Scene#mode).

Full sensor
Ellipsoid horizon surfaces only
Default Value: true
See:

showEllipsoidSurfaces : Boolean

When true, the ellipsoid/sensor intersection surfaces are shown.

These surfaces are only shown in 2D and Columbus View (see Scene#mode).

Default Value: true
See:

showEnvironmentIntersection : Boolean

When true, a line is shown where the sensor intersections the environment, e.g. terrain or models.
Default Value: false

showEnvironmentOcclusion : Boolean

When true, the portion of the sensor occluded by the environment will be drawn with CustomPatternSensor#environmentOcclusionMaterial. CustomPatternSensor#environmentConstraint must also be true.
Default Value: false

showIntersection : Boolean

When true, a polyline is shown where the sensor intersections the ellipsoid.
showIntersection : false
showIntersection : true
Default Value: true
See:

showLateralSurfaces : Boolean

When true, the sensor's lateral surfaces, i.e., the outer sides of the sensor, are shown.

These surfaces are only shown in 3D (see Scene#mode).

Full sensor
Lateral surfaces only
Default Value: true
See:

showThroughEllipsoid : Boolean

When true, a sensor intersecting the ellipsoid is drawn through the ellipsoid and potentially out to the other side.

showThroughEllipsoid : false
showThroughEllipsoid : true
Default Value: false

Methods

destroy()undefined

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object.

Once an object is destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception. Therefore, assign the return value (undefined) to the object as done in the example.
Returns:
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
sensor = sensor && sensor.destroy();

isDestroyed()Boolean

Returns true if this object was destroyed; otherwise, false.

If this object was destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception.
Returns:
true if this object was destroyed; otherwise, false.
Called when Viewer or CesiumWidget render the scene to get the draw commands needed to render this primitive.

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

Throws: