{"id":51062396,"url":"https://github.com/sebsop/kmeans-thesis-segmentation","last_synced_at":"2026-06-23T03:34:05.959Z","repository":{"id":344667240,"uuid":"1182336497","full_name":"sebsop/kmeans-thesis-segmentation","owner":"sebsop","description":"Real-time hybrid quantum-classical K-means segmentation using C++ and CUDA. Bachelor's Thesis at BBU bridging HPC and Quantum Machine Learning (QML).","archived":false,"fork":false,"pushed_at":"2026-06-19T20:46:38.000Z","size":1922,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T03:34:05.106Z","etag":null,"topics":["cpp","cuda","hpc","imgui","kmeans","opencv","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sebsop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T11:34:44.000Z","updated_at":"2026-06-19T20:46:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sebsop/kmeans-thesis-segmentation","commit_stats":null,"previous_names":["dosqas/kmeans-thesis-segmentation","sebsop/kmeans-thesis-segmentation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sebsop/kmeans-thesis-segmentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebsop%2Fkmeans-thesis-segmentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebsop%2Fkmeans-thesis-segmentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebsop%2Fkmeans-thesis-segmentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebsop%2Fkmeans-thesis-segmentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebsop","download_url":"https://codeload.github.com/sebsop/kmeans-thesis-segmentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebsop%2Fkmeans-thesis-segmentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34674702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","cuda","hpc","imgui","kmeans","opencv","quantum-computing"],"created_at":"2026-06-23T03:34:05.304Z","updated_at":"2026-06-23T03:34:05.953Z","avatar_url":"https://github.com/sebsop.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Real-Time Quantum-Inspired 5D K-Means Image Segmentation\n\nA high-performance computer vision system for real-time image segmentation, featuring a GPU-accelerated architecture (CUDA) utilizing quantum-inspired distance metrics.\n\n## Academic Context\n\nThis project was developed as the core practical component for my **Bachelor's Thesis at Babeș-Bolyai University**. \n\nHaving started my journey into Quantum Computing during my second year of study and subsequently completing various projects in the field, integrating quantum principles into my final thesis was a personal \"must-have.\" This project represents a convergence of my interests in high-performance computing, computer vision, and quantum mechanics, serving as a foundation for my future research goals in **Quantum Machine Learning (QML)**.\n\nThe fundamental architecture evolved from a previous academic project completed during my *Parallel and Distributed Programming* course: [Real-Time Parallel K-Means Image Segmentation](https://github.com/sebsop/realtime-parallel-kmeans-segmentation). While that work focused on distributed CPU parallelization (MPI/OpenMP), this thesis shifts the focus toward maximizing single-node throughput via low-level CUDA optimization and the exploration of non-Euclidean quantum-inspired similarity metrics.\n\n## Overview\n\nThis repository implements a highly modular, professional-grade C++/CUDA pipeline capable of segmenting live video feeds at high frame rates. It compares traditional Euclidean distance clustering against a novel, quantum-inspired phase-estimation metric (simulated via GPU).\n\n### Key Features\n\n*   **Modular Engine Architecture**: Hot-swap between a highly optimized Classical CUDA engine and a Quantum-inspired emulation engine in real-time.\n*   **Quantum-Inspired Metric**: Implements a simulated Swap-Test interference approximation to calculate vector similarity using Hilbert-space phase overlap rather than standard Euclidean distance.\n*   **High-Performance CUDA Backend**: Custom CUDA kernels for spatial preprocessing, K-Means++ initialization, and massive parallel pixel assignment utilizing shared memory optimization.\n*   **Scientific Benchmarking**: Integrated real-time metric calculation including approximated Silhouette Scores, Davies-Bouldin Index, and Within-Cluster Sum of Squares (WCSS).\n*   **Modern UI Integration**: Decoupled, thread-safe Dear ImGui interface providing dynamic parameter control, live telemetry, and side-by-side visual comparison.\n*   **Audit-Ready Codebase**: Comprehensive Doxygen documentation, strict C++20 adherence, RAII resource management, and a robust GoogleTest verification suite.\n\n## Architecture Highlights\n\nThe system is designed with strict separation of concerns, utilizing modern software engineering patterns:\n\n*   **Factory Pattern**: Dynamically instantiates the correct execution engine and initializer based on runtime configuration.\n*   **Observer Pattern**: Ensures the high-frequency CUDA processing loop remains completely decoupled from the UI rendering thread.\n*   **Temporal Coherence Optimization**: Implements configurable centroid memoization (learning intervals) to drastically reduce GPU computational load during stable video scenes.\n\n## Getting Started\n\n### Prerequisites\n\n*   C++20 compatible compiler (MSVC / GCC / Clang)\n*   CMake 3.20+\n*   NVIDIA CUDA Toolkit 12.x+\n*   OpenCV 4.x\n*   GoogleTest (Fetched automatically via CMake)\n*   Dear ImGui (Included/Fetched via build system)\n\n### Building the Project\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/sebsop/kmeans-thesis-segmentation.git\n   cd kmeans-thesis-segmentation\n   ```\n2. Configure and build via CMake:\n   ```bash\n   mkdir build \u0026\u0026 cd build\n   cmake .. -DCMAKE_BUILD_TYPE=Release\n   cmake --build . --config Release\n   ```\n3. Run the executable generated in your build directory.\n\n## Repository Structure\n\n```text\nkmeans-thesis-segmentation\n├─ .clang-format\n├─ .clang-tidy\n├─ assets\n├─ CMakeLists.txt\n├─ CMakeSettings.json\n├─ include\n│  ├─ backend\n│  │  └─ cuda_assignment_context.hpp\n│  ├─ clustering\n│  │  ├─ clustering_factory.hpp\n│  │  ├─ clustering_manager.hpp\n│  │  ├─ engines\n│  │  │  ├─ base_kmeans_engine.hpp\n│  │  │  ├─ classical_engine.hpp\n│  │  │  ├─ kmeans_engine.hpp\n│  │  │  └─ quantum_engine.hpp\n│  │  ├─ initializers\n│  │  │  ├─ initializer.hpp\n│  │  │  ├─ kmeans_plus_plus_initializer.hpp\n│  │  │  └─ random_initializer.hpp\n│  │  ├─ metrics.hpp\n│  │  └─ preprocessor\n│  │     └─ strided_data_preprocessor.hpp\n│  ├─ common\n│  │  ├─ config.hpp\n│  │  ├─ constants.hpp\n│  │  ├─ enums.hpp\n│  │  ├─ utils.hpp\n│  │  └─ vector_math.hpp\n│  └─ io\n│     ├─ application.hpp\n│     ├─ benchmark_command.hpp\n│     ├─ benchmark_observer.hpp\n│     ├─ benchmark_result.hpp\n│     ├─ benchmark_runner.hpp\n│     ├─ ui\n│     │  ├─ benchmark_overlay_ui.hpp\n│     │  ├─ control_panel_ui.hpp\n│     │  └─ video_feed_ui.hpp\n│     └─ ui_manager.hpp\n├─ LICENSE\n├─ README.md\n├─ src\n│  ├─ backend\n│  │  └─ cuda_kernels.cu\n│  ├─ clustering\n│  │  ├─ clustering_factory.cpp\n│  │  ├─ clustering_manager.cpp\n│  │  ├─ engines\n│  │  │  ├─ base_kmeans_engine.cu\n│  │  │  ├─ classical_engine.cu\n│  │  │  └─ quantum_engine.cu\n│  │  ├─ initializers\n│  │  │  ├─ kmeans_plus_plus_initializer.cu\n│  │  │  └─ random_initializer.cpp\n│  │  ├─ metrics.cpp\n│  │  └─ preprocessor\n│  │     └─ strided_data_preprocessor.cu\n│  ├─ io\n│  │  ├─ application.cpp\n│  │  ├─ benchmark_command.cpp\n│  │  ├─ benchmark_runner.cpp\n│  │  ├─ ui\n│  │  │  ├─ benchmark_overlay_ui.cpp\n│  │  │  ├─ control_panel_ui.cpp\n│  │  │  └─ video_feed_ui.cpp\n│  │  └─ ui_manager.cpp\n│  └─ main.cpp\n└─ tests\n   ├─ backend\n   │  └─ cuda_kernels_tests.cu\n   ├─ clustering\n   │  ├─ clustering_factory_tests.cpp\n   │  ├─ clustering_manager_tests.cpp\n   │  ├─ engines\n   │  │  ├─ base_kmeans_engine_tests.cu\n   │  │  ├─ classical_engine_tests.cu\n   │  │  └─ quantum_engine_tests.cu\n   │  ├─ initializers\n   │  │  ├─ kmeans_plus_plus_initializer_tests.cu\n   │  │  └─ random_initializer_tests.cu\n   │  ├─ metrics_tests.cpp\n   │  └─ preprocessor\n   │     └─ strided_data_preprocessor_tests.cu\n   ├─ CMakeLists.txt\n   ├─ common\n   │  └─ vector_math_tests.cpp\n   └─ io\n      └─ ui_integration_tests.cpp\n```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contact\n\n**Sebastian Soptelea**  \nBabeș-Bolyai University  \nEmail: [sebastian.soptelea@proton.me](mailto:sebastian.soptelea@proton.me)  \nGitHub: [\\@sebsop](https://github.com/sebsop)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebsop%2Fkmeans-thesis-segmentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebsop%2Fkmeans-thesis-segmentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebsop%2Fkmeans-thesis-segmentation/lists"}