routing.core.core

Core classes for routing.

class routing.core.core.Alternative(grid_path: GridPath, refinements: list[Refinement], input_port: Port | None = None, output_port: Port | None = None, name: str = '')

Bases: DessiaObject, Displayable3D

One route of a Solution: its generated path, the two ports it joins, and the optimizer’s refinements of it.

A Solution holds one alternative per route the search produced (k shortest paths, tap sites); the alternatives of one solution may end on different ports.

Parameters:

• grid_path – The generated path of this alternative.

• refinements – The successive refinements the optimizer made of the path.

• input_port – The port the alternative leaves from, built and equipped by the Solution.

• output_port – The port the alternative reaches, built and equipped by the Solution.

• name – The name to identify this alternative. Defaults to ‘’.

static best_optimized_pipe(optimized_pipes: list[Refinement]) → Refinement | None

Call best_refinement; best_optimized_pipe is its deprecated name.

property best_pipe: Refinement | None

The cheapest refinement the checks accepted, None before any optimization or when they all failed.

static best_refinement(refinements: list[Refinement]) → Refinement | None

Return the cheapest of refinements, the last one on a tie; None for none.

classmethod dict_to_object(dict_: dict[str, Any], force_generic: bool = False, global_dict: dict | None = None, pointers_memo: dict[str, Any] | None = None, path: str = '#') → Alternative

Rebuild the alternative; a dict stored before v3 names its refinements optimized_pipes.

property optimized_pipes: list[Refinement]

Deprecated name of refinements.

plot_data(reference_path: str = '#', **kwargs)

Specific display tag for PlotData. Add a picture argument.

to_samples(init_index: int = 1, reference_path: str = '#') → list[Sample]

Get plot_data Samples from all Refinement.

volmdlr_primitives(name: str = '')

class routing.core.core.GridPath(path: list[SmartGridNode], pipe: Pipe | None = None, cost: float = 0.0, indicators: dict[str, Any] | None = None, runs: int = 0, runtime: float = 0.0, states: list[PathState] | None = None, name: str = '')

Bases: DessiaObject

A class representing a routing path through the voxel grid with associated metadata.

This class inherits from DessiaObject, and contains a sequence of grid nodes forming a path from start to end, along with the corresponding Pipe object, cost metrics, and routing indicators.

Parameters:

• path – The list of SmartGridNode objects forming the routing path.

• pipe – The optional Pipe object representing the path geometry. If None, can be created later using to_pipe() method. Defaults to None.

• cost – The total cost of the path (lower is better). Used for ranking multiple path options. Defaults to 0.0.

• indicators – The optional dictionary of routing metrics and indicators. Defaults to None.

• runs – The number of pathfinding iterations/runs that generated this path. Defaults to 0.

• runtime – The time taken to compute the path in seconds. Defaults to 0.0.

• states – The state the path carries at each node (PathState), read off the nodes when the path was found: the nodes themselves are the grid’s, rewritten by every later search.

• name – The name to identify this path. Defaults to ‘’.

classmethod dict_to_object(dict_: dict[str, Any], **kwargs) → SerializableObject

Deserialize a dictionary to a GridPath object.

Reconstructs a GridPath from its serialized dictionary representation, including path nodes, pipe geometry, and all metadata.

Parameters:

• dict – Serializable dictionary containing GridPath data.

• kwargs – Additional keyword arguments for deserialization.

Returns:

Reconstructed GridPath object.

classmethod from_grid_result(path: list[SmartGridNode], cost: float, indicators: dict[str, list[tuple[int, int, int]]], runs: int, runtime: float, input_port: Port, output_port: Port, pipe_type: PipeType) → GridPath

Build the path the search found: its pipe through the cells, and the state its nodes carry.

The pipe runs port, cells, port: the first and last cells host the port extensions, so a route of two cells is port, extension, extension, port. The state is the one write_found_path laid on the nodes.

property is_direct: bool

Check if the path is direct (no intermediate waypoints).

A direct path has only 2 nodes (start and end), indicating a straight connection without turns.

Returns:

True if path is direct, False otherwise.

light_str() → str

Get compact string representation of GridPath.

Returns a shorter string showing only start and end nodes, cost, length, runs, runtime, and indicators.

Returns:

Compact string representation of the GridPath.

static nodes_to_points(nodes: list[GridNode]) → list[Point3D]

Convert a node path to waypoints: the corners of its cell-centre polyline, one junction per realignment.

The short runs made only to reach a centred gateway (_realignments()) are replaced by the single point joining the straight runs on either side (_junction()); a run so tilted is one segment.

path_to_points() → list[Point3D]

Waypoints of the path, see nodes_to_points().

string_indicators() → str

Get formatted string representation of routing indicators.

Formats all indicators in the indicators dictionary as a multi-line string for display in string representations.

Returns:

Formatted string containing all indicators and their values.

to_dict(use_pointers: bool = True, memo=None, path: str = '#', id_method=True, id_memo=None, **kwargs) → dict[str, Any]

Convert the GridPath object to a serializable dictionary.

Serializes the GridPath to a JSON-compatible dictionary format, including path node identifiers, pipe geometry, cost, indicators, and metadata.

Parameters:

• use_pointers – Flag to use object pointers in serialization. Defaults to True.

• memo – Memoization dictionary for circular reference handling.

• path – JSON path string for nested serialization.

• id_method – Flag to use identifier method. Defaults to True.

• id_memo – Memoization dictionary for identifiers.

• kwargs – Additional keyword arguments for serialization.

Returns:

Serializable dictionary representation of the GridPath.

to_pipe(input_port: Port, output_port: Port, pipe_type: PipeType) → Pipe

Generate Pipe from GridPath.

Creates a Pipe object from the grid path, connecting input and output ports with the path waypoints.

Parameters:

• input_port – Start port of the pipe

• output_port – End port of the pipe

• pipe_type – PipeType defining pipe characteristics

Returns:

Pipe instance representing the routed path

to_pipe_lines() → list[PipeLine]

Convert the routed path to PipeLines, one per straight run of cell centres, from port to port.

Packs, the optimizer and the indicators read the path as the router laid it on the lattice; the junctions of nodes_to_points() belong to the pipe alone.

to_samples(index: int, reference_path: str = '#') → Sample

Get plot_data equivalent Sample.

volmdlr_primitives(name: str = '') → list[Primitive3D]

Get volmdlr primitives representing this grid path.

Returns the 3D geometric primitives from the associated pipe, with an optional name applied to all primitives.

Parameters:

name – Optional name to assign to all primitives. Defaults to ‘’.

Returns:

List of Primitive3D objects representing the path geometry.

class routing.core.core.PathState(direction: tuple[int, int, int] | None, straight_length: int, lengths: dict[str, int])

Bases: NamedTuple

The state a path carries at one of its nodes, as the search derived it.

The direction the path arrived with, how far it has run straight, and its attribute lengths (<attribute>, no_<attribute>, visited_<attribute>), all in cells of the node’s grid.

classmethod at(node: SmartGridNode) → PathState

Read the state node carries, laid there by the replay of its path (write_found_path).

direction: tuple[int, int, int] | None

Alias for field number 0

lengths: dict[str, int]

Alias for field number 2

straight_length: int

Alias for field number 1

class routing.core.core.Pipe(wire: Wire, pipe_type: PipeType = None, points: list[Point3D] | None = None, mutualization_pipe_type: MutualizationPipeType = None, radius_curvature_dico: list[RadiusCurvaturePipe] | None = None, name: str = '')

Bases: Pipe, Displayable3D

A class representing a complete pipe with 3D path and properties.

This class inherits from piping.Pipe, and extends it with routing-specific functionality. It represents a complete pipe path defined by waypoints, with associated pipe type and routing metadata.

Parameters:

