fiberpath 0.3.0__py3-none-any.whl

fiberpath/planning/calculations.py

@@ -0,0 +1,50 @@
+"""Reusable numeric helpers for planner kinematics."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from fiberpath.config.schemas import HelicalLayer, MandrelParameters, TowParameters
+from fiberpath.math_utils import deg_to_rad
+
+
+@dataclass(slots=True)
+class HelicalKinematics:
+    mandrel_circumference: float
+    tow_arc_length: float
+    num_circuits: int
+    pattern_step_degrees: float
+    pass_rotation_mm: float
+    pass_rotation_degrees: float
+    pass_degrees_per_mm: float
+    lead_in_degrees: float
+    main_pass_degrees: float
+
+
+def compute_helical_kinematics(
+    layer: HelicalLayer,
+    mandrel_parameters: MandrelParameters,
+    tow_parameters: TowParameters,
+) -> HelicalKinematics:
+    mandrel_circumference = math.pi * mandrel_parameters.diameter
+    tow_arc_length = tow_parameters.width / math.cos(deg_to_rad(layer.wind_angle))
+    num_circuits = math.ceil(mandrel_circumference / tow_arc_length)
+    pattern_step_degrees = 360.0 * (1 / num_circuits)
+    pass_rotation_mm = mandrel_parameters.wind_length * math.tan(deg_to_rad(layer.wind_angle))
+    pass_rotation_degrees = 360.0 * (pass_rotation_mm / mandrel_circumference)
+    pass_degrees_per_mm = pass_rotation_degrees / mandrel_parameters.wind_length
+    lead_in_degrees = pass_degrees_per_mm * layer.lead_in_mm
+    main_pass_degrees = pass_degrees_per_mm * (mandrel_parameters.wind_length - layer.lead_in_mm)
+
+    return HelicalKinematics(
+        mandrel_circumference=mandrel_circumference,
+        tow_arc_length=tow_arc_length,
+        num_circuits=num_circuits,
+        pattern_step_degrees=pattern_step_degrees,
+        pass_rotation_mm=pass_rotation_mm,
+        pass_rotation_degrees=pass_rotation_degrees,
+        pass_degrees_per_mm=pass_degrees_per_mm,
+        lead_in_degrees=lead_in_degrees,
+        main_pass_degrees=main_pass_degrees,
+    )

fiberpath/planning/exceptions.py

@@ -0,0 +1,19 @@
+"""Custom exceptions raised during planning."""
+
+from __future__ import annotations
+
+
+class PlanningError(RuntimeError):
+    """Raised when the planner encounters a recoverable validation error."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class LayerValidationError(PlanningError):
+    """Raised when layer-specific validation fails."""
+
+    def __init__(self, layer_index: int, message: str) -> None:
+        super().__init__(f"Layer {layer_index}: {message}")
+        self.layer_index = layer_index

fiberpath/planning/helpers.py

