# hemapriyakst/pallet-alignment architecture

> Architecture diagram of the GitHub repository hemapriyakst/pallet-alignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemapriyakst/pallet-alignment
- Repository: https://github.com/hemapriyakst/pallet-alignment

## Overview

1. **Project purpose**
   - This repo is a small computer-vision application focused on **pallet detection and alignment guidance** for a robotic forklift.
   - It is not a full robotics stack; the core boundary is **camera input → YOLO detection → alignment logic → visual/command output**.

2. **Primary runtime paths**
   - There are three distinct execution modes:
     - **`align.py`**: the main real-time loop for live camera alignment and dashboard overlay.
     - **`detect.py`**: single-image or non-live detection utility.
     - **`train.py`**: model fine-tuning on the pallet dataset.
   - These scripts are the main architecture entry points.

3. **Live alignment pipeline**
   - `align.py` is the operational heart of the system.
   - Likely flow: **camera frame capture → YOLOv8 inference → pallet bounding box extraction → geometry-based offset/distance estimation → movement guidance → on-screen visualization**.
   - The output is intended to be consumed by a human operator or downstream robot control logic, but in this repo it appears as **real-time visual guidance**, not direct hardware control.

4. **Detection subsystem**
   - The detection subsystem is built around **Ultralytics YOLOv8**.
   - The model is fine-tuned from **`yolov8n.pt`** and used to detect pallet instances in frames or images.
   - This subsystem is shared conceptually by both `align.py` and `detect.py`, but one is optimized for continuous streaming and the other for one-off inference.

5. **Training subsystem**
   - `train.py` is the model development path.
   - It consumes the dataset described by `data.yaml` and produces training artifacts under `runs/`, including the best model weights.
   - This creates the model artifact that the runtime scripts use for inference.

6. **Dataset boundary**
   - The dataset is stored locally in the standard YOLO folder split:
     - `train/`
     - `valid/`
     - `test/`
   - `data.yaml` defines the dataset class names and locations, so it acts as the configuration boundary between the raw dataset and the training pipeline.

7. **Model artifacts and outputs**
   - `runs/` contains training outputs, logs, and the trained weights such as `best.pt`.
   - Runtime scripts depend on these generated artifacts, while training depends on the dataset and base weights.
   - This separates **offline model preparation** from **online inference**.

8. **External dependencies**
   - The architecture relies on:
     - **Python 3.x** as the runtime
     - **Ultralytics YOLOv8** for detection
     - **OpenCV** for camera I/O and visualization
     - **NumPy** for numeric geometry and frame-related calculations
   - The dataset originates from **Roboflow**, but the repo is otherwise self-contained.

9. **Data and control flow**
   - The main control flow is image-centric:
     - camera/frame input
     - object detection
     - position estimation relative to image center or target alignment point
     - guidance output
   - The system is likely computing left/right/forward/backward correction cues from pallet fork-opening placement in the frame.

10. **Visualization layer**
    - The README explicitly mentions a **live dashboard**, so the UI layer is embedded in `align.py`.
    - This is not a separate frontend service; visualization is part of the same process as capture and inference.
    - That means the architecture is a **single-process, real-time CV loop** rather than a distributed system.

11. **Repository structure implications**
    - The repo is intentionally compact:
      - one script for training
      - one for batch/single-image inference
      - one for live alignment
      - one dataset config
      - dataset folders and model artifacts
    - There are no signs of a database, message queue, API server, or robotics middleware in this repo.

12. **What to show in an architecture diagram**
    - A useful diagram should emphasize four layers:
      - **Dataset + model training**: `train/`, `valid/`, `test/`, `data.yaml`, `train.py`
      - **Model artifact**: `runs/` / trained YOLO weights
      - **Inference apps**: `align.py`, `detect.py`
      - **Runtime I/O**: camera frames in, bounding boxes and alignment guidance out
    - The main dependency arrow is from **training artifacts to inference scripts**.

13. **Architectural summary**
    - This is a **computer-vision alignment utility** built around a **fine-tuned YOLOv8 detector**.
    - Its core design is a tight loop that transforms live images into pallet location estimates and alignment instructions, with training and inference cleanly separated by the saved model weights.

