MegaDetector + SpeciesNet Workflow

This repository is a small working project for running wildlife detection and classification on folders of camera-trap images and videos.

AgentMorris

The original work comes from the excellent work of AgentMorris (Dan Morris) you can follow him for updates

https://github.com/agentmorris

https://github.com/agentmorris/MegaDetector

SpeciesNet

Thanks to Google for funding SpeciesNet and Dan Morris for being the primary contributor to the opensource repository.

https://github.com/google/cameratrapai

SnapShot Serengeti (T. Michael Anderson)

This particular repository is an adaptation of all the above mentioned work and represents the workflow that I adapted for Michael Anderson's Serengeti camera trap work at Wake Forest University.

https://www.tmandersonlab.com/

It is built around two models:

• MegaDetector for object detection
• SpeciesNet for taxonomic classification of MegaDetector crops

The repo contains a plain MegaDetector batch runner, a combined MegaDetector + SpeciesNet pipeline, and an EXIF-enabled variant that can preserve image timestamps in the final JSON output.

What This Project Is For

Use this project when you want to:

• run MegaDetector on a folder of images or videos
• classify detected animals with SpeciesNet
• reuse an existing MegaDetector JSON instead of rerunning detection
• include EXIF-derived image timestamps in the final output

The main practical output is a JSON file in MegaDetector-style format with added SpeciesNet classification fields.

Repository Contents

• run_detector_batch.py: local MegaDetector batch runner
• run_md_and_speciesnet.py: combined detection + classification pipeline
• run_md_and_speciesnet_exif.py: combined pipeline with optional EXIF timestamp extraction
• run_season.sh: simple shell workflow that runs detection first, then classification using an existing detections file
• total_detection.sh: simple shell wrapper around the EXIF-enabled combined pipeline
• RUN_MD_AND_SPECIESNET.md: detailed documentation for the original combined pipeline

How The Pipeline Works

The combined scripts follow this sequence:

1. Scan the source folder for images and optionally videos.
2. Run MegaDetector to produce bounding boxes.
3. For each above-threshold detection, crop and preprocess the region.
4. Run SpeciesNet on those crops.
5. Merge classification results back into the MegaDetector JSON.
6. Write a final combined results file.

For video inputs, MegaDetector operates on sampled frames. SpeciesNet classifications are attached to the detections associated with those frames.

Requirements

This project assumes:

• Python 3.11 is available
• the megadetector Python package and its internal modules are importable
• the speciesnet package is installed for classification
• model dependencies required by both packages are available in your environment

The shell scripts in this repository assume a local virtual environment at:

./.venv

If you are not using that layout, run the Python entry points directly with the interpreter from your own environment.

Typical Usage

1. Run detection only

python run_detector_batch.py MDv1000-redwood /path/to/images /path/to/output.md.json \
  --recursive --include_image_timestamp --threshold 0.05

2. Run combined detection and classification

python run_md_and_speciesnet.py /path/to/images /path/to/output.sn.json

3. Run combined detection and classification with EXIF timestamps

python run_md_and_speciesnet_exif.py /path/to/images /path/to/output.sn.json \
  --detector_model MDv1000-redwood \
  --include_image_timestamp

4. Reuse an existing MegaDetector JSON

python run_md_and_speciesnet_exif.py /path/to/images /path/to/output.sn.json \
  --detections_file /path/to/output.md.json \
  --include_image_timestamp

In that mode, the EXIF-enabled wrapper backfills missing image-level datetime values from the source image files when possible.

Output

The final combined JSON keeps the MegaDetector structure and adds SpeciesNet classification output per detection.

Typical additions include:

• classifications
• raw_classifications when requested
• info.classifier
• classification_categories
• classification_category_descriptions

When --include_image_timestamp is supplied to run_md_and_speciesnet_exif.py, image records may also contain:

"datetime": "2024:09:24 07:28:16"

That value is derived from EXIF DateTimeOriginal when available.

Script Notes

run_md_and_speciesnet.py

This is the original combined pipeline.

• Default detection model: MDV5A
• Default classifier model: SpeciesNet default model
• Does not include EXIF timestamps in its output

run_md_and_speciesnet_exif.py

This is the preferred combined pipeline if you need image timestamps in the output.

• Adds --include_image_timestamp
• Preserves image-level datetime metadata in the final JSON
• Can also populate timestamps when classifying from an existing MegaDetector detections file

run_season.sh

This script runs:

1. MegaDetector first
2. then run_md_and_speciesnet.py using --detections_file

It also applies:

• --include_image_timestamp in the detection phase
• --country TZA in the classification phase

total_detection.sh

This is a minimal shell wrapper around run_md_and_speciesnet_exif.py with:

• detector model forced to MDv1000-redwood
• --include_image_timestamp enabled

Practical Limitations

• The repository is a working project, not a packaged application.
• The shell scripts contain hard-coded assumptions about environment and output locations.
• Video EXIF-style timestamps are not produced by the combined pipeline.
• The original combined script and the EXIF-enabled variant are similar but not identical; use the EXIF-enabled script when timestamp preservation matters.

Recommended Starting Point

For most new runs, use:

python run_md_and_speciesnet_exif.py <source_folder> <output_json> \
  --detector_model MDv1000-redwood \
  --include_image_timestamp

That gives you:

• one-step detection + classification
• SpeciesNet-enriched output
• EXIF-derived image timestamps when present

Related Documentation

For a deeper description of the original combined pipeline, see RUN_MD_AND_SPECIESNET.md.