How loicland/cut-pursuit works
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