# ImageryLayer

#### new Cesium.ImageryLayer(imageryProvider, options)
engine/Source/Scene/ImageryLayer.js 174

An imagery layer that displays tiled image data from a single imagery provider on a `Globe` or `Cesium3DTileset`.

Name | Type | Description
--- | --- | ---
`imageryProvider` | ImageryProvider | optional The imagery provider to use.
`options` | ImageryLayer.ConstructorOptions | optional An object describing initialization options

##### Examples:

    // Add an OpenStreetMaps layer
    const imageryLayer = new Cesium.ImageryLayer(new Cesium.OpenStreetMapImageryProvider({
      url: "https://tile.openstreetmap.org/"
    }));
    scene.imageryLayers.add(imageryLayer);

    // Add Cesium ion's default world imagery layer
    const imageryLayer = Cesium.ImageryLayer.fromWorldImagery();
    scene.imageryLayers.add(imageryLayer);

    // Add a new transparent layer from Cesium ion
    const imageryLayer = Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
    imageryLayer.alpha = 0.5;
    scene.imageryLayers.add(imageryLayer);

    // Drape Bing Maps Aerial imagery over a 3D tileset
    const tileset = await Cesium.Cesium3DTileset.fromUrl(
      "http://localhost:8002/tilesets/Seattle/tileset.json"
    );
    scene.primitives.add(tileset);

    const imageryProvider = await Cesium.createWorldImageryAsync({
      style: Cesium.IonWorldImageryStyle.AERIAL,
    });
    const imageryLayer = new ImageryLayer(imageryProvider);
    tileset.imageryLayers.add(imageryLayer);

##### See:

- `ImageryLayer.fromProviderAsync` for creating an imagery layer from an asynchronous imagery provider.
- `ImageryLayer.fromWorldImagery` for creating an imagery layer for Cesium ion's default global base imagery layer.
- `Scene#imageryLayers` for adding an imagery layer to the globe.
- `Cesium3DTileset#imageryLayers` for adding an imagery layer to a 3D tileset.

### Members

#### static Cesium.ImageryLayer.DEFAULT_APPLY_COLOR_TO_ALPHA_THRESHOLD : number
engine/Source/Scene/ImageryLayer.js 494

This value is used as the default threshold for color-to-alpha if one is not provided during construction or by the imagery provider.

Default Value: `0.004`

#### static Cesium.ImageryLayer.DEFAULT_BRIGHTNESS : number
engine/Source/Scene/ImageryLayer.js 434

This value is used as the default brightness for the imagery layer if one is not provided during construction or by the imagery provider. This value does not modify the brightness of the imagery.

Default Value: `1.0`

#### static Cesium.ImageryLayer.DEFAULT_CONTRAST : number
engine/Source/Scene/ImageryLayer.js 441

This value is used as the default contrast for the imagery layer if one is not provided during construction or by the imagery provider. This value does not modify the contrast of the imagery.

Default Value: `1.0`

#### static Cesium.ImageryLayer.DEFAULT_GAMMA : number
engine/Source/Scene/ImageryLayer.js 462

This value is used as the default gamma for the imagery layer if one is not provided during construction or by the imagery provider. This value does not modify the gamma of the imagery.

Default Value: `1.0`

#### static Cesium.ImageryLayer.DEFAULT_HUE : number
engine/Source/Scene/ImageryLayer.js 448

This value is used as the default hue for the imagery layer if one is not provided during construction or by the imagery provider. This value does not modify the hue of the imagery.

Default Value: `0.0`

#### static Cesium.ImageryLayer.DEFAULT_MAGNIFICATION_FILTER : TextureMagnificationFilter
engine/Source/Scene/ImageryLayer.js 486

This value is used as the default texture magnification filter for the imagery layer if one is not provided during construction or by the imagery provider.

Default Value: `TextureMagnificationFilter.LINEAR`

#### static Cesium.ImageryLayer.DEFAULT_MINIFICATION_FILTER : TextureMinificationFilter
engine/Source/Scene/ImageryLayer.js 478

This value is used as the default texture minification filter for the imagery layer if one is not provided during construction or by the imagery provider.

Default Value: `TextureMinificationFilter.LINEAR`

#### static Cesium.ImageryLayer.DEFAULT_SATURATION : number
engine/Source/Scene/ImageryLayer.js 455

This value is used as the default saturation for the imagery layer if one is not provided during construction or by the imagery provider. This value does not modify the saturation of the imagery.

Default Value: `1.0`

#### static Cesium.ImageryLayer.DEFAULT_SPLIT : SplitDirection
engine/Source/Scene/ImageryLayer.js 470

This value is used as the default split for the imagery layer if one is not provided during construction or by the imagery provider.

Default Value: `SplitDirection.NONE`

