cvgeomkit 0.1.0__tar.gz

cvgeomkit-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: cvgeomkit
+Version: 0.1.0
+Summary: Geometry-based image analysis toolkit
+Author: polymorvic
+Author-email: polymorvic <polymorphic.bite@gmail.com>
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: opencv-python>=4.13.0.92
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: shapely>=2.1.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+

cvgeomkit-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "cvgeomkit"
+version = "0.1.0"
+description = "Geometry-based image analysis toolkit"
+readme = "README.md"
+authors = [
+    { name = "polymorvic", email = "polymorphic.bite@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "matplotlib>=3.10.9",
+    "numpy>=2.4.4",
+    "opencv-python>=4.13.0.92",
+    "pillow>=12.2.0",
+    "shapely>=2.1.2",
+]
+
+[project.scripts]
+cvgeomkit = "cvgeomkit:main"
+
+[build-system]
+requires = ["uv_build>=0.8.2,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.2.0",
+    "jupyterlab>=4.5.7",
+    "ruff>=0.15.12",
+]

cvgeomkit-0.1.0/src/cvgeomkit/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from cvgeomkit!")

cvgeomkit-0.1.0/src/cvgeomkit/common.py

@@ -0,0 +1,122 @@
+from abc import ABC, abstractmethod
+from collections.abc import Hashable as SupportsHash
+from enum import StrEnum
+from typing import Self
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+type ArrayLike = np.ndarray | NumpyImage
+
+
+type Numeric = float | int
+
+
+class BBoxFmt(StrEnum):
+    XYWH = "xywh"
+    XYXY = "xyxy"
+    CXCYWH = "cxcxywh"
+
+
+class ColorSpace(StrEnum):
+    GRAY = "gray"
+    BGR = "bgr"
+    RGB = "rgb"
+    HSV = "hsv"
+
+
+class NumpyImage(np.ndarray):
+    """
+    A lightweight wrapper around `numpy.ndarray` for easier image shape handling.
+
+    Provides convenient properties to access image dimensions:
+    - `height`: number of rows
+    - `width`: number of columns
+    - `depth`: number of channels (defaults to 1 if not present)
+
+    Fully compatible with OpenCV and other libraries that expect a standard
+    NumPy array, since it is implemented as a view of the original array.
+    """
+    def __new__(cls, input_array):
+        """Build a `NumpyImage` view over `input_array` (no copy if already ndarray)."""
+        obj = np.asarray(input_array).view(cls)
+        return obj
+
+    def to_colorspace(self, dst_space: ColorSpace, src_space: ColorSpace) -> Self:
+        """Convert pixels from `src_space` to `dst_space` via OpenCV; same space returns a copy."""
+
+        if src_space == dst_space:
+            return self.copy().view(NumpyImage)
+
+        conversions = {
+            (ColorSpace.BGR, ColorSpace.RGB): cv2.COLOR_BGR2RGB,
+            (ColorSpace.RGB, ColorSpace.BGR): cv2.COLOR_RGB2BGR,
+
+            (ColorSpace.BGR, ColorSpace.GRAY): cv2.COLOR_BGR2GRAY,
+            (ColorSpace.GRAY, ColorSpace.BGR): cv2.COLOR_GRAY2BGR,
+
+            (ColorSpace.RGB, ColorSpace.GRAY): cv2.COLOR_RGB2GRAY,
+            (ColorSpace.GRAY, ColorSpace.RGB): cv2.COLOR_GRAY2RGB,
+
+            (ColorSpace.BGR, ColorSpace.HSV): cv2.COLOR_BGR2HSV,
+            (ColorSpace.HSV, ColorSpace.BGR): cv2.COLOR_HSV2BGR,
+
+            (ColorSpace.RGB, ColorSpace.HSV): cv2.COLOR_RGB2HSV,
+            (ColorSpace.HSV, ColorSpace.RGB): cv2.COLOR_HSV2RGB,
+        }
+
+        code = conversions.get((src_space, dst_space))
+        if code is None:
+            raise ValueError(
+                f"Unsupported conversion: {src_space} -> {dst_space}"
+            )
+
+        return cv2.cvtColor(self, code).view(NumpyImage)
+
+    @property
+    def width(self):
+        """Column count; 1 for a 1-D array."""
+        return self.shape[1] if len(self.shape) > 1 else 1
+
+    @property
+    def height(self):
+        """Row count."""
+        return self.shape[0]
+
+    @property
+    def depth(self):
+        """Channel count; 1 when there is no channel axis."""
+        return self.shape[2] if len(self.shape) > 2 else 1
+    
+    def as_array(self):
+        """Convert back to regular numpy array for compatibility"""
+        return np.asarray(self)
+
+    @property
+    def as_pil(self) -> Image.Image:
+        """Pillow image backed by this array's pixel data."""
+        return Image.fromarray(self.as_array())
+
+
+class Hashable(ABC):
+    """
+    Value-based equality and hashing via `_key_()`.
+
+    Subclasses return a hashable tuple (or other immutable key); `__eq__` and
+    `__hash__` delegate to that key so instances with the same key compare equal.
+    """
+
+    @abstractmethod
+    def _key_(self) -> SupportsHash:
+        """Return the hashable identity used for `__hash__` and `__eq__`."""
+        raise NotImplementedError
+
+    def __hash__(self) -> int:
+        return hash(self._key_())
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, self.__class__):
+            return False
+        return self._key_() == other._key_()

