sh-batch-grid-builder 0.2.0__tar.gz

sh_batch_grid_builder-0.2.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: sh-batch-grid-builder
+Version: 0.2.0
+Summary: A tool for generating projection grid aligned bounding boxes and pixelated geometries from AOI (Area of Interest) files for Sentinel Hub Batch V2 API on CDSE
+Author-email: Maxim Lamare <maxim.lamare@sinergise.com>
+License: MIT
+Keywords: gis,geospatial,grid,pixelation,bounding-box
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: geopandas>=0.12.0
+Requires-Dist: pyproj>=3.4.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: rasterio>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# SH Batch Grid Builder
+
+This tool is designed to build custom tiling grids for the [Sentinel Hub Batch V2 API](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/BatchV2.html) on [CDSE](https://dataspace.copernicus.eu/). The custom grid is built around an input AOI for a given projection and ensures the Batch request produces outputs matching the pixel grid of the given projection.
+
+## Features
+
+- **Aligned Bounding Boxes**: Generate projection grid-aligned bounding boxes that snap to a specified grid resolution
+- **Pixelated Geometries**: Convert geometries to pixelated representations in order to only query data for the given AOI
+- **Automatic Splitting**: Automatically splits large geometries that exceed pixel limits
+- **Multiple CRS Support**: Works with any EPSG code, automatically handling CRS-specific grid origins
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install sh-batch-grid-builder
+```
+
+### From Source
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Command Line Interface
+
+The tool provides a command-line interface via the `sh-grid-builder` command:
+
+```bash
+sh-grid-builder <input_aoi> --resolution "(x,y)" --epsg <epsg_code> --output-type <type> -o <output_file>
+```
+
+#### Arguments
+
+- `input_aoi`: Path to input AOI file (GeoJSON, GPKG, or other formats supported by GeoPandas)
+- `--resolution`: Grid resolution as `(x,y)` tuple in CRS coordinate units:
+  - Format: `"(x,y)"` or `"x,y"` (brackets optional, e.g., `"(300,359)"` or `"300,359"`)
+  - **Important**: Always quote the resolution value to prevent shell interpretation (e.g., `--resolution "(300,359)"` or `--resolution "300,359"`)
+  - Note the resolution **must** be in the units of the selected projection (e.g. EPSG:3035: resolution in meters; EPSG:4326: resolution in degrees).
+  - X and Y resolutions can be different to support non-square pixels
+- The tool automatically detects and displays the CRS units when running
+- `--epsg`: EPSG code for the output CRS (e.g., `3035` for ETRS89 / LAEA Europe, `4326` for WGS84)
+- `--output-type`: Type of output to generate:
+  - `bounding-box`: Generate an aligned bounding box that covers the AOI
+  - `pixelated`: Generate pixelated geometry of the AOI
+- `-o, --output`: Path to output file (GPKG format required)
+
+#### Examples
+
+Generate aligned bounding boxes with same resolution for x and y:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(10,10)" --epsg 3035 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate aligned bounding boxes with different x and y resolutions:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(300,359)" --epsg 32632 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate pixelated geometry:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "10,10" --epsg 3035 --output-type pixelated -o output_pixelated.gpkg
+```
+
+Example with geographic CRS (degrees):
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(0.001,0.001)" --epsg 4326 --output-type bounding-box -o output_bbox.gpkg
+```
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from sh_batch_grid_builder import GeoData
+
+# Initialize with AOI file, EPSG code, and resolutions (x, y)
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=3035, resolution_x=10.0, resolution_y=10.0)
+
+# Or with different x and y resolutions
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=4326, resolution_x=0.002976190476204, resolution_y=0.002976190476204)
+
+# Generate aligned bounding boxes
+aligned_bboxes = geo_data.create_aligned_bounding_box(max_pixels=3500)
+
+# Generate pixelated geometry (includes all pixels that touch/intersect the AOI)
+pixelated_geom = geo_data.create_pixelated_geometry(max_pixels=3500)
+
+# Save results
+aligned_bboxes.to_file("output_bbox.gpkg", driver="GPKG")
+pixelated_geom.to_file("output_pixelated.gpkg", driver="GPKG")
+```
+
+## How It Works
+
+### Aligned Bounding Boxes
+
+The tool creates bounding boxes that are aligned to a grid based on:
+1. The specified X and Y resolutions (can be different for non-square pixels)
+2. The CRS origin (false easting/northing) for projected coordinate systems
+3. Automatic splitting when dimensions exceed 3500 pixels (fixed limit)
+
+### Pixelated Geometries
+
+The pixelated geometry generation uses a raster-based approach:
+1. Converts the input geometry to a raster mask
+2. Polygonizes the raster back to vector format
+3. Automatically splits large geometries to avoid memory issues
+
+This approach is much faster than vector-based methods for large grids. Pixelated
+output includes any pixel that touches/intersects the AOI.
+
+## Requirements
+
+- Python >= 3.8
+- geopandas >= 0.12.0
+- pyproj >= 3.4.0
+- shapely >= 2.0.0
+- rasterio >= 1.3.0
+- numpy >= 1.21.0
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Building the Package
+
+```bash
+python -m build
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

sh_batch_grid_builder-0.2.0/README.md

@@ -0,0 +1,159 @@
+# SH Batch Grid Builder
+
+This tool is designed to build custom tiling grids for the [Sentinel Hub Batch V2 API](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/BatchV2.html) on [CDSE](https://dataspace.copernicus.eu/). The custom grid is built around an input AOI for a given projection and ensures the Batch request produces outputs matching the pixel grid of the given projection.
+
+## Features
+
+- **Aligned Bounding Boxes**: Generate projection grid-aligned bounding boxes that snap to a specified grid resolution
+- **Pixelated Geometries**: Convert geometries to pixelated representations in order to only query data for the given AOI
+- **Automatic Splitting**: Automatically splits large geometries that exceed pixel limits
+- **Multiple CRS Support**: Works with any EPSG code, automatically handling CRS-specific grid origins
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install sh-batch-grid-builder
+```
+
+### From Source
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Command Line Interface
+
+The tool provides a command-line interface via the `sh-grid-builder` command:
+
+```bash
+sh-grid-builder <input_aoi> --resolution "(x,y)" --epsg <epsg_code> --output-type <type> -o <output_file>
+```
+
+#### Arguments
+
+- `input_aoi`: Path to input AOI file (GeoJSON, GPKG, or other formats supported by GeoPandas)
+- `--resolution`: Grid resolution as `(x,y)` tuple in CRS coordinate units:
+  - Format: `"(x,y)"` or `"x,y"` (brackets optional, e.g., `"(300,359)"` or `"300,359"`)
+  - **Important**: Always quote the resolution value to prevent shell interpretation (e.g., `--resolution "(300,359)"` or `--resolution "300,359"`)
+  - Note the resolution **must** be in the units of the selected projection (e.g. EPSG:3035: resolution in meters; EPSG:4326: resolution in degrees).
+  - X and Y resolutions can be different to support non-square pixels
+- The tool automatically detects and displays the CRS units when running
+- `--epsg`: EPSG code for the output CRS (e.g., `3035` for ETRS89 / LAEA Europe, `4326` for WGS84)
+- `--output-type`: Type of output to generate:
+  - `bounding-box`: Generate an aligned bounding box that covers the AOI
+  - `pixelated`: Generate pixelated geometry of the AOI
+- `-o, --output`: Path to output file (GPKG format required)
+
+#### Examples
+
+Generate aligned bounding boxes with same resolution for x and y:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(10,10)" --epsg 3035 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate aligned bounding boxes with different x and y resolutions:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(300,359)" --epsg 32632 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate pixelated geometry:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "10,10" --epsg 3035 --output-type pixelated -o output_pixelated.gpkg
+```
+
+Example with geographic CRS (degrees):
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(0.001,0.001)" --epsg 4326 --output-type bounding-box -o output_bbox.gpkg
+```
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from sh_batch_grid_builder import GeoData
+
+# Initialize with AOI file, EPSG code, and resolutions (x, y)
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=3035, resolution_x=10.0, resolution_y=10.0)
+
+# Or with different x and y resolutions
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=4326, resolution_x=0.002976190476204, resolution_y=0.002976190476204)
+
+# Generate aligned bounding boxes
+aligned_bboxes = geo_data.create_aligned_bounding_box(max_pixels=3500)
+
+# Generate pixelated geometry (includes all pixels that touch/intersect the AOI)
+pixelated_geom = geo_data.create_pixelated_geometry(max_pixels=3500)
+
+# Save results
+aligned_bboxes.to_file("output_bbox.gpkg", driver="GPKG")
+pixelated_geom.to_file("output_pixelated.gpkg", driver="GPKG")
+```
+
+## How It Works
+
+### Aligned Bounding Boxes
+
+The tool creates bounding boxes that are aligned to a grid based on:
+1. The specified X and Y resolutions (can be different for non-square pixels)
+2. The CRS origin (false easting/northing) for projected coordinate systems
+3. Automatic splitting when dimensions exceed 3500 pixels (fixed limit)
+
+### Pixelated Geometries
+
+The pixelated geometry generation uses a raster-based approach:
+1. Converts the input geometry to a raster mask
+2. Polygonizes the raster back to vector format
+3. Automatically splits large geometries to avoid memory issues
+
+This approach is much faster than vector-based methods for large grids. Pixelated
+output includes any pixel that touches/intersects the AOI.
+
+## Requirements
+
+- Python >= 3.8
+- geopandas >= 0.12.0
+- pyproj >= 3.4.0
+- shapely >= 2.0.0
+- rasterio >= 1.3.0
+- numpy >= 1.21.0
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Building the Package
+
+```bash
+python -m build
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