Main entry points: [`train.py`](https://github.com/hemapriyakst/pallet-alignment/blob/main/train.py) (train.py), [`data.yaml`](https://github.com/hemapriyakst/pallet-alignment/blob/main/data.yaml) (data.yaml), [`align.py`](https://github.com/hemapriyakst/pallet-alignment/blob/main/align.py) (align.py), [`detect.py`](https://github.com/hemapriyakst/pallet-alignment/blob/main/detect.py) (detect.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_align_py["align.py<br/>live alignment loop<br/>[align.py]"]
  node_detect_py["detect.py<br/>inference utility<br/>[detect.py]"]
  node_camera(("Camera<br/>frame source"))
  node_frame_proc["Frame processing<br/>cv pipeline"]
  node_geometry["Geometry<br/>offset estimation"]
  node_guidance["Guidance overlay<br/>visual output"]
end

subgraph group_training["Training"]
  node_train_py["train.py<br/>training script<br/>[train.py]"]
end

subgraph group_data["Data"]
  node_data_yaml["data.yaml<br/>dataset config<br/>[data.yaml]"]
  node_train_split[("train split<br/>image set")]
  node_valid_split[("valid split<br/>image set")]
  node_test_split[("test split<br/>image set")]
end

subgraph group_artifacts["Artifacts"]
  node_yolov8n_pt["yolov8n.pt<br/>base weights"]
  node_runs_dir[("runs/<br/>training outputs")]
  node_best_pt["best.pt<br/>trained weights"]
end

subgraph group_deps["Dependencies"]
  node_yolo_model{{"YOLOv8 detector<br/>detector core"}}
  node_opencv{{"OpenCV<br/>vision library"}}
  node_numpy{{"NumPy<br/>numeric library"}}
end

node_train_split -->|"listed in"| node_data_yaml
node_valid_split -->|"listed in"| node_data_yaml
node_test_split -->|"listed in"| node_data_yaml
node_data_yaml -->|"configures"| node_train_py
node_yolov8n_pt -->|"seed model"| node_train_py
node_train_py -->|"writes"| node_runs_dir
node_runs_dir -->|"contains"| node_best_pt
node_best_pt -->|"loads"| node_align_py
node_best_pt -->|"loads"| node_detect_py
node_camera -->|"feeds"| node_frame_proc
node_frame_proc -->|"uses"| node_opencv
node_frame_proc -->|"inference"| node_yolo_model
node_best_pt -->|"weights"| node_yolo_model
node_yolo_model -->|"boxes"| node_geometry
node_geometry -->|"calculates"| node_numpy
node_geometry -->|"produces"| node_guidance
node_guidance -->|"renders"| node_opencv
node_align_py -->|"orchestrates"| node_frame_proc
node_detect_py -->|"orchestrates"| node_yolo_model
node_train_py -->|"trains"| node_yolo_model

click node_align_py "https://github.com/hemapriyakst/pallet-alignment/blob/main/align.py"
click node_detect_py "https://github.com/hemapriyakst/pallet-alignment/blob/main/detect.py"
click node_train_py "https://github.com/hemapriyakst/pallet-alignment/blob/main/train.py"
click node_data_yaml "https://github.com/hemapriyakst/pallet-alignment/blob/main/data.yaml"

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_align_py,node_detect_py,node_camera,node_frame_proc,node_geometry,node_guidance toneBlue
class node_train_py toneAmber
class node_data_yaml,node_train_split,node_valid_split,node_test_split toneMint
class node_yolov8n_pt,node_runs_dir,node_best_pt toneRose
class node_yolo_model,node_opencv,node_numpy toneIndigo
```

## Components

### Runtime

Live and batch inference entry points

- [align.py](https://github.com/hemapriyakst/pallet-alignment/blob/main/align.py): live alignment loop · Real-time camera alignment and dashboard overlay · `align.py`
- [detect.py](https://github.com/hemapriyakst/pallet-alignment/blob/main/detect.py): inference utility · Single-image or non-live pallet detection · `detect.py`
- **Camera**: frame source · Live image input for alignment
- **Frame processing**: cv pipeline · Capture, resize, and prepare frames
- **Geometry**: offset estimation · Computes center offsets and alignment cues
- **Guidance overlay**: visual output · On-screen bounding boxes, cues, and dashboard

### Training

Model development and fine-tuning path

- [train.py](https://github.com/hemapriyakst/pallet-alignment/blob/main/train.py): training script · Fine-tunes the detector on the pallet dataset · `train.py`

### Data

Dataset boundary and configuration

- [data.yaml](https://github.com/hemapriyakst/pallet-alignment/blob/main/data.yaml): dataset config · Defines class names and dataset locations · `data.yaml`
- **train split**: image set · Training images and labels
- **valid split**: image set · Validation images and labels
- **test split**: image set · Held-out test images and labels

### Artifacts

Saved weights and generated outputs

- **yolov8n.pt**: base weights · Starting checkpoint for fine-tuning
- **runs/**: training outputs · Saved weights, logs, and experiment artifacts
- **best.pt**: trained weights · Primary model artifact used for inference

### Dependencies

External libraries used by the repo

- **YOLOv8 detector**: detector core · Ultralytics inference engine for pallet detection
- **OpenCV**: vision library · Camera I/O and visualization support
- **NumPy**: numeric library · Array and geometry calculations

## Connections

- train split → data.yaml: listed in · Dataset split referenced by the YOLO data config
- valid split → data.yaml: listed in · Validation split referenced by the YOLO data config
- test split → data.yaml: listed in · Test split referenced by the YOLO data config
- data.yaml → train.py: configures · Provides class names and dataset paths for training
- yolov8n.pt → train.py: seed model · Base checkpoint used to fine-tune the detector
- train.py → runs/: writes · Produces training logs and experiment outputs
- runs/ → best.pt: contains · Best-performing trained weights are stored in runs
- best.pt → align.py: loads · Live alignment uses the trained detector weights
- best.pt → detect.py: loads · Batch detection uses the trained detector weights
- Camera → Frame processing: feeds · Live frames enter the alignment loop
- Frame processing → OpenCV: uses · Capture and display operations rely on OpenCV
- Frame processing → YOLOv8 detector: inference · Prepared frames are passed to YOLOv8 for detection
- best.pt → YOLOv8 detector: weights · YOLOv8 runs with the fine-tuned pallet weights
- YOLOv8 detector → Geometry: boxes · Detection outputs are converted into alignment measurements
- Geometry → NumPy: calculates · Numeric offset and distance computations
- Geometry → Guidance overlay: produces · Alignment cues are rendered to the operator
- Guidance overlay → OpenCV: renders · Visual overlays are shown through OpenCV
- align.py → Frame processing: orchestrates · Main live loop coordinates capture and processing
- detect.py → YOLOv8 detector: orchestrates · Single-image inference drives the detector directly
- train.py → YOLOv8 detector: trains · Training process fine-tunes the detector model