DeepForest

https://github.com/weecology/deepforest
Admin
DeepForest is a Python package for training and predicting ecological objects in airborne imagery,...
Tokens:62,181
Snippets:776
Trust Score:9.4
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install and Run Tests Locally

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Install the project and run tests using pytest. Ensure you have the latest version installed.

```bash
pip install . --upgrade  # or python setup.py install
pytest -v
```

--------------------------------

### Install pre-commit

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Install the pre-commit tool if it's not already on your system. This is a prerequisite for managing code quality hooks.

```bash
pip install pre-commit
```

--------------------------------

### Install DeepForest with uv

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/index.md

Use this command to install the DeepForest package using uv.

```bash
uv add deepforest
```

--------------------------------

### Install DeepForest from GitHub using uv

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/install.md

Installs DeepForest directly from its GitHub repository using uv. This is useful for installing the latest development version.

```bash
uv add "deepforest @ git+https://github.com/weecology/deepforest"
```

--------------------------------

### CropModel Configuration Example

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Example `config.json` for a user-trained CropModel. It includes essential fields like `label_dict`, `architecture`, and `balance_classes`, along with training parameters.

```json
{
  "cropmodel": {
    "architecture": "resnet18",
    "label_dict": {"ClassA": 0, "ClassB": 1},
    "balance_classes": false,
    "batch_size": 4,
    "num_workers": 0,
    "lr": 0.0001,
    "resize": [224, 224],
    "resize_interpolation": "bilinear",
    "expand": 0,
    "scheduler": {
      "type": "ReduceLROnPlateau",
      "params": {
        "mode": "min",
        "factor": 0.5,
        "patience": 5,
        "threshold": 0.0001,
        "threshold_mode": "rel",
        "cooldown": 0,
        "min_lr": 0,
        "eps": 1e-08
      }
    }
  }
}
```

--------------------------------

### Install DeepForest

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/sample_test.ipynb

Install the DeepForest library from a local path. This command is typically run in a notebook environment.

```python
!pip install ../../ -U
```

--------------------------------

### Test Documentation Locally

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Build and test the documentation locally by navigating to the docs directory, installing the project, and running make commands.

```bash
cd docs  # Go to the docs directory and install the current changes.
pip install ../ -U
make clean  # Run
make html  # Run
```

--------------------------------

### Install pre-commit Hooks

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Set up the pre-commit hooks in your local repository to enforce code quality and style checks before each commit.

```bash
pre-commit install
```

--------------------------------

### Install Comet ML

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Installs the comet_ml library, which is used for experiment tracking and model logging.

```python
!pip install comet_ml

```

--------------------------------

### Install deepforestr R Package and DeepForest Python

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Installs the R package from GitHub and then installs the necessary Python environment and DeepForest package. Restart R after running these commands.

```R
devtools::install_github('weecology/deepforestr')
deepforestr::install_deepforest()
```

--------------------------------

### Install DeepForest with pip

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/index.md

Use this command to install the DeepForest package from PyPI.

```bash
pip install deepforest
```

--------------------------------

### Example Output of Shapefile Boxes

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Sample output after reading shapefile bounding box annotations. Includes label, image path, and geometry.

```default
  label    image_path                                           geometry
0  Tree  OSBS_029.tif  POLYGON ((105.000 214.000, 95.000 214.000, 95....
1  Tree  OSBS_029.tif  POLYGON ((205.000 214.000, 195.000 214.000, 19...

```

--------------------------------

### Install DeepForest Locally

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Navigates into the cloned DeepForest directory and installs the library in editable mode. This allows for direct modifications to the library's code.

```python
%cd DeepForest
!pip install -e .
%cd ..

```

--------------------------------

### Install DeepForest from GitHub using pip

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/install.md

Installs DeepForest directly from its GitHub repository using pip. This is useful for installing the latest development version.

```bash
pip install git+https://github.com/weecology/DeepForest.git
```

--------------------------------

### Clone and Install DeepForest Locally using uv

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/install.md

Clones the DeepForest repository and installs it locally using uv. This method allows for local modifications and dependency management with uv.

```bash
git clone https://github.com/weecology/DeepForest.git
cd DeepForest
uv sync --all-extras --dev
```

--------------------------------

### Multi-class Transfer Learning Setup

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Adapt a pre-trained model to new classes by copying backbone and regression head weights. All layers will be trained.

