# ForesTiler — Create Image Tiles From Large Input Rasters According to a Classified Mask Vector File
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13221009.svg)](https://doi.org/10.5281/zenodo.13221009)
ForesTiler provides a CLI tool to create image tiles from large input rasters according to a classified mask vector file.
The goal is to export images that are completely covered by a class polygon.
They can be saved either as PNGs to directly feed them into machine learning frameworks which may not interop with geodata or
as GeoTIFFs when retention of geographic information is deemed important.
> [!IMPORTANT]
> It was decided to trade computational efficiency and versatility for somewhat cleaner code. Thus, you may need to reduce the size of your input images.
> Also, also, this means only square images are supported
## Installation
> [!WARNING]
> Please note, that you need to have at least Python 3.9 installed.
> [!TIP]
> Use pipx instead of pip which also creates a unique virtual environment for environment isolation.
You can install `forestiler` via pip by running
```bash
pip install forestiler
```
## Usage
> [!CAUTION]
> Only north-up images are supported. If your raster images are rotated, please transform them first!
> [!CAUTION]
> Don't quote class labels on the command line.
```
usage: forestile [-h] [--no-progress] [--pad] [--kernel-size KERNEL_SIZE] [--stride STRIDE]
--vector-mask VECTOR_MASK [--class-field CLASS_FIELD] [--all-classes]
[--classes CLASSES [CLASSES ...]] [--input-glob INPUT_GLOB] [--geo-tiff]
input out
forestile creates image tiles from large input rasters according to a classified mask vector file.
positional arguments:
input Directory containing raster files to tile.
out Directory where output files should be stored.
May not exist prior to program invocation.
optional arguments:
-h, --help show this help message and exit
--no-progress Disable progress bar
--pad Disable padding of input images.
--kernel-size KERNEL_SIZE
Kernel size in pixels.
--stride STRIDE Stride of kernel.
--vector-mask VECTOR_MASK
Path to vector file. Always reads first layer,
if driver supports multi-layerr files (e.g. Geopackages).
--class-field CLASS_FIELD
Attribute field containing class values.
--all-classes Generate image chips for all unique values in class field.
--classes CLASSES [CLASSES ...]
List of classes to build image tiles for.
--input-glob INPUT_GLOB
Optional glob pattern to filter files in input directory.
--geo-tiff Store image chips as GeoTiffs instead of PNGs.
Copyright: Florian Katerndahl <florian@katerndahl.com>
```
### Example Usage
Given a directory structure like the one listed below, the following command reads the file `mask.gpkg` and queries all geometries where the attribute "tree" matches "oak".
All output image chips, here as georeferenced TIFF files, are written into the directory `output` (which may not exist prior to program invocation).
```bash
forestile --stride 50 --vector-mask mask.gpkg --class-field tree --classes "oak" --geo-tiff rasters/ output/
```
```bash
.
├── output/
├── rasters/
│ ├── truedop20rgb_386_5808_2_be_2020.tif
│ ├── truedop20rgb_386_5810_2_be_2020.tif
│ ├── truedop20rgb_388_5808_2_be_2020.tif
│ └── truedop20rgb_388_5810_2_be_2020.tif
└── mask.gpkg
```
## Contribution
Bug reports, suggestions and feature requests are always welcomed. Please [open an issue](https://github.com/Florian-Katerndahl/ForesTiler/issues) on GitHub.
## Citation
If you use this package, see [CITATION](CITATION.cff) and cite this work.
## Acknowledgements
This package was developed at the Remote Sensing Lab at Freie Universität Berlin.
Raw data
{
"_id": null,
"home_page": "https://github.com/Florian-Katerndahl/ForesTiler",
"name": "forestiler",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "remote sensing, image processing, data preparation",
"author": "Florian Katerndahl",
"author_email": "florian@katerndahl.com",
"download_url": "https://files.pythonhosted.org/packages/a1/d7/f917f2e8083cf94790b47b3018c26dfcf2ac11e479d1d2297b3944b2c715/forestiler-0.2.2.tar.gz",
"platform": null,
"description": "# ForesTiler \u2014 Create Image Tiles From Large Input Rasters According to a Classified Mask Vector File\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13221009.svg)](https://doi.org/10.5281/zenodo.13221009)\n\nForesTiler provides a CLI tool to create image tiles from large input rasters according to a classified mask vector file.\nThe goal is to export images that are completely covered by a class polygon.\nThey can be saved either as PNGs to directly feed them into machine learning frameworks which may not interop with geodata or\nas GeoTIFFs when retention of geographic information is deemed important.\n\n> [!IMPORTANT]\n> It was decided to trade computational efficiency and versatility for somewhat cleaner code. Thus, you may need to reduce the size of your input images.\n> Also, also, this means only square images are supported\n\n## Installation\n\n> [!WARNING]\n> Please note, that you need to have at least Python 3.9 installed.\n\n> [!TIP]\n> Use pipx instead of pip which also creates a unique virtual environment for environment isolation.\n\nYou can install `forestiler` via pip by running\n\n```bash\npip install forestiler\n```\n\n## Usage\n\n> [!CAUTION]\n> Only north-up images are supported. If your raster images are rotated, please transform them first!\n\n> [!CAUTION]\n> Don't quote class labels on the command line.\n\n```\nusage: forestile [-h] [--no-progress] [--pad] [--kernel-size KERNEL_SIZE] [--stride STRIDE] \n --vector-mask VECTOR_MASK [--class-field CLASS_FIELD] [--all-classes]\n [--classes CLASSES [CLASSES ...]] [--input-glob INPUT_GLOB] [--geo-tiff]\n input out\n\nforestile creates image tiles from large input rasters according to a classified mask vector file.\n\npositional arguments:\n input Directory containing raster files to tile.\n out Directory where output files should be stored. \n May not exist prior to program invocation.\n\noptional arguments:\n -h, --help show this help message and exit\n --no-progress Disable progress bar\n --pad Disable padding of input images.\n --kernel-size KERNEL_SIZE\n Kernel size in pixels.\n --stride STRIDE Stride of kernel.\n --vector-mask VECTOR_MASK\n Path to vector file. Always reads first layer, \n if driver supports multi-layerr files (e.g. Geopackages).\n --class-field CLASS_FIELD\n Attribute field containing class values.\n --all-classes Generate image chips for all unique values in class field.\n --classes CLASSES [CLASSES ...]\n List of classes to build image tiles for.\n --input-glob INPUT_GLOB\n Optional glob pattern to filter files in input directory.\n --geo-tiff Store image chips as GeoTiffs instead of PNGs.\n\nCopyright: Florian Katerndahl <florian@katerndahl.com>\n```\n\n### Example Usage\n\nGiven a directory structure like the one listed below, the following command reads the file `mask.gpkg` and queries all geometries where the attribute \"tree\" matches \"oak\".\nAll output image chips, here as georeferenced TIFF files, are written into the directory `output` (which may not exist prior to program invocation).\n\n```bash\nforestile --stride 50 --vector-mask mask.gpkg --class-field tree --classes \"oak\" --geo-tiff rasters/ output/\n```\n\n```bash\n.\n\u251c\u2500\u2500 output/\n\u251c\u2500\u2500 rasters/\n\u2502 \u251c\u2500\u2500 truedop20rgb_386_5808_2_be_2020.tif\n\u2502 \u251c\u2500\u2500 truedop20rgb_386_5810_2_be_2020.tif\n\u2502 \u251c\u2500\u2500 truedop20rgb_388_5808_2_be_2020.tif\n\u2502 \u2514\u2500\u2500 truedop20rgb_388_5810_2_be_2020.tif\n\u2514\u2500\u2500 mask.gpkg\n```\n\n## Contribution\n\nBug reports, suggestions and feature requests are always welcomed. Please [open an issue](https://github.com/Florian-Katerndahl/ForesTiler/issues) on GitHub.\n\n## Citation\n\nIf you use this package, see [CITATION](CITATION.cff) and cite this work.\n\n## Acknowledgements\n\nThis package was developed at the Remote Sensing Lab at Freie Universit\u00e4t Berlin.\n",
"bugtrack_url": null,
"license": "GPL-2.0-only",
"summary": "Create Image Tiles From Large Input Rasters According to a Classified Mask Vector File",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/Florian-Katerndahl/ForesTiler/issues",
"Homepage": "https://github.com/Florian-Katerndahl/ForesTiler",
"Repository": "https://github.com/Florian-Katerndahl/ForesTiler"
},
"split_keywords": [
"remote sensing",
" image processing",
" data preparation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e36c733e887158a47d2d2047a33980b02a26940f4a78febfbda6f4f51f877a4c",
"md5": "241624ea69f74c8629dc2cbf4ae2eab8",
"sha256": "ad24c8d5bcbe1f8f40a807511d0de4f0590ee890f60c335ab990e68e1bced0f5"
},
"downloads": -1,
"filename": "forestiler-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "241624ea69f74c8629dc2cbf4ae2eab8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 15244,
"upload_time": "2024-10-09T13:33:36",
"upload_time_iso_8601": "2024-10-09T13:33:36.488493Z",
"url": "https://files.pythonhosted.org/packages/e3/6c/733e887158a47d2d2047a33980b02a26940f4a78febfbda6f4f51f877a4c/forestiler-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1d7f917f2e8083cf94790b47b3018c26dfcf2ac11e479d1d2297b3944b2c715",
"md5": "e60986e9a65e20e3e8fbe7f1618ff0ad",
"sha256": "c735817b5863e8aa136e4a47d9905c3fe08931a2e201aec48ceb135861ba0cc0"
},
"downloads": -1,
"filename": "forestiler-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "e60986e9a65e20e3e8fbe7f1618ff0ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 13545,
"upload_time": "2024-10-09T13:33:38",
"upload_time_iso_8601": "2024-10-09T13:33:38.533284Z",
"url": "https://files.pythonhosted.org/packages/a1/d7/f917f2e8083cf94790b47b3018c26dfcf2ac11e479d1d2297b3944b2c715/forestiler-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 13:33:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Florian-Katerndahl",
"github_project": "ForesTiler",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "forestiler"
}