• wire – The Wire object defining the 3D path of the pipe.

• pipe_type – The PipeType defining characteristics and constraints. Defaults to None.

• points – The optional list of 3D waypoints. If provided, used for path representation. Defaults to None.

• mutualization_pipe_type – The optional mutualization pipe type for shared routing. Defaults to None.

• radius_curvature_dico – The optional list of radius curvature definitions for variable curvature along the path. Defaults to None.

• name – The name identifying this pipe. Defaults to ‘’.

static build_end_frames(ports: PortCouple) → tuple[ndarray, ndarray]

Build coordinate frames at the pipe’s ends with port direction as main vector.

Creates transformation frames at both start and end ports, where the z-axis is aligned with the port’s orientation direction. These frames are used for optimization and geometric operations.

Parameters:

ports – PortCouple containing start and end ports.

Returns:

Tuple of (start_frame, end_frame) as 4x4 transformation matrices.

distance_to_voxels(room_voxels: RoutingVoxelization) → ndarray

Calculate distances from voxel centers to pipe centerline.

Calculates the signed distance from each voxel center to the pipe centerline. Returns a distance matrix where values represent how far each voxel is from the pipe, with negative values indicating voxels inside the pipe radius.

Parameters:

room_voxels – RoutingVoxelization containing the voxel grid.

Returns:

Distance matrix of same shape as room_voxels.matrix, with distances from each voxel center to the pipe. Values are adjusted to account for pipe radius (negative distances inside pipe are set to 0).

classmethod from_optimizer(points: list[Point3D], pipe_type: PipeType, tol: float = 0.01) → Pipe

Create a Pipe from optimizer output points.

Creates a Pipe from points (typically from optimization), removing duplicates and using the pipe type’s name.

Parameters:

• points – List of 3D waypoints from optimizer

• pipe_type – PipeType defining pipe characteristics

• tol – Tolerance for removing duplicate points

Returns:

Pipe instance with cleaned path

classmethod from_points(points: list[Point3D], pipe_type: PipeType, name: str = '') → Pipe

Create a Pipe from a list of points and pipe type.

Creates a Pipe by building a Wire from the points and associating it with the given pipe type. Validates curvature constraints.

Parameters:

• points – List of 3D waypoints defining the pipe path

• pipe_type – PipeType defining pipe characteristics

• name – Name for the pipe

Returns:

Pipe instance with validated curvature

get_wire_points() → ndarray

Get points of equivalent Wire as numpy array.

Extracts all waypoints from the pipe’s wire path and converts them to a numpy array format for numerical operations.

Returns:

Array of shape (n_points, 3) containing (x, y, z) coordinates of waypoints.

static global_parameters(interior_points: ndarray, port_couple: PortCouple) → tuple[ndarray, ndarray, tuple[ndarray, ndarray]]

Parametrize interior_points for the global 3D optimizer.

The first point is its extension length along the input port axis, the last its extension length along the output port axis, the points between them their three coordinates.

static remove_duplicated_nodes(points: list[Point3D], tol: float = 0.01) → list[Point3D]

Remove duplicate points from a pipe path.

Removes points that are within tolerance distance from the previous point, simplifying the path while preserving its shape.

Parameters:

• points – List of 3D waypoints

• tol – Tolerance distance for considering points as duplicates

Returns:

List of points with duplicates removed

to_3d_global_parameters(port_couple: PortCouple) → tuple[ndarray, ndarray, tuple[ndarray, ndarray]]

From turn points to an array of variable for optimizing in global 3d context.

Converts the pipe’s turn points into a flattened array format suitable for 3D global optimization. Points are 3-component vectors, where initial_values for the 3D global optimizer is a flattened array built as follows: [input port extension length, X2, Y2, Z2, …, Xn-1, Yn-1, Zn-1, output port extension length] where n is the number of points that are not ports. Port extensions are the length of vectors (input port, input extension) and (output extension, output port) along the port direction vector.

Parameters:

port_couple – PortCouple defining the start and end ports.

Returns:

Tuple of (points, initial_values, end_frames) where: - points: Array of intermediate waypoints (excluding ports) - initial_values: Flattened array for optimizer initialization - end_frames: Tuple of (start_frame, end_frame) transformation matrices

to_pipe_lines() → list[PipeLine]

Create one PipeLine per waypoint segment of the wire — the path’s actual turns.

volmdlr_primitives() → list[Primitive3D]

Get volmdlr primitives representing this pipe.

Returns the 3D geometric primitives (sweeps) representing the pipe segments, with colors set according to the pipe type. If sweep generation fails, falls back to one straight cylinder per wire segment so the pipe stays displayable.

Returns:

List of Primitive3D objects with pipe type color applied.

class routing.core.core.PipeLine(points: ndarray, dot_product: float, length: float, vector: ndarray, voxels: tuple[tuple[int, int, int], tuple[int, int, int]], min_length: float, radius: float, type_: str, name: str = '')

Bases: DessiaObject, Displayable3D

A class representing a straight line segment of a pipe in 3D space.

Represents a fundamental building block for a single straight segment of a pipe between two points. Multiple PipeLines form a complete pipe path.

Parameters:

• points – The array of shape (2, 3) containing [start_point, end_point] coordinates.

• dot_product – The dot product value (used for optimization and cost calculations).

• length – The length of the line segment in length units.

• vector – The unit direction vector of shape (3,) indicating the line direction.

• voxels – The tuple of (start_voxel, end_voxel) as (i, j, k) indices.

• min_length – The minimum length constraint for this segment.

• radius – The pipe radius for this segment (same unit as length).

• type – The pipe type identifier for grouping/pooling.

• name – The name to identify this pipe line. Defaults to ‘’.

bounding_box(offset: float = 0.0) → ndarray

Get the bounding box of the pipe line.

Computes the axis-aligned bounding box that encompasses the pipe line, including the pipe radius and an optional offset.

Parameters:

offset – Additional offset to add to the bounding box. Defaults to 0.0.

Returns:

Array of shape (2, 3) containing [[min_x, min_y, min_z], [max_x, max_y, max_z]].

static compute_local_frame(start_voxel: tuple[float, float, float], end_voxel: tuple[float, float, float]) → ndarray

Compute local frame from start and end voxel indices.

Creates a transformation frame aligned with the direction from start_voxel to end_voxel, and returns its inverse for projecting voxels into this frame.

Parameters:

• start_voxel – Start voxel index as (i, j, k) tuple.

• end_voxel – End voxel index as (i, j, k) tuple.

Returns:

4x4 inverse transformation matrix for projecting into local frame.

coord_from_parametric_value(parametric_value: float) → ndarray

Convert parametric value on Pack into 3D coordinate.

crossed_voxels: ndarray | None

property direction: ndarray

Get unit direction vector as numpy array.

Computes the normalized direction vector from start to end point.

Returns:

Unit direction vector of shape (3,).

distance_to_point(point: ndarray) → float

Return the distance from point to this segment.

classmethod from_dict(attribute_dict: dict[str, Any], radius: float, type_: str) → PipeLine

Create PipeLine from a dictionary of attributes.

Parameters:

• attribute_dict – Dictionary with keys: points, dot_product, length, vector, voxels, min_length.

• radius – The pipe radius.

• type – The pipe type identifier.

Returns:

PipeLine instance.

classmethod from_list(attribute_values: list[Any], radius: float, type_: str) → PipeLine

Create PipeLine from a list of attribute values.

Parameters:

• attribute_values – List containing [points, dot_product, length, vector, voxels, min_length].

• radius – The pipe radius.

• type – The pipe type identifier.

Returns:

PipeLine instance.

classmethod from_points(start: Point3D, end: Point3D, radius: float, input_voxel: tuple[int, int, int], output_voxel: tuple[int, int, int], type_: str) → PipeLine