```python
from deepforest import main

m = main.deepforest(
    num_classes=2,
    label_dict={"Alive": 0, "Dead": 1}
)

pretrained = main.deepforest()
pretrained.load_model(
    "weecology/deepforest-tree"
)

m.model.backbone.load_state_dict(
    pretrained.model.backbone.state_dict()
)
m.model.head.regression_head.load_state_dict(
    pretrained.model.head.regression_head.state_dict()
)

```

--------------------------------

### Verify DeepForest Installation

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Run this Python code snippet to confirm that DeepForest has been successfully installed and is importable.

```python
from deepforest import main
model = main.deepforest()
print("DeepForest successfully installed!")
```

--------------------------------

### Example Output of Shapefile Points

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Sample output after reading shapefile point annotations. Includes label, image path, and geometry.

```default
  label    image_path                 geometry
0  Tree  OSBS_029.tif  POINT (100.000 209.000)
1  Tree  OSBS_029.tif  POINT (200.000 209.000)

```

--------------------------------

### Example Output of CSV Boxes

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Sample output after reading CSV bounding box annotations. Includes geometry information.

```default
      image_path  xmin  ymin  xmax  ymax label                                           geometry
0   OSBS_029.tif   203    67   227    90  Tree  POLYGON ((227.000 67.000, 227.000 90.000, 203....
1   OSBS_029.tif   256    99   288   140  Tree  POLYGON ((288.000 99.000, 288.000 140.000, 256...
2   OSBS_029.tif   166   253   225   304  Tree  POLYGON ((225.000 253.000, 225.000 304.000, 16...
3   OSBS_029.tif   365     2   400    27  Tree  POLYGON ((400.000 2.000, 400.000 27.000, 365.0...
4   OSBS_029.tif   312    13   349    47  Tree  POLYGON ((349.000 13.000, 349.000 47.000, 312....

```

--------------------------------

### Python: Start Model Training

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Initiate the training process by calling the `fit` method on the PyTorch Lightning trainer with the DeepForest model object.

```python
m.trainer.fit(model)
```

--------------------------------

### DeepForest Configuration File Example

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/09_configuration_file.md

This is a sample configuration file for the DeepForest pytorch module, controlling various parameters for data loading, model architecture, training, validation, and prediction.

```yaml
# Config file for DeepForest pytorch module

# Cpu workers for data loaders
# Dataloaders
workers: 0
devices: auto
accelerator: auto
batch_size: 1

# Model Architecture
architecture: 'retinanet'
nms_thresh: 0.05
score_thresh: 0.1

# Set model name to None to initialize from scratch
model:
    name: 'weecology/deepforest-tree'
    revision: 'main'

# If this label dict is specified, and it differs
# from the model downloaded from the hub, the model
# will be updated to reflect the new class list. By
# default, this is blank and is populated when the
# model is loaded.
#
# label_dict:
#   Tree: 0
# num_classes: 1
#
label_dict:
num_classes:

# Pre-processing parameters
path_to_raster:
patch_size: 400
patch_overlap: 0.05
annotations_xml:
rgb_dir:
path_to_rgb:

train:
    csv_file:
    root_dir:

    # Optimizer initial learning rate
    lr: 0.001
    scheduler:
        type:
        params:
            # Common parameters
            T_max: 10
            eta_min: 0.00001
            lr_lambda: "0.95 ** epoch"  # For lambdaLR and multiplicativeLR
            step_size: 30  # For stepLR
            gamma: 0.1  # For stepLR, multistepLR, and exponentialLR
            milestones: [50, 100]  # For multistepLR

            # ReduceLROnPlateau parameters (used if type is not explicitly mentioned)
            mode: "min"
            factor: 0.1
            patience: 10
            threshold: 0.0001
            threshold_mode: "rel"
            cooldown: 0
            min_lr: 0
            eps: 0.00000001

    # How many epochs to run for
    epochs: 1
    # Useful debugging flag in pytorch lightning, set to True to get a single batch of training to test settings.
    fast_dev_run: False
    # preload images to GPU memory for fast training. This depends on GPU size and number of images.
    preload_images: False

validation:
    csv_file:
    root_dir:
    preload_images: False
    size:

    # For retinanet you may prefer val_classification, but the default val_loss
    # should work with all models
    lr_plateau_target: val_loss

    # Intersection over union evaluation
    iou_threshold: 0.4
    val_accuracy_interval: 20

predict:
    pin_memory: False

cropmodel:
    batch_size: 4
    num_workers: 0
    lr: 0.0001
    scheduler:
        type: ReduceLROnPlateau
        params:
            mode: min
            factor: 0.5
            patience: 5
            threshold: 0.0001
            threshold_mode: rel
            cooldown: 0
            min_lr: 0
            eps: 1.0e-08
    balance_classes: False
    resize:
        - 224
        - 224

```

