geomask 0.1.0__py3-none-any.whl

geomask/__init__.py

@@ -0,0 +1,173 @@
+from dataclasses import dataclass, field
+from typing import Self, Union, TYPE_CHECKING
+import numpy as np
+from shapely import Polygon, MultiPolygon, intersection, Geometry, MultiPoint
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+SpatialGeometry = Union[Polygon, MultiPolygon]
+
+
+@dataclass(slots=True)
+class GeoMask:
+    """A geometric mask for spatial data processing.
+
+    This class creates a regular grid of points within a given geometry
+    and provides methods for spatial masking operations.
+
+    Attributes:
+        geom: The input spatial geometry (Polygon or MultiPolygon)
+        resolution: Grid resolution for point generation
+        offset: Optional offset for grid positioning
+        limit: Optional limit on number of points
+        mask: The resulting geometric mask after intersection (computed automatically)
+    """
+
+    geom: SpatialGeometry
+    resolution: float
+    offset: tuple[float, float] | None = None
+    limit: int | None = None
+    mask: Geometry = field(init=False)
+
+    def __post_init__(self) -> None:
+        if self.resolution <= 0:
+            raise ValueError("Resolution must be positive")
+        if self.limit is not None and self.limit <= 0:
+            raise ValueError("Limit must be positive")
+        if not isinstance(self.geom, (Polygon, MultiPolygon)):
+            raise TypeError("Geometry must be a Polygon or MultiPolygon")
+
+        self.mask = self._generate_mask()
+
+    def _generate_mask(self) -> Geometry:
+        """Generate the grid mask based on geometry and parameters.
+
+        Returns:
+            The geometric mask after intersection with the grid
+        """
+        actual_resolution = self.resolution
+        if self.limit:
+            estimated_points = self.geom.area / (self.resolution**2)
+            if estimated_points > self.limit:
+                actual_resolution = np.sqrt(self.geom.area / self.limit)
+                object.__setattr__(self, "resolution", actual_resolution)
+
+        xmin, ymin, xmax, ymax = self.geom.bounds
+
+        grid_bounds = (
+            np.floor(xmin / actual_resolution) * actual_resolution,
+            np.floor(ymin / actual_resolution) * actual_resolution,
+            np.ceil(xmax / actual_resolution) * actual_resolution,
+            np.ceil(ymax / actual_resolution) * actual_resolution,
+        )
+
+        xcoords, ycoords = np.meshgrid(
+            np.arange(grid_bounds[0], grid_bounds[2], actual_resolution),
+            np.arange(grid_bounds[1], grid_bounds[3], actual_resolution),
+        )
+
+        if self.offset:
+            xoffset, yoffset = self.offset
+            xcoords += xoffset
+            ycoords += yoffset
+
+        mcoords = np.column_stack((xcoords.flatten(), ycoords.flatten()))
+        points = MultiPoint(mcoords)
+
+        return intersection(self.geom, points)
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        return self.geom.bounds
+
+    @property
+    def area(self) -> float:
+        return self.geom.area
+
+    @property
+    def point_count(self) -> int:
+        """Get the number of points in the mask."""
+        if self.mask.is_empty:
+            return 0
+        elif hasattr(self.mask, "geoms"):
+            return len([p for p in self.mask.geoms if not p.is_empty])
+        return 1 if not self.mask.is_empty else 0
+
+    def to_coordinates(self) -> np.ndarray:
+        """Extract coordinates from the mask as a numpy array.
+
+        Returns:
+            Array of shape (n, 2) containing x, y coordinates
+        """
+        if self.mask.is_empty:
+            return np.array([]).reshape(0, 2)
+        elif hasattr(self.mask, "geoms"):
+            coords = []
+            for point in self.mask.geoms:
+                if not point.is_empty:
+                    coords.append([point.x, point.y])
+            return np.array(coords) if coords else np.array([]).reshape(0, 2)
+        elif hasattr(self.mask, "x") and hasattr(self.mask, "y"):
+            return np.array([[self.mask.x, self.mask.y]])
+        return np.array([]).reshape(0, 2)
+
+    def to_dataframe(self, x_col: str = "x", y_col: str = "y") -> "pd.DataFrame":
+        """Extract coordinates from the mask as a pandas DataFrame.
+
+        Args:
+            x_col: Name for the x-coordinate column (default: 'x')
+            y_col: Name for the y-coordinate column (default: 'y')
+
+        Returns:
+            DataFrame with specified column names containing coordinates
+
+        Raises:
+            ImportError: If pandas is not available
+        """
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError(
+                "pandas is required for to_dataframe(). "
+                "Install it with: pip install pandas"
+            )
+
+        coords = self.to_coordinates()
+        if coords.size == 0:
+            return pd.DataFrame(columns=[x_col, y_col])
+
+        return pd.DataFrame(coords, columns=[x_col, y_col])
+
+    def filter_by_geometry(self, filter_geom: SpatialGeometry, **kwargs) -> Self:
+        """Create a new GeoMask filtered by another geometry.
+
+        Args:
+            filter_geom: Geometry to filter by
+            **kwargs: Additional arguments passed to shapely.intersection
+
+        Returns:
+            A new filtered GeoMask instance
+        """
+        filtered_mask = intersection(self.mask, filter_geom, **kwargs)
+
+        new_instance = self.__class__(
+            geom=self.geom,
+            resolution=self.resolution,
+            offset=self.offset,
+            limit=self.limit,
+        )
+        object.__setattr__(new_instance, "mask", filtered_mask)
+        return new_instance
+
+    def __len__(self) -> int:
+        return self.point_count
+
+    def __bool__(self) -> bool:
+        return not self.mask.is_empty
+
+    def __repr__(self) -> str:
+        return (
+            f"GeoMask(area={self.area:.2f}, resolution={self.resolution:.3f}, "
+            f"points={self.point_count}, offset={self.offset}, limit={self.limit})"
+        )

