engeom 0.1.1__cp38-abi3-macosx_11_0_arm64.whl → 0.2.1__cp38-abi3-macosx_11_0_arm64.whl

engeom/geom3.pyi

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Tuple
+from typing import Tuple, Iterable, List, TypeVar
 
 import numpy
+from engeom import DeviationMode, Resample
 
-from engeom import DeviationMode
-
-type Transformable3 = Vector3 | Point3 | Plane3 | Iso3
+Transformable3 = TypeVar("Transformable3", Vector3, Point3, Plane3, Iso3, SurfacePoint3)
+PointOrVector3 = TypeVar("PointOrVector3", Vector3, Point3)
 
 
 class Vector3:
@@ -32,10 +32,13 @@ class Vector3:
     def z(self) -> float:
         ...
 
+    def __iter__(self) -> Iterable[float]:
+        ...
+
     def __rmul__(self, other: float) -> Vector3:
         ...
 
-    def __add__(self, other: Vector3 | Point3) -> Vector3 | Point3:
+    def __add__(self, other: PointOrVector3) -> PointOrVector3:
         ...
 
     def __sub__(self, other: Vector3) -> Vector3:
@@ -53,6 +56,42 @@ class Vector3:
         """
         ...
 
+    def dot(self, other: Vector3) -> float:
+        """
+        Calculate the dot product of this vector with another vector.
+        :param other: the other vector to calculate the dot product with.
+        :return: the dot product of the two vectors.
+        """
+        ...
+
+    def cross(self, other: Vector3) -> Vector3:
+        """
+        Calculate the cross product of this vector with another vector.
+        :param other: the other vector to calculate the cross product with.
+        :return: the cross product of the two vectors.
+        """
+        ...
+
+    def norm(self) -> float:
+        """
+        Calculate the norm (length) of the vector.
+        :return:
+        """
+
+    def normalized(self) -> Vector3:
+        """
+        Return a normalized version of the vector.
+        :return: a new vector that has unit length
+        """
+
+    def angle_to(self, other: Vector3) -> float:
+        """
+        Calculate the smallest angle between this vector and another vector.
+        :param other: the other vector to calculate the angle to.
+        :return: the angle between the two vectors in radians.
+        """
+        ...
+
 
 class Point3:
     def __init__(self, x: float, y: float, z: float):
@@ -76,6 +115,9 @@ class Point3:
     def z(self) -> float:
         ...
 
+    def __iter__(self) -> Iterable[float]:
+        ...
+
     @property
     def coords(self) -> Vector3:
         """