cvgeomkit-0.1.0/src/cvgeomkit/geometry/intersections.py

@@ -0,0 +1,173 @@
+from typing import TYPE_CHECKING, Self
+
+import numpy as np
+
+from cvgeomkit.common import Hashable, ArrayLike
+from .points import transform_point
+
+if TYPE_CHECKING:
+    from .lines import Line, transform_line
+    from .points import Point
+
+
+class Intersection(Hashable):
+    """
+    Represents the intersection point of two lines and the angle between them.
+    """
+
+    def __init__(self, line1: "Line", line2: "Line", intersection_point: "Point") -> None:
+        """
+        Initialize the Intersection object.
+
+        Args:
+            line1 (Line): The first line.
+            line2 (Line): The second line.
+            intersection_point (tuple[int, int]): The (x, y) coordinates of the intersection point.
+        """
+        self.line1 = line1
+        self.line2 = line2
+        self.point = intersection_point
+        self.angle = self._compute_angle(self.line1, self.line2)
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Returns a string representation of the intersection point and both lines.
+            Lines are shown in order of slope (lower slope first).
+        """
+
+        def format_line(line: "Line") -> str:
+            """Helper function to format a line equation."""
+            if line.xv is not None:
+                return f"x = {line.xv:.2f}"
+            else:
+                return f"y = {line.slope:.2f} * x + {line.intercept:.2f}"
+
+        lines = [self.line1, self.line2]
+        lines.sort(key=lambda line: line.slope if line.slope is not None else np.inf)
+
+        line1_eq = format_line(lines[0])
+        line2_eq = format_line(lines[1])
+
+        return f"Point {self.point} line1: [{line1_eq}] line2: [{line2_eq}]"
+
+    def _key_(self) -> tuple["Point", tuple[float, float]]:
+        """
+        Returns a tuple of identifying attributes used for hashing and equality comparison.
+        Links the intersection point with both lines for unique identification.
+
+        Returns:
+            tuple: A tuple containing the point coordinates and the keys of both lines,
+                sorted by slope (lower slope first, vertical lines last) to ensure consistent ordering.
+        """
+
+        def sort_key(line: "Line") -> tuple[float, float]:
+            primary = line.slope if line.slope is not None else np.inf
+            secondary = line.xv if line.xv is not None else -np.inf
+            return (primary, secondary)
+
+        lines = [self.line1, self.line2]
+        lines.sort(key=sort_key)
+
+        line_keys = [line._key_() for line in lines]
+        return (self.point, tuple(line_keys))
+
+
+    def distance(self, another_intersection: Self) -> float:
+        """
+        Calculate the Euclidean distance to another intersection point.
+
+        Args:
+            another_intersection (Intersection): Another intersection to compute distance to.
+
+        Returns:
+            float: The Euclidean distance.
+        """
+        return self.point.distance(another_intersection.point)
+
+
+    def other_line(self, used: "Line") -> "Line":
+        """
+        Return the line from this intersection that is NOT `used`.
+        Raises ValueError if `used` doesn't belong to this intersection.
+        """
+        if self.line1 is used or self.line1._key_() == used._key_():
+            return self.line2
+        if self.line2 is used or self.line2._key_() == used._key_():
+            return self.line1
+        raise ValueError("The provided line does not belong to this intersection.")
+
+
+    def _compute_angle(self, line1: "Line", line2: "Line") -> float:
+        """Compute the angle in degrees between two Line objects.
+
+        Args:
+            line1 (Line): First line.
+            line2 (Line): Second line.
+
+        Returns:
+            float: Angle in degrees between the two lines.
+        """
+        if line1.xv is None and line2.xv is not None:
+            angle = 90 - line1.theta
+        elif line1.xv is not None and line2.xv is None:
+            angle = 90 - line2.theta
+        elif line1.slope * line2.slope == -1:
+            angle = 90
+        else:
+            angle = np.rad2deg(np.arctan((line2.slope - line1.slope) / (1 + line1.slope * line2.slope)))
+
+        return angle + 180
+
+
+def compute_intersections(lines: list['Line'], image: ArrayLike) -> list[Intersection]:
+    """
+    Compute all intersection points between pairs of lines within image boundaries.
+    
+    This function finds all valid intersection points between every pair of lines
+    in the provided list that lie within the image boundaries. Each pair of lines
+    is checked only once to avoid duplicates.
+    
+    Args:
+        lines: List of Line objects to find intersections between
+        image: Image array used to determine valid intersection boundaries
+    
+    Returns:
+        List of Intersection objects representing valid intersection points
+    
+    Note:
+        Only intersections within the image boundaries are included. Each pair
+        of lines is processed only once (no duplicates).
+    """
+    intersections = []
+    for i in range(len(lines)):
+        for j in range(i + 1, len(lines)):
+            intersection = lines[i].intersection(lines[j], image)
+            if intersection is not None:
+                intersections.append(intersection)
+    return intersections
+
+
+def transform_intersection(
+    intersection: Intersection,
+    source_img: np.ndarray,
+    original_x_start: int,
+    original_y_start: int,
+    to_global: bool = True,
+    ) -> Intersection:
+    """
+    Transforms an Intersection in one go.
+    - If to_global=True: treats inputs as LOCAL and returns GLOBAL.
+    - If to_global=False: treats inputs as GLOBAL and returns LOCAL.
+
+    Note:
+        `source_img` should be the image in the *source* space,
+        i.e. the space you are transforming FROM. This keeps `limit_to_img`
+        correct in both directions.
+    """
+    from .lines import transform_line
+    
+    transformed_point = transform_point(intersection.point, original_x_start, original_y_start, to_global=to_global)
+    line1_t = transform_line(intersection.line1, source_img, original_x_start, original_y_start, to_global)
+    line2_t = transform_line(intersection.line2, source_img, original_x_start, original_y_start, to_global)
+    return Intersection(line1_t, line2_t, transformed_point)

cvgeomkit-0.1.0/src/cvgeomkit/geometry/lines.py

@@ -0,0 +1,422 @@
+import copy
+from typing import Iterable, Literal, Self, TYPE_CHECKING, Union
+
+import numpy as np
+
+from cvgeomkit.common import Hashable, Numeric
+from .points import Point, transform_point
+
+if TYPE_CHECKING:
+    from .intersections import Intersection
+
+
+class Line(Hashable):
+    """
+    Represents a 2D line in either slope-intercept form (y = ax + b) or vertical line form (xv = constant).
+    Distinguishes the existance of vertical lines where there is no slope and intercept but constant x-value instead.
+
+    Attributes:
+        slope (float | None): The slope (a) of the line. None if the line is vertical.
+        intercept (float | None): The y-intercept (b) of the line. None if the line is vertical.
+        xv (float | None): The constant x-value for vertical lines. None if the line is not vertical.
+
+    Note:
+        This class overloads `__eq__` and `__hash__` methods based on a unique key composed of the slope,
+        intercept, and xv attributes. This allows Line objects to be added to hash-based collections like sets
+        or used as dictionary keys. The equality comparison between Line instances is performed based on
+        the attributes defined in the internal __key method.
+    """
+
+    def __init__(self, slope: float | None = None, intercept: float | None = None, xv: float | None = None) -> None:
+        """
+        Initializes a Line instance.
+
+        Args:
+            slope (float | None, optional): The slope of the line. Defaults to None.
+            intercept (float | None, optional): The intercept of the line. Defaults to None.
+            xv (float | None, optional): The constant x-value for vertical lines. Defaults to None.
+        """
+        self.slope = slope
+        self.intercept = intercept
+        self.xv = xv
+
+    def _key_(self) -> tuple[Numeric, Numeric, Numeric | None]:
+        """
+        Returns a tuple of identifying attributes used for hashing and equality comparison.
+
+        Returns:
+            tuple: A tuple containing slope, intercept, and xv.
+        """
+        return (self.slope, self.intercept, self.xv)
+
+    def __repr__(self) -> str:
+        """
+        Returns a string representation of the line.
+
+        Returns:
+            str: String representation of the line.
+        """
+        return f"y = {self.slope} * x + {self.intercept}"
+
+    def copy(self) -> Self:
+        """
+        Creates a deep copy of the line.
+
+        Returns:
+            Line: A new Line instance with the same attributes.
+        """
+        return copy.deepcopy(self)
+
+    def intersection(self, another_line: Self, image: np.ndarray) -> Union['Intersection', None]:
+        """
+        Compute the intersection point between this line and another line,
+        and return it as an `Intersection` object if it lies within image bounds.
+
+        Args:
+            another_line (Line): The other line to intersect with.
+            image (np.ndarray): The image used to check if the intersection point lies within its bounds.
+
+        Returns:
+            Intersection | None: The intersection object if the lines intersect within the image bounds,
+            otherwise None.
+        """
+        from .intersections import Intersection
+        
+        if (self.slope is not None and another_line.slope is not None and self.slope == another_line.slope) or (
+            self.xv is not None and another_line.xv is not None
+        ):
+            return None
+
+        elif self.xv is not None and another_line.xv is None:
+            x = self.xv
+            y = another_line.slope * x + another_line.intercept
+
+        elif self.xv is None and another_line.xv is not None:
+            x = another_line.xv
+            y = self.slope * x + self.intercept
+
+        else:
+            x = (another_line.intercept - self.intercept) / (self.slope - another_line.slope)
+            y = self.slope * x + self.intercept
+
+        height, width = image.shape[:2]
+        if 0 <= x < width and 0 <= y < height:
+            return Intersection(self, another_line, Point(int(x), int(y)))
+        else:
+            return None
+
+    def y_for_x(self, x: int) -> int | None:
+        """
+        Calculates the y-coordinate on the line for a given x-coordinate.
+        It handles when line instance is vertical, then return None because y doesnt exist.
+
+        Args:
+            x (int): The x-coordinate.
+
+        Returns:
+            int | None: The corresponding y-coordinate if the line is not vertical, otherwise None.
+
+        Note:
+            The return value must be an integer because we are working with images,
+            and pixel coordinates must be whole numbers.
+        """
+        if self.slope is None or self.intercept is None:
+            return None
+        return int(self.slope * x + self.intercept)
+
+    def x_for_y(self, y: int) -> int | None:
+        """
+        Calculates the x-coordinate on the line for a given y-coordinate.
+        It handles when line instance is vertical or horizontal.
+        If Vertical line: x is constant, in case of horizontal line or undefined slope: no unique x for given y
+
+        Args:
+            y (int): The y-coordinate.
+
+        Returns:
+            int | None: The corresponding x-coordinate as an integer if the line is not horizontal;
+                        or the stored x-value if the line is vertical; otherwise, None.
+
+        Note:
+            The return value must be an integer because we are working with images,
+            and pixel coordinates must be whole numbers.
+        """
+        if self.xv is not None:
+            return int(self.xv)
+        if self.slope == 0 or self.slope is None:
+            return None
+        return int((y - self.intercept) / self.slope)
+
+    def get_points_by_distance(self, main_point: Point, distance: float) -> tuple[Point, Point]:
+        """
+        Finds two points on the line that are at a given Euclidean distance from a specified point.
+
+        Args:
+            main_point (tuple[int, int]): The reference (x, y) point from which distance is measured.
+            distance (float): The Euclidean distance to measure along the line.
+
+        Returns:
+            tuple[tuple[int, int], tuple[int, int]]: Two (x, y) integer coordinate points on the line.
+
+        Note:
+            Pixel coordinates are returned as integers.
+            For vertical lines, points are offset along the y-axis.
+        """
+        main_x, main_y = main_point
+
+        if self.xv is not None:
+            return Point(int(main_x), int(main_y - distance)), Point(int(main_x), int(main_y + distance))
+
+        if self.slope is None or self.intercept is None:
+            raise ValueError("Cannot compute points: line is not properly defined.")
+
+        m = self.slope
+        b = self.intercept
+
+        A = 1 + m**2
+        B = -2 * main_x + 2 * m * (b - main_y)
+        C = main_x**2 + (b - main_y) ** 2 - distance**2
+
+        discriminant = B**2 - 4 * A * C
+        if discriminant < 0:
+            raise ValueError("No real solution: check if the distance is too large or the point is far from the line.")
+
+        sqrt_delta = np.sqrt(discriminant)
+
+        x1 = int((-B + sqrt_delta) / (2 * A))
+        x2 = int((-B - sqrt_delta) / (2 * A))
+
+        y1 = int(self.y_for_x(x1))
+        y2 = int(self.y_for_x(x2))
+
+        return Point(x1, y1), Point(x2, y2)
+
+    def limit_to_img(self, img: np.ndarray) -> tuple[Point, Point]:
+        """
+        Returns two endpoints of the line segment clipped to the image boundaries.
+
+        Args:
+            img (np.ndarray): The image array used to determine dimensions.
+
+        Returns:
+            tuple[tuple[int, int], tuple[int, int]]: Two (x, y) points that define the visible
+            part of the line within the image.
+        """
+        img_width, img_height = img.shape[1] - 1, img.shape[0] - 1
+
+        if self.xv is not None:
+            x = int(self.xv)
+            return Point(x, 0), Point(x, img_height)
+
+        if self.slope == 0:
+            y = int(self.intercept)
+            return Point(0, y), Point(img_width, y)
+
+        points = []
+
+        x_top = self.x_for_y(0)
+        if x_top is not None and 0 <= x_top <= img_width:
+            points.append(Point(int(x_top), 0))
+
+        x_bottom = self.x_for_y(img_height)
+        if x_bottom is not None and 0 <= x_bottom <= img_width:
+            points.append(Point(int(x_bottom), img_height))
+
+        y_left = self.y_for_x(0)
+        if y_left is not None and 0 <= y_left <= img_height:
+            points.append(Point(0, int(y_left)))
+
+        y_right = self.y_for_x(img_width)
+        if y_right is not None and 0 <= y_right <= img_height:
+            points.append(Point(img_width, int(y_right)))
+
+        unique_points = list(dict.fromkeys(points))
+
+        if len(unique_points) >= 2:
+            return unique_points[0], unique_points[1]
+
+        raise ValueError("Line does not intersect the image in at least two places.")
+
+    def check_point_on_line(self, point: Point, tolerance: int = None) -> bool:
+        """
+        Checks whether a given point lies on the line, optionally within a specified tolerance.
+
+        Args:
+            point (tuple[int, int]): The (x, y) coordinates of the point to check.
+            tolerance (int, optional): Allowed deviation in pixels for both x and y.
+                                    If None, the match must be exact.
+
+        Returns:
+            bool: True if the point lies on the line (within tolerance if provided), False otherwise.
+        """
+
+        y = self.y_for_x(point.x)
+        x = self.x_for_y(point.y)
+
+        if y is None or x is None:
+            return False
+
+        line_point = Point(x, y).as_int()
+
+        if tolerance is None:
+            return point.x == line_point.x and point.y == line_point.y
+
+        return abs(line_point.y - point.y) < tolerance and abs(line_point.x - point.x) < tolerance
+
+    @property
+    def theta(self) -> float:
+        """
+        Returns the angle (in degrees) between the line and the horizontal axis.
+
+        Returns:
+            float: The angle in degrees. For vertical lines, returns 90.
+        """
+        if self.slope is None:
+            return 90.0
+        return np.degrees(np.arctan(self.slope))
+
+    @classmethod
+    def from_hough_line(cls, hough_line: tuple[int, int, int, int]) -> Self:
+        """
+        Creates a Line instance from a Hough line segment represented by two points.
+
+        Args:
+            hough_line (tuple[int, int, int, int]): A 4-tuple (x1, y1, x2, y2) representing the endpoints of the line.
+
+        Returns:
+            Line: A Line object representing the line segment.
+        """
+        x1, y1, x2, y2 = hough_line
+        return cls.from_points((x1, y1), (x2, y2))
+
+    @classmethod
+    def from_points(cls, p1: tuple[int, int], p2: tuple[int, int]) -> Self:
+        """
+        Creates a Line instance from two points.
+
+        Args:
+            p1 (tuple[int, int]): The first point (x1, y1).
+            p2 (tuple[int, int]): The second point (x2, y2).
+
+        Returns:
+            Line: A Line object defined by the two points.
+        """
+        x1, y1 = p1
+        x2, y2 = p2
+
+        if x1 == x2:
+            slope, intercept = None, None
+            xv = x1
+        else:
+            slope = (y2 - y1) / (x2 - x1)
+            intercept = y1 - slope * x1
+            xv = None
+
+        return cls(slope, intercept, xv)
+
+
+class LineGroup(Line):
+    """
+    A group of Line objects that are approximately aligned, represented as a single approximated line.
+
+    The approximation is based on the median slope/intercept (for non-vertical lines)
+    or median x-value (for vertical lines).
+    """
+
+    def __init__(self, lines: list[Line] = None) -> None:
+        self.lines = lines or []
+
+        if not self.lines:
+            self.slope = self.intercept = self.xv = None
+        else:
+            self._calculate_line_approximation()
+
+    def __repr__(self) -> str:
+        """Return a string representation of the approximated line equation."""
+        if not self.lines:
+            return "LineGroup(empty)"
+
+        if self.xv is not None:
+            return f"LineGroup: x = {self.xv:.2f} (from {len(self.lines)} lines)"
+        else:
+            return f"LineGroup: y = {self.slope:.2f} * x + {self.intercept:.2f} (from {len(self.lines)} lines)"
+
+    def process_line(self, line: Line, thresh_theta: float | int, thresh_intercept: float | int) -> bool:
+        """
+        Try to add a Line to the group if it is similar enough to the reference line.
+
+        Args:
+            line (Line): The line to evaluate and possibly add.
+            thresh_theta (float | int): Angular threshold for similarity in orientation.
+            thresh_intercept (float | int): Threshold for similarity in intercept (used for non-vertical lines).
+
+        Returns:
+            bool: True if the line was added to the group, False otherwise.
+        """
+        ref = self.lines[0]
+        found = False
+
+        if abs(ref.theta - line.theta) < thresh_theta:
+            if ref.xv is None and line.xv is None:
+                if abs(ref.intercept - line.intercept) < thresh_intercept:
+                    found = True
+
+            if ref.xv is not None or line.xv is not None:
+                found = True
+
+            if found:
+                self.lines.append(line)
+                self._calculate_line_approximation()
+
+        self.lines = sorted(self.lines, key=lambda line: -line.intercept)
+        return found
+
+    def get_line(self, line_type: Literal["min", "max"]) -> Line:
+        return {"min": self.lines[0], "max": self.lines[-1]}[line_type]
+
+    def _calculate_line_approximation(self) -> None:
+        """
+        Calculate the approximated line for the group based on the median of included lines.
+
+        - For vertical lines (with xv), median x is used.
+        - For non-vertical lines, median slope and intercept are used.
+        """
+        vertical_lines = [line.xv for line in self.lines if line.xv is not None]
+
+        if vertical_lines:
+            self.xv = np.median(vertical_lines)
+            self.slope, self.intercept = None, None
+
+        else:
+            self.xv = None
+            self.slope = np.median([line.slope for line in self.lines])
+            self.intercept = np.median([line.intercept for line in self.lines])
+
+
+def transform_line(
+    original_line: Line, 
+    original_img: np.ndarray, 
+    original_x_start: int, 
+    original_y_start: int, 
+    to_global: bool = True
+    ) -> Line:
+    """
+    Transforms a line's coordinates between local and global image reference frames.
+
+    The function shifts both endpoints of a line by the provided offsets using
+    `transform_point` and reconstructs a new line from the transformed coordinates.
+
+    Args:
+        original_line (Line): Line object to transform.
+        original_img (np.ndarray): Image used to determine line limits.
+        original_x_start (int): X-axis offset.
+        original_y_start (int): Y-axis offset.
+        to_global (bool, optional): If True, converts from local to global coordinates;
+                                    if False, converts from global to local (default: True).
+
+    Returns:
+        Line: Transformed line object with updated coordinates.
+    """
+    pts_source: Iterable[Point] = original_line.limit_to_img(original_img)
+    pts_transformed = [transform_point(p, original_x_start, original_y_start, to_global=to_global) for p in pts_source]
+    return Line.from_points(*pts_transformed)

cvgeomkit-0.1.0/src/cvgeomkit/geometry/points.py

@@ -0,0 +1,154 @@
+from typing import Iterator, TYPE_CHECKING, Self, Union
+
+import numpy as np
+
+from cvgeomkit.common import Hashable, Numeric
+
+if TYPE_CHECKING:
+    from .intersections import Intersection
+
+
+class Point[T: (Numeric, Numeric)](Hashable):
+    """Immutable 2D point represented as a generic point with two numbers."""
+
+    __slots__ = ("_x", "_y")
+
+    def __init__(self, x: T, y: T) -> None:
+        """
+        Create a new Point instance from X and Y coordinates.
+
+        Args:
+            x (T): The X coordinate (int or float).
+            y (T): The Y coordinate (int or float).
+        """
+        object.__setattr__(self, "_x", x)
+        object.__setattr__(self, "_y", y)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Prevent modification after initialization."""
+        raise AttributeError(f"'Point' object attribute '{name}' is read-only")
+
+    def _key_(self) -> tuple[T, T]:
+        """Return the key for hashing and equality comparison."""
+        return (self._x, self._y)
+
+    @classmethod
+    def from_xy(cls, x: T, y: T) -> Self:
+        """
+        Create a Point from separate X and Y values.
+
+        Args:
+            x (T): The X coordinate (int or float).
+            y (T): The Y coordinate (int or float).
+
+        Returns:
+            Point[T]: A new immutable Point instance.
+        """
+        return cls(x, y)
+
+    @classmethod
+    def from_iterable(cls, iterable: tuple[T, T] | list[T, T]) -> Self:
+        """
+        Create a Point from an iterable of exactly two elements.
+
+        Args:
+            iterable: An iterable containing exactly two numeric elements.
+
+        Returns:
+            Point[T]: A new immutable Point instance.
+
+        Raises:
+            ValueError: If the iterable does not contain exactly two elements.
+        """
+        values = tuple(iterable)
+        if len(values) != 2:
+            raise ValueError(f"Expected iterable of length 2, got {len(values)}")
+        return cls(values[0], values[1])
+
+    @property
+    def x(self) -> T:
+        """Get the X coordinate of the point."""
+        return self._x
+
+    @property
+    def y(self) -> T:
+        """Get the Y coordinate of the point."""
+        return self._y
+
+    def distance(self, another_point: Self) -> float:
+        """Calculate Euclidean distance to another point."""
+        return np.linalg.norm(np.array([self.x, self.y]) - np.array([another_point.x, another_point.y]))
+
+    def is_in_area(self, p1: Self, p2: Self) -> bool:
+        return p1.x < self.x < p2.x and p1.y < self.y < p2.y
+
+    def __getitem__(self, index: int) -> T:
+        """Allow indexing like a tuple."""
+        if index == 0:
+            return self._x
+        elif index == 1:
+            return self._y
+        else:
+            raise IndexError("Point index out of range")
+
+    def __iter__(self) -> Iterator[float]:
+        """Allow unpacking like a tuple."""
+        yield self._x
+        yield self._y
+
+    def __len__(self) -> int:
+        """Return length (always 2)."""
+        return 2
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"Point({self._x}, {self._y})"
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        return f"({self._x}, {self._y})"
+
+    def as_int(self) -> Self:
+        return Point(int(self.x), int(self.y))
+
+    def to_tuple(self) -> tuple[T, T]:
+        """
+        Convert the Point to a tuple (x, y).
+
+        Returns:
+            tuple[T, T]: A tuple containing the X and Y coordinates.
+        """
+        return (self._x, self._y)
+
+
+def transform_point(
+    point: Union['Intersection', Point], 
+    original_x_start: int, 
+    original_y_start: int, 
+    to_global: bool = True
+    ) -> Point:
+    """
+    Transforms a point's coordinates between local and global image reference frames.
+
+    The function shifts a point by the provided (x, y) offsets depending on the
+    transformation direction. Works with both `Point` and `Intersection` objects.
+
+    Args:
+        point (Intersection | Point): Point or intersection to transform.
+        original_x_start (int): X-axis offset.
+        original_y_start (int): Y-axis offset.
+        to_global (bool, optional): If True, converts from local to global coordinates;
+                                    if False, converts from global to local (default: True).
+
+    Returns:
+        Point: Transformed point with updated coordinates.
+    """
+    from .intersections import Intersection
+    
+    if isinstance(point, Intersection):
+        point = point.point
+
+    if to_global:
+        return Point(point.x + original_x_start, point.y + original_y_start)
+    else:
+        return Point(point.x - original_x_start, point.y - original_y_start)

