engeom 0.2.4__cp38-abi3-win_amd64.whl → 0.2.6__cp38-abi3-win_amd64.whl

engeom/_plot/__init__.py

@@ -0,0 +1 @@
+from .common import LabelPlace

engeom/_plot/common.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+class LabelPlace(Enum):
+    """
+    Represents the different locations where a label can be placed between its anchor points.
+    """
+
+    Outside = 1
+    """ The label is placed outside the anchor points, on the side of the second point in the measurement. """
+
+    Inside = 2
+    """ The label is placed between the two anchor points. """
+
+    OutsideRev = 3
+    """ The label is placed outside the two anchor points, on the side of the first point in the measurement. """
+
+

engeom/{matplotlib.py → _plot/matplotlib.py}

@@ -1,19 +1,11 @@
 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
+from .common import LabelPlace
+from engeom.geom2 import Curve2, Circle2, Aabb2, Point2, Vector2, SurfacePoint2
+from engeom.metrology import Distance2
 
 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
@@ -22,6 +14,12 @@ except ImportError:
 else:
 
     class GomColorMap(ListedColormap):
+        """
+        A color map similar to the 8 discrete colors in the GOM/Zeiss Inspect software.
+
+        You can use this to instantiate a color map, or you can use the `GOM_CMAP` object directly.
+        """
+
         def __init__(self):
             colors = numpy.array(
                 [
@@ -42,7 +40,13 @@ else:
             self.set_under("magenta")
             self.set_over("darkred")
 
+
     GOM_CMAP = GomColorMap()
+    """
+    A color map similar to the 8 discrete colors in the GOM/Zeiss Inspect software, already instantiated and
+    available in the module.
+    """
+
 
     def set_aspect_fill(ax: Axes):
         """
@@ -77,8 +81,30 @@ else:
             x_mid = (x0 + x1) / 2
             ax.set_xlim(x_mid - x_range / 2, x_mid + x_range / 2)
 
-    class AxesHelper:
+
+    class MatplotlibAxesHelper:
+        """
+        A helper class for working with Matplotlib. It wraps around a Matplotlib `Axes` object and provides direct
+        methods for plotting some `engeom` entities.  It also enforces the aspect ratio to be 1:1 and expands the
+        subplot to fill its available space.
+
+        !!! example
+            ```python
+            from matplotlib.pyplot import figure
+            fig = figure()
+            ax = fig.subplots()
+            helper = MatplotlibAxesHelper(ax)
+            ```
+        """
+
         def __init__(self, ax: Axes, skip_aspect=False, hide_axes=False):
+            """
+            Initialize the helper with a Matplotlib `Axes` object.
+            :param ax: The Matplotlib `Axes` object to wrap around.
+            :param skip_aspect: Set this to true to skip enforcing the aspect ratio to be 1:1.
+            :param hide_axes: Set this to true to hide the axes.
+            """
+
             self.ax = ax
             if not skip_aspect:
                 ax.set_aspect("equal", adjustable="datalim")
@@ -90,7 +116,6 @@ else:
             """
             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)
@@ -100,7 +125,6 @@ else:
             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
 
@@ -117,24 +141,45 @@ else:
             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,
-            template: str = "{value:.3f}",
-            fontsize: int = 10,
-            label_place: LabelPlace = LabelPlace.Outside,
-            label_offset: float | None = None,
-            fontname: str | None = None,
+        def distance(
+                self,
+                distance: Distance2,
+                side_shift: float = 0,
+                template: str = "{value:.3f}",
+                fontsize: int = 10,
+                label_place: LabelPlace = LabelPlace.Outside,
+                label_offset: float | None = None,
+                fontname: str | None = None,
+                scale_value: float = 1.0,
         ):
+            """
+            Plot a `Distance2` object on a Matplotlib Axes, drawing the leader lines and adding a text label with the
+            distance value.
+            :param distance: The `Distance2` object to plot.
+            :param side_shift: Shift the ends of the leader lines by this amount of data units. The direction of the
+            shift is orthogonal to the distance direction, with positive values shifting to the right.
+            :param template: The format string to use for the distance label. The default is "{value:.3f}".
+            :param fontsize: The font size to use for the label.
+            :param label_place: The placement of the label.
+            :param label_offset: The distance offset to use for the label. Will have different meanings depending on
+            the `label_place` parameter.
+            :param fontname: The name of the font to use for the label.
+            :param scale_value: A scaling factor to apply to the value before displaying it in the label. Use this to
+            convert between different units of measurement without having to modify the actual value or the coordinate
+            system.
+            """
             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)