@@ -84,7 +126,7 @@ class Point3:
         """
         ...
 
-    def __sub__(self, other: Vector3 | Point3) -> Vector3 | Point3:
+    def __sub__(self, other: PointOrVector3) -> PointOrVector3:
         ...
 
     def __add__(self, other: Vector3) -> Vector3:
@@ -97,6 +139,90 @@ class Point3:
         ...
 
 
+class SurfacePoint3:
+    def __init__(self, x: float, y: float, z: float, nx: float, ny: float, nz: float):
+        """
+
+        :param x:
+        :param y:
+        :param z:
+        :param nx:
+        :param ny:
+        :param nz:
+        """
+        ...
+
+    @property
+    def point(self) -> Point3:
+        """
+        Get the coordinates of the point as a Point3 object.
+        :return: a Point3 object
+        """
+        ...
+
+    @property
+    def normal(self) -> Vector3:
+        """
+        Get the normal of the point as a Vector3 object.
+        :return: a Vector3 object
+        """
+        ...
+
+    def at_distance(self, distance: float) -> Point3:
+        """
+        Get the point at a distance along the normal from the surface point.
+        :param distance: the distance to move along the normal.
+        :return: the point at the distance along the normal.
+        """
+        ...
+
+    def scalar_projection(self, point: Point3) -> float:
+        """
+        Calculate the scalar projection of a point onto the axis defined by the surface point position and direction.
+        Positive values indicate that the point is in the normal direction from the surface point, while negative values
+        indicate that the point is in the opposite direction.
+
+        :param point: the point to calculate the projection of.
+        :return: the scalar projection of the point onto the normal.
+        """
+        ...
+
+    def projection(self, point: Point3) -> Point3:
+        """
+        Calculate the projection of a point onto the axis defined by the surface point position and direction.
+
+        :param point: the point to calculate the projection of.
+        :return: the projection of the point onto the plane.
+        """
+        ...
+
+    def reversed(self) -> SurfacePoint3:
+        """
+        Return a new surface point with the normal vector inverted, but the position unchanged.
+        :return: a new surface point with the inverted normal vector.
+        """
+        ...
+
+    def planar_distance(self, point: Point3) -> float:
+        """
+        Calculate the planar (non-normal) distance between the surface point and a point. This is complementary to the
+        scalar projection. A point is projected onto the plane defined by the position and normal of the surface point,
+        and the distance between the surface point position and the projected point is returned.  The value will always
+        be positive.
+
+        :param point: the point to calculate the distance to.
+        :return: the planar distance between the surface point and the point.
+        """
+        ...
+
+    def get_plane(self) -> Plane3:
+        """
+        Get the plane defined by the surface point.
+        :return: the plane defined by the surface point.
+        """
+        ...
+
+
 class Iso3:
     """ An isometry (rigid body transformation) in 3D space. """
 
@@ -183,7 +309,11 @@ class SvdBasis3:
     fitting basis for the points using a singular value decomposition.
     """
 
-    def __init__(self, points: numpy.ndarray[float], weights: numpy.ndarray[float] | None):
+    def __init__(
+            self,
+            points: numpy.ndarray[float],
+            weights: numpy.ndarray[float] | None = None
+    ):
         """
         Create a basis from a set of points. The basis will be calculated using a singular value decomposition of the
         points.
@@ -305,6 +435,8 @@ class Mesh:
             self,
             vertices: numpy.ndarray[float],
             triangles: numpy.ndarray[numpy.uint32],
+            merge_duplicates: bool = False,
+            delete_degenerate: bool = False
     ):
         """
         Create an engeom mesh from vertices and triangles.  The vertices should be a numpy array of shape (n, 3), while
@@ -314,16 +446,26 @@ class Mesh:
 
         :param vertices: a numpy array of shape (n, 3) containing the vertices of the mesh.
         :param triangles: a numpy array of shape (m, 3) containing the triangles of the mesh, should be uint.
+        :param merge_duplicates: merge duplicate vertices and triangles
+        :param delete_degenerate: delete degenerate triangles
         """
         ...
 
+    @property
+    def aabb(self) -> Aabb3:
+        """ Return the axis-aligned bounding box of the mesh. """
+        ...
+
     @staticmethod
-    def load_stl(path: str | Path) -> Mesh:
+    def load_stl(path: str | Path, merge_duplicates: bool = False, delete_degenerate: bool = False) -> Mesh:
         """
         Load a mesh from an STL file. This will return a new mesh object containing the vertices and triangles from the
-        file.
+        file.  Optional parameters can be used to control the behavior of the loader when handling duplicate vertices/
+        triangles and degenerate triangles.
 
         :param path: the path to the STL file to load.
+        :param merge_duplicates: merge duplicate vertices and triangles. If None, the default behavior is to do nothing
+        :param delete_degenerate: delete degenerate triangles. If None, the default behavior is to do nothing
         :return: the mesh object containing the data from the file.
         """
         ...
@@ -337,7 +479,7 @@ class Mesh:
         """
         ...
 
-    def clone(self) -> Mesh:
+    def cloned(self) -> Mesh:
         """
         Will return a copy of the mesh. This is a copy of the data, so modifying the returned mesh will not modify the
         original mesh.
@@ -363,21 +505,18 @@ class Mesh:
         """
         ...
 
