Cesium Chinese Website: http://cesiumcn.org/ | China Fast Access: http://cesium.coinidea.com/

Entity Features in Viewer

Let’s look at the functions that Viewer provides for manipulating entities.

Selection and Description

Clicking an entity in the Viewer will display a SelectionIndicator widget at the entity’s location, providing an InfoBox for presenting more information. We can set name to define the title of the InfoBox. We can also provide the Entity.description property in HTML format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

wyoming.name = 'wyoming';
wyoming.description = '\
<img\
  width="50%"\
  style="float:left; margin: 0 1em 1em 0;"\
  src="//cesium.com/docs/tutorials/creating-entities/Flag_of_Wyoming.svg"/>\
<p>\
  Wyoming is a state in the mountain region of the Western \
  United States.\
</p>\
<p>\
  Wyoming is the 10th most extensive, but the least populous \
  and the second least densely populated of the 50 United \
  States. The western two thirds of the state is covered mostly \
  with the mountain ranges and rangelands in the foothills of \
  the eastern Rocky Mountains, while the eastern third of the \
  state is high elevation prairie known as the High Plains. \
  Cheyenne is the capital and the most populous city in Wyoming, \
  with a population estimate of 63,624 in 2017.\
</p>\
<p>\
  Source: \
  <a style="color: WHITE"\
    target="_blank"\
    href="http://en.wikipedia.org/wiki/Wyoming">Wikipedia</a>\
</p>';

All HTML displayed in the InfoBox is sandboxed. This prevents external data sources from injecting malicious content into the Cesium application. To run JavaScript or browser plugins within the description, access the sandboxed iframe via the viewer.infoBox.frame property. Refer to this article for more information on controlling iframe sandboxing.

Camera Controls

Use the viewer.zoomTo command to view a specific Entity. There is also a viewer.flyTo method for performing animated Camera flights to an Entity. Both methods can be passed an Entity, EntityCollection, DataSource, or an array of entities.

Either method will calculate the view for all provided entities. By default, the Camera faces north and looks down at a 45-degree angle. Customize this by passing in a HeadingPitchRange.

1
2
3

var heading = Cesium.Math.toRadians(90);
var pitch = Cesium.Math.toRadians(-30);
viewer.zoomTo(wyoming, new Cesium.HeadingPitchRange(heading, pitch));

zoomTo and flyTo are both asynchronous functions; that is, they are not guaranteed to complete before returning. For example, flying to an Entity happens over many animation frames. Both functions return Promises that can be used to schedule actions to perform after the flight or zoom completes. Replace zoomTo in the example with the following code snippet. This flies to Wyoming and selects it after the flight ends.

1
2
3
4
5

viewer.flyTo(wyoming).then(function(result){
    if (result) {
        viewer.selectedEntity = wyoming;
    }
});

The result parameter passed to the callback function will be true if the flight completed successfully; false if the flight was cancelled – that is, the user initiated another flight or zoom before this one completed; or if the target had no corresponding visualization, i.e., nothing to zoom to.

Sometimes, especially when working with time-dynamic data, we want the Camera to focus on and follow an entity rather than the center of the Earth. This can be accomplished by setting viewer.trackedEntity. Tracking an entity requires setting a position.

1
2

wyoming.position = Cesium.Cartesian3.fromDegrees(-107.724, 42.68);
viewer.trackedEntity = wyoming;

To stop tracking, set viewer.trackedEntity to undefined or double-click away from the entity. Calling zoomTo or flyTo will also cancel tracking.

Managing Entities

EntityCollection is an associative array for managing and monitoring a group of entities. viewer.entities is an EntityCollection. EntityCollection includes methods for managing entities such as add, remove, and removeAll.

Sometimes we need to update entities we previously created. All entity instances have a unique id that can be used to retrieve entities from the collection. We can assign an ID to an entity, otherwise one will be automatically generated.

1
2
3