geomask-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Henrique Campiotti
+
+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.

geomask-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.3
+Name: geomask
+Version: 0.1.0
+Summary: A very simple lib for creating geometric masks from spatial data using regular grids
+License: MIT
+Keywords: gis,spatial,grid,geometry,mask
+Author: campiohe
+Author-email: campiottihenrique@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Dist: shapely (>=2.1.1,<3.0.0)
+Project-URL: Homepage, https://github.com/campiohe/geomask
+Project-URL: Issues, https://github.com/campiohe/geomask/issues
+Project-URL: Repository, https://github.com/campiohe/geomask
+Description-Content-Type: text/markdown
+
+# GeoMask
+
+A very simple lib for creating geometric masks from spatial data using regular grids.
+
+## Features
+
+- Create regular grids of points inside spacial geometries (polygons or multipolygons)
+- Control grid spacing with a resolution parameter
+- Optional point limits to avoid huge grids
+- Export to pandas DataFrames
+
+## Installation
+
+```bash
+pip install geomask
+```
+
+## Quick Start
+
+```python
+from geomask import GeoMask
+from shapely import Polygon
+
+# Create a polygon
+polygon = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+
+# Generate a grid mask
+mask = GeoMask(geom=polygon, resolution=1.0)
+
+print(f"Generated {len(mask)} points")
+print(f"Area: {mask.area}")
+print(f"Bounds: {mask.bounds}")
+```
+
+## Core Functionality
+
+### Creating Masks
+
+```python
+from geomask import GeoMask
+from shapely import Polygon, MultiPolygon
+
+# Basic usage
+polygon = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+mask = GeoMask(geom=polygon, resolution=2.0)
+
+# With point limit
+mask = GeoMask(geom=polygon, resolution=0.5, limit=100)
+
+# With grid offset
+mask = GeoMask(geom=polygon, resolution=1.0, offset=(0.5, 0.5))
+
+# Works with MultiPolygons too
+poly1 = Polygon([(0, 0), (5, 0), (5, 5), (0, 5)])
+poly2 = Polygon([(10, 10), (15, 10), (15, 15), (10, 15)])
+multipoly = MultiPolygon([poly1, poly2])
+mask = GeoMask(geom=multipoly, resolution=1.0)
+```
+
+### Extracting Coordinates
+
+```python
+# As numpy array
+coords = mask.to_coordinates()
+print(f"Shape: {coords.shape}")  # (n_points, 2)
+
+# As pandas DataFrame (requires pandas)
+df = mask.to_dataframe()
+print(df.head())
+
+# Custom column names
+df = mask.to_dataframe(x_col='longitude', y_col='latitude')
+df = mask.to_dataframe(x_col='easting', y_col='northing')
+```
+
+### Filtering and Analysis
+
+```python
+# Filter by another geometry
+filter_polygon = Polygon([(2, 2), (8, 2), (8, 8), (2, 8)])
+filtered_mask = mask.filter_by_geometry(filter_polygon)
+
+# Properties and methods
+print(f"Point count: {len(mask)}")
+print(f"Has points: {bool(mask)}")
+print(f"Area: {mask.area}")
+print(f"Bounds: {mask.bounds}")
+```
+
+### Integration with Pandas
+
+```python
+import pandas as pd
+import numpy as np
+
+# Convert to DataFrame for analysis
+df = mask.to_dataframe(x_col='x', y_col='y')
+
+# Add computed columns
+df['distance_from_origin'] = np.sqrt(df.x**2 + df.y**2)
+df['quadrant'] = df.apply(
+    lambda row: ('N' if row.y >= 0 else 'S') + ('E' if row.x >= 0 else 'W'), 
+    axis=1
+)
+
+# Analysis
+print(df.describe())
+print(df.quadrant.value_counts())
+
+# Filter points
+close_points = df[df.distance_from_origin < 5.0]
+```
+
+## Advanced Usage
+
+### Working with Complex Geometries
+
+```python
+# Polygon with hole
+outer = [(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]
+inner = [(3, 3), (7, 3), (7, 7), (3, 7), (3, 3)]
+polygon_with_hole = Polygon(outer, [inner])
+
+mask = GeoMask(geom=polygon_with_hole, resolution=1.0)
+```
+
+### Performance Optimization
+
+```python
+# Use limits for large areas
+large_polygon = Polygon([(0, 0), (1000, 0), (1000, 1000), (0, 1000)])
+
+# This will automatically adjust resolution to meet the limit
+mask = GeoMask(geom=large_polygon, resolution=1.0, limit=10000)
+print(f"Actual resolution used: {mask.resolution}")
+```
+
+## Requirements
+
+- Python 3.11+
+- shapely >= 2.1.1
+- numpy
+- pandas (optional, for DataFrame functionality)
+
+## Development
+
+### Testing
+
+Run the comprehensive test suite:
+
+```bash
+# Basic tests
+pytest test_geomask.py
+
+# With coverage
+pytest test_geomask.py --cov=geomask --cov-report=term-missing
+
+# Verbose output
+pytest test_geomask.py -v
+```
+

geomask-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+geomask/__init__.py,sha256=CZYNEpQROzPd1MuiXGJDhe_Zd7PqIA9T6ZvJy1ir1pA,5961
+geomask-0.1.0.dist-info/LICENSE,sha256=zoVsLApRuFuvZL5VkVIKqADTbE-emx3B9kaaE31NmY8,1075
+geomask-0.1.0.dist-info/METADATA,sha256=HBxNbmlcj3OJE6-T4aLgAe0IGFzYL7jlwjFroA8OPi8,4396
+geomask-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+geomask-0.1.0.dist-info/RECORD,,

geomask-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any