Create PipeLine from start and end points.

Convenience method to create a PipeLine from two 3D points, automatically computing length, direction vector, and other geometric properties.

Parameters:

• start – The start point as Point3D.

• end – The end point as Point3D.

• radius – The pipe radius.

• input_voxel – The start voxel index as (i, j, k) tuple.

• output_voxel – The end voxel index as (i, j, k) tuple.

• type – The pipe type identifier.

Returns:

PipeLine instance.

classmethod from_points_array(points: ndarray, radius: float, type_: str) → PipeLine

Build a PipeLine from a (2, 3) endpoint array; vector and length are derived.

classmethod from_polyline_points(points: list[Point3D], radius: float, type_: str) → list[PipeLine]

Build one PipeLine per segment of the polyline given by its points.

classmethod from_start_and_vector(start: ndarray, direction: ndarray, length: float, radius: float, type_: str) → PipeLine

Build a PipeLine from a start point, unit direction and length.

classmethod from_successive_aligned_lines(successive_aligned_lines: list[PipeLine]) → PipeLine

Get approximated line from successive aligned lines. No check is done in this method.

get_crossed_voxels() → ndarray

Get voxels crossed by this pipe line.

Returns the array of voxel indices that this pipe line passes through. Must call update_crossed_voxels() first to compute this.

Returns:

Array of shape (n_voxels, 3) with voxel indices [i, j, k].

get_end_voxels(room_voxelization: RoutingVoxelization) → tuple[ndarray, ndarray]

Get the voxel indices for the start and end points of this pipe line.

Parameters:

room_voxelization – The RoutingVoxelization containing the voxel grid.

Returns:

Tuple of (start_voxel, end_voxel) as continuous (fractional) voxel coordinates.

get_halo(halo_radius: float, voxels_shape: tuple[int, int, int], check_validity: bool = True) → ndarray

Get voxels within a halo radius around crossed voxels.

Optimized alternative version without a KD-tree, for small radii. Returns all voxels within the specified radius from any voxel crossed by this pipe line.

Parameters:

• halo_radius – Radius of the halo in voxel units.

• voxels_shape – Shape of the voxel grid as (width, height, depth).

• check_validity – Flag indicating whether to check if voxels are within grid bounds. Defaults to True.

Returns:

Array of shape (3, n_voxels) containing voxel indices within the halo.

get_parametric_value(point: ndarray) → float

Get the parametric value of a point projected onto the line.

Computes the parameter t such that the projected point is at start + t * (end - start). Returns 0 for start point, 1 for end point, and values outside [0, 1] for points beyond the segment.

Parameters:

point – The 3D point to project as (x, y, z) array.

Returns:

Parametric value t. Returns False if line length is 0.

get_vector()

Get direction vector as volmdlr.Vector3D.

Returns the unit direction vector. If vector is not set, computes it from points.

Returns:

Vector3D representing the unit direction of this pipe line.

static get_voxels_in_obb(voxel_indices: ndarray, projected_voxels: ndarray, bounds: ndarray, radius_y: float = 1, radius_z: float = 1) → ndarray

Get voxels within an oriented bounding box (OBB) around a pipe line.

Filters voxels that fall within a rectangular box aligned with the pipe line’s local frame. The box extends along the pipe direction (x-axis) and has specified radii in the perpendicular directions (y and z axes).

Parameters:

• voxel_indices – Array of shape (4, n_voxels) containing homogeneous voxel indices.

• projected_voxels – Array of shape (4, n_voxels) containing voxels projected into local frame.

• bounds – Array defining the bounding box along x-axis in local frame.

• radius_y – Half-width of the bounding box in y direction (voxel units). Defaults to 1.

• radius_z – Half-height of the bounding box in z direction (voxel units). Defaults to 1.

Returns:

Array of shape (n_crossed_voxels, 3) containing (i, j, k) indices of voxels within OBB.

has_point(point: Point3D, tolerance: float = 0.001) → bool

Check if current PipeLine has a point geometrically equal to point.

has_point_array(point: ndarray, tolerance: float = 0.001) → bool

Check if current PipeLine has a point geometrically equal to point.

indicators: dict[str, Any]

is_facing_other(other: PipeLine) → bool

Check if this pipe line is facing another pipe line.

Two pipe lines are considered “facing” if they share an endpoint or if their projections overlap in a way that suggests they are aligned and could potentially be merged or grouped together.

Parameters:

other – The other PipeLine to check against.

Returns:

True if the pipe lines are facing each other, False otherwise.

local_frame()

Get the local coordinate frame for this pipe line.

Computes an orthonormal frame where the x-axis is aligned with the pipe line direction, and y and z axes are perpendicular. This frame is used for geometric operations like voxel projection.

Returns:

4x4 transformation matrix representing the local frame (homogeneous coordinates).

lock_on_port(port: Port, port_index: int = 0, other_index: int = 1) → None

Set coordinates of point at port_index with the port coordinates and recompute vector and other point.

merge_with(other: PipeLine, coefficient: float, offset: float, min_distance: float, min_length: float) → bool

Check if other PipeLine can merge in a Pack with self.

Merge is True when:

• both PipeLine lengths are more than min_length

• PipeLines are approximately aligned

• coefficient is a pooling coefficient

• distance between the two PipeLines is less than the radius_self + radius_other + offset + min_distance

Parameters:

• other – Other PipeLine to check for merging

• coefficient – Pooling coefficient

• offset – Offset value for distance calculation

• min_distance – Minimum distance threshold

• min_length – Minimum size threshold for both PipeLines

Returns:

True if the PipeLines can merge, False otherwise

neutral_fiber_voxels: ndarray | None

occupancy_half_width(voxel_size: float) → float

World half-width of the cells this line occupies on a grid of pitch voxel_size.

The gauge update_crossed_voxels() rasterizes with, read as a distance instead of an index count: a cell is occupied when the pipe surface reaches its near face, which is radius + voxel / 2, and a pipe thinner than the cell keeps its single lane.

pipe_line_distance(other_line: PipeLine) → float

Calculate the minimum distance between two 3D line segments.

The algorithm finds the closest points between two segments by:

1. Parameterizing each segment as P1(s) = P1_0 + s * u and P2(t) = P2_0 + t * v

2. Minimizing |P1(s) - P2(t)|² with respect to s and t

3. Clamping s and t to [0, 1] to stay within segment bounds

Parameters:

other_line – The other PipeLine to compute distance to.

Returns:

The minimum distance between the two pipe lines.

static points_from_optim_lines(optim_lines: list[PipeLine])

Extract waypoints from a list of optimized pipe lines.

Combines start and end points from multiple pipe lines into a single list of waypoints, removing duplicates at connection points.

Parameters:

optim_lines – List of PipeLine objects to extract points from.

Returns:

List of Point3D waypoints connecting all pipe lines.

points_matrix(offset: float = 0.0) → ndarray

Get bounding box matrix of points with radius and offset.

Computes the minimum and maximum points of the pipe line, expanded by the pipe radius and an optional offset.

Parameters:

offset – Additional offset to add to the bounding box. Defaults to 0.0.

Returns:

Array of shape (2, 3) containing [min_point, max_point] with radius and offset applied.

project_voxels(room_voxelization: RoutingVoxelization) → tuple[ndarray, ndarray]

Project all voxels from room voxelization into the local frame of this pipe line.

Transforms all voxel coordinates into the pipe line’s local coordinate system, where the x-axis is aligned with the pipe direction. Also computes bounding box bounds in this local frame.

Parameters:

room_voxelization – The RoutingVoxelization containing voxels to project.

Returns:

Tuple of (projected_voxels, bounds) where projected_voxels is array of shape (4, n_voxels) in homogeneous coordinates, and bounds defines the bounding box in local frame.

