Speckle-Scanner/PROJECT_CONTEXT.md

Project Architecture: Portable 3D Scanner Pipeline

1. Core Philosophy

This project is a modular 3D scanning and image processing pipeline. It is designed to be 100% portable. It anchors itself to the current user's Home Directory (~/) so it can be copy-pasted onto ANY Ubuntu/Linux machine and run immediately without setting manual paths.

2. The Four Main Folders

Everything revolves around four main directories located in ~/:

1. Source Code (~/Speckle-Scanner/): Contains all Python scripts, separated into pipeline steps (e.g., 04_Rectification, 05_disparity).
2. RAW Data (~/3D-Scans/): The original, untouched input data (images/sensors) categorized by project/date/session/scan.
3. Calibration Data (~/Calib-data/): Intrinsic and extrinsic camera parameters used to correct the images.
4. Processing Data (~/Speckle-Scanner_Processing_data/): The working space where all intermediate outputs are saved.

3. The Pipeline Data Flow (How things move)

Data is processed sequentially inside the Processing Data folder for a specific scan. The Python scripts in the Source Code folder perform the work, but the data itself moves through sequential subfolders.

General Flow Example:

• Step 1: Read raw images from ~/Speckle-Scanner_Processing_data/.../01_raw_images/
• Step 2 (Rectification): Read from 01_raw_images, apply math using Calib-data, and save to .../02_rect_images/
• Step 3 (Disparity): Read from 02_rect_images and save to .../03_disp_images/
• Step 4 (Point Cloud): Read from 03_disp_images and save to .../04_pointcloud/

4. Coding Rules for Cursor

1. NEVER Hardcode Paths: Do not use string paths like /home/yoga/ or C:/.
2. ALWAYS use config.py: Every script must import config.py (using relative imports) to resolve base paths using Path.home().
3. Dynamic Variables: Scripts should accept project, date, session, and scan as arguments or variables, passing them to the config functions to build the exact paths on the fly.
4. Auto-Create Folders: Whenever writing output data, ensure the destination directory is created if it doesn't exist (exist_ok=True).