# PointPrimitiveCollection

#### new Cesium.PointPrimitiveCollection(options)
Scene/PointPrimitiveCollection.js 114

  A renderable collection of points.
  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:
  Name | Type | Default | Description
  --- | --- | --- | ---
  `modelMatrix` | Matrix4 | `Matrix4.IDENTITY` | optional The 4x4 transformation matrix that transforms each point from model to world coordinates.
  `debugShowBoundingVolume` | Boolean | `false` | optional For debugging only. Determines if this primitive's commands' bounding spheres are shown.

  ##### Example:

      // Create a pointPrimitive collection with two points
      var 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:

  - PointPrimitiveCollection#add
  - PointPrimitiveCollection#remove
  - PointPrimitive

### Members

#### debugShowBoundingVolume : Boolean
Scene/PointPrimitiveCollection.js 194

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

  Draws the bounding sphere for each draw command in the primitive.

  Default Value: `false`

#### length : Number
Scene/PointPrimitiveCollection.js 227

  Returns the number of points in this collection. This is commonly used with `PointPrimitiveCollection#get` to iterate over all the points in the collection.

#### modelMatrix : Matrix4
Scene/PointPrimitiveCollection.js 181

  The 4x4 transformation matrix that transforms each point in this collection from model to world coordinates. When this is the identity matrix, the pointPrimitives are drawn in world coordinates, i.e., Earth's WGS84 coordinates. Local reference frames can be used by providing a different transformation matrix, like that returned by `Transforms.eastNorthUpToFixedFrame`.
  Default Value: ``Matrix4.IDENTITY``

  ##### Example:

      var 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:

  - Transforms.eastNorthUpToFixedFrame

### Methods

#### add(pointPrimitive) → PointPrimitive
Scene/PointPrimitiveCollection.js 279

  Creates and adds a point with the specified initial properties to the collection. The added point is returned so it can be modified or removed from the collection later.

  ##### 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
  --- | --- | ---
  `pointPrimitive` | Object | optional A template describing the point's properties as shown in Example 1.

  ##### Returns:

  The point that was added to the collection.

  ##### Throws:

  - DeveloperError : This object was destroyed, i.e., destroy() was called.

  ##### Examples:

      // Example 1:  Add a point, specifying all the default values.
      var 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.
      var p = pointPrimitives.add({
        position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
      });

  ##### See:

  - PointPrimitiveCollection#remove
  - PointPrimitiveCollection#removeAll

#### contains(pointPrimitive) → Boolean
Scene/PointPrimitiveCollection.js 386

  Check whether this collection contains a given point.

  Name | Type | Description
  --- | --- | ---
  `pointPrimitive` | PointPrimitive | optional The point to check for.

  ##### Returns:

  true if this collection contains the point, false otherwise.

  ##### See:

  - PointPrimitiveCollection#get

#### destroy() → undefined
Scene/PointPrimitiveCollection.js 974

  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:

      pointPrimitives = pointPrimitives && pointPrimitives.destroy();

  ##### See:

  - PointPrimitiveCollection#isDestroyed

#### get(index) → PointPrimitive
Scene/PointPrimitiveCollection.js 417

  Returns the point in the collection at the specified index. Indices are zero-based and increase as points are added. Removing a point shifts all points after it to the left, changing their indices. This function is commonly used with `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:

  The point at the specified index.

  ##### Throws:

  - DeveloperError : This object was destroyed, i.e., destroy() was called.

  ##### Example:

      // Toggle the show property of every point in the collection
      var len = pointPrimitives.length;
      for (var i = 0; i < len; ++i) {
        var p = pointPrimitives.get(i);
        p.show = !p.show;
      }

  ##### See:

  - PointPrimitiveCollection#length

#### isDestroyed() → Boolean
Scene/PointPrimitiveCollection.js 952

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

  ##### See:

  - PointPrimitiveCollection#destroy

#### remove(pointPrimitive) → Boolean
Scene/PointPrimitiveCollection.js 312

  Removes a point from the collection.

  ##### 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:

      var p = pointPrimitives.add(...);
      pointPrimitives.remove(p);  // Returns true

  ##### See:

  - PointPrimitiveCollection#add
  - PointPrimitiveCollection#removeAll
  - PointPrimitive#show

#### removeAll()
Scene/PointPrimitiveCollection.js 341

  Removes all points from the collection.

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

  ##### Example:

      pointPrimitives.add(...);
      pointPrimitives.add(...);
      pointPrimitives.removeAll();

  ##### See:

  - PointPrimitiveCollection#add
  - PointPrimitiveCollection#remove