offset-poly 0.1.0__tar.gz

offset_poly-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.1
+Name: offset-poly
+Version: 0.1.0
+Summary: 
+Author: Shay Hill
+Author-email: shay_public@hotmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+
+# offset_poly
+
+Move a polyline or polygon (left) by a given offset.
+
+A counterclockwise polygon will be offset to the inside. I clockwise polygon will be offset to the outside.
+
+## offset_polygon
+
+~~~python
+def offset_polygon(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polygon offset by offset
+    """
+~~~
+
+## offset_polyline
+
+~~~python
+def offset_polyline(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polyline offset by offset
+    """
+~~~
+
+The difference between the two is that `offset_polygon` will close the polygon if it is not already closed, whereas `offset_polyline` will leave the polyline open even if the first and last points are identical.
+
+This package is the simplest version of polyline offsetting, it does not anticipate or account for self intersections that may come up when offsetting a polyline.
+
+This is not nearly as sophisticated as curve offsetting, but you can use this for control polygon offsetting, which will be nearly as good in some instances.
+
+* multiple points (knots in your control points) are preserved.
+* if input[0] == input[-1], output[0] will equal output[-1]
+
+## You may see (nan, nan) in the result.
+
+If you pass two adjacent, opposite, parallel edges, you will get a (nan, nan) in the result. With points A -> B -> A, for instance, there is no point that would be any given distance (except 0) left of both A B and B A.

offset_poly-0.1.0/README.md

@@ -0,0 +1,42 @@
+# offset_poly
+
+Move a polyline or polygon (left) by a given offset.
+
+A counterclockwise polygon will be offset to the inside. I clockwise polygon will be offset to the outside.
+
+## offset_polygon
+
+~~~python
+def offset_polygon(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polygon offset by offset
+    """
+~~~
+
+## offset_polyline
+
+~~~python
+def offset_polyline(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polyline offset by offset
+    """
+~~~
+
+The difference between the two is that `offset_polygon` will close the polygon if it is not already closed, whereas `offset_polyline` will leave the polyline open even if the first and last points are identical.
+
+This package is the simplest version of polyline offsetting, it does not anticipate or account for self intersections that may come up when offsetting a polyline.
+
+This is not nearly as sophisticated as curve offsetting, but you can use this for control polygon offsetting, which will be nearly as good in some instances.
+
+* multiple points (knots in your control points) are preserved.
+* if input[0] == input[-1], output[0] will equal output[-1]
+
+## You may see (nan, nan) in the result.
+
+If you pass two adjacent, opposite, parallel edges, you will get a (nan, nan) in the result. With points A -> B -> A, for instance, there is no point that would be any given distance (except 0) left of both A B and B A.

offset_poly-0.1.0/offset_poly/__init__.py

@@ -0,0 +1,43 @@
+"""Import fuctions into the package namespace.
+
+:author: Shay Hill
+:created: 2023-08-19
+"""
+
+from offset_poly.offset import (
+    offset_poly_per_edge,
+    offset_poly_per_vert,
+    offset_polygon,
+    offset_polyline,
+)
+from offset_poly.offset_corner import miter_corner
+from offset_poly.vec2_math import (
+    det,
+    dot,
+    get_norm,
+    get_signed_angle,
+    move_along,
+    qrotate,
+    set_norm,
+    vadd,
+    vscale,
+    vsub,
+)
+
+__all__ = [
+    "miter_corner",
+    "offset_polyline",
+    "offset_polygon",
+    "offset_poly_per_vert",
+    "offset_poly_per_edge",
+    "det",
+    "dot",
+    "get_signed_angle",
+    "get_norm",
+    "set_norm",
+    "move_along",
+    "qrotate",
+    "vscale",
+    "vadd",
+    "vsub",
+]

offset_poly-0.1.0/offset_poly/offset.py

@@ -0,0 +1,156 @@
+"""Offset a polyline to the right.
+
+:author: Shay Hill
+:created: 2023-08-17
+"""
+
+from __future__ import annotations
+
+import enum
+import itertools as it
+from typing import TYPE_CHECKING
+
+from offset_poly.offset_corner import miter_corner
+from offset_poly.prepare_poly import (
+    align_closing_points,
+    remove_coincident_adjacent_points,
+)
+from offset_poly.vec2_math import vadd, vsub
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+_Vec2 = tuple[float, float]
+
+_MIN_PTS_FOR_POLYGON = 3
+_MIN_PTS_FOR_POLYLINE = 2
+
+
+class PolyType(enum.Enum):
+    """Polyline types."""
+
+    POLYLINE = enum.auto()
+    POLYGON = enum.auto()
+
+
+def _wrap_polygon(polyline: Sequence[_Vec2]) -> list[_Vec2]:
+    """Wrap a polyline around to the beginning if it is closed.
+
+    :param polyline: polyline
+    :return: polyline with last point repeated if it is closed
+
+    From A, B, C, A to C, A, B, C, A
+    """
+    points = list(polyline)
+    if points[0] == points[-1]:
+        points = points[:-1]
+    return points[-1:] + points + points[:1]
+
+
+def _anchor_polyline(polyline: Sequence[_Vec2]) -> list[_Vec2]:
+    """Add edges to endpoints of an open polyline.
+
+    :param polyline: polyline
+    :return: polyline with extended edges at the beginning and end
+
+        A --- B
+              |
+              C
+
+    becomes
+
+    A` --- A --- B
+                 |
+                 C
+                 |
+                 C`
+
+    From A, B, C to (A + (A - B)), A, B, C, (C - (B - C))
+    """
+    pnt_beg = vadd(polyline[0], vsub(*polyline[:2]))
+    pnt_end = vsub(polyline[-1], vsub(*polyline[-2:]))
+    return [pnt_beg, *list(polyline), pnt_end]
+
+
+def offset_poly_per_vert(
+    polyline: Sequence[_Vec2],
+    vert_offsets: Iterable[tuple[float, float]],
+    poly_type: PolyType,
+) -> list[_Vec2]:
+    """Offset each corner of a polyline or polygon.
+
+    :param polyline: polyline
+    :param vert_offsets: iterable of (gap_1, gap_2) tuples. One pair per corner.
+    :param poly_type: PolyType.POLYGON or PolyType.POLYLINE
+    :return: polyline offset by vert_offsets
+    :raise ValueError: if fewer than three points are given for a polygon
+    :raise ValueError: if fewer than two points are given for a polyline
+
+    This is the engine of the offset_polyline and offset_polygon
+    functions. You can use it directly, but it's going to be tricky if
+    you have zero-length segments or closed points. These points will
+    be removed before the gaps are applied, so you'll have to pass
+    exactly enough for gap pairs for the segments that are retained.
+    """
+    points = remove_coincident_adjacent_points(polyline)
+    gaps = it.cycle(vert_offsets or [(0, 0)])
+
+    if poly_type == PolyType.POLYGON:
+        if len(points) < _MIN_PTS_FOR_POLYGON:
+            msg = "at least three unique points required for a polygon"
+            raise ValueError(msg)
+        points = _wrap_polygon(points)
+    elif poly_type == PolyType.POLYLINE:
+        if len(points) < _MIN_PTS_FOR_POLYLINE:
+            msg = "at least two unique points required for a polyline"
+            raise ValueError(msg)
+        points = _anchor_polyline(points)
+    else:
+        msg = "poly_type must be PolyType.POLYGON or PolyType.POLYLINE"
+        raise ValueError(msg)
+
+    offset_points: list[_Vec2] = []
+    for pnt_a, pnt_b, pnt_c in zip(points, points[1:], points[2:]):
+        gap_1, gap_2 = next(gaps)
+        offset_points.append(miter_corner(pnt_a, pnt_b, pnt_c, gap_1, gap_2))
+
+    return align_closing_points(polyline, offset_points)
+
+
+def offset_poly_per_edge(
+    polyline: Sequence[_Vec2], edge_offsets: Iterable[float], poly_type: PolyType
+) -> list[_Vec2]:
+    """Offset each edge of a polyline or polygon.
+
+    :param polyline: polyline
+    :param edge_offsets: iterable of offsets. One per edge.
+    :param poly_type: PolyType.POLYGON or PolyType.POLYLINE
+    :return: polyline offset by edge_offsets
+
+    This function allows each edge of a polygon or polyline to be offset by
+    a different amount. You will end up with a ValueError in miter_corner
+    if you try to offset consecutive, parallel edges by different amounts.
+    """
+    prev_edges, next_edges = it.tee(edge_offsets, 2)
+    next_edges = it.islice(it.cycle(next_edges), 1, None)
+    return offset_poly_per_vert(polyline, zip(prev_edges, next_edges), poly_type)
+
+
+def offset_polyline(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polyline offset by offset
+    """
+    return offset_poly_per_edge(polyline, it.cycle([offset]), PolyType.POLYLINE)
+
+
+def offset_polygon(polyline: Sequence[_Vec2], offset: float) -> list[_Vec2]:
+    """Offset polygon edges (to the left) by a constant amount.
+
+    :param polyline: polyline
+    :param offset: distance to offset from each edge
+    :return: polygon offset by offset
+    """
+    return offset_poly_per_edge(polyline, it.cycle([offset]), PolyType.POLYGON)

offset_poly-0.1.0/offset_poly/offset_corner.py

@@ -0,0 +1,48 @@
+"""Simple math helpers and offsetting one corner defined by three points.
+
+:author: Shay Hill
+:created: 2023-08-17
+"""
+
+from __future__ import annotations
+
+import math
+
+from offset_poly.vec2_math import _Vec2, get_signed_angle, move_along, qrotate, vsub
+
+
+def miter_corner(
+    pnt_a: _Vec2, pnt_b: _Vec2, pnt_c: _Vec2, gap_1: float, gap_2: float | None = None
+) -> tuple[float, float]:
+    """Offset a corner (to the right) defined by three points.
+
+    :param pnt_a: previous  point
+    :param pnt_b: corner point
+    :param pnt_c: next point
+    :param gap_1: distance to offset from vec12
+    :param gap_2: optional distance to offset from vec23. If not given, gap_1 is used
+    :return: the unique point gap_1 distance from ab and gap_2 distance from bc
+    :raise ValueError: if angle abc is zero and gap_1 != gap_2
+    """
+    if gap_2 is None:
+        gap_2 = gap_1
+
+    if gap_1 is 0 and gap_2 is 0:
+        return pnt_b
+
+    vec12 = vsub(pnt_b, pnt_a)
+    vec23 = vsub(pnt_c, pnt_b)
+    angle = get_signed_angle(vec12, vec23)
+
+    if math.isclose(angle, 0, abs_tol=1e-6):
+        if gap_1 != gap_2:
+            except_msg = "gap_1 and gap_2 must be equal when angle is zero"
+            raise ValueError(except_msg)
+        return move_along(pnt_b, qrotate(vec12, 1), gap_1)
+
+    sin_angle = math.sin(angle)
+    if math.isclose(sin_angle, 0, abs_tol=1e-6):
+        return math.nan, math.nan
+
+    intermediate = move_along(pnt_b, vec23, gap_1 / sin_angle)
+    return move_along(intermediate, vec12, -(gap_2 or 0) / sin_angle)

offset_poly-0.1.0/offset_poly/prepare_poly.py

@@ -0,0 +1,59 @@
+"""Remove points that would give indeterminate results.
+
+:author: Shay Hill
+:created: 2023-08-17
+"""
+
+from __future__ import annotations
+
+import itertools as it
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_Vec2 = tuple[float, float]
+
+
+def remove_coincident_adjacent_points(polyline: Sequence[_Vec2]) -> list[_Vec2]:
+    """Remove zero-length segments from a polyline.
+
+    :param polyline: polyline
+    :return: polyline with zero-length segments removed
+    """
+    new_points: list[_Vec2] = []
+    for i, point in enumerate(polyline):
+        if i == 0 or point != polyline[i - 1]:
+            new_points.append(point)
+    return new_points
+
+
+def align_closing_points(
+    polyline_a: Sequence[_Vec2], polyline_b: list[_Vec2]
+) -> list[_Vec2]:
+    """Set b[0] to b[-1] if a[0] == a[-1].
+
+    :param polyline_a: polyline
+    :param polyline_b: polyline
+    :return: polyline_b with first point set to last point if polyline_a is closed
+
+    Match multiples of the same point.
+    polyline_a -> [A, B, B, C]
+    polyline_b -> [D, E, F]
+    polyline_c -> [D, E, E, F]
+
+    Wrap endpoints if polyline_a is closed.
+    polyline_a -> [A, B, C, A]
+    polyline_b -> [D, E, F]
+    polyline_c -> [D, E, F, D]
+    """
+    polyline_c: list[_Vec2] = []
+    points_b = it.cycle(polyline_b)
+    for i, point_a in enumerate(polyline_a):
+        if i == 0:
+            polyline_c.append(next(points_b))
+        elif point_a == polyline_a[i - 1]:
+            polyline_c.append(polyline_c[-1])
+        else:
+            polyline_c.append(next(points_b))
+    return polyline_c

offset_poly-0.1.0/offset_poly/vec2_math.py

@@ -0,0 +1,129 @@
+"""Simple operations on vectors. All return 2tuples.
+
+:author: Shay Hill
+:created: 2023-08-19
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from typing import Union
+
+_Vec2 = Union[tuple[float, float], Sequence[float]]
+
+
+def det(vec_a: _Vec2, vec_b: _Vec2) -> float:
+    """Return determinant of a 2x2 matrix.
+
+    :param vec_a: 2d vector
+    :param vec_b: 2d vector
+    :return: determinant of the 2x2 matrix where
+        vec_a is the first row and vec_b is the second
+    """
+    return vec_a[0] * vec_b[1] - vec_a[1] * vec_b[0]
+
+
+def dot(vec_a: _Vec2, vec_b: _Vec2) -> float:
+    """Return dot product of two 2d vectors.
+
+    :param vec_a: 2d vector
+    :param vec_b: 2d vector
+    :return: dot product of the vectors
+    """
+    return vec_a[0] * vec_b[0] + vec_a[1] * vec_b[1]
+
+
+def get_signed_angle(vec_a: _Vec2, vec_b: _Vec2) -> float:
+    """Calculate the signed angle at a corner defined by two vectors.
+
+    :param vec_a: 2d vector
+    :param vec_b: 2d vector
+    :return: signed angle between the vectors
+
+    Counterclockwise angles will be positive
+    Clockwise angles will be negative
+    """
+    return math.atan2(det(vec_a, vec_b), dot(vec_a, vec_b))
+
+
+def get_norm(vec: _Vec2) -> float:
+    """Return Euclidean norm of a 2d vector.
+
+    :param vec: 2d vector
+    :return: Euclidean norm of the vector
+    """
+    return math.sqrt(vec[0] ** 2 + vec[1] ** 2)
+
+
+def set_norm(vec: _Vec2, norm: float = 1) -> tuple[float, float]:
+    """Scale a 2d vector to a given magnitude.
+
+    :param vec: 2d vector
+    :param norm: desired magnitude of the output vector, default is 1
+    :return: normalized (then optionally scaled) 2d vector
+    :raise ValueError: if trying to scale a zero-length vector to a nonzero length
+    """
+    input_norm = get_norm(vec)
+    if input_norm == 0 and norm != 0:
+        except_msg = "cannot scale a zero-length vector to a nonzero length"
+        raise ValueError(except_msg)
+    if norm == 0:
+        return 0, 0
+    scale = norm / input_norm
+    return vscale(vec, scale)
+
+
+def vscale(vec: _Vec2, scale: float) -> tuple[float, float]:
+    """Multiply a 2d vector by a scalar.
+
+    :param vec: 2d vector
+    :param scale: scalar for vec
+    :return: vec * scale
+    """
+    return vec[0] * scale, vec[1] * scale
+
+
+def vadd(vec_a: _Vec2, vec_b: _Vec2) -> tuple[float, float]:
+    """Add two 2d vectors.
+
+    :param vec_a: 2d vector
+    :param vec_b: 2d vector
+    :return: sum of the vectors
+    """
+    return vec_a[0] + vec_b[0], vec_a[1] + vec_b[1]
+
+
+def vsub(vec_a: _Vec2, vec_b: _Vec2) -> tuple[float, float]:
+    """Subtract two 2d vectors.
+
+    :param vec_a: 2d vector
+    :param vec_b: 2d vector
+    :return: difference of the vectors
+    """
+    return vadd(vec_a, vscale(vec_b, -1))
+
+
+def move_along(pnt: _Vec2, vec: _Vec2, distance: float) -> tuple[float, float]:
+    """Move a point along a vector.
+
+    :param pnt: 2d vector
+    :param vec: 2d vector
+    :param distance: distance to move v1 along v2
+    :return: new point
+    """
+    vec12 = set_norm(vec, distance)
+    return vadd(pnt, vec12)
+
+
+def qrotate(vec: _Vec2, quadrants: int) -> tuple[float, float]:
+    """Rotate a 2d vector 90 degrees counterclockwise.
+
+    :param vec: 2d vector
+    :param quadrants: number of 90 degree clockwise rotations
+    :return: rotated vector
+    """
+    quadrants = quadrants % 4
+    if quadrants == 0:
+        return vec[0], vec[1]
+    return qrotate((-vec[1], vec[0]), quadrants - 1)

offset_poly-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "offset-poly"
+version = "0.1.0"
+description = ""
+authors = ["Shay Hill <shay_public@hotmail.com>"]
+readme = "README.md"
+packages = [{include = "offset_poly"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pre-commit = "^3.3.3"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"