--------------------------------

### Development Installation with pip

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/install.md

Installs DeepForest in development mode with all dependencies, including those for documentation, using pip. This is for developers contributing to the project.

```bash
git clone https://github.com/weecology/DeepForest.git
cd DeepForest
pip install .'[dev,docs]'
```

--------------------------------

### Environment Setup for Slurm

Source: https://github.com/weecology/deepforest/blob/main/docs/development/cluster.md

Set up the Conda environment and navigate to the DeepForest directory. Ensure logs directory exists.

```bash
ml conda
eval "$(conda shell.bash hook)"
conda activate predict
cd /path/to/DeepForest
mkdir -p slurm_logs
```

--------------------------------

### Example Output of Shapefile Polygons

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Sample output after reading shapefile polygon annotations. Includes label, image path, and geometry in WKT format.

```default
  label    image_path                                           geometry
0  Tree  OSBS_029.png  POLYGON ((0.00000 0.00000, 0.00000 2.00000, 1....
1  Tree  OSBS_029.png  POLYGON ((2.00000 2.00000, 2.00000 4.00000, 3....

```

--------------------------------

### Clone and Install DeepForest Locally using pip

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/install.md

Clones the DeepForest repository and installs it locally using pip. This method allows for local modifications.

```bash
git clone https://github.com/weecology/DeepForest.git
cd DeepForest
pip install .
```

--------------------------------

### Install DeepForest with Development Dependencies using Pip

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Install the DeepForest package using Pip, including optional development and documentation dependencies specified in pyproject.toml.

```bash
pip install .'[dev,docs]'
```

--------------------------------

### Train the DeepForest Model in R

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Initializes the trainer and fits the model using the configured training parameters. This command starts the actual model training process.

```R
model$create_trainer()
model$trainer$fit(model)
```

--------------------------------

### Run pre-commit on All Files

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Execute all configured pre-commit hooks on every file in the repository. This is useful for an initial setup or a full project-wide check.

```bash
pre-commit run --all-files
```

--------------------------------

### Create and Use Virtualenv Environment with DeepForest

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Shows how to create a new virtualenv environment, install Python packages, and then activate it for use with reticulate in R.

```R
library(reticulate)
# create a new environment
virtualenv_create("name_of_environment")

# install Python packages
virtualenv_install("name_of_environment", "scipy", "deepforest")
use_virtualenv("name_of_environment")
```

--------------------------------

### Example Annotations CSV Format

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

This is an example of the expected format for the annotations CSV file used during training. It includes image paths and bounding box coordinates for detected objects.

```csv
image_path, xmin, ymin, xmax, ymax, label
OSBS_029.jpg,256,99,288,140,Tree
OSBS_029.jpg,166,253,225,304,Tree
OSBS_029.jpg,365,2,400,27,Tree
OSBS_029.jpg,312,13,349,47,Tree
OSBS_029.jpg,365,21,400,70,Tree
OSBS_029.jpg,278,1,312,37,Tree
OSBS_029.jpg,364,204,400,246,Tree
OSBS_029.jpg,90,117,121,145,Tree
OSBS_029.jpg,115,109,150,152,Tree
OSBS_029.jpg,161,155,199,191,Tree
```

--------------------------------

### Configure Distributed Training

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/07_scaling.md

Pass arguments to PyTorch Lightning's create_trainer for distributed training. This example configures 5 GPUs on a single node using DDP strategy.

```python
m.create_trainer(logger=comet_logger, accelerator="gpu", strategy="ddp", num_nodes=1, devices=devices)
```

--------------------------------

### Train DeepForest Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Starts the training process for the DeepForest model using the configured trainer and prints the training duration.

```python
# Start the training
start_time = time.time()
m.trainer.fit(m)
print(f"--- Training on GPU: {(time.time() - start_time):.2f} seconds ---")
```

