meshtsdf

Truncated signed distance field for 3-D regions containing meshes

Since R2024a

Description

The meshtsdf discretizes meshes and stores their associated truncated signed distance fields (TSDF) over a voxelized 3-D space. Voxels that are outside of a mesh contain positive distances and voxels that are inside a mesh have negative distance. Any voxels that are more than a specified truncation distance from meshes have values equal to the truncation distance. Once you create the TSDF, you can modify the poses of meshes and get updated distance and gradient information over the discretized region.

Creation

Syntax

mTSDF = meshtsdf

mTSDF = meshtsdf(meshStruct)

mTSDF = meshtsdf(___,Name=Value)

Description

mTSDF = meshtsdf creates an empty TSDF manager with default properties.

mTSDF = meshtsdf(meshStruct) specifies one or more meshes and computes the signed distance over each meshes truncated region. Use the geom2struct function to convert geometry objects into an array of mesh structures.

mTSDF = meshtsdf(___,Name=Value) specifies properties using one or more name-value arguments in addition to the arguments from other syntaxes. For example, meshtsdf(TruncationDistance=10) sets the truncation distance to 10 meters.

Input Arguments

meshStruct — Geometry mesh structure

structure | N-element structure array

Geometry mesh, specified as a structure or an N-element structure array. N is the total number of collision objects.

Each structure contains these fields:

• ID — ID of the geometry structure stored as a positive integer. By default, the ID of each structure corresponds to the index of the structure in meshStruct. For example, if meshStruct contains five mesh structures, the first mesh structure at index 1 has an ID of 1, and the last mesh structure at index 5 has an ID of 5.

• Vertices — Vertices of the geometry, stored as an M-by-3 matrix. Each row represents a vertex in the form [x y z] with respect to the reference frame defined by Pose. M is the number of vertices needed to represent the convex hull of the mesh.

• Faces — Faces of the geometry, stored as an M-by-3 matrix. Each row contains three indices corresponding to vertices in Vertices that define a triangle faces of the geometry. M is the number of vertices in Vertices.

• Pose — Pose of the geometry as a 4-by-4 homogeneous transformation matrix specifying a transformation from the world frame to the frame in which the vertices are defined.

Data Types: struct

Properties

Resolution — Grid resolution

1 (default) | positive numeric scalar

This property is read-only.

Grid resolution, specified as a positive numeric scalar in cells per meter.

You can only set this property at object construction.

Example: meshtsdf(Resolution=10)

TruncationDistance — Maximum distance to mesh surface

3/Resolution (default) | numeric scalar greater than 3/Resolution

This property is read-only.

Maximum distance to a mesh surface, specified as a numeric scalar greater than 3/Resolution.

For voxels outside of the meshes, if the distance value of a voxel exceeds the value of TruncationDistance, then the distance value of the voxel becomes equal to the value of TruncationDistance.

For voxels inside of a mesh, if the negative distance value of the voxel is lower than -1*TruncationDistance, then the distance value of the voxel becomes equal to -1*TruncationDistance.

You can only set this property at object construction.

Example: meshtsdf(TruncationDistance=0.5)

FillInterior — Distance calculation mode for voxels inside meshes

true (default) | false

This property is read-only.

Distance calculation mode for voxels inside meshes, specified as either true or false:

• "true" — Calculate the negative interior distances from the voxels to the center of the mesh.

• "false" — Calculate negative interior distances to up to a maximum interior distance of -1*TruncationDistance. Voxels that have negative distances that exceed the maximum interior distance are truncated to -1*TruncationDistance.

You can only set this property at object construction.

Example: meshtsdf(FillInterior=false)

MeshID — IDs of meshes in TSDF

empty (default) | N-element vector of nonnegative integers

This property is read-only.

IDs of meshes in the TSDF, stored as an N-element vector of nonnegative integers.

NumMesh — Number of discretized meshes in TSDF

0 (default) | positive integer

