CesiumJS

[CesiumJS]Cesium Getting Started 9 - Loading and Styling Entities

Now that we have set up the Viewer configuration, imagery, and terrain for our application, we can add the main focus of our application – geocache data.

For visualization convenience, Cesium supports the popular vector formats GeoJSON and KML, as well as a format our team open-sourced called CZML, which we specifically developed for describing Cesium scenes.

Regardless of the initial format, all spatial data in Cesium is represented using the Entity API. The Entity API provides an efficient and flexible visualization method for Cesium rendering. A Cesium Entity is a data object that can be paired with styled graphical representations and positioned in space and time. Many simple Entity examples are provided in the test sandbox. To get up to speed on the Entity API, take a break from this application and read the Visualizing Spatial Data tutorial.

Here are some examples of different entity types:

Once you understand what an Entity looks like, loading datasets with Cesium becomes easy to understand. To read a data file, you need to create a DataSource appropriate for the data format, which will parse the data file hosted at the specified URL and create an EntityCollection containing an Entity for each geospatial object in the dataset. DataSource just defines an interface – the exact type of data source you need will depend on the data format. For example, KML uses KmlDataSource:

1
2
3
4
5
6
7
8

var kmlOptions = {
    camera : viewer.scene.camera,
    canvas : viewer.scene.canvas,
    clampToGround : true
};
// Load geocache points of interest from a KML file
// Data from : http://catalog.opendata.city/dataset/pediacities-nyc-neighborhoods/resource/91778048-3c58-449c-a3f9-365ed203e914
var geocachePromise = Cesium.KmlDataSource.load('./Source/SampleData/sampleGeocacheLocations.kml', kmlOptions);

The above code reads our sample geocache points from a KML file, calling KmlDataSource.load(options) with some configuration. For a KmlDataSource, the camera and canvas options are required. The clampToGround option enables ground clamping, a popular configuration for making ground geometry entities like polygons and ellipses conform to terrain rather than following the WGS84 ellipsoid surface.

Since this data is loaded asynchronously, KmlDataSource returns a Promise that will contain all our newly created entities.

If you’re not familiar with the Promise API for asynchronous functions, “asynchronous” here basically means you should do what you need with the data in the provided callback function using .then. To actually add this entity collection to the scene, we must wait until the promise is resolved, then add the KmlDataSource to viewer.dataSources:

1
2
3
4
5

// Add geocache billboard entities to scene and style them
geocachePromise.then(function(dataSource) {
    // Add the new data as entities to the viewer
    viewer.dataSources.add(dataSource);
});

By default, these newly created entities have useful features. Clicking will display an Infobox with metadata related to the entity, and double-clicking will zoom to and view the entity. To stop viewing that entity, click the “home” button, or click the “fly out” camera icon on the Infobox. Next, we’ll add custom styling to improve our application’s appearance.

For KML and CZML files, declarative styles can be established within the file. However, for this application, let’s practice manually styling our entities. To do this, we’ll take an approach similar to this styling example, waiting for our data source to load, then iterating through all entities in the data source collection, modifying and adding properties. By default, our geocache point markers are created as Billboards and Labels, so to modify the appearance of these entities, we do this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// Add geocache billboard entities to scene and style them
geocachePromise.then(function(dataSource) {
    // Add the new data as entities to the viewer
    viewer.dataSources.add(dataSource);

    // Get the array of entities
    var geocacheEntities = dataSource.entities.values;

    for (var i = 0; i < geocacheEntities.length; i++) {
        var entity = geocacheEntities[i];
        if (Cesium.defined(entity.billboard)) {
            // Entity styling code here
        }
    }
});

We can improve the appearance of the markers by adjusting their anchor points, removing labels to reduce clutter, and setting a distanceDisplayCondition so that only points within a certain distance from the camera are visible.

1
2
3
4
5
6
7
8
9

// Add geocache billboard entities to scene and style them
if (Cesium.defined(entity.billboard)) {
	// Adjust the vertical origin so pins sit on terrain
	entity.billboard.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;
	// Disable the labels to reduce clutter
	entity.label = undefined;
	// Add distance display condition
	entity.billboard.distanceDisplayCondition = new Cesium.DistanceDisplayCondition(10.0, 20000.0);
}

For more help on distanceDisplayCondition, see the sandcastle example.