shape(**kwargs) → Cylinder

Get the 3D shape representation of this pipe line as a Cylinder.

Creates a Cylinder primitive connecting the start and end points with the pipe line’s radius.

Parameters:

kwargs – Optional keyword arguments passed to Cylinder.from_end_points (e.g., ‘name’, ‘color’).

Returns:

Cylinder primitive representing this pipe line.

to_list() → list[Any]

Convert PipeLine to a list of attribute values.

Returns a list containing the main attributes of the pipe line in order: [points, dot_product, length, vector, voxels, min_length].

Returns:

List containing [points, dot_product, length, vector, voxels, min_length].

update_crossed_voxels(room_voxelization: RoutingVoxelization) → None

Update the list of voxels crossed by this pipe line.

Computes which voxels in the room voxelization are intersected by this pipe line, storing both the neutral fiber voxels (centerline) and the full crossed voxels (including pipe radius). Only the active voxels inside the line’s index-space window are projected, not the whole room cloud.

Parameters:

room_voxelization – RoutingVoxelization to compute voxel intersections with.

Returns:

None

volmdlr_primitives(*args, **kwargs) → list[Cylinder]

Get list of volmdlr primitives representing this pipe line.

Returns a list containing a single Cylinder primitive representing the pipe line geometry.

Parameters:

• args – Optional positional arguments (not used).

• kwargs – Optional keyword arguments passed to shape() method.

Returns:

List containing a single Cylinder primitive.

class routing.core.core.PipeType(section: Section, name: str, priority_index: int | None = None, radius_of_curvature_ratio_min: float = 1.0, sub_environment: VolumeModel = None, all_sub_environment: bool = False, radius_of_curvature_ratio_max: float = 1.0, length_before_turn_min: float = 0.0, length_before_turn_max: float | None = None, user_properties: list[UserProperty] | None = None, user_constraints: list[ConstraintRule] | None = None, min_slope: float | None = None, max_slope: float | None = None, number_turn_max: int = 0, color: tuple[float, float, float] = (0.1, 0.1, 0.1), type_: str = 'None')

Bases: PipeType

A class defining characteristics and constraints of a pipe type for routing.

This class inherits from piping.PipeType, and encapsulates all physical properties and design constraints for a specific pipe type (hydraulic, electrical, etc.). It defines dimensions, curvature constraints, slope rules, and custom properties.

Parameters:

• section – The pipe section defining the equivalent radius.

• name – The name identifying this pipe type.

• priority_index – The routing priority (lower = more priority). Defaults to None.

• radius_of_curvature_ratio_min – The minimum ratio of curvature radius to pipe radius. Defaults to None.

• sub_environment – The optional VolumeModel defining a sub-environment where this pipe type can be routed. Defaults to None.

• all_sub_environment – Flag indicating whether the pipe must remain entirely within sub_environment. Defaults to False.

• radius_of_curvature_ratio_max – The maximum ratio of curvature radius. Defaults to None.

• length_before_turn_min – The minimum length before a turn is allowed. Defaults to 0.0.

• length_before_turn_max – The maximum length before a turn. Defaults to None.

• user_properties – The list of UserProperty to define attributes based on distance. Defaults to None.

• user_constraints – The list of ConstraintRule for custom constraints. Defaults to None.

• min_slope – The minimum allowed slope (negative for gravity systems). Defaults to None.

• max_slope – The maximum allowed slope. Defaults to None.

• number_turn_max – The maximum number of turns allowed (0 = unlimited). Defaults to 0.

• color – The RGB color tuple (r, g, b) between 0 and 1 for visualization. Defaults to (0.1, 0.1, 0.1).

• type – The pipe type for grouping/pooling. Defaults to ‘None’.

classmethod from_table_row(row_dict: dict) → PipeType

Create a PipeType from a dict row. Required keys: name, radius. All others are optional.

property max_slope: float

Get max_slope requirement for current PipeType.

Returns the maximum allowed slope. If not set, returns negative infinity (no constraint).

Returns:

Maximum slope value, or float(“-inf”) if not constrained

property min_slope: float

Get min_slope requirement for current PipeType.

Returns the minimum allowed slope. If not set, returns infinity (no constraint).

Returns:

Minimum slope value, or float(“inf”) if not constrained

property plot_data_color: str

Get equivalent color in plot_data format (rgb(255)).

Converts the color tuple to plot_data RGB format. If color values are between 0 and 1, they are scaled to 0-255 range.

Returns:

Color string in format “rgb(r, g, b)” with values 0-255.

property radius: float

Get radius of PipeType.

property volmdlr_color: tuple[float, float, float]

Get equivalent color in plot_data (rgb(255)).

class routing.core.core.Port(coordinates: tuple[float, float, float], direction: tuple[float, float, float], length: float = 0.0, permitted_departure_angle: list[float] | None = None, len_adaptable_with_environment: bool = False, name: str = 'Port')

Bases: DessiaObject, Displayable3D

A class representing a connection point for pipe routing.

Defines a point in 3D space where a pipe can start or end, with an orientation direction and optional constraints on the departure angle.

Parameters:

• coordinates – The 3D position of the port as (x, y, z) tuple in global coordinates.

• direction – The non-normalized direction vector indicating the port orientation.

• length – The minimum extension length before the first turn (in length units). Defaults to 0.0.

• permitted_departure_angle – The optional list of angles (in radians) allowed for pipe departure from this port. If None, all angles are permitted. Defaults to None.

• len_adaptable_with_environment – Flag indicating whether the length can be automatically adjusted according to environment constraints. Defaults to False.

• name – The name to identify this port. Defaults to ‘Port’.

extension(length: float) → ndarray

Return the point at length from the port along its direction, where its straight extension ends.

classmethod from_table_row(row_dict: dict, prefix: str) → Port

Create a Port from a dict row using a column prefix (“start” or “end”).

classmethod from_xlsx_stream(stream: BinaryFile)

Create a list of Ports from an Excel file.

Reads port definitions from an Excel file with the following columns: name | coordinates_x | coordinates_y | coordinates_z | direction_x | direction_y | direction_z | length

Parameters:

stream – Binary file stream containing the Excel file.

Returns:

List of Port instances created from the Excel data.

property orientation: Point3D

Get direction of Port as a volmdlr.Point3D.

Returns the direction vector as a Point3D (not normalized).

Returns:

Point3D object representing the port’s direction vector.

property position: Point3D

Get position of Port as a volmdlr.Point3D.

Returns:

Point3D object representing the port’s 3D position.

stub(radius: float, length: float) → Cylinder

Return the cylinder a conduit of radius fills over length from this port along its direction.

property unit_orientation: Point3D

Get unit direction of Port as a volmdlr.Point3D.

Returns the normalized direction vector (unit length).

Returns:

Point3D object representing the port’s normalized direction vector

volmdlr_primitives(*args, **kwargs) → Solid

Get Primitive3D representation of Port for visualization.

Creates a 3D solid primitive representing the port as a revolved shape, useful for CAD visualization.

Parameters:

• args – Optional positional arguments (not used).

• kwargs – Optional keyword arguments, including ‘radius’ for the port visualization radius (default: 0.01).

Returns:

List containing a single Solid primitive representing the port.

class routing.core.core.PortCouple(start: Port, end: Port, name: str = '')

Bases: Terminals

A class representing a pair of ports defining a path to route.

This class links two ports (start and end) to define a pipe path to create. This is the basic input for a routing problem.

Parameters:

• start – The start port (where the pipe begins).

• end – The end port (where the pipe terminates).

• name – The name to identify this port couple. Defaults to ‘’.

end_length(pipe_type: PipeType) → float

Return the end port’s own length.

property ports: tuple[Port, Port]

Both ports, known before routing.

