deoverlap 0.1.1__tar.gz

deoverlap-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Pietro Leoni]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deoverlap-0.1.1/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: deoverlap
+Version: 0.1.1
+Summary: A high-level toolkit for de-overlapping Shapely geometries.
+Author-email: Pietro Leoni <pietro.leoni@gmail.com>
+License: MIT License
+        
+        Copyright (c) [2025] [Pietro Leoni]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/piLeoni/deoverlap
+Project-URL: Bug Tracker, https://github.com/piLeoni/deoverlap
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: shapely>=2.0
+Requires-Dist: tqdm
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: matplotlib; extra == "test"
+Dynamic: license-file
+
+# Deoverlap
+
+A high-level Python module for de-overlapping a set of Shapely geometric objects. It offers two main modes of operation: a fast "flat" mode that returns simple geometries, and a more powerful "structured" mode that preserves geometry types and can track the origin of removed pieces.
+
+![](test_outputs/test_tangent_circles_and_line_s_F_k_T.png)
+## Motivation
+
+When working with geospatial data, it's common to encounter datasets where geometries (such as lines representing roads or polygons representing land parcels) overlap one another. For many analysis and visualization tasks, it is desirable to remove these overlaps, ensuring that each point in space is covered by at most one geometry. This process, which we call "de-overlapping," can be complex to implement efficiently.
+
+This module provides a robust and easy-to-use solution for de-overlapping Shapely geometries. It intelligently handles various geometry types and provides fine-grained control over the output, making it a valuable tool for data cleaning and preparation in geospatial workflows.
+
+## Installation
+
+You can install `deoverlap` directly from PyPI using pip:
+
+```bash
+pip install deoverlap
+```
+
+## How to Use
+
+The core of this module is the `deoverlap` function. It takes an iterable of Shapely geometries and a tolerance value as input and returns the de-overlapped geometries.
+
+### Basic Usage: Flat Mode
+
+The default mode of operation is the "flat" mode (`preserve_types=False`). This mode is optimized for speed and returns a simple list of `LineString` and `Point` geometries. In this mode, any input `Polygon` objects are converted to their boundary `LineString`.
+
+Here's a simple example of de-overlapping two overlapping `LineString`:
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [LineString([(0, 0), (2, 0)]), LineString([(1, 0.05), (3, 0.05)])]
+tolerance = 0.1
+
+kept_geoms, removed_geoms, mask = deoverlap(geoms, tolerance)
+
+print(f"Kept geometries: {len(kept_geoms)}")
+print(f"Removed geometries: {len(removed_geoms)}")
+```
+
+## Advanced Usage
+
+The `deoverlap` function offers several parameters to control its behavior:
+
+- `preserve_types` (`bool`): When `True`, the function will attempt to preserve the original geometry types (e.g., `Polygon`, `MultiLineString`). This is more computationally intensive but provides a more structured output.
+- `keep_duplicates` (`bool`): If `True`, the function will also return the portions of the geometries that were removed due to overlap.
+- `track_origins` (`bool`): Only applicable when `preserve_types=True`. If `True`, the output is a dictionary that maps the removed parts to their original index in the input list. This is useful for understanding which original geometries were affected by the de-overlapping process.
+
+![](test_outputs/test_tangent_circles_and_line_s_T_k_T.png)
+### Preserving Geometry Types
+
+Set `preserve_types=True` to maintain the original geometry types in the output. This is particularly useful when working with Polygons or when you need to maintain the distinction between single and multi-part geometries.
+
+**Example:** De-overlapping a `LineString` that intersects another. With `preserve_types=True`, the intersected `LineString` is returned as a `MultiLineString`.
+
+- `preserve_types=False` (default, flat output):
+- `preserve_types=True` (structured output):
+
+### Keeping Removed Portions
+
+Set `keep_duplicates=True` to get a list of the geometries (or portions of geometries) that were removed.
+
+**Example:** Visualizing the removed portion of an engulfed `LineString`.
+
+- `keep_duplicates=False` (default):
+- `keep_duplicates=True` (showing removed parts):
+
+### Tracking the Origin of Removed Parts
+
+For detailed analysis of which input geometries were modified, use `track_origins=True` in conjunction with `preserve_types=True`. This returns a dictionary containing the kept geometries, a map of removed parts to their original indices, a list of indices of geometries that were wholly removed, and the overlap mask.
+
+**Example:**
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [
+    LineString([(0, 0), (4, 0)]),
+    LineString([(1, 0.05), (2, 0.05)]),  # This line will be wholly removed
+    LineString([(3, 0.05), (5, 0.05)])
+]
+tolerance = 0.1
+
+results = deoverlap(
+    geoms,
+    tolerance,
+    preserve_types=True,
+    keep_duplicates=True,
+    track_origins=True
+)
+
+print(f"Kept geometries: {len(results['kept'])}")
+print(f"Removed parts map: {results['removed_parts']}")
+print(f"Wholly removed indices: {results['wholly_removed_indices']}")
+```
+
+This will produce the following output, clearly indicating that the geometry at index 1 was completely removed:
+
+```
+Kept geometries: 2
+Removed parts map: {0: [<MultiLineString object>], 1: [<LineString object>], 2: [<LineString object>]}
+Wholly removed indices: [1]
+```
+
+## Working with Polygons and Mixed Geometries
+
+The `deoverlap` function can handle a mix of geometry types, including Polygons. When `preserve_types` is `False`, polygons are treated as their boundary lines. When `preserve_types` is `True`, the function attempts to preserve the `Polygon` objects, clipping them as necessary.
+
+**Example:** De-overlapping a set of tangent circles and a line.
+
+- `preserve_types=False` (flat output):
+- `preserve_types=True` (structured output):
+
+## API Reference
+
+### `deoverlap(geometries, tolerance, preserve_types=False, keep_duplicates=False, track_origins=False, progress_bar=False)`
+
+De-overlaps a list of geometries with extensive options for output format and origin tracking.
+
+#### Parameters:
+
+- `geometries` (`GeomInput`): An iterable of Shapely geometries.
+- `tolerance` (`float`): The buffer distance to consider geometries as overlapping.
+- `preserve_types` (`bool`, optional):
+  - `False` (Default): Fast mode. Returns a flat list of simple `LineString`s and `Point`s.
+  - `True`: Powerful mode. Returns structured geometries (e.g., `MultiLineString`). Slower.
+- `keep_duplicates` (`bool`, optional): If `True`, the removed/overlapping portions are returned. Defaults to `False`.
+- `track_origins` (`bool`, optional): Only applies when `preserve_types=True`. If `True`, returns a detailed dictionary mapping removed parts to their original index. Defaults to `False`.
+- `progress_bar` (`bool`, optional): If `True`, displays a tqdm progress bar. Defaults to `False`.
+
+#### Returns:
+
+- The return type depends on the flags:
+  - If `preserve_types=False` (flat mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) geometries (LineString, Point)
+    - `kept_map`: Always an empty dict in this mode
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=False` (structured mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) structured geometries
+    - `kept_map`: Dict mapping input index to list of kept geometries
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=True` (structured mode with origin tracking):
+    A dictionary with keys:
+    - `"kept"`: List of kept (non-overlapping) structured geometries
+    - `"kept_parts"`: Dict mapping input index to list of kept geometries
+    - `"removed_parts"`: Dict mapping input index to list of removed geometries (if `keep_duplicates=True`, else empty dict)
+    - `"wholly_removed_indices"`: List of indices of geometries that were wholly removed
+    - `"mask"`: List of mask polygons used for clipping
+

