fuelgauge 0.3.0__tar.gz

fuelgauge-0.3.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Shourya Mehta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Camera images, field samples and satellite data used by this project belong to
+their providers (PhenoCam Network, HPWREN, Globe-LFMC contributors, NASA, ESA,
+Copernicus) and are covered by their own terms; see README.md.

fuelgauge-0.3.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: fuelgauge
+Version: 0.3.0
+Summary: Turn any fixed camera into a calibrated sensor: pose from the skyline, decades of footage on one view, every pixel mapped to the ground.
+Author: Shourya Mehta
+License-Expression: MIT
+Project-URL: Homepage, https://shourya0mehta.github.io/fuel-gauge/
+Project-URL: Documentation, https://shourya0mehta.github.io/fuel-gauge/docs.html
+Project-URL: Source, https://github.com/shourya0mehta/fuel-gauge
+Project-URL: Research, https://shourya0mehta.github.io/fuel-gauge/research.html
+Keywords: computer-vision,camera-calibration,image-registration,wildfire,remote-sensing,viewshed,phenocam,geospatial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pillow>=10
+Provides-Extra: geo
+Requires-Dist: rasterio>=1.3; extra == "geo"
+Requires-Dist: pystac-client>=0.7; extra == "geo"
+Requires-Dist: planetary-computer>=1.0; extra == "geo"
+Provides-Extra: seg
+Requires-Dist: onnxruntime>=1.16; extra == "seg"
+Provides-Extra: eval
+Requires-Dist: scikit-learn>=1.3; extra == "eval"
+Requires-Dist: pyarrow>=14; extra == "eval"
+Requires-Dist: openpyxl>=3.1; extra == "eval"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://shourya0mehta.github.io/fuel-gauge/"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/banner.png" alt="fuelgauge: turn any fixed camera into a calibrated sensor" width="100%"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/tests.yml"><img src="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/site.yml"><img src="https://img.shields.io/badge/live_network-updated_daily-FF5B1F" alt="Live network updated daily"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-0E0E0E" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/runs_on-CPU-0E0E0E" alt="Runs on CPU">
+  <a href="https://github.com/shourya0mehta/fuel-gauge/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E0E0E" alt="MIT licence"></a>
+</p>
+
+<p align="center">
+  <a href="https://shourya0mehta.github.io/fuel-gauge/"><b>Website</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/docs.html"><b>Docs</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/research.html"><b>Research</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/#live"><b>Live network</b></a>
+</p>
+
+**Fuel Gauge is open-source computer vision that tells a camera exactly where it is looking.** It solves a camera's pose from the skyline alone, holds decades of footage on one fixed view, maps every pixel to a spot on the ground, and measures how the land changes. No survey, no ground control points, no hand-drawn masks, and it runs on a laptop.
+
+Thousands of cameras already watch wildland for fire. California alone runs 1,309 of them, each posting a frame a minute. To the software behind them a pixel is only a colour, with no distance and no place on a map. Fuel Gauge turns that colour into a measurement.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/console.gif" alt="A live HPWREN fire camera calibrated by Fuel Gauge: the skyline found in the photo locks onto the skyline the terrain predicts, then every point on the hillside reads out its distance, bearing, land cover and coordinates" width="90%"></p>
+<p align="center"><sub>A live HPWREN fire camera after calibration. Orange: the skyline Fuel Gauge found in the photo. Dashed: the skyline a 30 m terrain model predicts from the solved pose, 0.04° apart.</sub></p>
+
+## Highlights
+
+<table>
+  <tr>
+    <td align="center" width="33%"><h3>0.04°</h3><sub>median skyline error after solving a fire camera's pose from one photo</sub></td>
+    <td align="center" width="33%"><h3>29,047</h3><sub>photos from 21 cameras and 20 years locked onto fixed views</sub></td>
+    <td align="center" width="33%"><h3>1,309</h3><sub>California fire cameras audited for line of sight in one run</sub></td>
+  </tr>
+  <tr>
+    <td align="center" width="33%"><h3>1.4M acres</h3><sub>burned since 2020 by fires that started where no camera could see the smoke</sub></td>
+    <td align="center" width="33%"><h3>88%</h3><sub>of all burn area out of every camera's view that ten new cameras from the siting search would have seen</sub></td>
+    <td align="center" width="33%"><h3>8 cameras</h3><sub>calibrated, live, and measured every morning by GitHub Actions</sub></td>
+  </tr>
+</table>
+
+## Quickstart
+
+```bash
+pip install "fuelgauge[geo,seg]"
+
+# years of photos from one camera -> aligned views -> daily vegetation record
+fuelgauge run photos/ out/ridge
+
+# one frame + a location -> camera pose + pixel-to-ground lookup
+fuelgauge calibrate ridge frame.jpg --lat 33.4008 --lon -117.1905 --elev 483 --yaw 90
+
+# a list of camera sites -> what they can see, and where to add the next ones
+fuelgauge viewshed cameras.csv coverage.tif
+fuelgauge site cameras.csv --k 10 > new_sites.csv
+```
+
+Photo times are read from file names (ISO dates, PhenoCam and HPWREN naming) or EXIF, so most archives work as they are. Every step is also a Python function:
+
+```python
+from fuelgauge.archive import process
+from fuelgauge.measure import measure
+from fuelgauge import terrain, viewshed
+
+blocks = process(paths, times, "out/ridge")                  # align
+daily, regions, info = measure(blocks, "out/ridge")          # measure
+dem = terrain.load_planetary("cop-dem-glo-90", "data", 33.4, -117.2, 40000)
+picks = viewshed.site(dem, existing=[(33.40, -117.19)], k=5)  # site new cameras
+```
+
+Out come a daily GRVI/GCC record per view (`_daily.csv`), an image of the regions it measured (`_regions.png`), per-photo QA (`_qa.json`), a pixel-to-ground lookup (`_lookup.npz`) and a coverage GeoTIFF any GIS opens. Full guide and API reference: **[docs](https://shourya0mehta.github.io/fuel-gauge/docs.html)**.
+
+## How it works
+
+Five steps from raw footage to a calibrated sensor.
+
+| Step | What it solves | Under the hood |
+| --- | --- | --- |
+| **1. Align** <br><sub>`track`, `archive`</sub> | Cameras drift, get bumped, re-aimed and moved over the years | Frame screening (brightness, Laplacian sharpness, contrast, clipping); SIFT on CLAHE-equalised greyscale with Lowe's ratio test; 4-DOF similarity by RANSAC; keyframe tracking with relocalisation; loop closure through a maximum-inlier spanning tree; relocated cameras kept as second views; bump and re-aim detection |
+| **2. Calibrate** <br><sub>`terrain`, `camera`</sub> | Public cameras come with a location and nothing else | SegFormer-B2 sky segmentation (ONNX Runtime, CPU) to an edge-snapped skyline; terrain panorama ray-marched from Copernicus 30 m elevation with earth curvature and refraction; equidistant fisheye with one radial term; heading, tilt and roll by bounded Powell search on a trimmed loss; one lens fitted jointly across a network |
+| **3. Map** <br><sub>`terrain.backproject`</sub> | A measurement needs a place on the ground | Every pixel block's ray traced to its first terrain hit: distance, latitude, longitude, slope, aspect and ESA WorldCover land cover |
+| **4. Measure** <br><sub>`measure`, `quality`, `rois`, `colour`</sub> | Raw colour is mostly haze, weather and sensor drift | Haze scoring by Sobel edge correlation against a trailing norm; automatic regions from segmentation plus seasonal amplitude; drift-tracking von Kries white balance; GRVI, GCC and camera NDVI from near-infrared twins; causal smoothing that is safe to nowcast with |
+| **5. Scale** <br><sub>`viewshed`</sub> | Which ground a whole network can see, and where one more camera helps most | Radial viewsheds with curvature and refraction; smoke-column line of sight; greedy maximum-coverage siting over hilltop candidates |
+| **Evaluate** <br><sub>`evaluate`</sub> | Whether a camera signal knows anything the calendar does not | Leave-one-year-out ridge regression on a per-site, per-species seasonal baseline; held-out predictors clipped to the training range; RMSE, anomaly correlation and years beating season |
+
+27 tests run in CI on Python 3.10 and 3.12, covering synthetic drift, re-aims, relocations, terrain, viewsheds, siting, colour drift and leakage in the evaluation.
+
+## What we found with it
+
+Every result below was produced end to end by the pipeline on public data, and each has an interactive page on the **[research site](https://shourya0mehta.github.io/fuel-gauge/research.html)**.
+
+**A line-of-sight audit of California's fire cameras.** Fuel Gauge traced terrain line of sight from all 1,309 ALERTCalifornia cameras across the state and checked it against every wildfire from 2020 to 2025.
+
+- **46%** of California's wildland is in view of at least one camera, and **20%** of two, the overlap needed to triangulate smoke.
+- **21%** of the 277 fires over 1,000 acres started where no camera could see even a 300 m smoke column. Those fires, including the SCU Lightning Complex and the Claremont Fire, burned **1.4 million acres**.
+- A siting search over 11,847 hilltops finds ten new sites that add **9,332 km²** of watched wildland. Looking back, a different ten would have seen **1.31 million of the 1.48 million acres** that burned out of view.
+- The biggest blind spots: the Klamath Mountains, Yosemite's high country, the Modoc Plateau and the Diablo Range.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/coverage/ca_light.png" alt="California shaded by how many fire cameras can see each patch of wildland, with large fires since 2020 marked" width="60%"></p>
+
+**Twenty years of footage on one view.** 29,047 daily photos from 21 PhenoCam cameras in 6 states were locked onto fixed views, including six cameras that were moved to a new mast mid-record. Automatic regions beat the network's own hand-drawn masks at 12 of 20 cameras, and drift-tracking white balance lifts the year-to-year signal by 68%.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/hillside.gif" alt="Fifteen years of one hillside in the San Bernardino National Forest, every April and September, aligned onto one view" width="70%"></p>
+
+**A benchmark for camera fuel moisture.** The cameras were scored against 3,832 field samples of live fuel moisture, one held-out year at a time. Satellite shortwave infrared leads (anomaly correlation 0.31, ahead of season at 15 of 21 cameras), camera colour matches the seasonal baseline, and near-infrared camera NDVI adds little. That gives the field a clear target, and the harness ships with the package so the next signal can be scored the same way.
+
+**A live, calibrated fire-camera network.** Eight HPWREN cameras in Southern California, calibrated from their skylines with one shared lens (median error 0.04° to 0.17°). Every morning a GitHub Action pulls the latest frames, measures every ground block and publishes which slopes are drying fastest.
+
+## Scope and what's next
+
+- **The coverage audit shows the network at full reach.** Each site is treated as panning a full circle out to 30 km, so the gaps it finds are the floor: haze, night and where a camera happens to point only widen them. Next, per-camera aim from the live calibration.
+- **The fuel moisture benchmark is scored the hard way.** Field plots sit up to 25 km from each camera, often on another slope, and are sampled every two to four weeks. Any signal that holds up here is robust.
+- **Colour cameras see greenness; leaf water shows in shortwave infrared.** That is why satellite infrared leads, and why pairing camera timing with satellite infrared is the next step. The harness already scores combinations.
+- **The live network reports relative drying today** and is ready to score fuel moisture as soon as field plots sit close enough to its cameras.
+
+## Repository
+
+| Path | What it is |
+| --- | --- |
+| [`fuelgauge/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/fuelgauge) | The package and the `fuelgauge` command |
+| [`docs/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/docs) | The website: product page, docs (generated by `scripts/build_docs.py`), research pages and live data |
+| [`scripts/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/scripts) | The studies end to end: download, align, score, map, siting and site data |
+| [`live/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/live) | The daily updater for the calibrated HPWREN cameras, run by GitHub Actions |
+| [`study/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/study) | Camera list, per-camera results and coverage statistics |
+| [`tests/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/tests) | Synthetic cameras and terrain |
+
+<details>
+<summary><b>Reproduce the studies</b></summary>
+
+```bash
+pip install -e ".[geo,seg,eval,dev]"
+export DATA=data
+python scripts/fetch_lfmc.py                  # Globe-LFMC 2.0 field samples
+python scripts/fetch_phenocam.py              # midday photos for the cameras in study/cameras.json
+python scripts/fetch_modis.py                 # MODIS MCD43A4 at each camera view and sampling site
+python scripts/register_phenocam.py <camera>  # once per camera (STRIDE=2 keeps every other day)
+python scripts/fetch_nir.py <cam,cam,...>     # near-infrared twins + exposures for IR-capable cameras
+python scripts/nir.py <cam> ...               # camera NDVI on the registered regions
+python scripts/study.py && python scripts/timing.py && python scripts/summary.py
+python scripts/fetch_fires.py                 # NIFC WFIGS California wildfire ignitions
+python scripts/coverage.py && python scripts/siting.py && python scripts/coverage_report.py   # viewsheds, siting, stats, maps
+python scripts/build_site_data.py             # docs/data/ for the site
+```
+
+The full run downloads about 60,000 photos and takes a few hours on two CPU cores.
+</details>
+
+## Data and credits
+
+- **PhenoCam Network** (phenocam.nau.edu). Richardson et al. (2018), *Tracking vegetation phenology across diverse North American biomes using PhenoCam imagery*, Scientific Data 5:180028. Per-camera acknowledgements are in [study/ACKNOWLEDGEMENTS.md](https://github.com/shourya0mehta/fuel-gauge/blob/main/study/ACKNOWLEDGEMENTS.md).
+- **HPWREN** camera network, University of California San Diego (hpwren.ucsd.edu). Images courtesy of HPWREN.
+- **ALERTCalifornia** camera network (UC San Diego, with CAL FIRE): camera positions from the public camera map.
+- **Globe-LFMC 2.0**. Yebra et al. (2024), Scientific Data 11:332, compiled in part from the US National Fuel Moisture Database.
+- **MODIS MCD43A4 v6.1** (NASA LP DAAC), **Copernicus DEM GLO-30** (ESA) and **ESA WorldCover 2021**, through Microsoft Planetary Computer.
+- **SegFormer-B2** fine-tuned on ADE20K (NVIDIA), ONNX export by Xenova on Hugging Face.
+- **NIFC WFIGS** wildland fire incident locations (National Interagency Fire Center).
+- Camera NDVI method: Petach et al. (2014), *Monitoring vegetation phenology using an infrared-enabled security camera*, Agricultural and Forest Meteorology 195-196:143-151.
+
+Built by Shourya Mehta. To cite, see [CITATION.cff](https://github.com/shourya0mehta/fuel-gauge/blob/main/CITATION.cff).

fuelgauge-0.3.0/README.md

@@ -0,0 +1,159 @@
+<p align="center">
+  <a href="https://shourya0mehta.github.io/fuel-gauge/"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/banner.png" alt="fuelgauge: turn any fixed camera into a calibrated sensor" width="100%"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/tests.yml"><img src="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://github.com/shourya0mehta/fuel-gauge/actions/workflows/site.yml"><img src="https://img.shields.io/badge/live_network-updated_daily-FF5B1F" alt="Live network updated daily"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-0E0E0E" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/runs_on-CPU-0E0E0E" alt="Runs on CPU">
+  <a href="https://github.com/shourya0mehta/fuel-gauge/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E0E0E" alt="MIT licence"></a>
+</p>
+
+<p align="center">
+  <a href="https://shourya0mehta.github.io/fuel-gauge/"><b>Website</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/docs.html"><b>Docs</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/research.html"><b>Research</b></a> &nbsp;|&nbsp;
+  <a href="https://shourya0mehta.github.io/fuel-gauge/#live"><b>Live network</b></a>
+</p>
+
+**Fuel Gauge is open-source computer vision that tells a camera exactly where it is looking.** It solves a camera's pose from the skyline alone, holds decades of footage on one fixed view, maps every pixel to a spot on the ground, and measures how the land changes. No survey, no ground control points, no hand-drawn masks, and it runs on a laptop.
+
+Thousands of cameras already watch wildland for fire. California alone runs 1,309 of them, each posting a frame a minute. To the software behind them a pixel is only a colour, with no distance and no place on a map. Fuel Gauge turns that colour into a measurement.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/console.gif" alt="A live HPWREN fire camera calibrated by Fuel Gauge: the skyline found in the photo locks onto the skyline the terrain predicts, then every point on the hillside reads out its distance, bearing, land cover and coordinates" width="90%"></p>
+<p align="center"><sub>A live HPWREN fire camera after calibration. Orange: the skyline Fuel Gauge found in the photo. Dashed: the skyline a 30 m terrain model predicts from the solved pose, 0.04° apart.</sub></p>
+
+## Highlights
+
+<table>
+  <tr>
+    <td align="center" width="33%"><h3>0.04°</h3><sub>median skyline error after solving a fire camera's pose from one photo</sub></td>
+    <td align="center" width="33%"><h3>29,047</h3><sub>photos from 21 cameras and 20 years locked onto fixed views</sub></td>
+    <td align="center" width="33%"><h3>1,309</h3><sub>California fire cameras audited for line of sight in one run</sub></td>
+  </tr>
+  <tr>
+    <td align="center" width="33%"><h3>1.4M acres</h3><sub>burned since 2020 by fires that started where no camera could see the smoke</sub></td>
+    <td align="center" width="33%"><h3>88%</h3><sub>of all burn area out of every camera's view that ten new cameras from the siting search would have seen</sub></td>
+    <td align="center" width="33%"><h3>8 cameras</h3><sub>calibrated, live, and measured every morning by GitHub Actions</sub></td>
+  </tr>
+</table>
+
+## Quickstart
+
+```bash
+pip install "fuelgauge[geo,seg]"
+
+# years of photos from one camera -> aligned views -> daily vegetation record
+fuelgauge run photos/ out/ridge
+
+# one frame + a location -> camera pose + pixel-to-ground lookup
+fuelgauge calibrate ridge frame.jpg --lat 33.4008 --lon -117.1905 --elev 483 --yaw 90
+
+# a list of camera sites -> what they can see, and where to add the next ones
+fuelgauge viewshed cameras.csv coverage.tif
+fuelgauge site cameras.csv --k 10 > new_sites.csv
+```
+
+Photo times are read from file names (ISO dates, PhenoCam and HPWREN naming) or EXIF, so most archives work as they are. Every step is also a Python function:
+
+```python
+from fuelgauge.archive import process
+from fuelgauge.measure import measure
+from fuelgauge import terrain, viewshed
+
+blocks = process(paths, times, "out/ridge")                  # align
+daily, regions, info = measure(blocks, "out/ridge")          # measure
+dem = terrain.load_planetary("cop-dem-glo-90", "data", 33.4, -117.2, 40000)
+picks = viewshed.site(dem, existing=[(33.40, -117.19)], k=5)  # site new cameras
+```
+
+Out come a daily GRVI/GCC record per view (`_daily.csv`), an image of the regions it measured (`_regions.png`), per-photo QA (`_qa.json`), a pixel-to-ground lookup (`_lookup.npz`) and a coverage GeoTIFF any GIS opens. Full guide and API reference: **[docs](https://shourya0mehta.github.io/fuel-gauge/docs.html)**.
+
+## How it works
+
+Five steps from raw footage to a calibrated sensor.
+
+| Step | What it solves | Under the hood |
+| --- | --- | --- |
+| **1. Align** <br><sub>`track`, `archive`</sub> | Cameras drift, get bumped, re-aimed and moved over the years | Frame screening (brightness, Laplacian sharpness, contrast, clipping); SIFT on CLAHE-equalised greyscale with Lowe's ratio test; 4-DOF similarity by RANSAC; keyframe tracking with relocalisation; loop closure through a maximum-inlier spanning tree; relocated cameras kept as second views; bump and re-aim detection |
+| **2. Calibrate** <br><sub>`terrain`, `camera`</sub> | Public cameras come with a location and nothing else | SegFormer-B2 sky segmentation (ONNX Runtime, CPU) to an edge-snapped skyline; terrain panorama ray-marched from Copernicus 30 m elevation with earth curvature and refraction; equidistant fisheye with one radial term; heading, tilt and roll by bounded Powell search on a trimmed loss; one lens fitted jointly across a network |
+| **3. Map** <br><sub>`terrain.backproject`</sub> | A measurement needs a place on the ground | Every pixel block's ray traced to its first terrain hit: distance, latitude, longitude, slope, aspect and ESA WorldCover land cover |
+| **4. Measure** <br><sub>`measure`, `quality`, `rois`, `colour`</sub> | Raw colour is mostly haze, weather and sensor drift | Haze scoring by Sobel edge correlation against a trailing norm; automatic regions from segmentation plus seasonal amplitude; drift-tracking von Kries white balance; GRVI, GCC and camera NDVI from near-infrared twins; causal smoothing that is safe to nowcast with |
+| **5. Scale** <br><sub>`viewshed`</sub> | Which ground a whole network can see, and where one more camera helps most | Radial viewsheds with curvature and refraction; smoke-column line of sight; greedy maximum-coverage siting over hilltop candidates |
+| **Evaluate** <br><sub>`evaluate`</sub> | Whether a camera signal knows anything the calendar does not | Leave-one-year-out ridge regression on a per-site, per-species seasonal baseline; held-out predictors clipped to the training range; RMSE, anomaly correlation and years beating season |
+
+27 tests run in CI on Python 3.10 and 3.12, covering synthetic drift, re-aims, relocations, terrain, viewsheds, siting, colour drift and leakage in the evaluation.
+
+## What we found with it
+
+Every result below was produced end to end by the pipeline on public data, and each has an interactive page on the **[research site](https://shourya0mehta.github.io/fuel-gauge/research.html)**.
+
+**A line-of-sight audit of California's fire cameras.** Fuel Gauge traced terrain line of sight from all 1,309 ALERTCalifornia cameras across the state and checked it against every wildfire from 2020 to 2025.
+
+- **46%** of California's wildland is in view of at least one camera, and **20%** of two, the overlap needed to triangulate smoke.
+- **21%** of the 277 fires over 1,000 acres started where no camera could see even a 300 m smoke column. Those fires, including the SCU Lightning Complex and the Claremont Fire, burned **1.4 million acres**.
+- A siting search over 11,847 hilltops finds ten new sites that add **9,332 km²** of watched wildland. Looking back, a different ten would have seen **1.31 million of the 1.48 million acres** that burned out of view.
+- The biggest blind spots: the Klamath Mountains, Yosemite's high country, the Modoc Plateau and the Diablo Range.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/coverage/ca_light.png" alt="California shaded by how many fire cameras can see each patch of wildland, with large fires since 2020 marked" width="60%"></p>
+
+**Twenty years of footage on one view.** 29,047 daily photos from 21 PhenoCam cameras in 6 states were locked onto fixed views, including six cameras that were moved to a new mast mid-record. Automatic regions beat the network's own hand-drawn masks at 12 of 20 cameras, and drift-tracking white balance lifts the year-to-year signal by 68%.
+
+<p align="center"><img src="https://raw.githubusercontent.com/shourya0mehta/fuel-gauge/main/docs/assets/readme/hillside.gif" alt="Fifteen years of one hillside in the San Bernardino National Forest, every April and September, aligned onto one view" width="70%"></p>
+
+**A benchmark for camera fuel moisture.** The cameras were scored against 3,832 field samples of live fuel moisture, one held-out year at a time. Satellite shortwave infrared leads (anomaly correlation 0.31, ahead of season at 15 of 21 cameras), camera colour matches the seasonal baseline, and near-infrared camera NDVI adds little. That gives the field a clear target, and the harness ships with the package so the next signal can be scored the same way.
+
+**A live, calibrated fire-camera network.** Eight HPWREN cameras in Southern California, calibrated from their skylines with one shared lens (median error 0.04° to 0.17°). Every morning a GitHub Action pulls the latest frames, measures every ground block and publishes which slopes are drying fastest.
+
+## Scope and what's next
+
+- **The coverage audit shows the network at full reach.** Each site is treated as panning a full circle out to 30 km, so the gaps it finds are the floor: haze, night and where a camera happens to point only widen them. Next, per-camera aim from the live calibration.
+- **The fuel moisture benchmark is scored the hard way.** Field plots sit up to 25 km from each camera, often on another slope, and are sampled every two to four weeks. Any signal that holds up here is robust.
+- **Colour cameras see greenness; leaf water shows in shortwave infrared.** That is why satellite infrared leads, and why pairing camera timing with satellite infrared is the next step. The harness already scores combinations.
+- **The live network reports relative drying today** and is ready to score fuel moisture as soon as field plots sit close enough to its cameras.
+
+## Repository
+
+| Path | What it is |
+| --- | --- |
+| [`fuelgauge/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/fuelgauge) | The package and the `fuelgauge` command |
+| [`docs/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/docs) | The website: product page, docs (generated by `scripts/build_docs.py`), research pages and live data |
+| [`scripts/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/scripts) | The studies end to end: download, align, score, map, siting and site data |
+| [`live/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/live) | The daily updater for the calibrated HPWREN cameras, run by GitHub Actions |
+| [`study/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/study) | Camera list, per-camera results and coverage statistics |
+| [`tests/`](https://github.com/shourya0mehta/fuel-gauge/tree/main/tests) | Synthetic cameras and terrain |
+
+<details>
+<summary><b>Reproduce the studies</b></summary>
+
+```bash
+pip install -e ".[geo,seg,eval,dev]"
+export DATA=data
+python scripts/fetch_lfmc.py                  # Globe-LFMC 2.0 field samples
+python scripts/fetch_phenocam.py              # midday photos for the cameras in study/cameras.json
+python scripts/fetch_modis.py                 # MODIS MCD43A4 at each camera view and sampling site
+python scripts/register_phenocam.py <camera>  # once per camera (STRIDE=2 keeps every other day)
+python scripts/fetch_nir.py <cam,cam,...>     # near-infrared twins + exposures for IR-capable cameras
+python scripts/nir.py <cam> ...               # camera NDVI on the registered regions
+python scripts/study.py && python scripts/timing.py && python scripts/summary.py
+python scripts/fetch_fires.py                 # NIFC WFIGS California wildfire ignitions
+python scripts/coverage.py && python scripts/siting.py && python scripts/coverage_report.py   # viewsheds, siting, stats, maps
+python scripts/build_site_data.py             # docs/data/ for the site
+```
+
+The full run downloads about 60,000 photos and takes a few hours on two CPU cores.
+</details>
+
+## Data and credits
+
+- **PhenoCam Network** (phenocam.nau.edu). Richardson et al. (2018), *Tracking vegetation phenology across diverse North American biomes using PhenoCam imagery*, Scientific Data 5:180028. Per-camera acknowledgements are in [study/ACKNOWLEDGEMENTS.md](https://github.com/shourya0mehta/fuel-gauge/blob/main/study/ACKNOWLEDGEMENTS.md).
+- **HPWREN** camera network, University of California San Diego (hpwren.ucsd.edu). Images courtesy of HPWREN.
+- **ALERTCalifornia** camera network (UC San Diego, with CAL FIRE): camera positions from the public camera map.
+- **Globe-LFMC 2.0**. Yebra et al. (2024), Scientific Data 11:332, compiled in part from the US National Fuel Moisture Database.
+- **MODIS MCD43A4 v6.1** (NASA LP DAAC), **Copernicus DEM GLO-30** (ESA) and **ESA WorldCover 2021**, through Microsoft Planetary Computer.
+- **SegFormer-B2** fine-tuned on ADE20K (NVIDIA), ONNX export by Xenova on Hugging Face.
+- **NIFC WFIGS** wildland fire incident locations (National Interagency Fire Center).
+- Camera NDVI method: Petach et al. (2014), *Monitoring vegetation phenology using an infrared-enabled security camera*, Agricultural and Forest Meteorology 195-196:143-151.
+
+Built by Shourya Mehta. To cite, see [CITATION.cff](https://github.com/shourya0mehta/fuel-gauge/blob/main/CITATION.cff).

fuelgauge-0.3.0/fuelgauge/__init__.py

@@ -0,0 +1,17 @@
+"""fuelgauge: turn fixed outdoor cameras into georeferenced vegetation sensors.
+
+Modules
+    camera     fisheye camera model (pixel <-> azimuth/elevation)
+    terrain    DEM panoramas, skyline pose fitting, shared-lens network calibration, pixel -> ground
+    track      multi-year registration: keyframe tracking, segment linking (loop closure)
+    quality    frame screening and haze scoring
+    colour     block colours, GCC / GRVI, white balance, causal smoothing
+    rois       automatic measurement regions (no hand-drawn masks)
+    segment    SegFormer-B2 (ADE20K) sky / ground segmentation via ONNX Runtime
+    archive    end-to-end registration of a camera archive (photos -> registered block colours)
+    measure    registered blocks -> daily vegetation series: haze, automatic regions, white balance, smoothing
+    evaluate   leave-one-year-out comparison against field fuel moisture
+    viewshed   terrain line of sight, smoke-column visibility and greedy camera siting
+    sources    PhenoCam, HPWREN, Globe-LFMC, MODIS
+"""
+__version__ = "0.3.0"

fuelgauge-0.3.0/fuelgauge/archive.py

@@ -0,0 +1,100 @@
+"""Process a camera archive end to end: screen -> track -> link -> warp into each view -> block colours.
+
+A camera that was moved to a new spot gets a second view (its own anchor frame) instead of losing those years.
+Featureless scenes (open-grass close-ups) fragment into short stretches that cannot be joined; when fewer than
+half of the usable frames land in a view, every usable frame is measured in place, the way fixed PhenoCam
+regions are.
+
+    from fuelgauge.archive import process
+    out = process(sorted(glob('frames/*.jpg')), times, 'out/mycam')
+
+Writes <out>_blocks.npz (dates, per-block mean RGB, validity, haze score, segment) and <out>_qa.json.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+import numpy as np
+
+from . import quality, track as T
+from .colour import block_means
+
+W, H = 768, 576
+BLOCK = 24
+
+
+def _load(path, size=(W, H)):
+    import cv2
+    im = cv2.imread(path)
+    return None if im is None else cv2.resize(im, size, interpolation=cv2.INTER_AREA)
+
+
+def process(paths, times, out_prefix, log=print):
+    import cv2
+    matcher = T.Matcher()
+    sx = W / matcher.size[0]
+    recs = []
+
+    def frames():
+        for p, t in zip(paths, times):
+            img = _load(p)
+            if img is None:
+                recs.append(dict(file=os.path.basename(p), time=str(t), ok=False)); yield None, 0; continue
+            q = quality.screen(img)
+            recs.append(dict(file=os.path.basename(p), time=str(t), **q))
+            yield (img if q['ok'] else None), q['clarity']
+
+    res = T.track(frames(), matcher, progress=lambda k, s: log(f'track {k}/{len(paths)} segments {s}'))
+    import pandas as pd
+    n_ok = sum(1 for r in recs if r.get('ok'))
+    tt = pd.to_datetime(pd.Series(list(times)))
+    span_all = (tt.max() - tt.min()).days
+    # thresholds scale down for short archives
+    views = T.group_views(res, times, matcher, min_size=max(3, min(20, n_ok // 20)), min_frames=max(5, min(60, n_ok // 10)),
+                          min_span_days=min(300, span_all // 2))
+    n_view = sum(v['frames'] for v in views)
+    mode = 'registered'
+    if n_view < 0.5 * n_ok:
+        mode = 'in_place'
+        ok_idx = [k for k, r in enumerate(recs) if r.get('ok')]
+        anchor = max(ok_idx, key=lambda k: recs[k]['clarity'])
+        per_frame = [(0, T.I2) if k in set(ok_idx) else (None, None) for k in range(len(paths))]
+        anchors = [anchor]
+        log(f'only {n_view} of {n_ok} usable frames in a joined view: measuring in place')
+    else:
+        per_frame = []
+        for s_k, T_k in zip(res.seg, res.T):
+            v = next((i for i, vw in enumerate(views) if s_k in vw['to_view']), None)
+            per_frame.append((v, T.compose(T_k, views[v]['to_view'][s_k])) if (v is not None and T_k is not None) else (None, None))
+        anchors = [res.segments[v['anchor']].ref for v in views]
+        log(f'segments {len(res.segments)}, views {[sorted(v["to_view"]) for v in views]}')
+    view_imgs = [_load(paths[a]) for a in anchors]
+    view_edges = [quality.edge_map(v) for v in view_imgs]
+    dates, rgb, valid, haze, seg, view = [], [], [], [], [], []
+    for k, (p, (v, Tk)) in enumerate(zip(paths, per_frame)):
+        recs[k]['reg'] = Tk is not None
+        if Tk is None:
+            continue
+        Mf = Tk.copy(); Mf[:, 2] *= sx
+        img = _load(p)
+        warped = cv2.warpAffine(img.astype(np.float32), Mf, (W, H), flags=cv2.INTER_LINEAR, borderValue=(-1, -1, -1))
+        cover = warped[..., 0] >= 0
+        corr = quality.edge_agreement(np.clip(warped, 0, 255).astype(np.uint8), view_edges[v], cover)
+        mean, ok = block_means(np.where(cover[..., None], warped, 0)[..., ::-1], cover, BLOCK)
+        recs[k].update(edge_corr=corr, M=Mf.tolist(), tx=float(Mf[0, 2]), ty=float(Mf[1, 2]),
+                       scale=float(np.hypot(Mf[0, 0], Mf[1, 0])), seg=int(res.seg[k]), view=int(v))
+        dates.append(str(times[k])); rgb.append(mean.astype(np.float32)); valid.append(ok); haze.append(corr)
+        seg.append(int(res.seg[k])); view.append(int(v))
+    master, master_idx = view_imgs[0], anchors[0]
+    np.savez_compressed(f'{out_prefix}_blocks.npz', dates=np.array(dates), rgb=np.array(rgb), valid=np.array(valid),
+                        edge_corr=np.array(haze), seg=np.array(seg), view=np.array(view),
+                        masters=np.array([v[..., ::-1] for v in view_imgs]),
+                        master=master[..., ::-1], master_file=os.path.basename(paths[master_idx]))
+    sizes = np.bincount(res.seg[res.seg >= 0], minlength=len(res.segments)).tolist()
+    json.dump(dict(recs=recs, sizes=sizes, mode=mode,
+                   views=[] if mode == 'in_place' else [dict(anchor=int(v['anchor']), segments=sorted(int(s) for s in v['to_view']),
+                                                         links=[(int(a), int(b), int(n)) for a, b, n in v['links']]) for v in views]),
+              open(f'{out_prefix}_qa.json', 'w'))
+    log(f'{len(paths)} frames, {sum(r.get("ok", False) for r in recs)} pass checks, {len(dates)} registered')
+    return f'{out_prefix}_blocks.npz'

fuelgauge-0.3.0/fuelgauge/camera.py

@@ -0,0 +1,83 @@
+"""Camera model for fixed outdoor cameras: equidistant fisheye with one radial term.
+
+A pixel (u, v) maps to a viewing direction (azimuth, elevation) given
+    yaw    - azimuth of the optical axis, degrees clockwise from north
+    pitch  - tilt of the optical axis above the horizon, degrees
+    roll   - rotation about the optical axis, degrees
+    hfov   - angle spanned by the image half-width times two, in the undistorted model, degrees
+    k1     - radial term: off-axis angle = (r / f) * (1 + k1 * (r / f)^2)
+
+Wildfire cameras (Mobotix, Axis) are strongly barrel-distorted, so a pinhole model does not fit them.
+With k1 = 0 and a narrow field of view this reduces to a close approximation of a pinhole camera.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+import math
+import numpy as np
+
+
+@dataclass
+class Camera:
+    width: int
+    height: int
+    yaw: float = 0.0
+    pitch: float = 0.0
+    roll: float = 0.0
+    hfov: float = 100.0
+    k1: float = 0.0
+
+    @property
+    def focal(self) -> float:
+        """Pixels per radian of the undistorted angle."""
+        return (self.width / 2) / math.radians(self.hfov / 2)
+
+    def params(self) -> list[float]:
+        return [self.yaw, self.pitch, self.roll, self.hfov, self.k1]
+
+    def with_params(self, p) -> "Camera":
+        return Camera(self.width, self.height, *[float(x) for x in p])
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    # ------------------------------------------------------------------ pixel -> direction
+    def pixel_to_dir(self, u, v):
+        """Pixels -> (azimuth deg, elevation deg)."""
+        u = np.asarray(u, float); v = np.asarray(v, float)
+        dx = u - self.width / 2; dy = -(v - self.height / 2)
+        r = np.hypot(dx, dy) / self.focal
+        theta = r * (1 + self.k1 * r * r)
+        phi = np.arctan2(dy, dx)
+        x = np.sin(theta) * np.cos(phi); y = np.sin(theta) * np.sin(phi); z = np.cos(theta)
+        cr, sr = math.cos(math.radians(self.roll)), math.sin(math.radians(self.roll))
+        xr = cr * x - sr * y; yr = sr * x + cr * y
+        cp, sp = math.cos(math.radians(self.pitch)), math.sin(math.radians(self.pitch))
+        E = xr; N = z * cp - yr * sp; U = z * sp + yr * cp
+        az = (np.degrees(np.arctan2(E, N)) + self.yaw) % 360.0
+        el = np.degrees(np.arctan2(U, np.hypot(E, N)))
+        return az, el
+
+    # ------------------------------------------------------------------ direction -> pixel
+    def dir_to_pixel(self, az, el):
+        """(azimuth deg, elevation deg) -> pixels. Inverse of pixel_to_dir (Newton on the radial term)."""
+        az = np.radians(np.asarray(az, float) - self.yaw); el = np.radians(np.asarray(el, float))
+        E = np.cos(el) * np.sin(az); N = np.cos(el) * np.cos(az); U = np.sin(el)
+        cp, sp = math.cos(math.radians(self.pitch)), math.sin(math.radians(self.pitch))
+        z = N * cp + U * sp; yr = -N * sp + U * cp; xr = E
+        cr, sr = math.cos(math.radians(self.roll)), math.sin(math.radians(self.roll))
+        x = cr * xr + sr * yr; y = -sr * xr + cr * yr
+        theta = np.arccos(np.clip(z, -1, 1))
+        phi = np.arctan2(y, x)
+        r = theta.copy()
+        for _ in range(8):                               # solve r (1 + k1 r^2) = theta
+            f = r * (1 + self.k1 * r * r) - theta
+            r = r - f / (1 + 3 * self.k1 * r * r)
+        rad = r * self.focal
+        u = self.width / 2 + rad * np.cos(phi); v = self.height / 2 - rad * np.sin(phi)
+        return u, v
+
+    def effective_hfov(self) -> float:
+        """Real angular width across the image after distortion, degrees."""
+        r = math.radians(self.hfov / 2)
+        return 2 * math.degrees(r * (1 + self.k1 * r * r))