Models & Meshes

Modules: superdex.physics.model, superdex.physics.mesh

Prepare geometry before it reaches the engine.

superdex.physics.model

auto_correct

superdex.physics.ModelData) -> None

Apply automatic in-place fixes to the model data, such as normalizing vectors and weights.

Parameters:

data (ModelData) – ModelData to check and possibly modify.

Raises:

Error – If an error occurs.

Type:

auto_correct(data

bake_coordinate_space_transform

superdex.physics.MeshData, from_space: superdex.physics.CoordinateSpace, to_space: superdex.physics.CoordinateSpace) -> None bake_coordinate_space_transform(data: superdex.physics.ModelData, from_space: superdex.physics.CoordinateSpace, to_space: superdex.physics.CoordinateSpace) -> None

Overloaded function.

1. bake_coordinate_space_transform(data: superdex.physics.MeshData, from_space: superdex.physics.CoordinateSpace, to_space: superdex.physics.CoordinateSpace) -> None

Modify the MeshData to convert it from one CoordinateSpace to another.

If the transformation flips handedness, the mesh winding order will also be reversed.

Parameters:

• data (MeshData) – MeshData to modify.

• from_space (CoordinateSpace) – Coordinate space the mesh is currently expressed in.

• to_space (CoordinateSpace) – Coordinate space to convert the mesh to.

Raises:

Error – If an error occurs.

Note

The conversion is exact when units_per_meter is unchanged, because it only permutes and negates axes.

2. bake_coordinate_space_transform(data: superdex.physics.ModelData, from_space: superdex.physics.CoordinateSpace, to_space: superdex.physics.CoordinateSpace) -> None

Modify the ModelData to convert it from one CoordinateSpace to another.

All spatial data within the model will be transformed. If the transformation flips handedness, the winding order of any meshes will be reversed.

Parameters:

• data (ModelData) – ModelData to modify.

• from_space (CoordinateSpace) – Coordinate space the model is currently expressed in.

• to_space (CoordinateSpace) – Coordinate space to convert the model to.

Raises:

Error – If an error occurs.

Note

The conversion is exact when units_per_meter is unchanged, except for orientations stored as a quaternion (implicit box and grid SDF), which cannot represent a 90 degree rotation exactly.

Type:

bake_coordinate_space_transform(data

bake_sdf

superdex.physics.ModelData, params: superdex.physics.GridSdfParams = …) -> None

Compute and bake an SDF grid into the model data.

Computes a signed-distance field (SDF) grid from the model’s mesh (triangular or tetrahedral) and stores it in the model’s sdf field, replacing any existing SDF.

Parameters:

• data (ModelData) – ModelData to modify. Must contain a triangle or tetrahedral mesh.

• params (GridSdfParams) – Parameters to control grid resolution and padding.

Raises:

Error – If an error occurs.

Warning

SDF computation may be slow.

Type:

bake_sdf(data

bake_transform

superdex.physics.ModelData, scale: superdex.physics.Real3 = …, rotation: superdex.physics.Quaternion = …, translation: superdex.physics.Real3 = …) -> None bake_transform(data: superdex.physics.ModelData, scale: superdex.physics.Real3 = …, transform: superdex.physics.TransformRT = …) -> None

Overloaded function.

1. bake_transform(data: superdex.physics.ModelData, scale: superdex.physics.Real3 = ..., rotation: superdex.physics.Quaternion = ..., translation: superdex.physics.Real3 = ...) -> None

Modify the ModelData by applying a scale, rotation, and translation (in that order).

Parameters:

• data (ModelData) – ModelData to modify.

• scale (Real3Like) – Scale to apply (possibly non-uniform, i.e., 3 unequal absolute values).

• rotation (QuaternionLike) – Rotation to apply (quaternion in [x, y, z, w] order).

• translation (Real3Like) – Translation to apply.

Raises:

Error – If an error occurs.

Note

