# thenurii/qmiv architecture

> Architecture diagram of the GitHub repository thenurii/qmiv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thenurii/qmiv
- Repository: https://github.com/thenurii/qmiv

## Overview

QMIV is a command-line framework for comparing immersive-video sequences and reporting objective quality metrics. Its main workflow configures and validates paired inputs, reads frames, prepares and aligns comparison pictures, calculates selected metrics, aggregates frame statistics, and emits results. The README documents IV-PSNR, IV-SSIM, IV-MS-SSIM and general-purpose PSNR, WS-PSNR, SSIM and MS-SSIM. Source excerpts substantiate configuration, frame reading, shift-compensation preparation and SSIM internals; some metric wiring and output details are inferred only at subsystem level from the tree.

Main entry points: [`apps/QMIV/src/xAppQMIV.cpp`](https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xAppQMIV.cpp) (QMIV application), [`libs/pmbb-slst/src/xSeqLST.cpp`](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-slst/src/xSeqLST.cpp) (Sequence readers), [`libs/pmbb-ivqm/src/xSSIM.cpp`](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xSSIM.cpp) (SSIM metrics), [`apps/QMIV/src/xMetricQMIV.cpp`](https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xMetricQMIV.cpp) (Metric reporting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application workflow"]
  node_app["QMIV application<br/>[xAppQMIV.cpp]"]
  node_metric_results["Metric reporting<br/>[xMetricQMIV.cpp]"]
end

subgraph group_io["Sequence I/O"]
  node_sequences["Sequence readers<br/>[xSeqLST.cpp]"]
  node_bmp["BMP support<br/>[xBMP.cpp]"]
  node_png["PNG decoder<br/>[spng.c]"]
end

subgraph group_prep["Picture preparation"]
  node_pic_ops["Picture operations<br/>[xPic.cpp]"]
  node_color["Color conversion<br/>[xColorSpace.cpp]"]
  node_gcd["Color difference<br/>[xGlobClrDiff.cpp]"]
  node_shift["Shift compensation<br/>[xShftCompPic.cpp]"]
end

subgraph group_metrics["Quality metrics"]
  node_ivpsnr["IV-PSNR family<br/>[xIVPSNR.cpp]"]
  node_ivssim["IV-SSIM family<br/>[xIVSSIM.cpp]"]
  node_psnr["PSNR metric<br/>[xPSNR.cpp]"]
  node_ssim["SSIM metrics<br/>[xSSIM.cpp]"]
  node_wspsnr["WS-PSNR metric<br/>[xWSPSNR.cpp]"]
end

subgraph group_base["Core processing"]
  node_core_pixels["Pixel primitives<br/>[xPixelOps.h]"]
  node_thread_pool["Task execution<br/>[xThreadPool.cpp]"]
end

node_user(("CLI user"))
node_frame_data["Video frames"]
node_result_file["Result output"]

node_user -->|"configures run"| node_app
node_app -->|"opens inputs"| node_sequences
node_sequences -->|"reads BMP"| node_bmp
node_sequences -->|"decodes PNG"| node_png
node_sequences -->|"loads frames"| node_frame_data
node_app -->|"prepares pictures"| node_pic_ops
node_app -->|"converts color"| node_color
node_app -->|"computes differences"| node_gcd
node_app -->|"generates compensated pictures"| node_shift
node_app -->|"calculates immersive PSNR"| node_ivpsnr
node_app -->|"calculates immersive SSIM"| node_ivssim
node_app -->|"calculates PSNR"| node_psnr
node_app -->|"calculates SSIM"| node_ssim
node_app -->|"calculates WS-PSNR"| node_wspsnr
node_ssim -->|"uses pixel operations"| node_core_pixels
node_app -->|"dispatches frame tasks"| node_thread_pool
node_app -->|"aggregates statistics"| node_metric_results
node_app -->|"writes results"| node_result_file

click node_app "https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xAppQMIV.cpp"
click node_metric_results "https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xMetricQMIV.cpp"
click node_sequences "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-slst/src/xSeqLST.cpp"
click node_bmp "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-slst/src/xBMP.cpp"
click node_png "https://github.com/thenurii/qmiv/blob/main/thirdparty/spng/src/spng.c"
click node_pic_ops "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xPic.cpp"
click node_color "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xColorSpace.cpp"
click node_gcd "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xGlobClrDiff.cpp"
click node_shift "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xShftCompPic.cpp"
click node_ivpsnr "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xIVPSNR.cpp"
click node_ivssim "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xIVSSIM.cpp"
click node_psnr "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xPSNR.cpp"
click node_ssim "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xSSIM.cpp"
click node_wspsnr "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xWSPSNR.cpp"
click node_core_pixels "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xPixelOps.h"
click node_thread_pool "https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xThreadPool.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_metric_results,node_user toneBlue
class node_sequences,node_bmp,node_png toneAmber
class node_pic_ops,node_color,node_gcd,node_shift toneMint
class node_ivpsnr,node_ivssim,node_psnr,node_ssim,node_wspsnr toneRose
class node_core_pixels,node_thread_pool,node_frame_data,node_result_file toneIndigo
```

## Components

### Application workflow

- [QMIV application](https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xAppQMIV.cpp): `apps/QMIV/src/xAppQMIV.cpp`
- [Metric reporting](https://github.com/thenurii/qmiv/blob/main/apps/QMIV/src/xMetricQMIV.cpp): `apps/QMIV/src/xMetricQMIV.cpp`

### Sequence I/O

- [Sequence readers](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-slst/src/xSeqLST.cpp): `libs/pmbb-slst/src/xSeqLST.cpp`
- [BMP support](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-slst/src/xBMP.cpp): `libs/pmbb-slst/src/xBMP.cpp`
- [PNG decoder](https://github.com/thenurii/qmiv/blob/main/thirdparty/spng/src/spng.c): `thirdparty/spng/src/spng.c`

### Picture preparation

- [Picture operations](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xPic.cpp): `libs/pmbb-core/src/xPic.cpp`
- [Color conversion](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xColorSpace.cpp): `libs/pmbb-core/src/xColorSpace.cpp`
- [Color difference](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xGlobClrDiff.cpp): `libs/pmbb-ivqm/src/xGlobClrDiff.cpp`
- [Shift compensation](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xShftCompPic.cpp): `libs/pmbb-ivqm/src/xShftCompPic.cpp`

### Quality metrics

- [IV-PSNR family](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xIVPSNR.cpp): `libs/pmbb-ivqm/src/xIVPSNR.cpp`
- [IV-SSIM family](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xIVSSIM.cpp): `libs/pmbb-ivqm/src/xIVSSIM.cpp`
- [PSNR metric](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xPSNR.cpp): `libs/pmbb-ivqm/src/xPSNR.cpp`
- [SSIM metrics](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xSSIM.cpp): `libs/pmbb-ivqm/src/xSSIM.cpp`
- [WS-PSNR metric](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-ivqm/src/xWSPSNR.cpp): `libs/pmbb-ivqm/src/xWSPSNR.cpp`

### Core processing

- [Pixel primitives](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xPixelOps.h): `libs/pmbb-core/src/xPixelOps.h`
- [Task execution](https://github.com/thenurii/qmiv/blob/main/libs/pmbb-core/src/xThreadPool.cpp): `libs/pmbb-core/src/xThreadPool.cpp`

### Other components

- **CLI user**
- **Video frames**
- **Result output**

## Connections

- CLI user → QMIV application: configures run
- QMIV application → Sequence readers: opens inputs
- Sequence readers → BMP support: reads BMP
- Sequence readers → PNG decoder: decodes PNG
- Sequence readers → Video frames: loads frames
- QMIV application → Picture operations: prepares pictures
- QMIV application → Color conversion: converts color
- QMIV application → Color difference: computes differences
- QMIV application → Shift compensation: generates compensated pictures
- QMIV application → IV-PSNR family: calculates immersive PSNR
- QMIV application → IV-SSIM family: calculates immersive SSIM
- QMIV application → PSNR metric: calculates PSNR
- QMIV application → SSIM metrics: calculates SSIM
- QMIV application → WS-PSNR metric: calculates WS-PSNR
- SSIM metrics → Pixel primitives: uses pixel operations
- QMIV application → Task execution: dispatches frame tasks
- QMIV application → Metric reporting: aggregates statistics
- QMIV application → Result output: writes results