flat-bug 1.1.0

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):

# Add to a project permanently (recommended)
uv add flat-bug
# install temporarily in a venv/project
uv pip install flat-bug

or (not recommended):

pip install flat-bug

Source/development

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

# Clone repository
git clone https://github.com/darsa-group/flat-bug.git
cd flat-bug
# Install
uv sync --all-extras --all-groups --upgrade
# or (not recommended)
pip install -e .

However, 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] 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/.

---