--------------------------------

### Load Prebuilt Tree Crown Detection Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/02_prebuilt.md

Load the default prebuilt tree crown detection model from Hugging Face. This model is suitable as a starting point for further training.

```python
from deepforest import main

m = main.deepforest()
m.load_model(model_name="weecology/deepforest-tree")
```

--------------------------------

### Format for Negative Samples

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

This is a format example for creating negative samples by specifying an image path with zero bounding box coordinates and a 'Tree' label.

```text
image_path, xmin, ymin, xmax, ymax, label
myimage.png, 0,0,0,0,"Tree"
```

--------------------------------

### Create and Use Conda Environment with DeepForest

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Demonstrates creating a new conda environment, installing Python packages like SciPy and DeepForest, and then activating the environment for use within R.

```R
library(reticulate)
conda_create("name_of_environment")

# install Python packages e.g SciPy, deepforest
conda_install("name_of_environment", "scipy", "deepforest")
use_condaenv('name_of_environment')
```

--------------------------------

### Load Model and Predict Image with DeepForest

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/intro_tutorials/02_model_loader.md

Initializes the DeepForest model, loads a pretrained tree detection model from Hugging Face, predicts on a sample image, and plots the results. Ensure the necessary libraries are installed.

```python
from deepforest import main
from deepforest import get_data
from deepforest.visualize import plot_results
# Initialize the model class
model = main.deepforest()

# Load a pretrained tree detection model from Hugging Face
model.load_model(model_name="weecology/deepforest-tree", revision="main")

sample_image_path = get_data("OSBS_029.png")
img = model.predict_image(path=sample_image_path)
plot_results(img)
```

--------------------------------

### Install DeepForest Python Package

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Installs the DeepForest Python package into your preferred Python environment using pip. This is for users who already have a Python setup.

```bash
pip install DeepForest
```

--------------------------------

### Initialize, Train, and Validate Crop Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/03_cropmodels.md

This snippet shows the basic workflow for initializing a CropModel, setting up a trainer, loading data, and then training and validating the model. Ensure the 'path/to/train' and 'path/to/val' directories exist and contain your training and validation datasets.

```python
crop_model = CropModel(num_classes=2)

crop_model.create_trainer(
    max_epochs=10,
    accelerator="gpu",
    devices=1
)

crop_model.load_from_disk(
    train_dir="path/to/train",
    val_dir="path/to/val"
)

crop_model.trainer.fit(crop_model)

crop_model.trainer.validate(crop_model)

crop_model.trainer.save_checkpoint("model.ckpt")
```

--------------------------------

### Sample Tree Detection Output

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/intro_tutorials/load_sample_data.md

This is an example of the output format for bounding boxes returned by the `predict_image` function when detecting trees. It includes coordinates, label, confidence score, and the image path.

```text
>>> boxes
   xmin   ymin   xmax   ymax  label     score    image_path
0  330.0  342.0  373.0  391.0  Tree  0.802979  OSBS_029.png
1  216.0  206.0  248.0  242.0  Tree  0.778803  OSBS_029.png
2  325.0   44.0  363.0   82.0  Tree  0.751573  OSBS_029.png
3  261.0  238.0  296.0  276.0  Tree  0.748605  OSBS_029.png
4  173.0    0.0  229.0   33.0  Tree  0.738210  OSBS_029.png
5  258.0  198.0  291.0  230.0  Tree  0.716250  OSBS_029.png
6   97.0  305.0  152.0  363.0  Tree  0.711664  OSBS_029.png
7   52.0   72.0   85.0  108.0  Tree  0.698782  OSBS_029.png
```

--------------------------------

### DeepForest CLI Prediction with Custom Configuration

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/16_prediction.md

Example of running a prediction using the DeepForest CLI, specifying an output file, and overriding configuration parameters like patch size and overlap using Hydra's format.

```bash
deepforest predict ./path/to/your/image.tif -o results.csv patch_size=250 patch_overlap=0.1
```

--------------------------------

### Retrieve Sample Image Path

Source: https://github.com/weecology/deepforest/blob/main/docs/getting_started/intro_tutorials/load_sample_data.md

Use the `get_data` helper function to get the path to a sample image file within the DeepForest data directory. This is useful for testing the package's functionality.

