# oassal/sam2-labeling-tool architecture

> Architecture diagram of the GitHub repository oassal/sam2-labeling-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oassal/sam2-labeling-tool
- Repository: https://github.com/oassal/sam2-labeling-tool

## Overview

This is a semi-automatic video/image segmentation labeling tool. Its principal workflow is CLI input → video frame splitting → interactive point annotation → SAM2 mask propagation → optional LabelMe export. The source excerpts establish the orchestration and data handoffs shown here; README-documented capabilities are included where their implementation was not sampled.

Main entry points: [`main.py`](https://github.com/oassal/sam2-labeling-tool/blob/main/main.py) (Pipeline CLI), [`utils_labeling.py`](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py) (Point annotation), [`sam.py`](https://github.com/oassal/sam2-labeling-tool/blob/main/sam.py) (Video predictor), [`labelme_utils.py`](https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py) (LabelMe export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Labeling workflow"]
  node_main["Pipeline CLI<br/>[main.py]"]
  node_frame_split["Frame splitting<br/>[utils_labeling.py]"]
  node_point_annotation["Point annotation<br/>[utils_labeling.py]"]
  node_annotation_files["Point label JSON<br/>[utils_labeling.py]"]
  node_object_ids["Object ID mapping<br/>[utils_folders.py]"]
  node_label_reader["Annotation reader<br/>[utils_labeling.py]"]
end

subgraph group_segmentation["SAM2 segmentation"]
  node_sam_dispatch["SAM2 dispatch<br/>[utils_labeling.py]"]
  node_predictor["Video predictor<br/>[sam.py]"]
  node_mask_files[("Object masks<br/>[sam.py]")]
end

subgraph group_export["Dataset export"]
  node_labelme_export["LabelMe export<br/>[labelme_utils.py]"]
  node_polygon_conversion["Mask polygons<br/>[labelme_utils.py]"]
  node_labelme_dataset["LabelMe dataset<br/>[labelme_utils.py]"]
end

node_annotator(("Annotator"))
node_sam2["SAM2 model"]

node_annotator -->|"runs"| node_main
node_main -->|"splits videos"| node_frame_split
node_frame_split -->|"returns splits"| node_main
node_main -->|"labels each split"| node_point_annotation
node_point_annotation -->|"collects clicks"| node_annotator
node_point_annotation -->|"writes points"| node_annotation_files
node_main -->|"reads annotations"| node_label_reader
node_label_reader -->|"maps objects"| node_object_ids
node_label_reader -->|"passes prompts"| node_sam_dispatch
node_sam_dispatch -->|"generates masks"| node_predictor
node_predictor -->|"runs inference"| node_sam2
node_predictor -->|"writes masks"| node_mask_files
node_main -->|"optionally exports"| node_labelme_export
node_labelme_export -->|"reads masks"| node_mask_files
node_labelme_export -->|"converts contours"| node_polygon_conversion
node_polygon_conversion -->|"writes annotations"| node_labelme_dataset

click node_main "https://github.com/oassal/sam2-labeling-tool/blob/main/main.py"
click node_frame_split "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py"
click node_point_annotation "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py"
click node_annotation_files "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py"
click node_object_ids "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_folders.py"
click node_label_reader "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py"
click node_sam_dispatch "https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py"
click node_predictor "https://github.com/oassal/sam2-labeling-tool/blob/main/sam.py"
click node_mask_files "https://github.com/oassal/sam2-labeling-tool/blob/main/sam.py"
click node_labelme_export "https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py"
click node_polygon_conversion "https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py"
click node_labelme_dataset "https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_frame_split,node_point_annotation,node_annotation_files,node_object_ids,node_label_reader toneBlue
class node_sam_dispatch,node_predictor,node_mask_files toneAmber
class node_labelme_export,node_polygon_conversion,node_labelme_dataset toneMint
class node_annotator,node_sam2 toneIndigo
```

## Components

### Labeling workflow

- [Pipeline CLI](https://github.com/oassal/sam2-labeling-tool/blob/main/main.py): `main.py`
- [Frame splitting](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py): `utils_labeling.py`
- [Point annotation](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py): `utils_labeling.py`
- [Point label JSON](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py): `utils_labeling.py`
- [Object ID mapping](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_folders.py): `utils_folders.py`
- [Annotation reader](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py): `utils_labeling.py`

### SAM2 segmentation

- [SAM2 dispatch](https://github.com/oassal/sam2-labeling-tool/blob/main/utils_labeling.py): `utils_labeling.py`
- [Video predictor](https://github.com/oassal/sam2-labeling-tool/blob/main/sam.py): `sam.py`
- [Object masks](https://github.com/oassal/sam2-labeling-tool/blob/main/sam.py): `sam.py`

### Dataset export

- [LabelMe export](https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py): `labelme_utils.py`
- [Mask polygons](https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py): `labelme_utils.py`
- [LabelMe dataset](https://github.com/oassal/sam2-labeling-tool/blob/main/labelme_utils.py): `labelme_utils.py`

### Other components

- **Annotator**
- **SAM2 model**

## Connections

- Annotator → Pipeline CLI: runs
- Pipeline CLI → Frame splitting: splits videos
- Frame splitting → Pipeline CLI: returns splits
- Pipeline CLI → Point annotation: labels each split
- Point annotation → Annotator: collects clicks
- Point annotation → Point label JSON: writes points
- Pipeline CLI → Annotation reader: reads annotations
- Annotation reader → Object ID mapping: maps objects
- Annotation reader → SAM2 dispatch: passes prompts
- SAM2 dispatch → Video predictor: generates masks
- Video predictor → SAM2 model: runs inference
- Video predictor → Object masks: writes masks
- Pipeline CLI → LabelMe export: optionally exports
- LabelMe export → Object masks: reads masks
- LabelMe export → Mask polygons: converts contours
- Mask polygons → LabelMe dataset: writes annotations