DeepForest

The deepforest package is organized into several subpackages and modules designed for tree detection and analysis.

Core Subpackages:

• deepforest.data: Handles data management.
• deepforest.datasets: Manages dataset loading and structures.

Key Functional Modules:

• deepforest.model: Contains model definitions and architectures.
• deepforest.predict: Provides tools for running inference/predictions on images.
• deepforest.preprocess: Includes functions for preparing images and data before processing.
• deepforest.evaluate: Tools for assessing model performance.
• deepforest.visualize: Utilities for visualizing detections and results.
• deepforest.IoU: Implementation of Intersection over Union (IoU) metrics.
• deepforest.callbacks: Support for training callbacks.
• deepforest.utilities: General helper functions.
• deepforest.main: Entry points for the package.

When implementing a custom model, you must adhere to specific tensor shapes and dictionary keys to remain compatible with DeepForest's training and inference pipelines.

Input Format

• Batch of images: The model must accept a list or batch of tensors in the format [channels, height, width].
• Channels: Standard models are trained on 3-band images, though check_model can be customized for other dimensions.

Output Format (Inference)

During inference, the model must return a List[Dict[Tensor]] (one dictionary per input image). Each dictionary must contain the following keys:

• boxes (FloatTensor[N, 4]): Predicted boxes in [x1, y1, x2, y2] format, where 0 <= x1 < x2 <= W and 0 <= y1 < y2 <= H.
• labels (Int64Tensor[N]): The predicted class labels for each detection.
• scores (Tensor[N]): The confidence scores for each detection.

Input Format (Training)

During training, the model expects both input tensors and a list of target dictionaries containing:

• boxes (FloatTensor[N, 4]): Ground-truth boxes in [x1, y1, x2, y2] format.
• labels (Int64Tensor[N]): Class labels for each ground-truth box.

The CropModel allows you to apply a secondary classification model to the bounding boxes predicted by an object detection model (like the 'tree' or 'bird' backbones). This decouples detection from classification, which is useful when you have detailed labels (like species or health) for only a subset of detected objects.

When using predict_tile or predict_image with a CropModel, the resulting DataFrame will include new columns: cropmodel_label and cropmodel_score alongside the original detection columns.

import pandas as pd
from deepforest import model
from deepforest import main as m
from deepforest.utilities import get_data

# Load data
df = pd.read_csv(get_data("testfile_multi.csv"))

# Initialize CropModel
crop_model = model.CropModel(num_classes=2)
# Or load existing weights: crop_model = model.CropModel.load_from_checkpoint(<path>)

m.create_trainer()
result = m.predict_tile(path=path, crop_model=crop_model)

The DeepForest data model is designed to facilitate tree detection and analysis using four core components:

1. Annotations as Dataframes: Annotations are stored in GeoPandas dataframes. Each row represents a single annotation with one geometry and one label. Every dataframe must include an image_path column (containing the basename of the image, not the full path) and a label column.
2. Shapely Geometries: Annotation geometry is stored as shapely objects, which allows for seamless conversion between Point, Polygon, and Box representations.
3. Image Coordinates: All annotations are expressed in image coordinates (pixels) rather than geographic coordinates. DeepForest provides utilities to convert geospatial data (like .shp or .gpkg) into this image-coordinate format.
4. Root Directory: A root_dir attribute is attached to the dataframe to specify the directory where the actual image files are stored.