flat-bug 1.1.1

Universal Arthropod Localization and Instance Segmentation

flatbug

A General Method for Detection and Segmentation of Terrestrial Arthropods in Images

Find and cite the flatbug paper in Method in Ecology and Evolution

Send us new data through our data contribution form.

---

flatbug is partly a high-performance pyramid tiling inference wrapper for YOLOv8 and partly a hybrid instance segmentation dataset of terrestrial arthropods accompanied by an appropriate training schedule for YOLOv8 segmentation models, built on top of the original YOLOv8 training schedule.

The goal of flatbug is to provide a single unified model for detection and segmentation of all terrestrial arthropods on arbitrarily large images, especially fine-tuned for the case of top-down images/scans - thus the name "flat"bug.

---

Installation

We recommend using uv (installation):

# Easy-install
uv pip install flat-bug --torch-backend=auto
# Add to a project permanently (recommended)
uv add flat-bug

[!TIP] If you have problems with PyTorch not being installed with CUDA enabled try:

uv pip install torch torchvision --torch-backend=auto --reinstall

More details: https://docs.astral.sh/uv/guides/integration/pytorch/#the-uv-pip-interface

or (not recommended):

pip install flat-bug

Source/development

Or a development version can be installed from source by cloning this repository:

Clone the repository

git clone https://github.com/darsa-group/flat-bug.git
cd flat-bug

Install flatbug

uv sync --all-extras --all-groups --upgrade 
# (optional but recommended)
uv pip install torch torchvision --torch-backend=auto --reinstall

or (not recommended):

pip install -e .

[!WARNING] If you do decide to install with pip, as with other packages built with PyTorch it is best to ensure that torch is installed separately. See https://pytorch.org/ for details. We recommend using torch>=2.3.

---

CLI Usage

We provide a number of CLI scripts with flatbug. The main one of interest is fb_predict, which can be used to run inference on images or videos:

[uv run] fb_predict -i <DIR_WITH_IMGS> -o <OUTPUT_DIR> [-w <WEIGHT_PATH>] ...

Tutorials

We provide a number of tutorials on general and advanced usage, training, deployment and hyperparameters of flatbug in examples/tutorials or with Google Colab .

Documentation

Find our documentation at https://darsa.info/flat-bug/.

---

CUDA Issues

Working with cross-platform PyTorch code can be a bit confusing, so if you ever get stuck with some CUDA errors, here are some possible paths to resolve the issues.

uv and pip

If you installed flat-bug via a package manager but find that GPU acceleration is not working, your environment likely downloaded the default PyPI wheels which may not match your system's NVIDIA drivers.

If you are using uv, the easiest fix is to force a re-resolution of the PyTorch backend:

# Automatically detect hardware and reinstall PyTorch
uv pip install torch torchvision --torch-backend=auto --reinstall

# OR manually force a specific CUDA version (e.g., CUDA 11.8)
uv pip install torch torchvision --torch-backend=cu118 --reinstall

If you are using standard pip, you must manually point to the PyTorch index that matches your system:

# Uninstall the broken versions
pip uninstall torch torchvision

# Reinstall pointing explicitly to the CUDA 11.8 or 12.1 (cu121) index
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

Verification:

[uv run] python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

Source

Rebuild the environment and lockfile from scratch:

# cd ~/flat-bug

# 1. Purge old state
rm uv.lock
rm -rf .venv

# 2. Generate the pure, cross-platform lockfile
uv lock

# 3. Create your local environment
uv sync --all-extras --all-groups

# 4. Patch your local environment with your specific hardware backend
uv pip install torch torchvision --torch-backend=auto --reinstall