Metadata-Version: 2.4
Name: sh-batch-grid-builder
Version: 0.1.0
Summary: A tool for generating aligned bounding boxes and pixelated geometries from AOI (Area of Interest) files
Author-email: Your Name <your.email@example.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

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)

```bash
pip install sh-batch-grid-builder
```

### From Source

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

### Development Installation

```bash
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:

```bash
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:

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

Generate pixelated geometry:

```bash
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:

```python
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

```bash
pytest
```

### Building the Package

```bash
python -m build
```

## License

MIT License

## Contributing

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