# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
import numpy
import raygeo
import typing
__all__ = [
    "RasterSpec",
    "raster",
]

@typing.final
class RasterSpec:
    r"""
    Parameters for the ``raster`` assembler.
    
    Construct with ``RasterSpec(mode, line_interval_mm, ...)``. The
    optional ``alpha`` buffer is set via the ``alpha`` keyword. Wrap
    in an :class:`~raygeo.ops.assembly.Assembler` instance to drive
    the `Assembler` trait.
    """
    @property
    def mode(self) -> builtins.str: ...
    @property
    def line_interval_mm(self) -> builtins.float: ...
    @property
    def sample_interval_mm(self) -> builtins.float: ...
    @property
    def min_power(self) -> builtins.float: ...
    @property
    def max_power(self) -> builtins.float: ...
    @property
    def step_power(self) -> builtins.float: ...
    @property
    def num_power_levels(self) -> builtins.int: ...
    @property
    def angle(self) -> builtins.float: ...
    @property
    def offset_x_mm(self) -> builtins.float: ...
    @property
    def offset_y_mm(self) -> builtins.float: ...
    @property
    def scan_mode(self) -> builtins.str: ...
    @property
    def cross_hatch(self) -> builtins.bool: ...
    @property
    def num_depth_levels(self) -> builtins.int: ...
    @property
    def z_step_down(self) -> builtins.float: ...
    @property
    def angle_increment(self) -> builtins.float: ...
    @property
    def dot_width_correction_mm(self) -> builtins.float:
        r"""
        Compensates for the physical width of the laser spot by
        delaying laser-on and advancing laser-off by this distance
        at each end of every continuous engraved run.
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __new__(cls, mode: builtins.str = 'power_modulated', line_interval_mm: builtins.float = 0.1, sample_interval_mm: builtins.float = 0.05, min_power: builtins.float = 0.0, max_power: builtins.float = 1.0, step_power: builtins.float = 0.1, num_power_levels: builtins.int = 10, angle: builtins.float = 0.0, offset_x_mm: builtins.float = 0.0, offset_y_mm: builtins.float = 0.0, scan_mode: builtins.str = 'segmented', cross_hatch: builtins.bool = False, num_depth_levels: builtins.int = 5, z_step_down: builtins.float = 0.0, angle_increment: builtins.float = 0.0, dot_width_correction_mm: builtins.float = 0.0, alpha: typing.Optional[typing.Sequence[builtins.int]] = None) -> RasterSpec: ...

def raster(part: raygeo.ops.part.Part, alpha: numpy.ndarray | None = None, mode: str = 'power_modulated', line_interval_mm: float = 0.1, sample_interval_mm: float = 0.05, min_power: float = 0, max_power: float = 1, step_power: float = 0.1, num_power_levels: int = 10, angle: float = 0, offset_x_mm: float = 0, offset_y_mm: float = 0, scan_mode: str = 'segmented', cross_hatch: bool = False, num_depth_levels: int = 5, z_step_down: float = 0, angle_increment: float = 0, dot_width_correction_mm: float = 0) -> raygeo.ops.assembly.AssemblyResult:
    r"""
    Rasterise a part image into scan paths.
    
    Reads the pixel image from ``part.image`` (a 2-D uint8 numpy
    array) and converts it into scan-line toolpath commands.
    
    Three modes are supported:
    
    * ``"power_modulated"`` *(default)* — uses grayscale + alpha
      channels to produce power-modulated scan lines.
    * ``"mask_scan"`` — treats the image as a binary mask and
      produces scan-line segments with constant power.  Also used
      for ``"dither"`` — the caller pre-ditheres the image and
      stores it on ``part.image`` as a binary mask.
    * ``"multi_pass"`` — decomposes the grayscale image into
      *num_depth_levels* layers, rasterising each at a progressive
      Z offset.
    
    When *cross_hatch* is True the scan is run twice — once at
    *angle* and once at *angle* + 90° — and the results are
    concatenated.
    
    :param part: Part providing pixel density, size metadata, and
        the image buffer (``part.image``).
    :param alpha: Optional 2-D alpha mask (uint8). Required for
        ``power_modulated`` mode when the image is not pre-masked.
    :param mode: ``"power_modulated"``, ``"mask_scan"``, or
        ``"multi_pass"``.
    :param line_interval_mm: Spacing between scan lines in mm.
    :param sample_interval_mm: Power sampling interval along a scan
        line in mm (power_modulated only).
    :param min_power: Minimum laser power (0–1).
    :param max_power: Maximum laser power (0–1).
    :param step_power: Power step per level.
    :param num_power_levels: Number of discrete power levels.
    :param angle: Scan angle in degrees.
    :param offset_x_mm: Global X offset in mm.
    :param offset_y_mm: Global Y offset in mm.
    :param scan_mode: ``"segmented"`` or ``"full_sweep"``.
    :param cross_hatch: If True, add a second pass at angle + 90°
        (default False).
    :param num_depth_levels: Number of depth layers (multi_pass only,
        default 5).
    :param z_step_down: Z decrement per depth layer in mm
        (multi_pass only, default 0.0).
    :param angle_increment: Angle added per depth layer in degrees
        (multi_pass only, default 0.0).
    :param dot_width_correction_mm: Shortens laser firing by this
        distance at each end of every engraved run, to compensate
        for the physical width of the laser spot. Geometry is
        unaffected. ``power_modulated``/``mask_scan``/``dither``
        only.
    :returns: An :class:`AssemblyResult` with the raster path.
    :raises ValueError: If the mode is unknown, required data is
        missing, or ``part.image`` is None.
    """

