Address kwargs and boundary naming conventions

Author: willGraham01

movement/roi/base.py

@@ -117,7 +117,8 @@ def __init__(
             ``shapely.Polygon`` for details. Ignored if ``dimensions`` is 1.
         name : str, default None
             Human-readable name to assign to the given region, for
-            user-friendliness.
+            user-friendliness. Default name given is 'Un-named region' if no
+            explicit name is provided.
 
         """
         self._name = name

movement/roi/line.py

@@ -37,8 +37,10 @@ def __init__(
             If True, the final point in ``points`` will be connected by an
             additional line segment to the first, creating a closed loop.
             (See Notes).
-        name : str
-            Name of the LoI that is to be created.
+        name : str, optional
+            Name of the LoI that is to be created. A default name will be
+            inherited from the base class if not provided, and
+            defaults are inherited from.
 
         Notes
         -----
@@ -47,5 +49,10 @@ def __init__(
         analysis, we recommend you create a ``PolygonOfInterest`` and use
         its ``boundary`` property instead.
 
+        See Also
+        --------
+        movement.roi.base.BaseRegionOfInterest
+            The base class that constructor arguments are passed to.
+
         """
         super().__init__(points, dimensions=1, closed=loop, name=name)

movement/roi/polygon.py

@@ -1,5 +1,7 @@
 """2-dimensional regions of interest."""
 
+from __future__ import annotations
+
 from collections.abc import Sequence
 
 from movement.roi.base import BaseRegionOfInterest, PointLikeList
@@ -18,36 +20,53 @@ class PolygonOfInterest(BaseRegionOfInterest):
     interest (RoIs) in an analysis. The basic usage is to construct an
     instance of this class by passing in a list of points, which will then be
     joined (in sequence) by straight lines between consecutive pairs of points,
-    to form the boundary of the RoI. Note that the boundary itself is a
-    (closed) ``LineOfInterest``, and may be treated accordingly.
+    to form the exterior boundary of the RoI. Note that the exterior boundary
+    (accessible as via the ``.exterior`` property) is a (closed)
+    ``LineOfInterest``, and may be treated accordingly.
+
+    The class also supports holes - subregions properly contained inside the
+    region that are not part of the region itself. These can be specified by
+    the ``holes`` argument, and define the interior boundaries of the region.
+    These interior boundaries are accessible via the ``.interior_boundaries``
+    property, and the polygonal regions that make up the holes are accessible
+    via the ``holes`` property.
     """
 
     def __init__(
         self,
-        boundary: PointLikeList,
+        exterior_boundary: PointLikeList,
         holes: Sequence[PointLikeList] | None = None,
         name: str | None = None,
     ) -> None:
         """Create a new region of interest (RoI).
 
         Parameters
         ----------
-        boundary : tuple of (x, y) pairs
+        exterior_boundary : tuple of (x, y) pairs
             The points (in sequence) that make up the boundary of the region.
             At least three points must be provided.
         holes : sequence of sequences of (x, y) pairs, default None
             A sequence of items, where each item will be interpreted like
             ``boundary``. These items will be used to construct internal holes
             within the region. See the ``holes`` argument to
             ``shapely.Polygon`` for details.
-        name : str
-            Name of the RoI that is to be created.
+        name : str, optional
+            Name of the RoI that is to be created. A default name will be
+            inherited from the base class if not provided.
+
+        See Also
+        --------
+        movement.roi.base.BaseRegionOfInterest
+            The base class that constructor arguments are passed to, and
+            defaults are inherited from.
 
         """
-        super().__init__(points=boundary, dimensions=2, holes=holes, name=name)
+        super().__init__(
+            points=exterior_boundary, dimensions=2, holes=holes, name=name
+        )
 
     @property
-    def exterior(self) -> LineOfInterest:
+    def exterior_boundary(self) -> LineOfInterest:
         """The exterior boundary of this RoI."""
         return LineOfInterest(
             self.region.exterior.coords,
@@ -56,12 +75,26 @@ def exterior(self) -> LineOfInterest:
         )
 
     @property
-    def interiors(self) -> tuple[LineOfInterest, ...]:
-        """The interior boundaries of this RoI.
+    def holes(self) -> tuple[PolygonOfInterest, ...]:
+        """The interior holes of this RoI.
 
-        Interior boundaries are the boundaries of holes contained within the polygon.
+        Holes are regions properly contained within the exterior boundary of
+        the RoI that are not part of the RoI itself (like the centre of a
+        doughnut, for example). A region with no holes returns the empty tuple.
+        """
+        return tuple(
+            PolygonOfInterest(
+                int_boundary.coords, name=f"Hole {i} of {self.name}"
+            )
+            for i, int_boundary in enumerate(self.region.interiors)
+        )
+
+    @property
+    def interior_boundaries(self) -> tuple[LineOfInterest, ...]:
+        """The interior boundaries of this RoI.
 
-        A region with no interior boundaries returns the empty tuple.
+        Interior boundaries are the boundaries of holes contained within the
+        polygon.  A region with no holes returns the empty tuple.
         """
         return tuple(
             LineOfInterest(

tests/test_unit/test_roi/test_polygon_boundary.py

@@ -40,8 +40,8 @@ def test_boundary(exterior_boundary, interior_boundaries, request) -> None:
         shapely.LinearRing(ib) for ib in interior_boundaries
     )
 
-    computed_exterior = polygon.exterior
-    computed_interiors = polygon.interiors
+    computed_exterior = polygon.exterior_boundary
+    computed_interiors = polygon.interior_boundaries
 
     assert isinstance(computed_exterior, LineOfInterest)
     assert expected_exterior.equals_exact(computed_exterior.region, tolerance)