
## Ground From a Height Map

When the ground is created using _groundFromHeightMap_ the surface of the ground can be perturbed by a grayscale image file called a height map. Lighter areas are displayed higher than darker areas. This is a way of creating hills and valleys on your ground.

## MeshBuilder

Usage:

```javascript
const ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("gdhm", url_to_height_map, options, scene); //scene is optional and defaults to the current scene
```

| option       | value                                                                             | default value          |
| ------------ | --------------------------------------------------------------------------------- | ---------------------- |
| width        | _(number)_ size of the map width                                                  | 10                     |
| height       | _(number)_ size of the map height                                                 | 10                     |
| subdivisions | _(number)_ number of map subdivisions                                             | 1                      |
| minHeight    | _(number)_ minimum altitude                                                       | 0                      |
| maxHeight    | _(number)_ maximum altitude                                                       | 1                      |
| onReady      | _(function)_ a callback js function that is called and passed the just built mesh | (mesh) =\> \{return;\} |
| updatable    | _(boolean)_ true if the mesh is updatable                                         | false                  |

### Examples

The following image is used for the height map in the first examples

![height map](/img/how_to/HeightMap/heightMap.png)  
Low subdivisions: <Playground id="#LQ4LI1" title="Create Ground From A HeightMap - Low Subdivisions" description="Simple example of creating ground from a heightmap with low subdivision."/>
High subdivisions: <Playground id="#LQ4LI1#1" title="Create Ground From A HeightMap - High Subdivisions" description="Simple example of creating ground from a heightmap with high subdivision."/>

Flat world: <Playground id="#LQ4LI1#3" title="Create Ground From A HeightMap" description="Simple example of creating ground from a heightmap."/>

## Mesh

Usage :

```javascript
var ground = BABYLON.Mesh.CreateGroundFromHeightMap("ground", heightMapPath, width, height, subdivisions, minHeight, maxHeight, scene, updatable, onReadyCallback);
```



## Introduction

In this tutorial, our goal is to understand height maps, a method used to generate realistic terrain. 
Height-maps are easy to use, customizable yet produce impressive terrain:

>  What we are going to try and achieve

![HeightMap](/img/how_to/HeightMap/14.png)

## How to do this?

### How height-maps work

Understanding height maps is the main objective of this tutorial. A height map is simply a gray-scale texture. Each pixel in the texture maps onto the height of a point on a plane, thus the name height-map. The whiter the pixel the higher the displacement, the darker the lesser the displacement. From the variations of gray within the texture we can map out a terrain. For this example we shall use the following texture: 

![HeightMap3](/img/how_to/HeightMap/worldHeightMap.jpg)

> To help you generate height-map textures (like the one above), you can use software such as [Terragen](https://planetside.co.uk/free-downloads/terragen-4-free-download/), or [Picogen ](https://picogen.org/downloads.php.html)(free).

### Javascript code

Now let’s see this powerful function named `CreateGroundFromHeightMap`:

```javascript
// Create a material with our land texture.
let groundMaterial = new BABYLON.StandardMaterial("ground", scene);
groundMaterial.diffuseTexture = new BABYLON.Texture("Earth__land.jpg", scene);

// Use CreateGroundFromHeightMap to create a height map of 20 units by 20
// And a height of to
// units, with 250 subdivisions in each of the `x` and `z` directions, for a
// total of 62,500 divisions.
const ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("gdhm", "textures/heightMap.png", {
    width: 20, height: 20, subdivisions: 250, maxHeight: 10, minHeight: 2
});

// Bind our material to our mesh
ground.material = groundMaterial;
```

The parameters passed are:

- **name**: The name of the resulting mesh
- **Height-map texture**: The URL of the height-map texture.
- **options**: The options for producing the height-map.
- **scene**: The scene to append the resulting mesh
- **updatable**: Boolean to specify if the mesh should be updatable.
- **successCallback**: Callback that resolves to the successfully produced height-map terrain.

The following are options, third parameter, used to construct the height-mapped plane:

* **width**: The width of the plane
* **height**: The height of the plane
* **minHeight**: Lowest point on the plane
* **maxHeight**: Highest point on the plane
* **subdivisions**: How detailed should our height-mapped plane be. Higher for higher poly count and therefore better visual quality. As seen below:
* ![HeightMap4](/img/how_to/HeightMap/14-2.png)

----

> Now we can see a 3d representation of the earth's surface on a plane!

![HeightMap4](/img/how_to/HeightMap/14-3.png)

Another example showing basic lighting, height-maps and a [skybox](/features/featuresDeepDive/environment/environment_introduction) in use!

![HeightMap5](/img/how_to/HeightMap/14-4.png)

### Tips.

If a height-map negatively impacts performance try reducing the subdivisions to reduce the number of polygons on the mesh. For further documentation go to the [CreateGroundFromHeightMesh](https://doc.babylonjs.com/typedoc/modules/BABYLON#CreateGroundFromHeightMap-2) API reference.

#### Playground examples.

<Playground id="#95PXRY" title="Height Map Example" description="Simple example of using a height map."/>



## Ground

A ground is a flat horizontal plane parallel to the xz plane which can be subdivided into rectangular regions. The origin of the ground is at the center of the plane. The optional properties for determining the size of the ground are width (x) and height (z) (and yes we all agree that depth would be more descriptive than height!)

## MeshBuilder

Usage :

```javascript
const ground = BABYLON.MeshBuilder.CreateGround("ground", options, scene); //scene is optional and defaults to the current scene
```

| option       | value                                                    | default value |
| ------------ | -------------------------------------------------------- | ------------- |
| width        | _(number)_ size of the width                             | 1             |
| height       | _(number)_ size of the height                            | 1             |
| updatable    | _(boolean)_ true if the mesh is updatable                | false         |
| subdivisions | _(number)_ number of square subdivisions along each axis | 1             |

### Example

Ground: <Playground id="#45R5JK" title="Create a Ground" description="Simple example of creating a ground."/>

## Mesh

Usage

```javascript
const ground = BABYLON.MeshBuilder.CreateGround("ground", { width, height, subdivisions }, scene);
const ground = BABYLON.MeshBuilder.CreateGround("ground", { width, height, subdivisions }, scene, updatable); //one optional parameter after scene
```