#### alpha : number
engine/Source/Scene/ImageryLayer.js 190

The alpha blending value of this layer, with 0.0 representing fully transparent and 1.0 representing fully opaque.

Default Value: `1.0`

#### brightness : number
engine/Source/Scene/ImageryLayer.js 218

The brightness of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 makes the imagery darker while greater than 1.0 makes it brighter.

Default Value: ``ImageryLayer.DEFAULT_BRIGHTNESS``

#### colorToAlpha : Color
engine/Source/Scene/ImageryLayer.js 350

Color value that should be set to transparent.

#### colorToAlphaThreshold : number
engine/Source/Scene/ImageryLayer.js 357

Normalized (0-1) threshold for color-to-alpha.

#### contrast : number
engine/Source/Scene/ImageryLayer.js 230

The contrast of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the contrast while greater than 1.0 increases it.

Default Value: ``ImageryLayer.DEFAULT_CONTRAST``

#### cutoutRectangle : Rectangle
engine/Source/Scene/ImageryLayer.js 343

Rectangle cutout in this layer of imagery.

#### dayAlpha : number
engine/Source/Scene/ImageryLayer.js 209

The alpha blending value of this layer on the day side of the globe, with 0.0 representing fully transparent and 1.0 representing fully opaque. This only takes effect when `Globe#enableLighting` is `true`.

Default Value: `1.0`

#### readonly errorEvent : Event.<ImageryLayer.ErrorEventCallback>
engine/Source/Scene/ImageryLayer.js 395

Gets an event that is raised when the imagery provider encounters an asynchronous error. By subscribing to the event, you will be notified of the error and can potentially recover from it. Event listeners are passed an instance of the thrown error.

#### gamma : number
engine/Source/Scene/ImageryLayer.js 262

The gamma correction to apply to this layer. 1.0 uses the unmodified imagery color.

Default Value: ``ImageryLayer.DEFAULT_GAMMA``

#### hue : number
engine/Source/Scene/ImageryLayer.js 241

The hue of this layer in radians. 0.0 uses the unmodified imagery color.

Default Value: ``ImageryLayer.DEFAULT_HUE``

#### readonly imageryProvider : ImageryProvider
engine/Source/Scene/ImageryLayer.js 369

Gets the imagery provider for this layer. This should not be called before `ImageryLayer#ready` returns true.

#### magnificationFilter : TextureMagnificationFilter
engine/Source/Scene/ImageryLayer.js 302

The `TextureMagnificationFilter` to apply to this layer. Possible values are `TextureMagnificationFilter.LINEAR` (the default) and `TextureMagnificationFilter.NEAREST`. To take effect, this property must be set immediately after adding the imagery layer. Once a texture is loaded it won't be possible to change the texture filter used.

Default Value: ``ImageryLayer.DEFAULT_MAGNIFICATION_FILTER``

#### minificationFilter : TextureMinificationFilter
engine/Source/Scene/ImageryLayer.js 286

The `TextureMinificationFilter` to apply to this layer. Possible values are `TextureMinificationFilter.LINEAR` (the default) and `TextureMinificationFilter.NEAREST`. To take effect, this property must be set immediately after adding the imagery layer. Once a texture is loaded it won't be possible to change the texture filter used.

Default Value: ``ImageryLayer.DEFAULT_MINIFICATION_FILTER``

#### nightAlpha : number
engine/Source/Scene/ImageryLayer.js 199

The alpha blending value of this layer on the night side of the globe, with 0.0 representing fully transparent and 1.0 representing fully opaque. This only takes effect when `Globe#enableLighting` is `true`.

Default Value: `1.0`

#### readonly ready : boolean
engine/Source/Scene/ImageryLayer.js 381

Returns true when the terrain provider has been successfully created. Otherwise, returns false.

#### readonly readyEvent : Event.<ImageryLayer.ReadyEventCallback>
engine/Source/Scene/ImageryLayer.js 408

Gets an event that is raised when the imagery provider has been successfully created. Event listeners are passed the created instance of `ImageryProvider`.

#### readonly rectangle : Rectangle
engine/Source/Scene/ImageryLayer.js 421

Gets the rectangle of this layer. If this rectangle is smaller than the rectangle of the `ImageryProvider`, only a portion of the imagery provider is shown.

#### saturation : number
engine/Source/Scene/ImageryLayer.js 251

The saturation of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the saturation while greater than 1.0 increases it.

Default Value: ``ImageryLayer.DEFAULT_SATURATION``

#### show : boolean
engine/Source/Scene/ImageryLayer.js 313

Determines if this layer is shown.

Default Value: `true`

#### splitDirection : SplitDirection
engine/Source/Scene/ImageryLayer.js 273

The `SplitDirection` to apply to this layer.