class routing.core.core.Refinement(pipe: Pipe, pipe_lines: list[PipeLine], cost: float = 0.0, name: str = '')

Bases: DessiaObject, Displayable3D

A class representing an optimized pipe with discrete line segments and cost.

Contains a Pipe object along with its discrete PipeLine segments and optimization cost. This is the result of post-routing optimization.

Parameters:

• pipe – The Pipe object representing the optimized continuous path.

• pipe_lines – The list of PipeLine objects representing discrete segments of the optimized pipe.

• cost – The optimization cost (lower is better). Used for ranking multiple optimized solutions. Defaults to 0.0.

• name – The name to identify this optimized pipe. Defaults to ‘’.

distance_to_voxels(room_voxels: RoutingVoxelization) → ndarray

property failed: bool

Whether the optimizer’s checks rejected this refinement: it is not a conduit, only a trace.

classmethod from_grid_path(grid_path: GridPath, name: str = '') → Refinement

classmethod from_pipe_lines(pipe_lines: list[PipeLine], pipe_type: PipeType, cost: float, name: str = '') → Refinement

Build Refinement from list of PipeLine.

get_bounds(offset: float = 0.0) → ndarray

Get the bounds of the optimized pipe.

get_crossed_voxels()

pipelines_to_costs() → tuple[dict[str, Any], dict[str, Any]]

property radius: float

Get radius of Refinement.

to_sample(index: int, reference_path: str = '') → Sample

Get plot_data Samples from Refinement.

volmdlr_primitives(name: str = '', **kwargs) → list[Primitive3D]

class routing.core.core.RoomVoxelization(*args, **kwargs)

Bases: RoomVoxelization

Deprecated: use routing.core.voxels.RoomVoxelization instead.

class routing.core.core.RuledVolume(primitives: list[Primitive3D], global_rules: list[InstanceOf[DesignRule]], in_border: bool = True, voxel_inside: bool = False, overwrite_distance: float = 0.0, support: bool = False, name: str = '')

Bases: VolumeModel

A class representing a 3D volume with associated design rules for routing.

This class inherits from VolumeModel, and combines 3D geometry (primitives) with design rules that define how pipes can interact with this volume. These rules can include distance penalties, placement constraints, weighting factors, etc.

Parameters:

• primitives – The list of 3D primitives defining the volume geometry.

• global_rules – The list of design rules that apply to all pipes passing near this volume.

• in_border – Flag indicating whether this volume is used to compute the bounding box of the routing problem in CadMap. Defaults to True.

• voxel_inside – Flag indicating whether enclosed voxels will be filled during voxelization. Useful for hollow volumes. Defaults to False.

• overwrite_distance – Distance (in length units) under which the volume overrides the map’s weights with its own, whatever the composition of the volumes gives there. 0.0 overrides nothing. Defaults to 0.0.

• support – Whether trays rest on this volume: its faces give them their normal (ParallelPack). No volume flagged, trays rest on every volume. Defaults to False.

• name – The name to identify this volume. Defaults to ‘’.

closest_points(points: ndarray) → tuple[ndarray, ndarray]

Give the distance from each of points to the volume’s surface, and the point of the surface it is closest to.

What the trays’ support queries read (CadMap.support_normal()).

Parameters:

points – Points of shape (n, 3).

Returns:

Distances of shape (n,) and closest points of shape (n, 3).

static compose_weights(weights: list[ndarray]) → ndarray

Compose multiple weight arrays into a single weight array.

Sums all weight arrays element-wise. Used to combine weights from multiple design rules.

Parameters:

weights – List of weight arrays (must have compatible shapes).

Returns:

Combined weight array (sum of all input weights).

compute_voxels(voxel_size: float | None = None) → None

Compute RuledVolume MatrixBasedVoxelization from meshes.

Voxelizes the volume geometry and caches the result. If voxel_inside is True, enclosed voxels are also filled.

Parameters:

voxel_size – Size of voxels for voxelization. If None, uses a default size based on the volume’s bounding box. Defaults to None.

Returns:

None

compute_weights(distances: ndarray) → ndarray

Compute weights from a distance matrix using all design rules.

Applies all design rules (global and pipe-specific) to compute weights based on distances. Weights from all rules are combined by summation.

Parameters:

distances – Distance matrix or array from which to compute weights.

Returns:

Combined weight array representing the total weight/cost at each distance value based on all applicable design rules.

property design_rules

Get all design rules (global and pipe-specific) for this volume.

Combines global_rules and pipe_rules into a single list. Returns empty list if both are None or empty.

Returns:

List of all DesignRule instances applicable to this volume.

distance_from_points(points: ndarray, exact: bool) → ndarray

Compute distances from a point cloud to this volume.

Calculates the distance from each point to the nearest surface of this volume. Can use either exact mesh-based calculation or faster voxel-based approximation.

Parameters:

• points – Array of shape (n_points, 3) containing 3D points.

• exact – Flag indicating whether to use exact mesh distance calculation. If True, uses exact calculation (slower but accurate). If False, uses voxel-based approximation (faster but less accurate).

Returns:

Array of shape (n_points,) with distances from each point to the volume surface. Negative distances indicate points inside the volume.

distance_matrix_from_voxelization(voxelization: MatrixBasedVoxelization, exact: bool) → ndarray

Compute distance matrix from a voxelization to this volume.

Calculates distances from each voxel center in the given voxelization to this volume. Returns a matrix with the same shape as the voxelization’s matrix.

Parameters:

• voxelization – MatrixBasedVoxelization to compute distances from.

• exact – Flag indicating whether to use exact mesh distance calculation. If True, uses exact calculation. If False, uses voxel-based approximation.

Returns:

Distance matrix of same shape as voxelization.matrix, with distances from each voxel center to this volume. np.inf for inactive voxels.

duplicate() → RuledVolume

Create a duplicate of this RuledVolume with the same geometry, rules and properties.

Creates a copy including pipe_rules. Note that the open_shell and voxels caches are not copied and will be recomputed if needed.

Returns:

A new RuledVolume instance with the same primitives, rules, and properties.

classmethod from_ruled_volume(ruled_volume: RuledVolume, design_rules: list[InstanceOf[DesignRule]]) → RuledVolume

Create a new RuledVolume from an existing one with different design rules.

This method creates a copy of a RuledVolume while preserving its geometric primitives, name, and border status, but applying a new set of design rules. The open shell representation is also preserved to avoid recomputation.

Parameters:

• ruled_volume – The source RuledVolume to copy from.

• design_rules – New list of design rules (DesignRule instances) to apply.

Returns:

A new RuledVolume instance with the same geometry but different design rules.

classmethod from_volume_model(volume_model: VolumeModel, design_rules: list[InstanceOf[DesignRule]], in_border: bool = True, voxel_inside: bool = False, overwrite_distance: float = 0.0, support: bool = False, name: str = '') → RuledVolume

Create a RuledVolume from a VolumeModel with associated design rules.

This method extracts the geometric primitives from a VolumeModel and associates them with design rules to create a RuledVolume that can be used in routing and CAD mapping.

Parameters:

• volume_model – The VolumeModel to convert, containing geometric primitives.

• design_rules – List of design rules (DesignRule instances) to apply to the volume.

• in_border – Flag indicating whether the volume is used to build the BoundingBox of routing problem in CadMap. Defaults to True.

• voxel_inside – Flag indicating whether voxelization will fill enclosed voxels. Defaults to False.

• overwrite_distance – Distance under which the volume overrides the map’s weights with its own. Defaults to 0.0, overriding nothing.

• support – Whether trays rest on this volume. Defaults to False.

• name – Optional name for the RuledVolume. If None, uses volume_model.name. Defaults to None.

Returns:

A new RuledVolume instance with the volume model’s primitives and design rules.