cvgeomkit-0.1.0/src/cvgeomkit/utils/helpers.py

@@ -0,0 +1,127 @@
+from pathlib import Path
+from typing import Literal, Sequence
+
+import cv2
+import numpy as np
+
+from cvgeomkit.common import BBoxFmt, NumpyImage, Numeric
+from cvgeomkit.geometry.points import Point
+from cvgeomkit.geometry.lines import LineGroup, Line
+
+
+def convert_bbox(
+    bbox: Sequence[Numeric],
+    to_fmt: BBoxFmt,
+    returns_int: bool = True,
+) -> tuple[Numeric, Numeric, Numeric, Numeric]:
+    """
+    Convert a four-number box into ``to_fmt``.
+
+    Input layout depends on ``to_fmt``: ``XYXY`` expects ``(x, y, w, h)``;
+    ``XYWH`` expects ``(x1, y1, x2, y2)``; ``CXCYWH`` expects ``(x, y, w, h)``
+    in top-left ``xywh`` form and returns center ``x, y`` plus ``w, h``.
+    """
+    if to_fmt == BBoxFmt.XYXY:
+        x, y, w, h = bbox
+        out = (x, y, x + w, y + h)
+    elif to_fmt == BBoxFmt.XYWH:
+        x1, y1, x2, y2 = bbox
+        out = (x1, y1, x2 - x1, y2 - y1)
+    elif to_fmt == BBoxFmt.CXCYWH:
+        x, y, w, h = bbox
+        out = (x + w / 2, y + h / 2, w, h)
+    else:
+        raise ValueError(f"unsupported to_fmt: {to_fmt!r}")
+
+    if returns_int:
+        return tuple(map(int, out))
+    return out
+
+
+def rerange_hue(hue: np.ndarray) -> float:
+    """
+    Shifts the hue channel by 90 with wrap-around (overflow) within the 0–179 range.
+    Uses modulo arithmetic to keep the result within the valid hue range
+    """
+    return (hue + 90) % 180
+
+
+def group_lines(lines: list[Line], 
+    thresh_theta: float | int = 5, 
+    thresh_intercept: float | int = 10
+    ) -> list[LineGroup]:
+    """
+    Group similar Line objects into LineGroups based on orientation and position thresholds.
+
+    Args:
+        lines (list[Line]): A list of Line objects to group.
+        thresh_theta (float): Maximum allowed angle difference between lines to be in the same group.
+        thresh_intercept (float): Maximum allowed intercept difference (for non-vertical lines).
+
+    Returns:
+        list[LineGroup]: A list of LineGroup objects representing grouped lines.
+    """
+    groups = []
+
+    for line in lines:
+        for group in groups:
+            if group.process_line(line, thresh_theta, thresh_intercept):
+                break
+        else:
+            groups.append(LineGroup([line]))
+
+    return groups
+
+
+def read_image_as_numpyimage(path: str | Path, color_mode: Literal["rgb", "hsv", "grayscale"] = "rgb") -> NumpyImage:
+    """
+    Load an image from disk as a :class:`~cvgeomkit.common.NumpyImage`.
+
+    ``color_mode`` selects the channel layout after OpenCV's BGR decode:
+    ``rgb``/``hsv`` use ``cvtColor``; ``grayscale`` uses single-channel read.
+    """
+    color_mode = color_mode.lower()
+    if color_mode not in {"rgb", "hsv", "grayscale"}:
+        raise ValueError("color_mode must be 'RGB', 'HSV', or 'GRAYSCALE'")
+
+    img = cv2.imread(path, cv2.IMREAD_GRAYSCALE if color_mode == "grayscale" else cv2.IMREAD_COLOR)
+    if img is None:
+        raise FileNotFoundError(f"Cannot read image: {path}")
+
+    conversions = {
+        "rgb": lambda x: cv2.cvtColor(x, cv2.COLOR_BGR2RGB),
+        "hsv": lambda x: cv2.cvtColor(x, cv2.COLOR_BGR2HSV),
+    }
+
+    img = conversions.get(color_mode, lambda x: x)(img)
+    return NumpyImage(img)
+
+
+def order_clockwise(
+    points: np.ndarray | Sequence[Point] | Sequence[Sequence[Numeric]],
+) -> np.ndarray:
+    """
+    Sort 2D points clockwise around their mean (centroid), by polar angle.
+
+    Accepts an ``(N, 2)`` array, a sequence of :class:`~cvgeomkit.geometry.points.Point`,
+    or nested sequences of two numbers. Fewer than three points are returned unchanged.
+    """
+    if isinstance(points, np.ndarray):
+        arr = np.asarray(points, dtype=float)
+
+    elif points and isinstance(points[0], Point):
+        arr = np.array([[p.x, p.y] for p in points], dtype=float)
+
+    else:
+        arr = np.asarray(points, dtype=float)
+
+    if arr.ndim != 2 or arr.shape[1] != 2:
+        raise ValueError("points must be of shape (N, 2)")
+
+    if len(arr) < 3:
+        return arr
+
+    center = arr.mean(axis=0)
+    angles = np.arctan2(arr[:, 1] - center[1], arr[:, 0] - center[0])
+
+    return arr[np.argsort(-angles)]

