Main Content

meshtsdf

Truncated signed distance field for 3-D regions containing meshes

Since R2024a

expand all in page

    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. After you create the TSDF, you can modify the poses and vertices 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.

    example

    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=0.5) sets the truncation distance to 0.5 meters.

    Input Arguments

    expand all

    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

    expand all

    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)

    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)

    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)

    This property is read-only.

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

    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.

    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.

    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

    activeVoxelsReturn information about active voxels
    addMeshAdd mesh to mesh TSDF
    copyDeep copy TSDF
    removeMeshRemove mesh from mesh TSDF
    distanceCompute distance to zero level set for query points
    gradientCompute gradient of truncated signed distance field
    posesGet poses for one or more meshes in TSDF
    updatePoseUpdate pose of mesh in TSDF
    showDisplay TSDF in figure

    Examples

    collapse all

    Open Live Script

    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 40 cells per meter and a truncation distance of 0.1 meters.

    tsdfs = meshtsdf(Resolution=40,TruncationDistance=0.1);

    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

    See Also

    Topics