classmethod get_bounding_box(volume_models: list[VolumeModel], border_rule: list[InstanceOf[DesignRule]] | None = None, margin: float = 0.0) → RuledVolume

Build a RuledVolume from the bounding box of all listed volumes.

If border_rule is not empty, the bounding box will be considered as material walls.

property open_shell: OpenTriangleShell3D

Get the open shell representation of this volume.

The shell is computed from the volume’s mesh and cached for subsequent access. This is used for geometric operations like intersection detection.

Returns:

OpenTriangleShell3D representing the surface of the volume.

pipe_rules: InstanceOf[DesignRule] | None

remove_from_voxels(free_voxels: MatrixBasedVoxelization, voxel_size: float) → MatrixBasedVoxelization

Remove this volume from free_voxels.

Subtracts this volume’s voxels from the given free voxelization, effectively marking voxels occupied by this volume as non-traversable.

Parameters:

• free_voxels – MatrixBasedVoxelization representing free/traversable space.

• voxel_size – Voxel size for voxelizing this volume (if not already computed).

Returns:

New MatrixBasedVoxelization with this volume’s voxels removed.

reset_pipe_rules() → None

Reset all rules specific to a pipe.

Clears the pipe_rules list, removing any pipe-specific design rules that were added dynamically. Global rules are not affected.

Returns:

None

property surface_mesh: Mesh3D

The volume’s surface as triangles, built once: what closest_points() reads.

property surface_tree: AABB

The search tree of surface_mesh, built once: a query then costs a walk down it, not a new tree.

to_shell() → OpenTriangleShell3D

Convert the volume to an open triangle shell representation.

Creates a mesh from the volume primitives and converts it to an OpenTriangleShell3D. The result is cached in _open_shell for subsequent access.

Returns:

OpenTriangleShell3D representing the surface of the volume.

static voxelize_room(bounding_box: RuledVolume, ruled_volumes: list[RuledVolume], voxel_size: float) → RoutingVoxelization

Voxelize bounding_box and carve each ruled_volume out of it.

voxels(voxel_size: float | None = None) → MatrixBasedVoxelization

Get voxels of the RuledVolume.

Returns the voxelization, computing it if necessary. The result is cached for subsequent calls.

Parameters:

voxel_size – Size of voxels for voxelization. Required if voxels haven’t been computed yet. Defaults to None.

Returns:

MatrixBasedVoxelization representing the volume in discrete space.

Raises:

ValueError – If voxel_size is not provided and voxels haven’t been computed.

property weighs: bool

Whether a rule of the volume writes weights: a volume carrying only toggler rules weighs nothing.

class routing.core.core.Solution(alternatives: list[Alternative], terminals: Terminals, pipe_type: PipeType, name: str = '', picked_index: int | None = None)

Bases: Tappable, Displayable3D

A class representing a complete routing solution with multiple path options and optimizations.

Contains all routing results for a single pipe specification, including multiple generated paths (GridPath) and their optimized versions (Refinement). It provides methods to access the best path and best optimized pipe.

Parameters:

• alternatives – The routes the search produced, one Alternative each.

• terminals – What the routes join: two ports, or a port and the routed conduit a tee taps; a routed solution reads its ports on its picked alternative.

• pipe_type – The PipeType defining pipe characteristics and constraints.

• name – The name of the conduit, its specification’s; the pipe type’s name when empty.

• picked_index – The alternative the solution stands by; the cheapest generated path when None.

add_alternatives(alternatives: list[Alternative]) → None

Register the routes the search built, each with the ports it joins.

add_refinements(refinements: list[Refinement], index: int) → Alternative

Append the optimizer’s refinements to the alternative at index and mark the solution optimized.

property anchor_seeds: tuple[ndarray, ndarray]

Interior endpoints of the routed polyline (port leaders skipped).

Returns (pipe_lines[0].points[1], pipe_lines[-1].points[0]) — the first real routing waypoint after the input leader and the last one before the output leader. By construction these sit on the medial axis of the routed volume and are valid anchors for projecting the solution onto a skeleton.

apply_properties_on_volumes() → None

From UserProperties to DesignRules on ruled_volumes.

property best_path: GridPath | None

The generated path of the alternative the solution stands by; None when not routed.

property best_path_index: int

Index of the alternative the solution stands by: the user’s pick, else the cheapest generated path.

property best_pipe: Refinement | None

The conduit as it stands: the cheapest accepted refinement, else the picked generated path; None when not routed.

property best_refinement: Refinement | None

The cheapest refinement the checks accepted, over the pick or every alternative; None when none passed.

property curvature_radius: float

classmethod dict_to_object(dict_: dict[str, Any], force_generic: bool = False, global_dict: dict | None = None, pointers_memo: dict[str, Any] | None = None, path: str = '#') → Solution

Rebuild the solution.

A dict stored before v3 names its alternatives optimized_pipes and holds its two specification ports as input_port and output_port where terminals now stands.

classmethod from_pipe_definition(terminals: Terminals, pipe_type: PipeType, curvature_radius: float | None = None, name: str = '') → Solution

Create a Solution from what it joins and its pipe type.

Factory method to create a Solution from Terminals (a PortCouple, or TeeTerminals for a tee) and a PipeType. Computes port extension lengths and constraints based on pipe properties.

Parameters:

• terminals – What the route joins: two ports, or a port and the routed conduit it taps.

• pipe_type – PipeType defining pipe characteristics

• curvature_radius – Optional curvature radius. If None, computed from pipe type’s radius_of_curvature_ratio_min

Returns:

Solution instance ready for routing

get_best_path() → int

Get index of the best path among generated pipes.

Finds the GridPath with the lowest cost among all alternatives of the solution.

Returns:

Index of the best path in the optimized_pipes list

get_bounds(offset: float = 0.0) → ndarray

Get the bounds of the solution with an offset.

static get_equivalent_curvature_radius(solutions: list[Solution]) → float

get_global_constraints(radius_equivalent: float = 0) → list[InstanceOf[DesignRule]]

Get all constraints specific to a PipeType as DesignRules.

input_length: float

property input_port: Port

The port the picked alternative leaves from; the terminals’ before any route exists.

property is_gravity: bool

Check if this solution requires gravity constraints.

A solution is considered gravity-based if the pipe type has slope constraints (min_slope < 0 or max_slope > -inf).

Returns:

True if gravity constraints apply, False otherwise

is_optimized: bool

property is_routed: bool

Whether a route joins the ports: the solution carries at least one generated path.

property is_well_optimized: bool

Check if a solution is optimized and if optimized solution is feasible.

A solution is well-optimized if: - Optimization has been performed (is_optimized = True) - At least one refinement passed the optimizer’s checks (best_refinement)

Returns:

True if solution is optimized and feasible, False otherwise

min_straight_length: float

property optimized_pipes: list[Alternative]

Deprecated name of alternatives.

output_length: float

property output_port: Port | None

The port the picked alternative reaches; the terminals’ before any route exists, None for a tee.

pick(index: int) → None

Stand by the alternative at index: best_path and best_pipe follow it from now on.

pick_nearest(point: tuple[float, float, float]) → int

Stand by the alternative whose end port stands nearest point, a tee’s site; return its index.

property picked: Alternative

The alternative the solution stands by: the user’s pick, else the cheapest generated path.

static plot_data_attributes_optimized() → list[str]

Get displayed attributes on ParallelPlot.

property plot_data_color: str

Get equivalent color in plot_data (rgb(255)).

plot_data_generated(reference_path: str = '#', **kwargs) → ParallelPlot

Specific display tag for PlotData. Add a picture argument.

plot_data_optimized(reference_path: str = '#', **kwargs) → ParallelPlot

Specific display tag for PlotData. Add a picture argument.

property polyline_points: ndarray

Concatenation of best_pipe.pipe_lines points as an (N, 3) array.

