# Glint Mask Tools
<div style="overflow: hidden; display: flex; justify-content:flex-start; gap:10px;">
<a href="https://github.com/HakaiInstitute/GlintMaskGenerator/actions/workflows/test_code.yml">
<img alt="Tests" src="https://github.com/HakaiInstitute/GlintMaskGenerator/actions/workflows/test_code.yml/badge.svg"/>
</a>
<a href="https://github.com/HakaiInstitute/GlintMaskGenerator/blob/main/LICENSE.txt">
<img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-black.svg" height="20px" />
</a>
<a href="https://badge.fury.io/py/glint-mask-tools">
<img alt="PyPI version" src="https://badge.fury.io/py/glint-mask-tools.svg" height="20">
</a>
<a href="https://zenodo.org/badge/latestdoi/266147098">
<img src="https://zenodo.org/badge/266147098.svg" alt="DOI">
</a>
</div>
## Description
GlintMaskGenerator generates image masks for regions in RGB and multispectral image files that have high levels of specular reflection.
These masks can be used in 3rd party structure-from-motion programs to replace these high glint regions with more useful data from adjacent, overlapping imagery.
## Installation
1. Go to the [releases page](https://github.com/HakaiInstitute/glint-mask-tools/releases)
2. Download the latest release file for your operating system.
3. Extract the compressed binary files from the gzipped archive.
4. This archive contains a file named GlintMaskGenerator-v*.\*.\*.exe that provides a GUI interface to the glint mask generation program.
5. You can copy these files to any location that is convenient for you.
### PyPi package
There also a python package version of the code available for Python 3.8 and 3.9.
1. `pip install glint-mask-tools` to install the tools.
2. Then, `import glint_mask_generator` in your Python script.
3. Installing with pip also installs the CLI tool, detailed below.
## Usage
### GUI
In Windows, launch the GUI by double clicking the executable file. In Linux, you'll have to launch the GUI from the
terminal, e.g. `./GlintMaskGenerator`.
For now, generating masks by passing directory paths containing images is the supported workflow. Be sure to change the
image type option when processing imagery for cameras other than RGB cameras (e.g. Micasense RedEdge or DJI P4MS cameras). You will be notified of any
processing errors via a pop-up dialog.
### CLI
For information about the parameters expected by the CLI, run `glint-mask --help` in a bash terminal or command
line interface. All the functionality of the CLI is documented there.
#### Examples
```bash
glint-mask-v*.*.* --help
# NAME
# glint-mask-v*.*.*
#
# SYNOPSIS
# glint-mask-v*.*.* - COMMAND | VALUE
#
# COMMANDS
# COMMAND is one of the following:
#
# cir_threshold
# Generate masks for glint regions in 4 Band CIR imagery using Tom Bell's binning algorithm.
#
# micasense_threshold
# Generate masks for glint regions in multispectral imagery from the Micasense camera using Tom Bell's algorithm on the blue image band.
#
# p4ms_threshold
# Generate masks for glint regions in multispectral imagery from the DJI camera using Tom Bell's algorithm on the Blue image band.
#
# process
#
# rgb_threshold
# Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.
#
# VALUES
# VALUE is one of the following:
#
# max_workers
# The maximum number of threads to use for processing.
```
```bash
# Get addition parameters for one of the cameras/methods available
glint-mask-v*.*.* rgb_threshold --help
# NAME
# glint-mask-v*.*.* rgb_threshold - Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.
#
# SYNOPSIS
# glint-mask-v*.*.* rgb_threshold IMG_DIR OUT_DIR <flags>
#
# DESCRIPTION
# Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.
#
# POSITIONAL ARGUMENTS
# IMG_DIR
# The path to a named input image or directory containing images. If img_dir is a directory, all tif, jpg, jpeg, and png images in that directory will be # processed.
# OUT_DIR
# The path to send your out image including the file name and type. e.g. "/path/to/mask.png". out_dir must be a directory if img_dir is specified as a # # # directory.
#
# FLAGS
# --thresholds=THRESHOLDS
# The pixel band thresholds indicating glint. Domain for values is (0.0, 1.0). Default is [1, 1, 0.875].
# --pixel_buffer=PIXEL_BUFFER
# The pixel distance to buffer out the mask. Defaults to 0 (off).
#
# NOTES
# You can also use flags syntax for POSITIONAL ARGUMENTS
```
```bash
# Process rgb imagery directory with default parameters
glint-mask-v*.*.* rgb_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/
# Process PhaseONE camera imagery with image bands split over multiple files
glint-mask-v*.*.* aco_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/
# Process DJI P4MS imagery
glint-mask-v*.*.* p4ms_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/
# Process Micasense RedEdge imagery
glint-mask-v*.*.* micasense_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/
```
### Python package
Installing the PyPi package allows integrating the mask generation workflow into existing python scripts with ease.
```python
from glint_mask_generator import MicasenseRedEdgeThresholdMasker
# Also available: P4MSThresholdMasker, RGBIntensityRatioMasker, RGBThresholdMasker
masker = MicasenseRedEdgeThresholdMasker(img_dir="path/to/micasense/images/", mask_dir="path/to/output/dir/",
thresholds=(0.875, 1, 1, 1, 1), pixel_buffer=5)
masker.process(max_workers=5, callback=print, err_callback=print)
```
## Notes
### Directory of images processing
- All files with "jpg", "jpeg", "tif", "tiff" and "png" extensions will be processed. This can be extended as needed.
File extension matching is case-insensitive.
- Output mask files with be in the specified directory, and have the same name as the input file with "_mask" appended
to the end of the file name stem. The file type will match the input type.
### Multi-band image processing
- For imagery types where each band is spread over multiple files, a mask will be generated for all the sibling band images.
- For example, if a mask is generated using a threshold on the blue band image, identical masks are saved for sibling red, green, blue, nir, and red_edge bands as well.
- If thresholds are passed for multiple bands, these mask outputs combined with a union operator before being saved for all the sibling bands associated with that capture event.
## Bugs and Feature Requests
This software is under active development. Bugs and feature requests can be filed using issues page located [here](https://github.com/HakaiInstitute/glint-mask-tools/issues).
## Citation
Research using these tools or code should cite the following resources
```bibtext
@article{Cavanaugh2021,
title = {An Automated Method for Mapping Giant Kelp Canopy Dynamics from UAV},
author = {Cavanaugh, K.C. and Cavanaugh, K.C. and Bell, T.W. and Hockridge, E.G.},
year = 2021,
journal = {Front. Environ. Sci.},
volume = {8:587354},
doi = {10.3389/fenvs.2020.587354}
}
@misc{Denouden2021,
title = {GlintMaskGenerator},
author = {Denouden, T. and Timmer, B. and Reshitnyk, L.},
year = 2021,
journal = {GitHub repository},
publisher = {GitHub},
doi = {10.21966/3cpa-2e10},
howpublished = {\url{https://github.com/HakaiInstitute/GlintMaskGenerator}},
commit = {8cb19e55f128da86bf0dbd312bc360ac89fe71c3}
}
```
## Development
See [DEVELOPMENT.md](DEVELOPMENT.md) for development and software maintenance instructions.
## License
GlintMaskGenerator is released under a MIT license, as found in the [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/HakaiInstitute/GlintMaskGenerator",
"name": "glint-mask-tools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<3.12",
"maintainer_email": "",
"keywords": "",
"author": "Taylor Denouden",
"author_email": "taylor.denouden@hakai.org",
"download_url": "https://files.pythonhosted.org/packages/5b/ac/9e347838120f7a1f773c41e792c3bc592647489913638c2637792aa40780/glint_mask_tools-3.1.0.tar.gz",
"platform": null,
"description": "# Glint Mask Tools\n\n<div style=\"overflow: hidden; display: flex; justify-content:flex-start; gap:10px;\">\n<a href=\"https://github.com/HakaiInstitute/GlintMaskGenerator/actions/workflows/test_code.yml\">\n <img alt=\"Tests\" src=\"https://github.com/HakaiInstitute/GlintMaskGenerator/actions/workflows/test_code.yml/badge.svg\"/>\n</a>\n\n<a href=\"https://github.com/HakaiInstitute/GlintMaskGenerator/blob/main/LICENSE.txt\">\n <img alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-black.svg\" height=\"20px\" />\n</a>\n\n<a href=\"https://badge.fury.io/py/glint-mask-tools\">\n <img alt=\"PyPI version\" src=\"https://badge.fury.io/py/glint-mask-tools.svg\" height=\"20\">\n</a>\n\n<a href=\"https://zenodo.org/badge/latestdoi/266147098\">\n <img src=\"https://zenodo.org/badge/266147098.svg\" alt=\"DOI\">\n</a>\n</div>\n\n## Description\n\nGlintMaskGenerator generates image masks for regions in RGB and multispectral image files that have high levels of specular reflection.\n\nThese masks can be used in 3rd party structure-from-motion programs to replace these high glint regions with more useful data from adjacent, overlapping imagery.\n\n## Installation\n\n1. Go to the [releases page](https://github.com/HakaiInstitute/glint-mask-tools/releases)\n2. Download the latest release file for your operating system.\n3. Extract the compressed binary files from the gzipped archive.\n4. This archive contains a file named GlintMaskGenerator-v*.\\*.\\*.exe that provides a GUI interface to the glint mask generation program.\n5. You can copy these files to any location that is convenient for you.\n\n### PyPi package\n\nThere also a python package version of the code available for Python 3.8 and 3.9.\n\n1. `pip install glint-mask-tools` to install the tools.\n2. Then, `import glint_mask_generator` in your Python script.\n3. Installing with pip also installs the CLI tool, detailed below.\n\n## Usage\n\n### GUI\n\nIn Windows, launch the GUI by double clicking the executable file. In Linux, you'll have to launch the GUI from the\nterminal, e.g. `./GlintMaskGenerator`.\n\nFor now, generating masks by passing directory paths containing images is the supported workflow. Be sure to change the\nimage type option when processing imagery for cameras other than RGB cameras (e.g. Micasense RedEdge or DJI P4MS cameras). You will be notified of any\nprocessing errors via a pop-up dialog.\n\n### CLI\n\nFor information about the parameters expected by the CLI, run `glint-mask --help` in a bash terminal or command\nline interface. All the functionality of the CLI is documented there.\n\n#### Examples\n\n```bash\nglint-mask-v*.*.* --help\n\n# NAME\n# glint-mask-v*.*.*\n#\n# SYNOPSIS\n# glint-mask-v*.*.* - COMMAND | VALUE\n#\n# COMMANDS\n# COMMAND is one of the following:\n#\n# cir_threshold\n# Generate masks for glint regions in 4 Band CIR imagery using Tom Bell's binning algorithm.\n#\n# micasense_threshold\n# Generate masks for glint regions in multispectral imagery from the Micasense camera using Tom Bell's algorithm on the blue image band.\n#\n# p4ms_threshold\n# Generate masks for glint regions in multispectral imagery from the DJI camera using Tom Bell's algorithm on the Blue image band.\n#\n# process\n#\n# rgb_threshold\n# Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.\n#\n# VALUES\n# VALUE is one of the following:\n#\n# max_workers\n# The maximum number of threads to use for processing.\n```\n\n```bash\n# Get addition parameters for one of the cameras/methods available\nglint-mask-v*.*.* rgb_threshold --help\n\n# NAME\n# glint-mask-v*.*.* rgb_threshold - Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.\n#\n# SYNOPSIS\n# glint-mask-v*.*.* rgb_threshold IMG_DIR OUT_DIR <flags>\n#\n# DESCRIPTION\n# Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.\n#\n# POSITIONAL ARGUMENTS\n# IMG_DIR\n# The path to a named input image or directory containing images. If img_dir is a directory, all tif, jpg, jpeg, and png images in that directory will be # processed.\n# OUT_DIR\n# The path to send your out image including the file name and type. e.g. \"/path/to/mask.png\". out_dir must be a directory if img_dir is specified as a # # # directory.\n#\n# FLAGS\n# --thresholds=THRESHOLDS\n# The pixel band thresholds indicating glint. Domain for values is (0.0, 1.0). Default is [1, 1, 0.875].\n# --pixel_buffer=PIXEL_BUFFER\n# The pixel distance to buffer out the mask. Defaults to 0 (off).\n#\n# NOTES\n# You can also use flags syntax for POSITIONAL ARGUMENTS\n```\n\n```bash\n# Process rgb imagery directory with default parameters\nglint-mask-v*.*.* rgb_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/\n\n# Process PhaseONE camera imagery with image bands split over multiple files\nglint-mask-v*.*.* aco_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/\n\n# Process DJI P4MS imagery\nglint-mask-v*.*.* p4ms_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/\n\n# Process Micasense RedEdge imagery\nglint-mask-v*.*.* micasense_threshold /path/to/dir/with/images/ /path/to/out_masks/dir/\n```\n\n### Python package\nInstalling the PyPi package allows integrating the mask generation workflow into existing python scripts with ease.\n\n```python\nfrom glint_mask_generator import MicasenseRedEdgeThresholdMasker\n\n# Also available: P4MSThresholdMasker, RGBIntensityRatioMasker, RGBThresholdMasker\n\nmasker = MicasenseRedEdgeThresholdMasker(img_dir=\"path/to/micasense/images/\", mask_dir=\"path/to/output/dir/\",\n thresholds=(0.875, 1, 1, 1, 1), pixel_buffer=5)\nmasker.process(max_workers=5, callback=print, err_callback=print)\n```\n\n## Notes\n\n### Directory of images processing\n\n- All files with \"jpg\", \"jpeg\", \"tif\", \"tiff\" and \"png\" extensions will be processed. This can be extended as needed.\n File extension matching is case-insensitive.\n- Output mask files with be in the specified directory, and have the same name as the input file with \"_mask\" appended\n to the end of the file name stem. The file type will match the input type.\n\n### Multi-band image processing\n- For imagery types where each band is spread over multiple files, a mask will be generated for all the sibling band images.\n - For example, if a mask is generated using a threshold on the blue band image, identical masks are saved for sibling red, green, blue, nir, and red_edge bands as well.\n - If thresholds are passed for multiple bands, these mask outputs combined with a union operator before being saved for all the sibling bands associated with that capture event.\n\n## Bugs and Feature Requests\n\nThis software is under active development. Bugs and feature requests can be filed using issues page located [here](https://github.com/HakaiInstitute/glint-mask-tools/issues).\n\n## Citation\n\nResearch using these tools or code should cite the following resources\n\n```bibtext\n@article{Cavanaugh2021,\n\ttitle = {An Automated Method for Mapping Giant Kelp Canopy Dynamics from UAV},\n\tauthor = {Cavanaugh, K.C. and Cavanaugh, K.C. and Bell, T.W. and Hockridge, E.G.},\n\tyear = 2021,\n\tjournal = {Front. Environ. Sci.},\n\tvolume = {8:587354},\n\tdoi = {10.3389/fenvs.2020.587354}\n}\n@misc{Denouden2021,\n\ttitle = {GlintMaskGenerator},\n\tauthor = {Denouden, T. and Timmer, B. and Reshitnyk, L.},\n\tyear = 2021,\n\tjournal = {GitHub repository},\n\tpublisher = {GitHub},\n\tdoi = {10.21966/3cpa-2e10},\n\thowpublished = {\\url{https://github.com/HakaiInstitute/GlintMaskGenerator}},\n\tcommit = {8cb19e55f128da86bf0dbd312bc360ac89fe71c3}\n}\n```\n\n## Development\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for development and software maintenance instructions.\n\n## License\nGlintMaskGenerator is released under a MIT license, as found in the [LICENSE](LICENSE) file.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create masks for specular reflection in UAV and aerial imagery",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/HakaiInstitute/GlintMaskGenerator",
"Repository": "https://github.com/HakaiInstitute/GlintMaskGenerator"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7fc4964d52234f0213fee24d94c3d861d708b687611ee83d0c3902120b37ae2f",
"md5": "62a5fae82bc8c565e035bdb8e96d0fbe",
"sha256": "88c6b1cf56b9f988a405fbfa2506dacaef073499ed3a149824dbb3ef054ab5ce"
},
"downloads": -1,
"filename": "glint_mask_tools-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62a5fae82bc8c565e035bdb8e96d0fbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<3.12",
"size": 13789,
"upload_time": "2023-07-26T20:24:47",
"upload_time_iso_8601": "2023-07-26T20:24:47.640609Z",
"url": "https://files.pythonhosted.org/packages/7f/c4/964d52234f0213fee24d94c3d861d708b687611ee83d0c3902120b37ae2f/glint_mask_tools-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5bac9e347838120f7a1f773c41e792c3bc592647489913638c2637792aa40780",
"md5": "682ac8132937cf65cb28bb94bcc5c3a9",
"sha256": "4f0953b8be8b1baed9f5cb35b1f52be098943bf0283e37690702b9ecc667ec8c"
},
"downloads": -1,
"filename": "glint_mask_tools-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "682ac8132937cf65cb28bb94bcc5c3a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<3.12",
"size": 14388,
"upload_time": "2023-07-26T20:24:50",
"upload_time_iso_8601": "2023-07-26T20:24:50.224960Z",
"url": "https://files.pythonhosted.org/packages/5b/ac/9e347838120f7a1f773c41e792c3bc592647489913638c2637792aa40780/glint_mask_tools-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-26 20:24:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HakaiInstitute",
"github_project": "GlintMaskGenerator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "glint-mask-tools"
}
JSON
