DeepMeerkat 3.0

Desktop and CLI tooling for ecological camera video: MegaDetector (default) for animal / person / vehicle bounding boxes, Community Fish Detector for underwater fish detection (optional [fish] extras), plus classic OpenCV motion for legacy workflows.

Documentation: deepmeerkat.readthedocs.io (enable the repo on Read the Docs using .readthedocs.yaml).

Development uses the main branch (and CI runs on pushes/PRs to main).

Version history (why “3.0”?)

This codebase is released as DeepMeerkat 3.0 and is the modern “Meerkat 3” line:

Line	What it refers to
1.0	MotionMeerkat — earlier motion-focused tooling in the same research lineage.
2.0	DeepMeerkat — the previous desktop/codebase generation (legacy code is not stored in this repository).
3.0	DeepMeerkat 3.0 (this repository) — MegaDetector-first PySide6 GUI and CLI, rewritten packaging and outputs.

We start numbering releases at 3.0 here so installers and PyPI stay aligned with that story (not with MotionMeerkat or legacy DeepMeerkat release tags).

DeepMeerkat 2.0 (legacy)

The 2.x codebase is not present in this repository. If you need legacy behavior, use this 3.x codebase in --mode motion or ask maintainers for an archival 2.x source reference.

Requirements

• Python 3.11+
• For GPU inference, install PyTorch per PyTorch for your platform; megadetector will use it when available.

Downloads (GUI installers)

GitHub Releases attach Windows and macOS GUI builds when CI succeeds. There is no Linux .tar.gz or AppImage: bundled PyTorch pushes past GitHub’s 2 GiB per-file limit, so Linux uses pip from PyPI (see Install below).

Linux

pip install "deepmeerkat[ui]"
deepmeerkat-gui

Windows — run the downloaded .exe.

macOS — releases now include two architecture-specific files:

• Intel: DeepMeerkat-v3.0.0-macOS-x64
• Apple Silicon: DeepMeerkat-v3.0.0-macOS-arm64

They are not .dmg or .app bundles; each is a single unsigned executable. Use Terminal (double-click usually does not launch the GUI):

1. Open Terminal.
2. cd to the folder where you saved the file (often ~/Downloads).
3. Make it executable once: chmod +x DeepMeerkat-v3.0.0-macOS-x64 (or ...-arm64, matching your machine and release filename).
4. Run it: ./DeepMeerkat-v3.0.0-macOS-x64 (or ...-arm64).

Copy-paste example (adjust filename if your version differs):

cd ~/Downloads
chmod +x DeepMeerkat-v3.0.0-macOS-x64
./DeepMeerkat-v3.0.0-macOS-x64

If macOS blocks it (unidentified developer): System Settings → Privacy & Security → find the prompt → Open Anyway; or in Finder, Control-click the file → Open → confirm.

Easier on Mac: pip install "deepmeerkat[ui]" then deepmeerkat-gui — same app, no unsigned binary. See Install below.

Install

From PyPI

pip install "deepmeerkat[ui]"

CLI only (no PySide6 GUI): pip install deepmeerkat

Editable install from a clone (development)

git clone https://github.com/bw4sz/DeepMeerkat.git
cd DeepMeerkat
pip install -e ".[ui,dev]"

Run the GUI:

python -m deepmeerkat.ui

Run the CLI (MegaDetector is the default mode):

deepmeerkat run /path/to/video.mp4 --output ./out

Classic motion mode:

deepmeerkat run /path/to/video.mp4 --output ./out --mode motion

Community Fish Detector (underwater; install pip install "deepmeerkat[fish]"). Weights download automatically on first fish run (~116 MB, cached under the OS user cache). Optional: --fish-weights /path/to/custom.pth.

deepmeerkat run /path/to/video.avi --output ./out --mode fish

See the docs: Community Fish Detector.

Re-open previous results (GUI)

Use File → Open result folder… and select a run directory that contains annotations.csv (for example …/output/garcon_test/). DeepMeerkat fills in the original input video and output folder from parameters.csv so you can Review again or re-run. After a successful run, File → Reopen last results opens the review player for the last output folder.

Optional local smoke test

Set DEEPMEERKAT_TEST_VIDEO to a clip on your machine for manual checks (not used in CI).

PyPI and GitHub releases (maintainers)

1. Version bump

• Set version in pyproject.toml (for example 3.0.0).
• Commit on main.

2. Tag and push

Create an annotated tag (example for 3.0.0):

git tag -a v3.0.0 -m "DeepMeerkat 3.0.0"
git push origin v3.0.0

Pushing v* triggers:

• .github/workflows/publish.yml — sdist/wheel to PyPI (requires repository secret PYPI_TOKEN).
• .github/workflows/build_installers.yml — builds GUI PyInstaller bundles for Windows and macOS only; uploads to the GitHub Release (uses GITHUB_TOKEN). No Linux binary (see Downloads above).

If installer jobs fail (timeouts, size limits, or missing system libs), fix the workflow or build locally (below) and attach assets by hand on the release page.

3. GitHub Release assets

After the tag build, the release v3.0.0 should list downloadable files similar to:

• DeepMeerkat-v3.0.0-Windows-x64.exe
• DeepMeerkat-v3.0.0-macOS-x64 (unsigned binary; Intel)
• DeepMeerkat-v3.0.0-macOS-arm64 (unsigned binary; Apple Silicon)

Names follow build_installers.yml.

4. Manual installer build (optional)

From the repository root, with the same Python you use for development:

pip install -e ".[ui]" pyinstaller
# or: pip install -e ".[ui,packaging]"
pyinstaller --noconfirm packaging/deepmeerkat-gui.spec

Outputs live under dist/ (deepmeerkat-gui or deepmeerkat-gui.exe). A CLI one-file build is available via packaging/deepmeerkat-cli.spec (also large, includes PyTorch).

macOS distribution: CI produces a raw binary, not a signed .app or .dmg. For public distribution outside the lab, plan for codesigning and optionally notarization (Apple Developer Program), or ship via pip / conda instead.

Linux: We do not publish a release binary. Use pip install "deepmeerkat[ui]". Advanced users can run PyInstaller locally; the bundle is typically too large for GitHub Releases.

License

See LICENSE. Third-party models (MegaDetector) have their own terms; see the MegaDetector project documentation.