A height field is defined by a 1-dimensional array (Samples) which contains NumberOfSamplesX x NumberOfSamplesZ height values. This array is triangulated. Each array element defines a triangle vertex. The height samples are addressed like this:

height(indexX, indexZ) = Samples[indexZ * NumberOfSamplesX + indexX]

The height field is placed in the local x/z plane where the up direction is the positive y-axis. The top-left height field corner (Samples[0]) is positioned at x = OriginX and z = OriginZ.

The height field is stretched to fill a rectangle WidthX x WidthZ.

Holes in the height field can be created by setting a height value in the Samples to NaN. All triangles touching the "hole" vertex will be removed. This also means that the shape of the hole depends on the current tessellation pattern. If all elements in the Samples are NaN, then the behavior of the height field is undefined.

Limitations of holes and collision detection: Please note that computation of ClosestPoints, might not work as expected if an object moves through a hole and under the height field. Also computation of contacts might not work as expected on the border triangles near the hole. For good collision detection results it is recommended to avoid closest points queries for objects under the height field and to always surround a hole with other collision objects. For instance if there is a cave in a game terrain, make the hole larger than the cave entrance and surround it with additional rock meshes.

Shape Features: If a HeightField is involved in a Contact the shape feature property (FeatureA or FeatureB) contains the index of the triangle that creates the Contact: Each cell consists of two triangles. The first cell contains the triangles 0 and 1. The next cell in positive x direction contains the triangles 2 and 3. And so on. To compute an index all cells of a row in positive x direction are enumerated then the next x-row is enumerated and so on.

Here is an example (pseudo-code):

HeightField { Samples=float[200], OriginX=3000, OriginY =4000, WidthX=100, WidthZ=200 }

This creates a height field in the x/z plane. The field is 100 units wide in the x-axis and 200 units wide in the z-axis. The array element [0] defines the height field height at x = 3000, z = 4000. The array element [199] defines the height field height at x = 3100, z = 4200

The HeightField must contain at least 2 x 2 elements.

For best performance, IGeometricObjects that have a HeightField shape should use only 90 degree rotations in their Pose. The local x/z plane of the height field should be normal to a world space axis plane.

For a height field the collision behavior is only defined in the x/z range of the height field. Beyond the height field limits the collision behavior is undefined. For example, if a box is left of the height field and moves sideways into the height field, the closest-point and contact information might not be intuitive and such cases should be avoided.

Reference