deoverlap-0.1.1/README.md

@@ -0,0 +1,156 @@
+# Deoverlap
+
+A high-level Python module for de-overlapping a set of Shapely geometric objects. It offers two main modes of operation: a fast "flat" mode that returns simple geometries, and a more powerful "structured" mode that preserves geometry types and can track the origin of removed pieces.
+
+![](test_outputs/test_tangent_circles_and_line_s_F_k_T.png)
+## Motivation
+
+When working with geospatial data, it's common to encounter datasets where geometries (such as lines representing roads or polygons representing land parcels) overlap one another. For many analysis and visualization tasks, it is desirable to remove these overlaps, ensuring that each point in space is covered by at most one geometry. This process, which we call "de-overlapping," can be complex to implement efficiently.
+
+This module provides a robust and easy-to-use solution for de-overlapping Shapely geometries. It intelligently handles various geometry types and provides fine-grained control over the output, making it a valuable tool for data cleaning and preparation in geospatial workflows.
+
+## Installation
+
+You can install `deoverlap` directly from PyPI using pip:
+
+```bash
+pip install deoverlap
+```
+
+## How to Use
+
+The core of this module is the `deoverlap` function. It takes an iterable of Shapely geometries and a tolerance value as input and returns the de-overlapped geometries.
+
+### Basic Usage: Flat Mode
+
+The default mode of operation is the "flat" mode (`preserve_types=False`). This mode is optimized for speed and returns a simple list of `LineString` and `Point` geometries. In this mode, any input `Polygon` objects are converted to their boundary `LineString`.
+
+Here's a simple example of de-overlapping two overlapping `LineString`:
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [LineString([(0, 0), (2, 0)]), LineString([(1, 0.05), (3, 0.05)])]
+tolerance = 0.1
+
+kept_geoms, removed_geoms, mask = deoverlap(geoms, tolerance)
+
+print(f"Kept geometries: {len(kept_geoms)}")
+print(f"Removed geometries: {len(removed_geoms)}")
+```
+
+## Advanced Usage
+
+The `deoverlap` function offers several parameters to control its behavior:
+
+- `preserve_types` (`bool`): When `True`, the function will attempt to preserve the original geometry types (e.g., `Polygon`, `MultiLineString`). This is more computationally intensive but provides a more structured output.
+- `keep_duplicates` (`bool`): If `True`, the function will also return the portions of the geometries that were removed due to overlap.
+- `track_origins` (`bool`): Only applicable when `preserve_types=True`. If `True`, the output is a dictionary that maps the removed parts to their original index in the input list. This is useful for understanding which original geometries were affected by the de-overlapping process.
+
+![](test_outputs/test_tangent_circles_and_line_s_T_k_T.png)
+### Preserving Geometry Types
+
+Set `preserve_types=True` to maintain the original geometry types in the output. This is particularly useful when working with Polygons or when you need to maintain the distinction between single and multi-part geometries.
+
+**Example:** De-overlapping a `LineString` that intersects another. With `preserve_types=True`, the intersected `LineString` is returned as a `MultiLineString`.
+
+- `preserve_types=False` (default, flat output):
+- `preserve_types=True` (structured output):
+
+### Keeping Removed Portions
+
+Set `keep_duplicates=True` to get a list of the geometries (or portions of geometries) that were removed.
+
+**Example:** Visualizing the removed portion of an engulfed `LineString`.
+
+- `keep_duplicates=False` (default):
+- `keep_duplicates=True` (showing removed parts):
+
+### Tracking the Origin of Removed Parts
+
+For detailed analysis of which input geometries were modified, use `track_origins=True` in conjunction with `preserve_types=True`. This returns a dictionary containing the kept geometries, a map of removed parts to their original indices, a list of indices of geometries that were wholly removed, and the overlap mask.
+
+**Example:**
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [
+    LineString([(0, 0), (4, 0)]),
+    LineString([(1, 0.05), (2, 0.05)]),  # This line will be wholly removed
+    LineString([(3, 0.05), (5, 0.05)])
+]
+tolerance = 0.1
+
+results = deoverlap(
+    geoms,
+    tolerance,
+    preserve_types=True,
+    keep_duplicates=True,
+    track_origins=True
+)
+
+print(f"Kept geometries: {len(results['kept'])}")
+print(f"Removed parts map: {results['removed_parts']}")
+print(f"Wholly removed indices: {results['wholly_removed_indices']}")
+```
+
+This will produce the following output, clearly indicating that the geometry at index 1 was completely removed:
+
+```
+Kept geometries: 2
+Removed parts map: {0: [<MultiLineString object>], 1: [<LineString object>], 2: [<LineString object>]}
+Wholly removed indices: [1]
+```
+
+## Working with Polygons and Mixed Geometries
+
+The `deoverlap` function can handle a mix of geometry types, including Polygons. When `preserve_types` is `False`, polygons are treated as their boundary lines. When `preserve_types` is `True`, the function attempts to preserve the `Polygon` objects, clipping them as necessary.
+
+**Example:** De-overlapping a set of tangent circles and a line.
+
+- `preserve_types=False` (flat output):
+- `preserve_types=True` (structured output):
+
+## API Reference
+
+### `deoverlap(geometries, tolerance, preserve_types=False, keep_duplicates=False, track_origins=False, progress_bar=False)`
+
+De-overlaps a list of geometries with extensive options for output format and origin tracking.
+
+#### Parameters:
+
+- `geometries` (`GeomInput`): An iterable of Shapely geometries.
+- `tolerance` (`float`): The buffer distance to consider geometries as overlapping.
+- `preserve_types` (`bool`, optional):
+  - `False` (Default): Fast mode. Returns a flat list of simple `LineString`s and `Point`s.
+  - `True`: Powerful mode. Returns structured geometries (e.g., `MultiLineString`). Slower.
+- `keep_duplicates` (`bool`, optional): If `True`, the removed/overlapping portions are returned. Defaults to `False`.
+- `track_origins` (`bool`, optional): Only applies when `preserve_types=True`. If `True`, returns a detailed dictionary mapping removed parts to their original index. Defaults to `False`.
+- `progress_bar` (`bool`, optional): If `True`, displays a tqdm progress bar. Defaults to `False`.
+
+#### Returns:
+
+- The return type depends on the flags:
+  - If `preserve_types=False` (flat mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) geometries (LineString, Point)
+    - `kept_map`: Always an empty dict in this mode
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=False` (structured mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) structured geometries
+    - `kept_map`: Dict mapping input index to list of kept geometries
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=True` (structured mode with origin tracking):
+    A dictionary with keys:
+    - `"kept"`: List of kept (non-overlapping) structured geometries
+    - `"kept_parts"`: Dict mapping input index to list of kept geometries
+    - `"removed_parts"`: Dict mapping input index to list of removed geometries (if `keep_duplicates=True`, else empty dict)
+    - `"wholly_removed_indices"`: List of indices of geometries that were wholly removed
+    - `"mask"`: List of mask polygons used for clipping
+