+
+            # The offset_dir is the direction from `a` to `b` projected so that it's parallel to the measurement
+            # direction.
+            offset_dir = distance.direction if distance.value >= 0 else -distance.direction
+            center = SurfacePoint2(*distance.center.point, *offset_dir)
+            center = center.shift_orthogonal(side_shift)
+            leader_a = center.projection(distance.a)
+            leader_b = center.projection(distance.b)
 
             if label_place == LabelPlace.Inside:
                 label_offset = label_offset or 0.0
@@ -143,29 +188,26 @@ else:
                 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)
+                label_coords = leader_b + offset_dir * label_offset
+                self.arrow(leader_a - offset_dir * 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)
+                label_coords = leader_a - offset_dir * label_offset
+                self.arrow(leader_b + offset_dir * 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)
+            self._line_if_needed(pad_scale, distance.a, leader_a)
+            self._line_if_needed(pad_scale, distance.b, leader_b)
 
             kwargs = {"ha": "center", "va": "center", "fontsize": fontsize}
             if fontname is not None:
                 kwargs["fontname"] = fontname
 
-            result = self.annotate_text_only(
-                template.format(value=length.value),
-                label_coords,
-                bbox=dict(boxstyle="round,pad=0.3", ec="black", fc="white"),
-                **kwargs,
-            )
+            value = distance.value * scale_value
+            box_style = dict(boxstyle="round,pad=0.3", ec="black", fc="white")
+            self.annotate_text_only(template.format(value=value), label_coords, bbox=box_style, **kwargs)
 
         def _line_if_needed(self, pad: float, actual: Point2, leader_end: Point2):
             half_pad = pad * 0.5
@@ -182,7 +224,7 @@ else:
             :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: the annotation object
             """
             return self.ax.annotate(text, xy=_tuplefy(pos), **kwargs)
 
@@ -191,10 +233,10 @@ else:
             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
+            :param arrow: the style of arrow to use
+            :return: the annotation object
             """