Default Value: ``ImageryLayer.DEFAULT_SPLIT``

### Methods

#### static Cesium.ImageryLayer.fromProviderAsync(imageryProviderPromise, options) → ImageryLayer
engine/Source/Scene/ImageryLayer.js 535

Create a new imagery layer from an asynchronous imagery provider. The layer will handle any asynchronous loads or errors, and begin rendering the imagery layer once ready.

Name | Type | Description
--- | --- | ---
`imageryProviderPromise` | Promise.<ImageryProvider> | A promise which resolves to a imagery provider
`options` | ImageryLayer.ConstructorOptions | optional An object describing initialization options

##### Returns:

The created imagery layer.

##### Examples:

    // Create a new base layer
    const viewer = new Cesium.Viewer("cesiumContainer", {
      baseLayer: Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
    });

    // Add a new transparent layer
    const imageryLayer = Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
    imageryLayer.alpha = 0.5;
    viewer.imageryLayers.add(imageryLayer);

    // Handle loading events
    const imageryLayer = Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
    viewer.imageryLayers.add(imageryLayer);

    imageryLayer.readyEvent.addEventListener(provider => {
      imageryLayer.imageryProvider.errorEvent.addEventListener(error => {
        alert(`Encountered an error while loading imagery tiles! ${error}`);
      });
    });

    imageryLayer.errorEvent.addEventListener(error => {
      alert(`Encountered an error while creating an imagery layer! ${error}`);
    });

##### See:

- ImageryLayer#errorEvent
- ImageryLayer#readyEvent
- ImageryLayer#imageryProvider
- ImageryLayer.fromWorldImagery

#### static Cesium.ImageryLayer.fromWorldImagery(options) → ImageryLayer
engine/Source/Scene/ImageryLayer.js 592

Create a new imagery layer for ion's default global base imagery layer, currently Bing Maps. The layer will handle any asynchronous loads or errors, and begin rendering the imagery layer once ready.

Name | Type | Description
--- | --- | ---
`options` | ImageryLayer.WorldImageryConstructorOptions | An object describing initialization options

##### Returns:

The created imagery layer. * @example // Create a new base layer const viewer = new Cesium.Viewer("cesiumContainer", { baseLayer: Cesium.ImageryLayer.fromWorldImagery(); });

##### Examples:

    // Add a new transparent layer
    const imageryLayer = Cesium.ImageryLayer.fromWorldImagery();
    imageryLayer.alpha = 0.5;
    viewer.imageryLayers.add(imageryLayer);

    // Handle loading events
    const imageryLayer = Cesium.ImageryLayer.fromWorldImagery();
    viewer.imageryLayers.add(imageryLayer);

    imageryLayer.readyEvent.addEventListener(provider => {
      imageryLayer.imageryProvider.errorEvent.addEventListener(error => {
        alert(`Encountered an error while loading imagery tiles! ${error}`);
      });
    });

    imageryLayer.errorEvent.addEventListener(error => {
      alert(`Encountered an error while creating an imagery layer! ${error}`);
    });

##### See:

- ImageryLayer#errorEvent
- ImageryLayer#readyEvent
- ImageryLayer#imageryProvider

#### destroy()
engine/Source/Scene/ImageryLayer.js 646

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:

    imageryLayer = imageryLayer && imageryLayer.destroy();

##### See:

- ImageryLayer#isDestroyed

#### getImageryRectangle() → Rectangle
engine/Source/Scene/ImageryLayer.js 669

Computes the intersection of this layer's rectangle with the imagery provider's availability rectangle, producing the overall bounds of imagery that can be produced by this layer.

##### Returns:

A rectangle which defines the overall bounds of imagery that can be produced by this layer.

##### Example:

    // Zoom to an imagery layer.
    const imageryRectangle = imageryLayer.getImageryRectangle();
    scene.camera.flyTo({
        destination: rectangle
    });

#### isBaseLayer() → boolean
engine/Source/Scene/ImageryLayer.js 612

Gets a value indicating whether this layer is the base layer in the `ImageryLayerCollection`. The base layer is the one that underlies all others. It is special in that it is treated as if it has global rectangle, even if it actually does not, by stretching the texels at the edges over the entire globe.

##### Returns:

true if this is the base layer; otherwise, false.

#### isDestroyed() → boolean
engine/Source/Scene/ImageryLayer.js 626

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:

- ImageryLayer#destroy

### Type Definitions

#### Cesium.ImageryLayer.ConstructorOptions
engine/Source/Scene/ImageryLayer.js 42

Initialization options for the ImageryLayer constructor.