deoverlap-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+# pyproject.toml
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deoverlap"
+version = "0.1.1"
+authors = [
+  { name="Pietro Leoni", email="pietro.leoni@gmail.com" },
+]
+description = "A high-level toolkit for de-overlapping Shapely geometries."
+readme = "README.md"
+license = { file="LICENSE" }
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "shapely>=2.0",
+    "tqdm"
+]
+
+[project.urls]
+Homepage = "https://github.com/piLeoni/deoverlap"
+"Bug Tracker" = "https://github.com/piLeoni/deoverlap"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "matplotlib"
+]

deoverlap-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deoverlap-0.1.1/src/deoverlap/__init__.py

@@ -0,0 +1,6 @@
+"""
+A Python toolkit for resolving overlaps in 2D vector geometries.
+"""
+__version__ = "0.1.1"
+
+from .deoverlap import deoverlap, flatten_geometries, GeomInput

deoverlap-0.1.1/src/deoverlap/deoverlap.py

@@ -0,0 +1,293 @@
+"""
+This module provides high-level functions for de-overlapping a set of Shapely
+geometric objects. It intelligently removes portions of geometries that are
+within a specified tolerance of geometries earlier in the processing order.
+
+It offers two main modes of operation: a fast "flat" mode that returns simple
+geometries (Points and LineStrings), and a more powerful "structured" mode that
+preserves geometry types and can track the origin of removed pieces.
+"""
+
+from typing import List, Union, Iterable, Tuple, Dict, Any
+from shapely import union_all
+from shapely.ops import unary_union
+from shapely.strtree import STRtree
+from tqdm import tqdm
+from shapely.geometry import (
+    LineString, Point, MultiLineString, MultiPoint,
+    Polygon, MultiPolygon, GeometryCollection
+)
+from shapely.geometry.base import BaseGeometry
+
+# =============================================================================
+#  Type Aliases
+# =============================================================================
+# Using type aliases for better readability and maintainability of type hints.
+GeomInput = Union[BaseGeometry, Iterable['GeomInput']]
+FlatGeomOutput = List[Union[LineString, Point]]
+
+# =============================================================================
+#  Helper Function
+# =============================================================================
+
+def flatten_geometries(geoms: GeomInput) -> FlatGeomOutput:
+    """
+    Recursively flattens any geometry input into a flat list of non-empty
+    LineStrings and Points.
+
+    This utility is used to decompose complex geometries into a simple,
+    standardized format that the de-overlapping engines can process.
+
+    Args:
+        geoms: A Shapely geometry or a nested iterable of geometries.
+
+    Returns:
+        A flat list of simple Point and LineString geometries. Polygons are
+        converted to their exterior and interior boundary LineStrings.
+    """
+    out = []
+    if geoms is None: return out
+
+    # Use modern pattern matching for clear, type-safe dispatching.
+    match geoms:
+        case LineString() | Point():
+            if not geoms.is_empty: out.append(geoms)
+        case MultiLineString() | MultiPoint() | GeometryCollection():
+            # Recursively flatten all geometries within a collection.
+            for g in geoms.geoms: out.extend(flatten_geometries(g))
+        case Polygon():
+            # Convert Polygons to their constituent rings (LineStrings).
+            if not geoms.is_empty:
+                out.append(LineString(geoms.exterior.coords))
+                for ring in geoms.interiors: out.append(LineString(ring.coords))
+        case MultiPolygon():
+            # Handle MultiPolygons by flattening each Polygon individually.
+            for poly in geoms.geoms: out.extend(flatten_geometries(poly))
+        case list() | tuple() | set():
+            # Handle standard iterable types.
+            for g in geoms: out.extend(flatten_geometries(g))
+        case _:
+            # Fallback for any other type that is a valid Shapely geometry
+            # but not explicitly listed above. This provides some future-proofing.
+            if not isinstance(geoms, BaseGeometry):
+                 raise TypeError(f"Unsupported geometry type: {type(geoms)}")
+    return out
+
+# =============================================================================
+#  Internal Engine Functions
+# =============================================================================
+
+def _deoverlap_flat_engine(
+    geometries: GeomInput,
+    tolerance: float,
+    progress_bar: bool,
+) -> Tuple[FlatGeomOutput, FlatGeomOutput, list]:
+    """
+    Internal engine for fast, flat de-overlapping.
+
+    This function prioritizes performance by working with a flattened list of
+    simple geometries. It always computes both the kept and removed portions.
+
+    Args:
+        geometries: The input geometries to de-overlap.
+        tolerance: The buffer distance to define the overlap area.
+        progress_bar: Whether to display a tqdm progress bar.
+
+    Returns:
+        A tuple containing:
+            - A flat list of the kept (non-overlapping) geometries.
+            - A flat list of the removed (overlapping) geometries.
+            - The list of mask polygons used for clipping.
+    """
+    mask, flat_geoms, kept_geoms, removed_geoms = [], flatten_geometries(geometries), [], []
+    
+    # A tiny buffer used to resolve floating-point ambiguities. When geometries
+    # are perfectly aligned, a simple `.difference()` can be inconsistent.
+    # Buffering the clipping mask ensures robust results.
+    ROBUSTNESS_BUFFER = 1e-9
+
+    iterable = tqdm(flat_geoms, desc="De-overlapping (flat)", disable=not progress_bar)
+
+    for geom in iterable:
+        kept_portion = geom
+        
+        # Only perform clipping if a mask has been built up from previous geometries.
+        if mask:
+            # Use an STRtree for efficient spatial querying of nearby mask polygons.
+            # This is much faster than checking against the entire mask every time.
+            tree = STRtree(mask)
+            if (nearby_indices := tree.query(geom)).size > 0:
+                # Create a local mask from only the relevant nearby polygons.
+                local_mask = union_all([mask[i] for i in nearby_indices])
+                # The core operation: clip the geometry by the buffered local mask.
+                kept_portion = geom.difference(local_mask.buffer(ROBUSTNESS_BUFFER))
+        
+        # Add the kept portion to the results and update the master mask for the next iteration.
+        if not kept_portion.is_empty:
+            kept_geoms.append(kept_portion)
+            mask.append(kept_portion.buffer(tolerance))
+        
+        # The removed portion is simply what's left of the original after the difference.
+        if not (removed_portion := geom.difference(kept_portion)).is_empty:
+            removed_geoms.append(removed_portion)
+            
+    # Return flattened lists, as difference operations can create multi-part geometries.
+    return flatten_geometries(kept_geoms), flatten_geometries(removed_geoms), mask
+
+def _deoverlap_structured_engine(
+    geometries: Iterable[BaseGeometry],
+    tolerance: float,
+    progress_bar: bool,
+) -> Tuple[List[BaseGeometry], Dict[int, List[BaseGeometry]], Dict[int, List[BaseGeometry]], List[int], List[Polygon]]:
+    """
+    Internal engine for structure-preserving de-overlapping with origin tracking.
+
+    This function is more powerful, preserving geometry types where possible
+    and tracking the origin of all kept and removed pieces.
+
+    Args:
+        geometries: The input geometries to de-overlap.
+        tolerance: The buffer distance to define the overlap area.
+        progress_bar: Whether to display a tqdm progress bar.
+
+    Returns:
+        A tuple containing:
+            - A list of the final kept (non-overlapping) structured geometries.
+            - A dictionary mapping original index to its list of kept geometries.
+            - A dictionary mapping original index to its list of removed parts.
+            - A list of indices of geometries that were wholly removed.
+            - The list of mask polygons used for clipping.
+    """
+    kept_results, kept_parts_map, removed_parts_map, wholly_removed_indices, mask = [], {}, {}, [], []
+    ROBUSTNESS_BUFFER = 1e-9
+
+    iterable = tqdm(list(geometries), desc="De-overlapping (structured)", disable=not progress_bar)
+    
+    # Enumerate to get the original index 'i' for origin tracking.
+    for i, geom in enumerate(iterable):
+        if geom.is_empty: continue
+
+        # Decompose the current top-level geometry into its constituent primitive
+        # parts (e.g., a MultiLineString becomes a list of LineStrings).
+        parts_to_process = flatten_geometries(geom)
+        if not parts_to_process: continue
+
+        kept_sub_parts = []
+        if not mask:
+            # If the mask is empty (i.e., this is the first geometry), keep all parts.
+            kept_sub_parts = parts_to_process
+        else:
+            # Check each constituent part against the cumulative mask.
+            tree = STRtree(mask)
+            for part in parts_to_process:
+                if (nearby_indices := tree.query(part)).size > 0:
+                    local_mask = union_all([mask[i] for i in nearby_indices])
+                    if not (kept_part := part.difference(local_mask.buffer(ROBUSTNESS_BUFFER))).is_empty:
+                        kept_sub_parts.append(kept_part)
+                else: # Part is not near any existing mask geometry, so it's kept entirely.
+                    kept_sub_parts.append(part)
+        
+        # If no sub-parts survived the clipping, the entire original geometry was removed.
+        if not kept_sub_parts:
+            wholly_removed_indices.append(i)
+            # Store the entire original geometry as the "removed part".
+            removed_parts_map.setdefault(i, []).append(geom)
+            continue
+        
+        # Reassemble the surviving sub-parts into a single, valid geometry.
+        # e.g., two LineStrings become one MultiLineString.
+        reassembled_kept_geom = unary_union(kept_sub_parts)
+        
+        # This is a crucial check to preserve Polygons. If a Polygon was clipped
+        # but its boundary remains a single, intact ring, we restore the original
+        # Polygon object instead of just returning its boundary line.
+        final_kept_geom = reassembled_kept_geom
+        if geom.geom_type == 'Polygon' and reassembled_kept_geom.equals(geom.boundary):
+             final_kept_geom = geom
+        
+        # Store the final kept geometry in both the simple list and the origin-tracked map.
+        kept_results.append(final_kept_geom)
+        kept_parts_map.setdefault(i, []).append(final_kept_geom)
+        
+        # Calculate the removed portion for origin tracking.
+        # For Polygons, we must diff against its boundary, not its area, to get
+        # the removed LineString fragments correctly.
+        source_for_diff = geom.boundary if isinstance(geom, (Polygon, MultiPolygon)) else geom
+        if not (removed_portion := source_for_diff.difference(reassembled_kept_geom)).is_empty:
+             removed_parts_map.setdefault(i, []).append(removed_portion)
+        
+        # Update the master mask with the buffer of the geometry that was *actually kept*.
+        mask.append(reassembled_kept_geom.buffer(tolerance))
+        
+    return kept_results, kept_parts_map, removed_parts_map, wholly_removed_indices, mask
+
+# =============================================================================
+#  Single Public-Facing Function
+# =============================================================================
+
+def deoverlap(
+    geometries: GeomInput,
+    tolerance: float,
+    preserve_types: bool = False,
+    keep_duplicates: bool = False,
+    track_origins: bool = False,
+    progress_bar: bool = False,
+) -> Any:
+    """De-overlaps a list of geometries, with extensive options for output format.
+
+    This is the main public-facing function that acts as a dispatcher to the
+    internal engines based on user-selected flags.
+
+    Args:
+        geometries: An iterable of shapely geometries.
+        tolerance: The buffer distance to consider geometries as overlapping.
+        preserve_types (bool, optional):
+            - `False` (Default): Fast mode. Returns a flat list of simple
+              LineStrings and Points.
+            - `True`: Powerful mode. Returns structured geometries
+              (e.g., MultiLineString). Slower but more informative.
+        keep_duplicates (bool, optional):
+            If `True`, the removed/overlapping portions are also returned.
+            Defaults to False.
+        track_origins (bool, optional):
+            Only applies when `preserve_types=True`. If `True`, returns a
+            detailed dictionary with full origin tracking. Defaults to False.
+        progress_bar (bool, optional):
+            If `True`, displays a tqdm progress bar during processing.
+            Defaults to False.
+
+    Returns:
+        The return type is dynamic and depends on the flags:
+        - `preserve_types=False`:
+          `(kept_geoms, kept_map, removed_geoms, mask)` where `kept_map` is empty.
+        - `preserve_types=True` and `track_origins=False`:
+          `(kept_geoms, kept_map, removed_geoms, mask)`
+        - `preserve_types=True` and `track_origins=True`:
+          A dictionary with keys `("kept", "kept_parts", "removed_parts",
+          "wholly_removed_indices", "mask")`.
+    """
+    # --- Mode 1: Fast, Flat Output ---
+    if not preserve_types:
+        kept, removed, mask = _deoverlap_flat_engine(geometries, tolerance, progress_bar)
+        # Return a consistent 4-item tuple for predictable unpacking in tests.
+        return kept, {}, (removed if keep_duplicates else []), mask
+    
+    # --- Mode 2: Structure-Preserving Output ---
+    kept, kept_map, removed_map, wholly_removed, mask = _deoverlap_structured_engine(geometries, tolerance, progress_bar)
+    
+    # Sub-mode: Return the detailed dictionary with full origin tracking.
+    if track_origins:
+        return {
+            "kept": kept,
+            "kept_parts": kept_map,
+            "removed_parts": (removed_map if keep_duplicates else {}),
+            "wholly_removed_indices": wholly_removed,
+            "mask": mask
+        }
+    else:
+        # Sub-mode: Return a simplified tuple for compatibility.
+        removed_list = []
+        if keep_duplicates:
+            for parts in removed_map.values():
+                removed_list.extend(parts)
+        return kept, kept_map, removed_list, mask

