How hemapriyakst/pallet-alignment works
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 train.py · data.yaml data.yaml · align.py align.py · detect.py detect.py
Components 17
Runtime
Live and batch inference entry points
- align.py · Real-time camera alignment and dashboard overlay
align.py - detect.py · Single-image or non-live pallet detection
detect.py - Camera · Live image input for alignment
- Frame processing · Capture, resize, and prepare frames
- Geometry · Computes center offsets and alignment cues
- Guidance overlay · On-screen bounding boxes, cues, and dashboard
Training
Model development and fine-tuning path
- train.py · Fine-tunes the detector on the pallet dataset
train.py
Data
Dataset boundary and configuration
- data.yaml · Defines class names and dataset locations
data.yaml - train split · Training images and labels
- valid split · Validation images and labels
- test split · Held-out test images and labels
Artifacts
Saved weights and generated outputs
- yolov8n.pt · Starting checkpoint for fine-tuning
- runs/ · Saved weights, logs, and experiment artifacts
- best.pt · Primary model artifact used for inference
Dependencies
External libraries used by the repo
- YOLOv8 detector · Ultralytics inference engine for pallet detection
- OpenCV · Camera I/O and visualization support
- NumPy · Array and geometry calculations
Connections 20
- 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