##### Properties:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`rectangle` | Rectangle | <optional> | imageryProvider.rectangle | The rectangle of the layer. This rectangle can limit the visible portion of the imagery provider.
`alpha` | number | function | <optional> | 1.0 | The alpha blending value of this layer, from 0.0 to 1.0. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the alpha is required, and it is expected to return the alpha value to use for the tile.
`nightAlpha` | number | function | <optional> | 1.0 | The alpha blending value of this layer on the night side of the globe, from 0.0 to 1.0. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the alpha is required, and it is expected to return the alpha value to use for the tile. This only takes effect when `enableLighting` is `true`.
`dayAlpha` | number | function | <optional> | 1.0 | The alpha blending value of this layer on the day side of the globe, from 0.0 to 1.0. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the alpha is required, and it is expected to return the alpha value to use for the tile. This only takes effect when `enableLighting` is `true`.
`brightness` | number | function | <optional> | 1.0 | The brightness of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 makes the imagery darker while greater than 1.0 makes it brighter. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the brightness is required, and it is expected to return the brightness value to use for the tile. The function is executed for every frame and for every tile, so it must be fast.
`contrast` | number | function | <optional> | 1.0 | The contrast of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the contrast while greater than 1.0 increases it. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the contrast is required, and it is expected to return the contrast value to use for the tile. The function is executed for every frame and for every tile, so it must be fast.
`hue` | number | function | <optional> | 0.0 | The hue of this layer. 0.0 uses the unmodified imagery color. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the hue is required, and it is expected to return the hue value to use for the tile. The function is executed for every frame and for every tile, so it must be fast.
`saturation` | number | function | <optional> | 1.0 | The saturation of this layer. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the saturation while greater than 1.0 increases it. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the saturation is required, and it is expected to return the saturation value to use for the tile. The function is executed for every frame and for every tile, so it must be fast.
`gamma` | number | function | <optional> | 1.0 | The gamma correction to apply to this layer. 1.0 uses the unmodified imagery color. This can either be a simple number or a function with the signature `function(frameState, layer, x, y, level)`. The function is passed the current frame state, this layer, and the x, y, and level coordinates of the imagery tile for which the gamma is required, and it is expected to return the gamma value to use for the tile. The function is executed for every frame and for every tile, so it must be fast.
`splitDirection` | SplitDirection | function | <optional> | SplitDirection.NONE | The `SplitDirection` split to apply to this layer.
`minificationFilter` | TextureMinificationFilter | <optional> | TextureMinificationFilter.LINEAR | The texture minification filter to apply to this layer. Possible values are `TextureMinificationFilter.LINEAR` and `TextureMinificationFilter.NEAREST`.
`magnificationFilter` | TextureMagnificationFilter | <optional> | TextureMagnificationFilter.LINEAR | The texture minification filter to apply to this layer. Possible values are `TextureMagnificationFilter.LINEAR` and `TextureMagnificationFilter.NEAREST`.
`show` | boolean | <optional> | true | True if the layer is shown; otherwise, false.
`maximumAnisotropy` | number | <optional> | maximum supported | The maximum anisotropy level to use for texture filtering. If this parameter is not specified, the maximum anisotropy supported by the WebGL stack will be used. Larger values make the imagery look better in horizon views.
`minimumTerrainLevel` | number | <optional> |  | The minimum terrain level-of-detail at which to show this imagery layer, or undefined to show it at all levels. Level zero is the least-detailed level.
`maximumTerrainLevel` | number | <optional> |  | The maximum terrain level-of-detail at which to show this imagery layer, or undefined to show it at all levels. Level zero is the least-detailed level.
`cutoutRectangle` | Rectangle | <optional> |  | Cartographic rectangle for cutting out a portion of this ImageryLayer.
`colorToAlpha` | Color | <optional> |  | Color to be used as alpha.
`colorToAlphaThreshold` | number | <optional> | 0.004 | Threshold for color-to-alpha.

#### Cesium.ImageryLayer.ErrorEventCallback(err)
engine/Source/Scene/ImageryLayer.js 1733

A function that is called when an error occurs.

##### This:

- ImageryLayer

Name | Type | Description
--- | --- | ---
`err` | Error | An object holding details about the error that occurred.

#### Cesium.ImageryLayer.ReadyEventCallback(provider)
engine/Source/Scene/ImageryLayer.js 1741

A function that is called when the provider has been created

##### This:

- ImageryLayer

Name | Type | Description
--- | --- | ---
`provider` | ImageryProvider | The created imagery provider.

#### Cesium.ImageryLayer.WorldImageryConstructorOptions
engine/Source/Scene/ImageryLayer.js 547

Initialization options for ImageryLayer.fromWorldImagery

##### Properties:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`options.style` | IonWorldImageryStyle | <optional> | IonWorldImageryStyle | The style of base imagery, only AERIAL, AERIAL_WITH_LABELS, and ROAD are currently supported.

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