- Qt 6.12
- Qt Quick 3D Physics
- QML Types
- HeightFieldShape
- Qt Quick 3D Physics | Commercial or GPLv3

# HeightFieldShape QML Type

A collision shape where the elevation is defined by a height map. More...

Import Statement: | `import QtQuick3D.Physics`
Since: | Qt 6.4
Inherits: | CollisionShape

- List of all members, including inherited members

## Properties

- extents : vector3d
- image : Image `(since 6.7)`
- source : url

## Detailed Description

The HeightFieldShape type defines a physical surface where the height is determined by the value of the pixels of the source image. The x-axis of the image is mapped to the positive x-axis of the scene, and the y-axis of the image is mapped to the negative z-axis of the scene. A typical use case is to represent natural terrain.

Objects that are controlled by the physics simulation cannot use HeightFieldShape: It can only be used with StaticRigidBody and kinematic bodies.

QtQuick3D.Helpers.HeightFieldGeometry is API compatible with the HeightFieldShape type, and can be used to show the height field visually. To improve performance, use a lower resolution version of the height map for the HeightFieldShape: As long as the extents and the image aspect ratio are the same, the physics body and the visual item will overlap.

See also Qt Quick 3D Physics Shapes, Bodies and Joints.

## Property Documentation

### extents : vector3d

This property defines the extents of the height field. The default value is `(100, 100, 100)` when the heightMap is square. If the heightMap is non-square, the default value is reduced along the x- or z-axis, so the height field will keep the aspect ratio of the image.

### image : Image `[since 6.7]`

This property defines the image holding the heightMap.

Internally, HeightFieldShape converts the height map image to an optimized data structure. This conversion can be done in advance. See the cooking overview documentation for details.

Note: If both the image and source properties are set then only image will be used.

This property was introduced in Qt 6.7.

See also HeightFieldShape::source.

### source : url

This property defines the location of the heightMap file.

Internally, HeightFieldShape converts the height map image to an optimized data structure. This conversion can be done in advance. See the cooking overview documentation for details.

Note: If both the image and source properties are set then only image will be used.

See also HeightFieldShape::image.