# ClippingPlaneCollection

#### new Cesium.ClippingPlaneCollection(options)
engine/Source/Scene/ClippingPlaneCollection.js 68

Specifies a set of clipping planes. Clipping planes selectively disable rendering in a region on the outside of the specified list of `ClippingPlane` objects for a single gltf model, 3D Tileset, or the globe.

In general the clipping planes' coordinates are relative to the object they're attached to, so a plane with distance set to 0 will clip through the center of the object.

For 3D Tiles, the root tile's transform is used to position the clipping planes. If a transform is not defined, the root tile's `Cesium3DTile#boundingSphere` is used instead.

Name | Type | Description
--- | --- | ---
`options` | object | optional Object with the following properties:
Name | Type | Default | Description
--- | --- | --- | ---
`planes` | Array.<ClippingPlane> | `[]` | optional An array of `ClippingPlane` objects used to selectively disable rendering on the outside of each plane.
`enabled` | boolean | `true` | optional Determines whether the clipping planes are active.
`modelMatrix` | Matrix4 | `Matrix4.IDENTITY` | optional The 4x4 transformation matrix specifying an additional transform relative to the clipping planes original coordinate system.
`unionClippingRegions` | boolean | `false` | optional If true, a region will be clipped if it is on the outside of any plane in the collection. Otherwise, a region will only be clipped if it is on the outside of every plane.
`edgeColor` | Color | `Color.WHITE` | optional The color applied to highlight the edge along which an object is clipped.
`edgeWidth` | number | `0.0` | optional The width, in pixels, of the highlight applied to the edge along which an object is clipped.

##### Example:

    // This clipping plane's distance is positive, which means its normal
    // is facing the origin. This will clip everything that is behind
    // the plane, which is anything with y coordinate < -5.
    const clippingPlanes = new Cesium.ClippingPlaneCollection({
        planes : [
            new Cesium.ClippingPlane(new Cesium.Cartesian3(0.0, 1.0, 0.0), 5.0)
        ],
    });
    // Create an entity and attach the ClippingPlaneCollection to the model.
    const entity = viewer.entities.add({
        position : Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706, 10000),
        model : {
            uri : 'model.gltf',
            minimumPixelSize : 128,
            maximumScale : 20000,
            clippingPlanes : clippingPlanes
        }
    });
    viewer.zoomTo(entity);

##### Demo:

- Clipping 3D Tiles and glTF models.
- Clipping the Globe.

### Members

#### edgeColor : Color
engine/Source/Scene/ClippingPlaneCollection.js 95

The color applied to highlight the edge along which an object is clipped.

Default Value: `Color.WHITE`

#### edgeWidth : number
engine/Source/Scene/ClippingPlaneCollection.js 103

The width, in pixels, of the highlight applied to the edge along which an object is clipped.

Default Value: `0.0`

#### enabled : boolean
engine/Source/Scene/ClippingPlaneCollection.js 201

If true, clipping will be enabled.

Default Value: `true`

#### readonly length : number
engine/Source/Scene/ClippingPlaneCollection.js 164

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

#### modelMatrix : Matrix4
engine/Source/Scene/ClippingPlaneCollection.js 87

The 4x4 transformation matrix specifying an additional transform relative to the clipping planes original coordinate system.

Default Value: `Matrix4.IDENTITY`

#### readonly planeAdded : Event
engine/Source/Scene/ClippingPlaneCollection.js 111

An event triggered when a new clipping plane is added to the collection. Event handlers are passed the new plane and the index at which it was added.

#### readonly planeRemoved : Event
engine/Source/Scene/ClippingPlaneCollection.js 119

An event triggered when a new clipping plane is removed from the collection. Event handlers are passed the new plane and the index from which it was removed.

#### unionClippingRegions : boolean
engine/Source/Scene/ClippingPlaneCollection.js 179

If true, a region will be clipped if it is on the outside of any plane in the collection. Otherwise, a region will only be clipped if it is on the outside of every plane.

Default Value: `false`

### Methods

#### add(plane)
engine/Source/Scene/ClippingPlaneCollection.js 280

Adds the specified `ClippingPlane` to the collection to be used to selectively disable rendering on the outside of each plane. Use `ClippingPlaneCollection#unionClippingRegions` to modify how modify the clipping behavior of multiple planes.

Name | Type | Description
--- | --- | ---
`plane` | ClippingPlane | The ClippingPlane to add to the collection.

##### See:

- ClippingPlaneCollection#unionClippingRegions
- ClippingPlaneCollection#remove
- ClippingPlaneCollection#removeAll

#### contains(clippingPlane) → boolean
engine/Source/Scene/ClippingPlaneCollection.js 333

Checks whether this collection contains a ClippingPlane equal to the given ClippingPlane.

Name | Type | Description
--- | --- | ---
`clippingPlane` | ClippingPlane | optional The ClippingPlane to check for.

##### Returns:

true if this collection contains the ClippingPlane, false otherwise.

##### See:

- ClippingPlaneCollection#get

#### destroy()
engine/Source/Scene/ClippingPlaneCollection.js 759

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.

##### Throws:

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

##### Example:

    clippingPlanes = clippingPlanes && clippingPlanes.destroy();

##### See:

- ClippingPlaneCollection#isDestroyed

#### get(index) → ClippingPlane
engine/Source/Scene/ClippingPlaneCollection.js 306

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

Name | Type | Description
--- | --- | ---
`index` | number | The zero-based index of the plane.

##### Returns:

The ClippingPlane at the specified index.

##### See:

- ClippingPlaneCollection#length

#### isDestroyed() → boolean
engine/Source/Scene/ClippingPlaneCollection.js 739

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:

- ClippingPlaneCollection#destroy

#### remove(clippingPlane) → boolean
engine/Source/Scene/ClippingPlaneCollection.js 347

Removes the first occurrence of the given ClippingPlane from the collection.

Name | Type | Description
--- | --- | ---
`clippingPlane` | ClippingPlane |

##### Returns:

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

##### See:

- ClippingPlaneCollection#add
- ClippingPlaneCollection#contains
- ClippingPlaneCollection#removeAll

#### removeAll()
engine/Source/Scene/ClippingPlaneCollection.js 386

Removes all planes from the collection.

##### See:

- ClippingPlaneCollection#add
- ClippingPlaneCollection#remove

#### update()
engine/Source/Scene/ClippingPlaneCollection.js 467

Called when `Viewer` or `CesiumWidget` render the scene to build the resources for clipping planes.

Do not call this function directly.

Need help? The fastest way to get answers is from the community and team on the Cesium Forum.