HISTORY.md

DeepForest Changelog

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 (#1230)
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

---

Version 2.0.0 (Date: November 4, 2025)

The major innovations are:

1. Migration from albumentations to kornia for data augmentations - Replaced albumentations with kornia

• Migrated most transformations to kornia equivalents. See documentation for more information.
• albumentations dependency is removed.
• Most existing transformation types are supported with minimal changes to configuration needed.
• ZoomBlur and RandomPadTo augmentations added

Breaking Changes - Deprecated Items Removed:

• Albumentations' DownScale (down + upscale) is no longer supported. Users can use two Resize steps to mimic this, or RandomResizedCrop.

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:

• Augmentations: Update parameter names and use kornia transforms (see documentation)
• 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

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)

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

Version 1.5.2 (Date: Feb 7, 2025)

The major innovations are:

1. Improve Tests on edge cases

Additional features and enhancements include:

• Documentation: Improved documentation workflow and version available

Version 1.5.0 (Date: Jan 15, 2024)

The major innovations are:

1. Restructured package layout by moving code into src/ directory for better organization
2. Added batch prediction capabilities for improved processing of multiple images
3. Implemented support for image dataframes to allow more flexible input formats
4. Created plot_annotations method for better visualization of predictions
5. Added out-of-memory dataset sample for handling large datasets efficiently

Additional features and enhancements include:

• Enhancement: Reorganized package structure to follow modern Python packaging standards
• Enhancement: Enhanced test coverage for new features
• Enhancement: Improved code organization and maintainability
• Documentation: Added docformatter for consistent docstring formatting
• Documentation: Improved documentation clarity and organization
• Documentation: Added new contributor: Dingyi Fang

Version 1.4.1 (Date: Oct 26, 2024)

• Enhancement: Use GitHub Actions to publish the package.

Version 1.4.0 (Date: Oct 9, 2024)

The major innovations are:

1. New model loading framework using HuggingFace. DeepForest models are now available on HuggingFace. The models can be loaded using load_model() and used for inference.
2. An all-purpose read_file method is introduced to read annotations from various formats including CSV, JSON, and Pascal VOC.
3. The CropModel class is introduced to classify detected objects using a trained classification model. Use when a multi-class DeepForest model is not sufficiently flexible, such as when new data sources are used for fine-grained classification and class imbalance.
4. deepforest.visualize.plot_results is now the primary method for visualizing predictions. The function is more flexible and allows for customizing the plot using the supervision package.

Additional features and enhancements include:

• New Feature: A crop_raster function is introduced to crop a raster image using a bounding box.

• New Feature: Added beta support for multiple annotation types including point, box, and polygon.

• New Feature: Added support for learning rates scheduling using the torch.optim.lr_scheduler module. The learning rate scheduler can be specified in the configuration file.

• New Utility: Created utilities.download_ArcGIS_REST function to download tiles from the ArcGIS REST API (e.g., NAIP imagery).

• Enhancement: The training module better matches torchvision negative anchors format for empty frames.

• Deprecation: shapefile_to_annotations in deepforest/utilities.py is deprecated in favor of the more general read_file method.

• Deprecation: predict in deepforest/main.py. The return_plot argument is deprecated and will be removed in version 2.0. Use visualize.plot_results instead.

• Deprecation: predict_tile in deepforest/main.py. Deprecated arguments return_plot, color, and thickness will be removed in version 2.0.

• Deprecation: crop_function in deepforest/preprocess.py. The base_dir argument is deprecated and will be removed in version 2.0. Use save_dir instead.

• Deprecation: The deepforest.visualize.IoU_Callback for better alignment with the PyTorch Lightning API (see issue).

• Deprecation: deepforest.main.use_release and deepforest.main.use_bird_release are deprecated in favor of the new model loading framework, for example using deepforest.main.load_model("weecology/deepforest-bird").

Version 1.3.3 (Date: Mar 12, 2024)

• Enhancement: split_raster now allows annotations_file to be None, enabling flexibility during data preprocessing.

Version 1.3.0 (Date: Dec 3, 2023)

• Deprecation: Removed IoU_Callback for better alignment with the PyTorch Lightning API (see issue).
• Refactor: Evaluation code now leverages the PyTorch Lightning evaluation loop for result calculation during training.
• Refactor: Simplified image_callbacks by using predictions directly. No need to specify the root directory or CSV file, as the evaluation file is assumed.

Version 1.1.3 (Date: Nov 9, 2021)

• Enhancement: Added box coordinates to the evaluation results frame for better result tracking.

Version 1.1.2 (Date: Sep 30, 2021)

• Bug Fix: Fixed incorrect precision calculation in class_recall.csv when multiple classes were present.

Version 1.1.1 (Date: Sep 14, 2021)

• Update: project_boxes now includes output options for both predict_tile and predict_image.
• New Feature: Introduced annotations_to_shapefile, which reverses shapefile_to_annotations functionality. Thanks to @sdtaylor for this contribution.

Version 1.1.0 (Date: Aug 5, 2021)

1. Enhancement: Empty frames are now allowed by passing annotations with 0's for all coordinates. Example format:

   image_path, 0, 0, 0, 0, "Tree"
   

2. New Feature: Introduced check_release to reduce GitHub rate limit issues. When using use_release(), the local model will be used if check_release = False.

Version 1.0.9 (Date: Jul 14, 2021)

• Enhancement: Improved default dtype for Windows users, thanks to @ElliotSalisbury for the contribution.

Version 1.0.0 (Date: Jun 7, 2021)

• Major Update: Transitioned from TensorFlow to a PyTorch backend, enhancing performance and flexibility.

Version 0.1.34 (Date: )

• Optimization: Profiled dataset and evaluation code, significantly improving evaluation performance.

Version 0.1.30 (Date: )

• Bug Fix: Resolved issues to allow learning rate monitoring and decay based on val_classification_loss.