Click or drag to resize

Visualization with Cesium

Cesium is an open-source JavaScript library, founded by AGI in 2011. Cesium provides a cross-platform, browser-based virtual globe with a focus on precision and time-dynamic data. AGI has also created an enhanced commercial version of Cesium, STK Web Visualization Library, which is included with STK Components.

In STK Components, the Cesium Library provides the ability to generate CZML content from Platforms and other DefinitionalObjects, as well as analysis derived from them. CZML is a JSON-based data format designed by AGI to load static and time-dynamic data into Cesium.

This topic assumes basic familiarity with Cesium. Cesium documentation, tutorials, and code samples are available separately from the Cesium site.

Overview

The Cesium Library is built upon the same design patterns used throughout STK Components. It provides ObjectExtensions that describe how CZML properties are defined over time. These extensions are then added to individual Platforms and other ExtensibleObjects. Effectively, these extensions add CZML visualization information to your existing objects, after which they can be added to a CzmlDocument and serialized to CZML.

To understand how this works in practice, the following code sample demonstrates how to draw a label at the location of the International Space Station, and draw its orbit.

C#
var earth = CentralBodiesFacet.GetFromContext().Earth;
var issTle =
    new TwoLineElementSet(@"1 25544U 98067A   10172.34241898  .00007451  00000-0  60420-4 0  3627
                            2 25544  51.6459 209.3399 0009135 352.3227 186.5240 15.71934500664129");

var issPoint = new Sgp4Propagator(issTle).CreatePoint();
var iss = new Platform
{
    Name = "ISS",
    LocationPoint = issPoint,
    OrientationAxes = new AxesVehicleVelocityLocalHorizontal(earth.FixedFrame, issPoint),
};

var labelExtension = new LabelGraphicsExtension(new LabelGraphics
{
    Text = new ConstantCesiumProperty<string>(iss.Name),
    FillColor = new ConstantCesiumProperty<Color>(Color.White),
});
iss.Extensions.Add(labelExtension);

iss.Extensions.Add(new PathGraphicsExtension(new PathGraphics
{
    Material = new PolylineOutlineMaterialGraphics
    {
        Color = new ConstantCesiumProperty<Color>(Color.White),
        OutlineWidth = new ConstantCesiumProperty<double>(1.0),
        OutlineColor = new ConstantCesiumProperty<Color>(Color.Black),
    },
    Width = 2,
    LeadTime = Duration.FromMinutes(44).TotalSeconds,
    TrailTime = Duration.FromMinutes(44).TotalSeconds,
}));

var interval = new TimeInterval(new JulianDate(new GregorianDate(2009, 1, 1)),
                                new JulianDate(new GregorianDate(2009, 1, 2)));
var czmlDocument = new CzmlDocument
{
    Name = "SimpleExample",
    Description = "A simple example",
    PrettyFormatting = true,
    RequestedInterval = interval,
    Clock = new Clock
    {
        Interval = interval,
        CurrentTime = interval.Start,
    }
};
czmlDocument.ObjectsToWrite.Add(iss);

using (var streamWriter = new StreamWriter("Example.czml"))
{
    czmlDocument.WriteDocument(streamWriter);
}

First, we create a Platform to represent the ISS, with its location determined by a TLE. We then add a LabelGraphicsExtension and a PathGraphicsExtension. These extensions define various graphical properties that determine how the object will be displayed in Cesium. Then, to write the CZML, we create a CzmlDocument, provide a name and description for the document, configure the time interval over which we want to write data for, add the ISS platform to the list of objects to write, and then finally write the CZML file to disk. If you were to load this file into Cesium, you would see something like the below:

Example CZML in Cesium
Cesium Properties

In the code above, we configure the graphical properties using instances of ConstantCesiumProperty<T>. In CZML, almost every value can be defined to vary over time, so graphical properties, such as FillColor, are actually instances of the abstract base class CesiumProperty<T>. ConstantCesiumProperty<T> is merely the simplest implementation, for cases where a value is constant with respect to time.

CesiumProperty<T> is a means to define how a particular graphical property of an object in your Cesium scene changes over time. This allows you to associate the results of your analysis with the desired appearance of the display and is a fundamental concept in the Cesium Library.

The following additional types of CesiumProperty<T> are available:

As an example, suppose we wanted the text of the ISS label to be green before January 1st, 2009, and red any time after that. The following example shows how to accomplish this using a TimeIntervalCesiumProperty<Color>:

C#
var colorChangeTime = new JulianDate(new GregorianDate(2009, 1, 1));
var intervals = new TimeIntervalCollection<Color>
{
    new TimeInterval<Color>(JulianDate.MinValue, colorChangeTime, Color.Green),
    new TimeInterval<Color>(colorChangeTime, JulianDate.MaxValue, Color.Red),
};
labelExtension.LabelGraphics.FillColor = new TimeIntervalCesiumProperty<Color>(intervals);
Implicit Conversions

For convenience, CesiumProperty<T> also defines implicit conversion operators. The following conversions are defined:

These conversions make it easier to define properties, as shown in the below sample.

C#
labelExtension.LabelGraphics.Text = iss.Name;
labelExtension.LabelGraphics.FillColor = intervals;
CZML Identifiers

By default, the identifiers for each CZML object will be auto-generated, but if you need more control, you can add an IdentifierExtension to configure the identifier for that object.

C#
iss.Extensions.Add(new IdentifierExtension("ISS"));
Links

So far we have mainly been using color, but the same model applies to all other CZML properties. Suppose we wanted to visualize when the ISS had line of sight to a point on the ground, for example, AGI headquarters. In Components, we model this as an Access problem, using LinkInstantaneous and a CentralBodyObstructionConstraint.

C#
var facilityLocation = new Cartographic(-1.3191780323141054, 0.69871349190638687, 0.0);
var facilityPoint = new PointCartographic(earth, facilityLocation);
var facility = new Platform
{
    Name = "AGI HQ",
    LocationPoint = facilityPoint,
    OrientationAxes = new AxesEastNorthUp(earth, facilityPoint),
};

facility.Extensions.Add(new LabelGraphicsExtension(new LabelGraphics
{
    Text = facility.Name,
    FillColor = Color.White,
}));

var link = new LinkInstantaneous(facility, iss);
var constraint = new CentralBodyObstructionConstraint(link, earth);

We can then use these analysis types directly to visualize the results in Cesium. First, we create an LinkGraphicsExtension to describe the graphical properties of our link, which will be represented using a polyline in CZML. In our example, we make the link yellow by configuring the link's material. See the next section for more information on materials. Next, we want to only show the link when the constraint is satisfied. Since CentralBodyObstructionConstraint is an AccessQuery, we define the Show property as an AccessQueryCesiumProperty<bool>, indicating that the link graphics should be shown when access exists, and not otherwise. The following code sample shows this:

C#
link.Extensions.Add(new LinkGraphicsExtension(new LinkGraphics
{
    Show = new AccessQueryCesiumProperty<bool>
    {
        Query = constraint,
        AccessExists = true,
        AccessUnknown = false,
        NoAccess = false,
    },
    Material = new SolidColorMaterialGraphics(Color.Yellow),
}));
Materials

In the above examples, we configured both PathGraphics and LinkGraphics using materials. A material defines how the surface of many Cesium graphical types will be rendered. For example, Cesium (and therefore CZML) defines a PolylineOutline material which renders an outlined polyline. In Components, this corresponds to the PolylineOutlineMaterialGraphics type. Alternatively, we could use a SolidColorMaterialGraphics, or any other material instead. Each material defines its own set of specialized graphical properties. For example, the PolylineGlowMaterialGraphics provides Color and GlowPower properties.

In addition to polyline material types, which implement the IPolylineMaterialGraphics interface, there are also more general material types, which implement the IMaterialGraphics interface. These materials are used for shape and volume rendering, such as CentralBodySurfaceRegionGraphics and SensorFieldOfViewGraphics. In fact, sensor visualization allows different materials to be used for different parts of the sensor volume. For example, the following code sample adds a sensor to our facility representing AGI, pointing at the ISS as it passes overhead. We make the primary sensor volume green, but we use a white grid material to represent the sensor dome.

C#
var sensorOrientation =
    new AxesTargetingLink(link, LinkRole.Transmitter, new VectorFixed(iss.OrientationAxes, UnitCartesian.UnitZ));
var sensor = new Platform
{
    LocationPoint = facility.LocationPoint,
    OrientationAxes = sensorOrientation,
};

sensor.Extensions.Add(new FieldOfViewExtension(new RectangularPyramid
{
    XHalfAngle = Trig.DegreesToRadians(8),
    YHalfAngle = Trig.DegreesToRadians(4.5),
    Radius = 500000,
}));
sensor.Extensions.Add(new FieldOfViewGraphicsExtension(new SensorFieldOfViewGraphics
{
    DomeSurfaceMaterial = new GridMaterialGraphics
    {
        Color = Color.White,
        CellAlpha = 0.0,
    },
    LateralSurfaceMaterial = new SolidColorMaterialGraphics
    {
        Color = Color.FromArgb(128, Color.Green),
    }
}));

When loaded in Cesium, this looks like:

Example CZML with Sensor in Cesium
Code Sample

The Code Sample topic puts each of the pieces described above into one complete example.

Deleting Data

In advanced situations, you may need to delete data from a Cesium client via CZML documents processed into an existing client-side data source. This can also be necessary in order to replace data correctly, because processing data is an additive operation. As a result, by default, sampled properties have their samples merged with existing samples, which can produce incorrect visualization.

In order to delete data, objects must have stable identifiers. See the Identifiers section for more information on associating objects with identifiers.

There are several different mechanisms for deleting data:

The recommended approach to deleting an object is to use a placeholder ExtensibleObject, which has no extensions by default, then specify the identifier of the existing object, and add the extensions to delete the desired data, then add the placeholder object to the CzmlDocument.

Because CZML is generated for objects in order, you can then add a complete definition of the object using the same identifier. The generated CZML will contain a packet deleting the requested data, then a subsequent packet adding new data. Because Cesium processes packets in order, this will effectively replace the data.

Update Documents

The functionality described above is designed to produce a complete description of a set of objects to be visualized in Cesium. In most use cases, this conceptually simple way of transmitting information is sufficient, even in situations where objects may change their definition. A complete CzmlDocument can be written each time definitions change, and loaded into Cesium, replacing the previous document on the client. Since each document fully describes all objects, they are independent from any previous state.

In advanced situations with large amounts of data, producing complete documents can result in a large amount of CZML to be transmitted and processed. In these cases, update documents can be generated to send only data that has changed, which requires a more complex implementation but can significantly reduce the amount of data produced.

CzmlClientEntitySet represents the complete state of all entities for a specific Cesium client. Each client should have a separate instance associated with it, and the entity set should persist as long as the client is active.

Next, whenever the state of the objects change, create a complete CzmlDocument containing all objects, including all extensions, that should be visualized. Make sure that all objects have stable identifiers (see the Identifiers section) because identifiers will be used to correlate objects across updates.

Then, call Add to add the new complete document to the entity set. This method returns a CzmlUpdateDocument which contains the changes between the previous state and the new document. This update document can be then written to the client and processed (without clearing existing data).

This technique is most useful when building a web application that uses Cesium as the front-end, with STK Components providing server-side analysis, to provide a common operational picture. A Cesium-based client could refresh its data on a schedule, or the server could push updates to clients when they occur. An entity set would be maintained associated with each Cesium client, and the update documents would then be written directly to the web service response to be processed by the client.

The following code sample shows the intended sequence of operations to create update documents for a single client. The details of the CZML document are omitted here.

C#
// Create an entity set for a specific Cesium client.
CzmlClientEntitySet entitySet = new CzmlClientEntitySet();

// Create a complete document containing all entities and all extensions.
CzmlDocument czmlDocument = CreateDocument();

// Add the document to the entity set, producing a CzmlUpdateDocument.
CzmlUpdateDocument updateDocument = entitySet.Add(czmlDocument);

// Write the update document to a writer, such as a web service response.
updateDocument.WriteDocument(GetOutputWriter());

// Later...

// Create a new complete document containing all entities.
// Entities will be correlated by identifier.
czmlDocument = CreateDocument();

// Add the new complete document to the existing entity set.
// The update document will contain only the data that has changed
// since the previous document was added.
updateDocument = entitySet.Add(czmlDocument);

// Write the new update document as before.
updateDocument.WriteDocument(GetOutputWriter());
List of Services and Extensions

The table below provides a list of all services and related extensions involved in writing CZML. While most generated CZML is compatible with open-source Cesium, some features are only supported by STK Web Visualization Library. Loading a CZML file with STK Web Visualization Library features into open-source Cesium will simply cause the unsupported features to be ignored.

Service

Extension

Description

CZML Type

Availability

IAzimuthElevationMaskGraphicsService

AzimuthElevationMaskGraphicsExtension

Visualizes an AzimuthElevationMask at the object's position, oriented using the object's orientation. The geometry will be defined by the IAzimuthElevationMaskService service.

agi_fan

STK Web Visualization Library

IBillboardGraphicsService

BillboardGraphicsExtension

Visualizes a 2D marker at the object's position.

billboard

Cesium

ICentralBodySurfaceCurveGraphicsService

CentralBodySurfaceCurveGraphicsExtension

Visualizes a surface curve on an central body. The geometry of the curve will be defined by the ICentralBodySurfaceCurveService service.

polyline

Cesium

ICentralBodySurfaceRegionGraphicsService

CentralBodySurfaceRegionGraphicsExtension

Visualizes the outline, interior and boundary wall of a surface region on an central body. The geometry of the region will be defined by the ICentralBodySurfaceRegionService service.

polygon

Cesium

ICesiumAvailabilityService

CesiumAvailabilityExtension

Overrides the auto-detected availability of a CZML object with the specified interval.

availability

Cesium

ICesiumCustomPropertiesService

CesiumCustomPropertiesExtension

Defines custom time-varying CZML properties for use by client-side code.

properties

Cesium

ICesiumDeleteService

CesiumDeleteExtension

Indicates that a CZML object with the associated identifier should be deleted from the client.

delete

Cesium

ICesiumDirectionService

GraphicalVector

Customizes details about how an vector's direction will be written to CZML.

orientation

Cesium

ICesiumFixedStepService

CesiumFixedStepExtension

Customizes the step size to use when sampling properties for an object, instead of using the value specified for CzmlDocumentStep.

Cesium

ICesiumOrientationService

CesiumOrientationExtension

Customizes details about how an object's orientation will be written to CZML.

orientation

Cesium

ICesiumPositionService

CesiumPositionExtension

Customizes details about how an object's position will be written to CZML.

position

Cesium

ICesiumReferenceFrameService

CesiumReferenceFrameExtension

Allows a CZML object's position to be written in the inertial frame.

position

Cesium

IDescriptionService

DescriptionExtension

Specifies the HTML description of an object.

description

Cesium

IEllipsoidGraphicsService

EllipsoidGraphicsExtension

Visualizes a 3D ellipsoid at the object's position, oriented using the object's orientation.

ellipsoid

Cesium

IFieldOfViewGraphicsService

FieldOfViewGraphicsExtension

Defines graphical properties for sensor volumes and footprints projected onto a central body, at the object's position, oriented using the object's orientation. The geometry of the sensor volume will be defined by the IFieldOfViewService service.

agi_conicSensor, agi_customPatternSensor, agi_rectangularSensor

STK Web Visualization Library

IIdentifierService

IdentifierExtension

Specifies the identifier of the object, which must be unique. If not provided, a unique identifier will be generated automatically.

id

Cesium

ILabelGraphicsService

LabelGraphicsExtension

Visualizes text at the object's position.

label

Cesium

ILinkGraphicsService

LinkGraphicsExtension

Visualizes a polyline drawn connecting the two end points of a link. The geometry of the polyline will be defined by the ILinkService service.

polyline

Cesium

ILocationPointService

LocationPointExtension

Specifies the position for an object. Most graphical extensions require this information.

position

Cesium

IModelGraphicsService

ModelGraphicsExtension

Visualizes a 3D model in glTF format at the object's position, oriented using the object's orientation. See the glTF repository for more details on the glTF format.

model

Cesium

INameService

NameExtension

The name of the object, which does not have to be unique and is intended for user consumption.

name

Cesium

IOrientationAxesService

OrientationAxesExtension

Specifies the orientation of an object over time. Some 3D graphical extensions require this information.

orientation

Cesium

IParentService

ParentExtension

The parent object of the object.

parent

Cesium

IPathGraphicsService

PathGraphicsExtension

A path of an object as it moves over time.

path

Cesium

IPointGraphicsService

PointGraphicsExtension

Visualizes a 2D point at the object's position.

point

Cesium

IVectorGraphicsService

GraphicalVector

Defines the graphical properties of a 3D Vector, at the object's position. The geometry of the vector is defined by the IVectorService service.

agi_vector

STK Web Visualization Library

IViewFromService

ViewFromExtension

Specifies the suggested initial camera view offset when tracking an object.

viewFrom

Cesium