deoverlap-0.1.1/src/deoverlap.egg-info/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: deoverlap
+Version: 0.1.1
+Summary: A high-level toolkit for de-overlapping Shapely geometries.
+Author-email: Pietro Leoni <pietro.leoni@gmail.com>
+License: MIT License
+        
+        Copyright (c) [2025] [Pietro Leoni]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/piLeoni/deoverlap
+Project-URL: Bug Tracker, https://github.com/piLeoni/deoverlap
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: shapely>=2.0
+Requires-Dist: tqdm
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: matplotlib; extra == "test"
+Dynamic: license-file
+
+# Deoverlap
+
+A high-level Python module for de-overlapping a set of Shapely geometric objects. It offers two main modes of operation: a fast "flat" mode that returns simple geometries, and a more powerful "structured" mode that preserves geometry types and can track the origin of removed pieces.
+
+![](test_outputs/test_tangent_circles_and_line_s_F_k_T.png)
+## Motivation
+
+When working with geospatial data, it's common to encounter datasets where geometries (such as lines representing roads or polygons representing land parcels) overlap one another. For many analysis and visualization tasks, it is desirable to remove these overlaps, ensuring that each point in space is covered by at most one geometry. This process, which we call "de-overlapping," can be complex to implement efficiently.
+
+This module provides a robust and easy-to-use solution for de-overlapping Shapely geometries. It intelligently handles various geometry types and provides fine-grained control over the output, making it a valuable tool for data cleaning and preparation in geospatial workflows.
+
+## Installation
+
+You can install `deoverlap` directly from PyPI using pip:
+
+```bash
+pip install deoverlap
+```
+
+## How to Use
+
+The core of this module is the `deoverlap` function. It takes an iterable of Shapely geometries and a tolerance value as input and returns the de-overlapped geometries.
+
+### Basic Usage: Flat Mode
+
+The default mode of operation is the "flat" mode (`preserve_types=False`). This mode is optimized for speed and returns a simple list of `LineString` and `Point` geometries. In this mode, any input `Polygon` objects are converted to their boundary `LineString`.
+
+Here's a simple example of de-overlapping two overlapping `LineString`:
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [LineString([(0, 0), (2, 0)]), LineString([(1, 0.05), (3, 0.05)])]
+tolerance = 0.1
+
+kept_geoms, removed_geoms, mask = deoverlap(geoms, tolerance)
+
+print(f"Kept geometries: {len(kept_geoms)}")
+print(f"Removed geometries: {len(removed_geoms)}")
+```
+
+## Advanced Usage
+
+The `deoverlap` function offers several parameters to control its behavior:
+
+- `preserve_types` (`bool`): When `True`, the function will attempt to preserve the original geometry types (e.g., `Polygon`, `MultiLineString`). This is more computationally intensive but provides a more structured output.
+- `keep_duplicates` (`bool`): If `True`, the function will also return the portions of the geometries that were removed due to overlap.
+- `track_origins` (`bool`): Only applicable when `preserve_types=True`. If `True`, the output is a dictionary that maps the removed parts to their original index in the input list. This is useful for understanding which original geometries were affected by the de-overlapping process.
+
+![](test_outputs/test_tangent_circles_and_line_s_T_k_T.png)
+### Preserving Geometry Types
+
+Set `preserve_types=True` to maintain the original geometry types in the output. This is particularly useful when working with Polygons or when you need to maintain the distinction between single and multi-part geometries.
+
+**Example:** De-overlapping a `LineString` that intersects another. With `preserve_types=True`, the intersected `LineString` is returned as a `MultiLineString`.
+
+- `preserve_types=False` (default, flat output):
+- `preserve_types=True` (structured output):
+
+### Keeping Removed Portions
+
+Set `keep_duplicates=True` to get a list of the geometries (or portions of geometries) that were removed.
+
+**Example:** Visualizing the removed portion of an engulfed `LineString`.
+
+- `keep_duplicates=False` (default):
+- `keep_duplicates=True` (showing removed parts):
+
+### Tracking the Origin of Removed Parts
+
+For detailed analysis of which input geometries were modified, use `track_origins=True` in conjunction with `preserve_types=True`. This returns a dictionary containing the kept geometries, a map of removed parts to their original indices, a list of indices of geometries that were wholly removed, and the overlap mask.
+
+**Example:**
+
+```python
+from shapely.geometry import LineString
+from deoverlap import deoverlap
+
+geoms = [
+    LineString([(0, 0), (4, 0)]),
+    LineString([(1, 0.05), (2, 0.05)]),  # This line will be wholly removed
+    LineString([(3, 0.05), (5, 0.05)])
+]
+tolerance = 0.1
+
+results = deoverlap(
+    geoms,
+    tolerance,
+    preserve_types=True,
+    keep_duplicates=True,
+    track_origins=True
+)
+
+print(f"Kept geometries: {len(results['kept'])}")
+print(f"Removed parts map: {results['removed_parts']}")
+print(f"Wholly removed indices: {results['wholly_removed_indices']}")
+```
+
+This will produce the following output, clearly indicating that the geometry at index 1 was completely removed:
+
+```
+Kept geometries: 2
+Removed parts map: {0: [<MultiLineString object>], 1: [<LineString object>], 2: [<LineString object>]}
+Wholly removed indices: [1]
+```
+
+## Working with Polygons and Mixed Geometries
+
+The `deoverlap` function can handle a mix of geometry types, including Polygons. When `preserve_types` is `False`, polygons are treated as their boundary lines. When `preserve_types` is `True`, the function attempts to preserve the `Polygon` objects, clipping them as necessary.
+
+**Example:** De-overlapping a set of tangent circles and a line.
+
+- `preserve_types=False` (flat output):
+- `preserve_types=True` (structured output):
+
+## API Reference
+
+### `deoverlap(geometries, tolerance, preserve_types=False, keep_duplicates=False, track_origins=False, progress_bar=False)`
+
+De-overlaps a list of geometries with extensive options for output format and origin tracking.
+
+#### Parameters:
+
+- `geometries` (`GeomInput`): An iterable of Shapely geometries.
+- `tolerance` (`float`): The buffer distance to consider geometries as overlapping.
+- `preserve_types` (`bool`, optional):
+  - `False` (Default): Fast mode. Returns a flat list of simple `LineString`s and `Point`s.
+  - `True`: Powerful mode. Returns structured geometries (e.g., `MultiLineString`). Slower.
+- `keep_duplicates` (`bool`, optional): If `True`, the removed/overlapping portions are returned. Defaults to `False`.
+- `track_origins` (`bool`, optional): Only applies when `preserve_types=True`. If `True`, returns a detailed dictionary mapping removed parts to their original index. Defaults to `False`.
+- `progress_bar` (`bool`, optional): If `True`, displays a tqdm progress bar. Defaults to `False`.
+
+#### Returns:
+
+- The return type depends on the flags:
+  - If `preserve_types=False` (flat mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) geometries (LineString, Point)
+    - `kept_map`: Always an empty dict in this mode
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=False` (structured mode):
+    `(kept_geoms, kept_map, removed_geoms, mask)`
+    - `kept_geoms`: List of kept (non-overlapping) structured geometries
+    - `kept_map`: Dict mapping input index to list of kept geometries
+    - `removed_geoms`: List of removed (overlapping) geometries (if `keep_duplicates=True`, else empty list)
+    - `mask`: List of mask polygons used for clipping
+  - If `preserve_types=True` and `track_origins=True` (structured mode with origin tracking):
+    A dictionary with keys:
+    - `"kept"`: List of kept (non-overlapping) structured geometries
+    - `"kept_parts"`: Dict mapping input index to list of kept geometries
+    - `"removed_parts"`: Dict mapping input index to list of removed geometries (if `keep_duplicates=True`, else empty dict)
+    - `"wholly_removed_indices"`: List of indices of geometries that were wholly removed
+    - `"mask"`: List of mask polygons used for clipping
+