-    def clone_vertices(self) -> numpy.ndarray[float]:
+    @property
+    def points(self) -> numpy.ndarray[float]:
         """
-        Will return a copy of the vertices of the mesh as a numpy array. If the mesh has not been modified, this will
-        be the same as the original vertices. This is a copy of the data, so modifying the returned array will not
-        modify the mesh.
+        Will return an immutable view of the vertices of the mesh as a numpy array of shape (n, 3).
         :return: a numpy array of shape (n, 3) containing the vertices of the mesh.
         """
         ...
 
-    def clone_triangles(self) -> numpy.ndarray[numpy.uint32]:
+    @property
+    def triangles(self) -> numpy.ndarray[numpy.uint32]:
         """
-        Will return a copy of the triangles of the mesh as a numpy array. If the mesh has not been modified, this will
-        be the same as the original triangles. This is a copy of the data, so modifying the returned array will not
-        modify the mesh.
-
+        Will return an immutable view of the triangles of the mesh as a numpy array of shape (m, 3).
         :return: a numpy array of shape (m, 3) containing the triangles of the mesh.
         """
         ...
@@ -423,3 +562,204 @@ class Mesh:
         :return: a numpy array of shape (n, 6) containing the sampled points.
         """
         ...
+
+    def section(self, plane: Plane3, tol: float | None = None) -> List[Curve3]:
+        """
+        Calculate and return the intersection curves between the mesh and a plane.
+
+        :param plane:
+        :param tol:
+        :return:
+        """
+        ...
+
+
+class CurveStation3:
+    """
+    A class representing a station along a curve in 3D space. The station is represented by a point on the curve, a
+    tangent (direction) vector, and a length along the curve.
+    """
+
+    @property
+    def point(self) -> Point3:
+        """ The 3d position in space on the curve. """
+        ...
+
+    @property
+    def direction(self) -> Vector3:
+        """ The tangent (direction) vector of the curve at the station. """
+        ...
+
+    @property
+    def direction_point(self) -> SurfacePoint3:
+        """
+        A `SurfacePoint3` object representing the point on the curve and the curve's tangent/direction vector.
+        """
+        ...
+
+    @property
+    def index(self) -> int:
+        """ The index of the previous vertex on the curve, at or before the station. """
+        ...
+
+    @property
+    def length_along(self) -> float:
+        """ The length along the curve from the start of the curve to the station. """
+        ...
+
+
+class Curve3:
+    """
+    A class representing a polyline in 3D space. The curve is represented by a set of vertices and the segments
+    between them.
+    """
+
+    def __init__(self, vertices: numpy.ndarray, tol: float = 1.0e-6):
+        """
+        Create a curve from a set of vertices. The vertices should be a numpy array of shape (n, 3).
+
+        :param vertices: a numpy array of shape (n, 3) containing the vertices of the curve.
+        :param tol: the inherent tolerance of the curve; points closer than this distance will be considered the same.
+        """
+        ...
+
+    def clone(self) -> Curve3:
+        """
+        Will return a copy of the curve. This is a copy of the data, so modifying the returned curve will not modify
+        the original curve.
+
+        :return: a copy of the curve.
+        """
+        ...
+
+    def length(self) -> float:
+        """
+        Return the total length of the curve in the units of the vertices.
+
+        :return: the length of the curve.
+        """
+        ...
+
+    @property
+    def points(self) -> numpy.ndarray[float]:
+        """
+        Will return an immutable view of the vertices of the mesh as a numpy array of shape (n, 3).
+        :return: a numpy array of shape (n, 3) containing the vertices of the mesh.
+        """
+        ...
+
+    def at_length(self, length: float) -> CurveStation3:
+        """
+        Return a station along the curve at the given length. The length is measured from the start of the curve to the
+        station. If the length is greater than the length of the curve or less than 0, an error will be raised.
+
+        :param length: the length along the curve to return the station at.
+        :return: a `CurveStation3` object representing the station along the curve.
+        """
+        ...
+
+    def at_fraction(self, fraction: float) -> CurveStation3:
+        """
+        Return a station along the curve at the given fraction of the length of the curve. If the fraction is greater
+        than 1 or less than 0, an error will be raised.
+
+        :param fraction: the fraction of the length of the curve to return the station at.
+        :return: a `CurveStation3` object representing the station along the curve.
+        """
+        ...
+
+    def at_closest_to_point(self, point: Point3) -> CurveStation3:
+        """
+        Return a station along the curve at the closest point to the given point. The station will be the point on the
+        curve that is closest to the given point.
+
+        :param point: the point to find the closest station to.
+        :return: a `CurveStation3` object representing the station along the curve.
+        """
+        ...
+
+    def at_front(self) -> CurveStation3:
+        """
+        Return a station at the front of the curve. This is equivalent to calling `at_length(0)`.
+
+        :return: a `CurveStation3` object representing the station at the front of the curve.
+        """
+        ...
+
+    def at_back(self) -> CurveStation3:
+        """
+        Return a station at the back of the curve. This is equivalent to calling `at_length(length)`.
+
+        :return: a `CurveStation3` object representing the station at the back of the curve.
+        """
+        ...
+
+    def resample(self, resample: Resample) -> Curve3:
+        """
+        Resample the curve using the given resampling method. The resampling method can be one of the following:
+
+        - `Resample.ByCount(count: int)`: resample the curve to have the given number of points.
+        - `Resample.BySpacing(distance: float)`: resample the curve to have points spaced by the given distance.
+        - `Resample.ByMaxSpacing(distance: float)`: resample the curve to have points spaced by a maximum distance.
+
+        :param resample: the resampling method to use.
+        :return: a new curve object with the resampled vertices.
+        """
+        ...
+
+    def simplify(self, tolerance: float) -> Curve3:
+        """
+        Simplify the curve using the Ramer-Douglas-Peucker algorithm. This will remove vertices from the curve that are
+        within the given tolerance of the line between the previous and next vertices.
+
+        :param tolerance: the tolerance to use when simplifying the curve.
+        :return: a new curve object with the simplified vertices.
+        """
+        ...
+
+    def transformed_by(self, iso: Iso3) -> Curve3:
+        """
+        Transform the curve by an isometry. This will return a new curve object with the transformed vertices.
+
+        :param iso: the isometry to transform the curve by.
+        :return: a new curve object with the transformed vertices.
+        """
+        ...
+
+
+class Aabb3:
+    """
+    A class representing an axis-aligned bounding box in 3D space. The box is defined by its minimum and maximum
+    """
+
+    def __init__(self, x_min: float, y_min: float, z_min: float, x_max: float, y_max: float, z_max: float):
+        """
+        Create an axis-aligned bounding box from the minimum and maximum coordinates.
+        :param x_min: the minimum x coordinate of the box.
+        :param y_min: the minimum y coordinate of the box.
+        :param z_min: the minimum z coordinate of the box.
+        :param x_max: the maximum x coordinate of the box.
+        :param y_max: the maximum y coordinate of the box.
+        :param z_max: the maximum z coordinate of the box.
+        """
+        ...
+
+    @property
+    def min(self) -> Point3:
+        """ The minimum point of the box. """
+        ...
+
+    @property
+    def max(self) -> Point3:
+        """ The maximum point of the box. """
+        ...
+
+    @property
+    def center(self) -> Point3:
+        """ The center point of the box. """
+        ...
+
+    @property
+    def extent(self) -> Vector3:
+        """ The extent of the box. """
+        ...

engeom/matplotlib.py

@@ -1,11 +1,49 @@
+from typing import List, Iterable, Tuple, Union
+from enum import Enum
+import matplotlib.lines
 import numpy
+from .geom2 import Curve2, Circle2, Aabb2, Point2, Vector2, SurfacePoint2
+from .metrology import Length2
+
+PlotCoords = Union[Point2, Vector2, Iterable[float]]
+
+
+class LabelPlace(Enum):
+    Outside = 1
+    Inside = 2
+    OutsideRev = 3
+
 
 try:
     from matplotlib.pyplot import Axes, Circle
+    from matplotlib.colors import ListedColormap
 except ImportError:
     pass
 else:
 
+    class GomColorMap(ListedColormap):
+        def __init__(self):
+            colors = numpy.array(
+                [
+                    [1, 0, 160],
+                    [1, 0, 255],
+                    [0, 254, 255],
+                    [0, 160, 0],
+                    [0, 254, 0],
+                    [255, 255, 0],
+                    [255, 128, 0],
+                    [255, 1, 0],
+                ],
+                dtype=numpy.float64,
+            )
+            colors /= 256.0
+            colors = numpy.hstack((colors, numpy.ones((len(colors), 1))))
+            super().__init__(colors)
+            self.set_under("magenta")
+            self.set_over("darkred")
+
+    GOM_CMAP = GomColorMap()
+
     def set_aspect_fill(ax: Axes):
         """
         Set the aspect ratio of a Matplotlib Axes (subplot) object to be 1:1 in x and y, while also having it expand