cvgeomkit-0.1.0/src/cvgeomkit/utils/metrics.py

@@ -0,0 +1,35 @@
+import numpy as np
+from shapely.geometry import Polygon
+from cvgeomkit.common import Numeric
+from cvgeomkit.geometry.points import Point
+from .helpers import order_clockwise
+
+
+def iou(
+    area1: list[list[Numeric]] | list[Point] | np.ndarray,
+    area2: list[list[Numeric]] | list[Point] | np.ndarray,
+) -> float:
+    """
+    Intersection-over-union of two polygons given as vertex rings.
+
+    Vertices are oriented consistently via :func:`~cvgeomkit.utils.helpers.order_clockwise`
+    before building Shapely polygons.
+    """
+    area1 = order_clockwise(area1)
+    area2 = order_clockwise(area2)
+
+    area1 = Polygon(area1)
+    area2 = Polygon(area2)
+
+    intersection = area1.intersection(area2).area
+    union = area1.union(area2).area
+
+    return intersection / union if union > 0 else 0.0
+
+
+def euclidean_distance(
+        point1: Point | np.ndarray | list[Numeric], 
+        point2: Point | np.ndarray | list[Numeric]
+) -> float:
+    """Euclidean distance between two 2D points (each as ``Point``, array, or pair of numbers)."""
+    return np.linalg.norm(np.array(point1) - np.array(point2))