PolylineCollection - Cesium Documentation

# PolylineCollection

#### new PolylineCollection(options)

  A renderable collection of polylines.
  Example polylines
  Polylines are added and removed from the collection using `PolylineCollection#add` and `PolylineCollection#remove`.

  ##### Performance:

  For best performance, prefer a few collections, each with many polylines, to many collections with only a few polylines each. Organize collections so that polylines with the same update frequency are in the same collection, i.e., polylines that do not change should be in one collection; polylines 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 polyline 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 polyline collection with two polylines
      var polylines = new Cesium.PolylineCollection();
      polylines.add({
        positions : Cesium.Cartesian3.fromDegreesArray([
          -75.10, 39.57,
          -77.02, 38.53,
          -80.50, 35.14,
          -80.12, 25.46]),
        width : 2
      });

      polylines.add({
        positions : Cesium.Cartesian3.fromDegreesArray([
          -73.10, 37.57,
          -75.02, 36.53,
          -78.50, 33.14,
          -78.12, 23.46]),
        width : 4
      });

  ##### Demo:

  - Cesium Sandcastle Polyline Demo

  ##### See:

  - PolylineCollection#add
  - PolylineCollection#remove
  - Polyline
  - LabelCollection
  Source: Scene/PolylineCollection.js, line 139

### Members

#### debugShowBoundingVolume :Boolean

  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`
  Source: Scene/PolylineCollection.js, line 164

#### length :Number

  Returns the number of polylines in this collection. This is commonly used with `PolylineCollection#get` to iterate over all the polylines in the collection.
  Source: Scene/PolylineCollection.js, line 203

#### modelMatrix :Matrix4

  The 4x4 transformation matrix that transforms each polyline in this collection from model to world coordinates. When this is the identity matrix, the polylines 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``
  Source: Scene/PolylineCollection.js, line 151

### Methods

#### add(polyline) → Polyline

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

  ##### Performance:

  After calling `add`, `PolylineCollection#update` is called and the collection's vertex buffer is rewritten - an `O(n)` operation that also incurs CPU to GPU overhead. For best performance, add as many polylines as possible before calling `update`.

  Name | Type | Description
  --- | --- | ---
  `polyline` | Object | optional A template describing the polyline's properties as shown in Example 1.

  ##### Returns:

  The polyline that was added to the collection.

  ##### Throws:

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

  ##### Example:

      // Example 1:  Add a polyline, specifying all the default values.
      var p = polylines.add({
        show : true,
        positions : ellipsoid.cartographicDegreesToCartesians([
          new Cesium.Cartographic2(-75.10, 39.57),
          new Cesium.Cartographic2(-77.02, 38.53)]),
          width : 1
      });

  ##### See:

  - PolylineCollection#remove
  - PolylineCollection#removeAll
  - PolylineCollection#update
  Source: Scene/PolylineCollection.js, line 238

#### contains(polyline) → Boolean

  Determines if this collection contains the specified polyline.

  Name | Type | Description
  --- | --- | ---
  `polyline` | Polyline | The polyline to check for.

  ##### Returns:

  true if this collection contains the polyline, false otherwise.

  ##### See:

  - PolylineCollection#get
  Source: Scene/PolylineCollection.js, line 321

#### destroy() → undefined

  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:

      polylines = polylines && polylines.destroy();

  ##### See:

  - PolylineCollection#isDestroyed
  Source: Scene/PolylineCollection.js, line 634

#### get(index) → Polyline

  Returns the polyline in the collection at the specified index. Indices are zero-based and increase as polylines are added. Removing a polyline shifts all polylines after it to the left, changing their indices. This function is commonly used with `PolylineCollection#length` to iterate over all the polylines in the collection.

  ##### Performance:

  If polylines were removed from the collection and `PolylineCollection#update` was not called, an implicit `O(n)` operation is performed.

  Name | Type | Description
  --- | --- | ---
  `index` | Number | The zero-based index of the polyline.

  ##### Returns:

  The polyline at the specified index.

  ##### Throws:

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

  ##### Example:

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

  ##### See:

  - PolylineCollection#length
  Source: Scene/PolylineCollection.js, line 351

#### isDestroyed() → Boolean

  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:

  - PolylineCollection#destroy
  Source: Scene/PolylineCollection.js, line 613

#### remove(polyline) → Boolean

  Removes a polyline from the collection.

  ##### Performance:

  After calling `remove`, `PolylineCollection#update` is called and the collection's vertex buffer is rewritten - an `O(n)` operation that also incurs CPU to GPU overhead. For best performance, remove as many polylines as possible before calling `update`. If you intend to temporarily hide a polyline, it is usually more efficient to call `Polyline#show` instead of removing and re-adding the polyline.

  Name | Type | Description
  --- | --- | ---
  `polyline` | Polyline | The polyline to remove.

  ##### Returns:

  `true` if the polyline was removed; `false` if the polyline was not found in the collection.

  ##### Throws:

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

  ##### Example:

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

  ##### See:

  - PolylineCollection#add
  - PolylineCollection#removeAll
  - PolylineCollection#update
  - Polyline#show
  Source: Scene/PolylineCollection.js, line 269

#### removeAll()

  Removes all polylines from the collection.

  ##### Performance:

  `O(n)`. It is more efficient to remove all the polylines 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:

      polylines.add(...);
      polylines.add(...);
      polylines.removeAll();

  ##### See:

  - PolylineCollection#add
  - PolylineCollection#remove
  - PolylineCollection#update
  Source: Scene/PolylineCollection.js, line 303