Points are added and removed from the collection using
PointPrimitiveCollection#add
and PointPrimitiveCollection#remove.
Performance:
For best performance, prefer a few collections, each with many points, to many collections with only a few points each. Organize collections so that points with the same update frequency are in the same collection, i.e., points that do not change should be in one collection; points that change every frame should be in another collection; and so on.
| Name | Type | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
optional
Object with the following properties:
|
Example:
// Create a pointPrimitive collection with two points
const points = scene.primitives.add(new Cesium.PointPrimitiveCollection());
points.add({
position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
color : Cesium.Color.YELLOW
});
points.add({
position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
color : Cesium.Color.CYAN
});See:
Members
-
Default Value:
BlendOption.OPAQUE_AND_TRANSLUCENT
Draws the bounding sphere for each draw command in the primitive.
-
Default Value:
false
PointPrimitiveCollection#get to iterate over all the points
in the collection.
modelMatrix : Matrix4
Transforms.eastNorthUpToFixedFrame.
-
Default Value:
Matrix4.IDENTITYExample:
const center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
pointPrimitives.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
pointPrimitives.add({
color : Cesium.Color.ORANGE,
position : new Cesium.Cartesian3(0.0, 0.0, 0.0) // center
});
pointPrimitives.add({
color : Cesium.Color.YELLOW,
position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) // east
});
pointPrimitives.add({
color : Cesium.Color.GREEN,
position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) // north
});
pointPrimitives.add({
color : Cesium.Color.CYAN,
position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) // up
});See:
PointPrimitive at rest and are deliberately excluded
from PointPrimitiveCollection#length so that no existing
for (i < length) get(i) loop can materialize a million
objects by accident.
"auto" (the default) resolves a per-camera draw index in
WASM: horizon and frustum rejection on cube-face quadtree cells, then one
deterministic representative per roughly one-pixel cell.
"cull" decimates nothing: every site the horizon and the
frustum admit is drawn, and the kernel grows its emitted-list allocation
to one entry per site the first time cull is asked for, so the promise
holds at the dataset's own scale rather than only below a decimated
frame's draw cap. It costs four bytes per site while it is selected.
"off" disables the whole path, and the draw is then
byte-for-byte what it is without this feature.
The setting is a REQUEST. Outside SCENE3D, before a block has finished writing its vertices, and whenever the WASM backend cannot build an index, the collection draws everything - which is exactly the behaviour it has without a visibility index at all.
-
Default Value:
"auto"
-
Default Value:
true
ALL THREE, DELIBERATELY. The kernel's own accounting is the smallest of the three and quoting it alone under-reports the feature: at 6,951,096 sites across eight packed blocks the kernel holds ~9.05 B/site while the staging and the element buffer add 4 B/site each for the blocks above the per-block draw cap. A bytes-per-site figure that a reader can check against the process has to name what it counted.
-
Default Value:
1.0
Methods
Performance:
Calling add is expected constant time. However, the collection's vertex buffer
is rewritten - an O(n) operation that also incurs CPU to GPU overhead. For
best performance, add as many pointPrimitives as possible before calling update.
| Name | Type | Description |
|---|---|---|
options |
object | optional A template describing the point's properties as shown in Example 1. |
Returns:
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Examples:
// Example 1: Add a point, specifying all the default values.
const p = pointPrimitives.add({
show : true,
position : Cesium.Cartesian3.ZERO,
pixelSize : 10.0,
color : Cesium.Color.WHITE,
outlineColor : Cesium.Color.TRANSPARENT,
outlineWidth : 0.0,
id : undefined
});// Example 2: Specify only the point's cartographic position.
const p = pointPrimitives.add({
position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});See:
| Name | Type | Description |
|---|---|---|
pointPrimitive |
PointPrimitive | optional The point to check for. |
Returns:
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.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
pointPrimitives = pointPrimitives && pointPrimitives.destroy();See:
PointPrimitiveCollection#length to iterate over all the points
in the collection.
Performance:
Expected constant time. If points were removed from the collection and
PointPrimitiveCollection#update was not called, an implicit O(n)
operation is performed.
| Name | Type | Description |
|---|---|---|
index |
number | The zero-based index of the point. |
Returns:
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
// Toggle the show property of every point in the collection
const len = pointPrimitives.length;
for (let i = 0; i < len; ++i) {
const p = pointPrimitives.get(i);
p.show = !p.show;
}See:
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.
Performance:
Calling remove is expected constant time. However, the collection's vertex buffer
is rewritten - an O(n) operation that also incurs CPU to GPU overhead. For
best performance, remove as many points as possible before calling update.
If you intend to temporarily hide a point, it is usually more efficient to call
PointPrimitive#show instead of removing and re-adding the point.
| Name | Type | Description |
|---|---|---|
pointPrimitive |
PointPrimitive | The point to remove. |
Returns:
true if the point was removed; false if the point was not found in the collection.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
const p = pointPrimitives.add(...);
pointPrimitives.remove(p); // Returns trueSee:
PointPrimitives from the collection.
PACKED BLOCKS ARE NOT REMOVED. A packed block is owned by the
EntityCollection that created it, not by this collection, which
merely draws it; length, add, remove
and this method are the JavaScript-primitive half of the collection and stop
at _pointPrimitives. So after removeAll(),
length is 0 while packedLength and
totalLength are unchanged and the packed vertices are rebuilt
into the new vertex array. Use
PointPrimitiveCollection#removePackedBlock - or, from the owning
side, EntityCollection#removePacked - to drop a packed block.
Performance:
O(n). It is more efficient to remove all the points
from a collection and then add new ones than to create a new collection entirely.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
- PointPrimitiveCollection#add
- PointPrimitiveCollection#remove
- PointPrimitiveCollection#removePackedBlock
Example:
pointPrimitives.add(...);
pointPrimitives.add(...);
pointPrimitives.removeAll();