Negative scale can be used to mirror the model. In that case, flip_winding_order() will be called automatically to avoid turning the model inside out.

Note

If element_frame_axes is present, axes are transformed as normal directions using the inverse-transpose of the scale-rotation transform, then normalized. This preserves orthogonality with transformed polyline element tangents under non-uniform scale.

Warning

Some model data cannot bake arbitrary non-uniform scale, resulting in an error.

Warning

Precomputed grid SDF data is preserved only when scale is uniform by absolute value. Non-uniform scale by absolute value discards the precomputed SDF. If an SDF collider later requires SDF data, Mochi regenerates the SDF from the transformed mesh at runtime, which may be expensive.

2. bake_transform(data: superdex.physics.ModelData, scale: superdex.physics.Real3 = ..., transform: superdex.physics.TransformRT = ...) -> None

Modify the ModelData by applying a scale, rotation, and translation (in that order).

Takes a combined TransformRT instead of separate rotation and translation.

Parameters:

• data (ModelData) – ModelData to modify.

• scale (Real3Like) – Scale to apply (possibly non-uniform, i.e., 3 unequal absolute values).

• transform (TransformRT) – Combined rotation and translation to apply.

Raises:

Error – If an error occurs.

Note

Negative scale can be used to mirror the model. In that case, flip_winding_order() will be called automatically to avoid turning the model inside out.

Note

If element_frame_axes is present, axes are transformed as normal directions using the inverse-transpose of the scale-rotation transform, then normalized. This preserves orthogonality with transformed polyline element tangents under non-uniform scale.

Warning

Some model data cannot bake arbitrary non-uniform scale, resulting in an error.

Warning

Precomputed grid SDF data is preserved only when scale is uniform by absolute value. Non-uniform scale by absolute value discards the precomputed SDF. If an SDF collider later requires SDF data, Mochi regenerates the SDF from the transformed mesh at runtime, which may be expensive.

Type:

bake_transform(data

flip_winding_order

superdex.physics.MeshData) -> None flip_winding_order(data: superdex.physics.ModelData) -> None

Overloaded function.

1. flip_winding_order(data: superdex.physics.MeshData) -> None

Flip mesh winding order by swapping the connectivity indices within each element.

Parameters:

data (MeshData) – MeshData to modify.

Raises:

Error – If an error occurs.

2. flip_winding_order(data: superdex.physics.ModelData) -> None

Flip mesh winding order by swapping the connectivity indices within each element.

Operates on the simulation mesh (mesh), visual mesh (visual_mesh), and contact skin (contact_skin_mesh) when present. Implicit shapes and SDF data are not modified.

Parameters:

data (ModelData) – ModelData to modify.

Raises:

Error – If an error occurs.

Type:

flip_winding_order(data

load_from_bytes

Span[str]) -> superdex.physics.ModelData load_from_bytes(data: Span[str], format: superdex.physics.MeshFileType) -> superdex.physics.ModelData

Overloaded function.

1. load_from_bytes(data: Span[str]) -> superdex.physics.ModelData

Convenience overload using LEGACY.

Parameters:

data (ArrayLikeChar) – File contents in memory.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

2. load_from_bytes(data: Span[str], format: superdex.physics.MeshFileType) -> superdex.physics.ModelData

Load model data from a file in memory. Then, auto_correct() and validate() will be called automatically.

Parameters:

• data (ArrayLikeChar) – File contents in memory.

• format (MeshFileType | int) – Mesh file format hint. When LEGACY (the default), auto-detects between HDF5 and JSON via header bytes. When a surface mesh format (PLY, OFF, STL, OBJ), dispatches directly to that reader.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

Type:

load_from_bytes(data

load_from_bytes_unchecked

Span[str]) -> superdex.physics.ModelData load_from_bytes_unchecked(data: Span[str], format: superdex.physics.MeshFileType) -> superdex.physics.ModelData

Overloaded function.