-            self.ax.annotate(
+            return self.ax.annotate(
                 "",
                 xy=_tuplefy(end),
                 xytext=_tuplefy(start),
@@ -202,7 +244,7 @@ else:
             )
 
         def _font_height(self, font_size: int) -> float:
-            """Get the height of a font in data units."""
+            # 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
@@ -211,7 +253,7 @@ else:
             return font_height_px / px_per_data
 
         def _get_scale(self) -> float:
-            """Get the scale of the plot in data units per pixel."""
+            # Get the scale of the plot in data units per pixel.
             x0, x1 = self.ax.get_xlim()
             y0, y1 = self.ax.get_ylim()
 
@@ -224,6 +266,7 @@ else:
 
             return min(x_scale, y_scale)
 
+
 def _tuplefy(item: PlotCoords) -> Tuple[float, float]:
     if isinstance(item, (Point2, Vector2)):
         return item.x, item.y

engeom/_plot/pyvista.py

@@ -0,0 +1,256 @@
+"""
+This module contains helper functions for working with PyVista.
+"""
+
+from __future__ import annotations
+
+from typing import List, Any, Dict, Union, Iterable, Tuple
+
+import numpy
+
+from engeom.geom3 import Mesh, Curve3, Vector3, Point3, Iso3, SurfacePoint3
+from engeom.metrology import Distance3
+from .common import LabelPlace
+
+PlotCoords = Union[Point3, Vector3, Iterable[float]]
+
+try:
+    import pyvista
+except ImportError:
+    pass
+else:
+    class PyvistaPlotterHelper:
+        """
+        A helper class for working with PyVista. It wraps around a PyVista `Plotter` object and provides direct methods
+        for plotting some `engeom` entities.
+
+        !!! example
+            ```python
+            import pyvista
+            plotter = pyvista.Plotter()
+            helper = PyvistaPlotterHelper(plotter)
+            ```
+        """
+
+        def __init__(self, plotter: pyvista.Plotter):
+            """
+            Initialize the helper with a PyVista `Plotter` object.
+
+            :param plotter: The PyVista `Plotter` object to wrap around.
+            """
+            self.plotter = plotter
+
+        def add_curves(
+                self,
+                *curves: Curve3,
+                color: pyvista.ColorLike = "w",
+                width: float = 3.0,
+                label: str | None = None,
+                name: str | None = None,
+        ) -> pyvista.vtkActor:
+            """
+            Add one or more curves to be plotted.
+            :param curves: The curves to add.
+            :param color: The color to use for the curve(s).
+            :param width: The line width to use for the curve(s).
+            :param label: The label to use for the curve(s) if a legend is present.
+            :param name: The name to use for the actor in the scene.
+            :return: The PyVista actor that was added to the plotter.
+            """
+            curve_vertices = []
+            for curve in curves:
+                b = curve.points[1:-1]
+                c = numpy.zeros((len(curve.points) + len(b), 3), dtype=curve.points.dtype)
+                c[0::2, :] = curve.points[0:-1]
+                c[1:-1:2, :] = b
+                c[-1] = curve.points[-1]
+                curve_vertices.append(c)
+
+            vertices = numpy.concatenate(curve_vertices, axis=0)
+            return self.plotter.add_lines(
+                vertices,
+                color=color,
+                width=width,
+                label=label,
+                name=name,
+            )
+
+        def add_mesh(self, mesh: Mesh, **kwargs) -> pyvista.vtkActor:
+            """
+            Add an `engeom` mesh to be plotted. Additional keyword arguments will be passed directly to the PyVista
+            `Plotter.add_mesh` method, allowing for customization of the mesh appearance.
+
+            :param mesh: The mesh object to add to the plotter scene
+            :return: The PyVista actor that was added to the plotter.
+            """
+            if "cmap" in kwargs:
+                cmap_extremes = _cmap_extremes(kwargs["cmap"])
+                kwargs.update(cmap_extremes)
+
+            prefix = numpy.ones((mesh.faces.shape[0], 1), dtype=mesh.faces.dtype)
+            faces = numpy.hstack((prefix * 3, mesh.faces))
+            data = pyvista.PolyData(mesh.vertices, faces)
+            return self.plotter.add_mesh(data, **kwargs)
+
+        def distance(
+                self,
+                distance: Distance3,
+                template: str = "{value:.3f}",
+                label_place: LabelPlace = LabelPlace.Outside,
+                label_offset: float | None = None,
+                font_size: int = 12,
+                scale_value: float = 1.0,
+                font_family=None,
+        ):
+            """
+            Add a distance entity to the plotter.
+            :param distance: The distance entity to add.
+            :param template: A format string to use for the label. The `value` key will be replaced with the actual
+            value read from the measurement.
+            :param label_place: The placement of the label relative to the distance entity's anchor points.
+            :param label_offset: The distance offset to use for the label. Will have different meanings depending on
+            the `label_place` parameter.
+            :param font_size: The size of the text to use for the label.
+            :param scale_value: A scaling factor to apply to the value before displaying it in the label. Use this to
+            convert between different units of measurement without having to modify the actual value or the coordinate
+            system.
+            :param font_family: The font family to use for the label.
+            """
+            label_offset = label_offset or max(abs(distance.value), 1.0) * 3
+
+            # The offset_dir is the direction from `a` to `b` projected so that it's parallel to the measurement
+            # direction.
+            offset_dir = distance.direction if distance.value >= 0 else -distance.direction
+
+            # Rather than arrows, we'll use spheres to indicate the anchor points at the end of the leader lines
+            spheres = [distance.a, distance.b]
+            builder = LineBuilder()
+
+            if label_place == LabelPlace.Inside:
+                c = SurfacePoint3(*distance.center.point, *offset_dir)
+                label_coords = c.at_distance(label_offset)
+
+                builder.add(distance.a)
+                builder.add(distance.a - offset_dir * label_offset * 0.25)
+                builder.skip()
+
+                builder.add(distance.b)
+                builder.add(distance.b + offset_dir * label_offset * 0.25)
+
+            elif label_place == LabelPlace.Outside:
+                label_coords = distance.b + offset_dir * label_offset
+
+                builder.add(distance.a)
+                builder.add(distance.a - offset_dir * label_offset * 0.25)
+                builder.skip()
+
+                builder.add(distance.b)
+                builder.add(label_coords)
+
+            elif label_place == LabelPlace.OutsideRev:
+                label_coords = distance.a - offset_dir * label_offset
+
+                builder.add(distance.b)
+                builder.add(distance.b + offset_dir * label_offset * 0.25)
+                builder.skip()
+
+                builder.add(distance.a)
+                builder.add(label_coords)
+
+            points = numpy.array([_tuplefy(p) for p in spheres], dtype=numpy.float64)
+            self.plotter.add_points(points, color="black", point_size=4, render_points_as_spheres=True)
+
+            lines = builder.build()
+            self.plotter.add_lines(lines, color="black", width=1.5)
+
+            value = distance.value * scale_value
+            self.plotter.add_point_labels(
+                [_tuplefy(label_coords)],
+                [template.format(value=value)],
+                show_points=False,
+                background_color="white",
+                font_family=font_family,
+                # justification_vertical="center",
+                # justification_horizontal="center",
+                font_size=font_size,
+                bold=False,
+            )
+
+        def coordinate_frame(self, iso: Iso3, size: float = 1.0):
+            """
+            Add a coordinate frame to the plotter.  This will appear as three lines, with X in red, Y in green,
+            and Z in blue.  The length of each line is determined by the `size` parameter.
+            :param iso: The isometry to use as the origin and orientation of the coordinate frame.
+            :param size: The length of each line in the coordinate frame.
+            """
+            points = numpy.array([[0, 0, 0], [size, 0, 0], [0, size, 0], [0, 0, size]], dtype=numpy.float64)
+            points = iso.transform_points(points)
+
+            self.plotter.add_lines(points[[0, 1]], color="red", width=5.0)
+            self.plotter.add_lines(points[[0, 2]], color="green", width=5.0)
+            self.plotter.add_lines(points[[0, 3]], color="blue", width=5.0)
+
+        def label(self, point: PlotCoords, text: str, **kwargs):
+            """
+            Add a text label to the plotter.
+            :param point: The position of the label in 3D space.
+            :param text: The text to display in the label.
+            :param kwargs: Additional keyword arguments to pass to the `pyvista.Label` constructor.
+            """
+            label = pyvista.Label(text=text, position=_tuplefy(point), **kwargs)
+            self.plotter.add_actor(label)
+
+        def arrow(self, start: PlotCoords, direction: PlotCoords,
+                  tip_length: float = 0.25,
+                  tip_radius: float = 0.1,
+                  shaft_radius: float = 0.05,
+                  **kwargs):
+            pd = pyvista.Arrow(_tuplefy(start), _tuplefy(direction), tip_length=tip_length, tip_radius=tip_radius,
+                               shaft_radius=shaft_radius)
+            self.plotter.add_mesh(pd, **kwargs, color="black")
+
+
+    def _cmap_extremes(item: Any) -> Dict[str, pyvista.ColorLike]:
+        working = {}
+        try:
+            from matplotlib.colors import Colormap
+        except ImportError:
+            return working
+        else:
+            if isinstance(item, Colormap):
+                over = getattr(item, "_rgba_over", None)
+                under = getattr(item, "_rgba_under", None)
+                if over is not None:
+                    working["above_color"] = over
+                if under is not None:
+                    working["below_color"] = under
+            return working
+
+
+class LineBuilder:
+    def __init__(self):
+        self.vertices = []
+        self._skip = 1
+
+    def add(self, points: PlotCoords):
+        if self.vertices:
+            if self._skip > 0:
+                self._skip -= 1
+            else:
+                self.vertices.append(self.vertices[-1])
+
+        self.vertices.append(_tuplefy(points))
+
+    def skip(self):
+        self._skip = 2
+
+    def build(self) -> numpy.ndarray:
+        return numpy.array(self.vertices, dtype=numpy.float64)
+
+
+def _tuplefy(item: PlotCoords) -> Tuple[float, float, float]:
+    if isinstance(item, (Point3, Vector3)):
+        return item.x, item.y, item.z
+    else:
+        x, y, z, *_ = item
+        return x, y, z

engeom/airfoil/__init__.py

@@ -1,3 +1,7 @@
+"""
+This module contains a number of tools to help analyze airfoil geometries in 2D.
+"""
+
 from ..engeom import _airfoil
 
 # Global import of all functions