# alicevision/popsift architecture

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

- Interactive diagram: https://gitdiagram.com/alicevision/popsift
- Repository: https://github.com/alicevision/popsift

## Overview

##### Project type and purpose
- PopSift is a performance-critical, GPU-accelerated C++ library implementing David Lowe’s SIFT algorithm in CUDA.
- It ships with a small demo application (`popsift-demo`) and test scripts but its main purpose is to expose a host-side API that queues image processing jobs to the GPU and returns SIFT features.

##### File structure
Top-level directories and key files:
- `src/application/` – standalone demo apps (`main.cpp`, `match.cpp`, `pgmread.*`).
- `src/popsift/` – the heart of the library, organized by functionality:
– `common/` utilities and synchronization primitives
– GPU kernels & host wrappers for image filtering, pyramid build, extrema detection, orientation, descriptor computation (`s_*` modules)
– `popsift.cu/.h` – high-level orchestration of the SIFT pipeline
– `features.cu/.h`, `gauss_filter.*`, etc. for core algorithm steps
- `cmake/`, `CMakeLists.txt`, Dockerfiles, CI workflows – build and deployment configuration
- `doc/` – Sphinx documentation
- `testScripts/` – dataset download and test harness

##### README for insights
- Confirms it is a CUDA-only library (CUDA ≥ 8.0, compute capability ≥ 3.0) with an asynchronous, non-blocking API (`enqueue()`) and a blocking alternative (`init()`/`execute()`).
- Provides guidance on integrating via `find_package(PopSift)` and the `PopSift::popsift` CMake target.

##### Main components and their relationships
a. Application Layer
– `popsift-demo` or any client C++ code that reads images (PGM or via DevIL) and interacts with the PopSift API.
b. Host-side Library Layer (CPU)
– Configuration (`popart::Config`)
– Job management and queuing (`PopSift::enqueue()`, `SiftJob`)
– Synchronization (via Boost threads/atomic if enabled)
c. GPU-side Processing Layer
– CUDA kernels for each pipeline stage:
1. Gaussian filtering
2. Scale‐space pyramid construction
3. Extrema detection (keypoint candidates)
4. Orientation assignment
5. Descriptor computation
– Memory management and kernel launches happen in `popsift.cu`
d. External Dependencies
– CUDA runtime and driver
– Optional DevIL for image I/O
– Boost (atomic, thread, chrono, date-time) for host threading
e. Build & CI Infrastructure
– CMake configuration (`cmake/` folder, `PopSiftConfig.cmake`)
– Dockerfiles for reproducible builds
– CI pipelines (GitHub Actions, Travis, Appveyor)

##### Architectural patterns & design principles
- Layered architecture separating Application → Host API → GPU Kernel Pipeline.
- Data‐flow / pipeline pattern: image buffers flow through ordered CUDA kernel stages.
- Asynchronous job queue decoupling host thread from GPU execution.
- Modular decomposition: each SIFT stage lives in its own source module for clarity and maintainability.

a. Components to include:
– Client Application (popsift-demo or third-party code)
– PopSift Host API layer
– SiftJob / Job Queue
– GPU Kernel Pipeline (with sub-components for filter, pyramid, detection, orientation, descriptor)
– Image storage (host memory buffers)
– Results (feature list iterators)
– External deps: CUDA Runtime, DevIL, Boost
– Build/config modules (CMake, Docker, CI) as contextual footnotes
b. Interactions & data flow:
1. App loads image → Host memory buffer
2. App calls `PopSift::enqueue(buffer, width, height)` → returns `SiftJob*` immediately
3. Host enqueues job into internal queue (optional thread pool)
4. GPU: image buffer copied to device → passes through kernel stages in sequence → results copied back
5. App calls `job->get()` to block until completion → returns feature vector
c. Important patterns to highlight:
– Asynchronous queuing (non-blocking API) vs blocking API
– Clear separation of concerns: CPU for orchestration, GPU for heavy compute
– Modular kernel organization by algorithmic stage
d. Key technologies and libraries:
– C++14 (host), CUDA 8+ (device), CMake, Boost, DevIL

