raisim::HeightMap

class · #include <raisim/object/terrain/HeightMap.hpp>

Inherits: raisim::SingleBodyObject
Derived by: raisim::DeformableTerrain

A static terrain defined by a regular grid of heights (create it with World::addHeightMap()). The grid lies in the heightmap's own frame. It covers [centerX - xSize/2, centerX + xSize/2] x [centerY - ySize/2, centerY + ySize/2] there, and the heights are z coordinates in that frame; sample (x, y) is stored at index y * xSamples + x, with index 0 at the minimum x and y. Height samples may be NaN or infinity and are stored without filtering. Heights are interpolated over two triangles per cell. A triangle with a NaN or infinite corner is a hole: bodies, granular media and rays pass through it.

Like every other object, the heightmap is placed by the pose of its frame: setPosition() moves the frame origin and setOrientation() rotates the frame about that origin, so a point p of the frame lies at position + R p in the world. A new heightmap has the identity pose, so its grid is centered at (centerX, centerY) in the world. Collision (including granular media and swept CCD), ray tests and rendering follow the full pose.

The point queries getHeight(), getContactHeight(), getNormal() and getColor() ignore the orientation by design: they read the height field as if only the translation were applied, so a world-frame (x, y) addresses the grid directly. To evaluate a rotated map, query its unrotated coordinates and rotate the result about the position t: the surface point above (x, y) of the unrotated map is t + R ((x, y, getHeight(x, y)) - t), and its normal is R getNormal(x, y). For a world point w, the unrotated coordinates are t + R^T (w - t).

Constructors & destructor

HeightMap

HeightMap(
    double centerX,
    double centerY,
    const std::string &raisimHeightMapFileName)

load a heightmap from a raisim text file: "xSamples ySamples xSize ySize" followed by xSamples*ySamples heights.

Parameters

Parameter	Description
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
raisimHeightMapFileName (in)	path to the text file

HeightMap(
    double centerX,
    double centerY,
    const std::string &pngFileName,
    double xSize,
    double ySize,
    double heightScale,
    double heightOffset)

load a heightmap from a grayscale PNG (8 or 16 bit). Each height is pixelValue * heightScale + heightOffset.

Parameters

Parameter	Description
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
pngFileName (in)	path to the PNG file (must have the .png extension)
xSize (in)	size in x (m)
ySize (in)	size in y (m)
heightScale (in)	scale applied to the raw pixel value
heightOffset (in)	offset added after scaling (m)

HeightMap(
    size_t xSamples,
    size_t ysamples,
    double xSize,
    double ySize,
    double centerX,
    double centerY,
    const std::vector<double> &height)

create a heightmap from height samples.

Parameters

Parameter	Description
xSamples (in)	number of samples in x (at least 2)
ysamples (in)	number of samples in y (at least 2)
xSize (in)	size in x (m)
ySize (in)	size in y (m)
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
height (in)	xSamples*ySamples heights, indexed y * xSamples + x (m). NaN and infinity are copied unchanged.

HeightMap(
    size_t xSamples,
    int ysamples,
    double xSize,
    double ySize,
    double centerX,
    double centerY,
    const Eigen::VectorXd &heightIn)

Same as the std::vector overload, with the heights in an Eigen vector.

Parameters

Parameter	Description
xSamples (in)	number of samples in x (at least 2)
ysamples (in)	number of samples in y (at least 2)
xSize (in)	size in x (m)
ySize (in)	size in y (m)
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
heightIn (in)	xSamples*ySamples heights, indexed y * xSamples + x (m). NaN and infinity are copied unchanged.

HeightMap(
    double xSize,
    double ySize,
    double centerX,
    double centerY,
    const Eigen::MatrixXd &heightIn)

create a heightmap from a matrix of heights. Matrix rows are x samples and columns are y samples.

Parameters

Parameter	Description
xSize (in)	size in x (m)
ySize (in)	size in y (m)
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
heightIn (in)	heights; heightIn(i, j) is the sample at x index i and y index j (m). NaN and infinity are copied unchanged.

HeightMap(
    double centerX,
    double centerY,
    const TerrainProperties &terrainProperties)

