Skip to content

Commit c1bf563

Browse files
taydentayden
committed
Merge branch 'docs'
2 parents dadf54b + 5c19497 commit c1bf563

File tree

12 files changed

+1402
-184
lines changed

12 files changed

+1402
-184
lines changed

‎.github/dependabot.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,4 @@ updates:
1515
- "*"
1616
update-types:
1717
- "minor"
18-
- "patch"
18+
- "patch"

‎.readthedocs.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
version: 2
2+
3+
build:
4+
os: "ubuntu-20.04"
5+
tools:
6+
python: "3.9"
7+
8+
mkdocs:
9+
configuration: mkdocs.yml
10+
fail_on_warning: false
11+
12+
python:
13+
# Install our python package before building the docs
14+
install:
15+
- requirements: docs/requirements.txt
16+
- method: pip
17+
path: .
18+
extra_requirements:
19+
- docs

‎docs/faq.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Common Questions
2+
3+
Here are some answers to the questions we get most often
4+
5+
**What settings do you recommend?**
6+
7+
The current threshold defaults in all interfaces are what we found works best, in our own testing. We recommend
8+
starting there and making small adjustments as needed. It may be useful to process just a subset of your images for
9+
testing purposes for the sake of quickly iterating and finding what works best for you.
10+
11+
We typically use a pixel buffer of 2 to slightly expand our masked areas.
12+
13+
**What number of workers should I use?**
14+
15+
We typically use the default of 4. If you have a really powerful machine with a lot of memory, you might benefit from
16+
increasing this value. If you're machine is grinding to a halt, lower it.

‎docs/how_it_works.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# How it works
2+
3+
Structure from Motion (SfM) photogrammetry offers an effective solution for handling masked or obscured areas in imagery
4+
through its multi-image processing capabilities. As illustrated in the diagram, when two overlapping images contain
5+
masks identifying problematic areas (such as glints or data gaps), SfM can leverage the complementary information from
6+
both images during the alignment and mosaicking process.
7+
8+
![How it works](images/howitdo.png)
9+
10+
**Key Requirements for Optimal Results:**
11+
12+
- Image overlap >50% recommended
13+
- Consistent lighting conditions
14+
- Proper camera settings
15+
- Quality source imagery

