Metadata-Version: 2.4
Name: GeoPatch
Version: 1.2.7
Summary: GeoPatch is a package for generating patches from remote sensing data
Home-page: https://github.com/Hejarshahabi
Author: Hejar Shahabi
Author-email: hejarshahabi@gmail.com
License: MIT
Keywords: Machine Learning,Remote Sensing,Deep Learning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Requires-Dist: terratiff
Requires-Dist: tqdm
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# GeoPatch

[![PyPI version](https://img.shields.io/pypi/v/GeoPatch.svg?color=green)](https://pypi.org/project/GeoPatch/) [![Downloads](https://pepy.tech/badge/geopatch)](https://pepy.tech/project/geopatch) [![Github](https://img.shields.io/badge/Github-GeoPatch-blueviolet)](https://github.com/Hejarshahabi/GeoPatch) [![LinkedIn](https://img.shields.io/badge/LinkedIn-Hejar%20Shahabi-blue)](https://www.linkedin.com/in/hejarshahabi/) [![Twitter URL](https://img.shields.io/twitter/url?color=blue&label=Hejar%20Shahabi&style=social&url=https%3A%2F%2Ftwitter.com%2Fhejarshahabi)](https://twitter.com/hejarshahabi)

![GeoPatch Logo](https://raw.githubusercontent.com/Hejarshahabi/GeoPatch/main/Patch_logo.jpg)
**GeoPatch** is a high-performance Python package designed for generating patches from remote sensing satellite imagery. It simplifies the preprocessing pipeline for deep learning tasks by automatically handling large rasters, clipping them into patches, and exporting them alongside corresponding labels for **Semantic Segmentation** and **Object Detection (YOLO format)**.

GeoPatch is built on top of **[TerraTiff](https://github.com/Hejarshahabi/TerraTiff)** for lightweight, lightning-fast raster operations without the heavy GDAL dependencies.
---

## 🛠️ Installation

You can install GeoPatch directly from PyPI:

```bash
pip install GeoPatch
```

---

## 🚀 Tutorial & Usage

GeoPatch makes generating datasets for your computer vision models incredibly simple. It provides two main classes: `TrainPatch` (for generating training datasets) and `PredictionPatch` (for generating inference patches).

### 1. Generating Training Patches (`TrainPatch`)

You can generate datasets for either semantic segmentation or object detection. 

```python
from GeoPatch import TrainPatch

# Define your image and label paths
img_path = "path/to/your/satellite_image.tif"
lbl_path = "path/to/your/label_raster.tif"

# Initialize the patch generator
# patch_size: size of the square patches (e.g., 256x256)
# stride: sliding window step (overlap occurs if stride < patch_size)
patch_generator = TrainPatch(
    image=img_path, 
    label=lbl_path, 
    patch_size=256, 
    stride=128, 
    channel_first=True
)
```

#### Using Polygon Vector Data (Shapefiles / GeoJSON) as Labels
`GeoPatch` requires labels to be in a raster format (`.tif` or `.npy`). If your ground-truth labels are vector polygons (e.g., a `.shp` or `.geojson` file), you must rasterize them into a GeoTIFF mask before passing them to `GeoPatch`. 

Here is how you can easily convert your polygons to a raster mask using `geopandas` and `rasterio`:

```python
import geopandas as gpd
import rasterio
from rasterio.features import rasterize

# 1. Load the reference satellite image and the polygon shapefile
with rasterio.open("path/to/your/satellite_image.tif") as src:
    meta = src.meta.copy()
    transform = src.transform
    shape = (src.height, src.width)

gdf = gpd.read_file("path/to/your/polygons.shp")

# 2. Extract geometries and values (e.g., class IDs from a column like 'class_id')
# If you don't have a class column, you can use a default value (e.g., 1)
shapes = ((geom, value) for geom, value in zip(gdf.geometry, gdf['class_id']))

# 3. Rasterize the polygons into a mask array
mask = rasterize(
    shapes=shapes,
    out_shape=shape,
    transform=transform,
    fill=0,          # Background value
    all_touched=True,
    dtype=rasterio.uint8
)

# 4. Save the rasterized mask as a GeoTIFF
meta.update(count=1, dtype=rasterio.uint8)
with rasterio.open("path/to/your/label_raster.tif", 'w', **meta) as dst:
    dst.write(mask, 1)

# Now you can pass "path/to/your/label_raster.tif" to TrainPatch!
```

#### Semantic Segmentation Datasets
To generate image patches and their corresponding label masks:

```python
# Generates semantic segmentation patches and saves them as GeoTIFFs
patch_generator.generate_segmentation(
    format="tif",                # Output format: "tif" or "npy"
    folder_name="seg_dataset",   # Output directory
    only_label=False             # Set to True to skip empty background patches
)
```

#### Object Detection Datasets (YOLO Format)
GeoPatch automatically converts your raster labels into YOLO-format bounding boxes `.txt` files.

```python
# Generates image patches and YOLO bounding box text files
patch_generator.generate_detection(
    format="npy",                # Output format: "tif" or "npy"
    folder_name="det_dataset",   # Output directory
    only_label=True,             # Skips patches with no objects
    segmentation=True            # Set to True to also save segmentation masks alongside bboxes
)
```

### 2. Generating Inference Patches (`PredictionPatch`)

When you are ready to predict on a new satellite image, you can use `PredictionPatch` to slice the image into manageable pieces while preserving the geospatial metadata (GeoTransform, CRS) for seamless reconstruction later.

```python
from GeoPatch import PredictionPatch

img_path = "path/to/new_area.tif"

# Initialize prediction patcher
pred_patch = PredictionPatch(
    image=img_path, 
    patch_size=512, 
    stride=512, 
    channel_first=True
)

# Export all patches as GeoTIFFs ready for model inference
pred_patch.save_Geotif(folder_name="inference_patches")
```

---

## 💡 Contact & Contributions

Any feedback from users is welcome! You can write to me at [hejarshahabi@gmail.com](mailto:hejarshahabi@gmail.com) in case of any contribution, bug reports, or suggestions.
