GroundElevationVolume

new IonSdkSensors.GroundElevationVolume(options)

Visualizes a volume whose inner and outer boundaries are defined by maximum GroundElevationVolume#maximumGroundElevationAngle and minimum GroundElevationVolume#minimumGroundElevationAngle ground elevation angles, respectively. The ground elevation angles are measured between the local horizontal at a point on the ellipsoid and a vector from that ellipsoid point to the origin, the apex of the volume, which is usually the position of the sensor or platform it is attached to. Because these angles are measured at the ground, the volume and footprint change with the origin's altitude, and no surface extends past the ellipsoid horizon. The volume shape is also defined by minimum GroundElevationVolume#minimumClockAngle and maximum GroundElevationVolume#maximumClockAngle clock angles and minimum GroundElevationVolume#minimumRadius and maximum GroundElevationVolume#maximumRadius radii.

Unlike sensor types such as ConicSensor, whose orientation is set freely, this volume always points at nadir and its heading is defined by the motion of its origin. For that reason it is referred to as a volume rather than a sensor.

The volume is positioned using GroundElevationVolume#modelMatrix, and its principal direction is along the positive z-axis, which always points at nadir regardless of the model matrix's rotation. The x-axis is the model matrix's x-axis projected onto the local horizontal plane. Clock angles are angles around the z-axis, rotating x into y.

Approximations and assumptions:

  • Nadir points opposite the geodetic surface normal at the surface point beneath the origin, not toward the ellipsoid center.
  • The volume is modeled as the region between two circular cones about nadir: an inner cone derived from the maximum ground elevation angle and an outer cone derived from the minimum.
  • Each cone half-angle is derived from a ground elevation angle with the law of sines: sin(halfAngle) = (Re / Rs) cos(elevationAngle), where halfAngle is measured from nadir, Re is the distance from the ellipsoid center to the surface point beneath the origin, and Rs is the distance from the ellipsoid center to the origin. This is exact for a spherical body, but on an ellipsoid the error in ground elevation angle at the footprint boundary grows toward the horizon, where the ground's distance from the ellipsoid center differs most from Re. The error also grows with the origin's altitude, since the footprint of a higher volume spans more of the ellipsoid.
  • Ground elevation angles are measured against the ellipsoid surface; terrain is ignored.

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
ellipsoid Ellipsoid Ellipsoid.WGS84 optional The ellipsoid that the volume potentially intersects.
show Boolean true optional Determines if the volume will be shown.
modelMatrix Matrix4 Matrix4.IDENTITY optional The 4x4 transformation matrix that positions the volume and sets its heading. See GroundElevationVolume#modelMatrix.
radius Number Number.POSITIVE_INFINITY optional The distance from the origin to any point on the dome. Equivalent to GroundElevationVolume#maximumRadius, which takes precedence over this property when both are provided.
maximumRadius Number Number.POSITIVE_INFINITY optional The distance from the origin to any point on the dome. Equivalent to GroundElevationVolume#radius and takes precedence over it when both are provided.
minimumRadius Number 0.0 optional The minimum distance from the origin to any point on the inner dome.
minimumGroundElevationAngle Number 0.0 optional The minimum ground elevation angle, in radians, defining the outer (near-limb) boundary of the volume.
maximumGroundElevationAngle Number CesiumMath.PI_OVER_TWO optional The maximum ground elevation angle, in radians, defining the inner (near-nadir) boundary of the volume.
minimumClockAngle Number 0.0 optional The minimum clock angle of the wedge.
maximumClockAngle Number CesiumMath.TWO_PI optional The maximum clock angle of the wedge.
lateralSurfaceMaterial Material Material.ColorType optional The surface appearance of the volume lateral surface, i.e., the outer sides of the volume.
showLateralSurfaces Boolean true optional Determines if the lateral surfaces, i.e., the outer sides of the volume, are shown.
ellipsoidSurfaceMaterial Material Material.ColorType optional The appearance of the ellipsoid surface where the volume intersects.
showEllipsoidSurfaces Boolean true optional Determines if the ellipsoid/volume intersection surfaces are shown.
domeSurfaceMaterial Material Material.ColorType optional The appearance of the dome surfaces. Affects both the minimum and maximum radius dome surfaces.
showDomeSurfaces Boolean true optional Determines if the dome surfaces are shown. Affects both the minimum and maximum radius dome surfaces.
showIntersection Boolean true optional Determines if a polyline is shown where the volume intersects the ellipsoid.
intersectionColor Color Color.WHITE optional The color of the polyline where the volume intersects the ellipsoid.
intersectionWidth Number 5.0 optional The approximate pixel width of the polyline where the volume intersects the ellipsoid.
showThroughEllipsoid Boolean false optional Determines if a volume intersecting the ellipsoid is drawn through the ellipsoid and potentially out to the other side.
environmentConstraint Boolean false optional Determines if the volume will be occluded by objects in the current view of the environment, e.g. visible terrain or models.
showEnvironmentOcclusion Boolean false optional Determines if the portion of the volume 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 volume and the environment is shown.
environmentIntersectionColor Color Color.WHITE optional The color of the line intersecting the volume and the environment.
environmentIntersectionWidth Number 5.0 optional The width of the line intersecting the volume and the environment in meters.
showViewshed Boolean false optional Determine if a viewshed is shown. The viewshed is only shown in 3D (see Scene#mode) and only accounts for visible objects in the current camera view.
viewshedVisibleColor Material Color.LIME optional The color of the scene geometry that is visible from the origin.
viewshedOccludedColor Material Color.RED optional The color of the scene geometry that is not visible from the origin.
viewshedResolution Number 2048 optional The resolution in pixels of the viewshed.
classificationType ClassificationType ClassificationType.BOTH optional Determines whether terrain, 3D Tiles or both will be classified.
id Object optional User-defined object returned when the volume is picked.
debugShowCrossingPoints Boolean false optional For debugging only. Determines if the points where the volume 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 surfaces of the volume 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.
Example:
// A ground elevation volume on a satellite, with the zero clock angle pointing north
const volume = scene.primitives.add(new IonSdkSensors.GroundElevationVolume({
  modelMatrix : Cesium.Transforms.northEastDownToFixedFrame(Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 700000.0)),
  minimumGroundElevationAngle : Cesium.Math.toRadians(10.0),
  maximumGroundElevationAngle : Cesium.Math.toRadians(70.0)
}));
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

