# Terrain

#### new Cesium.Terrain(terrainProviderPromise)
engine/Source/Scene/Terrain.js 43

A helper to manage async operations of a terrain provider.

Name | Type | Description
--- | --- | ---
`terrainProviderPromise` | Promise.<TerrainProvider> | A promise which resolves to a terrain provider

##### Examples:

    // Create
    const viewer = new Cesium.Viewer("cesiumContainer", {
      terrain: new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));
    });

    // Handle loading events
    const terrain = new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));

    scene.setTerrain(terrain);

    terrain.readyEvent.addEventListener(provider => {
      scene.globe.enableLighting = true;

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

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

##### See:

- Terrain.fromWorldTerrain
- CesiumTerrainProvider
- VRTheWorldTerrainProvider
- GoogleEarthEnterpriseTerrainProvider

### Members

#### readonly errorEvent : Event.<Terrain.ErrorEventCallback>
engine/Source/Scene/Terrain.js 65

Gets an event that is raised when the terrain 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.

#### readonly provider : TerrainProvider
engine/Source/Scene/Terrain.js 104

The terrain provider providing surface geometry to a globe. Do not use until `Terrain.readyEvent` is raised.

#### readonly ready : boolean
engine/Source/Scene/Terrain.js 91

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

#### readonly readyEvent : Event.<Terrain.ReadyEventCallback>
engine/Source/Scene/Terrain.js 78

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

### Methods

#### static Cesium.Terrain.fromWorldBathymetry(options) → Terrain
engine/Source/Scene/Terrain.js 204

Creates a `Terrain` instance for Cesium World Bathymetry.

Name | Type | Description
--- | --- | ---
`options` | Object | optional Object with the following properties:
Name | Type | Default | Description
--- | --- | --- | ---
`requestVertexNormals` | Boolean | `false` | optional Flag that indicates if the client should request additional lighting information from the server if available.

##### Returns:

An asynchronous helper object for a CesiumTerrainProvider

##### Examples:

    // Create Cesium World Bathymetry with default settings
    const viewer = new Cesium.Viewer("cesiumContainer", {
      terrain: Cesium.Terrain.fromWorldBathymetry)
    });

    // Create Cesium World Terrain with normals.
    const viewer1 = new Cesium.Viewer("cesiumContainer", {
      terrain: Cesium.Terrain.fromWorldBathymetry({
         requestVertexNormals: true
       });
    });

    // Handle loading events
    const bathymetry = Cesium.Terrain.fromWorldBathymetry();

    scene.setTerrain(bathymetry);

    bathymetry.readyEvent.addEventListener(provider => {
      scene.globe.enableLighting = true;

      bathymetry.provider.errorEvent.addEventListener(error => {
        alert(`Encountered an error while loading bathymetric terrain tiles! ${error}`);
      });
    });

    bathymetry.errorEvent.addEventListener(error => {
      alert(`Encountered an error while creating bathymetric terrain! ${error}`);
    });

##### See:

- Ion
- createWorldBathymetryAsync

#### static Cesium.Terrain.fromWorldTerrain(options) → Terrain
engine/Source/Scene/Terrain.js 156

Creates a `Terrain` instance for Cesium World Terrain.

Name | Type | Description
--- | --- | ---
`options` | Object | optional Object with the following properties:
Name | Type | Default | Description
--- | --- | --- | ---
`requestVertexNormals` | Boolean | `false` | optional Flag that indicates if the client should request additional lighting information from the server if available.
`requestWaterMask` | Boolean | `false` | optional Flag that indicates if the client should request per tile water masks from the server if available.

##### Returns:

An asynchronous helper object for a CesiumTerrainProvider

##### Examples:

    // Create Cesium World Terrain with default settings
    const viewer = new Cesium.Viewer("cesiumContainer", {
      terrain: Cesium.Terrain.fromWorldTerrain()
    });

    // Create Cesium World Terrain with water and normals.
    const viewer1 = new Cesium.Viewer("cesiumContainer", {
      terrain: Cesium.Terrain.fromWorldTerrain({
         requestWaterMask: true,
         requestVertexNormals: true
       });
    });

    // Handle loading events
    const terrain = Cesium.Terrain.fromWorldTerrain();

    scene.setTerrain(terrain);

    terrain.readyEvent.addEventListener(provider => {
      scene.globe.enableLighting = true;

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

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

##### See:

- Ion
- createWorldTerrainAsync

### Type Definitions

#### Cesium.Terrain.ErrorEventCallback(err)
engine/Source/Scene/Terrain.js 231

A function that is called when an error occurs.

##### This:

- Terrain

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

#### Cesium.Terrain.ReadyEventCallback(provider)
engine/Source/Scene/Terrain.js 239

A function that is called when the provider has been created

##### This:

- Terrain

Name | Type | Description
--- | --- | ---
`provider` | TerrainProvider | The created terrain provider.

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