generate a fractal (Perlin) terrain.

Parameters

Parameter	Description
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
terrainProperties (in)	terrain generation parameters (sample counts, size, ...)

~HeightMap

~HeightMap() override

Public member functions

update

void update(
    double centerX,
    double centerY,
    const TerrainProperties &terrainProperties)

Update the existing heightmap with a new terrain properties. The size should be the same. You cannot change the topology. If you want to create a new topology, delete an old one and make a new heightmap. Invalid input is ignored with a warning (the previous state is kept).

Parameters

Parameter	Description
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
terrainProperties (in)	new terrain properties. You cannot change the sample size

void update(
    double centerX,
    double centerY,
    double sizeX,
    double sizeY,
    const std::vector<double> &height)

Update the existing heightmap and rebuild its collision surface. The sample count is fixed; recreate the heightmap to change its topology. Height samples may be NaN or infinity and are copied without filtering. Invalid sample count or geometry leaves the previous state unchanged.

Parameters

Parameter	Description
centerX (in)	x coordinate of the grid center in the heightmap frame (m)
centerY (in)	y coordinate of the grid center in the heightmap frame (m)
sizeX (in)	height map size in the x direction
sizeY (in)	height map size in the y direction
height (in)	height samples, height[y * xSamples + x]; must have exactly xSamples*ySamples values. NaN and infinity samples are copied unchanged.

updateVisualHeight

void updateVisualHeight(
    double centerX,
    double centerY,
    double sizeX,
    double sizeY,
    const std::vector<double> &height)

Update height samples for visualization/server synchronization without rebuilding the contact heightmap used by physics. Call update(...) when collision must be synchronized immediately. Height samples may be NaN or infinity; they are copied without filtering. The center and size must equal the current ones (otherwise the call is ignored with a warning).

Parameters

Parameter	Description
centerX (in)	current grid center x in the heightmap frame (m)
centerY (in)	current grid center y in the heightmap frame (m)
sizeX (in)	current size in x (m)
sizeY (in)	current size in y (m)
height (in)	new height samples, height[y * xSamples + x]; NaN and infinity are copied unchanged

updateVisualHeightPatch

bool updateVisualHeightPatch(
    double centerX,
    double centerY,
    double sizeX,
    double sizeY,
    const std::vector<double> &height,
    double heightOffset,
    size_t minX,
    size_t maxX,
    size_t minY,
    size_t maxY)

Update a rectangular sample patch for visualization without copying/rebuilding the whole heightmap or its contact data. Sample bounds are inclusive and clamped to the grid. Patch samples and resulting values may be NaN or infinity; they are stored without filtering. Samples that keep their value (bit for bit) are not reported as updated.

Parameters

Parameter	Description
centerX (in)	current center x (must match exactly)
centerY (in)	current center y (must match exactly)
sizeX (in)	current size in x (must match exactly)
sizeY (in)	current size in y (must match exactly)
height (in)	full-size height vector (at least xSamples*ySamples, indexed y * xSamples + x); only the patch is read
heightOffset (in)	offset added to every copied sample; non-finite results are retained
minX (in)	first x sample index
maxX (in)	last x sample index
minY (in)	first y sample index
maxY (in)	last y sample index

Returns false (and no change) if the geometry does not match or the patch is empty

init

void init(
    size_t xSamples,
    size_t ysamples,
    double xSize,
    double ySize,
    double centerX,
    double centerY)

Internal: validates the geometry and builds the collision heightmap from the stored heights.

Parameters

Parameter	Description
xSamples (in)	number of samples in x
ysamples (in)	number of samples in y
xSize (in)	size in x (m)
ySize (in)	size in y (m)
centerX (in)	center x (m)
centerY (in)	center y (m)

getHeightMap

const std::vector<double> &getHeightMap() const

PHY-012: read-only access. Editing heights in place bypassed extrema/AABB/collision rebuild and dirty-flagging, yielding stale contacts and out-of-bounds sampling. Use update(...), updateVisualHeight(...), or the patch APIs to modify heights safely.

Returns the (visual) height samples, indexed y * xSamples + x. Same as getHeightVector().

getHeight

double getHeight(double x, double y) const