1. load_from_bytes_unchecked(data: Span[str]) -> superdex.physics.ModelData

Convenience overload using LEGACY.

Parameters:

data (ArrayLikeChar) – File contents in memory.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

2. load_from_bytes_unchecked(data: Span[str], format: superdex.physics.MeshFileType) -> superdex.physics.ModelData

Load model data from a file in memory without calling auto_correct() nor validate(). Can be used to load a model that is not currently in a valid state.

Parameters:

• data (ArrayLikeChar) – File contents in memory.

• format (MeshFileType | int) – Mesh file format hint. When LEGACY (the default), auto-detects between HDF5 and JSON via header bytes. When a surface mesh format (PLY, OFF, STL, OBJ), dispatches directly to that reader.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

Type:

load_from_bytes_unchecked(data

load_from_file

str) -> superdex.physics.ModelData

Load model data from a file. Then, auto_correct() and validate() will be called automatically.

Supported formats: JSON (.mochi.json), HDF5 (.mochi.h5), OBJ (.obj), OFF (.off), PLY (.ply), and STL (.stl).

Parameters:

path (str) – File path to load.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

Type:

load_from_file(path

load_from_file_unchecked

str) -> superdex.physics.ModelData

Load model data from a file without calling auto_correct() nor validate(). Can be used to load a model that is not currently in a valid state.

Supported formats: JSON (.mochi.json), HDF5 (.mochi.h5), OBJ (.obj), OFF (.off), PLY (.ply), and STL (.stl).

Parameters:

path (str) – File path to load.

Returns:

ModelData that was loaded.

Raises:

Error – If an error occurs.

Type:

load_from_file_unchecked(path

save_to_file

superdex.physics.ModelData, path: str, format: superdex.physics.FileFormat) -> None save_to_file(data: superdex.physics.ModelDataView, path: str, format: superdex.physics.FileFormat) -> None

Overloaded function.

1. save_to_file(data: superdex.physics.ModelData, path: str, format: superdex.physics.FileFormat) -> None

Save a model to a file of the specified format.

Parameters:

• data (ModelData) – Model data to write.

• path (str) – File path to write.

• format (FileFormat | int) – File format to write.

Raises:

Error – If an error occurs.

Note

Creates the destination directories if necessary.

Warning

Some model files contain additional data for experimental features (e.g. ROMs), which cannot be represented by the ModelData struct. That data will be lost if you use the ModelData struct to save over the original file.

2. save_to_file(data: superdex.physics.ModelDataView, path: str, format: superdex.physics.FileFormat) -> None

Save a model to a file of the specified format.

Parameters:

• data (ModelDataView) – A non-owning view of the model data to write.

• path (str) – File path to write.

• format (FileFormat | int) – File format to write.

Raises:

Error – If an error occurs.

Note

Creates the destination directories if necessary.

Warning

Some model files contain additional data for experimental features (e.g. ROMs), which cannot be represented by the ModelData struct. That data will be lost if you use the ModelData struct to save over the original file.

Type:

save_to_file(data

save_to_json_string

superdex.physics.ModelData) -> str

Save a model to a JSON string in memory.

Parameters:

data (ModelData) – Model data to serialize.

Returns:

JSON string containing the model data.

Raises:

Error – If an error occurs.

Type:

save_to_json_string(data

validate

superdex.physics.ModelDataView) -> None

Check the model for errors.

Parameters:

data (ModelDataView) – Non-owning view of the model data to check.

Raises:

Error – If an error occurs.

Type:

validate(data

superdex.physics.mesh

SuperDex Physics mesh-processing operations.

Provides surface remeshing, mesh statistics, and SDF isosurface reconstruction.

Mochi mesh processing operations (heavy geometry runs in the superdex_mesh_cli helper)

ACVD

ALPHA_WRAP

class DistributionStatistics

Bases: object

property max

(self) -> float

property mean

(self) -> float

property min

(self) -> float

property standard_deviation

(self) -> float

class Error

Bases: RuntimeError

class MeshStatistics

Bases: object

property angles

(self) -> superdex.physics.mesh.DistributionStatistics

property edge_lengths

(self) -> superdex.physics.mesh.DistributionStatistics

property hausdorff_distance

(self) -> float

property is_closed

(self) -> bool

property num_faces

(self) -> int

property num_vertices

(self) -> int

NONE

class RemeshMethod(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

SURFACE_DELAUNAY

class SurfaceRemeshingParams(*args, **kwargs)

Bases: object

property acvd_gradation_factor

(self) -> float

property adaptive_sizing_tolerance

(self) -> float

property alpha_wrap_relative_alpha

(self) -> float

property alpha_wrap_relative_offset

(self) -> float

property angle_smoothing_iterations

(self) -> int

property detect_features

(self) -> bool

property edge_size

(self) -> float

property facet_angle_bound

(self) -> float

property facet_distance_bound

(self) -> float

property max_edge_size_factor

(self) -> float

property method

(self) -> superdex.physics.mesh.RemeshMethod

property min_edge_size_factor

(self) -> float

property protect_constraints

(self) -> bool

property relative_to_mesh_size

(self) -> bool

property relax_constraints

(self) -> bool

property relaxation_steps_per_iteration

(self) -> int

property repair_mesh

(self) -> bool

property sharp_feature_angle

(self) -> float

property smoothing_iterations

(self) -> int

property tangential_relaxation_iterations

(self) -> int

property target_vertex_count

(self) -> int

property use_adaptive_sizing

(self) -> bool

compute_mesh_statistics

numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False], faces: numpy.ndarray[dtype=int32, order=’C’, device=’cpu’, writable=False], ref_vertices: numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False] | None = None, ref_faces: numpy.ndarray[dtype=int32, order=’C’, device=’cpu’, writable=False] | None = None) -> superdex.physics.mesh.MeshStatistics

Compute quality statistics for a triangle surface mesh.

Parameters:

• vertices – (N, 3) array of vertex coordinates

• faces – (M, 3) array of triangle vertex indices

• ref_vertices – Optional (N, 3) reference mesh vertices for Hausdorff distance

• ref_faces – Optional (M, 3) reference mesh faces for Hausdorff distance

Returns:

MeshStatistics object with edge_lengths, angles, and hausdorff_distance

Type:

compute_mesh_statistics(vertices

reconstruct_surface_from_sdf

numpy.ndarray[dtype=int32, order=’C’, device=’cpu’, writable=False], values: numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False], bounds_min: numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False], bounds_max: numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False]) -> tuple

Reconstruct a triangle mesh from a grid SDF using Marching Cubes.

Parameters:

• dims – (3,) integer array of grid dimensions [x, y, z]

• values – Flat float array of SDF values in x-slowest, z-fastest order (index = dims[1]*dims[2]*x + dims[2]*y + z, size = dims[0]*dims[1]*dims[2])

• bounds_min – (3,) float array of grid minimum bounds

• bounds_max – (3,) float array of grid maximum bounds

Returns:

Tuple of (vertices, faces) numpy arrays

Type:

reconstruct_surface_from_sdf(dims

remesh_surface

numpy.ndarray[dtype=float32, order=’C’, device=’cpu’, writable=False], faces: numpy.ndarray[dtype=int32, order=’C’, device=’cpu’, writable=False], params: superdex.physics.mesh.SurfaceRemeshingParams = <superdex.physics.mesh.SurfaceRemeshingParams object>) -> tuple

Remesh a triangular surface mesh.

Parameters:

• vertices – (N, 3) array of vertex coordinates

• faces – (M, 3) array of triangle vertex indices

• params – SurfaceRemeshingParams

Returns:

Tuple of (vertices, faces) numpy arrays

Type:

remesh_surface(vertices