property port_couple: PortCouple

Get port couple from input and output ports.

property ports: tuple[Port, Port]

Get ports tuple from input and output ports.

ports_primitives() → list[Primitive3D]

Build primitives for ports.

reroute(alternatives: list[Alternative]) → None

Replace every route by alternatives: the pick and the refinements no longer mean anything.

set_direct_connection_as_optimized(pipe_index: int) → Alternative

set_for_optim(radius_factor: float = 1.0) → Solution

Create a copy of this solution with modified radius for optimization.

Creates a new Solution with the same ports but with pipe radius scaled by radius_factor. Useful for optimization workflows where different radius values need to be tested.

Parameters:

radius_factor – Factor to multiply the pipe radius by (default: 1.0)

Returns:

New Solution instance with modified pipe type radius

set_optimized_pipes(optimized_pipes: list[Refinement], pipe_index: int) → Alternative

Call add_refinements; set_optimized_pipes is its deprecated name.

set_properties(curvature_radius: float | None = None) → None

tappable_segments() → list[TappableSegment]

Return the interior segments of the picked conduit’s axis: the port lines, first and last, cannot be tapped.

to_cylinders(with_ports: bool = False) → tuple[list[Cylinder], list[Cylinder]]

Split each Solution’s pipe_lines into interior-routing vs port cylinders.

to_mesh(merge_vertices: bool = False, merge_triangles: bool = False)

to_samples_generated(reference_path: str = '#') → list[Sample]

to_samples_optimized(reference_path: str = '#') → list[Sample]

to_shell()

update_with_grid_paths(grid_paths: list[GridPath]) → None

Build a Solution from a list of GridPaths.

Adds one Alternative per grid path to the solution, each containing a GridPath but no optimized pipes yet. The optimized pipes can be added later using set_optimized_pipes().

Parameters:

grid_paths – List of GridPath objects between the terminals’ own ports.

volmdlr_primitives() → list[Primitive3D]

Get primitives for 3D display: the pipes and the ports, or the port stubs when not routed.

class routing.core.core.SpecInterface(input_position: tuple[float, float, float], input_vector: tuple[float, float, float], input_length: float, output_position: tuple[float, float, float], output_vector: tuple[float, float, float], output_length: float, radius: float, name: str, radius_of_curvature_ratio: float | None = None, min_straight_length: float = 0.0, min_slope: float | None = None, max_slope: float | None = None, pooling_type: str = 'None', color: tuple[float, float, float] = (0.1, 0.1, 0.1))

Bases: DessiaObject

A class for defining pipe specifications with input/output ports and pipe properties.

This class inherits from DessiaObject, and provides a simplified interface for creating pipe routing specifications by directly specifying port positions, directions, and pipe characteristics without requiring separate Port and PipeType objects.

Parameters:

• input_position – The 3D position of input port as (x, y, z) tuple.

• input_vector – The direction vector of input port (non-normalized).

• input_length – The extension length of input port before first turn.

• output_position – The 3D position of output port as (x, y, z) tuple.

• output_vector – The direction vector of output port (non-normalized).

• output_length – The extension length of output port before first turn.

• radius – The pipe equivalent radius.

• name – The name identifying this specification.

• radius_of_curvature_ratio – The minimum ratio of curvature radius to pipe radius. Defaults to None.

• min_straight_length – The minimum straight length before turns. Defaults to 0.0.

• min_slope – The minimum allowed slope (negative for gravity systems). Defaults to None.

• max_slope – The maximum allowed slope. Defaults to None.

• pooling_type – The type for grouping/pooling. Defaults to ‘None’.

• color – The RGB color tuple (r, g, b) between 0 and 1 for visualization. Defaults to (0.1, 0.1, 0.1).

property input_port: Port

Get equivalent Input Port from SpecInterface attributes.

Creates a Port object from the input position, vector, and length attributes of this SpecInterface.

Returns:

Port object representing the input connection point.

property output_port: Port

Get equivalent Output Port from SpecInterface attributes.

Creates a Port object from the output position, vector, and length attributes of this SpecInterface.

Returns:

Port object representing the output connection point.

property pipe_type: PipeType

Get equivalent PipeType from SpecInterface attributes.

Creates a PipeType object from the radius, curvature, slope, and other attributes of this SpecInterface.

Returns:

PipeType object with all constraints and properties from this spec.

class routing.core.core.Specification(start: Port, end: Port, pipe_type: PipeType, name: str = '')

Bases: DessiaObject

A class to associate a port couple with a pipe type.

This class inherits from DessiaObject, and defines a complete routing requirement: a path between two ports using a specific pipe type. This is the main input for creating routing solutions.

Parameters:

• start – The start port of the path (where the pipe begins).

• end – The end port of the path (where the pipe terminates).

• pipe_type – The PipeType defining the characteristics of the pipe to route.

• name – The name of the Specification. Defaults to ‘’.

as_tapped(routed: list[Tappable]) → Tappable

Return the conduit a tee taps once the plan routed routed: its Solution, the only one routed for it.

dependencies() → tuple[Specification | TeeSpecification, ...]

Return the specifications to route before this one: none, a port couple stands alone.

classmethod from_complete_definition(start: Port, end: Port, radius: float, name: str, radius_of_curvature_ratio: float | None = None, min_straight_length: float = 0.0, min_slope: float | None = None, max_slope: float | None = None, pooling_type: str = 'None', color: tuple[float, float, float] = (0.1, 0.1, 0.1)) → Specification

Create specification from ports and all requirements for the pipe type.

Creates a Specification by building a PipeType from individual parameters. Useful when pipe properties are specified directly rather than using a pre-existing PipeType.

Parameters:

• start – Start port

• end – End port

• radius – Pipe equivalent radius

• name – Name for the specification and pipe type

• radius_of_curvature_ratio – Minimum ratio of curvature radius to pipe radius

• min_straight_length – Minimum straight length before turns

• min_slope – Minimum allowed slope (negative for gravity systems)

• max_slope – Maximum allowed slope

• pooling_type – Type for grouping/pooling

• color – RGB color tuple for visualization

Returns:

Specification instance with a newly created PipeType

classmethod from_csv(pipe_types_path: str, specifications_path: str) → list[Specification]

Create a list of Specifications from two CSV files.

Same structure as from_xlsx but split across two files. See from_xlsx for column definitions.

classmethod from_ports(start: Port, end: Port, pipe_type: PipeType) → Specification

Create specification for a couple of ports and a pipe type.

Convenience method to create a Specification using the pipe type’s name.

Parameters:

• start – The start port.

• end – The end port.

• pipe_type – The PipeType for the specification.

Returns:

Specification instance with name from pipe_type.name.

classmethod from_spec_interfaces(specifications: list[SpecInterface])

Build list of Specifications from list of SpecInterface objects.

Converts a list of SpecInterface objects (simplified specification format) into a list of Specification objects (full format with Port and PipeType objects).

Parameters:

specifications – The list of SpecInterface objects to convert.

Returns:

List of Specification instances, one per SpecInterface.

classmethod from_xlsx(stream: BinaryFile) → list[Specification]

Create a list of Specifications from an Excel file with two sheets.

The file must contain two sheets:

• pipe_types: one row per pipe type. Columns: name and radius (required), plus optional radius_of_curvature_ratio, min_straight_length, min_slope, max_slope, pooling_type, color_r, color_g, color_b, priority_index, number_turn_max. Empty cells fall back to PipeType defaults.

• specifications: one row per specification. Columns (all required): name, pipe_type (must match a name in the pipe_types sheet), start_x, start_y, start_z, start_dx, start_dy, start_dz, start_length, end_x, end_y, end_z, end_dx, end_dy, end_dz, end_length.

planned_before() → tuple[Specification]

