Repository files navigation

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.