deoverlap-0.1.1/src/deoverlap.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/deoverlap/__init__.py
+src/deoverlap/deoverlap.py
+src/deoverlap.egg-info/PKG-INFO
+src/deoverlap.egg-info/SOURCES.txt
+src/deoverlap.egg-info/dependency_links.txt
+src/deoverlap.egg-info/requires.txt
+src/deoverlap.egg-info/top_level.txt
+tests/test_deoverlap.py

deoverlap-0.1.1/src/deoverlap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

deoverlap-0.1.1/src/deoverlap.egg-info/requires.txt

@@ -0,0 +1,6 @@
+shapely>=2.0
+tqdm
+
+[test]
+pytest
+matplotlib

deoverlap-0.1.1/src/deoverlap.egg-info/top_level.txt

@@ -0,0 +1 @@
+deoverlap

deoverlap-0.1.1/tests/test_deoverlap.py

@@ -0,0 +1,257 @@
+import os
+import inspect
+import pytest
+from typing import Union, Iterable
+from itertools import cycle
+import matplotlib.pyplot as plt
+import numpy as np
+from shapely import union_all
+from shapely.geometry import (LineString, Point, MultiLineString,
+                             Polygon, MultiPolygon, GeometryCollection)
+from shapely.geometry.base import BaseGeometry
+
+from deoverlap import deoverlap, flatten_geometries
+
+GeomInput = Union[BaseGeometry, Iterable['GeomInput']]
+
+# =============================================================================
+#  Global Color Configuration
+# =============================================================================
+
+# Colors for the default "flat" mode plots
+FLAT_MODE_COLORS = {
+    "kept": "#0A8AB2",
+    "removed": "#FF0249",
+    "mask": "#F26835",
+    "background": "#F2F2F2"
+}
+
+# Default color palette for "structured" (preserve_types=True) mode plots.
+# This list will be cycled through for each original geometry.
+STRUCTURED_COLOR_PALETTE = [
+    '#2DA6CC', '#0A8AB2', '#52b69a', '#FFF029', '#C0D99A',
+    '#1A1F4A', '#72588C', '#D98299', '#7CA687', '#314022'
+]
+
+
+# =============================================================================
+#  Test Visualization Helper (Using Global Colors)
+# =============================================================================
+def plot_results(input_geoms: GeomInput, kept_items: dict, removed_items: Union[list, dict], mask: list, filename: str = None, title: str = None, folder: str = 'test_outputs', color_palette: list = None):
+    """
+    Generates and saves a plot visualizing the results of the deoverlap process.
+    Uses global color variables for styling.
+    """
+    # --- Filename and Title Setup (unchanged) ---
+    if filename is None:
+        test_name = "unknown_test"
+        try:
+            stack_frame = inspect.stack()[1]
+            test_name = stack_frame.function
+            if color_palette:
+                test_name += "_custom_palette"
+            params = stack_frame[0].f_locals
+            param_str_list = []
+            if 'preserve_types' in params: param_str_list.append(f"s_{str(params['preserve_types'])[0]}")
+            if 'keep_duplicates' in params: param_str_list.append(f"k_{str(params['keep_duplicates'])[0]}")
+            if 'track_origins' in params: param_str_list.append(f"o_{str(params['track_origins'])[0]}")
+            filename = f"{test_name}_{'_'.join(param_str_list)}" if param_str_list else test_name
+        except (KeyError, IndexError):
+            filename = test_name
+    if title is None:
+        try:
+            test_name = inspect.stack()[1].function
+            main_title_line = test_name.replace('_', ' ').capitalize()
+            params = inspect.stack()[1][0].f_locals
+            param_lines = []
+            if 'preserve_types' in params: param_lines.append(f"preserve_types: {params.get('preserve_types')}")
+            if 'keep_duplicates' in params: param_lines.append(f"keep_duplicates: {params.get('keep_duplicates')}")
+            if 'track_origins' in params: param_lines.append(f"track_origins: {params.get('track_origins', False)}")
+            title = main_title_line
+            if param_lines:
+                title += "\n\n" + "\n".join(param_lines)
+        except (KeyError, IndexError):
+            title = filename.replace('_', ' ').capitalize()
+
+    # --- Plotting Setup ---
+    os.makedirs(folder, exist_ok=True)
+    fig, ax = plt.subplots(figsize=(8, 8), constrained_layout=True)
+    labels_used = set()
+    params = inspect.stack()[1][0].f_locals
+    input_geoms_list = list(input_geoms)
+    LEGEND_THRESHOLD = 20
+    enable_legend = len(input_geoms_list) <= LEGEND_THRESHOLD
+    def add_to_legend(label):
+        if enable_legend and label not in labels_used:
+            labels_used.add(label)
+            return label
+        return ""
+
+    # --- Set plot bounds (unchanged) ---
+    if flat_inputs := flatten_geometries(input_geoms_list):
+        all_bounds = [g.bounds for g in flat_inputs if not g.is_empty]
+        if all_bounds:
+            min_x, min_y, max_x, max_y = (min(b[0] for b in all_bounds), min(b[1] for b in all_bounds),
+                                          max(b[2] for b in all_bounds), max(b[3] for b in all_bounds))
+            width, height = max_x - min_x, max_y - min_y
+            max_dim = max(width, height) if max(width, height) > 0 else 1
+            padding = max_dim * 0.1
+            center_x, center_y = (min_x + max_x) / 2, (min_y + max_y) / 2
+            half_size = (max_dim / 2) + padding
+            ax.set_xlim(center_x - half_size, center_x + half_size)
+            ax.set_ylim(center_y - half_size, center_y + half_size)
+
+    # --- Draw geometries using global colors ---
+    active_palette = color_palette if color_palette is not None else STRUCTURED_COLOR_PALETTE
+    color_cycler = cycle(active_palette)
+    structured_colors = {i: next(color_cycler) for i in range(len(input_geoms_list))}
+
+    if mask and not (full_mask := union_all(mask)).is_empty:
+        for poly in getattr(full_mask, 'geoms', [full_mask]):
+            if isinstance(poly, Polygon):
+                ax.plot(*poly.exterior.xy, color=FLAT_MODE_COLORS["mask"], linewidth=0.5, label=add_to_legend('Mask Outline'), zorder=1)
+                for interior in poly.interiors:
+                    ax.plot(*interior.xy, color=FLAT_MODE_COLORS["mask"], linewidth=0.5, zorder=1)
+
+    for g in flatten_geometries(input_geoms_list):
+        if g.geom_type == 'LineString':
+            ax.plot(*g.xy, color=FLAT_MODE_COLORS["background"], linewidth=5, alpha=0.6, zorder=2, solid_capstyle='round')
+        elif g.geom_type == 'Point':
+            ax.plot(g.x, g.y, 'o', color=FLAT_MODE_COLORS["background"], markersize=15, alpha=0.6, zorder=2)
+
+    # --- Plot Kept Items ---
+    if params.get('preserve_types'):
+        for i, kept_parts in kept_items.items():
+            color = structured_colors.get(i)
+            for k_geom in flatten_geometries(kept_parts):
+                if k_geom.geom_type == 'LineString':
+                    ax.plot(*k_geom.xy, color=color, linewidth=2.5, label=add_to_legend(f'Kept from {i}'), zorder=4, solid_capstyle='round')
+                elif k_geom.geom_type == 'Point':
+                    ax.plot(k_geom.x, k_geom.y, 'o', color=color, markersize=8, label=add_to_legend(f'Kept from {i}'), zorder=5)
+    else: # Flat mode
+        flat_kept = list(kept_items.values())[0]
+        for g in flatten_geometries(flat_kept):
+            if g.geom_type == 'LineString':
+                ax.plot(*g.xy, color=FLAT_MODE_COLORS["kept"], linewidth=2.5, label=add_to_legend('Kept'), zorder=4, alpha=0.75, solid_capstyle='round')
+            elif g.geom_type == 'Point':
+                ax.plot(g.x, g.y, 'o', color=FLAT_MODE_COLORS["kept"], markersize=8, label=add_to_legend('Kept'), zorder=5)
+
+    # --- Plot Removed Items ---
+    if isinstance(removed_items, dict): # track_origins=True case
+        for i, removed_parts_list in removed_items.items():
+            color = structured_colors.get(i)
+            for r_geom in flatten_geometries(removed_parts_list):
+                if r_geom.geom_type == 'LineString':
+                    ax.plot(*r_geom.xy, color=color, linewidth=2.0, linestyle='--', label=add_to_legend(f'Removed from {i}'), zorder=3, solid_capstyle='round')
+                elif r_geom.geom_type == 'Point':
+                    ax.plot(r_geom.x, r_geom.y, 'x', color=color, markersize=10, mew=2.5, label=add_to_legend(f'Removed from {i}'), zorder=4)
+    elif isinstance(removed_items, list): # All other cases
+        color = FLAT_MODE_COLORS["removed"]
+        if params.get('preserve_types'):
+            pass
+        for g in flatten_geometries(removed_items):
+            if g.geom_type == 'LineString':
+                ax.plot(*g.xy, color=color, linewidth=2.5, label=add_to_legend('Removed'), zorder=3, solid_capstyle='round')
+            elif g.geom_type == 'Point':
+                ax.plot(g.x, g.y, 'x', color=color, markersize=10, mew=2.5, label=add_to_legend('Removed'), zorder=4)
+
+    # --- Finalize plot ---
+    if title:
+        ax.set_title(title, fontsize=10, pad=20, loc='center')
+    ax.set_aspect('equal', adjustable='box')
+    ax.axis('off')
+    if labels_used:
+        ax.legend(loc='lower right')
+    plt.savefig(os.path.join(folder, f"{filename}.png"), dpi=150)
+    plt.close(fig)
+
+
+# =============================================================================
+#  Comprehensive Test Suite (Unchanged)
+# =============================================================================
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_simple_line_overlap(preserve_types, keep_duplicates):
+    geoms = [LineString([(0, 0), (2, 0)]), LineString([(1, 0.05), (3, 0.05)])]
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.1, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    if preserve_types: assert len(kept) == 2
+    else: assert len(kept) == 2
+    if keep_duplicates: assert len(removed) > 0
+    else: assert len(removed) == 0
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_line_fully_engulfed(preserve_types, keep_duplicates):
+    geoms = [LineString([(0, 0), (3, 0)]), LineString([(1, 0), (2, 0)])]
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.2, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    assert len(kept) == 1
+    if keep_duplicates: assert len(removed) == 1
+    else: assert len(removed) == 0
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_complex_intersection(preserve_types, keep_duplicates):
+    geoms = [LineString([(0, 1), (3, 1)]), LineString([(1.5, 0), (1.5, 2)])]
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.2, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    if preserve_types: assert len(kept) == 2
+    else: assert len(kept) == 3
+    if keep_duplicates: assert len(removed) == 1
+    else: assert len(removed) == 0
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_tangent_circles_and_line(preserve_types, keep_duplicates):
+    geoms = [ Point(0, 0).buffer(1.5), Point(2.0, 0).buffer(0.5), Point(0, 2.5).buffer(1.0), LineString([(-2, 1), (3, 1)]) ]
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.1, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    if preserve_types: assert len(kept) == 4
+    else: assert len(kept) > 4
+    if keep_duplicates: assert len(removed) > 0
+    else: assert len(removed) == 0
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_high_volume_points(preserve_types, keep_duplicates):
+    points = [Point(x*0.2, y*0.2) for x in range(10) for y in range(10)]
+    remover_poly = Polygon([(0.5, 0.5), (0.5, 1.5), (1.5, 1.5), (1.5, 0.5)])
+    geoms = [remover_poly] + points
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.1, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    kept_points = [g for g in flatten_geometries(kept) if isinstance(g, Point)]
+    removed_points = [g for g in flatten_geometries(removed) if isinstance(g, Point)]
+    if keep_duplicates: assert len(kept_points) + len(removed_points) == len(points)
+    else: assert len(removed) == 0 and len(kept_points) < len(points)
+
+def test_origin_tracking_feature():
+    geoms = [ LineString([(0, 0), (4, 0)]), LineString([(1, 0.05), (2, 0.05)]), LineString([(3, 0.05), (5, 0.05)]) ]
+    results = deoverlap(geoms, 0.1, preserve_types=True, keep_duplicates=True, track_origins=True)
+    plot_results(geoms, results["kept_parts"], results["removed_parts"], results["mask"])
+    assert isinstance(results, dict)
+    assert len(results["kept"]) == 2
+    assert results["wholly_removed_indices"] == [1]
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+@pytest.mark.parametrize("keep_duplicates", [True, False])
+def test_tangent_circles(preserve_types, keep_duplicates):
+    geoms = [ Point(0, 1).buffer(1), Point(0, 2).buffer(2), Point(0, 3).buffer(3) ]
+    kept, kept_map, removed, mask = deoverlap(geoms, 0.1, preserve_types, keep_duplicates)
+    plot_results(geoms, kept_map if preserve_types else {0: kept}, removed, mask)
+    if preserve_types: assert len(kept) == 3
+    else: assert len(kept) > 3
+    if keep_duplicates: assert len(removed) > 0
+    else: assert len(removed) == 0
+
+@pytest.mark.parametrize("preserve_types", [True, False])
+def test_empty_input(preserve_types):
+    output = deoverlap([], 0.1, preserve_types=preserve_types, track_origins=True)
+    if preserve_types:
+        assert isinstance(output, dict) and not output["kept"] and not output["removed_parts"]
+    else:
+        assert isinstance(output, tuple) and len(output) == 4
+        assert output[0] == []
+        assert output[1] == {}
+        assert output[2] == []