Get visual height at a given coordinate. After a visual-only update this can intentionally differ from the collision surface. Points outside the map use the nearest edge samples. The orientation is ignored by design: the result is the height of the unrotated heightmap at its current position (see the class description for evaluating a rotated map).

Parameters

Parameter	Description
x (in)	x position in the world frame (m)
y (in)	y position in the world frame (m)

Returns height in the world frame (m)

getContactHeight

double getContactHeight(double x, double y) const

Get the collision-surface height at a given coordinate (same interpolation as getHeight()). Like getHeight(), this ignores the orientation by design.

Parameters

Parameter	Description
x (in)	x position in the world frame (m)
y (in)	y position in the world frame (m)

Returns height in the world frame (m)

getNormal

void getNormal(double x, double y, Vec<3> &normal) const

Get the collision-surface normal at a given coordinate. Like getHeight(), this ignores the orientation by design: the normal is that of the unrotated heightmap (rotate it by the orientation for the world-frame normal of a rotated map).

Parameters

Parameter	Description
x (in)	x position in the world frame (m)
y (in)	y position in the world frame (m)
normal (out)	unit normal of the triangle under (x, y), pointing up (+z side)

destroyCollisionBodies

void destroyCollisionBodies() final

Internal: releases collision bodies before removal.

getXSamples

size_t getXSamples() const

Get the number of points in x direction

Returns the number of points

getYSamples

size_t getYSamples() const

Get the number of points in y direction

Returns the number of points

getXSize

double getXSize() const

Get the size of the heightmap in x direction

Returns the length (m)

getYSize

double getYSize() const

Get the size of the heightmap in y direction

Returns the width (m)

getCenterX

double getCenterX() const

Get the x coordinate of the grid center in the heightmap frame, as given to the constructor or update(). It is the world x of the center only while the heightmap has the identity pose; the world position of the center is getComPosition().

Returns center x in the heightmap frame (m)

getCenterY

double getCenterY() const

Get the y coordinate of the grid center in the heightmap frame (see getCenterX()).

Returns center y in the heightmap frame (m)

getHeightVector

const std::vector<double> &getHeightVector() const

Get the vector of (visual) height values

Returns vector containing height values, indexed y * xSamples + x

getContactHeightVector

const std::vector<double> &getContactHeightVector() const

Returns the height samples of the collision surface (differs from getHeightVector() after a visual-only update).

setUpdatedFalse

void setUpdatedFalse()

Internal: clears the update flags after the server has sent the geometry.

isUpdated

bool isUpdated() const

Get if the height or color is updated (used by the server to resend the geometry)

Returns if the height is updated or not

hasVisualHeightUpdate

bool hasVisualHeightUpdate() const

Returns true if the heights changed since the last setUpdatedFalse().

getVisualDirtyRegion

bool getVisualDirtyRegion(
    size_t &minX,
    size_t &maxX,
    size_t &minY,
    size_t &maxY) const

Get the sample region changed by visual patch updates since the last setUpdatedFalse().

Parameters

Parameter	Description
minX (out)	first dirty x sample
maxX (out)	last dirty x sample
minY (out)	first dirty y sample
maxY (out)	last dirty y sample

Returns false if no region is tracked (nothing changed, or the whole map is dirty)

getHeightRowRevisions

const std::vector<std::uint64_t> &getHeightRowRevisions() const

Revisions of the sample rows, for renderers that refresh only the edited part of the surface. Entry y advances whenever a height in sample row y may have changed. Unlike getVisualDirtyRegion(), the revisions are never cleared, so any number of readers can track them.

Returns one revision per y sample

updateCollision

void updateCollision() final

Internal: synchronizes the collision geometry with the current pose.

updateContactAabbs

void updateContactAabbs() override

Internal: recomputes the world-frame AABBs used by the broadphase.

setPosition

void setPosition(const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &originPosition) final

Move the heightmap frame origin. The grid moves with it, keeping its center (centerX, centerY) in the heightmap frame; z raises all heights.

Parameters

Parameter	Description
originPosition (in)	position of the heightmap frame origin in the world frame (m)

void setPosition(double x, double y, double z) final

Move the heightmap frame origin (see the Eigen overload).