See:

Members

static IonSdkSensors.GroundElevationVolume.ellipsoidSurfaceIn3DSupported
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 796

Determines if ellipsoid surface shading is supported in 3D mode.

static IonSdkSensors.GroundElevationVolume.viewshedSupported
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 805

Determines if viewshed shading is supported.

classificationType : ClassificationType
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 423

Determines whether terrain, 3D Tiles or both will be classified.
Default Value: ClassificationType.BOTH

debugShowBoundingVolume : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 471

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 volume.

Default Value: false

debugShowCrossingPoints : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 447

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

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

Default Value: false

debugShowProxyGeometry : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 459

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 surfaces of the volume boundary.

Default Value: false

debugShowShadowMap : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 483

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

domeSurfaceMaterial : Material
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 249

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

When undefined, GroundElevationVolume#lateralSurfaceMaterial is used.

Default Value: undefined
See:

readonly ellipsoid : Ellipsoid
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 536

Gets the ellipsoid that the volume potentially intersects.
Default Value: Ellipsoid.WGS84

ellipsoidSurfaceMaterial : Material
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 223

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

When undefined, GroundElevationVolume#lateralSurfaceMaterial is used.

Default Value: undefined
See:

environmentConstraint : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 315

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

environmentIntersectionColor : Color
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 353

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

environmentIntersectionWidth : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 363

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

environmentOcclusionMaterial : Material
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 332

The surface appearance of the portion of the volume occluded by the environment.
Default Value: Material.ColorType

id : Object
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 435

User-defined object returned when the volume is picked.
Default Value: undefined
See:

intersectionColor : Color
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 286

The color of the polyline where the volume intersects the ellipsoid.
Default Value: Color.WHITE
See:

intersectionWidth : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 298

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

lateralSurfaceMaterial : Material
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 194

The surface appearance of the lateral surfaces, i.e., the outer sides of the volume. This can be one of several built-in Material objects or a custom material, scripted with Fabric.
Default Value: Material.ColorType
See:

maximumClockAngle : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 183

The maximum clock angle of the wedge, in radians.
Default Value: CesiumMath.TWO_PI

maximumGroundElevationAngle : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 166

The maximum ground elevation angle, in radians, measured at a point on the ground from the local horizontal up to the direction to the origin. Defines the inner (near-nadir) boundary of the volume.
Default Value: CesiumMath.PI_OVER_TWO

maximumRadius : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 518

The distance from the origin to any point on the dome. Equivalent to GroundElevationVolume#radius and takes precedence over it when both are provided.
Default Value: Number.POSITIVE_INFINITY

minimumClockAngle : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 175

The minimum clock angle of the wedge, in radians.
Default Value: 0.0

minimumGroundElevationAngle : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 157

The minimum ground elevation angle, in radians, measured at a point on the ground from the local horizontal up to the direction to the origin. Defines the outer (near-limb) boundary of the volume.
Default Value: 0.0

minimumRadius : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 148

The minimum distance from the origin to any point on the inner dome.
Default Value: 0.0

modelMatrix : Matrix4
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 131

The 4x4 transformation matrix that positions the volume and sets its heading. The translation gives the origin's position, whose altitude above the ellipsoid determines the boundaries of the volume. The volume always points at nadir regardless of the rotation; the rotation's x-axis, projected onto the local horizontal plane, defines the zero clock angle.
Default Value: Matrix4.IDENTITY

radius : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 139

The distance from the origin to any point on the dome. Informally, this is the length of the volume. Equivalent to GroundElevationVolume#maximumRadius, which takes precedence over this property when both are provided.
Default Value: Number.POSITIVE_INFINITY

show : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 120

When true, the volume is shown.
Default Value: true

showDomeSurfaces : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 264

When true, the dome surfaces are shown.

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

Default Value: true
See:

showEllipsoidSurfaces : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 235

When true, the ellipsoid/volume intersection surfaces are shown.
Default Value: true
See:

showEnvironmentIntersection : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 344

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

showEnvironmentOcclusion : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 324

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

showIntersection : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 276

When true, a polyline is shown where the volume intersects the ellipsoid.
Default Value: true
See:

showLateralSurfaces : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 209

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

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

Default Value: true
See:

showThroughEllipsoid : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 307

When true, a volume intersecting the ellipsoid is drawn through the ellipsoid and potentially out to the other side.
Default Value: false

showViewshed : Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 380

Determine if a viewshed is shown. Viewsheds only take into account objects in the scene that are currently visible and are only show in 3D (see Scene#mode.)
Default Value: false
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

See:

viewshedOccludedColor : Color
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 402

The color of the scene geometry that is not visible from the origin.
Default Value: Color.RED
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

viewshedResolution : Number
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 414

The resolution in pixels of the viewshed.
Default Value: 2048
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

viewshedVisibleColor : Color
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 390

The color of the scene geometry that is visible from the origin.
Default Value: Color.LIME
Experimental

This feature is not final and is subject to change without Cesium's standard deprecation policy.

Methods

destroy() → undefined
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 834

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:
volume = volume && volume.destroy();

isDestroyed() → Boolean
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 815

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.

update()
packages/ion-sdk-sensors/Source/Scene/GroundElevationVolume.js 703

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:
  • DeveloperError : this.minimumGroundElevationAngle and this.maximumGroundElevationAngle must be between zero and 90 degrees, with the minimum less than or equal to the maximum.
  • DeveloperError : this.radius must be greater than or equal to zero.
  • DeveloperError : this.lateralSurfaceMaterial must be defined.
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
CtrlK
packages/ion-sdk-measurements
packages/ion-sdk-sensors
packages/ion-sdk-geometry
@cesium/core
@cesium/engine
@cesium/widgets