@@ -0,0 +1,55 @@
+"""Utility helpers shared by planner components."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from fiberpath.math_utils import strip_precision
+
+if TYPE_CHECKING:
+    from fiberpath.gcode.dialects import AxisMapping
+
+
+class Axis(Enum):
+    CARRIAGE = "carriage"
+    MANDREL = "mandrel"
+    DELIVERY_HEAD = "delivery_head"
+
+
+AXIS_LOOKUP: dict[Axis, str] = {
+    Axis.CARRIAGE: "X",
+    Axis.MANDREL: "Y",
+    Axis.DELIVERY_HEAD: "Z",
+}
+
+Coordinate = dict[Axis, float]
+
+
+def get_axis_letter(axis: Axis, mapping: AxisMapping) -> str:
+    """Get G-code axis letter for logical axis based on dialect mapping."""
+    return {
+        Axis.CARRIAGE: mapping.carriage,
+        Axis.MANDREL: mapping.mandrel,
+        Axis.DELIVERY_HEAD: mapping.delivery_head,
+    }[axis]
+
+
+def serialize_coordinate(coordinate: Coordinate) -> str:
+    serialized = " ".join(
+        f"{axis.value}:{strip_precision(value)}" for axis, value in coordinate.items()
+    )
+    return "{" + serialized + "}"
+
+
+def interpolate_coordinates(start: Coordinate, end: Coordinate, steps: int) -> list[Coordinate]:
+    if steps <= 0:
+        raise ValueError("Steps cannot be less than 1")
+    if steps == 1:
+        return [end]
+
+    coordinates: list[Coordinate] = []
+    delta = {axis: (end[axis] - start[axis]) / (steps - 1) for axis in Axis}
+    for step in range(steps):
+        coordinates.append({axis: start[axis] + step * delta[axis] for axis in Axis})
+    return coordinates

fiberpath/planning/layer_strategies.py

@@ -0,0 +1,194 @@
+"""Layer-specific planning helpers."""
+
+from __future__ import annotations
+
+import logging
+import math
+
+from fiberpath.config.schemas import (
+    HelicalLayer,
+    HoopLayer,
+    LayerModel,
+    MandrelParameters,
+    SkipLayer,
+    TowParameters,
+)
+from fiberpath.math_utils import rad_to_deg
+
+from .calculations import HelicalKinematics, compute_helical_kinematics
+from .helpers import Axis
+from .machine import WinderMachine
+
+LOGGER = logging.getLogger(__name__)
+
+
+def build_layer_summary(index: int, total: int, layer: LayerModel) -> str:
+    base = f"Layer {index} of {total}: {layer.wind_type}"
+    if isinstance(layer, HelicalLayer):
+        return base
+    return base
+
+
+def dispatch_layer(
+    machine: WinderMachine,
+    layer: LayerModel,
+    mandrel_parameters: MandrelParameters,
+    tow_parameters: TowParameters,
+    *,
+    helical_kinematics: HelicalKinematics | None = None,
+) -> None:
+    if isinstance(layer, HoopLayer):
+        plan_hoop_layer(machine, layer, mandrel_parameters, tow_parameters)
+        return
+    if isinstance(layer, HelicalLayer):
+        plan_helical_layer(
+            machine,
+            layer,
+            mandrel_parameters,
+            tow_parameters,
+            helical_kinematics=helical_kinematics,
+        )
+        return
+    if isinstance(layer, SkipLayer):
+        plan_skip_layer(machine, layer)
+        return
+    raise TypeError(f"Unsupported layer type: {layer}")
+
+
+def plan_hoop_layer(
+    machine: WinderMachine,
+    layer: HoopLayer,
+    mandrel_parameters: MandrelParameters,
+    tow_parameters: TowParameters,
+) -> None:
+    lock_degrees = 180.0
+    wind_angle = 90.0 - rad_to_deg(math.atan(mandrel_parameters.diameter / tow_parameters.width))
+    mandrel_rotations = mandrel_parameters.wind_length / tow_parameters.width
+    far_mandrel = lock_degrees + mandrel_rotations * 360.0
+    far_lock = far_mandrel + lock_degrees
+    near_mandrel = far_lock + mandrel_rotations * 360.0
+    near_lock = near_mandrel + lock_degrees
+
+    machine.move({Axis.CARRIAGE: 0.0, Axis.MANDREL: lock_degrees, Axis.DELIVERY_HEAD: 0.0})
+    machine.move({Axis.DELIVERY_HEAD: -wind_angle})
+    machine.move({Axis.CARRIAGE: mandrel_parameters.wind_length, Axis.MANDREL: far_mandrel})
+    machine.move({Axis.MANDREL: far_lock, Axis.DELIVERY_HEAD: 0.0})
+
+    if layer.terminal:
+        return
+
+    machine.move({Axis.DELIVERY_HEAD: wind_angle})
+    machine.move({Axis.CARRIAGE: 0.0, Axis.MANDREL: near_mandrel})
+    machine.move({Axis.MANDREL: near_lock, Axis.DELIVERY_HEAD: 0.0})
+    machine.zero_axes(near_lock)
+
+
+def plan_helical_layer(
+    machine: WinderMachine,
+    layer: HelicalLayer,
+    mandrel_parameters: MandrelParameters,
+    tow_parameters: TowParameters,
+    *,
+    helical_kinematics: HelicalKinematics | None = None,
+) -> None:
+    delivery_head_pass_start_angle = -10.0
+    lead_out_degrees = layer.lead_out_degrees
+    wind_lead_in_mm = layer.lead_in_mm
+    lock_degrees = layer.lock_degrees
+    delivery_head_angle = -1.0 * (90.0 - layer.wind_angle)
+    pattern_number = layer.pattern_number
+
+    kinematics = helical_kinematics or compute_helical_kinematics(
+        layer, mandrel_parameters, tow_parameters
+    )
+    num_circuits = kinematics.num_circuits
+    pattern_step_degrees = kinematics.pattern_step_degrees
+    pass_rotation_degrees = kinematics.pass_rotation_degrees
+    lead_in_degrees = kinematics.lead_in_degrees
+    main_pass_degrees = kinematics.main_pass_degrees
+    number_of_patterns = num_circuits / pattern_number
+    start_position_increment = 360.0 / pattern_number
+    pass_parameters = [
+        {
+            "delivery_head_sign": 1,
+            "lead_in_end_mm": wind_lead_in_mm,
+            "full_pass_end_mm": mandrel_parameters.wind_length,
+        },
+        {
+            "delivery_head_sign": -1,
+            "lead_in_end_mm": mandrel_parameters.wind_length - wind_lead_in_mm,
+            "full_pass_end_mm": 0.0,
+        },
+    ]
+
+    LOGGER.debug("Helical wind with %s circuits", num_circuits)
+
+    if num_circuits % pattern_number != 0:
+        LOGGER.warning(
+            "Skipping helical layer: %s circuits not divisible by pattern %s",
+            num_circuits,
+            pattern_number,
+        )
+        return
+
+    if not layer.skip_initial_near_lock:
+        machine.move({Axis.CARRIAGE: 0.0, Axis.MANDREL: lock_degrees, Axis.DELIVERY_HEAD: 0.0})
+        machine.set_position({Axis.MANDREL: 0.0})
+
+    mandrel_position = 0.0
+    patterns = int(number_of_patterns)
+    for pattern_index in range(patterns):
+        for in_pattern_index in range(pattern_number):
+            machine.insert_comment(
+                f"\tPattern: {pattern_index + 1}/{patterns} "
+                f"Circuit: {in_pattern_index + 1}/{pattern_number}"
+            )
+
+            for pass_params in pass_parameters:
+                sign = pass_params["delivery_head_sign"]
+                machine.move({Axis.MANDREL: mandrel_position, Axis.DELIVERY_HEAD: 0.0})
+                machine.move({Axis.DELIVERY_HEAD: sign * delivery_head_pass_start_angle})
+
+                mandrel_position += lead_in_degrees
+                machine.move(
+                    {
+                        Axis.CARRIAGE: pass_params["lead_in_end_mm"],
+                        Axis.MANDREL: mandrel_position,
+                        Axis.DELIVERY_HEAD: sign * delivery_head_angle,
+                    }
+                )
+
+                mandrel_position += main_pass_degrees
+                machine.move(
+                    {
+                        Axis.CARRIAGE: pass_params["full_pass_end_mm"],
+                        Axis.MANDREL: mandrel_position,
+                    }
+                )
+
+                mandrel_position += lead_out_degrees
+                machine.move(
+                    {
+                        Axis.MANDREL: mandrel_position,
+                        Axis.DELIVERY_HEAD: sign * delivery_head_pass_start_angle,
+                    }
+                )
+
+                mandrel_position += (
+                    lock_degrees - lead_out_degrees - (pass_rotation_degrees % 360.0)
+                )
+
+            mandrel_position += start_position_increment
+
+        mandrel_position += pattern_step_degrees
+
+    mandrel_position += lock_degrees
+    machine.move({Axis.MANDREL: mandrel_position, Axis.DELIVERY_HEAD: 0.0})
+    machine.zero_axes(mandrel_position)
+
+
+def plan_skip_layer(machine: WinderMachine, layer: SkipLayer) -> None:
+    machine.move(
+        {Axis.CARRIAGE: 0.0, Axis.MANDREL: layer.mandrel_rotation, Axis.DELIVERY_HEAD: 0.0}
+    )
+    machine.set_position({Axis.MANDREL: 0.0})

fiberpath/planning/machine.py

@@ -0,0 +1,151 @@
+"""G-code aware machine abstraction used for planning."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+from fiberpath.math_utils import strip_precision
+
+from .helpers import Axis, get_axis_letter, interpolate_coordinates, serialize_coordinate
+
+if TYPE_CHECKING:
+    from fiberpath.gcode.dialects import MarlinDialect
+
+
+class WinderMachine:
+    def __init__(
+        self,
+        mandrel_diameter: float,
+        verbose_output: bool = False,
+        dialect: MarlinDialect | None = None,
+    ) -> None:
+        self._verbose = verbose_output
+        self._gcode: list[str] = []
+        self._feed_rate_mmpm = 0.0
+        self._total_time_s = 0.0
+        self._total_tow_length_mm = 0.0
+        self._last_position: dict[Axis, float] = {
+            Axis.CARRIAGE: 0.0,
+            Axis.MANDREL: 0.0,
+            Axis.DELIVERY_HEAD: 0.0,
+        }
+        self._mandrel_diameter = mandrel_diameter
+
+        # Import here to avoid circular dependency
+        if dialect is None:
+            from fiberpath.gcode.dialects import MARLIN_XYZ_LEGACY
+
+            dialect = MARLIN_XYZ_LEGACY
+        self._dialect = dialect
+
+    def get_gcode(self) -> list[str]:
+        return self._gcode.copy()
+
+    def add_raw_gcode(self, command: str) -> None:
+        self._gcode.append(command)
+
+    def insert_comment(self, text: str) -> None:
+        self._gcode.append(f"; {text}")
+
+    def set_feed_rate(self, feed_rate_mmpm: float) -> None:
+        self._feed_rate_mmpm = feed_rate_mmpm
+        self._gcode.append(f"G0 F{strip_precision(feed_rate_mmpm)}")
+
+    def move(self, position: Mapping[Axis, float]) -> None:
+        complete_end = self._last_position.copy()
+        complete_end.update(position)
+        do_segment_move = not math.isclose(
+            self._last_position[Axis.CARRIAGE], complete_end[Axis.CARRIAGE], abs_tol=1e-6
+        )
+        if not do_segment_move:
+            if self._verbose:
+                self.insert_comment(
+                    "Move "
+                    f"{serialize_coordinate(self._last_position)} -> "
+                    f"{serialize_coordinate(complete_end)}"
+                )
+            # Pass complete_end so all axes are included in the G-code command
+            self._move_segment(complete_end)
+            return
+
+        carriage_delta = abs(self._last_position[Axis.CARRIAGE] - complete_end[Axis.CARRIAGE])
+        num_segments = int(round(carriage_delta)) + 1
+        if self._verbose:
+            self.insert_comment(
+                "Segmented move "
+                f"{serialize_coordinate(self._last_position)} -> "
+                f"{serialize_coordinate(complete_end)} in {num_segments} steps"
+            )
+        for intermediate in interpolate_coordinates(
+            self._last_position, complete_end, num_segments
+        ):
+            self._move_segment(intermediate)
+
+    def set_position(self, position: Mapping[Axis, float]) -> None:
+        command_parts = ["G92"]
+        for axis, value in position.items():
+            axis_letter = get_axis_letter(axis, self._dialect.axis_mapping)
+            command_parts.append(f"{axis_letter}{strip_precision(value)}")
+            self._last_position[axis] = value
+        self._gcode.append(" ".join(command_parts))
+
+    def zero_axes(self, current_angle_degrees: float) -> None:
+        self.set_position(
+            {
+                Axis.CARRIAGE: 0.0,
+                Axis.MANDREL: current_angle_degrees % 360.0,
+                Axis.DELIVERY_HEAD: 0.0,
+            }
+        )
+        self.move({Axis.MANDREL: 360.0})
+        self.set_position({Axis.MANDREL: 0.0})
+
+    def get_gcode_time_s(self) -> float:
+        return self._total_time_s
+
+    def get_tow_length_m(self) -> float:
+        return self._total_tow_length_mm / 1000.0
+
+    def set_mandrel_diameter(self, mandrel_diameter: float) -> None:
+        self._mandrel_diameter = mandrel_diameter
+
+    def get_mandrel_diameter(self) -> float:
+        return self._mandrel_diameter
+
+    def _move_segment(self, position: Mapping[Axis, float]) -> None:
+        command_parts = ["G0"]
+        total_distance_sq = 0.0
+        tow_length_sq = 0.0
+        for axis, value in position.items():
+            axis_letter = get_axis_letter(axis, self._dialect.axis_mapping)
+            command_parts.append(f"{axis_letter}{strip_precision(value)}")
+            move_component = value - self._last_position[axis]
+
+            # Distance calculation depends on whether axis is truly rotational in Marlin
+            if axis == Axis.MANDREL:
+                # For XYZ legacy: Y/Z configured as linear in Marlin
+                # For XAB standard: A/B are rotational in Marlin
+                # In both cases, use degree value directly for distance calculation
+                total_distance_sq += move_component**2
+                # For tow length, always convert to arc length
+                arc_length = move_component / 360.0 * self._mandrel_diameter * math.pi
+                tow_length_sq += arc_length**2
+            elif axis == Axis.CARRIAGE:
+                # Carriage: always linear in mm
+                total_distance_sq += move_component**2
+                tow_length_sq += move_component**2
+            elif axis == Axis.DELIVERY_HEAD:
+                # Delivery head: use value directly for distance
+                total_distance_sq += move_component**2
+                # Delivery head rotation doesn't contribute to tow length
+
+            self._last_position[axis] = value
+
+        if self._feed_rate_mmpm <= 0:
+            raise RuntimeError("Feed rate must be set before moving the machine")
+
+        self._total_time_s += math.sqrt(total_distance_sq) / self._feed_rate_mmpm * 60.0
+        self._total_tow_length_mm += math.sqrt(tow_length_sq)
+        self._gcode.append(" ".join(command_parts))

