# mayankm96/stereo-odometry-soft architecture

> Architecture diagram of the GitHub repository mayankm96/stereo-odometry-soft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mayankm96/stereo-odometry-soft
- Repository: https://github.com/mayankm96/stereo-odometry-soft

## Overview

##### Project type and purpose
- This is an academic/open‐source MATLAB implementation of a stereo‐odometry algorithm (“SOFT”) that processes synchronized left/right image pairs over time to estimate camera motion.
- It is not a client-server or full-stack app but rather a data‐processing pipeline implemented as MATLAB scripts and functions, orchestrated by main.m and visualSOFT.m.

##### File structure
- Top-level:
– README.md, LICENSE.md, .gitignore
– code/ directory containing config, functions, main scripts
– data/ directory holding input images and calibration files
– images/ directory holding documentation figures
- code/config:
– configFile.m defines camera parameters, bucket sizes, thresholds, etc.
- code/functions:
– featureProcessing: filters (blob, checkerboard, Sobel), descriptor computation, non-max suppression
– featureMatching: match SAD, circular matching, NCC verification, outlier removal
– featureSelection: bucketFeatures (uniform distribution)
– triangulation: linearTriangulation, cross2Matrix
– updateMotion: updateMotionP3P (P3P + RANSAC)
– utils: createCamProjectionMatrices, plotting/visualization helpers
- code/main.m and code/visualSOFT.m orchestrate the end-to-end pipeline and plotting.

##### README for additional insights
- The README outlines a 5‐stage pipeline: feature processing → feature matching → feature selection → egomotion estimation (triangulation + P3P) → visualization.
- It calls out MATLAB toolboxes (Parallel Processing, Computer Vision) as external dependencies.

- Input Data Loader
- Configuration Module
- Feature Processing
- Feature Matching
- Feature Selection
- Triangulation & Motion Estimation
- Visualization / Output
- External MATLAB Toolboxes (annotated as “Parallel Processing Toolbox” and “Computer Vision Toolbox”)
b. Relationships and data flow:
c. Architectural patterns/design principles:
- Pipeline pattern: sequential processing of image data.
- Modular design: each stage is a separate folder of functions.
- Reuse of utils (projection matrix creation, plotting) across modules.
- Parameter‐driven behavior (configFile.m).
d. Technologies & frameworks:
- MATLAB R2018a
- MATLAB toolboxes as external services
- Algorithmic modules implemented as .m functions grouped by responsibility

3. Next, a rectangle “Feature Matching” with sublabels: SAD matching, circular strategy, NCC outlier removal.
4. Then “Feature Selection” (bucketFeatures).
5. Then “Triangulation & P3P ‑ Motion Estimation” grouping code/functions/triangulation and updateMotion.
6. Finally, a “Visualization” block calling visualSOFT and utils plotting functions.

##### Emphasizing essential architectural elements
- Parameter flow from configFile into each stage.
- Pipeline ordering and key data transformations (raw images → keypoints → matches → 3D points → pose).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Input
    DataLoader["Image Loader\n(raw stereo frames)"]:::data
    %% Processing Modules
    FeatureProcessing["Feature Processing"]:::process
    FeatureMatching["Feature Matching"]:::process
    FeatureSelection["Feature Selection"]:::process
    TriangulationMotion["Triangulation &\nMotion Estimation"]:::process
    Visualization["Visualization / Output"]:::data

    %% Configuration
    Config["Configuration\n(configFile.m)"]:::config

    %% External Dependencies
    CVToolbox["Computer Vision Toolbox"]:::external
    PPToolbox["Parallel Processing Toolbox"]:::external

    %% Pipeline flow
    DataLoader -->|raw images| FeatureProcessing
    FeatureProcessing -->|keypoints & descriptors| FeatureMatching
    FeatureMatching -->|matched features| FeatureSelection
    FeatureSelection -->|selected features| TriangulationMotion
    TriangulationMotion -->|pose estimates| Visualization

    %% Config injection
    Config -.-> FeatureProcessing
    Config -.-> FeatureMatching
    Config -.-> FeatureSelection
    Config -.-> TriangulationMotion
    Config -.-> Visualization

    %% External toolbox usage
    FeatureProcessing -.->|uses| CVToolbox
    FeatureMatching -.->|uses| CVToolbox
    FeatureProcessing -.->|parallel loops| PPToolbox
    FeatureMatching -.->|parallel loops| PPToolbox
    FeatureSelection -.->|parallel loops| PPToolbox

    %% Click events
    click DataLoader "https://github.com/mayankm96/stereo-odometry-soft/tree/master/data/"
    click DataLoader "https://github.com/mayankm96/stereo-odometry-soft/blob/master/code/main.m"
    click Config "https://github.com/mayankm96/stereo-odometry-soft/blob/master/code/config/configFile.m"
    click FeatureProcessing "https://github.com/mayankm96/stereo-odometry-soft/tree/master/code/functions/featureProcessing/"
    click FeatureMatching "https://github.com/mayankm96/stereo-odometry-soft/tree/master/code/functions/featureMatching/"
    click FeatureSelection "https://github.com/mayankm96/stereo-odometry-soft/blob/master/code/functions/featureSelection/bucketFeatures.m"
    click TriangulationMotion "https://github.com/mayankm96/stereo-odometry-soft/tree/master/code/functions/triangulation/"
    click TriangulationMotion "https://github.com/mayankm96/stereo-odometry-soft/blob/master/code/functions/updateMotion/updateMotionP3P.m"
    click Visualization "https://github.com/mayankm96/stereo-odometry-soft/blob/master/code/visualSOFT.m"
    click Visualization "https://github.com/mayankm96/stereo-odometry-soft/tree/master/code/functions/utils/"

    %% Styling
    classDef data fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:2px;
    classDef process fill:#DFFFD0,stroke:#228B22,color:#228B22,stroke-width:2px;
    classDef config fill:#FFF5B1,stroke:#D4A017,color:#D4A017,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#606060,color:#606060,stroke-width:2px;
```