Return what a plan routes before a tee taps this: the specification itself.

property port_couple: PortCouple

Get port couple object from start and end ports.

Creates a PortCouple from the specification’s ports.

Returns:

PortCouple instance linking start and end ports.

property ports: tuple[Port, Port]

The conduit’s own ports.

property terminals: PortCouple

What the route joins: both ports, known before routing.

terminals_for(routed_dependencies: list[Tappable]) → Terminals

Return what the route joins given the routed dependencies: the couple’s own ports.

class routing.core.core.TapSite(abscissa: float, name: str = '')

Bases: DessiaObject

A point of a routed conduit’s axis where a tee taps it: a curvilinear abscissa along its best_pipe.

classmethod at(tapped: Tappable, point: tuple[float, float, float]) → TapSite

Return the site nearest point: its projection on the straight part of the tappable segments of tapped.

classmethod every(tapped: Tappable, step: float) → list[TapSite]

Return one site every step along the straight part of each tappable segment of tapped.

The bends take the conduit’s curvature radius on each side of a corner: the sites start one curvature radius after the corner and stop one before the next; a segment shorter than two radii gives none.

ports(tapped: Tappable, junction_length: float) → list[Port]

Return the ports a tee may tap tapped at this site: on its axis, radial to it, junction_length long.

Eight radials in the world frame, built on the world axis least aligned with the segment (on an axial segment, the eight integer directions). None when the abscissa falls outside the tappable segments.

class routing.core.core.Tappable(name: str = '')

Bases: DessiaObject

A routed conduit a tee may tap: the role Solution plays for TeeTerminals and TapSite.

A tee reads the conduit as it stands: best_pipe for its axis, tappable_segments for the sites it may tap, and the attributes pipe_type and curvature_radius for the junction length and the corner margin.

as_tapped(routed: list[Tappable]) → Tappable

Return the conduit a tee taps once the plan routed routed: this one, routed already.

property best_pipe: Refinement | None

The conduit as it stands, None when not routed.

planned_before() → tuple

Return what a plan routes before a tee taps this: nothing, the conduit is routed already.

tappable_segments() → list[TappableSegment]

Return the straight segments of the conduit’s axis a tee may tap.

class routing.core.core.TappableSegment(start_abscissa: float, start: ndarray, end: ndarray)

Bases: NamedTuple

A straight segment of a routed conduit’s axis a tee may tap, with the curvilinear abscissa where it starts.

end: ndarray

Alias for field number 2

property end_abscissa: float

The curvilinear abscissa where the segment ends.

property length: float

The segment’s length.

start: ndarray

Alias for field number 1

start_abscissa: float

Alias for field number 0

property vector: ndarray

From start to end.

class routing.core.core.TeeSpecification(port: Port, tapped: Specification | TeeSpecification | Tappable, pipe_type: PipeType, tap_sites: list[TapSite] | None = None, explored_step: float | None = None, name: str = '')

Bases: DessiaObject

A conduit tapping another one: its port, the specification of the conduit it taps and its pipe type.

Parameters:

• tapped – The conduit to tap: its specification, routed first, itself a tee or not; or a conduit routed already, taken as it stands.

• tap_sites – Where the tee may tap the conduit; None leaves the tap point free along it.

• explored_step – Every how far along the conduit the generation routes the tee, one alternative per site, standing by the cheapest; None routes it to the cheapest site only.

as_tapped(routed: list[Tappable]) → Tappable

Return the conduit a tee taps once the plan routed routed: its Solution, the only one routed for it.

dependencies() → tuple[Specification | TeeSpecification, ...]

Return the specifications to route before this one: the conduit it taps, unless routed already.

planned_before() → tuple[TeeSpecification]

Return what a plan routes before a tee taps this: the specification itself.

property ports: tuple[Port]

The tee port: the tap port is built by the routing.

terminals_for(routed_dependencies: list[Tappable]) → TeeTerminals

Return what the route joins: the tee port and the routed conduit it taps.

class routing.core.core.TeeTerminals(port: Port, tapped: Tappable, tap_sites: list[TapSite] | None = None, explored_step: float | None = None, name: str = '')

Bases: Terminals

What a tee joins: its port and the routed conduit it taps, anywhere along it or at the given sites.

Parameters:

• tapped – The routed conduit the tee taps; the tap port is built on its axis by the routing.

• tap_sites – Where the tee may tap; None leaves the tap point free along the conduit.

• explored_step – Every how far along the conduit the generation routes the tee, one alternative per site, standing by the cheapest; None routes it to the cheapest site only.

at_site(site: TapSite) → TeeTerminals

Return these terminals narrowed to site: the tee taps there and nowhere else.

dependencies() → tuple[Tappable]

Return the routed conduit this route is built on: the one it taps.

property end: None

None: the tap port is built by the routing.

end_length(pipe_type: PipeType) → float

Return the junction length: the tapped conduit’s radius plus the tee’s straight length before its first turn.

explored_sites() → list[TapSite]

Return the sites routed one by one at generation: its sites every explored_step, none when unset.

host_lines(port: Port) → list[PipeLine]

Return the lines of the tapped conduit’s best_pipe whose axis carries port, the tap port.

The tap port lies on that axis by construction, the tolerance absorbs numerical noise only: a tee whose conduit moved since the tee was routed finds no host line, and is to be rerouted on it.

property ports: tuple[Port]

The tee port alone.

sites(step: float) → list[TapSite]

Return the sites the tee may tap: the declared ones, else one every step along the conduit.

property start: Port

The tee port.

tap_ports(pipe_type: PipeType, step: float) → list[Port]

Return the ports the tee may tap its conduit at: on its sites (sites()), radial to the conduit.

class routing.core.core.Terminals(name: str = '')

Bases: DessiaObject

What a route joins: two ports, or a port and the routed conduit it taps.

Subclasses expose start, the port the route leaves from, and end, the port it reaches or None when routing builds it.

dependencies() → tuple[Tappable, ...]

Return the routed conduits this route is built on: none, two ports stand alone.

end_length(pipe_type: PipeType) → float

Return the length the route runs straight at its end, before any turn.

explored_sites() → list[TapSite]

Return the sites routed one by one at generation: none, two ports have no site.

host_lines(port: Port) → list[PipeLine]

Return the lines of a routed conduit port stands on: none, a port couple stands on no conduit.

property ports: tuple[Port, ...]

The ports known before routing.

class routing.core.core.UserProperty(attribute: str = 'user_defined', min_distance: float = 0.0, max_distance: float | None = None, ruled_volumes: list[RuledVolume] | None = None, name: str = '')

Bases: DessiaObject

A class to build User Defined Property on voxels.

This class inherits from DessiaObject, and creates a property based on proximity rule: while the voxel is in a distance range defined by [min_distance, max_distance] from the ruled volumes, the property named attribute of these voxels will be True. Outside they will be False. This property is used to build a DistanceAttributeToggler, that is used by ConstraintRules.

Parameters:

• attribute – The name of the attribute to apply on voxels. Defaults to ‘user_defined’.

• min_distance – The minimum distance from ruled volumes for a voxel to have the property set to True. Defaults to 0.0.

• max_distance – The maximum distance from ruled volumes for a voxel to have the property set to True. If None, no maximum distance limit. Defaults to None.

• ruled_volumes – The list of RuledVolume objects to consider for distance computation. Defaults to None.

• name – The name to identify this UserProperty. Defaults to ‘’.

to_rule_on_volumes() → None

Push the current UserProperty as a DesignRule on its RuledVolumes.

Converts this UserProperty into a DistanceAttributeToggler rule and adds it to the pipe_rules of each associated RuledVolume. This allows the property to be used as a constraint during routing.

The rule will be added to pipe_rules, which are pipe-specific design rules that can be applied dynamically.