viewer.entities.add({
    id : 'uniqueId'
});

Use getById to retrieve an entity. If no entity with the provided ID exists, undefined is returned.

1

var entity = viewer.entities.getById('uniqueId');

To get an entity or create a new one if it doesn’t exist, use getOrCreateEntity.

1

var entity = viewer.entities.getOrCreateEntity('uniqueId');

Manually create a new entity and use add to add it to the collection. This method will throw an exception if an entity with the same id already exists in the collection.

1
2
3
4

var entity = new Entity({
    id: 'uniqueId'
});
viewer.entities.add(entity);

EntityCollection emits events using the CollectionChanged event. Listeners are notified when entities are added, removed, or updated in the collection.

Use the [Geometry Showcase] (https://cesiumjs.org/Cesium/Build/Apps/Sandcastle/index.html?src=Geometry and Appearances.html&label=Showcases) example in Sandcastle. Paste the following code after the line that creates the viewer.

1
2
3
4
5
6
7
8

function onChanged(collection, added, removed, changed){
  var msg = 'Added ids';
  for(var i = 0; i < added.length; i++) {
    msg += '\n' + added[i].id;
  }
  console.log(msg);
}
viewer.entities.collectionChanged.addEventListener(onChanged);

When running the example, you should see about 65 messages in the console, one for each call to viewer.entities.add.

When updating a large number of entities at once, it is more performant to queue the updates and send a single event at the end. This allows Cesium to process the required changes in a single pass. At the end of the example, call viewer.entities.suspendEvents before viewer.entities.add, and call viewer.entities.resumeEvents after. When running the demo again, we now get a single event containing all 65 entities. These calls are reference-counted, so multiple suspend and resume calls can be nested.

Picking

Picking (clicking to select an object) is an area where we need brief interaction with the base API. Use scene.pick and scene.drillPick to retrieve entities.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

/**
 * Returns the top-most entity at the provided window coordinates
 * or undefined if no entity is at that location.
 *
 * @param {Cartesian2} windowPosition The window coordinates.
 * @returns {Entity} The picked entity or undefined.
 */
function pickEntity(viewer, windowPosition) {
  var picked = viewer.scene.pick(windowPosition);
  if (defined(picked)) {
    var id = Cesium.defaultValue(picked.id, picked.primitive.id);
    if (id instanceof Cesium.Entity) {
      return id;
    }
  }
  return undefined;
};

/**
 * Returns the list of entities at the provided window coordinates.
 * The entities are sorted front to back by their visual order.
 *
 * @param {Cartesian2} windowPosition The window coordinates.
 * @returns {Entity[]} The picked entities or undefined.
 */
function drillPickEntities(viewer, windowPosition) {
  var i;
  var entity;
  var picked;
  var pickedPrimitives = viewer.scene.drillPick(windowPosition);
  var length = pickedPrimitives.length;
  var result = [];
  var hash = {};

  for (i = 0; i < length; i++) {
    picked = pickedPrimitives[i];
    entity = Cesium.defaultValue(picked.id, picked.primitive.id);
    if (entity instanceof Cesium.Entity && !Cesium.defined(hash[entity.id])) {
      result.push(entity);
      hash[entity.id] = true;
    }
  }
  return result;
};

Points, Billboards, and Labels

Create graphical points or labels by setting position, point, and label. For example, place a point at our favorite sports team’s home stadium.

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

var viewer = new Cesium.Viewer('cesiumContainer');

var citizensBankPark = viewer.entities.add({
    name : 'Citizens Bank Park',
    position : Cesium.Cartesian3.fromDegrees(-75.166493, 39.9060534),
    point : {
        pixelSize : 5,
        color : Cesium.Color.RED,
        outlineColor : Cesium.Color.WHITE,
        outlineWidth : 2
    },
    label : {
        text : 'Citizens Bank Park',
        font : '14pt monospace',
        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
        outlineWidth : 2,
        verticalOrigin : Cesium.VerticalOrigin.BOTTOM,
        pixelOffset : new Cesium.Cartesian2(0, -9)
    }
});

viewer.zoomTo(viewer.entities);

By default, labels are horizontally and vertically centered. Since the label and point share the same position, they overlap on screen. To avoid this, specify the label origin as VerticalOrigin.BOTTOM and set the pixel offset to (0, -9). Replace the point with a billboard, which is a marker that always faces the user.

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

var citizensBankPark = viewer.entities.add({
  position : Cesium.Cartesian3.fromDegrees(-75.166493, 39.9060534),
  billboard : {
    image : '//cesiumjs.org/tutorials/Visualizing-Spatial-Data/images/Philadelphia_Phillies.png',
    width : 64,
    height : 64
  },
  label : {
    text : 'Citizens Bank Park',
    font : '14pt monospace',
    style: Cesium.LabelStyle.FILL_AND_OUTLINE,
    outlineWidth : 2,
    verticalOrigin : Cesium.VerticalOrigin.TOP,
    pixelOffset : new Cesium.Cartesian2(0, 32)
  }
});

For more customization options, see the Sandcastle Labels and Billboards examples.

3D Models

CesiumJS supports creating 3D models via glTF (runtime asset format). You can find example models in the 3D models Sandcastle.

Set a position and URI to a glTF model to create a model entity.

1
2
3
4
5
6
7
8

var viewer = new Cesium.Viewer('cesiumContainer');
var entity = viewer.entities.add({
    position : Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706),
    model : {
        uri : '../../../../Apps/SampleData/models/GroundVehicle/GroundVehicle.glb'
    }
});
viewer.trackedEntity = entity;

