deepmeerkat 3.1.1

DeepMeerkat 3.0 — MegaDetector, Community Fish Detector, and classic motion for ecological video

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, preserved as Git tag v2.0.0 and branch v2.0.
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 frozen at Git tag v2.0.0 on branch v2.0. Use those only if you need the older application.

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 — the release file is named like DeepMeerkat-v3.0.0-macOS (version in the name). It is not a .dmg or .app; it 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 (match the filename from the release).
4. Run it: ./DeepMeerkat-v3.0.0-macOS

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

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

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 (unsigned binary; see below)

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.