StrandSeg-Lite

StrandSeg-Lite

Lightweight binary semantic segmentation for thin yoyo strings. The model is a MobileNetV3-Large encoder with a small high-resolution FPN decoder and one foreground logit channel. It predicts the visible string region in a BGR/RGB image.

Files

• model.pt — PyTorch checkpoint (yoyo_string_semantic_transfer_v1).
• model.py — standalone MobileNetV3-FPN definition and checkpoint loader.
• inference.py — dependency-light image/file and Python APIs.
• requirements.txt — runtime dependencies.
• MODEL_CARD.json — reproducibility metadata and checksums.

Quick start

python -m pip install -r requirements.txt
python inference.py path/to/frame.jpg --output-mask mask.png --output-probability probability.png

The command writes a binary PNG mask and an 8-bit probability PNG. For a Python caller:

from inference import StrandSegLite

segmenter = StrandSegLite("model.pt")
result = segmenter.predict_file("frame.jpg")
mask = result.mask          # HxW uint8, values 0 or 1
probability = result.probability  # HxW float32 in [0, 1]

The checkpoint's selected threshold is 0.9204. The model letterboxes input to 960x544, uses ImageNet normalization, and maps the output back to the original image size. The public API accepts RGB or BGR NumPy arrays; set color="bgr" when passing OpenCV frames.

Visual examples

The panels below show evaluation examples centered on the predicted string region. Each panel contains the input, the predicted mask overlay, and the thresholded binary mask. Green denotes pixels selected at the checkpoint threshold.

Evaluation snapshot

The checkpoint was trained and evaluated on a self-built, manually reviewed yoyo string dataset. On the held-out evaluation split, it reached Centerline F1@8 of 0.829465, Presence F1 of 0.976562, and Pixel Dice of 0.694979. On the consecutive evaluation set, pooled Centerline F1@8 was 0.818297; the weakest source group scored 0.638996. These metrics use the project’s centerline-tolerance protocol and should not be compared with pixel Dice from other mask widths or buffering rules.

Architecture comparison

The following tables compare metrics across model architectures. FPS is model-only throughput unless noted otherwise.

Validation screening (4 epochs)

Consecutive evaluation (927 frames)

The consecutive rows also report geometry diagnostics: StrandSeg-Lite Chamfer/HD95 was 15.6212/57.4703 px, while RT-DLO was 9.1097/37.4760 px. End-to-end video throughput for the StrandSeg-Lite tracking pipeline was approximately 11.14 FPS on the same RTX 4070 Laptop test system.

Intended use and limitations

StrandSeg-Lite is designed for research and prototyping on yoyo performance video frames, where a compact segmentation model and straightforward mask output are useful. It works best when the capture setup resembles the reviewed evaluation material; lighting, resolution, motion blur, occlusion, and annotation conventions can affect the resulting mask.

The model repository contains the checkpoint and inference code. The training images and annotations are from the project’s self-built dataset.

Reproducibility

MODEL_CARD.json records the model configuration, threshold, and evaluation references.