sh_batch_grid_builder-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sh-batch-grid-builder"
+version = "0.2.0"
+description = "A tool for generating projection grid aligned bounding boxes and pixelated geometries from AOI (Area of Interest) files for Sentinel Hub Batch V2 API on CDSE"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Maxim Lamare", email = "maxim.lamare@sinergise.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+keywords = ["gis", "geospatial", "grid", "pixelation", "bounding-box"]
+
+dependencies = [
+    "geopandas>=0.12.0",
+    "pyproj>=3.4.0",
+    "shapely>=2.0.0",
+    "rasterio>=1.3.0",
+    "numpy>=1.21.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+sh-grid-builder = "sh_batch_grid_builder.cli:main"
+
+[tool.setuptools]
+packages = ["sh_batch_grid_builder"]
+
+[tool.setuptools.package-data]
+"*" = ["*.txt", "*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

sh_batch_grid_builder-0.2.0/setup.cfg

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

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder/__init__.py

@@ -0,0 +1,11 @@
+"""
+SH Batch Grid Builder
+
+A tool for generating aligned bounding boxes and pixelated geometries from AOI files.
+"""
+
+from sh_batch_grid_builder.geo import GeoData
+from sh_batch_grid_builder.crs import get_crs_data, get_crs_units
+
+__version__ = "0.1.0"
+__all__ = ["GeoData", "get_crs_data", "get_crs_units"]

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder/cli.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Command-line interface for SH Batch Grid Builder.
+
+This tool generates bounding boxes or pixelated geometries from AOI files.
+"""
+import argparse
+import sys
+from pathlib import Path
+from sh_batch_grid_builder.geo import GeoData
+from sh_batch_grid_builder.crs import get_crs_units
+
+# Fixed maximum pixels setting - geometries will be automatically split if they exceed this limit
+MAX_PIXELS = 3500
+
+
+def _parse_resolution(value: str) -> tuple[float, float]:
+    cleaned = value.strip()
+    if cleaned.startswith("(") and cleaned.endswith(")"):
+        cleaned = cleaned[1:-1].strip()
+    parts = [part.strip() for part in cleaned.split(",") if part.strip()]
+    if len(parts) != 2:
+        raise ValueError(
+            "Resolution must be provided as '(x,y)' or 'x,y' with two values."
+        )
+    try:
+        resolution_x = float(parts[0])
+        resolution_y = float(parts[1])
+    except ValueError as exc:
+        raise ValueError("Resolution values must be numeric.") from exc
+    if resolution_x <= 0 or resolution_y <= 0:
+        raise ValueError(
+            f"Resolution must be positive, got ({resolution_x}, {resolution_y})"
+        )
+    return resolution_x, resolution_y
+
+
+def main():
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        description="Generate bounding boxes or pixelated geometries from AOI files",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Generate bounding box
+  sh-grid-builder input.geojson --resolution "(10,10)" --epsg 3035 --output-type bounding-box -o output.gpkg
+
+  # Generate pixelated geometry
+  sh-grid-builder input.geojson --resolution "10,10" --epsg 3035 --output-type pixelated -o output.gpkg
+        """,
+    )
+
+    parser.add_argument(
+        "input_aoi",
+        type=str,
+        help="Path to input AOI file (GeoJSON, GPKG, or other geospatial formats supported by GeoPandas)",
+    )
+
+    parser.add_argument(
+        "--resolution",
+        type=str,
+        required=True,
+        help=(
+            "Grid resolution as '(x,y)' or 'x,y' in CRS coordinate units "
+            "(e.g., '(10,10)' for 10 meters, or '0.001,0.001' for degrees)"
+        ),
+    )
+
+    parser.add_argument(
+        "--epsg",
+        type=int,
+        required=True,
+        help="EPSG code for the output CRS (e.g., 3035 for ETRS89 / LAEA Europe)",
+    )
+
+    parser.add_argument(
+        "--output-type",
+        type=str,
+        choices=["bounding-box", "pixelated"],
+        required=True,
+        help="Type of output to generate: 'bounding-box' for aligned bounding boxes, 'pixelated' for pixelated geometry",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        required=True,
+        help="Path to output file (GPKG format required)",
+    )
+
+    args = parser.parse_args()
+
+    # Validate input file exists
+    input_path = Path(args.input_aoi)
+    if not input_path.exists():
+        print(f"Error: Input file '{args.input_aoi}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    # Parse and validate resolution
+    try:
+        resolution_x, resolution_y = _parse_resolution(args.resolution)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # Check CRS units and warn user
+    try:
+        crs_units = get_crs_units(args.epsg)
+        print(f"CRS EPSG:{args.epsg} uses units: {crs_units}")
+        print(f"Resolution: ({resolution_x}, {resolution_y}) {crs_units}")
+
+        # Warn if using geographic CRS (degrees) with potentially inappropriate resolution
+        if crs_units == "degrees":
+            if resolution_x > 1.0 or resolution_y > 1.0:
+                print(
+                    f"Warning: Resolution of ({resolution_x}, {resolution_y}) degrees is very large. "
+                    f"For EPSG:{args.epsg} (geographic CRS), resolution should be in degrees. "
+                    f"Typical values are small (e.g., 0.001 degrees ≈ 111 meters).",
+                    file=sys.stderr,
+                )
+            elif resolution_x < 0.00001 or resolution_y < 0.00001:
+                print(
+                    f"Warning: Resolution of ({resolution_x}, {resolution_y}) degrees is very small. "
+                    f"This may result in extremely large pixel counts.",
+                    file=sys.stderr,
+                )
+    except Exception as e:
+        print(f"Warning: Could not determine CRS units: {e}", file=sys.stderr)
+        print("Proceeding with resolution as provided...", file=sys.stderr)
+
+    try:
+        # Initialize GeoData
+        print(f"Loading AOI from: {args.input_aoi}")
+        geo_data = GeoData(input_path, args.epsg, resolution_x, resolution_y)
+
+        # Generate output based on type
+        if args.output_type == "bounding-box":
+            print(
+                f"Generating aligned bounding box(es) with resolution ({resolution_x}, {resolution_y})..."
+            )
+            result_gdf = geo_data.create_aligned_bounding_box(max_pixels=MAX_PIXELS)
+            print(f"Created {len(result_gdf)} aligned bounding box(es)")
+        else:  # pixelated
+            print(
+                f"Generating pixelated geometry with resolution ({resolution_x}, {resolution_y})..."
+            )
+            result_gdf = geo_data.create_pixelated_geometry(max_pixels=MAX_PIXELS)
+            print(f"Created {len(result_gdf)} pixelated geometry/geometries")
+
+        # Save output
+        output_path = Path(args.output)
+        result_gdf.to_file(output_path, driver="GPKG")
+        print(f"Successfully saved {len(result_gdf)} feature(s) to {output_path}")
+
+    except Exception as e:
+        print(f"Error: {str(e)}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder/crs.py

@@ -0,0 +1,62 @@
+from typing import Tuple
+from pyproj import CRS
+
+
+def get_crs_data(target_epsg: int) -> Tuple[float, float]:
+    crs = CRS.from_epsg(target_epsg)
+
+    origin_x = 0.0
+    origin_y = 0.0
+
+    if crs.is_projected:
+        for param in crs.coordinate_operation.params:
+            if "easting" in param.name.lower() or "false easting" in param.name.lower():
+                origin_x = param.value
+            if (
+                "northing" in param.name.lower()
+                or "false northing" in param.name.lower()
+            ):
+                origin_y = param.value
+
+    return origin_x, origin_y
+
+
+def get_crs_units(target_epsg: int) -> str:
+    """
+    Get the units of the CRS.
+    
+    Args:
+        target_epsg: EPSG code
+        
+    Returns:
+        String describing the units (e.g., "degrees", "metre", "meter", "foot", etc.)
+    """
+    crs = CRS.from_epsg(target_epsg)
+    
+    if crs.is_geographic:
+        return "degrees"
+    elif crs.is_projected:
+        # Get units from axis info
+        if crs.axis_info:
+            unit_name = crs.axis_info[0].unit_name.lower()
+            # Normalize common variations
+            if unit_name in ["metre", "meter", "m"]:
+                return "meters"
+            elif unit_name in ["degree", "degrees", "deg"]:
+                return "degrees"
+            elif unit_name in ["foot", "feet", "ft"]:
+                return "feet"
+            else:
+                return unit_name
+        else:
+            # Default for projected CRS is usually meters
+            return "meters"
+    else:
+        # Fallback - try to get from CRS string
+        crs_str = str(crs).lower()
+        if "degree" in crs_str:
+            return "degrees"
+        elif "metre" in crs_str or "meter" in crs_str:
+            return "meters"
+        else:
+            return "unknown"

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder/geo.py

@@ -0,0 +1,278 @@
+from pathlib import Path
+from typing import Union
+import math
+import geopandas as gpd
+from shapely.geometry import box, shape
+from shapely.ops import unary_union
+from sh_batch_grid_builder.crs import get_crs_data
+from pyproj import CRS
+from rasterio import features
+from rasterio.transform import from_origin
+
+
+class GeoData:
+    """
+    A class for working with geodata and creating aligned bounding boxes to the projection grid.
+
+    Args:
+        filepath: Path to the input geodata file
+        epsg_code: EPSG code of the input geodata
+        resolution_x: Resolution of the input geodata in x direction
+        resolution_y: Resolution of the input geodata in y direction
+    """
+
+    def __init__(
+        self,
+        filepath: Union[str, Path],
+        epsg_code: int,
+        resolution_x: float,
+        resolution_y: float,
+    ):
+        self.gdf = self.read_geodata(filepath)
+        self.crs = epsg_code
+        self.bounds = self.gdf.total_bounds
+
+        self.resolution_x = resolution_x
+        self.resolution_y = resolution_y
+        self._validate_resolutions()
+
+        self._validate_epsg(epsg_code)
+        self.epsg_code = epsg_code
+
+    def _validate_resolutions(self):
+        if self.resolution_x <= 0:
+            raise ValueError(f"Resolution X must be positive, got {self.resolution_x}")
+        if self.resolution_y <= 0:
+            raise ValueError(f"Resolution Y must be positive, got {self.resolution_y}")
+
+    def _validate_epsg(self, epsg_code: int):
+        if self.gdf.crs.to_epsg() is None:
+            raise ValueError(
+                f"Could not determine EPSG code from input file CRS. "
+                f"Expected EPSG:{epsg_code}. Please ensure the file has a valid EPSG CRS."
+            )
+
+        if self.gdf.crs.to_epsg() != epsg_code:
+            raise ValueError(
+                f"Input file CRS (EPSG:{self.gdf.crs.to_epsg()}) does not match target EPSG ({epsg_code}). "
+                f"Please reproject the input file to EPSG:{epsg_code} before processing, "
+                f"or use EPSG:{self.gdf.crs.to_epsg()} as the target EPSG."
+            )
+
+    def _align_axis(
+        self, minv: float, maxv: float, origin: float, res: float
+    ) -> tuple[float, float]:
+        # snap to grid defined by origin + k*res
+        aligned_min = origin + math.floor((minv - origin) / res) * res
+        aligned_max = origin + math.ceil((maxv - origin) / res) * res
+
+        # ensure width/height is multiple of res (guards floating error)
+        size = aligned_max - aligned_min
+        steps = math.ceil(size / res)
+        aligned_max = aligned_min + steps * res
+
+        return aligned_min, aligned_max
+
+    def _split_pixel_counts(self, total: int, parts: int) -> list[int]:
+        base = total // parts
+        remainder = total % parts
+        return [base + 1 if i < remainder else base for i in range(parts)]
+
+    def _grid_origin(self) -> tuple[float, float]:
+        origin_x, origin_y = get_crs_data(self.crs)
+        if not CRS.from_epsg(self.crs).is_projected:
+            origin_x -= self.resolution_x / 2
+            origin_y -= self.resolution_y / 2
+        return origin_x, origin_y
+
+    def read_geodata(self, filepath: Union[str, Path]):
+        gdf = gpd.read_file(filepath)
+        return gdf
+
+    def create_aligned_bounding_box(self, max_pixels: int = 3500) -> gpd.GeoDataFrame:
+        """
+        Create an aligned bounding box to the projection grid that covers the input geometry.
+
+        Args:
+            max_pixels: Maximum allowed pixels in either dimension (default: 3500)
+
+        Returns:
+            GeoDataFrame with one or more bounding boxes (split if exceeds max_pixels)
+        """
+        # Get the grid origin from the CRS
+        origin_x, origin_y = self._grid_origin()
+
+        # Get the grid bounds of the input geometry
+        minx, miny, maxx, maxy = self.bounds
+
+        aligned_minx, aligned_maxx = self._align_axis(
+            minx, maxx, origin_x, self.resolution_x
+        )
+        aligned_miny, aligned_maxy = self._align_axis(
+            miny, maxy, origin_y, self.resolution_y
+        )
+
+        # Calculate width and height in pixels of the aligned bounding box
+        width_px = int(round((aligned_maxx - aligned_minx) / self.resolution_x))
+        height_px = int(round((aligned_maxy - aligned_miny) / self.resolution_y))
+
+        tiles_x = max(1, math.ceil(width_px / max_pixels))
+        tiles_y = max(1, math.ceil(height_px / max_pixels))
+
+        widths = self._split_pixel_counts(width_px, tiles_x)
+        heights = self._split_pixel_counts(height_px, tiles_y)
+
+        geometries = []
+        y_min = aligned_miny
+        for row_idx, tile_h in enumerate(heights, start=1):
+            y_max = y_min + tile_h * self.resolution_y
+            x_min = aligned_minx
+            for col_idx, tile_w in enumerate(widths, start=1):
+                x_max = x_min + tile_w * self.resolution_x
+                geometries.append(
+                    {
+                        "geometry": box(x_min, y_min, x_max, y_max),
+                        "width": tile_w,
+                        "height": tile_h,
+                        "row_idx": row_idx,
+                        "col_idx": col_idx,
+                    }
+                )
+                x_min = x_max
+            y_min = y_max
+
+        if not geometries:
+            return gpd.GeoDataFrame(
+                [], columns=["id", "identifier", "width", "height", "geometry"], crs=CRS.from_epsg(self.crs)
+            )
+
+        aoi_union = unary_union(self.gdf.geometry)
+        filtered_tiles = [
+            tile for tile in geometries if tile["geometry"].intersects(aoi_union)
+        ]
+
+        if not filtered_tiles:
+            return gpd.GeoDataFrame(
+                [], columns=["id", "identifier", "width", "height", "geometry"], crs=CRS.from_epsg(self.crs)
+            )
+
+        # Renumber tiles without gaps in row/col identifiers
+        filtered_tiles.sort(key=lambda tile: (tile["row_idx"], tile["col_idx"]))
+        renumbered_tiles = []
+        current_row = None
+        row_counter = 0
+        col_counter = 0
+        for tile in filtered_tiles:
+            if tile["row_idx"] != current_row:
+                row_counter += 1
+                current_row = tile["row_idx"]
+                col_counter = 0
+            col_counter += 1
+            renumbered_tiles.append(
+                {
+                    "geometry": tile["geometry"],
+                    "width": tile["width"],
+                    "height": tile["height"],
+                    "identifier": f"tile_{col_counter}_{row_counter}",
+                }
+            )
+
+        # Create GeoDataFrame and renumber sequentially
+        bbox_gdf = gpd.GeoDataFrame(renumbered_tiles, crs=CRS.from_epsg(self.crs))
+        bbox_gdf["id"] = range(1, len(bbox_gdf) + 1)
+
+        # Reorder columns to match expected format
+        bbox_gdf = bbox_gdf[["id", "identifier", "width", "height", "geometry"]]
+
+        return bbox_gdf
+
+    def create_pixelated_geometry(self, max_pixels: int = 3500) -> gpd.GeoDataFrame:
+        """
+        Rasterize AOI to aligned grid, then dissolve connected pixels into polygons.
+
+        Args:
+            max_pixels: Maximum allowed pixels in either dimension (default: 3500)
+
+        Returns:
+            GeoDataFrame of dissolved pixel groups.
+        """
+        # Get the grid origin from the CRS
+        origin_x, origin_y = self._grid_origin()
+
+        # Get the grid bounds of the input geometry
+        minx, miny, maxx, maxy = self.bounds
+
+        aligned_minx, aligned_maxx = self._align_axis(
+            minx, maxx, origin_x, self.resolution_x
+        )
+        aligned_miny, aligned_maxy = self._align_axis(
+            miny, maxy, origin_y, self.resolution_y
+        )
+
+        # Calculate width and height in pixels of the aligned bounding box
+        width_px = int(round((aligned_maxx - aligned_minx) / self.resolution_x))
+        height_px = int(round((aligned_maxy - aligned_miny) / self.resolution_y))
+
+        if width_px <= 0 or height_px <= 0:
+            return gpd.GeoDataFrame([], crs=self.gdf.crs)
+
+        transform = from_origin(
+            aligned_minx, aligned_maxy, self.resolution_x, self.resolution_y
+        )
+
+        shapes = ((geom, 1) for geom in self.gdf.geometry)
+        mask = features.rasterize(
+            shapes=shapes,
+            out_shape=(height_px, width_px),
+            transform=transform,
+            fill=0,
+            all_touched=True,
+            dtype="uint8",
+        )
+
+        tiles_x = max(1, math.ceil(width_px / max_pixels))
+        tiles_y = max(1, math.ceil(height_px / max_pixels))
+
+        widths = self._split_pixel_counts(width_px, tiles_x)
+        heights = self._split_pixel_counts(height_px, tiles_y)
+
+        split_polygons = []
+        y_offset = 0
+        for row_idx, tile_h in enumerate(heights, start=1):
+            x_offset = 0
+            for col_idx, tile_w in enumerate(widths, start=1):
+                window = mask[
+                    y_offset : y_offset + tile_h,
+                    x_offset : x_offset + tile_w,
+                ]
+                if window.any():
+                    tile_identifier = f"tile_{col_idx}_{row_idx}"
+                    window_transform = from_origin(
+                        aligned_minx + x_offset * self.resolution_x,
+                        aligned_maxy - y_offset * self.resolution_y,
+                        self.resolution_x,
+                        self.resolution_y,
+                    )
+                    feature_idx = 0
+                    for geom, value in features.shapes(
+                        window, mask=window > 0, transform=window_transform
+                    ):
+                        feature_idx += 1
+                        split_polygons.append(
+                            {
+                                "geometry": shape(geom),
+                                "width": tile_w,
+                                "height": tile_h,
+                                "identifier": f"{tile_identifier}_{feature_idx}",
+                            }
+                        )
+                x_offset += tile_w
+            y_offset += tile_h
+
+        if not split_polygons:
+            return gpd.GeoDataFrame([], crs=self.gdf.crs)
+
+        pixel_gdf = gpd.GeoDataFrame(split_polygons, crs=self.gdf.crs)
+        pixel_gdf["id"] = range(1, len(pixel_gdf) + 1)
+        pixel_gdf = pixel_gdf[["id", "identifier", "width", "height", "geometry"]]
+        return pixel_gdf

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: sh-batch-grid-builder
+Version: 0.2.0
+Summary: A tool for generating projection grid aligned bounding boxes and pixelated geometries from AOI (Area of Interest) files for Sentinel Hub Batch V2 API on CDSE
+Author-email: Maxim Lamare <maxim.lamare@sinergise.com>
+License: MIT
+Keywords: gis,geospatial,grid,pixelation,bounding-box
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: geopandas>=0.12.0
+Requires-Dist: pyproj>=3.4.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: rasterio>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# SH Batch Grid Builder
+
+This tool is designed to build custom tiling grids for the [Sentinel Hub Batch V2 API](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/BatchV2.html) on [CDSE](https://dataspace.copernicus.eu/). The custom grid is built around an input AOI for a given projection and ensures the Batch request produces outputs matching the pixel grid of the given projection.
+
+## Features
+
+- **Aligned Bounding Boxes**: Generate projection grid-aligned bounding boxes that snap to a specified grid resolution
+- **Pixelated Geometries**: Convert geometries to pixelated representations in order to only query data for the given AOI
+- **Automatic Splitting**: Automatically splits large geometries that exceed pixel limits
+- **Multiple CRS Support**: Works with any EPSG code, automatically handling CRS-specific grid origins
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install sh-batch-grid-builder
+```
+
+### From Source
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/maximlamare/SH-Batch-Grid-Builder.git
+cd SH-Batch-Grid-Builder
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Command Line Interface
+
+The tool provides a command-line interface via the `sh-grid-builder` command:
+
+```bash
+sh-grid-builder <input_aoi> --resolution "(x,y)" --epsg <epsg_code> --output-type <type> -o <output_file>
+```
+
+#### Arguments
+
+- `input_aoi`: Path to input AOI file (GeoJSON, GPKG, or other formats supported by GeoPandas)
+- `--resolution`: Grid resolution as `(x,y)` tuple in CRS coordinate units:
+  - Format: `"(x,y)"` or `"x,y"` (brackets optional, e.g., `"(300,359)"` or `"300,359"`)
+  - **Important**: Always quote the resolution value to prevent shell interpretation (e.g., `--resolution "(300,359)"` or `--resolution "300,359"`)
+  - Note the resolution **must** be in the units of the selected projection (e.g. EPSG:3035: resolution in meters; EPSG:4326: resolution in degrees).
+  - X and Y resolutions can be different to support non-square pixels
+- The tool automatically detects and displays the CRS units when running
+- `--epsg`: EPSG code for the output CRS (e.g., `3035` for ETRS89 / LAEA Europe, `4326` for WGS84)
+- `--output-type`: Type of output to generate:
+  - `bounding-box`: Generate an aligned bounding box that covers the AOI
+  - `pixelated`: Generate pixelated geometry of the AOI
+- `-o, --output`: Path to output file (GPKG format required)
+
+#### Examples
+
+Generate aligned bounding boxes with same resolution for x and y:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(10,10)" --epsg 3035 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate aligned bounding boxes with different x and y resolutions:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(300,359)" --epsg 32632 --output-type bounding-box -o output_bbox.gpkg
+```
+
+Generate pixelated geometry:
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "10,10" --epsg 3035 --output-type pixelated -o output_pixelated.gpkg
+```
+
+Example with geographic CRS (degrees):
+
+```bash
+sh-grid-builder data/aoi.geojson --resolution "(0.001,0.001)" --epsg 4326 --output-type bounding-box -o output_bbox.gpkg
+```
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from sh_batch_grid_builder import GeoData
+
+# Initialize with AOI file, EPSG code, and resolutions (x, y)
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=3035, resolution_x=10.0, resolution_y=10.0)
+
+# Or with different x and y resolutions
+geo_data = GeoData("path/to/aoi.geojson", epsg_code=4326, resolution_x=0.002976190476204, resolution_y=0.002976190476204)
+
+# Generate aligned bounding boxes
+aligned_bboxes = geo_data.create_aligned_bounding_box(max_pixels=3500)
+
+# Generate pixelated geometry (includes all pixels that touch/intersect the AOI)
+pixelated_geom = geo_data.create_pixelated_geometry(max_pixels=3500)
+
+# Save results
+aligned_bboxes.to_file("output_bbox.gpkg", driver="GPKG")
+pixelated_geom.to_file("output_pixelated.gpkg", driver="GPKG")
+```
+
+## How It Works
+
+### Aligned Bounding Boxes
+
+The tool creates bounding boxes that are aligned to a grid based on:
+1. The specified X and Y resolutions (can be different for non-square pixels)
+2. The CRS origin (false easting/northing) for projected coordinate systems
+3. Automatic splitting when dimensions exceed 3500 pixels (fixed limit)
+
+### Pixelated Geometries
+
+The pixelated geometry generation uses a raster-based approach:
+1. Converts the input geometry to a raster mask
+2. Polygonizes the raster back to vector format
+3. Automatically splits large geometries to avoid memory issues
+
+This approach is much faster than vector-based methods for large grids. Pixelated
+output includes any pixel that touches/intersects the AOI.
+
+## Requirements
+
+- Python >= 3.8
+- geopandas >= 0.12.0
+- pyproj >= 3.4.0
+- shapely >= 2.0.0
+- rasterio >= 1.3.0
+- numpy >= 1.21.0
+
+## Development
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Building the Package
+
+```bash
+python -m build
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+sh_batch_grid_builder/__init__.py
+sh_batch_grid_builder/cli.py
+sh_batch_grid_builder/crs.py
+sh_batch_grid_builder/geo.py
+sh_batch_grid_builder.egg-info/PKG-INFO
+sh_batch_grid_builder.egg-info/SOURCES.txt
+sh_batch_grid_builder.egg-info/dependency_links.txt
+sh_batch_grid_builder.egg-info/entry_points.txt
+sh_batch_grid_builder.egg-info/requires.txt
+sh_batch_grid_builder.egg-info/top_level.txt
+tests/test_crs.py

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sh-grid-builder = sh_batch_grid_builder.cli:main

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/requires.txt

@@ -0,0 +1,9 @@
+geopandas>=0.12.0
+pyproj>=3.4.0
+shapely>=2.0.0
+rasterio>=1.3.0
+numpy>=1.21.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0

sh_batch_grid_builder-0.2.0/sh_batch_grid_builder.egg-info/top_level.txt

@@ -0,0 +1 @@
+sh_batch_grid_builder

sh_batch_grid_builder-0.2.0/tests/test_crs.py

@@ -0,0 +1,31 @@
+import pytest
+from sh_batch_grid_builder.crs import get_crs_data
+
+
+class TestGetCrsData:
+    """Test the get_crs_data function with known EPSG codes and their expected origins."""
+
+    def test_epsg_4326(self):
+        origin_x, origin_y = get_crs_data(4326)
+        assert origin_x == 0.0
+        assert origin_y == 0.0
+
+    def test_epsg_3857(self):
+        origin_x, origin_y = get_crs_data(3857)
+        assert origin_x == 0.0
+        assert origin_y == 0.0
+
+    def test_epsg_3035(self):
+        origin_x, origin_y = get_crs_data(3035)
+        assert origin_x == 4321000
+        assert origin_y == 3210000
+
+    def test_epsg_32633(self):
+        origin_x, origin_y = get_crs_data(32633)
+        assert origin_x == 500000
+        assert origin_y == 0
+
+    def test_epsg_2154(self):
+        origin_x, origin_y = get_crs_data(2154)
+        assert origin_x == 700000
+        assert origin_y == 6600000