@@ -39,6 +77,164 @@ else:
             x_mid = (x0 + x1) / 2
             ax.set_xlim(x_mid - x_range / 2, x_mid + x_range / 2)
 
+    class AxesHelper:
+        def __init__(self, ax: Axes, skip_aspect=False, hide_axes=False):
+            self.ax = ax
+            if not skip_aspect:
+                ax.set_aspect("equal", adjustable="datalim")
+
+            if hide_axes:
+                ax.axis("off")
+
+        def set_bounds(self, box: Aabb2):
+            """
+            Set the bounds of a Matplotlib Axes object.
+            :param box: an Aabb2 object
+            :return: None
+            """
+            self.ax.set_xlim(box.min.x, box.max.x)
+            self.ax.set_ylim(box.min.y, box.max.y)
+
+        def plot_circle(self, *circle: Circle2 | Iterable[float], **kwargs):
+            """
+            Plot a circle on a Matplotlib Axes object.
+            :param circle: a Circle2 object
+            :param kwargs: keyword arguments to pass to the plot function
+            :return: None
+            """
+            from matplotlib.pyplot import Circle
+
+            for cdata in circle:
+                if isinstance(cdata, Circle2):
+                    c = Circle((cdata.center.x, cdata.center.y), cdata.r, **kwargs)
+                else:
+                    x, y, r, *_ = cdata
+                    c = Circle((x, y), r, **kwargs)
+                self.ax.add_patch(c)
+
+        def plot_curve(self, curve: Curve2, **kwargs):
+            """
+            Plot a curve on a Matplotlib Axes object.
+            :param curve: a Curve2 object
+            :param kwargs: keyword arguments to pass to the plot function
+            :return: None
+            """
+            self.ax.plot(curve.points[:, 0], curve.points[:, 1], **kwargs)
+
+        def dimension(
+            self,
+            length: Length2,
+            side_shift: float = 0,
+            format: str = "{value:.3f}",
+            fontsize: int = 10,
+            label_place: LabelPlace = LabelPlace.Outside,
+            label_offset: float | None = None,
+            fontname: str | None = None,
+        ):
+            """
+            Plot a Length2 object on a Matplotlib Axes object.
+            :param side_shift:
+            :param length: a Length2 object
+            :return: None
+            """
+            from matplotlib.pyplot import Line2D
+
+            pad_scale = self._font_height(12) * 1.5
+            center = length.center.shift_orthogonal(side_shift)
+            leader_a = center.projection(length.a)
+            leader_b = center.projection(length.b)
 