##### Detail without overthinking
- Every major module (host API, queue, kernel stages).
- CI/Build as a side-note rather than core pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        AppMain["main.cpp"]:::cpu
        AppMatch["match.cpp"]:::cpu
        AppPgmread["pgmread.*"]:::cpu
    end
    click AppMain "https://github.com/alicevision/popsift/blob/develop/src/application/main.cpp"
    click AppMatch "https://github.com/alicevision/popsift/blob/develop/src/application/match.cpp"
    click AppPgmread "https://github.com/alicevision/popsift/blob/develop/src/application/pgmread.cpp"
    click AppPgmread "https://github.com/alicevision/popsift/blob/develop/src/application/pgmread.h"

    subgraph "Host API Layer"
        POPAPI["popsift.h/.cu"]:::cpu
    end
    click POPAPI "https://github.com/alicevision/popsift/blob/develop/src/popsift/popsift.h"
    click POPAPI "https://github.com/alicevision/popsift/blob/develop/src/popsift/popsift.cu"

    AppMain -->|"enqueue() / init()"| POPAPI
    AppMatch -->|"enqueue() / init()"| POPAPI
    AppPgmread --> POPAPI

    subgraph "Job Queue & Sync"
        Queue["sync_queue.h"]:::cpu
        Assist["assist.*"]:::cpu
        DeviceProp["device_prop.*"]:::cpu
        DebugMacros["debug_macros.*"]:::cpu
    end
    click Queue "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/sync_queue.h"
    click Assist "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/assist.cu"
    click Assist "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/assist.h"
    click DeviceProp "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/device_prop.cu"
    click DeviceProp "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/device_prop.h"
    click DebugMacros "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/debug_macros.cu"
    click DebugMacros "https://github.com/alicevision/popsift/blob/develop/src/popsift/common/debug_macros.h"

    POPAPI -->|"enqueue()"| Queue

    subgraph "GPU Pipeline"
        direction TB
        subgraph "Gaussian Filtering"
            Gauss["gauss_filter.*"]:::gpu
        end
        subgraph "Pyramid Build"
            Pyramid1["s_pyramid_build.*"]:::gpu
            PyramidFixed["s_pyramid_fixed.cu"]:::gpu
            PyramidTop["sift_pyramid.*"]:::gpu
        end
        subgraph "Extrema Detection"
            Extrema["s_extrema.cu"]:::gpu
            Extremum["sift_extremum.*"]:::gpu
        end
        subgraph "Orientation Assignment"
            Orientation["s_orientation.cu"]:::gpu
        end
        subgraph "Descriptor Computation"
            DescGrid["s_desc_grid.*"]:::gpu
            DescIgrid["s_desc_igrid.*"]:::gpu
            DescIloop["s_desc_iloop.*"]:::gpu
            DescLoop["s_desc_loop.*"]:::gpu
            DescNotile["s_desc_notile.*"]:::gpu
            DescNorm["s_desc_normalize.h"]:::gpu
            DescNormL2["s_desc_norm_l2.h"]:::gpu
            DescNormRS["s_desc_norm_rs.h"]:::gpu
            DescMain["sift_desc.cu"]:::gpu
        end
        subgraph "Feature Output"
            Features["features.*"]:::gpu
        end
    end

    click Gauss "https://github.com/alicevision/popsift/blob/develop/src/popsift/gauss_filter.cu"
    click Gauss "https://github.com/alicevision/popsift/blob/develop/src/popsift/gauss_filter.h"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build.cu"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_aa.cu"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_aa.h"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_ai.cu"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_ai.h"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_ra.cu"
    click Pyramid1 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_build_ra.h"
    click PyramidFixed "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_pyramid_fixed.cu"
    click PyramidTop "https://github.com/alicevision/popsift/blob/develop/src/popsift/sift_pyramid.cu"
    click PyramidTop "https://github.com/alicevision/popsift/blob/develop/src/popsift/sift_pyramid.h"
    click Extrema "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_extrema.cu"
    click Extremum "https://github.com/alicevision/popsift/blob/develop/src/popsift/sift_extremum.cu"
    click Extremum "https://github.com/alicevision/popsift/blob/develop/src/popsift/sift_extremum.h"
    click Orientation "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_orientation.cu"
    click DescGrid "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_grid.cu"
    click DescGrid "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_grid.h"
    click DescIgrid "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_igrid.cu"
    click DescIgrid "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_igrid.h"
    click DescIloop "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_iloop.cu"
    click DescIloop "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_iloop.h"
    click DescLoop "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_loop.cu"
    click DescLoop "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_loop.h"
    click DescNotile "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_notile.cu"
    click DescNotile "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_notile.h"
    click DescNorm "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_normalize.h"
    click DescNormL2 "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_norm_l2.h"
    click DescNormRS "https://github.com/alicevision/popsift/blob/develop/src/popsift/s_desc_norm_rs.h"
    click DescMain "https://github.com/alicevision/popsift/blob/develop/src/popsift/sift_desc.cu"
    click Features "https://github.com/alicevision/popsift/blob/develop/src/popsift/features.cu"
    click Features "https://github.com/alicevision/popsift/blob/develop/src/popsift/features.h"

    Queue -->|"kernel launch"| Gauss
    Gauss -->|"next stage"| Pyramid1
    Pyramid1 --> PyramidFixed
    PyramidFixed --> PyramidTop
    PyramidTop --> Extrema
    Extrema --> Extremum
    Extremum --> Orientation
    Orientation --> DescGrid
    DescGrid --> DescIgrid
    DescIgrid --> DescIloop
    DescIloop --> DescLoop
    DescLoop --> DescNotile
    DescNotile --> DescMain
    DescMain --> DescNorm
    DescNorm --> DescNormL2
    DescNormL2 --> DescNormRS
    DescNormRS --> Features
    Features -->|"copy D2H"| POPAPI

    subgraph "Memory Buffers"
        HostBuf["Host Memory"]:::cpu
        DeviceBuf["Device Memory"]:::gpu
    end
    AppMain --> HostBuf
    POPAPI -->|"H2D Memcopy"| DeviceBuf
    DeviceBuf --> Gauss
    Features --> HostBuf

    subgraph "External Dependencies"
        CUDA["CUDA Runtime/Driver"]:::ext
        DevIL["DevIL"]:::ext
        Boost["Boost"]:::ext
    end
    POPAPI --> CUDA
    AppPgmread --> DevIL
    Queue --> Boost

    subgraph "Build & CI"
        CMakeRoot["CMakeLists.txt"]:::build
        CMakeSrc["src/CMakeLists.txt"]:::build
        CMakeDir["cmake/"]:::build
        Docker["Dockerfile"]:::build
        CI[".github/workflows"]:::build
    end

    classDef cpu fill:#CEF,stroke:#333,stroke-width:1px
    classDef gpu fill:#FDD,stroke:#333,stroke-width:1px
    classDef ext fill:#DDD,stroke:#333,stroke-width:1px,stroke-dasharray:5 5
    classDef build fill:#DFD,stroke:#333,stroke-width:1px,stroke-dasharray:2 2
```
