# error273/box-measurer architecture

> Architecture diagram of the GitHub repository error273/box-measurer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/error273/box-measurer
- Repository: https://github.com/error273/box-measurer

## Overview

Box Measurer turns one photograph into physical length and width estimates, using a known-size ArUco marker for scale and SAM 2.1 for the box outline. Users can run the same measurement workflow through CLI or HTTP; both produce quality metrics and optional annotated output. The graph follows documented stages and sampled wiring. Some domain and CLI/API internals were not excerpted, so uncertain implementation links are omitted; README-documented capabilities remain represented.

Main entry points: [`src/box_measurer/application/measure_box.py`](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/measure_box.py) (Measure box), [`src/box_measurer/cli/main.py`](https://github.com/error273/box-measurer/blob/main/src/box_measurer/cli/main.py) (CLI commands), [`src/box_measurer/bootstrap.py`](https://github.com/error273/box-measurer/blob/main/src/box_measurer/bootstrap.py) (Pipeline assembly), [`src/box_measurer/application/segment_box.py`](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/segment_box.py) (Segment box)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
  node_http["FastAPI endpoints<br/>[app.py]"]
  node_api_service["API service<br/>[service.py]"]
end

subgraph group_workflow["Measurement workflow"]
  node_measure["Measure box<br/>[measure_box.py]"]
  node_inspect["Inspect image<br/>[inspect_image.py]"]
  node_detect_usecase["Detect marker<br/>[detect_marker.py]"]
  node_map_plane["Map plane<br/>[map_plane.py]"]
  node_segment_usecase["Segment box<br/>[segment_box.py]"]
end

subgraph group_vision["Vision adapters"]
  node_reader["Safe image reader<br/>[image_reader.py]"]
  node_cv_adapter["OpenCV image adapter<br/>[cv_image.py]"]
  node_sam["SAM 2.1 segmenter"]
end

subgraph group_domain["Geometry and quality"]
  node_marker["ArUco detection<br/>[marker.py]"]
  node_plane["Plane homography<br/>[plane.py]"]
  node_color_segment["Color segmentation<br/>[segmentation.py]"]
  node_dimensions["Dimension estimation<br/>[measurement.py]"]
  node_quality["Quality assessment<br/>[quality.py]"]
end

subgraph group_runtime["Runtime setup"]
  node_config["Application config<br/>[config.py]"]
  node_bootstrap["Pipeline assembly<br/>[bootstrap.py]"]
  node_dataset["Dataset manifest<br/>[dataset.py]"]
end

node_user(("Image user"))

node_user -->|"runs command"| node_cli
node_user -->|"uploads photo"| node_http
node_cli -->|"runs measurement"| node_measure
node_http -->|"routes request"| node_api_service
node_http -->|"builds pipeline"| node_bootstrap
node_api_service -->|"calls scenario"| node_measure
node_cli -->|"runs inspection"| node_inspect
node_cli -->|"runs detection"| node_detect_usecase
node_cli -->|"runs plane mapping"| node_map_plane
node_cli -->|"runs segmentation"| node_segment_usecase
node_bootstrap -->|"assembles"| node_measure
node_bootstrap -->|"assembles"| node_segment_usecase
node_measure -->|"reads image"| node_cv_adapter
node_cv_adapter -->|"checks metadata"| node_reader
node_measure -->|"detects marker"| node_marker
node_measure -->|"validates and scores"| node_quality
node_measure -->|"locates box"| node_sam
node_measure -->|"estimates dimensions"| node_dimensions
node_marker -->|"sets reference scale"| node_plane
node_measure -->|"maps corners"| node_plane
node_sam -->|"uses color hint"| node_color_segment
node_segment_usecase -->|"detects reference"| node_marker
node_segment_usecase -->|"locates mask"| node_sam
node_detect_usecase -->|"detects marker"| node_marker
node_map_plane -->|"gets observation"| node_detect_usecase
node_map_plane -->|"maps reference"| node_plane
node_inspect -.->|"reads image info"| node_reader
node_measure -->|"writes debug image"| node_cv_adapter
node_bootstrap -->|"uses settings"| node_config

click node_cli "https://github.com/error273/box-measurer/blob/main/src/box_measurer/cli/main.py"
click node_http "https://github.com/error273/box-measurer/blob/main/src/box_measurer/api/app.py"
click node_api_service "https://github.com/error273/box-measurer/blob/main/src/box_measurer/api/service.py"
click node_measure "https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/measure_box.py"
click node_inspect "https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/inspect_image.py"
click node_detect_usecase "https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/detect_marker.py"
click node_map_plane "https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/map_plane.py"
click node_segment_usecase "https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/segment_box.py"
click node_reader "https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/image_reader.py"
click node_cv_adapter "https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/cv_image.py"
click node_sam "https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/sam2_segmentation.py"
click node_marker "https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/marker.py"
click node_plane "https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/plane.py"
click node_color_segment "https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/segmentation.py"
click node_dimensions "https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/measurement.py"
click node_quality "https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/quality.py"
click node_config "https://github.com/error273/box-measurer/blob/main/src/box_measurer/config.py"
click node_bootstrap "https://github.com/error273/box-measurer/blob/main/src/box_measurer/bootstrap.py"
click node_dataset "https://github.com/error273/box-measurer/blob/main/src/box_measurer/dataset.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_cli,node_http,node_api_service,node_user toneBlue
class node_measure,node_inspect,node_detect_usecase,node_map_plane,node_segment_usecase toneAmber
class node_reader,node_cv_adapter,node_sam toneMint
class node_marker,node_plane,node_color_segment,node_dimensions,node_quality toneRose
class node_config,node_bootstrap,node_dataset toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/error273/box-measurer/blob/main/src/box_measurer/cli/main.py): `src/box_measurer/cli/main.py`
- [FastAPI endpoints](https://github.com/error273/box-measurer/blob/main/src/box_measurer/api/app.py): `src/box_measurer/api/app.py`
- [API service](https://github.com/error273/box-measurer/blob/main/src/box_measurer/api/service.py): `src/box_measurer/api/service.py`

### Measurement workflow

- [Measure box](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/measure_box.py): `src/box_measurer/application/measure_box.py`
- [Inspect image](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/inspect_image.py): `src/box_measurer/application/inspect_image.py`
- [Detect marker](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/detect_marker.py): `src/box_measurer/application/detect_marker.py`
- [Map plane](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/map_plane.py): `src/box_measurer/application/map_plane.py`
- [Segment box](https://github.com/error273/box-measurer/blob/main/src/box_measurer/application/segment_box.py): `src/box_measurer/application/segment_box.py`

### Vision adapters

- [Safe image reader](https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/image_reader.py): `src/box_measurer/adapters/image_reader.py`
- [OpenCV image adapter](https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/cv_image.py): `src/box_measurer/adapters/cv_image.py`
- [SAM 2.1 segmenter](https://github.com/error273/box-measurer/blob/main/src/box_measurer/adapters/sam2_segmentation.py): `src/box_measurer/adapters/sam2_segmentation.py`

### Geometry and quality

- [ArUco detection](https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/marker.py): `src/box_measurer/domain/marker.py`
- [Plane homography](https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/plane.py): `src/box_measurer/domain/plane.py`
- [Color segmentation](https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/segmentation.py): `src/box_measurer/domain/segmentation.py`
- [Dimension estimation](https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/measurement.py): `src/box_measurer/domain/measurement.py`
- [Quality assessment](https://github.com/error273/box-measurer/blob/main/src/box_measurer/domain/quality.py): `src/box_measurer/domain/quality.py`

### Runtime setup

- [Application config](https://github.com/error273/box-measurer/blob/main/src/box_measurer/config.py): `src/box_measurer/config.py`
- [Pipeline assembly](https://github.com/error273/box-measurer/blob/main/src/box_measurer/bootstrap.py): `src/box_measurer/bootstrap.py`
- [Dataset manifest](https://github.com/error273/box-measurer/blob/main/src/box_measurer/dataset.py): `src/box_measurer/dataset.py`

### Other components

- **Image user**

## Connections

- Image user → CLI commands: runs command (evidence: `README.md`)
- Image user → FastAPI endpoints: uploads photo (evidence: `README.md`)
- CLI commands → Measure box: runs measurement (evidence: `src/box_measurer/cli/main.py`)
- FastAPI endpoints → API service: routes request (evidence: `src/box_measurer/api/app.py`)
- FastAPI endpoints → Pipeline assembly: builds pipeline (evidence: `src/box_measurer/api/app.py`)
- API service → Measure box: calls scenario (evidence: `src/box_measurer/api/service.py`)
- CLI commands → Inspect image: runs inspection (evidence: `src/box_measurer/cli/main.py`)
- CLI commands → Detect marker: runs detection (evidence: `src/box_measurer/cli/main.py`)
- CLI commands → Map plane: runs plane mapping (evidence: `src/box_measurer/cli/main.py`)
- CLI commands → Segment box: runs segmentation (evidence: `README.md`)
- Pipeline assembly → Measure box: assembles (evidence: `src/box_measurer/bootstrap.py`)
- Pipeline assembly → Segment box: assembles (evidence: `src/box_measurer/bootstrap.py`)
- Measure box → OpenCV image adapter: reads image (evidence: `src/box_measurer/bootstrap.py`)
- OpenCV image adapter → Safe image reader: checks metadata (evidence: `src/box_measurer/adapters/cv_image.py`)
- Measure box → ArUco detection: detects marker (evidence: `src/box_measurer/bootstrap.py`)
- Measure box → Quality assessment: validates and scores (evidence: `src/box_measurer/bootstrap.py`)
- Measure box → SAM 2.1 segmenter: locates box (evidence: `src/box_measurer/bootstrap.py`)
- Measure box → Dimension estimation: estimates dimensions (evidence: `src/box_measurer/bootstrap.py`)
- ArUco detection → Plane homography: sets reference scale (evidence: `README.md`)
- Measure box → Plane homography: maps corners (evidence: `README.md`)
- SAM 2.1 segmenter → Color segmentation: uses color hint (evidence: `src/box_measurer/bootstrap.py`)
- Segment box → ArUco detection: detects reference (evidence: `src/box_measurer/application/segment_box.py`)
- Segment box → SAM 2.1 segmenter: locates mask (evidence: `src/box_measurer/bootstrap.py`)
- Detect marker → ArUco detection: detects marker (evidence: `src/box_measurer/application/detect_marker.py`)
- Map plane → Detect marker: gets observation (evidence: `src/box_measurer/application/map_plane.py`)
- Map plane → Plane homography: maps reference (evidence: `src/box_measurer/application/map_plane.py`)
- Inspect image → Safe image reader: reads image info
- Measure box → OpenCV image adapter: writes debug image (evidence: `src/box_measurer/bootstrap.py`)
- Pipeline assembly → Application config: uses settings (evidence: `src/box_measurer/bootstrap.py`)
