# astaranowicz/dcct architecture

> Architecture diagram of the GitHub repository astaranowicz/dcct, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astaranowicz/dcct
- Repository: https://github.com/astaranowicz/dcct

## Overview

##### Project Type and Purpose
- It provides an interactive command-line interface (CLI) in MATLAB to process RGB images and corresponding depth maps, fit geometric primitives (circles, ellipses, spheres), and compute calibration parameters via linear and non-linear minimization.

a. Host Environment
- MATLAB runtime / interpreter (scripts .m files execute here)
b. Entry Point & Configuration
- DCCT_v1_1.m – Main orchestration script (CLI menu, driver)
- DCCT_variables_SetupScript.m – Global default parameters (do not modify)
c. Data I/O
- Data folder – Raw inputs: RGBImage_ball_#.jpg and ball_#.txt (depth vectors)
- Save/Load routines – MATLAB .mat files for intermediate session data
d. RGB Image Processing Module
- f_RGB_imageProcessing.m – Interactive: rectangle selection → Canny edge → Hough circle → RANSAC ellipse fit → user validation
- Hough Transform for Circles toolbox (houghcircles.m and related)
- Ellipse-fitting functions (f_EllipseDirectFit.m, f_ellipseFit_points2Ellipse.m, etc.)
e. Depth Map Processing Module
- f_Depth_imageProcessing.m – Interactive: rectangle selection → depth thresholding → pixel filtering → user validation
- Depth-to-XYZ conversions (f_depth2XYZ.m, f_DepthImage2Depthmap.m)
f. Calibration Core Module
- Linear estimation – “6-point” and “sphere” algorithms (f_sixPointAlgo.m, f_minSphere.m, f_sphereFit_points2Sphere.m, etc.)
- Non-linear minimization – f_nonLinearMinization_6pnt_Conic.m (refines intrinsic, extrinsic, distortion)
- Conic toolbox (conic/*.m) – algebraic routines for conic sections used in sphere/ellipse estimation
- Epipolar Geometry Toolbox (EGT_v2p0) – external dependency for epipolar computations
g. Output & Visualization
- Figures of fitted ellipses on images, depth overlays
- Final calibration parameters (intrinsics, extrinsics, distortion coefficients) written to workspace or saved to file

##### Component Interactions & Data Flow
1) User launches DCCT_v1_1.m in MATLAB
2) Main script reads DCCT_variables_SetupScript for default settings
3) User chooses “new session” or “load previous data”
4) For each RGB-D frame:
– Call RGB Image Processing → returns 2D ellipse parameters
– Call Depth Map Processing → returns 3D point cloud of sphere surface
– Store results in internal data structure
5) Once all frames are processed, pass collected 2D–3D correspondences to Calibration Core
6) Calibration Core performs linear estimation, then non-linear minimization
7) Generate output: calibration parameters, plots
8) Optionally save session data in Data folder

##### Architectural Patterns & Design Principles
- Modular pipeline: clear separation between data acquisition (processing) and algorithmic calibration
- Interactive feedback loop: user-in-the-loop validation for robust feature extraction
- Extensibility points: external toolboxes (conic, EGT, Hough) plugged in as libraries
- Single responsibility: each function/script focuses on one stage

##### Detailed Element Checklist
- Host: MATLAB Environment
- Main Script: DCCT_v1_1.m
- Config: DCCT_variables_SetupScript.m
- RGB Processor: f_RGB_imageProcessing + Hough/Ellipse libs
- Depth Processor: f_Depth_imageProcessing + depth conversion
- Calibration Engine: linear estimators, f_nonLinearMinization_6pnt_Conic
- External Toolboxes: conic/, EGT_v2p0/, HoughTransform
- Data Store: Data/ folder + save/load routines
- Outputs: Calibration parameters + Visualizations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    HOST["MATLAB Environment"]:::host

    %% Entry Point & Configuration
    subgraph "Entry Point & Configuration"
        MAIN["DCCT_v1_1.m"]:::config
        CONFIG["DCCT_variables_SetupScript.m"]:::config
    end

    %% Data I/O
    subgraph "Data I/O"
        RAW["Raw Data (Data/)"]:::input
        MAT[".mat Save/Load (Data/)"]:::input
    end

    %% RGB Image Processing
    subgraph "RGB Image Processing"
        RGB["f_RGB_imageProcessing.m"]:::process
        HOUGH["houghcircles.m"]:::external
        ELLIPSE_DIRECT["f_EllipseDirectFit.m"]:::process
        ELLIPSE_PTS["f_ellipseFit_points2Ellipse.m"]:::process
        ELLIPSE_LS["f_ellipseLinLS.m"]:::process
        ELLIPSE_NL["f_ellipseNonLinLS.m"]:::process
        DRAW_CONIC["f_drawConic.m"]:::process
    end

    %% Depth Map Processing
    subgraph "Depth Map Processing"
        DEPTH_PROC["f_Depth_imageProcessing.m"]:::process
        DEPTH2XYZ["f_depth2XYZ.m"]:::process
        DEPTHMAP["f_DepthImage2Depthmap.m"]:::process
    end

    %% Calibration Core
    subgraph "Calibration Core"
        SIXPT["f_sixPointAlgo.m"]:::process
        MINSPH["f_minSphere.m"]:::process
        SPHFIT["f_sphereFit_points2Sphere.m"]:::process
        NONLIN["f_nonLinearMinization_6pnt_Conic.m"]:::process
    end

    %% External Toolboxes
    subgraph "External Toolboxes"
        CONIC["conic/"]:::external
        EGT["EGT_v2p0/"]:::external
    end

    %% Visualization & Utilities
    subgraph "Visualization & Utilities"
        DRAW_CIRC["DrawCircle.m"]:::process
        PLOT_CONIC["f_plot_conicwparams.m"]:::process
    end

    %% Outputs
    OUTPUT["Calibration Params & Plots"]:::output

    %% Connections
    HOST --> MAIN
    MAIN --> CONFIG
    MAIN --> RAW
    MAIN --> MAT
    MAIN --> RGB
    MAIN --> DEPTH_PROC

    RGB --> HOUGH
    RGB --> ELLIPSE_DIRECT
    RGB --> ELLIPSE_PTS
    RGB --> ELLIPSE_LS
    RGB --> ELLIPSE_NL
    RGB --> DRAW_CONIC

    DEPTH_PROC --> DEPTH2XYZ
    DEPTH_PROC --> DEPTHMAP

    RGB -->|"2D ellipse params"| SIXPT
    DEPTH_PROC -->|"3D point cloud"| SIXPT

    SIXPT --> NONLIN
    NONLIN --> DRAW_CIRC
    NONLIN --> PLOT_CONIC
    NONLIN --> OUTPUT

    SIXPT --> CONIC
    MINSPH --> CONIC
    SPHFIT --> CONIC
    NONLIN --> CONIC
    NONLIN --> EGT

    %% Click Events
    click MAIN "https://github.com/astaranowicz/dcct/blob/v1.2/DCCT_v1_1.m"
    click CONFIG "https://github.com/astaranowicz/dcct/blob/v1.2/DCCT_variables_SetupScript.m"
    click RAW "https://github.com/astaranowicz/dcct/tree/v1.2/Data/"
    click RGB "https://github.com/astaranowicz/dcct/blob/v1.2/f_RGB_imageProcessing.m"
    click HOUGH "https://github.com/astaranowicz/dcct/blob/v1.2/houghcircles.m"
    click ELLIPSE_DIRECT "https://github.com/astaranowicz/dcct/blob/v1.2/f_EllipseDirectFit.m"
    click ELLIPSE_PTS "https://github.com/astaranowicz/dcct/blob/v1.2/f_ellipseFit_points2Ellipse.m"
    click ELLIPSE_LS "https://github.com/astaranowicz/dcct/blob/v1.2/f_ellipseLinLS.m"
    click ELLIPSE_NL "https://github.com/astaranowicz/dcct/blob/v1.2/f_ellipseNonLinLS.m"
    click DRAW_CONIC "https://github.com/astaranowicz/dcct/blob/v1.2/f_drawConic.m"
    click DEPTH_PROC "https://github.com/astaranowicz/dcct/blob/v1.2/f_Depth_imageProcessing.m"
    click DEPTH2XYZ "https://github.com/astaranowicz/dcct/blob/v1.2/f_depth2XYZ.m"
    click DEPTHMAP "https://github.com/astaranowicz/dcct/blob/v1.2/f_DepthImage2Depthmap.m"
    click SIXPT "https://github.com/astaranowicz/dcct/blob/v1.2/f_sixPointAlgo.m"
    click MINSPH "https://github.com/astaranowicz/dcct/blob/v1.2/f_minSphere.m"
    click SPHFIT "https://github.com/astaranowicz/dcct/blob/v1.2/f_sphereFit_points2Sphere.m"
    click NONLIN "https://github.com/astaranowicz/dcct/blob/v1.2/f_nonLinearMinization_6pnt_Conic.m"
    click CONIC "https://github.com/astaranowicz/dcct/tree/v1.2/conic/"
    click EGT "https://github.com/astaranowicz/dcct/tree/v1.2/EGT_v2p0/"
    click DRAW_CIRC "https://github.com/astaranowicz/dcct/blob/v1.2/DrawCircle.m"
    click PLOT_CONIC "https://github.com/astaranowicz/dcct/blob/v1.2/f_plot_conicwparams.m"

    %% Styles
    classDef host fill:#bbbbbb
    classDef config fill:#cc88ff
    classDef input fill:#88ccff
    classDef process fill:#88ff88
    classDef external fill:#ffbb55
    classDef output fill:#ff8888
```