+            if label_place == LabelPlace.Inside:
+                label_offset = label_offset or 0.0
+                label_coords = center.at_distance(label_offset)
+                self.arrow(label_coords, leader_a)
+                self.arrow(label_coords, leader_b)
+            elif label_place == LabelPlace.Outside:
+                label_offset = label_offset or pad_scale * 3
+                label_coords = leader_b + length.direction * label_offset
+                self.arrow(leader_a - length.direction * pad_scale, leader_a)
+                self.arrow(label_coords, leader_b)
+            elif label_place == LabelPlace.OutsideRev:
+                label_offset = label_offset or pad_scale * 3
+                label_coords = leader_a - length.direction * label_offset
+                self.arrow(leader_b + length.direction * pad_scale, leader_b)
+                self.arrow(label_coords, leader_a)
 
+            # Do we need sideways leaders?
+            self._line_if_needed(pad_scale, length.a, leader_a)
+            self._line_if_needed(pad_scale, length.b, leader_b)
 
+            kwargs = {"ha": "center", "va": "center", "fontsize": fontsize}
+            if fontname is not None:
+                kwargs["fontname"] = fontname
+
+            result = self.annotate_text_only(
+                format.format(value=length.value),
+                label_coords,
+                bbox=dict(boxstyle="round,pad=0.3", ec="black", fc="white"),
+                **kwargs,
+            )
+
+        def _line_if_needed(self, pad: float, actual: Point2, leader_end: Point2):
+            half_pad = pad * 0.5
+            v: Vector2 = leader_end - actual
+            if v.norm() < half_pad:
+                return
+            work = SurfacePoint2(*actual, *v)
+            t1 = work.scalar_projection(leader_end) + half_pad
+            self.arrow(actual, work.at_distance(t1), arrow="-")
+
+        def annotate_text_only(self, text: str, pos: PlotCoords, **kwargs):
+            """
+            Annotate a Matplotlib Axes object with text only.
+            :param text: the text to annotate
+            :param pos: the position of the annotation
+            :param kwargs: keyword arguments to pass to the annotate function
+            :return: None
+            """
+            return self.ax.annotate(text, xy=_tuplefy(pos), **kwargs)
+
+        def arrow(self, start: PlotCoords, end: PlotCoords, arrow="-|>"):
+            """
+            Plot an arrow on a Matplotlib Axes object.
+            :param start: the start point of the arrow
+            :param end: the end point of the arrow
+            :param kwargs: keyword arguments to pass to the arrow function
+            :return: None
+            """
+            self.ax.annotate(
+                "",
+                xy=_tuplefy(end),
+                xytext=_tuplefy(start),
+                arrowprops=dict(arrowstyle=arrow, fc="black"),
+            )
+
+        def _font_height(self, font_size: int) -> float:
+            """Get the height of a font in data units."""
+            fig_dpi = self.ax.figure.dpi
+            font_height_inches = font_size * 1.0 / 72.0
+            font_height_px = font_height_inches * fig_dpi
+
+            px_per_data = self._get_scale()
+            return font_height_px / px_per_data
+
+        def _get_scale(self) -> float:
+            """Get the scale of the plot in data units per pixel."""
+            x0, x1 = self.ax.get_xlim()
+            y0, y1 = self.ax.get_ylim()
+
+            bbox = self.ax.get_window_extent()
+            width, height = bbox.width, bbox.height
+
+            # Units are pixels per data unit
+            x_scale = width / (x1 - x0)
+            y_scale = height / (y1 - y0)
+
+            return min(x_scale, y_scale)
+
+    def _tuplefy(item: PlotCoords) -> Tuple[float, float]:
+        if isinstance(item, (Point2, Vector2)):
+            return item.x, item.y
+        else:
+            x, y, *_ = item
+            return x, y

engeom/metrology/__init__.py

@@ -0,0 +1,5 @@
+from ..engeom import _metrology
+
+# Global import of all functions
+for name in [n for n in dir(_metrology) if not n.startswith("_")]:
+    globals()[name] = getattr(_metrology, name)