Next, let’s improve the Infobox for each geocache entity. The Infobox title is the entity name, and the content is the entity description, displayed as HTML.

You’ll notice the default description isn’t very helpful. Since we’re displaying geocache locations, let’s update them to show the longitude and latitude of each point.

First, we convert the entity’s position to cartographic, then read the longitude and latitude from the Cartographic and add them to the description in an HTML table.

When clicked, our geocache entities will now display a well-formatted Infobox with just the data we need.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Add geocache billboard entities to scene and style them
if (Cesium.defined(entity.billboard)) {
	// Adjust the vertical origin so pins sit on terrain
	entity.billboard.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;
	// Disable the labels to reduce clutter
	entity.label = undefined;
	// Add distance display condition
	entity.billboard.distanceDisplayCondition = new Cesium.DistanceDisplayCondition(10.0, 20000.0);
	// Compute longitude and latitude in degrees
	var cartographicPosition = Cesium.Cartographic.fromCartesian(entity.position.getValue(Cesium.JulianDate.now()));
	var longitude = Cesium.Math.toDegrees(cartographicPosition.longitude);
	var latitude = Cesium.Math.toDegrees(cartographicPosition.latitude);
	// Modify description
	// Modify description
	var description = '<table class="cesium-infoBox-defaultTable cesium-infoBox-defaultTable-lighter"><tbody>' +
		'<tr><th>' + "Longitude" + '</th><td>' + longitude.toFixed(5) + '</td></tr>' +
		'<tr><th>' + "Latitude" + '</th><td>' + latitude.toFixed(5) + '</td></tr>' +
		'</tbody></table>';
	entity.description = description;
}

Our geocache markers should now look like this:

For our geo application, it would also be helpful to visualize the neighborhoods of specific points. Let’s try loading a GeoJSON file containing polygons for each New York neighborhood. Loading GeoJSON files is very similar to the loading process we just used for KML. But in this case, we use GeoJsonDataSource. Like the previous data source, we need to add it to viewer.dataSources to actually add the data to the scene.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

var geojsonOptions = {
    clampToGround : true
};
// Load neighborhood boundaries from KML file
var neighborhoodsPromise = Cesium.GeoJsonDataSource.load('./Source/SampleData/neighborhoods.geojson', geojsonOptions);

// Save an new entity collection of neighborhood data
var neighborhoods;
neighborhoodsPromise.then(function(dataSource) {
    // Add the new data as entities to the viewer
    viewer.dataSources.add(dataSource);
});

Let’s adjust the loaded neighborhood polygons. Just like the billboard styling we just did, we first iterate through the neighborhood data source entities after the data source loads, this time checking if each entity’s polygon is defined:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// Save an new entity collection of neighborhood data
var neighborhoods;
neighborhoodsPromise.then(function(dataSource) {
    // Add the new data as entities to the viewer
    viewer.dataSources.add(dataSource);
    neighborhoods = dataSource.entities;

    // Get the array of entities
    var neighborhoodEntities = dataSource.entities.values;
    for (var i = 0; i < neighborhoodEntities.length; i++) {
        var entity = neighborhoodEntities[i];

        if (Cesium.defined(entity.polygon)) {
            // entity styling code here
        }
    }
});

Since we’re displaying neighborhoods, let’s rename each entity to use the neighborhood as its name. The neighborhood from the original GeoJSON file is stored as a property. Cesium stores GeoJSON properties in entity.properties, so we can set the neighborhood name like this:

1
2
3
4

// entity styling code here

// Use geojson neighborhood value as entity name
entity.name = entity.properties.neighborhood;

Instead of making all neighborhoods the same color, we can assign each polygon a new color material with a random color using ColorMaterialProperty and Color.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// entity styling code here

// Set the polygon material to a random, translucent color.
entity.polygon.material = Cesium.Color.fromRandom({
    red : 0.1,
    maximumGreen : 0.5,
    minimumBlue : 0.5,
    alpha : 0.6
});

// Tells the polygon to color the terrain. ClassificationType.CESIUM_3D_TILE will color the 3D tileset, and ClassificationType.BOTH will color both the 3d tiles and terrain (BOTH is the default)
entity.polygon.classificationType = Cesium.ClassificationType.TERRAIN;