```python
from deepforest import get_data
# Retrieve sample image path
sample_image = get_data("OSBS_029.png")
print(sample_image)
# '[path]...../deepforest/data/OSBS_029.png'
```

--------------------------------

### Initialize and Predict with Crop Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/03_cropmodels.md

Demonstrates how to initialize a CropModel with a specified number of classes and use it for prediction on a tile. It also shows how to load a pre-trained model from a checkpoint.

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

df = pd.read_csv(get_data("testfile_multi.csv"))
crop_model = model.CropModel(num_classes=2)
# Or set up the crop model or load weights model.CropModel.load_from_checkpoint(<path>)

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

--------------------------------

### Initialize Multi-species Model with Generic Pretrained Weights

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/06_multi_species.md

Start a multi-species DeepForest model using generic pretrained weights (like MS-COCO) by setting the model name to None in config_args. This is useful when you want to train from scratch with custom weights and a specific number of classes.

```python
# If you'd prefer to start with generic pretrained weights (typically from MS-COCO):
m = main.deepforest(config_args={"model": {"name": None},
                                 "num_classes":2,
                                 "label_dict": {"Tree":0, "Dead":1}})
assert m.model.num_classes == 2
```

--------------------------------

### Python: Initialize and Configure Training

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

This Python snippet demonstrates how to initialize the DeepForest model, set training parameters like epochs and the annotation file path, and prepare the trainer.

```python
import os
from deepforest import main
from deepforest import get_data

# Example run with short training
annotations_file = get_data("testfile_deepforest.csv")

# Load the default model
m = main.deepforest()

m.config.train.epochs = 1
m.config.train.csv_file = annotations_file
m.config.train.root_dir = os.path.dirname(annotations_file)

m.create_trainer()
```

--------------------------------

### Initialize CropModel with Custom Resize

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/09_configuration_file.md

Instantiate the CropModel with custom image resize dimensions specified in config_args.

```python
from deepforest.model import CropModel

# Or use custom resize dimensions
crop_model = CropModel(config_args={"resize": [300, 300]})
```

--------------------------------

### Install Development Version of deepforestr

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/deepforestr.md

Installs the development version of the deepforestr R package directly from GitHub using the remotes package.

```R
remotes::install_github("weecology/deepforestr")
```

--------------------------------

### Train with Custom Configuration File

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Execute training using a custom configuration file specified via '--config-dir' and '--config-name'. This is the preferred method for repeatable training runs.

```bash
deepforest --config-dir /your/config/folder --config-name config_file_name train
```

--------------------------------

### Create and Upload User-Trained CropModel

Source: https://github.com/weecology/deepforest/blob/main/CONTRIBUTING.md

Create a `CropModel`, define its architecture and number of classes, set the `label_dict`, and then upload it to your Hugging Face username using `push_to_hub`. This method requires manual loading of trained weights before uploading.

```python
from deepforest.model import CropModel

crop_model = CropModel(config_args={"architecture": "resnet18"})
crop_model.create_model(num_classes=10)
# ... load your trained weights ...
crop_model.label_dict = {"SpeciesA": 0, "SpeciesB": 1}
crop_model.push_to_hub("your-username/cropmodel-yourmodel")
```

--------------------------------

### Example Validation Metrics Output

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/12_evaluation.md

This is an example output of the validation metrics, showing scores for classes, IoU, mAP, and various recall levels. These metrics are useful for tracking model performance during training.

```default
classes                    0.0
           iou              0.6305446564807566
        iou/cl_0            0.6305446564807566
           map              0.04219449311494827
         map_50             0.11141198128461838
         map_75            0.025357535108923912
        map_large                  -1.0
       map_medium           0.05097917467355728
      map_per_class                -1.0
        map_small                   0.0
          mar_1            0.008860759437084198
         mar_10             0.03417721390724182
         mar_100            0.08481013029813766
    mar_100_per_class              -1.0
        mar_large                  -1.0
       mar_medium           0.09436620026826859
        mar_small                   0.0
   val_bbox_regression      0.5196723341941833
   val_classification       0.4998389184474945
```

--------------------------------

### Get Box Recall

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Retrieves the box recall metric from the model evaluation results.

```python
results["box_recall"]
```

--------------------------------

### Get Box Precision

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Retrieves the box precision metric from the model evaluation results.

