mascaf.visualization

mascaf.visualization.plot_surface_mesh_grid(meshes, grid_shape, *, out_path=None, show=False, center_each=True, auto_rotate_each=True, view_dir=None, parallel_scale_margin=1.08, zoom=1.0, mesh_color=None, colors=None, window_size=None, screenshot_scale=None, background='white', off_screen=None, scale_bar_um=None, pixels_to_um=0.005)[source]

Plot multiple surface meshes on a regular grid with parallel isometric views.

Each cell uses the same orthographic parallel_scale, computed from the largest bounding-sphere radius among prepared meshes, so relative physical size (in the same units) is preserved across panels.

Parameters:

  • meshes (Sequence[Union[str, Trimesh, PolyData]]) – Sequence of paths, trimesh.Trimesh, or pyvista.PolyData.

  • grid_shape (tuple[int, int]) – (n_rows, n_cols). Must satisfy n_rows * n_cols >= len(meshes).

  • out_path (str | None) – If set, save a raster image (extension chooses format, e.g. .png).

  • show (bool) – If True, open an interactive window (forces on-screen rendering).

  • center_each (bool) – Translate each mesh so its vertex centroid is at the origin.

  • auto_rotate_each (bool) – Apply vertex PCA then map 1st/2nd/3rd principal directions to isometric screen up, horizontal, and toward the camera (see module docstring). Skips rotation for nearly spherical point clouds.

  • view_dir (ndarray | None) – Unit vector from the scene origin toward the camera (default matches PyVista’s isometric view: (1,1,1) / ||(1,1,1)||).

  • parallel_scale_margin (float) – Multiplier on the shared orthographic half-height after the largest mesh radius is chosen. Values closer to 1 shrink the empty margin around every panel (meshes look larger and sit visually closer to neighbors). Typical range about 1.0–1.1; below 1 may clip the largest mesh.

  • zoom (float) – Values > 1 zoom in (smaller parallel_scale, e.g. 1.5 is 1.5×). Combine with a lower parallel_scale_margin to reduce white space between panel contents.

  • mesh_color (str | None) – If set, every mesh uses this color (overrides colors).

  • colors (Optional[Sequence[str]]) – Optional color per mesh (named colors or hex). Cycles if shorter than meshes (ignored when mesh_color is set).

  • window_size (tuple[int, int] | None) – (width, height) in pixels for the whole render window before any screenshot_scale enlargement. Increase (e.g. (2400, 2400)) for more pixels per panel at base scale.

  • screenshot_scale (int | None) – Integer ≥ 1. If greater than 1, the render window is enlarged by this factor (window_size × scale) immediately before saving, then a full-size screenshot is taken. This avoids VTK’s WindowToImageFilter scale path, which often leaves the PNG at the original window size on some off-screen / Windows setups. Omitted or 1 keeps window_size as-is.

  • background (str) – Matplotlib-like color string for the render window background.

  • off_screen (bool | None) – If None, off-screen is used when neither show nor out_path is set defaults to False only when show is True; when saving, off-screen is used automatically on headless setups via PyVista.

  • scale_bar_um (float | None) – If set (and out_path is set), draw a black horizontal scale bar and label in the bottom-right of the saved image. Mesh units are pixels; micrometers = pixels × pixels_to_um.

  • pixels_to_um (float) – Conversion from mesh pixel units to micrometers (default 5/1000).

Returns:

The plotter (already shown or screenshotted if requested).

Return type:

Plotter

mascaf.visualization.save_surface_meshes_svg(meshes, *, out_dir, file_stems=None, file_prefix='mesh', start_index=0, center_each=True, auto_rotate_each=True, view_dir=None, parallel_scale_margin=1.08, zoom=1.0, mesh_color=None, colors=None, window_size=None, background='white', off_screen=True)[source]

Save one true-vector SVG file per mesh using the grid camera and framing style.

Parameters:

  • meshes (Sequence[Union[str, Trimesh, PolyData]]) – Meshes to render, one SVG file each.

  • out_dir (str | Path) – Output directory (created if it does not exist).

  • file_stems (Optional[Sequence[str]]) – Filenames without .svg extension, one per mesh. If None, names are generated as {file_prefix}_{index:03d}.svg.

  • file_prefix (str) – Prefix used for auto-generated filenames.

  • start_index (int) – Starting index for auto-generated filenames.

  • **kwargs – Remaining keyword arguments (center_each, auto_rotate_each, view_dir, parallel_scale_margin, zoom, mesh_color, colors, window_size, background, off_screen) are passed through to plot_surface_mesh_grid() unchanged.

  • center_each (bool)

  • auto_rotate_each (bool)

  • view_dir (ndarray | None)

  • parallel_scale_margin (float)

  • zoom (float)

  • mesh_color (str | None)

  • colors (Sequence[str] | None)

  • window_size (tuple[int, int] | None)

  • background (str)

  • off_screen (bool)

Returns:

Paths to each written SVG file, in input order.

Return type:

list[Path]

Raises:

ValueError – If file_stems length does not match len(meshes) or contains an empty string.

mascaf.visualization.save_surface_mesh_grid_svg(meshes, grid_shape, *, out_path, save_individual_meshes=False, individual_out_dir=None, individual_file_stems=None, individual_file_prefix='mesh', individual_start_index=0, center_each=True, auto_rotate_each=True, view_dir=None, parallel_scale_margin=1.08, zoom=1.0, mesh_color=None, colors=None, window_size=None, background='white', off_screen=True)[source]

Save a mesh-grid figure as a true-vector SVG, with optional per-mesh SVGs.

Parameters:

  • meshes (Sequence[Union[str, Trimesh, PolyData]]) – Meshes to render.

  • grid_shape (tuple[int, int]) – (n_rows, n_cols) grid layout.

  • out_path (str | Path) – Destination for the composite grid SVG.

  • save_individual_meshes (bool) – If True, also save one SVG per mesh.

  • individual_out_dir (str | Path | None) – Directory for individual SVGs. Defaults to the same directory as out_path when None.

  • individual_file_stems (Optional[Sequence[str]]) – Filenames (without .svg) for each individual mesh.

  • individual_file_prefix (str) – Prefix used when individual_file_stems is None.

  • individual_start_index (int) – Starting index for auto-generated filenames.

  • **kwargs – Remaining keyword arguments (center_each, auto_rotate_each, view_dir, parallel_scale_margin, zoom, mesh_color, colors, window_size, background, off_screen) are passed through to plot_surface_mesh_grid() unchanged.

  • center_each (bool)

  • auto_rotate_each (bool)

  • view_dir (ndarray | None)

  • parallel_scale_margin (float)

  • zoom (float)

  • mesh_color (str | None)

  • colors (Sequence[str] | None)

  • window_size (tuple[int, int] | None)

  • background (str)

  • off_screen (bool)

Returns:

(grid_svg_path, individual_svg_paths) — the second list is empty unless save_individual_meshes is True.

Return type:

tuple[Path, list[Path]]