# 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`).