- Notifications
You must be signed in to change notification settings - Fork29
A Python package for identifying 42 kinds of animals, training custom models, and estimating distance from camera trap videos and images
License
drivendataorg/zamba
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
monkey-vid.mp4
Zamba means "forest" in Lingala, a Bantu language spoken throughout the Democratic Republic of the Congo and the Republic of the Congo.
zamba
is a tool built in Python that uses machine learning and computer vision to automatically detect and classify animals in camera trapimages andvideos. You can usezamba
to:
- Identify which species appear in each image or video
- Filter out blank images or videos
- Create your own custom models that identify your species in your habitats
- Estimate the distance between animals in the frame and the video camera
- And more! 🙈 🙉 🙊
The official video models inzamba
can identify blank videos (where no animal is present) along with 32 species common to Africa and 11 species common to Europe. The official image models can identify 178 species from throughout the world. Users can also finetune models using their own labeled images and videos to then make predictions for new species and/or new ecologies.
zamba
can be used both as a command-line tool and as a Python package. It is also available as a user-friendly website application,Zamba Cloud.
We encourage people to share their custom models trained with Zamba. If you train a model and want to make it available, please add it to theModel Zoo Wiki for others to be able to use!
Visithttps://zamba.drivendata.org/docs/ for full documentation and tutorials.
First, make sure you have the prerequisites installed:
- Python 3.11 or 3.12
- FFmpeg > 4.3
Then run:
pip install https://github.com/drivendataorg/zamba/releases/latest/download/zamba.tar.gz
See theInstallation page of the documentation for details.
Once you havezamba
installed, some good starting points are:
- TheQuickstart page for basic examples of usage
- The user tutorials forclassifying images,classifying videos, ortraining a model
Oncezamba
is installed, you can see the basic command options with:
$zamba --help Usage: zamba [OPTIONS] COMMAND [ARGS]... Zamba is a tool built in Python to automatically identify the species seen in camera trap videos from sites in Africa and Europe. Visit https://zamba.drivendata.org/docs for more in-depth documentation.╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮│ --version Show zamba version and exit. ││ --install-completion Install completion for the current shell. ││ --show-completion Show completion for the current shell, to copy it or ││ customize the installation. ││ --help Show this message and exit. │╰───────────────────────────────────────────────────────────────────────────────────────────╯╭─ Commands ────────────────────────────────────────────────────────────────────────────────╮│ densepose Run densepose algorithm on videos. ││ depth Estimate animal distance at each second in the video. ││ predict Identify species in a video. ││ train Train a model on your labeled data. │| image Tools for working with images instead of videos. |╰───────────────────────────────────────────────────────────────────────────────────────────╯
zamba
can be used "out of the box" to generate predictions or train a model using your own images and videos.zamba
supports the same image formats aspillow
and the same video formats as FFmpeg,which are listed here. Any images or videos that fail a set of validation checks will be skipped during inference or training.
Zamba classifies videos by default, but can easily be set to classify images instead. To get classifications for videos:
$zamba predict --data-dir path/to/videos
and for images:
$zamba image predict --data-dir path/to/videos
By default, predictions will be saved tozamba_predictions.csv
. Runzamba predict --help
orzamba image predict --help
to list all possible options to pass topredict
.
See theQuickstart page or the user tutorial onclassifying images orclassifying videos for more details.
Zamba defaults to training a model for classifying videos:
$zamba train --data-dir path/to/videos --labels path_to_labels.csv --save_dir my_trained_model
Training a model for images is similar:
$zamba image train --data-dir path/to/images --labels path_to_labels.csv --save_dir my_trained_model
The newly trained model will be saved to the specified save directory. The folder will contain a model checkpoint as well as training configuration, model hyperparameters, and validation and test metrics. Runzamba train --help
orzamba image train --help
to list all possible options to pass totrain
.
You can use your trained model on new images or videos by editing thetrain_configuration.yaml
that is generated byzamba
. Add apredict_config
section to the yaml that points to the checkpoint file that is generated:
...# generated train_config...predict_config:checkpoint:PATH_TO_YOUR_CHECKPOINT_FILE
Now you can pass this configuration to the command line. See theQuickstart page or the user tutorial ontraining a model for more details.
You can then share your model with others by adding it to theModel Zoo Wiki.
Depth-estimation models are also supported, but only for video files. For example:
$zamba depth --data-dir path/to/videos
By default, predictions will be saved todepth_predictions.csv
. Runzamba depth --help
to list all possible options to pass todepth
.
See thedepth estimation page for more details.
We would love your contributions of code fixes, new models, additional training data, docs revisions, and anything else you can bring to the project!
See the docs page oncontributing tozamba
for details.
About
A Python package for identifying 42 kinds of animals, training custom models, and estimating distance from camera trap videos and images