forestiler


Nameforestiler JSON
Version 0.2.2 PyPI version JSON
download
home_pagehttps://github.com/Florian-Katerndahl/ForesTiler
SummaryCreate Image Tiles From Large Input Rasters According to a Classified Mask Vector File
upload_time2024-10-09 13:33:38
maintainerNone
docs_urlNone
authorFlorian Katerndahl
requires_python<4.0,>=3.9
licenseGPL-2.0-only
keywords remote sensing image processing data preparation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.56858s