# rschip
Split satellite images into smaller fixed-sized tiles, for input into convolutional neural networks (cnn), or vision
transformers (ViT) such as [Segment Anything](https://arxiv.org/abs/2304.02643).
## Features
- **Tile Satellite Images**: Split large satellite images into smaller chips of specified dimensions. Can min-max normalise
or standard scale before writing chips as required.
- **Mask Segmentation**: Generate segmentation mask images from geopackage or shapefile features for supervised
segmentation, e.g using [U-Net](https://arxiv.org/abs/1505.04597).
- **Remove Background Chips**: Filter out image chips containing only background. Useful for when preparing training
and testing datasets.
## Installation
Install rschip with pip:
```bash
pip install rschip
```
Requires `rasterio`, `numpy`, `geopandas`, and `shapely`.
## Usage
### 1. ImageChip Class
The `ImageChip` class provides functionality for creating tiles (also known as chips) from large satellite images.
```python
from rschip import ImageChip
# Initialize the ImageChip instance for 128 by 128 tiles
image_chipper = ImageChip(
input_image_path="path/to/large_image.tif",
output_path="path/to/output_directory_image",
pixel_dimensions=128,
offset=64,
output_format="tif",
)
# set a min max normaliser
# e.g for 16 bit Sentinel 2 RGB might use
image_chipper.set_normaliser(min_val=500, max_val=3000)
# Generate chips
image_chipper.chip_image()
```
With the `output_format` parameter set to `"tif"`, each resulting tile is named using a suffix that represents the bottom left `(x, y)`
pixel coordinate position. If output_format is set to `"npz"`, the resulting .npz zip file contains a dictionary of arrays,
where the keys are the same as these tile names. By default, the prefix of each tile name is taken from the input image file name
(`input_image_path`), unless you specify `output_name`.
Using the parameter `use_multiprocessing=True` (default) makes chipping process faster by using multiple cores.
### 2. SegmentationMask Class
The `SegmentationMask` class is used to create a segmentation mask images from geopackage or shapefile using an input image as extent and pixel size reference.
Once the segmentation mask has been created, the segmentation image can also be split into tiles. Some deep learning
frameworks expect images and corresponding masks to have the same file name in separate directories. The `output_name`
argument of ImageChip can ensure this is the case.
```python
from rschip import SegmentationMask, ImageChip
# Initialize the SegmentationMask
seg_mask = SegmentationMask(
input_image_path="path/to/large_image.tif",
input_features_path="path/to/geopackage_features.gpkg",
output_path="path/to/output_mask.tif",
class_field="ml_class"
)
# Generate segmentation mask image
seg_mask.create_mask()
# Chip the segmentation image to match satellite image
image_chipper = ImageChip(
input_image_path="path/to/output_mask.tif",
output_path="path/to/output_directory_mask",
output_name="large_image",
pixel_dimensions=128,
offset=64,
output_format="tif",
standard_scale=False,
)
image_chipper.chip_image()
```
### 3. RemoveBackgroundOnly Class
The `RemoveBackgroundOnly` class provides functionality to remove image chips (either could be tifs or numpy arrays inside npz file) that contain only background. Filtering out images only containing background helps to prepare a dataset more suitable for training models.
```python
from rschip import RemoveBackgroundOnly
# Initialize the RemoveBackgroundOnly instance
remover = RemoveBackgroundOnly(background_val=0, non_background_min=100)
# Remove chips with only background
remover.remove_background_only_files(
class_chips_dir="path/to/mask_directory",
image_chips_dir="path/to/image_directory"
)
```
The default assumption is that image and mask equivalent have the same file names as shown in example 2. above. If that is
not the case, use the `masks_prefix`, `images_prefix` arguments which are prefix strings which are removed on checking for
image to mask equivalent using the bottom left (x,y) indices found in the outputs generated by `ImageChip.create_chips()`.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "rschip",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "satellite, deep learning, tiling, segmentation, geospatial",
"author": null,
"author_email": "Tom Wilson <thomaswilson81@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/af/e3/347086dbb8936a762eb2378f54db20610c8e3517ca00d156969ebc3d7133/rschip-0.3.1.tar.gz",
"platform": null,
"description": "# rschip\n\n\n\n\n\nSplit satellite images into smaller fixed-sized tiles, for input into convolutional neural networks (cnn), or vision \ntransformers (ViT) such as [Segment Anything](https://arxiv.org/abs/2304.02643).\n\n## Features\n\n- **Tile Satellite Images**: Split large satellite images into smaller chips of specified dimensions. Can min-max normalise \n or standard scale before writing chips as required.\n- **Mask Segmentation**: Generate segmentation mask images from geopackage or shapefile features for supervised \n segmentation, e.g using [U-Net](https://arxiv.org/abs/1505.04597).\n- **Remove Background Chips**: Filter out image chips containing only background. Useful for when preparing training \n and testing datasets.\n\n## Installation\n\nInstall rschip with pip:\n\n```bash\npip install rschip\n```\n\nRequires `rasterio`, `numpy`, `geopandas`, and `shapely`.\n\n## Usage\n\n### 1. ImageChip Class\nThe `ImageChip` class provides functionality for creating tiles (also known as chips) from large satellite images.\n\n```python\nfrom rschip import ImageChip\n\n# Initialize the ImageChip instance for 128 by 128 tiles\nimage_chipper = ImageChip(\n input_image_path=\"path/to/large_image.tif\",\n output_path=\"path/to/output_directory_image\",\n pixel_dimensions=128,\n offset=64,\n output_format=\"tif\",\n)\n\n# set a min max normaliser \n# e.g for 16 bit Sentinel 2 RGB might use\nimage_chipper.set_normaliser(min_val=500, max_val=3000)\n\n# Generate chips\nimage_chipper.chip_image()\n```\nWith the `output_format` parameter set to `\"tif\"`, each resulting tile is named using a suffix that represents the bottom left `(x, y)`\npixel coordinate position. If output_format is set to `\"npz\"`, the resulting .npz zip file contains a dictionary of arrays, \nwhere the keys are the same as these tile names. By default, the prefix of each tile name is taken from the input image file name \n(`input_image_path`), unless you specify `output_name`.\n\nUsing the parameter `use_multiprocessing=True` (default) makes chipping process faster by using multiple cores. \n\n### 2. SegmentationMask Class\nThe `SegmentationMask` class is used to create a segmentation mask images from geopackage or shapefile using an input image as extent and pixel size reference.\n\nOnce the segmentation mask has been created, the segmentation image can also be split into tiles. Some deep learning \nframeworks expect images and corresponding masks to have the same file name in separate directories. The `output_name` \nargument of ImageChip can ensure this is the case.\n\n```python\nfrom rschip import SegmentationMask, ImageChip\n\n# Initialize the SegmentationMask\nseg_mask = SegmentationMask(\n input_image_path=\"path/to/large_image.tif\",\n input_features_path=\"path/to/geopackage_features.gpkg\",\n output_path=\"path/to/output_mask.tif\",\n class_field=\"ml_class\"\n)\n\n# Generate segmentation mask image\nseg_mask.create_mask()\n\n# Chip the segmentation image to match satellite image\nimage_chipper = ImageChip(\n input_image_path=\"path/to/output_mask.tif\",\n output_path=\"path/to/output_directory_mask\",\n output_name=\"large_image\",\n pixel_dimensions=128,\n offset=64,\n output_format=\"tif\",\n standard_scale=False,\n)\nimage_chipper.chip_image()\n```\n\n### 3. RemoveBackgroundOnly Class\nThe `RemoveBackgroundOnly` class provides functionality to remove image chips (either could be tifs or numpy arrays inside npz file) that contain only background. Filtering out images only containing background helps to prepare a dataset more suitable for training models.\n \n```python\nfrom rschip import RemoveBackgroundOnly\n\n# Initialize the RemoveBackgroundOnly instance\nremover = RemoveBackgroundOnly(background_val=0, non_background_min=100)\n\n# Remove chips with only background\nremover.remove_background_only_files(\n class_chips_dir=\"path/to/mask_directory\",\n image_chips_dir=\"path/to/image_directory\"\n)\n```\nThe default assumption is that image and mask equivalent have the same file names as shown in example 2. above. If that is\nnot the case, use the `masks_prefix`, `images_prefix` arguments which are prefix strings which are removed on checking for\nimage to mask equivalent using the bottom left (x,y) indices found in the outputs generated by `ImageChip.create_chips()`.\n\n## License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Prepare satellite images and training data for use with deep learning models",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [
"satellite",
" deep learning",
" tiling",
" segmentation",
" geospatial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "47f2b12599d110cad51f9903cdc503453b4f4274f20dc285ae3da9916828dedf",
"md5": "d78565568cb3cf4d648446a5030bc728",
"sha256": "f3db21c06b03a59c41b3048f300aa25b5b287d35fbb27de746b477c345e70cb2"
},
"downloads": -1,
"filename": "rschip-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d78565568cb3cf4d648446a5030bc728",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 13490,
"upload_time": "2024-11-12T11:34:09",
"upload_time_iso_8601": "2024-11-12T11:34:09.200260Z",
"url": "https://files.pythonhosted.org/packages/47/f2/b12599d110cad51f9903cdc503453b4f4274f20dc285ae3da9916828dedf/rschip-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "afe3347086dbb8936a762eb2378f54db20610c8e3517ca00d156969ebc3d7133",
"md5": "2cb96294ae0f2071c4f70bb95e3ceb4a",
"sha256": "51457ee35c24372d1b6f806dfd7428f8bccd4fb37e5e9bcca8e09e8594ea7314"
},
"downloads": -1,
"filename": "rschip-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "2cb96294ae0f2071c4f70bb95e3ceb4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18144,
"upload_time": "2024-11-12T11:34:11",
"upload_time_iso_8601": "2024-11-12T11:34:11.344622Z",
"url": "https://files.pythonhosted.org/packages/af/e3/347086dbb8936a762eb2378f54db20610c8e3517ca00d156969ebc3d7133/rschip-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 11:34:11",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "rschip"
}
JSON