Release: Projected Precise Mode (#2491)

- release #2490 as discussed in #2488 doing minor cleanup below the
precision threshold before unioning every triangle in `projected(...
precise=True)`
- release #2487 cleaning up the logic in
`trimesh.grouping.group_distance` to be more coherent.

Author: mikedh

pyproject.toml

@@ -5,7 +5,7 @@ requires = ["setuptools >= 61.0", "wheel"]
 [project]
 name = "trimesh"
 requires-python = ">=3.8"
-version = "4.10.0"
+version = "4.10.1"
 authors = [{name = "Michael Dawson-Haggerty", email = "[email protected]"}]
 license = {file = "LICENSE.md"}
 description = "Import, export, process, analyze and view triangular meshes."

tests/test_polygons.py

@@ -117,14 +117,15 @@ def test_project_backface():
 
 
 def test_project_multi():
-    mesh = g.trimesh.creation.box() + g.trimesh.creation.box().apply_translation(
-        [3, 0, 0]
-    )
-    proj = mesh.projected(normal=[0, 0, 1])
+    for ignore_sign, precise in g.itertools.combinations([True, False] * 2, 2):
+        mesh = g.trimesh.creation.box() + g.trimesh.creation.box().apply_translation(
+            [3, 0, 0]
+        )
+        proj = mesh.projected(normal=[0, 0, 1], ignore_sign=ignore_sign, precise=precise)
 
-    assert mesh.body_count == 2
-    assert len(proj.root) == 2
-    assert g.np.isclose(proj.area, 2.0)
+        assert mesh.body_count == 2
+        assert len(proj.root) == 2
+        assert g.np.isclose(proj.area, 2.0)
 
 
 def test_second_moment():

trimesh/base.py

@@ -2689,20 +2689,28 @@ def projected(self, normal: ArrayLike, **kwargs) -> Path2D:
 
         Parameters
         ----------
-        check : bool
-          If True make sure is flat
         normal : (3,) float
           Normal to extract flat pattern along
         origin : None or (3,) float
           Origin of plane to project mesh onto
-        pad : float
+        ignore_sign : bool
+          Allow a projection from the normal vector in
+          either direction: this provides a substantial speedup
+          on watertight meshes where the direction is irrelevant
+          but if you have a triangle soup and want to discard
+          backfaces you should set this to False.
+        rpad : float
           Proportion to pad polygons by before unioning
           and then de-padding result by to avoid zero-width gaps.
+        apad : float
+          Absolute padding to pad polygons by before unioning
+          and then de-padding result by to avoid zero-width gaps.
         tol_dot : float
           Tolerance for discarding on-edge triangles.
-        max_regions : int
-          Raise an exception if the mesh has more than this
-          number of disconnected regions to fail quickly before unioning.
+        precise : bool
+          Use the precise projection computation using shapely.
+        precise_eps : float
+          Tolerance for precise triangle checks.
 
         Returns
         ----------

trimesh/exchange/stl.py

@@ -1,6 +1,7 @@
 import numpy as np
 
 from .. import util
+from ..typed import Dict, Stream
 
 
 class HeaderError(Exception):
@@ -19,22 +20,20 @@ class HeaderError(Exception):
 _stl_dtype_header = np.dtype([("header", np.void, 80), ("face_count", "<u4")])
 
 
-def load_stl(file_obj, **kwargs):
+def load_stl(file_obj: Stream, **kwargs) -> Dict:
     """
-    Load an STL file from a file object.
+    Load a binary or an ASCII STL file from a file object.
 
     Parameters
     ----------
-    file_obj : open file-like object
+    file_obj
       Containing STL data
 
     Returns
     ----------
-    loaded : dict
-      kwargs for a Trimesh constructor with keys:
-      vertices:     (n,3) float, vertices
-      faces:        (m,3) int, indexes of vertices
-      face_normals: (m,3) float, normal vector of each face
+    loaded
+      Keyword arguments for a Trimesh constructor with
+      data loaded into properly shaped numpy arrays.
     """
     # save start of file obj
     file_pos = file_obj.tell()
@@ -53,7 +52,7 @@ def load_stl(file_obj, **kwargs):
         return load_stl_ascii(file_obj)
 
 
-def load_stl_binary(file_obj):
+def load_stl_binary(file_obj: Stream) -> Dict:
     """
     Load a binary STL file from a file object.
 
@@ -64,10 +63,9 @@ def load_stl_binary(file_obj):
 
     Returns
     ----------
-    loaded: kwargs for a Trimesh constructor with keys:
-              vertices:     (n,3) float, vertices
-              faces:        (m,3) int, indexes of vertices
-              face_normals: (m,3) float, normal vector of each face
+    loaded
+      Keyword arguments for a Trimesh constructor with data
+      loaded into properly shaped numpy arrays.
     """
     # the header is always 84 bytes long, we just reference the dtype.itemsize
     # to be explicit about where that magical number comes from
@@ -136,7 +134,7 @@ def load_stl_binary(file_obj):
     return result
 
 
-def load_stl_ascii(file_obj):
+def load_stl_ascii(file_obj: Stream) -> Dict:
     """
     Load an ASCII STL file from a file object.
 
@@ -147,11 +145,9 @@ def load_stl_ascii(file_obj):
 
     Returns
     ----------
-    loaded : dict
-      kwargs for a Trimesh constructor with keys:
-      vertices:     (n, 3) float, vertices
-      faces:        (m, 3) int, indexes of vertices
-      face_normals: (m, 3) float, normal vector of each face
+    loaded
+      Keyword arguments for a Trimesh constructor with
+      data loaded into properly shaped numpy arrays.
     """
 
     # read all text into one string

trimesh/grouping.py

@@ -9,7 +9,7 @@
 
 from . import util
 from .constants import log, tol
-from .typed import ArrayLike, Integer, NDArray, Optional
+from .typed import ArrayLike, Integer, NDArray, Number, Optional, Sequence, Tuple
 
 try:
     from scipy.spatial import cKDTree
@@ -666,14 +666,16 @@ def group_vectors(vectors, angle=1e-4, include_negative=False):
     return new_vectors, groups
 
 
-def group_distance(values, distance):
+def group_distance(
+    values: ArrayLike, distance: Number
+) -> Tuple[NDArray[np.float64], Sequence]:
     """
-    Find groups of points which have neighbours closer than radius,
-    where no two points in a group are farther than distance apart.
+    Find non-overlapping groups of points where no two points in a
+    group are farther than 2*distance apart.
 
     Parameters
     ---------
-    points :   (n, d) float
+    values : (n, d) float
         Points of dimension d
     distance : float
         Max distance between points in a cluster
@@ -700,6 +702,7 @@ def group_distance(values, distance):
         if consumed[index]:
             continue
         group = np.array(tree.query_ball_point(value, distance), dtype=np.int64)
+        group = group[~consumed[group]]
         consumed[group] = True
         unique.append(np.median(values[group], axis=0))
         groups.append(group)

trimesh/path/polygons.py

@@ -735,6 +735,7 @@ def projected(
     apad=None,
     tol_dot=1e-10,
     precise: bool = False,
+    precise_eps: float = 1e-10,
 ):
     """
     Project a mesh onto a plane and then extract the polygon
@@ -753,8 +754,6 @@ def projected(
     ----------
     mesh : trimesh.Trimesh
       Source geometry
-    check : bool
-      If True make sure is flat
     normal : (3,) float
       Normal to extract flat pattern along
     origin : None or (3,) float
@@ -773,10 +772,10 @@ def projected(
       and then de-padding result by to avoid zero-width gaps.
     tol_dot : float
       Tolerance for discarding on-edge triangles.
-    max_regions : int
-      Raise an exception if the mesh has more than this
-      number of disconnected regions to fail quickly before
-      unioning.
+    precise : bool
+      Use the precise projection computation using shapely.
+    precise_eps : float
+      Tolerance for precise triangle checks.
 
     Returns
     ----------
@@ -829,15 +828,28 @@ def projected(
     vertices_2D = transform_points(mesh.vertices, to_2D)[:, :2]
 
     if precise:
-        eps = 1e-10
+        # precise mode just unions triangles as one shapely
+        # polygon per triangle which historically has been very slow
+        # but it is more defensible intellectually
         faces = mesh.faces[side]
-        # just union all the polygons
+        # round the 2D vertices with slightly more precision
+        # than our final dilate-erode cleanup
+        digits = int(np.abs(np.log10(precise_eps)) + 2)
+        rounded = np.round(vertices_2D, digits)
+        # get the triangles as closed 4-vertex polygons
+        triangles = rounded[np.column_stack((faces, faces[:, :1]))]
+        # do a check for exactly-degenerate triangles where any two
+        # vertices are exactly identical which means the triangle has
+        # zero area
+        valid = ~(triangles[:, [0, 0, 2]] == triangles[:, [1, 2, 1]]).all(axis=2).any(
+            axis=1
+        )
+        # union the valid triangles and then dilate-erode to clean up
+        # any holes or defects smaller than precise_eps
         return (
-            ops.unary_union(
-                [Polygon(f) for f in vertices_2D[np.column_stack((faces, faces[:, :1]))]]
-            )
-            .buffer(eps)
-            .buffer(-eps)
+            ops.unary_union([Polygon(f) for f in triangles[valid]])
+            .buffer(precise_eps)
+            .buffer(-precise_eps)
         )
 
     # a sequence of face indexes that are connected

trimesh/typed.py

@@ -43,7 +43,6 @@
 
 # most loader routes take `file_obj` which can either be
 # a file-like object or a file path, or sometimes a dict
-
 Stream = Union[IO, BytesIO, StringIO, BinaryIO, TextIO, BufferedRandom]
 Loadable = Union[str, Path, Stream, Dict, None]