v2.1.1

v2.1.1 – Docs overhaul, multispectral + predict/outputs upgrades, CI refresh

Compare: v2.0.1...v2.1.1
Stats: 53 commits · 40 files · +2,918 / −2,126 LOC

Highlights

• Multispectral support in prediction/training: predict.py now reads .tif stacks via rasterio and handles H×W×C ordering; training docs cover MS workflows.
• Smarter crown de-overlap (clean_crowns): rewritten around spatial join + union-find clustering; more robust, faster on big scenes.
• Docs: major restructure: new tutorial series, API reference, and an HPC/cluster guide; docs build is more reliable via mocked heavy deps.
• CI refresh: runners moved to Ubuntu 22.04, pin/upgrade key pieces (GDAL in CI, NumPy bound for tests), and a cleaner Sphinx workflow with gh-pages deploy.
• Dependency modernisation: shapely ≥2, geopandas/rasterio/fiona ranges updated; stale geospatial deps removed.

New / Improved

Models & pipeline

• predict.py

  • Accepts .png (RGB via OpenCV) and .tif (multispectral via rasterio).
  • Safer filename handling and JSON output naming.
  • Clearer logging and mode detection via get_filenames(...).

• outputs.py

  • New clean_crowns algorithm:

    • bbox-based spatial join to find candidates;
    • union-find to cluster overlaps by IoU;
    • keep best per cluster by field (default Confidence_score);
    • filters invalid/empty geometry; configurable area_threshold (now default 2 m²).

• evaluation.py

  • More robust geometry ops:

    • handles GEOSException, uses make_valid fallback;
    • consistent union_area/IoU computation;
    • safer handling of test/pred file naming.

• train.py

  • Large update (see docs): clarified config path, support surfaced for MS training, early-stopping usage, and advanced options captured in docs.

Documentation

• Restructure

  • New docs/source/tutorials/ series:

    • 01_getting_started, 02_data_preparation, 03_training_and_evaluation,
    • 04_prediction, 05_advanced_topics.

  • API reference via sphinx-apidoc (docs/source/api.rst).

  • Cluster/HPC guide with CSD3 examples and GPU setup (cluster.rst).

• Build reliability

  • conf.py: add repo root to sys.path; mock heavy deps (torch, detectron2, rasterio, geopandas, shapely, etc.) so docs build without native libs.
  • release string set to 2.1.1.
  • docs/requirements.txt added.

• Model garden

  • Updated Zenodo links; added notes for 230717_base, 230729_05dates, and 250312_flexi; example wget commands updated.

Continuous Integration

• python-ci.yml

  • Runner: ubuntu-22.04.
  • GDAL in CI from 3.6.4; explicit numpy>=1.20,<2.0 for tests; add pytest-order.
  • Keep flake8 erroring on syntax/undefined names; soften general run with --exit-zero for metrics only.

• sphinx-ci.yml

  • Renamed to “Sphinx Documentation”; runner ubuntu-22.04.
  • Streamlined: setup-python@v4, build, upload artifact (v4), and deploy to GitHub Pages on master.

Repo/Meta

• .gitattributes: make *.py detectable, ignore notebooks for linguist.
• New dark/light logos updated.
• README: contributors updated (incl. Christopher Kotthoff).

Removals / Potentially Breaking

• Removed data loaders:

  • detectree2/data_loading/gdrive.py
  • gdrivePull.sh
  • gee_download.py
  • quickstart.py

  If you relied on these, migrate to your own fetch scripts or keep them pinned at ≤ v2.0.1.

• Docs cleanup: legacy tutorial.rst and tutorial_multi.rst removed (replaced by new tutorial set).

Dependency changes (setup.py)

• Now requires

  • shapely>=2.0, geopandas>=0.13,
  • rasterio>=1.2,<1.4, fiona>=1.8,<1.10,
  • numpy>=1.20, pandas>=1.3, opencv-python>=4.5, tqdm>=4.60, pycocotools>=2.0.4,
  • detectron2 from GitHub.

• Removed: proj, geos, pygeos, pypng, pycrs, descartes, hard-pinned prerelease rasterio, etc.

Tests

• tests/test_preprocessing.py: updated expected ybox_coords (reflects tiling math tweak).

Upgrade notes

