# loicland/cut-pursuit architecture

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

- Interactive diagram: https://gitdiagram.com/loicland/cut-pursuit
- Repository: https://github.com/loicland/cut-pursuit

## Overview

##### Project type and purpose
- This is an open-source C/C++ library implementing the nonconvex L0-cut pursuit algorithm on weighted graphs, with Matlab (MEX) and Python interfaces. It provides high-performance graph-based segmentation/partitioning and can be embedded in C++, Matlab or Python workflows.

##### High-level file-structure analysis
- Top-level build:
- CMakeLists.txt + cmake/FindNumPy.cmake → orchestration of C++ core and Python wrapper builds
- Core library:
- / → public headers (API.h, Common.h, Graph.h, plus algorithm-specific headers: CutPursuit_*.h)
- src/ → implementation (cutpursuit.cpp) and Python smoke test (test.py)
- Matlab interface:
- mex/ → two MEX entry points (L0_cut_pursuit.cpp, L0_cut_pursuit_segmentation.cpp) that include API.h
- Support files:
- LICENSE, .gitignore, README.md

##### Key points from the README
- Core functionality: L0-cut pursuit for piecewise constant function estimation on graphs
- Supported fidelity terms: quadratic, linear, Kullback–Leibler
- Dependencies: Boost (≥1.58), OpenMP, Eigen3, Python development headers, Matlab MEX API
- Build instructions for C++, Matlab, and Python

##### Components
a. Core C++ Library (“cutpursuit_core”)
- Public API (include/API.h)
- Graph model (include/Graph.h)
- Algorithm implementations (include/CutPursuit_*.h, src/cutpursuit.cpp)
b. Build System (CMake)
- Configuration modules (cmake/FindNumPy.cmake)
- Targets:
- cutpursuit_core (static or shared lib)
- Python wrapper (libcp.so)
- Matlab MEX binaries
c. Matlab MEX Wrappers
- mex/L0_cut_pursuit.cpp → binds C++ API to Matlab
- mex/L0_cut_pursuit_segmentation.cpp → segmentation entry point
d. Python Wrapper
- Generated libcp.so → Python importable module
- src/test.py → example usage and smoke test
e. External Dependencies
- Boost (threading, program_options?)
- OpenMP (parallelism)
- Eigen3 (linear algebra)
- Matlab MEX API
- Python C API / NumPy C API

##### Relationships & interactions
- The build system compiles the core into a library and links it into:
- the Python extension (C API → libcp.so)
- the Matlab MEX binaries
- At runtime:
- Python client calls libcp.so functions via Python-C binding
- Matlab client invokes MEX functions which call the same C++ API
- Data flow inside core:
- User data & graph topology → API.h → Graph class → cut-pursuit routines → result arrays

##### Architectural patterns & design principles
- Single core computation engine (avoid code duplication)
- Thin language-specific bindings (Matlab and Python) that rely exclusively on the C++ public API
- CMake-based multi-language build orchestration
- Separation of concerns:
- Algorithm implementation vs. user interfaces vs. build configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build System"
        direction TB
        CMakeLists["CMakeLists.txt"]:::build
        FindNumPy["cmake/FindNumPy.cmake"]:::build
        srcCMake["src/CMakeLists.txt"]:::build
    end

    subgraph "cutpursuit_core (C++)"
        direction TB
        API["API.h"]:::core
        Common["Common.h"]:::core
        Graph["Graph.h"]:::core
        CutPursuit["CutPursuit.h"]:::core
        L2["CutPursuit_L2.h"]:::core
        KL["CutPursuit_KL.h"]:::core
        Linear["CutPursuit_Linear.h"]:::core
        SPG["CutPursuit_SPG.h"]:::core
        CPImpl["cutpursuit.cpp"]:::core
    end

    subgraph "Matlab MEX module"
        direction TB
        MEX1["L0_cut_pursuit.cpp"]:::wrappers
        MEX2["L0_cut_pursuit_segmentation.cpp"]:::wrappers
    end

    subgraph "Python extension (libcp.so)"
        direction TB
        TestPy["test.py"]:::wrappers
    end

    subgraph "External Dependencies"
        direction TB
        Boost["Boost"]:::ext
        OpenMP["OpenMP"]:::ext
        Eigen3["Eigen3"]:::ext
        MatlabAPI["Matlab MEX API"]:::ext
        PythonAPI["Python/NumPy C API"]:::ext
    end

    subgraph "Clients"
        direction TB
        PyClient["Python Client"]:::client
        MatClient["Matlab Client"]:::client
    end

    %% Build relationships
    CMakeLists -->|"configures"| API
    CMakeLists -->|"builds"| CPImpl
    CMakeLists -->|"builds"| TestPy
    CMakeLists -->|"builds"| MEX1
    CMakeLists -->|"builds"| MEX2
    FindNumPy -->|"provides API"| TestPy
    srcCMake -->|"orchestrates"| CPImpl

    %% External dependencies
    Boost -->|used by| CMakeLists
    OpenMP -->|used by| CMakeLists
    Eigen3 -->|used by| CMakeLists
    MatlabAPI -->|used by| CMakeLists
    PythonAPI -->|used by| FindNumPy

    Boost -->|links to| API
    OpenMP -->|links to| CPImpl
    Eigen3 -->|links to| CPImpl

    %% Runtime data flow
    PyClient -->|"import libcp.so"| TestPy
    TestPy -->|"NumPy C API"| CPImpl
    MatClient -->|"invoke MEX API"| MEX1
    MatClient -->|"invoke MEX API"| MEX2
    MEX1 -->|"C++ API"| CPImpl
    MEX2 -->|"C++ API"| CPImpl

    %% Data pipeline inside core
    API -->|"graph data"| Graph
    Graph -->|"calls"| CPImpl
    CPImpl -->|"returns results"| Graph
    Graph -->|"provides output"| API

    %% Click events
    click API "https://github.com/loicland/cut-pursuit/blob/master/include/API.h"
    click Common "https://github.com/loicland/cut-pursuit/blob/master/include/Common.h"
    click Graph "https://github.com/loicland/cut-pursuit/blob/master/include/Graph.h"
    click CutPursuit "https://github.com/loicland/cut-pursuit/blob/master/include/CutPursuit.h"
    click L2 "https://github.com/loicland/cut-pursuit/blob/master/include/CutPursuit_L2.h"
    click KL "https://github.com/loicland/cut-pursuit/blob/master/include/CutPursuit_KL.h"
    click Linear "https://github.com/loicland/cut-pursuit/blob/master/include/CutPursuit_Linear.h"
    click SPG "https://github.com/loicland/cut-pursuit/blob/master/include/CutPursuit_SPG.h"
    click CPImpl "https://github.com/loicland/cut-pursuit/blob/master/src/cutpursuit.cpp"
    click CMakeLists "https://github.com/loicland/cut-pursuit/blob/master/CMakeLists.txt"
    click FindNumPy "https://github.com/loicland/cut-pursuit/blob/master/cmake/FindNumPy.cmake"
    click srcCMake "https://github.com/loicland/cut-pursuit/blob/master/src/CMakeLists.txt"
    click MEX1 "https://github.com/loicland/cut-pursuit/blob/master/mex/L0_cut_pursuit.cpp"
    click MEX2 "https://github.com/loicland/cut-pursuit/blob/master/mex/L0_cut_pursuit_segmentation.cpp"
    click TestPy "https://github.com/loicland/cut-pursuit/blob/master/src/test.py"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef wrappers fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef build fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef ext fill:#eeeeee,stroke:#757575,color:#424242;
    classDef client fill:#f0f4c3,stroke:#827717,color:#33691e;
```
