sh-batch-grid-builder 0.1.0

A tool for generating aligned bounding boxes and pixelated geometries from AOI (Area of Interest) files

SH Batch Grid Builder

A Python tool for generating aligned bounding boxes and pixelated geometries from Area of Interest (AOI) files. This tool is particularly useful for creating grid-aligned geometries that can be used for batch processing workflows.

Features

• Aligned Bounding Boxes: Generate grid-aligned bounding boxes that snap to a specified grid resolution
• Pixelated Geometries: Convert geometries to pixelated (rasterized) representations
• 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 (when published)

pip install sh-batch-grid-builder

From Source

git clone <repository-url>
cd SH-Batch-Grid-Builder
pip install .

Development Installation

git clone <repository-url>
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:

sh-grid-builder <input_aoi> --resolution <resolution> --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 in coordinate units (e.g., 10 for 10 meters)
• --epsg: EPSG code for the output CRS (e.g., 3035 for ETRS89 / LAEA Europe)
• --output-type: Type of output to generate:
  • bounding-box: Generate aligned bounding boxes
  • pixelated: Generate pixelated geometry
• -o, --output: Path to output file (GPKG format required)

Examples

Generate aligned bounding boxes:

sh-grid-builder data/aoi.geojson --resolution 10 --epsg 3035 --output-type bounding-box -o output_bbox.gpkg

Generate pixelated geometry:

sh-grid-builder data/aoi.geojson --resolution 10 --epsg 3035 --output-type pixelated -o output_pixelated.gpkg

Python API

You can also use the package programmatically:

from sh_batch_grid_builder import GeoData

# Initialize with AOI file, EPSG code, and resolution
geo_data = GeoData("path/to/aoi.geojson", epsg_code=3035, resolution=10.0)

# Generate aligned bounding boxes
aligned_bboxes = geo_data.create_aligned_bounding_box(max_pixels=3500)

# Generate pixelated geometry
pixelated_geom = geo_data.create_pixelated_geometry_split(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 resolution
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.

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

pytest

Building the Package

python -m build

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.