VisionMeasure AI

Real-time computer vision dimensional measurement system using a standard webcam and an A4 paper calibration reference.

---

Overview

VisionMeasure AI transforms a standard USB webcam into a real-time dimensional measurement tool. Positioned above a dark surface, the system uses an A4 paper sheet (210 mm × 297 mm) as a physical calibration reference to calculate real-world physical metrics:

• Length & Width (in mm and cm)
• Planar Surface Area (in mm² and cm²)
• Orientation Angle (in degrees)
• Center Coordinates (in mm)

Using Classical Computer Vision (OpenCV + NumPy), the software runs efficiently on any CPU without GPU or deep learning overhead.

---

Visual Pipeline

       WEBCAM (720 mm height)
                 │
                 ▼
     ┌───────────────────────┐
     │  Measurement Zone ROI │ Selective Region
     └───────────┬───────────┘
                 │
  ┌──────────────┴──────────────┐
  ▼                             ▼
┌──────────────────┐   ┌──────────────────────────┐
│ CALIBRATION MODE │   │ MEASUREMENT MODE         │
│ (Place A4 Paper) │   │ (Place Any Object)       │
└────────┬─────────┘   └────────────┬─────────────┘
         │                          │
         ▼                          ▼
┌──────────────────┐   ┌──────────────────────────┐
│ Find 4 Corners   │   │ Foreground Segmentation  │
└────────┬─────────┘   └────────────┬─────────────┘
         │                          │
         ▼                          ▼
┌─────────────────────────────────────────────────┐
│ Perspective Homography Transformation Matrix (H)│
└────────────────────────┬────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│  Real-World Millimeter Physical Dimensions     │
└────────────────────────┬────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│  Temporal Median Filter & HUD Overlay Dashboard │
└─────────────────────────────────────────────────┘

---

Features

• 🎯 A4 Perspective Calibration: Automatic 4-corner detection computes a homography matrix ($H$) to correct lens tilt and transform pixels into real-world millimeters.
• 📐 Measurement Zone ROI: User-defined rectangular region isolates the measurement surface and rejects surrounding background artifacts (floor tiles, furniture, shadows).
• ⏱️ Stationary & Moving Object Support: Operates continuously without relying on motion detection or frame differencing.
• 📊 Temporal Stabilization: 15-frame rolling median filter smooths sensor noise, displaying real-time STABLE ✓ status when measurement variation is $<1.5%$.
• 🔒 Measurement Locking: Freeze stable measurements on screen with a single keypress (L) for easy inspection and logging.
• 🏷️ Multi-Object Mode: Measures multiple objects inside the measurement zone simultaneously.
• 📏 Millimeter Ruler Scales: Renders physical ruler tick marks directly along the borders of the measurement ROI.
• 🧪 Synthetic Testing Mode: Includes a built-in frame generator to test and demonstrate the system without physical hardware.

---

Quick Start

1. Clone & Install

git clone https://github.com/your-username/VisionMeasure-AI.git
cd VisionMeasure-AI

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Run Application

# Run with physical USB webcam
python src/main.py --camera-index 0

# Or run in Synthetic Test Mode (no camera required)
python src/main.py --synthetic

---

Simple 4-Step Setup Workflow

  1. DEFINE ROI ──► 2. PLACE A4 ──► 3. CALIBRATE ──► 4. MEASURE OBJECT
 (Drag Rectangle)   (White Paper)     (Press 'C')       (Read Metrics)

1. Define Measurement Zone (Z): Drag your mouse on the live video window to draw a box around your black mat.
2. Place A4 Paper: Place a standard white A4 paper sheet ($210 \times 297\text{ mm}$) inside the measurement zone.
3. Calibrate (C): Press C. The system detects the A4 corners, calculates calibration, and saves it. Remove the A4 paper.
4. Place & Measure Object: Place any object inside the measurement zone. Read continuous real-world metrics on the HUD overlay!

---

Keyboard Controls

Key	Action
A	Auto-Detect dark mat boundary for ROI
Z	Interactively draw / reset Measurement Zone ROI
C	Calibrate A4 paper reference sheet
O	Toggle Single-Object / Multi-Object Mode
L	Lock current measurement on screen (LOCKED 🔒)
U	Unlock measurement tracking
M	Cycle synthetic test shapes (Rectangle $\rightarrow$ Smartphone $\rightarrow$ Multiple)
S	Save measurement report to data/measurements/*.json
R	Reset calibration and temporal buffers
Q / Esc	Quit application

---

Example JSON Output Report

Saved reports (data/measurements/*.json) contain structured physical measurements:

{
  "timestamp": "20260813_120000",
  "count": 1,
  "measurements": [
    {
      "length_mm": 151.35,
      "width_mm": 81.71,
      "length_cm": 15.14,
      "width_cm": 8.17,
      "area_mm2": 12239.08,
      "area_cm2": 122.39,
      "orientation_deg": 14.9,
      "center_mm": [104.68, 148.15],
      "stability_pct": 100.0,
      "status": "STABLE ✓"
    }
  ]
}

---

Accuracy & Limitations

• Accuracy: Benchmark tests achieve $<1.6%$ measurement error ($\sim 2\text{ mm}$ precision on a standard 720p webcam at 72 cm height).
• 2D Planar Area: Homography calibration establishes a 2D reference plane ($Z = 0$) on the table surface. A single monocular RGB camera measures planar 2D dimensions. Arbitrary 3D height recovery requires depth sensors or stereo cameras.

---

Project Structure

VisionMeasure-AI/
├── README.md                  # Main documentation
├── LICENSE                    # MIT License
├── CONTRIBUTING.md            # Guidelines for open-source contributions
├── requirements.txt           # Clean dependencies
├── config/
│   └── camera.yaml            # Camera height, ROI, and threshold settings
├── calibration/
│   ├── detect_a4.py           # A4 corner detection & aspect ratio validation
│   ├── homography.py          # Homography transformation matrix (pixels <-> mm)
│   ├── calibrate_camera.py    # Chessboard intrinsic camera calibration
│   └── validate_accuracy.py   # Physical accuracy benchmark validator
├── camera/
│   └── webcam.py              # USB camera interface & synthetic frame stream
├── measurement/
│   ├── geometry.py            # Point ordering, border checks, & TemporalStabilizer
│   ├── object_detector.py     # ROI cropping, thresholding, & object detection
│   ├── contour_measurement.py # Metric conversion engine (Length, Width, Angle)
│   └── area.py                # Planar 2D surface area calculation
├── ui/
│   └── measurement_view.py    # OpenCV HUD overlay renderer with ruler scales
├── docs/
│   └── ARCHITECTURE.md        # Technical mathematics & deep-dive pipeline guide
├── examples/
│   └── sample_measurement.json# Example output report
├── tests/                     # Pytest suite
└── src/
    └── main.py                # Main CLI application entry point

---

Contributing

Contributions are welcome! Please review CONTRIBUTING.md for details on submitting bug reports, feature requests, and pull requests.

---

License

Distributed under the MIT License. See LICENSE for details.