This property is read-only.

Number of discretized meshes in the TSDF, stored as a positive integer. The value of NumMesh is equal to the length of meshStruct.

MapLimits — Minimum and maximum limits that contain all active voxels of TSDF

zeros(2,3) (default) | 2-by-3 matrix

This property is read-only.

Minimum and maximum limits that contain all active voxels of the TSDF, stored as an 2-by-3 matrix. The first row represents the minimum x, y, and z limits. The second row represents the maximum x, y, and z limits.

Active voxels are voxels that contain computed distance values.

NumActiveVoxel — Number of active voxels in TSDF

0 (default) | positive integer

This property is read-only.

Number of active voxels in the TSDF, stored as a positive integer.

Active voxels are voxels that contain computed distance values.

Object Functions

activeVoxels	Return information about active voxels
addMesh	Add mesh to mesh TSDF
copy	Deep copy TSDF
removeMesh	Remove mesh from mesh TSDF
distance	Compute distance to zero level set for query points
gradient	Compute gradient of truncated signed distance field
poses	Get poses for one or more meshes in TSDF
updatePose	Update pose of mesh in TSDF
show	Display TSDF in figure

Examples

Add Meshes to Mesh TSDF Manager

Create two collision boxes and one collision sphere. The collision boxes represent a static environment and the sphere represents a dynamic obstacle with a pose that could change at any time.

box1 = collisionBox(0.5,1,0.1);
box2 = collisionBox(0.5,0.1,0.2,Pose=trvec2tform([0 -0.45 0.15]));
sph = collisionSphere(0.125,Pose=trvec2tform([-0.1 0.25 0.75]));
showCollisionArray({box1,box2,sph});
title("Static Environment and Dynamic Obstacle")
v = [110 10];
view(v);

Create a mesh TSDF manager with a resolution of 25 cells per meter.

tsdfs = meshtsdf(Resolution=25);

To improve the efficiency of signed distance field computation, combine meshes that represent the static environment.

staticMeshes = geom2struct({box1,box2});
staticEnv = staticMeshes(1);
staticEnv.Pose = eye(4);
staticEnv.Vertices = [];
staticEnv.Faces = [];
for i = 1:numel(staticMeshes)
    H = staticMeshes(i).Pose;
    V = staticMeshes(i).Vertices*H(1:3,1:3)'+ H(1:3,end)';
    nVert = size(staticEnv.Vertices,1);
    staticEnv.Vertices = [staticEnv.Vertices; V];
    staticEnv.Faces = [staticEnv.Faces; staticMeshes(i).Faces+nVert];
end
staticEnv.ID = 1;

Add the static environment mesh to the TSDF manager.

addMesh(tsdfs,staticEnv);

Convert the sphere collision geometry into a structure for the mesh TSDF manager. Assign it an ID of 2 and add it to the mesh TSDF manager.

obstacleID = 2;
dynamicObstacle = geom2struct(sph,obstacleID);
addMesh(tsdfs,dynamicObstacle);
show(tsdfs)
view(v)
axis equal
title("Mesh TSDFs of Static Environment and Dynamic Obstacle")

Update the pose of the dynamic obstacle in the mesh TSDF manager by changing Pose property of the object handle of the obstacle. Then use the updatePose function to update the pose of the mesh in the TSDF manager.

dynamicObstacle.Pose = trvec2tform([0.2 0.25 0.2]);
updatePose(tsdfs,dynamicObstacle)

ans = 
1

show(tsdfs)
view(v)
axis equal
title("Updated Dynamic Obstacle Pose")

Limitations

• meshtsdf supports packNGo (MATLAB Coder) only for MATLAB^® host targets.

References

[1] Zhao, Hongkai. “A Fast Sweeping Method for Eikonal Equations.” Mathematics of Computation 74, no. 250 (May 21, 2004): 603–27. https://doi.org/10.1090/S0025-5718-04-01678-3.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2024a