engeom 0.2.4__tar.gz → 0.2.5__tar.gz

{engeom-0.2.4 → engeom-0.2.5}/Cargo.lock

@@ -1024,7 +1024,7 @@ dependencies = [
 
 [[package]]
 name = "py-engeom"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "engeom",
  "numpy",

{engeom-0.2.4 → engeom-0.2.5}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "py-engeom"
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

{engeom-0.2.4 → engeom-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engeom
-Version: 0.2.4
+Version: 0.2.5
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -8,3 +8,9 @@ Requires-Dist: numpy
 Requires-Dist: pytest ; extra == 'tests'
 Provides-Extra: tests
 Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# Engeom Python Bindings
+
+Full documentation at https://mattj23.github.io/py-engeom/
+

engeom-0.2.5/README.md

@@ -0,0 +1,3 @@
+# Engeom Python Bindings
+
+Full documentation at https://mattj23.github.io/py-engeom/

engeom-0.2.5/docs/airfoils/intro.md

@@ -0,0 +1,13 @@
+# Airfoil Introduction
+
+An airfoil is a body designed to produce asymmetrical forces when moving through a fluid. Airfoils are a common subject
+of metrology and engineering analysis in the aerospace and aerospace propulsion industries.
+
+The `engeom` library has tools for airfoil analysis centered around the 2D cross-sections of airfoil bodies. This is a
+function of the aerospace industry's historical use of 2D drawings to specify airfoil dimensional requirements and 
+performance characteristics.
+
+Airfoil analysis is a complicated subject with a lot of specialized tools and terminology based on convention and 
+historical precedent. There aren't typically one-size-fits-all algorithms and methods because of the extreme variation 
+in airfoil shapes and requirements. Different institutions and organizations even within the same industry will often 
+have their own preferred methods, tools, and sometimes even terminology.

engeom-0.2.5/docs/bounding_volumes.md

@@ -0,0 +1,112 @@
+# Bounding Volumes
+
+There are currently two types of bounding volumes available in the `engeom` library. Both are axis-aligned bounding
+boxes (AABBs), but one is for 2D (`Aabb2`) and the other is for 3D (`Aabb3`).
+
+These bounding volumes are primarily used within the Rust language library as an internal mechanism to support data
+structures which accelerate distance queries and intersection checks. However, they also have a number of useful
+features and so are exposed to the Python API.
+
+## Creating Bounding Volumes
+
+Most commonly, bounding volumes are created internally by the library for geometries that are part of acceleration
+structures or have clear spatial bounds, and accessed by retrieving them from those entities. However, through the
+Python API, they can also be created directly.
+
+```python
+from engeom.geom2 import Aabb2
+from engeom.geom3 import Aabb3
+
+# Create a 2D AABB. The arguments are x_min, y_min, x_max, y_max.
+box2 = Aabb2(-1, -2, 3, 4)
+
+# Create a 3D AABB. The arguments are x_min, y_min, z_min, x_max, y_max, z_max.
+box3 = Aabb3(-1, -2, -3, 3, 4, 5)
+```
+
+Two other convenient methods for creating bounding volumes are `from_points` and `at_point`.
+
+The `from_points` function creates a bounding volume that contains all the points in the input list. Pass it a list of
+points as a numpy array, and it will determine the bounds.
+
+```python
+import numpy
+from engeom.geom2 import Aabb2
+from engeom.geom3 import Aabb3
+
+points = numpy.array([[0, 0, 0],
+                      [1, 1, 1],
+                      [2, 2, 2],
+                      [3, 3, 3]]).astype(numpy.float64)
+
+# Create boxes that contain all the points
+box2 = Aabb2.from_points(points[:, :2])
+box3 = Aabb3.from_points(points)
+```
+
+The `at_point` function creates a bounding volume centered at the specified point with the specified dimensions. The
+arguments are the center point and the dimensions of the box. The 2D version takes 4 arguments (x, y, width, height),
+and the 3D version takes 6 arguments (x, y, z, width, height, depth).
+
+```python
+from engeom.geom2 import Aabb2
+from engeom.geom3 import Aabb3
+
+# Create a 2D AABB centered at the point (1, 2) that is 3 units wide (x) 
+# and 4 units tall (y).
+box2 = Aabb2.at_point(1, 2, 3, 4)
+
+# Create a 3D AABB centered at the point (1, 2, 3) that is 4 units wide (x),
+# 5 units tall (y), and 6 units deep (z).
+box3 = Aabb3.at_point(1, 2, 3, 4, 5, 6)
+```
+
+## Bounding Volume Properties
+
+There are four properties of bounding volumes, both 2D and 3D, that can be accessed and yield point and vector values
+related to the geometry of the volume.
+
+| Property  | Type                | Description                                                      |
+|-----------|---------------------|------------------------------------------------------------------|
+| `.center` | `Point2`/`Point3`   | The center point of the bounding volume                          |
+| `.min`    | `Point2`/`Point3`   | The minimum corner point of the bounding volume                  |
+| `.max`    | `Point2`/`Point3`   | The maximum corner point of the bounding volume                  |
+| `.extent` | `Vector2`/`Vector3` | The extents of the bounding volume (equivalent to `.max - .min`) |
+
+```python
+from engeom.geom3 import Aabb3
+
+box = Aabb3(-1, -2, -3, 1, 2, 3)
+
+# Get the center point of the box
+print(box.center)  # Point3(0, 0, 0)
+print(box.min)     # Point3(-1, -2, -3)
+print(box.max)     # Point3(1, 2, 3)
+print(box.extent)  # Vector3(2, 4, 6)
+```
+
+## Expand and Shrink
+
+Bounding volumes can be expanded or shrunk by a specified amount, yielding a new bounding volume. The `expand` and
+`shrink` methods take a single argument, which is the amount to expand or shrink the perimeter of the bounding volume.
+
+The overall change in the size of the extents will be twice the amount specified. For example, if you expand  a 2D box 
+by 1 unit, the width and height will each increase by 2 units.
+
+```python
+from engeom.geom2 import Aabb2
+box = Aabb2(-1, -2, 1, 2)
+
+print(box.extent)  # Vector2(2, 4)
+
+expanded = box.expand(0.5)
+print(expanded.extent)  # Vector2(3, 5)
+
+shrunk = box.shrink(0.5) 
+print(shrunk.extent)  # Vector2(1, 3)
+```
+
+## Intersection and Containment
+
+!!! warning 
+    Intersection and containment options are not yet bound to the Python API. This will be added in a future release.

engeom-0.2.5/docs/curves.md

@@ -0,0 +1,111 @@
+# Curves
+
+## Introduction
+
+The `engeom` library has both a 2D and 3D curve type. This type represents a 1-dimensional manifold that consists of
+a sequence of vertices in $\mathbb{R}^n$ space that are connected by line-segment edges, sometimes referred to as a
+polyline.
+
+Each curve entity consists of a single contiguous sequence of vertices with a clear start and end point. In the case of
+the 2D `Curve2` type, the curve can also be "closed", meaning that the end point is connected to the start point to
+form a closed loop and so operations on the manifold that cross the end point will wrap around to the start point,
+and vice versa.
+
+While the fundamental operations on a curve, such as distance queries and manifold traversal are the same or similar
+for the 2D and 3D curve types, the 2D curve type has many more features that are made possible by the 2D plane.
+
+## 2D Curves
+
+The 2D curve type, `Curve2`, is a more feature-rich type than the 3D curve type, because the nature of the 2D plane
+means that a 2D polyline is more conceptually related to a 3D `Mesh` object than it is to a 3D polyline. A `Curve2`
+object can represent a boundary/surface with a clear sense of "inside" and "outside", and if it forms a closed loop
+it can model a partitioning of the $\mathbb{R}^2$ plane into an interior and exterior region.
+
+In 2D, a curve has concept of a surface normal direction, which is built from the concept inside/outside defined through
+the winding order of the vertices. By convention, the segment from vertex $i$ to vertex $i+1$ defines the space to
+its "right" as being outside the curve, and the space to its "left" as being inside the curve, resulting in a
+counter-clockwise winding order defining a positive convex shape.
+
+### Creation
+
+Creation of a `Curve2` object is done by passing in a list of ordered vertices that define the curve. The vertices
+will be interpreted in sequential order, so that each vertex will be connected to the next vertex in the list.
+
+Adjacent vertices that are within a distance tolerance from each other will be de-duplicated, to prevent the curve from
+having zero-length segments. Additionally, if the first and last point are within the distance tolerance, the curve
+will be considered "closed" and algorithms which do manifold traversal will wrap between the first and last points.
+
+However, because of the importance of winding order on 2D curves, the `Curve2` type must *also* be constructed with the
+vertices in the specific order that matches the intended definition of "inside" vs "outside" for the curve.
+
+While the space occupied by the curve might be exactly the same whether the vertices are constructed in forward or
+reverse order, the inside vs outside will be opposite.
+
+There are three ways that winding order can be specified during construction of a `Curve2` object:
+
+1. You can prepare the list of vertices so that they are in the correct order and then pass them into the constructor.
+   Counter-clockwise order of vertices for positive convex shapes/regions, and clockwise order for negative convex
+   shapes/regions.
+
+2. If you know that the curve is meant to represent a positive (convex) shape overall, you can set the `hull_ccw=True`
+   flag. The constructor will build the convex hull of the vertices you provide and reverse their order if the hull
+   sequence does not match the input sequence.
+
+3. You may provide the constructor with an array of surface normals that correspond with the vertices. There must be one
+   normal per vertex in the input list, and it must be pointing in the direction that you intend to be the "outside" of
+   the surface. The constructor will reverse the input order if the majority of normals are not pointing in the same
+   direction as the winding order would imply.
+
+The input arguments for the constructor are:
+
+| Argument       | Type                         | Description                                                                                                                                                                                                              |
+|----------------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `vertices`     | `numpy.ndarray`              | A 2D array of shape `(n, 2)` where `n` is the number of vertices in the curve. The columns are the x and y components of the vertices                                                                                    |
+| `normals`      | `numpy.ndarray` **OPTIONAL** | A 2D array of shape `(n, 2)` where `n` is the number of vertices in the curve. The columns are the x and y components of the normals at each vertex. Default is `None`.                                                  |
+| `tol`          | `float` **OPTIONAL**         | A tolerance distance, below which points are considered to be the same and de-duplicated. Default is `1e-6`                                                                                                              |
+| `force_closed` | `bool` **OPTIONAL**          | If `True`, the curve will be guaranteed to be closed. If the first and last point are more than `tol` distance apart, an additional vertex will be added to the end that overlaps with the beginning. Default is `False` |
+| `hull_ccw`     | `bool` **OPTIONAL**          | If `True`, the vertices will be re-ordered to match the convex hull of the vertices. Default is `False`. This will be ignored if `normals` is not `None`                                                                 |
+
+```python
+import numpy
+from engeom.geom2 import Curve2
+
+# These are the corners of an open unit square
+vertices = numpy.array([[0.0, 0], [1, 0], [1, 1], [0, 1]])
+
+# Create a curve with these vertices and nothing else
+c1 = Curve2(vertices)
+print(c1)  # <Curve2 n=4, l=3 (open)>
+
+# Force the curve to be closed
+c2 = Curve2(vertices, force_closed=True)
+print(c2)  # <Curve2 n=5, l=4 (closed)>
+```
+
+### Stations
+
+Because a `Curve2` object is a 1D manifold, every unique position along the curve can be represented by a single scalar
+value, which is the length from the start of the curve. Each unique position along a 2D curve has several geometric
+properties which are useful.  These properties are bundled in a `CurveStation2` object, which is a lightweight data 
+object that represents a single position on the manifold.
+
+`CurveStation2` objects are not created directly, but are retrieved from a `Curve2` object through one of several different possible queries on the manifold.
+
+The `CurveStation2` object has the following properties:
+
+| Property           | Type            | Description                                                                                                                                      |
+|--------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.point`           | `Point2`        | The 2D position in space that corresponds with the station on the manifold.                                                                      |
+| `.direction`       | `Vector2`       | The vector pointing in the direction of positive distance along the curve. Typically this is the vector from the last vertex to the next vertex. |
+| `.normal`          | `Vector2`       | The vector pointing in the direction of the surface normal at the station. This is the `direction` vector rotated by $-90°$.                     |
+| `.direction_point` | `SurfacePoint2` | A convenience surface point that combines the `point` position and `direction` vector.                                                           |
+| `.surface_point`   | `SurfacePoint2` | A convenience surface point that combines the `point` position and `normal` vector.                                                              |
+| `.index`           | `int`           | The index of the previous vertex on the curve, at or before the station.                                                                         | 
+| `.length_along`    | `float`         | The distance along the curve from the start to the station. This is the manifold domain.                                                         |
+
+
+### Querying
+
+
+
+

engeom-0.2.5/docs/index.md

@@ -0,0 +1,27 @@
+# Engeom (Python Bindings)
+
+This site has the documentation for the Python bindings of the `engeom` library. 
+
+The [`engeom` library](https://github.com/mattj23/engeom) is a Rust library for 2D and 3D engineering geometry, with a specific focus on metrology applications.  The Python bindings provide a way to use some of the library's functionality in Python, with a reasonably similar interface to the Rust library.
+
+The bindings are built using `pyo3` and `maturin` and `engeom` is compiled as a self-contained extension library, so the python module is the only thing which needs to be installed on an interpreter for everything to work.  It is available for Python versions `>=3.8`, for Windows/Linux/macOS, and on most common 64-bit architectures.
+
+## Quick Overview
+
+The `engeom` Python library has a few general feature sets:
+
+- 2D and 3D geometric primitives (points, vectors, planes, circles/arcs, line segments, transformation matrices, etc) which can be used to represent and perform basic geometric operations through a simple and consistent interface.
+- More complicated entities like 3D triangle meshes, 2D and 3D polylines, and 3D point clouds, with common operations like intersections, projections, distance queries, transformations, etc.
+- Some basic fitting and alignment algorithms for 2D and 3D data
+- Helper functions for plotting and visualization to assist in use of the `matplotlib` and `pyvista` libraries.
+
+## Installation
+
+The Python bindings can be installed using `pip`:
+
+```bash
+pip install engeom
+```
+
+
+

engeom-0.2.5/docs/isometries.md

@@ -0,0 +1,146 @@
+# Isometries (Rigid-body Transformations)
+
+Isometries are a class of transformations that preserve distances between points. They are also known as rigid-body
+transformations, as they preserve the shape of the object being transformed.
+
+In the underlying Rust `engeom` library, isometries are aliases for a native `nalgebra` struct. In two dimensions this
+consists of a 2D translation and a unit complex for rotation, and in three dimensions it consists of a 3D translation
+and a unit quaternion for rotation.
+
+Isometries can be thought of as equivalent to transformation matrices, but with the limitation that certain matrices
+are not valid isometries because they do not preserve distances. They can be composed together by multiplication
+according to the rules of matrix multiplication, inverted according to the rules of matrix inversion, and they can be
+multiplied against points or vectors to transform them.
+
+## Creating Isometries
+
+Two-dimensional isometries can be created directly from three scalar values: the x and y components of the translation,
+and the angle of rotation in radians. Three-dimensional isometries are more complicated, and are easiest to create
+through composition.
+
+### Two-dimensional Isometries
+
+```python
+from math import pi
+from engeom.geom2 import Iso2
+
+# Shortcut for the identity transform
+i0 = Iso2.identity()
+
+# Create an isometry that translates by (1, 2) and rotates by pi/4 radians
+i1 = Iso2(1, 2, pi / 4)
+```
+
+### Three-dimensional Isometries
+
+```python
+import numpy
+from math import pi
+from engeom.geom3 import Iso3
+
+# Shortcut for the identity transform
+i0 = Iso3.identity()
+
+# Try to create an isometry directly from a 4x4 transformation matrix. Will throw
+# an exception if the matrix is not a valid isometry.
+m = numpy.array([[1, 0, 0, 1],
+                 [0, 1, 0, 2],
+                 [0, 0, 1, 3],
+                 [0, 0, 0, 1]])
+i1 = Iso3(m)
+
+# Create an isometry that only translates by specifying the translation vector
+i2 = Iso3.from_translation(1, 2, 3)
+
+# Create an isometry that rotates by pi/4 radians around the x-axis. See the documentation
+# for `from_rotation` for more information on the arguments.
+i3 = Iso3.from_rotation(pi / 4, 1, 0, 0)
+```
+
+## Inverting Isometries
+
+Isometries can, by definition, be inverted. The inverse of an isometry is an isometry that, when applied to the result
+of the original isometry, returns the original input. An isometry multiplied by its inverse is the identity isometry.
+
+```python
+from math import pi
+from engeom.geom3 import Iso3
+
+i = Iso3.from_rotation(pi / 4, 1, 0, 0)
+
+# Invert the isometry
+i_inv = i.inverse()
+```
+
+
+## Composition
+
+Isometries can be composed together by multiplying them together. The order of multiplication is important, as
+isometries do not commute. The result of multiplying two isometries together is a new isometry that is equivalent to
+apply the right hand isometry first, and then the left hand isometry.
+
+The operator for isometry multiplication is the same as the matrix multiplication operator, `@`.
+
+```python
+from math import pi
+from engeom.geom3 import Iso3
+
+i1 = Iso3.from_rotation(pi / 4, 1, 0, 0)
+i2 = Iso3.from_translation(1, 2, 3)
+
+# Apply the rotation first, then the translation
+
+i3 = i2 @ i1
+```
+
+## Transforming Primitives
+
+### Vectors, Points, Surface Points, etc
+
+Isometries can be applied to points, vectors, and other geometric primitives by multiplying them by the isometry using
+the `@` operator.
+
+* A point transformed by an isometry is a new point that is at a new position in space.
+* A vector transformed by an isometry has been rotated, but its magnitude has not changed.
+* A surface point transformed by an isometry is the result of transforming the point and the normal vector
+  independently, and then re-constituting them into a new surface point. The position has been moved and the normal
+  vector rotated but remains of unit magnitude.
+
+```python
+from math import pi
+from engeom.geom2 import Iso2, Vector2, Point2, SurfacePoint2
+
+p = Point2(1, 2)
+v = Vector2(1, 2)
+sp = SurfacePoint2(1, 2, 1, 0)
+
+i = Iso2(1, 2, pi / 4)
+
+p2 = i @ p
+v2 = i @ v
+sp2 = i @ sp
+```
+
+### Numpy Arrays
+
+For efficient transformation of large numbers of points or vectors, both 2D and 3D isometries can be applied to `numpy`
+arrays representing points or vectors according to the rules defined in the previous section.
+
+```python
+import numpy
+from math import pi
+from engeom.geom2 import Iso2
+
+values = numpy.array([[1, 2],
+                      [3, 4],
+                      [5, 6],
+                      [7, 8]])
+
+i = Iso2(1, 2, pi / 4)
+
+# Apply the isometry to the values as if they were points
+new_points = i.transform_points(values)
+
+# Apply the isometry to the values as if they were vectors
+new_vectors = i.transform_vectors(values)
+```