{"id":13612319,"url":"https://github.com/drivendataorg/zamba","last_synced_at":"2025-05-16T19:03:29.724Z","repository":{"id":31903111,"uuid":"124150639","full_name":"drivendataorg/zamba","owner":"drivendataorg","description":"A Python package for identifying hundreds of kinds of animals, training custom models, and estimating distance from camera trap videos and images","archived":false,"fork":false,"pushed_at":"2025-05-08T17:26:23.000Z","size":87399,"stargazers_count":129,"open_issues_count":57,"forks_count":31,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-08T17:43:24.704Z","etag":null,"topics":["animals","camera-traps","chimps","cli","conservation","deep-learning","ecology","gpu","images","jungle","machine-learning","neural-network","python","pytorch","pytorch-lightning","video-processing","videos"],"latest_commit_sha":null,"homepage":"https://zamba.drivendata.org/docs/stable/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drivendataorg.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-06T23:18:46.000Z","updated_at":"2025-05-04T04:49:33.000Z","dependencies_parsed_at":"2023-09-24T12:10:31.162Z","dependency_job_id":"acb023c1-9471-4ec0-9d50-ec935ae7ed6f","html_url":"https://github.com/drivendataorg/zamba","commit_stats":{"total_commits":230,"total_committers":17,"mean_commits":"13.529411764705882","dds":0.6869565217391305,"last_synced_commit":"dc87a8aae448e099e6dd7dc16c03fcc27242e30a"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drivendataorg%2Fzamba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drivendataorg%2Fzamba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drivendataorg%2Fzamba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drivendataorg%2Fzamba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drivendataorg","download_url":"https://codeload.github.com/drivendataorg/zamba/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592368,"owners_count":22097011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animals","camera-traps","chimps","cli","conservation","deep-learning","ecology","gpu","images","jungle","machine-learning","neural-network","python","pytorch","pytorch-lightning","video-processing","videos"],"created_at":"2024-08-01T20:00:27.548Z","updated_at":"2025-05-16T19:03:29.715Z","avatar_url":"https://github.com/drivendataorg.png","language":"Python","funding_links":[],"categories":["Software","Biosphere"],"sub_categories":["Other Topics","Terrestrial Wildlife"],"readme":"# Zamba\n\n[![Docs Status](https://img.shields.io/badge/docs-stable-informational)](https://zamba.drivendata.org/docs/)\n[![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)\n[![codecov](https://codecov.io/gh/drivendataorg/zamba/branch/master/graph/badge.svg)](https://codecov.io/gh/drivendataorg/zamba)\n\u003c!-- [![PyPI](https://img.shields.io/pypi/v/zamba.svg)](https://pypi.org/project/zamba/) --\u003e\n\nhttps://user-images.githubusercontent.com/46792169/138346340-98ee196a-5ecd-4753-b9df-380528091f9e.mp4\n\n\u003e *Zamba* means \"forest\" in Lingala, a Bantu language spoken throughout the Democratic Republic of the Congo and the Republic of the Congo.\n\n**`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:\n\n- Identify which species appear in each image or video\n- Filter out blank images or videos\n- Create your own custom models that identify your species in your habitats\n- Estimate the distance between animals in the frame and the video camera\n- And more! 🙈 🙉 🙊\n\nThe 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 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.\n\n`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/).\n\nWe 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!\n\nVisit https://zamba.drivendata.org/docs/ for full documentation and tutorials.\n\n## Installing `zamba`\n\nFirst, make sure you have the prerequisites installed:\n\n* Python \u003e= 3.11\n* FFmpeg \u003e 4.3\n\nThen run:\n```console\npip install https://github.com/drivendataorg/zamba/releases/latest/download/zamba.tar.gz\n```\n\nSee the [Installation](https://zamba.drivendata.org/docs/stable/install/) page of the documentation for details.\n\n## Getting started\n\nOnce you have `zamba` installed, some good starting points are:\n\n- The [Quickstart](https://zamba.drivendata.org/docs/stable/quickstart/) page for basic examples of usage\n- 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/)\n\n## Example usage\n\nOnce `zamba` is installed, you can see the basic command options with:\n```console\n$ zamba --help\n\n Usage: zamba [OPTIONS] COMMAND [ARGS]...\n\n Zamba is a tool built in Python to automatically identify the species seen in camera trap\n videos from sites in Africa and Europe. Visit https://zamba.drivendata.org/docs for more\n in-depth documentation.\n\n╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮\n│ --version                     Show zamba version and exit.                                │\n│ --install-completion          Install completion for the current shell.                   │\n│ --show-completion             Show completion for the current shell, to copy it or        │\n│                               customize the installation.                                 │\n│ --help                        Show this message and exit.                                 │\n╰───────────────────────────────────────────────────────────────────────────────────────────╯\n╭─ Commands ────────────────────────────────────────────────────────────────────────────────╮\n│ densepose      Run densepose algorithm on videos.                                         │\n│ depth          Estimate animal distance at each second in the video.                      │\n│ predict        Identify species in a video.                                               │\n│ train          Train a model on your labeled data.                                        │\n| image          Tools for working with images instead of videos.                           |\n╰───────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n`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.\n\n### Classifying unlabeled images and videos\n\nZamba classifies videos by default, but can easily be set to classify images instead. To get classifications for videos:\n\n```console\n$ zamba predict --data-dir path/to/videos\n```\nand for images:\n\n```console\n$ zamba image predict --data-dir path/to/videos\n```\n\nBy 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`.\n\nSee 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.\n\n### Training a model\n\nZamba defaults to training a model for classifying videos:\n```console\n$ zamba train --data-dir path/to/videos --labels path_to_labels.csv --save_dir my_trained_model\n```\n\nTraining a model for images is similar:\n```console\n$ zamba image train --data-dir path/to/images --labels path_to_labels.csv --save_dir my_trained_model\n```\n\nThe 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`.\n\nYou 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:\n\n```yaml\n...\n# generated train_config\n...\n\npredict_config:\n  checkpoint: PATH_TO_YOUR_CHECKPOINT_FILE\n\n```\n\nNow 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.\n\nYou can then share your model with others by adding it to the [Model Zoo Wiki](https://github.com/drivendataorg/zamba/wiki).\n\n### Estimating distance between animals and the camera\n\nDepth-estimation models are also supported, but only for video files. For example:\n```console\n$ zamba depth --data-dir path/to/videos\n```\n\nBy default, predictions will be saved to `depth_predictions.csv`. Run `zamba depth --help` to list all possible options to pass to `depth`.\n\nSee the [depth estimation page](https://zamba.drivendata.org/docs/stable/models/depth/) for more details.\n\n\n## Contributing\n\nWe would love your contributions of code fixes, new models, additional training data, docs revisions, and anything else you can bring to the project!\n\nSee the docs page on [contributing to `zamba`](https://zamba.drivendata.org/docs/stable/contribute/) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrivendataorg%2Fzamba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrivendataorg%2Fzamba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrivendataorg%2Fzamba/lists"}