Metadata-Version: 2.4
Name: zamba
Version: 2.7.2
Summary: Zamba is a command line tool and Python package to identify animals in camera trap videos and train custom models for new species and habitats.
Author-email: DrivenData <info@drivendata.org>
Requires-Python: >=3.11, <3.14
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
License-File: LICENSE
Requires-Dist: appdirs
Requires-Dist: click<=8.1.8
Requires-Dist: cloudpathlib[s3]
Requires-Dist: gitpython
Requires-Dist: loguru
Requires-Dist: mlflow-skinny
Requires-Dist: numpy<2.0.0
Requires-Dist: openpyxl
Requires-Dist: pandas>=2.0.0
Requires-Dist: pandas_path
Requires-Dist: pqdm
Requires-Dist: pyarrow>=23.0.0
Requires-Dist: pydantic<2.0.0
Requires-Dist: python-dotenv
Requires-Dist: pytorch-lightning>=2.0.0
Requires-Dist: scikit-learn
Requires-Dist: tensorboard
Requires-Dist: thop
Requires-Dist: timm
Requires-Dist: torch
Requires-Dist: torch>=2.7.1,!=2.7.2,!=2.7.3,!=2.8.0,!=2.8.1,!=2.8.2,!=2.9.0,!=2.9.1,!=2.10.0; sys_platform == 'win32'
Requires-Dist: torchinfo
Requires-Dist: torchvision>=0.10.0
Requires-Dist: tqdm
Requires-Dist: typer[all]
Requires-Dist: mike ; extra == "docs"
Requires-Dist: mkdocs>=1.2.2 ; extra == "docs"
Requires-Dist: mkdocs-material>=7.3.4,<9.6 ; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.19.0,<=0.27 ; extra == "docs"
Requires-Dist: megadetector>=10.0.0 ; extra == "image"
Requires-Dist: Pillow>=9.0.0 ; extra == "image"
Requires-Dist: black>=26.1.0 ; extra == "tests"
Requires-Dist: coverage ; extra == "tests"
Requires-Dist: flake8 ; extra == "tests"
Requires-Dist: nvidia-ml-py ; extra == "tests"
Requires-Dist: psutil ; extra == "tests"
Requires-Dist: pytest ; extra == "tests"
Requires-Dist: pytest-coverage ; extra == "tests"
Requires-Dist: pytest-duration-insights ; extra == "tests"
Requires-Dist: pytest-mock ; extra == "tests"
Requires-Dist: pytest-reportlog ; extra == "tests"
Requires-Dist: pytest-xdist ; extra == "tests"
Requires-Dist: wheel ; extra == "tests"
Requires-Dist: av ; extra == "video"
Requires-Dist: ffmpeg-python ; extra == "video"
Requires-Dist: future ; extra == "video"
Requires-Dist: fvcore ; extra == "video"
Requires-Dist: opencv-python-headless ; extra == "video"
Requires-Dist: pytorchvideo ; extra == "video"
Requires-Dist: pixeltable-yolox ; extra == "video"
Project-URL: Bug Tracker, https://github.com/drivendataorg/zamba/issues
Project-URL: Changelog, https://github.com/drivendataorg/zamba/blob/master/HISTORY.md
Project-URL: Documentation, https://zamba.drivendata.org/docs/stable/
Project-URL: Homepage, https://github.com/drivendataorg/zamba
Provides-Extra: docs
Provides-Extra: image
Provides-Extra: tests
Provides-Extra: video

# Zamba

