1. Executive Summary
PixelScope Standalone is a standalone, browser-based application designed for precise photogrammetry and object measurement within digital images. Unlike server-dependent solutions, this application runs entirely on the client side (HTML5/JavaScript), ensuring high performance, data privacy, and offline capability.
The core functionality allows users to upload images, perform perspective correction (warping) to simulate a top-down view, calibrate scale using reference lines, and measure real-world dimensions with sub-millimeter accuracy depending on image resolution.
2. Technical Architecture
Core Philosophy: "Standalone-First" - The application loads libraries once and caches them, allowing full functionality without an internet connection after the initial load.
Technology Stack
- Frontend Framework: Vanilla JavaScript (ES6+) or Lightweight Library (Vue/React) for state management.
- Image Processing Engine: OpenCV.js (loaded via CDN, cached locally). Handles Homography matrices and pixel coordinate mapping.
- Rendering Layer: HTML5 Canvas API. Used for rendering images, drawing interactive lines/points, and applying transformations.
- Data Storage: LocalStorage / IndexedDB to save project states (image data + calibration) so users can resume work without re-uploading immediately.
System Requirements
| Requirement |
Specification |
| Image Upload Limit |
Max Resolution: 5000 x 5000 pixels (approx. 25MP) |
| File Format |
JPG, PNG, BMP |
| Browser Support |
Chrome 80+, Firefox 75+, Safari 13+ |
3. User Workflow & Features
Phase 1: Image Ingestion
The user initiates the process by uploading an image via a drag-and-drop interface or file browser.
- Validation: The system checks if dimensions exceed 5000px. If so, it prompts for resizing or compression.
- Preview: A thumbnail and resolution metadata are displayed immediately upon load.
Phase 2: Perspective Correction (Warping)
To measure an object accurately, the image must be "flattened" to a top-down view. The user defines four corner points on the image representing the true corners of the object.
- Control Points: 4 draggable handles appear at the corners.
- Transformation: The system calculates a Homography Matrix and applies `cv.warpPerspective` to create a flat, undistorted view of the object.
Phase 3: Calibration (Scale Definition)
This is the most critical step. The user must define what "1 pixel" equals in real life.
- Select Tool: User chooses the "Calibration Line" tool.
- Draw Reference: Draw a line over an object of known length (e.g., a ruler, door frame).
- Input Real Length: Enter the physical measurement (e.g., 2.0 meters).
- Average & RMS: The system calculates the average scale factor and Root Mean Square (RMS) error if multiple lines are used.
Phase 4: Measurement
Once calibrated, the user can measure any other object in the image.
- Select Unit: Choose from Meters (m), Centimeters (cm), Millimeters (mm), Inches (in), or Feet (ft).
- Click-to-Measure: Click Point A and Point B. The system calculates the pixel distance, applies the scale factor, and displays the result.
Phase 5: Navigation
The canvas supports infinite panning (drag) and zooming (scroll wheel), allowing detailed inspection of large images without losing resolution context.
4. Mathematical Logic
A. Scale Factor Calculation ($S$)
The core of the application is determining the scale factor $S$. This relates pixel distance to real-world distance.
S = RealLength / PixelLength
B. RMS Error Calculation
To ensure high accuracy, we use multiple reference lines (n). We calculate the Root Mean Square error to validate the calibration quality.
| Variable | Description |
|---|
| $L_{real, i}$ | The real-world length of reference line $i$ (e.g., 2.5m) |
| $P_{pix, i}$ | The pixel length measured on the warped image for line $i$ |
| $\bar{S}$ | The average scale factor calculated from all lines |
Step 1: Calculate Mean Scale ($\bar{S}$)
$$ \bar{S} = \frac{\sum_{i=1}^{n} (L_{real, i})}{\sum_{i=1}^{n} (P_{pix, i})} $$
Step 2: Calculate RMS Error
$$ RMS = \sqrt{ \frac{\sum_{i=1}^{n} (L_{real, i} - P_{pix, i} \times \bar{S})^2}{n} } $$
Interpretation:
If RMS Error is < 1%, the calibration is excellent.
If RMS Error is between 1% - 5%, it is acceptable for general use.
If RMS Error > 5%, check if reference lines are straight or if perspective warping was imperfect.
C. Final Measurement
When measuring a new object with pixel distance $P_{new}$:
$$ L_{final} = P_{new} \times \bar{S} $$
5. UI/UX Design Guidelines
The interface is designed to be distraction-free and focused on the canvas.
Layout Structure
- Center Stage: Full-screen Canvas (Image + Overlays). This is where all interaction happens.
- Left Sidebar: Tool Palette. Contains buttons for Upload, Warp, Measure, Calibrate, and Units.
- Right Sidebar: Properties Panel. Displays current Scale Factor, RMS Error, Pixel Count, and Unit Selector.
Visual Feedback
- Calibration Status: A green bar indicates "Good Calibration" (Low RMS), while a red bar warns of high error.
- Interactive Lines: Reference lines glow blue when selected, and measurement lines appear in orange upon creation.
Theme
A "Dark Mode" default theme is recommended to reduce eye strain during long sessions of detailed measurement work.
6. Implementation Roadmap
Phase 1 (Weeks 1-3): MVP Core
Setup HTML/CSS skeleton, basic image loader with validation (<5000px), and Canvas Pan/Zoom functionality.
Phase 2 (Weeks 4-6): Core Logic
Integrate OpenCV.js for perspective warping. Implement the Calibration Line tool and RMS Error calculation logic. Add Unit Converter mapping.
Phase 3 (Weeks 7-8): Polish
Refine UI/UX, add error handling (e.g., "Image too large"), and implement Service Workers for offline caching.
Phase 4 (Week 9+): Deployment
Cross-browser testing, performance optimization on low-end devices, and packaging as a downloadable `.zip` or hosting via static site.
7. Deliverables & Deployment
The final product will be delivered as a single, portable solution.
- Source Code: Modular JavaScript/HTML/CSS files ready for deployment.
- Documentation: This whitepaper included in the package.
- Offline Installer (Optional): A `.zip` file containing all assets, allowing users to run the app from a USB drive or local folder without internet.
Future Enhancements
- Multi-Image Stitching: Combining multiple photos of an object into one 3D model.
- Export Reports: Generating a PDF report with screenshots and measurement logs.