# GeoPatch
## *GeoPatch* is a package for generating patches from remote sensing data [](https://pypi.org/project/GeoPatch/) [](https://pepy.tech/project/geopatch) [](https://github.com/Hejarshahabi/GeoPatch) [](https://www.linkedin.com/in/hejarshahabi/) [](https://twitter.com/hejarshahabi)
*GeoPatch* enables users to read, process, and export GeoTIFF patches for training deep learning models. Built on the Rasterio library, it simplifies reading and exporting GeoTIFF patches for semantic segmentation and object detection. The package supports generating patches from raster labels or polygon shapefiles, producing outputs in GeoTIFF or NumPy formats with optional YOLO-format bounding box annotations.
Users can feed satellite imagery and corresponding label data (raster or shapefile) to export patches, with support for data augmentation (vertical flip, horizontal flip, and 90/180/270-degree rotations) for NumPy output. The package ensures complete image coverage, including edge pixels, and supports visualization of patches with optional bounding box overlays.
Any feedback is welcome! Contact me at hejarshahabi@gmail.com for contributions or suggestions.
<img src="https://github.com/Hejarshahabi/GeoPatch/blob/main/Patch_logo.jpg?raw=true" width="880" height="325">
## Quick Tutorial on How to Use GeoPatch
### 1. Installation
```bash
pip install GeoPatch
```
This automatically installs dependencies, including `GDAL`, `numpy`, `rasterio`, `geopandas`, `shapely`, `tqdm`, `matplotlib`, and `scikit-image` for handling GeoTIFF files, shapefiles, and image processing.
### 2. Calling the Package
```bash
from GeoPatch import TrainPatch, PredictionPatch
```
### 3. Feeding Data
For the `image` variable, you can pass either a string (file path to `.tif` or `.npy`) or a NumPy array. For the `label` variable, you can pass a string (file path to `.tif`, `.npy`, or `.shp` for shapefiles) or a NumPy array. The package automatically processes and reads the dataset.
```bash
# For segmentation or detection with raster labels
patch = TrainPatch(image="xxx/image.tif", label="xxx/label.tif", patch_size=128, stride=64, channel_first=True, shapefile_path=None, label_field=None)
# For segmentation or detection with shapefile labels
patch = TrainPatch(image="xxx/image.tif", label=None, patch_size=128, stride=64, channel_first=True, shapefile_path="xxx/labels.shp", label_field="class_id")
```
### 4. Input Data Specifications
Display the shape and size of the input data:
```bash
patch.data_dimension()
```
### 5. Patch Details
Show the number of original image patches generated based on the given patch size and stride:
```bash
patch.patch_info()
```
### 6. Saving Image Patches as GeoTIFF Files (Segmentation)
Save image and label patches as GeoTIFF files in the specified `folder_name` under the current working directory. If `only_label=True`, only patches with non-zero labels are saved.
```bash
patch.generate_segmentation(format="tif", folder_name="seg_tif", only_label=True)
```
### 7. Saving Image Patches as NumPy Arrays (Segmentation)
Generate image and label patches in NumPy format with optional data augmentation (vertical flip, horizontal flip, 90/180/270-degree rotations). Augmentations are applied only for `format="npy"`.
```bash
patch.generate_segmentation(
format="npy",
folder_name="seg_npy",
only_label=False,
return_stacked=False,
save_stack=False,
V_flip=True,
H_flip=True,
Rotation=True
)
# To return stacked NumPy patches:
patch_stacked, label_stacked = patch.generate_segmentation(
format="npy",
folder_name="seg_npy",
only_label=False,
return_stacked=True,
save_stack=False,
V_flip=True,
H_flip=True,
Rotation=True
)
```
### 8. Saving Patches for Object Detection (YOLO Format)
Generate patches for object detection, producing image patches, optional segmentation masks, and YOLO-format bounding box annotations (`.txt` files). Augmentations are applied only for `format="npy"`.
```bash
patch.generate_detection(
format="npy",
folder_name="det_npy",
only_label=True,
return_stacked=False,
save_stack=False,
V_flip=True,
H_flip=True,
Rotation=True,
segmentation=True
)
```
### 9. Saving Patches from Shapefiles (Segmentation and/or Object Detection)
Generate patches for segmentation and/or object detection using a polygon shapefile. The shapefile is reprojected to WGS84 (EPSG:4326) before clipping and rasterization to ensure alignment with the image. Specify the `label_field` containing integer class IDs (e.g., `class_id`) during `TrainPatch` initialization. Outputs include image patches, optional segmentation masks, and YOLO-format bounding box annotations. Augmentations are applied only for `format="npy"`.
```bash
patch = TrainPatch(
image="xxx/image.tif",
label=None,
patch_size=128,
stride=64,
channel_first=True,
shapefile_path="xxx/labels.shp",
label_field="class_id"
)
# For segmentation
patch.generate_segmentation(
format="npy",
folder_name="shp_npy",
only_label=True,
return_stacked=True,
save_stack=True,
V_flip=True,
H_flip=True,
Rotation=True
)
# For detection
patch.generate_detection(
format="npy",
folder_name="shp_npy",
only_label=True,
return_stacked=True,
save_stack=True,
V_flip=True,
H_flip=True,
Rotation=True,
segmentation=True
)
```
### 10. Patch Visualization
Display patches with their corresponding labels or bounding boxes. Specify the exact `folder_name` where patches are saved. Use `show_bboxes=True` to overlay YOLO bounding boxes.
```bash
patch.visualize(
folder_name="shp_npy",
patches_to_show=2,
band_num=1,
fig_size=(10, 20),
dpi=96,
show_bboxes=True
)
```
### 11. Generating Prediction Patches
Generate patches for prediction using the `PredictionPatch` class:
```bash
prediction = PredictionPatch(image="xxx/test_image.tif", patch_size=128, stride=128, channel_first=True)
```
### 12. Saving Prediction Patches
Save prediction patches as GeoTIFF or NumPy arrays. Edge pixels are included to ensure complete image coverage.
```bash
# Save as GeoTIFF
prediction.save_Geotif(folder_name="pred_tif")
# Save as NumPy arrays
prediction.save_numpy(folder_name="pred_npy")
```
## Change Log
### 1.0 (04/07/2022)
- First Release
### 1.1 (03/08/2022)
- Fixed issues with loading NumPy arrays
- Fixed random visualization of samples
### 1.1.1 (15/12/2022)
- Fixed visualization issues in Linux environments
- Added `PredictionPatch` class for generating prediction patches
### 1.1.1 (22/11/2023)
- Fixed edge pixel issue in prediction patch generation to ensure entire image is patched
- Added GDAL to automatically installed packages
### 1.2 (27/07/2025)
- Added `generate_detection` method to `TrainPatch` for object detection with YOLO-format bounding box annotations
- Modified `generate_segmentation` and `generate_detection` to apply augmentations (V_flip, H_flip, Rotation) only for `format="npy"`, not for `format="tif"`, to prevent shape mismatch errors
### 1.3 (28/07/2025)
- Added support for generating patches from polygon shapefiles in `TrainPatch`, enabling segmentation and/or object detection
- Updated shapefile processing to reproject to WGS84 (EPSG:4326) before clipping and rasterization to prevent label mismatches due to CRS issues
- Removed redundant `shapefile_path` parameter in `generate_from_shapefile`, using `label` and `label_field` from `TrainPatch` initialization
- Added dependencies (`geopandas`, `shapely`, `scikit-image`) to support shapefile processing and bounding box generation
### 1.3.1 (28/07/2025)
- minor bugs resolved
### 1.3.2 (28/07/2025)
- Removed verbose print statements in `preprocess_and_rasterize` function to streamline output and improve user experience
- Updated `TrainPatch` initialization to explicitly handle `shapefile_path` and `label_field` parameters for clarity
- Improved documentation to reflect updated `TrainPatch` usage with shapefile inputs
Raw data
{
"_id": null,
"home_page": "https://github.com/Hejarshahabi/GeoPatch",
"name": "GeoPatch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Machine Learning, Remote Sensing, Deep Learning, Object Detection, YOLO, Shapefile, GeoTIFF",
"author": "Hejar Shahabi",
"author_email": "hejarshahabi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/43/7e/094756675248c1ec61defe0f25517323e3680eb82ccc231f2d87c617f9f9/geopatch-1.3.2.tar.gz",
"platform": null,
"description": "# GeoPatch\r\n\r\n## *GeoPatch* is a package for generating patches from remote sensing data [](https://pypi.org/project/GeoPatch/) [](https://pepy.tech/project/geopatch) [](https://github.com/Hejarshahabi/GeoPatch) [](https://www.linkedin.com/in/hejarshahabi/) [](https://twitter.com/hejarshahabi)\r\n\r\n*GeoPatch* enables users to read, process, and export GeoTIFF patches for training deep learning models. Built on the Rasterio library, it simplifies reading and exporting GeoTIFF patches for semantic segmentation and object detection. The package supports generating patches from raster labels or polygon shapefiles, producing outputs in GeoTIFF or NumPy formats with optional YOLO-format bounding box annotations.\r\n\r\nUsers can feed satellite imagery and corresponding label data (raster or shapefile) to export patches, with support for data augmentation (vertical flip, horizontal flip, and 90/180/270-degree rotations) for NumPy output. The package ensures complete image coverage, including edge pixels, and supports visualization of patches with optional bounding box overlays.\r\n\r\nAny feedback is welcome! Contact me at hejarshahabi@gmail.com for contributions or suggestions.\r\n\r\n<img src=\"https://github.com/Hejarshahabi/GeoPatch/blob/main/Patch_logo.jpg?raw=true\" width=\"880\" height=\"325\">\r\n\r\n## Quick Tutorial on How to Use GeoPatch\r\n\r\n### 1. Installation\r\n\r\n```bash\r\npip install GeoPatch\r\n```\r\n\r\nThis automatically installs dependencies, including `GDAL`, `numpy`, `rasterio`, `geopandas`, `shapely`, `tqdm`, `matplotlib`, and `scikit-image` for handling GeoTIFF files, shapefiles, and image processing.\r\n\r\n### 2. Calling the Package\r\n\r\n```bash\r\nfrom GeoPatch import TrainPatch, PredictionPatch\r\n```\r\n\r\n### 3. Feeding Data\r\n\r\nFor the `image` variable, you can pass either a string (file path to `.tif` or `.npy`) or a NumPy array. For the `label` variable, you can pass a string (file path to `.tif`, `.npy`, or `.shp` for shapefiles) or a NumPy array. The package automatically processes and reads the dataset.\r\n\r\n```bash\r\n# For segmentation or detection with raster labels\r\npatch = TrainPatch(image=\"xxx/image.tif\", label=\"xxx/label.tif\", patch_size=128, stride=64, channel_first=True, shapefile_path=None, label_field=None)\r\n\r\n# For segmentation or detection with shapefile labels\r\npatch = TrainPatch(image=\"xxx/image.tif\", label=None, patch_size=128, stride=64, channel_first=True, shapefile_path=\"xxx/labels.shp\", label_field=\"class_id\")\r\n```\r\n\r\n### 4. Input Data Specifications\r\n\r\nDisplay the shape and size of the input data:\r\n\r\n```bash\r\npatch.data_dimension()\r\n```\r\n\r\n### 5. Patch Details\r\n\r\nShow the number of original image patches generated based on the given patch size and stride:\r\n\r\n```bash\r\npatch.patch_info()\r\n```\r\n\r\n### 6. Saving Image Patches as GeoTIFF Files (Segmentation)\r\n\r\nSave image and label patches as GeoTIFF files in the specified `folder_name` under the current working directory. If `only_label=True`, only patches with non-zero labels are saved.\r\n\r\n```bash\r\npatch.generate_segmentation(format=\"tif\", folder_name=\"seg_tif\", only_label=True)\r\n```\r\n\r\n### 7. Saving Image Patches as NumPy Arrays (Segmentation)\r\n\r\nGenerate image and label patches in NumPy format with optional data augmentation (vertical flip, horizontal flip, 90/180/270-degree rotations). Augmentations are applied only for `format=\"npy\"`.\r\n\r\n```bash\r\npatch.generate_segmentation(\r\n format=\"npy\",\r\n folder_name=\"seg_npy\",\r\n only_label=False,\r\n return_stacked=False,\r\n save_stack=False,\r\n V_flip=True,\r\n H_flip=True,\r\n Rotation=True\r\n)\r\n\r\n# To return stacked NumPy patches:\r\npatch_stacked, label_stacked = patch.generate_segmentation(\r\n format=\"npy\",\r\n folder_name=\"seg_npy\",\r\n only_label=False,\r\n return_stacked=True,\r\n save_stack=False,\r\n V_flip=True,\r\n H_flip=True,\r\n Rotation=True\r\n)\r\n```\r\n\r\n### 8. Saving Patches for Object Detection (YOLO Format)\r\n\r\nGenerate patches for object detection, producing image patches, optional segmentation masks, and YOLO-format bounding box annotations (`.txt` files). Augmentations are applied only for `format=\"npy\"`.\r\n\r\n```bash\r\npatch.generate_detection(\r\n format=\"npy\",\r\n folder_name=\"det_npy\",\r\n only_label=True,\r\n return_stacked=False,\r\n save_stack=False,\r\n V_flip=True,\r\n H_flip=True,\r\n Rotation=True,\r\n segmentation=True\r\n)\r\n```\r\n\r\n### 9. Saving Patches from Shapefiles (Segmentation and/or Object Detection)\r\n\r\nGenerate patches for segmentation and/or object detection using a polygon shapefile. The shapefile is reprojected to WGS84 (EPSG:4326) before clipping and rasterization to ensure alignment with the image. Specify the `label_field` containing integer class IDs (e.g., `class_id`) during `TrainPatch` initialization. Outputs include image patches, optional segmentation masks, and YOLO-format bounding box annotations. Augmentations are applied only for `format=\"npy\"`.\r\n\r\n```bash\r\npatch = TrainPatch(\r\n image=\"xxx/image.tif\",\r\n label=None,\r\n patch_size=128,\r\n stride=64,\r\n channel_first=True,\r\n shapefile_path=\"xxx/labels.shp\",\r\n label_field=\"class_id\"\r\n)\r\n\r\n# For segmentation\r\npatch.generate_segmentation(\r\n format=\"npy\",\r\n folder_name=\"shp_npy\",\r\n only_label=True,\r\n return_stacked=True,\r\n save_stack=True,\r\n V_flip=True,\r\n H_flip=True,\r\n Rotation=True\r\n)\r\n\r\n# For detection\r\npatch.generate_detection(\r\n format=\"npy\",\r\n folder_name=\"shp_npy\",\r\n only_label=True,\r\n return_stacked=True,\r\n save_stack=True,\r\n V_flip=True,\r\n H_flip=True,\r\n Rotation=True,\r\n segmentation=True\r\n)\r\n```\r\n\r\n### 10. Patch Visualization\r\n\r\nDisplay patches with their corresponding labels or bounding boxes. Specify the exact `folder_name` where patches are saved. Use `show_bboxes=True` to overlay YOLO bounding boxes.\r\n\r\n```bash\r\npatch.visualize(\r\n folder_name=\"shp_npy\",\r\n patches_to_show=2,\r\n band_num=1,\r\n fig_size=(10, 20),\r\n dpi=96,\r\n show_bboxes=True\r\n)\r\n```\r\n\r\n### 11. Generating Prediction Patches\r\n\r\nGenerate patches for prediction using the `PredictionPatch` class:\r\n\r\n```bash\r\nprediction = PredictionPatch(image=\"xxx/test_image.tif\", patch_size=128, stride=128, channel_first=True)\r\n```\r\n\r\n### 12. Saving Prediction Patches\r\n\r\nSave prediction patches as GeoTIFF or NumPy arrays. Edge pixels are included to ensure complete image coverage.\r\n\r\n```bash\r\n# Save as GeoTIFF\r\nprediction.save_Geotif(folder_name=\"pred_tif\")\r\n\r\n# Save as NumPy arrays\r\nprediction.save_numpy(folder_name=\"pred_npy\")\r\n```\r\n\r\n## Change Log\r\n\r\n### 1.0 (04/07/2022)\r\n- First Release\r\n\r\n### 1.1 (03/08/2022)\r\n- Fixed issues with loading NumPy arrays\r\n- Fixed random visualization of samples\r\n\r\n### 1.1.1 (15/12/2022)\r\n- Fixed visualization issues in Linux environments\r\n- Added `PredictionPatch` class for generating prediction patches\r\n\r\n### 1.1.1 (22/11/2023)\r\n- Fixed edge pixel issue in prediction patch generation to ensure entire image is patched\r\n- Added GDAL to automatically installed packages\r\n\r\n### 1.2 (27/07/2025)\r\n- Added `generate_detection` method to `TrainPatch` for object detection with YOLO-format bounding box annotations\r\n- Modified `generate_segmentation` and `generate_detection` to apply augmentations (V_flip, H_flip, Rotation) only for `format=\"npy\"`, not for `format=\"tif\"`, to prevent shape mismatch errors\r\n\r\n### 1.3 (28/07/2025)\r\n- Added support for generating patches from polygon shapefiles in `TrainPatch`, enabling segmentation and/or object detection\r\n- Updated shapefile processing to reproject to WGS84 (EPSG:4326) before clipping and rasterization to prevent label mismatches due to CRS issues\r\n- Removed redundant `shapefile_path` parameter in `generate_from_shapefile`, using `label` and `label_field` from `TrainPatch` initialization\r\n- Added dependencies (`geopandas`, `shapely`, `scikit-image`) to support shapefile processing and bounding box generation\r\n\r\n### 1.3.1 (28/07/2025)\r\n- minor bugs resolved\r\n\r\n### 1.3.2 (28/07/2025)\r\n- Removed verbose print statements in `preprocess_and_rasterize` function to streamline output and improve user experience\r\n- Updated `TrainPatch` initialization to explicitly handle `shapefile_path` and `label_field` parameters for clarity\r\n- Improved documentation to reflect updated `TrainPatch` usage with shapefile inputs\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GeoPatch generates patches from remote sensing data and shapefiles for semantic segmentation and object detection with YOLO-format annotations",
"version": "1.3.2",
"project_urls": {
"Homepage": "https://github.com/Hejarshahabi/GeoPatch"
},
"split_keywords": [
"machine learning",
" remote sensing",
" deep learning",
" object detection",
" yolo",
" shapefile",
" geotiff"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b3a57bea33bf65e370babfe454751b6601b61c326433142555f5b3a0014d35d1",
"md5": "17c8446d304d48fe2b73f2d625f914a7",
"sha256": "468a959155c08e51e1e58b3444d54a0caecf3a63461c9fd2212c900e96728e84"
},
"downloads": -1,
"filename": "geopatch-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17c8446d304d48fe2b73f2d625f914a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10888,
"upload_time": "2025-07-28T20:46:45",
"upload_time_iso_8601": "2025-07-28T20:46:45.599004Z",
"url": "https://files.pythonhosted.org/packages/b3/a5/7bea33bf65e370babfe454751b6601b61c326433142555f5b3a0014d35d1/geopatch-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "437e094756675248c1ec61defe0f25517323e3680eb82ccc231f2d87c617f9f9",
"md5": "09c54fbb63ee8b7ef135d79070c4a40d",
"sha256": "1836263101c038c204f723026bfc3e6bef3bb16e4f4ad890ca10b29c45249a66"
},
"downloads": -1,
"filename": "geopatch-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "09c54fbb63ee8b7ef135d79070c4a40d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11814,
"upload_time": "2025-07-28T20:46:46",
"upload_time_iso_8601": "2025-07-28T20:46:46.706030Z",
"url": "https://files.pythonhosted.org/packages/43/7e/094756675248c1ec61defe0f25517323e3680eb82ccc231f2d87c617f9f9/geopatch-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 20:46:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hejarshahabi",
"github_project": "GeoPatch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "geopatch"
}
JSON
