
## 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 to create 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 JavaScript callback function that is called and passed the newly 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.webp)  
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, and still produce impressive terrain:

>  What we are going to try and achieve

![HeightMap](/img/how_to/HeightMap/14.webp)

## 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, hence the name height map. The whiter the pixel, the higher the displacement; the darker the pixel, the smaller the displacement. From the variations of gray within the texture, we can map out terrain. For this example, we shall use the following texture: 

![HeightMap3](/img/how_to/HeightMap/worldHeightMap.webp)

> 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 look at the 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 which the resulting mesh is appended.
- **updatable**: Boolean to specify if the mesh should be updatable.
- **successCallback**: Callback that receives the successfully produced height-map terrain.

The following options, passed as the third parameter, are 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 the height-mapped plane should be. Higher values mean a higher polygon count and therefore better visual quality, as seen below:
* ![HeightMap4](/img/how_to/HeightMap/14-2.webp)

----

> Now we can see a 3D representation of the earth's surface on a plane!

![HeightMap4](/img/how_to/HeightMap/14-3.webp)

Another example showing basic lighting, height maps, and a [skybox](/features/featuresDeepDive/environment/environment_introduction) in use!

![HeightMap5](/img/how_to/HeightMap/14-4.webp)

### Tips.

If a height map negatively impacts performance, try reducing the subdivisions to reduce the number of polygons on the mesh. For further documentation, see 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 that can be subdivided into rectangular regions. The origin of the ground is at the center of the plane. The optional properties that determine 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
```


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 JavaScript callback function that is called and passed the newly built mesh	(mesh) => {return;}
updatable	(boolean) true if the mesh is updatable	false

Creating Ground From a Height Map

Ground From a Height Map

MeshBuilder

Examples

Mesh