Finally, let’s generate a Label with some basic styling options for each entity. To keep things clean, we can use disableDepthTestDistance to make Cesium always render the labels above any 3D objects that might occlude them.

However, note that labels are always positioned at entity.position. A Polygon is created with an undefined position because it has a list of positions defining the polygon boundary. We can generate a position by taking the center of the polygon positions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// entity styling code here

// Generate Polygon position
var polyPositions = entity.polygon.hierarchy.getValue(Cesium.JulianDate.now()).positions;
var polyCenter = Cesium.BoundingSphere.fromPoints(polyPositions).center;
polyCenter = Cesium.Ellipsoid.WGS84.scaleToGeodeticSurface(polyCenter);
entity.position = polyCenter;
// Generate labels
entity.label = {
    text : entity.name,
    showBackground : true,
    scale : 0.6,
    horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
    verticalOrigin : Cesium.VerticalOrigin.BOTTOM,
    distanceDisplayCondition : new Cesium.DistanceDisplayCondition(10.0, 8000.0),
    disableDepthTestDistance : 100.0
};

This gives us labeled polygons that look like this:

Finally, let’s add a high-tech perspective to our NYC geocaches by adding a drone flight over the city.

Since the flight path is just a series of positions over time, we can add this data from a CZML file. CZML is a format for describing time-dynamic graphical scenes, primarily for display in web browsers running Cesium. It describes lines, points, billboards, models, and other graphical primitives, and specifies how they change over time. CZML is to Cesium what KML is to Google Earth – a standard format that allows most Cesium features to be used through a declarative styling language (in this case, a JSON schema).

Our CZML file defines an entity (visualized as a point by default) whose position is defined as a series of positions at different time points. There are several property types available in the Entity API for handling time-dynamic data. See the demo example below:

1
2
3
4
5
6

// Load a drone flight path from a CZML file
var dronePromise = Cesium.CzmlDataSource.load('./Source/SampleData/SampleFlight.czml');

dronePromise.then(function(dataSource) {
    viewer.dataSources.add(dataSource);
});

The CZML file uses Cesium to display a drone flight. The path is a property that shows the entity’s position over time. A path visualizes discrete points connected into a continuous line using interpolation. Finally, let’s improve the appearance of the drone flight. First, instead of simply displaying a point, we can load a 3D model to represent our drone and attach it to the entity.

Cesium supports loading 3D models based on glTF (GL Transmission Format), an open specification developed by the Cesium team together with the Khronos Group, designed to efficiently load 3D models for applications by minimizing file size and runtime processing. Don’t have a glTF model? We provide an online converter to convert COLLADA and OBJ files to glTF format.

Let’s load a drone Model with nice physically-based shading and some animations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var drone;
dronePromise.then(function(dataSource) {
    viewer.dataSources.add(dataSource);
    // Get the entity using the id defined in the CZML data
    drone = dataSource.entities.getById('Aircraft/Aircraft1');
    // Attach a 3D model
    drone.model = {
        uri : './Source/SampleData/Models/CesiumDrone.gltf',
        minimumPixelSize : 128,
        maximumScale : 1000,
        silhouetteColor : Cesium.Color.WHITE,
        silhouetteSize : 2
    };
});

Now our model looks good, but unlike the original point, the drone model has a direction, and it looks strange when the drone moves forward without orientation. Fortunately, Cesium provides a VelocityOrientationProperty, which automatically calculates orientation based on positions sampled before and after the entity:

1
2

// Add computed orientation based on sampled positions
drone.orientation = new Cesium.VelocityOrientationProperty(drone.position);

Now our drone model will behave as expected.

One more thing we can do to improve the appearance of our drone flight: from a distance, it may not be obvious, but the drone’s path is made up of line segments that look unnatural. This is because Cesium uses linear interpolation by default to construct the path from sampled points. However, interpolation options can be configured.

For a smoother flight path, we can change the interpolation options like this:

1
2
3
4
5

// Smooth path interpolation
drone.position.setInterpolationOptions({
    interpolationDegree : 3,
    interpolationAlgorithm : Cesium.HermitePolynomialApproximation
});

Cesium Chinese Community QQ Group: 807482793

Original link: http://cesiumcn.org/topic/161.html | China fast access: http://cesium.coinidea.com/topic/161.html