mascaf.basis_optimizer

MorphologyGraph basis optimization prior to radius fitting.

class mascaf.basis_optimizer.BasisOptimizerOptions(do_pruning=False, pruning_min_length=None, pruning_min_length_fraction=None, pruning_iterative=True, do_snapping=True, do_forcing=True, snap_distance_multiplier=1.1, max_iterations=100, step_size=0.1, convergence_threshold=0.0001, preserve_terminal_nodes=True, preserve_branch_nodes=False, n_rays=6, fallback_distance=10.0, smoothing_weight=0.5, verbose=False)

Bases: object

Configuration for morphology-basis optimization.

All fields are keyword arguments to the dataclass constructor; see each field’s inline annotation for defaults and semantics.

Parameters:

• do_pruning (bool)

• pruning_min_length (float | None)

• pruning_min_length_fraction (float | None)

• pruning_iterative (bool)

• do_snapping (bool)

• do_forcing (bool)

• snap_distance_multiplier (float)

• max_iterations (int)

• step_size (float)

• convergence_threshold (float)

• preserve_terminal_nodes (bool)

• preserve_branch_nodes (bool)

• n_rays (int)

• fallback_distance (float)

• smoothing_weight (float)

• verbose (bool)

do_pruning: bool = False

pruning_min_length: float | None = None

pruning_min_length_fraction: float | None = None

pruning_iterative: bool = True

do_snapping: bool = True

do_forcing: bool = True

snap_distance_multiplier: float = 1.1

max_iterations: int = 100

step_size: float = 0.1

convergence_threshold: float = 0.0001

preserve_terminal_nodes: bool = True

preserve_branch_nodes: bool = False

n_rays: int = 6

fallback_distance: float = 10.0

smoothing_weight: float = 0.5

verbose: bool = False

__init__(do_pruning=False, pruning_min_length=None, pruning_min_length_fraction=None, pruning_iterative=True, do_snapping=True, do_forcing=True, snap_distance_multiplier=1.1, max_iterations=100, step_size=0.1, convergence_threshold=0.0001, preserve_terminal_nodes=True, preserve_branch_nodes=False, n_rays=6, fallback_distance=10.0, smoothing_weight=0.5, verbose=False)

Parameters:

• do_pruning (bool)

• pruning_min_length (float | None)

• pruning_min_length_fraction (float | None)

• pruning_iterative (bool)

• do_snapping (bool)

• do_forcing (bool)

• snap_distance_multiplier (float)

• max_iterations (int)

• step_size (float)

• convergence_threshold (float)

• preserve_terminal_nodes (bool)

• preserve_branch_nodes (bool)

• n_rays (int)

• fallback_distance (float)

• smoothing_weight (float)

• verbose (bool)

Return type:

None

class mascaf.basis_optimizer.BasisOptimizer(graph, mesh, options=None)

Bases: object

Optimize a downsampled MorphologyGraph basis against a target mesh.

Runs up to three sequential phases controlled by BasisOptimizerOptions:

1. Pruning — remove short terminal branches.

2. Snapping — move outside nodes back inside the mesh.

3. Forcing — iteratively pull nodes toward the medial axis.

Parameters:

• graph (MorphologyGraph) – The morphology basis to optimize. A deep copy is made internally so the original is not modified.

• mesh (Trimesh) – The target mesh that defines the interior/exterior and surface.

• options (Optional[BasisOptimizerOptions]) – Optimization configuration. Defaults to BasisOptimizerOptions with all defaults when None.

Examples

>>> from mascaf import BasisOptimizer, BasisOptimizerOptions
>>> opts = BasisOptimizerOptions(do_snapping=True, do_forcing=True)
>>> optimized = BasisOptimizer(morphology, mesh, opts).optimize()

__init__(graph, mesh, options=None)

Parameters:

• graph (MorphologyGraph)

• mesh (Trimesh)

• options (BasisOptimizerOptions | None)

get_outside_nodes()

Identify graph nodes that lie outside the mesh surface.

Returns:

(outside_node_ids, has_crossing, num_outside, max_dist) where:

• outside_node_ids — list of node IDs outside the mesh.

• has_crossing — True if any node is outside.

• num_outside — count of outside nodes.

• max_dist — maximum distance from any outside node to the nearest mesh surface point.

Return type:

Tuple[list[int], bool, int, float]

optimize()

Run the configured optimization phases and return the result.

Runs pruning, snapping, and forcing in sequence (each phase is skipped when its corresponding do_* flag is False).

Returns:

The optimized morphology basis (a modified copy of the input).

Return type:

MorphologyGraph

get_optimization_stats()

Return summary statistics for the optimized basis graph.

Return type:

dict