‎docs/index.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Glint Mask Generator
2+
3+
Glint Mask Generator is a utility for generating mask images that correspond to the area of spectral glint in some
4+
source imagery. Once generated, the masks can be used by 3rd party structure-from-motion (SfM) software to replace glint
5+
areas with data from overlapping imagery that are not glinty.
6+
7+
## Quick Start
8+
9+
1. Download the [latest release](https://github.com/HakaiInstitute/glint-mask-tools/releases) for your platform
10+
2. Launch the GUI application
11+
3. Select your imagery type and input directory
12+
4. Click Run to generate masks
13+
14+
<div style="margin-top: 50px; overflow: hidden; display: flex; justify-content:center; gap:10px;">
15+
<img alt="Glint" src="./images/glint.gif" width="80%" />
16+
</div>
17+
18+
## Features
19+
20+
### Multiple interfaces to suit your workflow:
21+
- User-friendly GUI for interactive use
22+
- CLI for automation and scripting
23+
- Python package for integration into existing pipelines
24+
25+
### Support for various camera types:
26+
- RGB cameras
27+
- PhaseOne 4-band CIRs
28+
- MicaSense RedEdge
29+
- DJI Phantom 4 MS
30+
31+
### Advanced processing capabilities:
32+
- Configurable band thresholds
33+
- Pixel buffering around glint areas
34+
- Parallel processing for improved performance
35+
- Batch processing of multiple images
36+
37+
## System Requirements
38+
39+
- Operating Systems:
40+
- Windows 10 or later
41+
- Linux (modern distributions)
42+
- Python 3.9 - 3.12 (for CLI/Python package)
43+
- Minimum 4GB RAM
44+
- Storage space: 100MB + space for your imagery
45+
46+
## Interface Comparison
47+
48+
| Feature | GUI | CLI | Python Package |
49+
|--------------------------|------------------|--------------------|------------------|
50+
| Ease of Use | ★★★★★ | ★★★ | ★★★ |
51+
| Automation Support | ★ | ★★★★★ | ★★★★★ |
52+
| Integration Capabilities | ★ | ★★★★ | ★★★★★ |
53+
| Customization | ★ | ★★★ | ★★★★★ |
54+
| Learning Curve | Minimal | Moderate | Moderate |
55+
| Best For | Individual users | Automation/Scripts | Custom workflows |
56+
57+
## Next Steps
58+
59+
- [How it Works](how_it_works.md) - How glint masking works
60+
- [Installation Guide](installation.md) - Get started with installation
61+
- [Usage Guide](usage.md) - Learn how to use the tool
62+
- [FAQs](faq.md) - Answers to common questions
63+
64+
## License
65+
66+
GlintMaskGenerator is released under
67+
the [MIT license](https://raw.githubusercontent.com/tayden/GlintMaskGenerator/main/LICENSE.txt).
68+
69+
## Contribute
70+
71+
We welcome contributions! Please file bug reports, feature requests, or propose improvements using
72+
our [GitHub Issue Tracker :material-github:](https://github.com/HakaiInstitute/GlintMaskGenerator/issues).
73+
74+
<div style="margin-top: 50px; overflow: hidden; display: flex; justify-content:center; gap:10px;">
75+
<img alt="Hakai" src="./images/hakai_logo.png" width="30%" />
76+
</div>

‎docs/installation.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Installation and Updating
2+
3+
The library is currently available for Python versions 3.9 through 3.12. Support for
4+
future versions will be added when possible.
5+
6+
## GUI Tool
7+
8+
1. Go to the [releases page](https://github.com/HakaiInstitute/glint-mask-tools/releases)
9+
2. Download the latest release file for your operating system.
10+
3. Extract the compressed binary files from the gzipped archive.
11+
4. This archive contains a file named GlintMaskGenerator-v*.\*.\*.exe that provides a GUI interface to the glint mask generation program.
12+
5. You can copy these files to any location that is convenient for you.
13+
14+
## CLI Tool / Python Package
15+
16+
Installation of the CLI and Python tool are achieved using the Python package manager PIP.
17+
18+
### Installing
19+
20+
```bash
21+
pip install glint-mask-tools
22+
```
23+
24+
### Update
25+
26+
```bash
27+
pip install --upgrade glint-mask-tools
28+
```

‎docs/requirements.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
mkdocs-material==9.5.47
2+
mkdocstrings-python

‎docs/usage.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Usage
2+
3+
## General usage notes
4+
5+
### Accepted file types
6+
7+
- Supported file types are currently .jpg, .jpeg, .tif, .tiff, and .png (all are case-insensitive).
8+
9+
### Output files:
10+
11+
- Saved in the specified output directory
12+
- Named as original filename + "_mask" suffix and maintain the same file type as the input file
13+
- Example: `image1.jpg` → `image1_mask.jpg`
14+
- When processing multi-band imagery (e.g., Micasense RedEdge or P4MS), masks will be generated for all sibling band
15+
images.
16+
- This caters to the expectations of SfM software like Agisoft Metashape.
17+
18+
### Understanding Pixel Thresholds
19+
20+
Pixel thresholds determine how the software identifies glint in your imagery. The thresholds are specified as decimal
21+
values between 0.0 and 1.0, which are then applied to the full range of possible pixel values in your image.
22+
23+
#### How Thresholds Work
24+
25+
For example, in an 8-bit image (pixel values 0-255):
26+
27+
- A threshold of 0.5 means: pixel value > (0.5 × 255) = 127
28+
- A threshold of 0.875 means: pixel value > (0.875 × 255) = 223
29+
30+
#### Multiple Band Behavior
31+
32+
When multiple bands are present (like in RGB images):
33+
34+
1. Each band is checked against its respective threshold
35+
2. If ANY band exceeds its threshold, that pixel is marked as glint
36+
3. The resulting masks are combined using a union operation
37+
38+
#### Example
39+
40+
For an RGB image with thresholds:
41+
42+
- Blue: 0.875 (triggers at values > 223)
43+
- Green: 1.000 (never triggers)
44+
- Red: 1.000 (never triggers)
45+
46+
A pixel will be marked as glint if its blue value exceeds 223, regardless of its red and green values.
47+
48+
## Interfaces
49+
50+
### GUI
51+
52+
The GUI version provides an intuitive interface for generating glint masks from imagery. Launch the application by
53+
double-clicking the executable file on Windows, or running `./GlintMaskGenerator` from the terminal on Linux.
54+
55+
#### Main Options
56+
57+
1. **Imagery Type Selection**
58+
- Choose the appropriate camera/sensor type for your imagery:
59+
- RGB: Standard RGB camera imagery
60+
- CIR: 4-band Color Infrared imagery
61+
- P4MS: DJI Phantom 4 Multispectral camera imagery
62+
- MicasenseRedEdge: Micasense RedEdge multispectral camera imagery
63+
64+
2. **Directory Selection**
65+
- Image Directory: Select the input folder containing your imagery files using the "..." button
66+
- Output Directory: Choose where the generated mask files will be saved
67+
68+
3. **Band Thresholds**
69+
- Adjust thresholds for each available band using the sliders
70+
- Range: 0.0 to 1.0 (higher values = less masking)
71+
- Default values:
72+
- Blue: 0.875
73+
- Green: 1.000
74+
- Red: 1.000
75+
- Red Edge: 1.000 (when applicable)
76+
- NIR: 1.000 (when applicable)
77+
- Use the "Reset all" button to restore default values
78+
79+
4. **Processing Options**
80+
- Pixel Buffer Radius: Adjusts the expansion of masked regions (default: 0)
81+
- Max Workers: Controls the number of parallel processing threads (default: 4)
82+
83+
5. **Processing**
84+
- Click "Run" to start generating masks
85+
86+
### CLI
87+
88+
For information about the parameters expected by the CLI, run glint-mask --help in a bash terminal or command line
89+
interface. All the functionality of the CLI is documented there.
90+
91+
```
92+
❯ glint-mask --help
93+
94+
Usage: glint-mask [OPTIONS] COMMAND [ARGS]...
95+
96+
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
97+
│ --install-completion Install completion for the current shell. │
98+
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
99+
│ --help Show this message and exit. │
100+
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
101+
╭─ Commands ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
102+
│ rgb-threshold Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm. │
103+
│ cir-threshold Generate masks for glint regions in 4 Band CIR imagery using Tom Bell's binning algorithm. │
104+
│ p4ms-threshold Generate masks for glint regions in multispectral imagery from the DJI camera using Tom Bell's algorithm on the Blue image band. │
105+
│ micasense-threshold Generate masks for glint regions in multispectral imagery from the Micasense camera using Tom Bell's algorithm on the blue image band. │
106+
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
107+
```
108+
109+
```
110+
# Get addition parameters for one of the cameras/methods available
111+
❯ glint-mask rgb-threshold --help
112+
113+
Usage: glint-mask rgb-threshold [OPTIONS] IMG_DIR OUT_DIR
114+
115+
Generate masks for glint regions in RGB imagery using Tom Bell's binning algorithm.
116+
117+
╭─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
118+
│ * img_dir PATH 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. [default: None] [required] │
119+
│ * out_dir PATH 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. [default: None] [required] │
120+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
121+
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
122+
│ --thresholds FLOAT The pixel band thresholds indicating glint. Domain for values is (0.0, 1.0). [default: 0.875, 1, 1, 1, 1] │
123+
│ --pixel-buffer INTEGER The pixel distance to buffer out the mask. [default: 0] │
124+
│ --max-workers INTEGER The maximum number of threads to use for processing. [default: 4] │
125+
│ --help Show this message and exit. │
126+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
127+
```
128+
129+
#### CLI Examples
130+
131+
```bash
132+
# Process RGB imagery directory with default parameters
133+
# - Uses default thresholds (Blue: 0.875, Green: 1.0, Red: 1.0)
134+
# - No pixel buffer
135+
# - 4 worker threads
136+
glint-mask rgb-threshold /path/to/dir/with/images/ /path/to/out_masks/dir/
137+
138+
# Process PhaseONE CIR imagery with custom settings
139+
# - Specify custom thresholds with --thresholds
140+
# - Add 2-pixel buffer with --pixel-buffer
141+
# - Use 8 worker threads with --max-workers
142+
glint-mask cir-threshold \
143+
--thresholds 0.8,0.9,0.9,0.9 \
144+
--pixel-buffer 2 \
145+
--max-workers 8 \
146+
/path/to/dir/with/images/ \
147+
/path/to/out_masks/dir/
148+
149+
# Process DJI P4MS imagery with minimal masking
150+
# - Higher thresholds mean less aggressive masking
151+
# - Useful for scenes with minimal glint
152+
glint-mask p4ms-threshold \
153+
--thresholds 0.95,1.0,1.0,1.0,1.0 \
154+
/path/to/dir/with/images/ \
155+
/path/to/out_masks/dir/
156+
157+
# Process Micasense RedEdge imagery with aggressive masking
158+
# - Lower thresholds mean more aggressive masking
159+
# - Larger pixel buffer for broader masked areas
160+
glint-mask micasense-threshold \
161+
--thresholds 0.8,0.9,0.9,0.9,0.9 \
162+
--pixel-buffer 5 \
163+
/path/to/dir/with/images/ \
164+
/path/to/out_masks/dir/
165+
```
166+
167+
### Python Library
168+
169+
Installing the PyPi package allows integrating the mask generation workflow into existing python scripts with ease.
170+
171+
```py
172+
from glint_mask_generator import MicasenseRedEdgeThresholdMasker
173+
174+
# Also available: P4MSThresholdMasker, RGBIntensityRatioMasker, RGBThresholdMasker
175+
176+
masker = MicasenseRedEdgeThresholdMasker(
177+
img_dir="path/to/micasense/images/",
178+
mask_dir="path/to/output/dir/",
179+
thresholds=(0.875, 1, 1, 1, 1),
180+
pixel_buffer=5
181+
)
182+
masker.process(max_workers=5, callback=print, err_callback=print)
183+
```

0 commit comments

Comments
 (0)