BeetleFlow

Segments the body parts (head, pronotum, elytra, legs, antennae, and more) of pinned ground-beetle specimens in cropped images, for trait measurement.

Intended use. Pixel-level segmentation of body parts on cropped images of single, pinned ground beetles, so that part-specific traits (elytra length, pronotum area and so on) can be measured at scale. It is the segmentation stage of the BeetleFlow pipeline (detection → cropping → segmentation) from the Imageomics Institute. It does not find beetles in an image and does not identify them.

Architecture and training

Mask2Former with a Swin-Large backbone, fine-tuned from facebook/mask2former-swin-large-ade-semantic. Two checkpoints are released:

Training images are manually annotated pinned specimens from the Beetles as Sentinel Taxa dataset (NEON pitfall-trap carabids, CC BY 4.0). Trained for 30 epochs at 512×512 with AdamW (lr 1e-4) on one A100.

Inputs and outputs

Input: an RGB crop of one specimen, resized to 512×512 and normalised with the ADE20K mean and std by Mask2FormerImageProcessor. Output: a per-pixel class map over the part labels of the chosen checkpoint. Crops are expected to come from the BeetleFlow detection and cropping stages; see the repository for batch inference.

Performance

As reported on the model card, on the held-out BeetleFlow segmentation test split (68 images for 5-class, 66 for 9-class), at 512×512:

Large structures segment well (elytra and pronotum IoU > 0.9). Thin or small parts do worse: antennae 0.66 (5-class), and in the 9-class model tail 0.53, mouthparts 0.60 and eyes 0.68.

Limitations

• Trained only on pinned ground beetles (Carabidae) photographed under museum lighting at NEON. Expect degradation on other beetle families, other preparations, and any field or trap photographs.
• Not usable for other insect orders without fine-tuning. The part labels (pronotum, elytra) are beetle-specific.
• Needs a clean single-specimen crop. Poor upstream cropping lowers mask quality, and it cannot handle full trays or several specimens in one image.
• The test sets are small (66–68 images) and come from the same source as the training data, so the reported IoU says nothing about out-of-distribution use.
• Thin appendages (antennae, legs, tail) are the least reliable, which matters for traits measured from them.

License and rights

• License: MIT
• Commercial use: allowed
• Restrictions: None stated. The training images are CC BY 4.0.
• Upstream source: https://huggingface.co/imageomics/BeetleFlow

How to obtain the weights

Open on Hugging Face, no gate. Links above are pinned to commit 521d768. Each checkpoint is about 866 MB of Safetensors and loads with transformers (Mask2FormerForUniversalSegmentation.from_pretrained("imageomics/BeetleFlow", subfolder="5-class")).

Citation

@inproceedings{liu2025beetleflow,
  title     = {BeetleFlow: An Integrative Deep Learning Pipeline for Beetle Image Processing},
  author    = {Liu, Fangxun and Rayeed, S M and Stevens, Samuel and East, Alyson and Chiang, Cheng Hsuan and Lee, Colin and Yi, Daniel and Yang, Junke and Naik, Tejas and Wang, Ziyi and Kilrain, Connor and Buckwalter, Elijah H. and Hou, Jiacheng and Bueno, Saul Ibaven and Wang, Shuheng and Ma, Xinyue and Liu, Yifan and Tao, Zhiyuan and Zhang, Ziheng and Sokol, Eric and Belitz, Michael and Record, Sydne and Stewart, Charles V. and Chao, Wei-Lun},
  booktitle = {NeurIPS 2025 Workshop for Imageomics: Discovering Biological Knowledge from Images Using AI},
  year      = {2025}
}

The authors also ask that the sentinel-beetles dataset be cited.

Output format probe

The author batch_inference.py script was run with the 5-class checkpoint and an author test image. It saved an RGB palette mask and an additive overlay at the original 301 × 154 resolution. The 9-class checkpoint was not tested. The script increments output filenames per folder, so multiple same-extension images in a folder overwrite each other.

Probe date: 2026-09-30. Reproducible setup and evidence are in src/probe.