Source code for jitx.shapes.hull

"""
Convex hulls of board elements
==============================

A :py:class:`ConvexHull` is a shape defined by board elements rather than
coordinates: the runtime evaluates it to the convex hull of the elements'
copper, and re-evaluates it when they move.
"""

from __future__ import annotations

from collections.abc import Iterable

from . import ShapeGeometry
from .primitive import Primitive




class ConvexHull(ShapeGeometry):
    """The convex hull of board elements, evaluated by the runtime.

    For now only accepted by interactive region requests
    (:py:meth:`~jitx.run.layout.SyncBatch.region`); a feature in code
    can't use it yet.

    >>> rd.layout.region(KeepOut(ConvexHull([u1, j1.p[1]], expand=0.5),
    ...                           LayerSet(0), pour=True))

    Args:
        anchors: The elements: pads, vias, control points, ports (every pad
            they map to), or components (all their pads).
        expand: Distance to grow the hull by, negative to shrink it; None for
            none.
    """

    anchors: tuple[object, ...]
    """The elements the hull is made from."""
    expand: float | None
    """Distance the hull is grown by, or None."""
    evaluated: Primitive | None
    """The hull as the runtime evaluated it, or None before it has."""

    def __init__(
        self,
        anchors: Iterable[object],
        expand: float | None = None,
        *,
        evaluated: Primitive | None = None,
    ):
        super().__init__()
        self.anchors = tuple(anchors)
        self.expand = expand
        self.evaluated = evaluated



    def to_primitive(self) -> Primitive:
        """The evaluated hull.

        Raises:
            ValueError: if the runtime has not evaluated the hull.
        """
        if self.evaluated is None:
            raise ValueError(
                "a ConvexHull is evaluated by the runtime; it can't be used "
                "before the runtime reports it"
            )
        return self.evaluated


    def __repr__(self):
        return f"ConvexHull({len(self.anchors)} anchors, expand={self.expand})"