Deepforest v2.1.0

Version 2.1.0 (Date: February 25, 2026)

The most important changes since 2.0.0:

1. Replace Albumentations with Kornia - Migrated augmentations to Kornia
2. CLI restructure - Split CLI into sub-scripts for clearer organization
3. Evaluation improvements - Refactored evaluation to support other geometries; migrated to torchmetrics
4. Prediction and training API - Simplified evaluation and prediction to mirror training; standardized train, eval and predict to accept lists not batches
5. Numpy 2.x support - Removed restriction to numpy<2.0
6. CropModel enhancements - Added macro-precision metric and expand context pixels for BoundingBoxDataset

Bug Fixes

• Fix: Image color format when saving; now uses PIL instead of OpenCV to preserve colors
• Fix: MultiImage dataset using same indices during batch processing
• Fix: evaluate_boxes TypeError when ground truth has non-default index
• Fix: DETR box coordinates
• Fix: Support empty annotations in image callback
• Fix: Detach losses when logging to avoid graph retention
• Fix: CropModel docstring to match __init__ signature

Features and Enhancements

• Config: Added log_root config option; improved config handling; serialize dictconfig as plain data
• read_file: Refactored for readability and to allow multiple image files; assume dataframe has root dir to simplify viz code
• Bounding boxes: Add validation checks for boxes outside image boundaries
• Compatibility: Block incompatible transformers versions; remove numpy<2.0 restriction
• CropModel: Add expand context pixels for BoundingBoxDataset via cropmodel.expand config

Internal / Developer

• Switch from tmpdir to tmp_path in tests
• Add white-image model inference test; add regression test for HuggingFace model label_dict loading
• Codecov test target and threshold; disable build failures from patch coverage diffs
• New contributing guidelines and dev guidelines

Deepforest v2.0.0

Version 2.0.0 (Date: November 4, 2025)

Breaking Changes - Deprecated Items Removed:

Removed Functions:

• xml_to_annotations() - Use utilities.read_pascal_voc(path) or the general utilities.read_file(path).
• boxes_to_shapefile() - Use image_to_geo_coordinates().
• project_boxes() - Use image_to_geo_coordinates().
• annotations_to_shapefile - Use image_to_geo_coordinates().
• plot_points() - Use plot_results
• draw_points() - Use plot_results
• plot_predictions() - Use plot_results
• draw_predictions() - Use plot_results
• use_release() - Use load_model('weecology/deepforest-tree') instead
• use_bird_release() - Use load_model('weecology/deepforest-bird') instead

Removed Parameters:

• geometry_type and save_dir from shapefile_to_annotations()
• num_classes and label_dict from deepforest() constructor - Use config file instead
• augment parameter from all functions - Use augmentations parameter instead
• raster_path parameter from predict_tile() - Use path parameter instead

Migration Guide:

• Replace xml_to_annotations(xml_path) with read_pascal_voc(xml_path)
• Replace boxes_to_shapefile(df, root_dir) with image_to_geo_coordinates(df, root_dir)
• Replace plot_points(image, points) with plot_results(results)
• Replace draw_points(image, points) with plot_results(results)
• Replace plot_predictions(image, df) with plot_results(results)
• Replace draw_predictions(image, df) with plot_results(results)
• Replace use_release() with load_model('weecology/deepforest-tree')
• Replace use_bird_release() with load_model('weecology/deepforest-bird')
• Use config file or config_args instead of constructor parameters
• Use augmentations parameter instead of augment parameter

---

Developer

Developer Workflow:

• Pre-commit workflow with Ruff, docformatter, and nbQA for automated code quality checks
• Editor integration recommendations (VS Code, PyCharm, Vim/Neovim)
• Comprehensive developer contributing guide

Infrastructure:

• Modernized pyproject.toml configuration with improved dependency management
• Better optional dependency handling (dev, docs)

Documentation:

• Enhanced Sphinx documentation with pydata theme
• Improved version switcher for release candidates
• ReadTheDocs integration with uv

Testing:

• Enhanced test coverage for edge cases
• Added comprehensive test suites for dataset handling, evaluation metrics, CLI functionality, model inference, and HuggingFace model loading

---

Features

Model Structure:

• Enhanced configuration handling via config file system
• Better separation of concerns between training and prediction modules
• Consistent type hints in BaseModel and model creation methods
• Improved model validation with check_model() method

Data Handling:

• Improved annotation reading with unified read_file() method
• Enhanced geometry type detection and conversion
• Better coordinate system handling (image ↔ geographic)

---

Enhancements

Installation & Packaging:

• Updated Python version requirement to 3.11+
• Removed conda support (package now only available via PyPI)
• Canonical PEP 440 versioning format implementation (e.g., 2.0.0rc1)

Testing & Evaluation:

• Improved evaluate_boxes() with better multi-class support
• Enhanced class recall and precision calculations
• Better handling of empty predictions and ground truth
• Improved point recall evaluation for point annotations

Documentation:

• Enhanced installation instructions (pip/uv focused)
• Better examples and tutorials
• Updated migration guides for deprecated features

deepforest 2.0.0rc2

DeepForest Changelog