```python
results["box_precision"]
```

--------------------------------

### View Available Configuration Options

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Run 'deepforest config' to inspect the current configuration and available parameters for training. This command helps in understanding how to override settings.

```bash
deepforest config
```

--------------------------------

### Fine-tune DeepForest Model for Bird Detection

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/Bird_FineTuning.ipynb

Fine-tunes a pre-trained DeepForest model for bird detection. Key parameters include learning rate and epochs. This snippet configures the model, sets up a Comet logger, and starts the training process. It's recommended to test learning rates carefully, with 0.0001 often being a good starting point.

```python
%timeit

# Comment out if comet-ml is not installed

comet_logger = CometLogger()

# Just reload here to make sure we are starting from the same model
model = main.deepforest()
model.load_model("weecology/deepforest-bird")

model.config["train"]["csv_file"] = "data/DeepWaterHorizon/train_annotations.csv"
model.config["train"]["root_dir"] = "data/DeepWaterHorizon"
model.config["validation"]["csv_file"] = "data/DeepWaterHorizon/test_annotations.csv"
model.config["validation"]["root_dir"] = "data/DeepWaterHorizon"
model.config["validation"]["val_accuracy_interval"] = 2
model.config["train"]["epochs"] = 20
model.config["train"]["lr"] = 0.00001

# Train model for just a few steps for show on cpu (model.create_trainer(max_steps=5)), takes 1 min on GPU
model.create_trainer(logger=comet_logger)
model.trainer.fit(model)
```

--------------------------------

### Get Scheduler Type

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Retrieves the configured learning scheduler type from the model's configuration.

```python
m.config["train"]["scheduler"]["type"]
```

--------------------------------

### CSV Data Format for Points

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Example of CSV format for point annotations. Includes x, y coordinates and a label.

```default
x,y,label
10,20,Tree
15,30,Tree
```

--------------------------------

### Initialize CropModel with Default Resize

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/09_configuration_file.md

Instantiate the CropModel using default image resize dimensions (224x224).

```python
from deepforest.model import CropModel

# Use default 224x224 resize
crop_model = CropModel()
```

--------------------------------

### Configure and Train Multi-species Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/06_multi_species.md

Set up the training and validation parameters, including dataset paths and batch size, and then initiate the training process for a multi-species DeepForest model. Ensure 'fast_dev_run' is set to True for quick testing.

```python
m.config["train"]["csv_file"] = get_data("testfile_multi.csv")
m.config["train"]["root_dir"] = os.path.dirname(get_data("testfile_multi.csv"))
m.config["train"]["fast_dev_run"] = True
m.config["batch_size"] = 2

m.config["validation"]["csv_file"] = get_data("testfile_multi.csv")
m.config["validation"]["root_dir"] = os.path.dirname(get_data("testfile_multi.csv"))
m.config["validation"]["val_accuracy_interval"] = 1

m.create_trainer()
m.trainer.fit(m)
```

--------------------------------

### Manually Set Release Version

Source: https://github.com/weecology/deepforest/blob/main/docs/development/contributing.md

Use bump-my-version to manually set a specific release version number, for example, to '1.4.0'.

```bash
bump-my-version bump --new-version 1.4.0
```

--------------------------------

### Train DeepForest Model via Command Line

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Initiate model training using the 'deepforest train' command, configuring parameters like batch size and dataset paths via command-line arguments.

```bash
deepforest train batch_size=8 train.csv_file=your_labels.csv train.root_dir=some/path
```

--------------------------------

### Initialize SGD Optimizer

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/09_configuration_file.md

Initializes the Stochastic Gradient Descent optimizer with momentum for model training. This is a common setup for deep learning optimization.

```python
from torch import optim

optim.SGD(self.model.parameters(), lr=self.config.train.lr, momentum=0.9)
```

--------------------------------

### Initialize Trainer and Load Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Creates a PyTorch Lightning trainer, disables validation sanity checks, and loads the latest release model.

```python
# create a pytorch lighting trainer used to training
# Disable the sanity check for validation data
m.create_trainer(logger=comet_logger, num_sanity_val_steps=0)
# load the lastest release model (RetinaNet)
m.load_model("weecology/deepforest-tree")
```

--------------------------------

### Train/Test with Existing Dataloader

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/05_model_architecture.md

