mascaf.mesh

Main mesh class

mascaf.mesh.example_mesh(kind='cylinder', *, radius=1, height=10, sections=16, major_radius=4, minor_radius=1, major_sections=32, minor_sections=16, **kwargs)

Create a simple demo mesh using trimesh primitives.

Parameters:

• kind (str) – Type of primitive to generate. Default “cylinder”.

• radius (float) – Cylinder radius (when kind=”cylinder”). Default 1.

• height (float) – Cylinder height (when kind=”cylinder”). Default 10.

• sections (int | None) – Cylinder radial resolution (pie wedges). Default 16.

• major_radius (float) – Torus major radius (center of hole to centerline of tube). Default 4.

• minor_radius (float) – Torus minor radius (tube radius). Default 1.

• major_sections (int | None) – Torus resolution around major circle. Default 32.

• minor_sections (int | None) – Torus resolution around tube section. Default 16.

• **kwargs (dict) – Passed through to Trimesh constructor via trimesh.creation.* helpers (e.g., process=False).

Returns:

Generated primitive mesh.

Return type:

Trimesh

Examples

>>> m = example_mesh("cylinder", radius=0.4, height=1.5)
>>> t = example_mesh("torus", major_radius=1.0, minor_radius=0.25)

class mascaf.mesh.MeshManager(mesh=None, mesh_path=None, verbose=True)

Bases: object

Unified mesh class handling loading, processing, and analysis of triangle meshes.

Wraps a trimesh.Trimesh with convenience methods for loading, saving, copying, and analyzing mesh geometry. Loading can be deferred by passing a mesh_path to the constructor or by calling load_mesh() directly.

Parameters:

• mesh (Optional[Trimesh]) – An already-loaded mesh to wrap. Either this or mesh_path must be provided.

• mesh_path (Optional[str]) – Path to a mesh file. If provided, load_mesh() is called immediately during construction.

• verbose (bool) – If True, log informational messages when loading.

Examples

>>> mgr = MeshManager(mesh_path="neuron.obj")
>>> mgr.bounding_box_diagonal()

__init__(mesh=None, mesh_path=None, verbose=True)

Parameters:

• mesh (Trimesh | None)

• mesh_path (str | None)

• verbose (bool)

load_mesh(filepath, file_format=None)

Load a mesh from file and store it as mesh.

Parameters:

• filepath (str) – Path to the mesh file.

• file_format (Optional[str]) – Format hint (e.g. "obj"). Auto-detected from the file extension when None.

Returns:

The loaded mesh (also stored as self.mesh).

Return type:

Trimesh

Raises:

ValueError – If the file cannot be loaded or does not contain a single mesh.

save(filepath, file_format='obj')

Export the mesh to a file.

Parameters:

• filepath (str) – Destination file path.

• file_format (str) – Format string understood by trimesh.Trimesh.export.

Return type:

None

copy()

Return a new MeshManager wrapping a deep copy of the mesh.

Return type:

MeshManager

to_trimesh()

Return the underlying trimesh.Trimesh object.

Return type:

Trimesh

bounding_box_diagonal()

Return the length of the bounding box space diagonal.

Computed as the Euclidean distance between the minimum and maximum corners of the axis-aligned bounding box of the mesh. Useful as a scale reference when choosing max_edge_length for FitOptions.

Returns:

Length of the bounding box diagonal.

Return type:

float

analyze_mesh()

Analyze mesh properties for diagnostic purposes without modifying the mesh.

Returns:

Dictionary with keys: face_count, vertex_count, bounds, is_watertight, is_winding_consistent, volume, is_manifold, euler_characteristic, genus, normal_stats, and issues (list of warning strings).

Return type:

dict

print_mesh_analysis(verbose=False)

Analyze a mesh and print a formatted report of its properties.

Return type:

None

Parameters:

verbose (bool)

Args:

verbose: Whether to print detailed information

repair_mesh(fix_holes=True, remove_duplicates=True, fix_normals=True, remove_degenerate=True, fix_negative_volume=True, keep_largest_component=False, verbose=True)

Attempt to repair common mesh issues to improve watertightness and quality.

Return type:

Trimesh

Parameters:

• fix_holes (bool)

• remove_duplicates (bool)

• fix_normals (bool)

• remove_degenerate (bool)

• fix_negative_volume (bool)

• keep_largest_component (bool)

• verbose (bool)

Args:

mesh_data: Either a Trimesh object or (vertices, faces) tuple fix_holes: Whether to attempt filling holes remove_duplicates: Whether to remove duplicate faces and vertices fix_normals: Whether to fix face normal consistency remove_degenerate: Whether to remove degenerate faces fix_negative_volume: Whether to invert faces if mesh has negative volume keep_largest_component: Whether to keep only the largest connected component verbose: Whether to print repair summary

Returns:

Repaired mesh (new copy, original is not modified)

visualize_mesh_3d(title='3D Mesh Visualization', color='lightblue', backend='auto', show_axes=True, show_wireframe=False, width=800, height=600, *, eye_scale=1.25, skel=None, skel_color='crimson', skel_line_width=3.0, skel_opacity=0.95)

Create a 3D visualization of a mesh.

Return type:

Optional[object]

Parameters:

• title (str)

• color (str)

• backend (str)

• show_axes (bool)

• show_wireframe (bool)

• width (int)

• height (int)

• eye_scale (float)

• skel (SkeletonGraph | List[SkeletonGraph] | None)

• skel_color (str | List[str])

• skel_line_width (float)

• skel_opacity (float)

Args:

title: Plot title color: Mesh color (named color or RGB tuple) backend: Visualization backend (‘plotly’ or ‘matplotlib’) show_axes: Whether to show coordinate axes show_wireframe: Whether to show wireframe overlay skel: Optional SkeletonGraph or list of SkeletonGraph to overlay as 3D lines skel_color: Color(s) for skeleton overlay. Can be a single color or list of colors (one per skeleton) skel_line_width: Line width for skeleton overlay skel_opacity: Opacity for skeleton overlay (plotly only)

Returns:

Figure object (backend-dependent) or None if visualization fails

visualize_mesh_slice_interactive(title='Interactive Mesh Slice', z_range=None, num_slices=50, slice_color='red', mesh_color='lightblue', mesh_opacity=0.3)

Create an interactive 3D visualization of a mesh with a controllable slice plane.

This function displays a 3D mesh and calculates the intersection of the mesh with an xy-plane at a user-controlled z-value. The intersection is shown as a colored line on the mesh. A slider allows the user to interactively change the z-value of the intersection plane.

Return type:

Optional[object]

Parameters:

• title (str)

• z_range (Tuple[float, float] | None)

• num_slices (int)

• slice_color (str)

• mesh_color (str)

• mesh_opacity (float)

Args:

title: Plot title z_range: Tuple of (min_z, max_z) for slice range. Auto-detected if None. num_slices: Number of positions for the slider slice_color: Color for the intersection line mesh_color: Color for the 3D mesh mesh_opacity: Opacity of the 3D mesh (0-1)

Returns:

Plotly figure with interactive slider for controlling the z-value