Parameters

Parameter	Description
x (in)	origin x (m)
y (in)	origin y (m)
z (in)	origin z (m)

setOrientation

void setOrientation(const Eigen::Quaterniond &quaternion) final

Set the orientation; the heightmap rotates about its frame origin (getPosition()), like every other object, so a grid centered away from the origin swings around it.

Parameters

Parameter	Description
quaternion (in)	orientation

void setOrientation(const Eigen::Vector4d &quaternion) final

Set the orientation; the heightmap rotates about its frame origin.

Parameters

Parameter	Description
quaternion (in)	orientation (w, x, y, z)

void setOrientation(const Vec<4> &quaternion) final

Set the orientation; the heightmap rotates about its frame origin.

Parameters

Parameter	Description
quaternion (in)	orientation (w, x, y, z)

void setOrientation(double w, double x, double y, double z) final

Set the orientation; the heightmap rotates about its frame origin.

Parameters

Parameter	Description
w (in)	quaternion w
x (in)	quaternion x
y (in)	quaternion y
z (in)	quaternion z

void setOrientation(const Eigen::Matrix3d &rotationMatrix) final

Set the orientation; the heightmap rotates about its frame origin.

Parameters

Parameter	Description
rotationMatrix (in)	orientation (heightmap frame to world)

setColor

void setColor(const std::vector<ColorRGB> &colorLevel)

Set varying color on the heightmap If set, the appearance will be ignored. Set empty vector to the color level to make the appearance active

Parameters

Parameter	Description
colorLevel (in)	per-vertex color values (same size as the height vector, or empty)

setColorPatch

bool setColorPatch(
    const std::vector<ColorRGB> &colorPatch,
    size_t minX,
    size_t maxX,
    size_t minY,
    size_t maxY)

Overwrite a rectangular region of the per-vertex color map (see setColor()). Bounds are inclusive and clamped.

Parameters

Parameter	Description
colorPatch (in)	(maxX-minX+1)*(maxY-minY+1) colors, x fastest
minX (in)	first x sample index
maxX (in)	last x sample index
minY (in)	first y sample index
maxY (in)	last y sample index

Returns false if no full color map is set or the patch size does not match

getColorMap

const std::vector<ColorRGB> &getColorMap() const

Get the whole color vector. If set, the appearance will be ignored in unreal. Unity color map is not supported yet

Returns color

getColor

ColorRGB getColor(double x, double y) const

Returns color of the heightmap at specified point. The color from an RGB camera can be different from this because this is the base color and lighting changes the appearance. Like getHeight(), this ignores the orientation by design.

Parameters

Parameter	Description
x (in)	x position in world coordinates
y (in)	y position in world coordinates

Returns the RGB color

Inherited members

From raisim::SingleBodyObject: clearExternalForcesAndTorques, getAngularVelocity, getAppearance, getBodyToComPosition_rs, getCollisionBody, getCollisionGroup, getCollisionMask, getCom, getComPosition, getComPosition_rs, getContactPointVel, getDOF, getEnergy, getGeneralizedCoordinateDim, getGyroscopicMode, getInertiaMatrix_B, getInertiaMatrix_B_rs, getInertiaMatrix_W, getInertiaMatrix_W_rs, getKineticEnergy, getLinearMomentum, getLinearVelocity, getMass, getObjectType, getOrientation, getPosition, getPotentialEnergy, getQuaternion, getRotationMatrix, getVelocity, integrate, preContactSolverUpdate1, preContactSolverUpdate2, setAngularDamping, setAngularVelocity, setAppearance, setBodyType, setCom, setConstraintForce, setExternalForce, setExternalTorque, setGyroscopicMode, setInertia, setLinearDamping, setLinearVelocity, setMass, setPose, setVelocity

From raisim::Object: addContactToPerObjectContact, clearPerObjectContact, getBodyType, getContactAabb, getContactAabbCount, getContacts, getExternalForce, getExternalForcePosition, getExternalTorque, getExternalTorquePosition, getId, getIndexInWorld, getName, getRenderRevision, Id, lock, lockMutex, setIndexInWorld, setName, try_lock, unlock, unlockMutex