Demonstrates how to load an existing dataloader for training and evaluation. Ensure `create_trainer()` is called after reassigning or loading a custom dataloader.

```python
from deepforest import main

m = main.deepforest()
existing_loader = m.load_dataset(csv_file=m.config.train.csv_file,
                                root_dir=m.config.train.root_dir,
                                batch_size=m.config.batch_size)

# Can be passed directly to main.deepforest(existing_train_dataloader) or reassign to existing deepforest object
m.existing_train_dataloader_loader
m.create_trainer()
m.trainer.fit()
```

--------------------------------

### Initialize CropModel with Custom PyTorch Backbone

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/03_cropmodels.md

Use any PyTorch model as a backbone for the CropModel. Ensure the backbone is compatible with the expected input/output of the CropModel.

```python
from torchvision.models import resnet101

# Initialize with custom model
backbone = resnet101(weights='DEFAULT')
crop_model = CropModel(
    num_classes=2,
    model=backbone
)
```

--------------------------------

### Launch Cluster Prediction Test

Source: https://github.com/weecology/deepforest/blob/main/docs/development/cluster.md

Submit a pre-configured batch script to run a cluster prediction test. This is useful for verifying cluster setup.

```bash
sbatch src/deepforest/scripts/HPC/run_cluster_predict_test.sbatch
```

--------------------------------

### deepforest.preprocess.split_raster

Source: https://github.com/weecology/deepforest/blob/main/docs/source/deepforest.md

Splits a large raster into smaller patches for processing. It can optionally use annotations to guide the splitting process and can save the resulting patches.

```APIDOC
## deepforest.preprocess.split_raster(annotations_file=None, path_to_raster=None, numpy_image=None, root_dir=None, patch_size=400, patch_overlap=0.05, allow_empty=False, image_name=None, save_dir='.')

### Description
Split a large raster into smaller patches for processing.

### Parameters
#### Path Parameters
- **annotations_file** (str) - Optional - Path to annotations CSV or DataFrame with columns: image_path, xmin, ymin, xmax, ymax, label
- **path_to_raster** (str) - Optional - Path to raster file on disk
- **numpy_image** (array) - Optional - Numpy array in (channels, height, width) order
- **root_dir** (str) - Optional - Root directory for annotations file
- **patch_size** (int) - Optional - Size of square patches (default: 400)
- **patch_overlap** (float) - Optional - Overlap between patches (0-1) (default: 0.05)
- **allow_empty** (bool) - Optional - Include patches with no annotations (default: False)
- **image_name** (str) - Optional - Name for the raster image
- **save_dir** (str) - Optional - Directory to save patches (default: '.')

### Returns
- **DataFrame or list** - DataFrame with annotations for training, or list of patch filenames
```

--------------------------------

### Instantiate and Load Custom Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/04_extending_module.md

Instantiate the custom module and load a pre-trained model. This demonstrates how to use the extended class with a specific model release.

```python
m = mymodule()
m.load_model("weecology/deepforest-tree")

```

--------------------------------

### Load Pretrained Backbone for Multi-species Training

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/06_multi_species.md

Initialize a DeepForest model using a pre-built model's backbone (e.g., 'weecology/deepforest-tree') while customizing the classification head for a specific number of species and their labels. This approach allows the model to leverage learned features while focusing on new classification tasks.

```python
import os
from deepforest import main
from deepforest import get_data

# Initialize new Deepforest model ( the model that you will train ) with your classes.
#
# When you override the number of classes and label_dict, deepforest will
# automatically modify the pretrained model to have the correct classification head
# structure, while keeping the backbone the same.
m = main.deepforest(config_args={"model": {"name": "weecology/deepforest-tree"}, # or 'weecology/deepforest-bird'
                                 "num_classes":2,
                                 "label_dict": {"Alive":0, "Dead":1}})
assert m.model.num_classes == 2
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/weecology/deepforest/blob/main/docs/development/contributing.md

Execute pre-commit checks manually to verify code quality and style. Use '--all-files' to check the entire repository or omit it to check only staged files.

```bash
pre-commit run --all-files
```

```bash
pre-commit run
```

```bash
pre-commit run ruff
```

--------------------------------

### Read Raster and Get Shape

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

This snippet demonstrates how to open a raster file using rasterio and check its shape. It includes a warning for non-georeferenced datasets.

```default
"""Split raster into crops with overlaps to maintain all annotations"""
raster = get_data("2019_YELL_2_528000_4978000_image_crop2.png")
import rasterio
src = rasterio.open(raster)
/Users/benweinstein/.conda/envs/DeepForest/lib/python3.9/site-packages/rasterio/__init__.py:220: NotGeoreferencedWarning: Dataset has no geotransform, gcps, or rpcs. The identity matrix be returned.
  s = DatasetReader(path, driver=driver, sharing=sharing, **kwargs)