Version 2.0.0rc2 (Date: October 23, 2025)

Internal / Developer Updates:

• Fixed publish pipeline issues
• No user-facing changes from 2.0.0rc1

Version 2.0.0rc1 (Date: October 21, 2025) (Additional)

Release Candidate 1 - Beta Release

Breaking Changes - Deprecated Items Removed:

Removed Functions:

• xml_to_annotations() - Use utilities.read_pascal_voc(path) or the general utilities.read_file(path).
• boxes_to_shapefile() - Use image_to_geo_coordinates().
• project_boxes() - Use image_to_geo_coordinates().
• annotations_to_shapefile - Use image_to_geo_coordinates().
• plot_points() - Use plot_results
• draw_points() - Use plot_results
• plot_predictions() - Use plot_results
• draw_predictions() - Use plot_results
• use_release() - Use load_model('weecology/deepforest-tree') instead
• use_bird_release() - Use load_model('weecology/deepforest-bird') instead

Removed Parameters:

• geometry_type and save_dir from shapefile_to_annotations()
• num_classes and label_dict from deepforest() constructor - Use config file instead
• augment parameter from all functions - Use augmentations parameter instead
• raster_path parameter from predict_tile() - Use path parameter instead

Migration Guide:

• Replace xml_to_annotations(xml_path) with read_pascal_voc(xml_path)
• Replace boxes_to_shapefile(df, root_dir) with image_to_geo_coordinates(df, root_dir)
• Replace plot_points(image, points) with plot_results(results)
• Replace draw_points(image, points) with plot_results(results)
• Replace plot_predictions(image, df) with plot_results(results)
• Replace draw_predictions(image, df) with plot_results(results)
• Replace use_release() with load_model('weecology/deepforest-tree')
• Replace use_bird_release() with load_model('weecology/deepforest-bird')
• Use config file or config_args instead of constructor parameters
• Use augmentations parameter instead of augment parameter

deepforest 2.0.0rc1

Version 2.0.0rc1 (Date: October 23, 2025)

Release Candidate 1 - Beta Release

Breaking Changes - Deprecated Items Removed:

Removed Functions:

• xml_to_annotations() - Use utilities.read_pascal_voc(path) or the general utilities.read_file(path).
• boxes_to_shapefile() - Use image_to_geo_coordinates().
• project_boxes() - Use image_to_geo_coordinates().
• annotations_to_shapefile - Use image_to_geo_coordinates().
• plot_points() - Use plot_results
• draw_points() - Use plot_results
• plot_predictions() - Use plot_results
• draw_predictions() - Use plot_results
• use_release() - Use load_model('weecology/deepforest-tree') instead
• use_bird_release() - Use load_model('weecology/deepforest-bird') instead

Removed Parameters:

• geometry_type and save_dir from shapefile_to_annotations()
• num_classes and label_dict from deepforest() constructor - Use config file instead
• augment parameter from all functions - Use augmentations parameter instead
• raster_path parameter from predict_tile() - Use path parameter instead

Migration Guide:

• Replace xml_to_annotations(xml_path) with read_pascal_voc(xml_path)
• Replace boxes_to_shapefile(df, root_dir) with image_to_geo_coordinates(df, root_dir)
• Replace plot_points(image, points) with plot_results(results)
• Replace draw_points(image, points) with plot_results(results)
• Replace plot_predictions(image, df) with plot_results(results)
• Replace draw_predictions(image, df) with plot_results(results)
• Replace use_release() with load_model('weecology/deepforest-tree')
• Replace use_bird_release() with load_model('weecology/deepforest-bird')
• Use config file or config_args instead of constructor parameters
• Use augmentations parameter instead of augment parameter

Pytorch release

This a major version change transition from tensorflow backend to pytorch. The pytorch backend was previously in a different repo and pypi package deepforest-pytorch. Continued tensorflow updates means that the pinned 1.14.0 version for keras-retinanet (which itself is deprecated) is a real risk to package longevity. To avoid needing to patch upstream dependencies we are deprecating the tensorflow backend and moving to pytorch. The release

model score is very close, within 1% of the tensorflow model, and we do not expect significant performance changes. Please see the README for links to updating code and please submit an issues you may have as we transition to 1.0.

This release is the same as https://github.com/weecology/DeepForest-pytorch/releases/tag/v0.1.17

Conda Version Distribution

This release is inline with the first release of the conda build. The prebuilt model has not changed from previous release.

21SiteModel

Model training parameters: https://www.comet.ml/bw4sz/deepforest/fabe532d9e5f4edaa98edf0d2c080011

red is the new release, blue the previous release. Recall and precision for each of the sites in the NeonTreeEvaluation Benchmark

> summary_statistics(results,method="all")
# A tibble: 2 x 3
  Method                mean_precision mean_recall
  <chr>                          <dbl>       <dbl>
1 Weinstein_unpublished          0.617       0.726
2 Weinstein2019                  0.567       0.645

https://github.com/weecology/NeonTreeEvaluation

Python Package

This is the first model version - corresponding to Weinstein et al. 2019. Four site NEON model (NIWO, TEAK, SJER, MLBS sites) with pretraining and hand-annotations.