[![Docs Status](https://img.shields.io/badge/docs-stable-informational)](https://zamba.drivendata.org/docs/)
[![tests](https://github.com/drivendataorg/zamba/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/drivendataorg/zamba/actions/workflows/tests.yml?query=branch%3Amaster)
[![codecov](https://codecov.io/gh/drivendataorg/zamba/branch/master/graph/badge.svg)](https://codecov.io/gh/drivendataorg/zamba)
<!-- [![PyPI](https://img.shields.io/pypi/v/zamba.svg)](https://pypi.org/project/zamba/) -->

https://user-images.githubusercontent.com/46792169/138346340-98ee196a-5ecd-4753-b9df-380528091f9e.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 trap _images_ and _videos_.** You can use `zamba` 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 in `zamba` 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 identify species from throughout the world: `lila.science` covers 178 global species and groups, and `speciesnet` (a conversion of Google's SpeciesNet) covers a much larger taxonomy of over 2,000 classes. 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](https://www.zambacloud.com/).

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 the [Model Zoo Wiki](https://github.com/drivendataorg/zamba/wiki) for others to be able to use!

Visit https://zamba.drivendata.org/docs/ for full documentation and tutorials.

## Installing `zamba`

We recommend [uv](https://docs.astral.sh/uv/) for installing Python packages and managing environments. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then ensure you have:

* Python >= 3.11
* FFmpeg > 4.3 and < 5 (only needed for video workflows)

Then install the extras you need with uv. **We recommend only installing one or the other depending on your use case.** Pass `--torch-backend=auto` so uv installs a PyTorch build matched to your GPU (or CPU):

```console
# For video workflows
uv pip install zamba[video] --torch-backend=auto

# For image workflows
uv pip install zamba[image] --torch-backend=auto

# For both (requires protobuf/setuptools overrides — see Installation docs)
uv pip install zamba[video,image] --torch-backend=auto --overrides zamba-overrides.txt
```

See the [Installation](https://zamba.drivendata.org/docs/stable/install/) page for the overrides file and full details.

You can also use pip: `pip install zamba[video]`, `pip install zamba[image]`, or `pip install zamba[video,image]`.

## Getting started

Once you have `zamba` installed, some good starting points are:

- The [Quickstart](https://zamba.drivendata.org/docs/stable/quickstart/) page for basic examples of usage
- The user tutorials for [classifying images](https://zamba.drivendata.org/docs/stable/images-predict-tutorial/), [classifying videos](https://zamba.drivendata.org/docs/stable/predict-tutorial/), or [training a model](https://zamba.drivendata.org/docs/stable/train-tutorial/)

## Example usage

Once `zamba` is installed, you can see the basic command options with:
```console
$ 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 as [`pillow`](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#fully-supported-formats) and the same video formats as FFmpeg, [which are listed here](https://www.ffmpeg.org/general.html#Supported-File-Formats_002c-Codecs-or-Features). Any images or videos that fail a set of validation checks will be skipped during inference or training.

### Classifying unlabeled images and videos

Zamba classifies videos by default, but can easily be set to classify images instead. To get classifications for videos:

```console
$ zamba predict --data-dir path/to/videos
```
and for images:

```console
$ zamba image predict --data-dir path/to/videos
```

By default, predictions will be saved to `zamba_predictions.csv`. Run `zamba predict --help` or `zamba image predict --help` to list all possible options to pass to `predict`.

See the [Quickstart](https://zamba.drivendata.org/docs/stable/quickstart/) page or the user tutorial on [classifying images](https://zamba.drivendata.org/docs/stable/images-predict-tutorial/) or [classifying videos](https://zamba.drivendata.org/docs/stable/predict-tutorial/) for more details.

### Training a model

Zamba defaults to training a model for classifying videos:
```console
$ zamba train --data-dir path/to/videos --labels path_to_labels.csv --save_dir my_trained_model
```

Training a model for images is similar:
```console
$ 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. Run `zamba train --help` or `zamba image train --help` to list all possible options to pass to `train`.

You can use your trained model on new images or videos by editing the `train_configuration.yaml` that is generated by `zamba`. Add a `predict_config` section to the yaml that points to the checkpoint file that is generated:

```yaml
...
# generated train_config
...

predict_config:
  checkpoint: PATH_TO_YOUR_CHECKPOINT_FILE

```

Now you can pass this configuration to the command line. See the [Quickstart](https://zamba.drivendata.org/docs/stable/quickstart/) page or the user tutorial on [training a model](https://zamba.drivendata.org/docs/stable/train-tutorial/) for more details.

You can then share your model with others by adding it to the [Model Zoo Wiki](https://github.com/drivendataorg/zamba/wiki).

### Estimating distance between animals and the camera

Depth-estimation models are also supported, but only for video files. For example:
```console
$ zamba depth --data-dir path/to/videos
```

By default, predictions will be saved to `depth_predictions.csv`. Run `zamba depth --help` to list all possible options to pass to `depth`.

See the [depth estimation page](https://zamba.drivendata.org/docs/stable/models/depth/) for more details.


## Contributing

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 on [contributing to `zamba`](https://zamba.drivendata.org/docs/stable/contribute/) for details.

## Reference paper

Dorne, E., Qi, J., Bull, P., Stephens, C., Bessone, M., Debetencourt, B., Fruth, B., Morgan, D., Palmer, M. S., Sanz, C., Wendefeuer, J., Crockford, C., Deschner, T., Langergraber, K. E., Piel, A. K., Robbins, M., Sommer, V., Stewart, F. A., Wittig, R. M., . . . Arandjelovic, M. (2025). Zamba: Computer vision for wildlife conservation. _Proceedings of the Python in Science Conferences_, 85–111. [https://doi.org/10.25080/crcw9835](https://doi.org/10.25080/crcw9835)