src.read().shape
(3, 2472, 2299)
```

--------------------------------

### Initialize Comet Logger

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Initializes the CometLogger with a specified project name and the retrieved API key. This logger will track experiments and model performance.

```python
# change the project_name
comet_logger = CometLogger(project_name="temporary2", api_key=api_key)

```

--------------------------------

### Launch Cluster Tile Prediction Test

Source: https://github.com/weecology/deepforest/blob/main/docs/development/cluster.md

Submit a batch script to test tiled prediction on a cluster. This is for verifying large raster processing setup.

```bash
sbatch src/deepforest/scripts/HPC/run_cluster_predict_tile_test.sbatch
```

--------------------------------

### Configure DeepForest Model

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/examples/nest_detection.ipynb

Initializes the DeepForest model and configures training parameters, including label dictionary, number of classes, GPUs, and file paths.

```python
# initialize the model and change the corresponding config file
m = main.deepforest(config_args={"label_dict": {"Nest": 0}, "num_classes": 1})

# move to GPU and use all the GPU resources
m.config["gpus"] = "-1"
m.config["train"]["csv_file"] = annotations_file
m.config["train"]["root_dir"] = os.path.dirname(annotations_file)

# Define the learning scheduler type
m.config["train"]["scheduler"]["type"] = "cosine"
m.config["score_thresh"] = 0.4
m.config["train"]["epochs"] = 10
m.config["validation"]["csv_file"] = validation_file
m.config["validation"]["root_dir"] = os.path.dirname(validation_file)
```

--------------------------------

### Example Output of Shapefile Boxes with Projected Coordinates

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Sample output of reading a shapefile with projected coordinates. Coordinates are made relative to the image origin upon reading.

```default
gdf.iloc[0]
geometry      POLYGON ((404222.4 3285121.5, 404222.4 3285122...
label                                                      Tree
image_path    /Users/benweinstein/Documents/DeepForest/deepf...
Name: 0, dtype: object
```

--------------------------------

### CSV Data Format for Polygons

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Example of CSV format for polygon annotations. Polygons are expressed in Well-Known Text (WKT) format, along with a label and image path.

```default
"POLYGON ((0 0, 0 2, 1 1, 1 0, 0 0))",Tree,OSBS_029.png
"POLYGON ((2 2, 2 4, 3 3, 3 2, 2 2))",Tree,OSBS_029.png
```

--------------------------------

### CSV Data Format for Boxes

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/01_Reading_data.md

Example of CSV format for bounding box annotations. Includes image path, coordinates (xmin, ymin, xmax, ymax), and label.

```default
image_path,xmin,ymin,xmax,ymax,label
OSBS_029.tif,203,67,227,90,Tree
OSBS_029.tif,256,99,288,140,Tree
OSBS_029.tif,166,253,225,304,Tree
OSBS_029.tif,365,2,400,27,Tree
OSBS_029.tif,312,13,349,47,Tree
OSBS_029.tif,365,21,400,70,Tree
OSBS_029.tif,278,1,312,37,Tree
OSBS_029.tif,364,204,400,246,Tree
```

--------------------------------

### Initialize Model for Training from Scratch

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/11_training.md

Set `model.name = None` to initialize a RetinaNet model ready for training. Always specify `num_classes` and `label_dict`.

```python
m = main.deepforest(config_args{"num_classes": 3,
                                "label_dict": {
                                    "Tree": 0,
                                    "Bird": 1,
                                    "Animal": 2
                                }
                                "model":{"name":None}})

```

--------------------------------

### Get Box Precision Score

Source: https://github.com/weecology/deepforest/blob/main/docs/user_guide/12_evaluation.md

This retrieves the box precision score from the evaluation results. Precision is defined as the proportion of predicted boxes that overlap with a ground truth box.

```default
results["box_precision"]
0.781
```
Tokens:
Raw