By default, the model is upright and faces east. Control the model’s orientation by specifying a Quaternion for the Entity.orientation property. This controls the model’s heading, pitch, and roll.

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

var viewer = new Cesium.Viewer('cesiumContainer');
var position = Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706);
var heading = Cesium.Math.toRadians(45.0);
var pitch = Cesium.Math.toRadians(15.0);
var roll = Cesium.Math.toRadians(0.0);
var orientation = Cesium.Transforms.headingPitchRollQuaternion(position, new Cesium.HeadingPitchRoll(heading, pitch, roll));

var entity = viewer.entities.add({
    position : position,
    orientation : orientation,
    model : {
        uri : '../../../../Apps/SampleData/models/GroundVehicle/GroundVehicle.glb'
    }
});
viewer.trackedEntity = entity;

For more advanced model features, see the 3D Models tutorial. If you create your own models, be sure to check our post on glTF Tips for Artists.

The Property System

All values we define for entities are stored as property objects. For example, see the value of Wyoming’s outline:

1

console.log(typeof wyoming.polygon.outline);

outline is an instance of ConstantProperty. This tutorial uses a shorthand called implicit property conversion, which automatically takes raw values and creates the corresponding Property under the hood. Without this shorthand, we would have to write a longer version of the initial example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var wyoming = new Cesium.Entity();
wyoming.name = 'Wyoming';

var polygon = new Cesium.PolygonGraphics();
polygon.material = new Cesium.ColorMaterialProperty(Cesium.Color.RED.withAlpha(0.5));
polygon.outline = new Cesium.ConstantProperty(true);
polygon.outlineColor = new Cesium.ConstantProperty(Cesium.Color.BLACK);
wyoming.polygon = polygon;

viewer.entities.add(wyoming);

Properties are used because the Entity API can represent not only constant values but also values that change over time. See the Callback Property and Interpolation Sandcastle examples for some time-dynamic properties.

Resources

For examples on how to style and create entities using GeoJSON and CZML, see the Cesium Workshop Tutorial.

Cesium Chinese Website QQ Group: 807482793

Cesium Chinese Website: http://cesiumcn.org/ | China Fast Access: http://cesium.coinidea.com/