• If your environment is older (e.g., shapely <2), create a fresh venv and reinstall.
• For MS .tif predictions, ensure rasterio can open your imagery and that channel order matches expectations.
• The new clean_crowns defaults are stricter (area_threshold=2). If you need tiny crowns, lower that or post-filter by Confidence_score.

Contributors

Thanks to everyone who pushed on CI, docs, MS support, and the crown cleaning logic. Also updated contributor credits in README.

What's Changed

• Added Compute Cluster Guide by @ChristopherKotthoff in #154
• fixed the random rotation augmentation inconsistency by @ChristopherKotthoff in #155
• Fixed Layout for the Cluster Guide by @ChristopherKotthoff in #156
• Jb/dec24 by @PatBall1 in #158
• Github Workflow Fix (python-ci.yml) by @ChristopherKotthoff in #172
• [Re-Opened] Added Adaptive Tiling by @ChristopherKotthoff in #173
• Masks and Other Features for Tiling by @ChristopherKotthoff in #165
• Random Tiles Subset Generation by @ChristopherKotthoff in #166
• Additional Custom nodata-Values by @ChristopherKotthoff in #167
• Conversion of all Multispectral Tiles to the Range 0-255 by @ChristopherKotthoff in #168
• Overlapping Tiles - More Training Data by @ChristopherKotthoff in #169
• Fix typo in tutorial by @CiSong10 in #175
• visualization feature with clean_crowns bugfix by @ChristopherKotthoff in #179
• Weight Initialization for MS by repeating RGB Channel Weights in the First Layer by @ChristopherKotthoff in #170
• Create an RGB clone of a MS Tiles Folder by @ChristopherKotthoff in #180
• Ignoring certain Bands during the Tiling Process by @ChristopherKotthoff in #181
• Remove non-annotated image data from training-tiles by @ChristopherKotthoff in #182
• Fixing sphinx-ci Workflow + Optimization by @ChristopherKotthoff in #185
• Fixed failing Pytest by @ChristopherKotthoff in #186
• Fix FileNotFoundError and shapely.errors.GEOSException for models/evaluation.py by @CiSong10 in #187
• Jb/sept25 by @PatBall1 in #203
• Enhancing RGB Tile Contrast by @ChristopherKotthoff in #202
• Tutorial Modifications and Extension by @ChristopherKotthoff in #204

New Contributors

• @CiSong10 made their first contribution in #175

Full Changelog: v2.0.1...v2.1.1

v2.0.1

Bug fix to ensure prediction tiling works as intended

v2.0.0

Major changes and upgrades

Tiling

• Tiling now works with the path to the orthomosaic as an argument (rather than the orthomosaic). This will require previous scripts to be adjusted.
• Tiling is now parallelised rather than sequential. This should speed up the tiling process on multi-core systems.

Multispectral compatibility

• Tiling and training now works with MS imagery (as well as RGB) - this is described in the updated tutorial.
• There is no upper bound on the number of bands that can be used (except for memory limitations of the system) - this can mean additional spectral and non-spectral (e.g. CHM bands) can be stacked

Multi-class models

• The functionality of multi-class training has been upgraded - this is described in the updated tutorial
• It is now easier to train models to detect and classify trees of different types (e.g. species, liana infestations)
• A "class mapping" is generated at the tiling stage and carried throughout the training and prediction stages

Please raise and issues you find with the new features and we will get them fixed ASAP.

v1.0.8

Models moved from repo to Zenodo to resolve bandwidth issues

v1.0.7

Multi-temporal prediction combination.
Multi-class outputs.

v1.0.6

Some changes to how the file paths are constructed in tile_data to allow more flexibility for non-conventional crs

v1.0.5

to_traintest_function tweaked to support cases where there is limited available data. It is now possible to not reserve any data for testing (keeping it all for training/validation). Through the strict argument it is also possible to control whether no overlap in the buffer of training/validation tiles and test tiles is enforced.

This flexibility should help users who have limited data to train on.

v1.0.4

Minor updates to the clean_crown function to help handle crs and indexing issues

v1.0.3

Some fixes to the tile_data_train function were implemented to stop misalignment on tiles along the edge of a raster scene

v1.0.2

Some cleaning of the repo to align with publication in Remote Sensing in Ecology and Conservation