fiberpath/planning/planner.py

@@ -0,0 +1,133 @@
+"""High-level wind planning orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from fiberpath.config import WindDefinition
+from fiberpath.config.schemas import HelicalLayer, MandrelParameters
+from fiberpath.gcode.generator import sanitize_program
+
+from .calculations import HelicalKinematics
+from .layer_strategies import build_layer_summary, dispatch_layer
+from .machine import WinderMachine
+from .validators import (
+    validate_helical_layer,
+    validate_layer_numeric_bounds,
+    validate_layer_sequence,
+)
+
+if TYPE_CHECKING:
+    from fiberpath.gcode.dialects import MarlinDialect
+
+
+@dataclass(slots=True)
+class PlanOptions:
+    verbose: bool = False
+    dialect: MarlinDialect = field(default_factory=lambda: _get_default_dialect())  # noqa: E731
+
+
+def _get_default_dialect() -> MarlinDialect:
+    """Import default dialect lazily to avoid circular imports."""
+    from fiberpath.gcode.dialects import MARLIN_XAB_STANDARD
+
+    return MARLIN_XAB_STANDARD
+
+
+@dataclass(slots=True)
+class LayerMetrics:
+    index: int
+    wind_type: str
+    commands: int
+    time_s: float
+    cumulative_time_s: float
+    tow_m: float
+    cumulative_tow_m: float
+    terminal: bool
+
+
+@dataclass(slots=True)
+class PlanResult:
+    commands: list[str]
+    total_time_s: float
+    total_tow_m: float
+    layers: list[LayerMetrics]
+
+
+def plan_wind(definition: WindDefinition, options: PlanOptions | None = None) -> PlanResult:
+    options = options or PlanOptions()
+    machine = WinderMachine(
+        mandrel_diameter=definition.mandrel_parameters.diameter,
+        verbose_output=options.verbose,
+        dialect=options.dialect,
+    )
+
+    # Generate initial position command using correct axis letters
+    mapping = options.dialect.axis_mapping
+    init_cmd = f"G0 {mapping.carriage}0 {mapping.mandrel}0 {mapping.delivery_head}0"
+    program: list[str] = [definition.dump_header(), init_cmd]
+
+    machine.set_feed_rate(definition.default_feed_rate)
+    layer_metrics: list[LayerMetrics] = []
+    encountered_terminal = False
+    mandrel_diameter = definition.mandrel_parameters.diameter
+
+    for index, layer in enumerate(definition.layers, start=1):
+        validate_layer_sequence(index, encountered_terminal)
+        validate_layer_numeric_bounds(index, layer)
+
+        current_mandrel = MandrelParameters(
+            diameter=mandrel_diameter,
+            windLength=definition.mandrel_parameters.wind_length,
+        )
+        machine.set_mandrel_diameter(current_mandrel.diameter)
+
+        helical_kinematics: HelicalKinematics | None = None
+        if isinstance(layer, HelicalLayer):
+            helical_kinematics = validate_helical_layer(
+                index, layer, current_mandrel, definition.tow_parameters
+            )
+
+        summary = build_layer_summary(index, len(definition.layers), layer)
+        machine.insert_comment(summary)
+
+        pre_commands = len(machine.get_gcode())
+        pre_time = machine.get_gcode_time_s()
+        pre_tow = machine.get_tow_length_m()
+
+        dispatch_layer(
+            machine,
+            layer,
+            current_mandrel,
+            definition.tow_parameters,
+            helical_kinematics=helical_kinematics,
+        )
+
+        layer_metrics.append(
+            LayerMetrics(
+                index=index,
+                wind_type=layer.wind_type,
+                commands=len(machine.get_gcode()) - pre_commands,
+                time_s=machine.get_gcode_time_s() - pre_time,
+                cumulative_time_s=machine.get_gcode_time_s(),
+                tow_m=machine.get_tow_length_m() - pre_tow,
+                cumulative_tow_m=machine.get_tow_length_m(),
+                terminal=bool(getattr(layer, "terminal", False)),
+            )
+        )
+
+        if getattr(layer, "terminal", False):
+            encountered_terminal = True
+    program.extend(machine.get_gcode())
+
+    if options.verbose:
+        program.insert(0, "; Verbose output enabled")
+
+    sanitized_commands = sanitize_program(program)
+    return PlanResult(
+        commands=sanitized_commands,
+        total_time_s=machine.get_gcode_time_s(),
+        total_tow_m=machine.get_tow_length_m(),
+        layers=layer_metrics,
+    )

fiberpath/planning/validators.py

@@ -0,0 +1,51 @@
+"""Validation helpers for planner inputs."""
+
+from __future__ import annotations
+
+from math import gcd
+
+from fiberpath.config.schemas import HelicalLayer, LayerModel, MandrelParameters, TowParameters
+
+from .calculations import HelicalKinematics, compute_helical_kinematics
+from .exceptions import LayerValidationError
+
+MIN_WIND_ANGLE = 1.0
+MAX_WIND_ANGLE = 89.0
+
+
+def validate_layer_sequence(layer_index: int, encountered_terminal: bool) -> None:
+    if encountered_terminal:
+        raise LayerValidationError(
+            layer_index,
+            "terminal layer must be the final entry in the definition",
+        )
+
+
+def validate_layer_numeric_bounds(layer_index: int, layer: LayerModel) -> None:
+    wind_angle = getattr(layer, "wind_angle", None)
+    if wind_angle is not None and not (MIN_WIND_ANGLE <= wind_angle <= MAX_WIND_ANGLE):
+        raise LayerValidationError(
+            layer_index,
+            f"wind angle {wind_angle}° must be between {MIN_WIND_ANGLE}° and {MAX_WIND_ANGLE}°",
+        )
+
+
+def validate_helical_layer(
+    layer_index: int,
+    layer: HelicalLayer,
+    mandrel: MandrelParameters,
+    tow: TowParameters,
+) -> HelicalKinematics:
+    if layer.skip_index >= layer.pattern_number:
+        raise LayerValidationError(
+            layer_index,
+            "skipIndex must be less than patternNumber",
+        )
+
+    if gcd(layer.skip_index, layer.pattern_number) != 1:
+        raise LayerValidationError(
+            layer_index,
+            "skipIndex and patternNumber must be coprime for full coverage",
+        )
+
+    return compute_helical_kinematics(layer, mandrel, tow)

fiberpath/simulation/__init__.py

@@ -0,0 +1,5 @@
+"""Simulation entry points."""
+
+from .simulator import SimulationError, SimulationResult, simulate_program
+
+__all__ = ["SimulationResult", "SimulationError", "simulate_program"]