# wangxuan95/nbli architecture

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

- Interactive diagram: https://gitdiagram.com/wangxuan95/nbli
- Repository: https://github.com/wangxuan95/nbli

## Overview

##### Project type and purpose
- This is a command-line, C++ based, single-threaded image compressor/decompressor.
- It has two deliverables:
- NBLI: prototype implementation (source + binary)
- fNBLI: optimized AVX2-accelerated binary only
- It reads .pgm/.ppm/.pnm/.png, applies a lossless (or optional lossy) entropy-coding pipeline, and writes .nbli/.fnbli files (and vice versa).

##### File structure
- Top-level:
- LICENSE, README.md
- NBLI.exe, fNBLI.exe (binaries)
- image/ (sample images)
- src/ (all source code)
- src/ hierarchy:
- src/NBLI – core compression engine
– main.cpp (CLI arg parsing + orchestrator)
– NBLI.cpp / NBLI.h (dispatcher for compress/decompress)
– AdvancedPredictor.h, PlaneModel.h (prediction stage)
– AutoReorder.h (pixel reordering module)
– GolombCodeTree.h, rANS.h, CRC32.h (entropy coder & metadata)
- src/imageio – image format abstraction
– imageio_pnm.c, imageio_png.c (PNM/PNG decoders)
– uPNG/ (tiny PNG library)
– imageio.h (high-level I/O interface)
- src/FileIO.h – file read/write helper
- Build scripts are ad-hoc g++ commands (static link, -O3).

##### README for additional insights
- Clearly states:
- Two modes: compress (encode) and decompress (decode).
- Switches control verbosity, CRC, distortion, predictor type, coder type.
- fNBLI leverages parallel ANS (AVX2) for speed.

##### Detailed capture of components
- Break the compression engine into sub-blocks: Predictor, Reorder, Entropy Coder, CRC32.
- Main.cpp as orchestrator, indicating call sequence.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Files"
        direction TB
        Gray["Gray.pgm"]:::input
        RGB["RGB.ppm"]:::input
    end

    %% CLI Layer
    subgraph "CLI & Config" 
        direction TB
        CLIParser["CLI Parser (main.cpp)"]:::frontend
    end

    %% File I/O Layer
    subgraph "File I/O" 
        direction TB
        FileIO["FileIO Module (FileIO.h)"]:::io
    end

    %% Image I/O Layer
    subgraph "Image I/O" 
        direction TB
        ImageIO["High-level I/O (imageio.h)"]:::io
        PNM["PNM Decoder/Encoder (imageio_pnm.c)"]:::io
        PNG["PNG Decoder/Encoder (imageio_png.c)"]:::io
        uPNGc["uPNG C Lib (uPNG.c)"]:::io
        uPNGh["uPNG Header (uPNG.h)"]:::io
    end

    %% Compression Engine
    subgraph "Compression Engine" 
        direction TB

        subgraph "Orchestrator & Dispatcher"
            direction TB
            NBLIcpp["NBLI.cpp"]:::engine
            NBLIh["NBLI.h"]:::engine
            Codec["NBLIcodec.h"]:::engine
            Mapper["Mapper.h"]:::engine
            HeaderH["Header.h"]:::engine
        end

        subgraph "Pre-processing"
            direction TB
            PlaneModel["PlaneModel.h"]:::engine
            AdvPred["AdvancedPredictor.h"]:::engine
            Reorder["AutoReorder.h"]:::engine
        end

        subgraph "Entropy Coding"
            direction TB
            rANS["rANS Coder (rANS.h)"]:::engine
            Golomb["Golomb Coder (GolombCodeTree.h)"]:::engine
            CRC32["CRC32 Module (CRC32.h)"]:::engine
            AVX2["AVX2-optimized ANS"]:::engineAlt
        end
    end

    %% Output Layer
    subgraph "Outputs"
        direction TB
        NBLIexe["NBLI.exe"]:::output
        fNBLIexe["fNBLI.exe"]:::output
        NBLI_dir["NBLI Directory"]:::output
        fNBLI_dir["fNBLI Directory"]:::output
    end

    %% Connections
    Gray -->|raw bytes| CLIParser
    RGB -->|raw bytes| CLIParser
    CLIParser -->|parsed args| FileIO
    FileIO -->|file stream| ImageIO
    ImageIO -->|image buffer| NBLIcpp
    NBLIcpp -->|dispatch| PlaneModel
    PlaneModel --> AdvPred
    AdvPred --> Reorder
    Reorder --> rANS
    Reorder --> Golomb
    rANS --> CRC32
    Golomb --> CRC32
    CRC32 --> AVX2
    CRC32 --> NBLIcpp
    NBLIcpp -->|bitstream| FileIO
    FileIO --> NBLIexe
    FileIO --> fNBLIexe
    NBLIexe --> NBLI_dir
    fNBLIexe --> fNBLI_dir

    %% Click Events
    click CLIParser "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/main.cpp"
    click FileIO "https://github.com/wangxuan95/nbli/blob/main/src/FileIO.h"
    click ImageIO "https://github.com/wangxuan95/nbli/blob/main/src/imageio/imageio.h"
    click PNM "https://github.com/wangxuan95/nbli/blob/main/src/imageio/imageio_pnm.c"
    click PNG "https://github.com/wangxuan95/nbli/blob/main/src/imageio/imageio_png.c"
    click uPNGc "https://github.com/wangxuan95/nbli/blob/main/src/imageio/uPNG/uPNG.c"
    click uPNGh "https://github.com/wangxuan95/nbli/blob/main/src/imageio/uPNG/uPNG.h"
    click NBLIcpp "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/NBLI.cpp"
    click NBLIh "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/NBLI.h"
    click Codec "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/NBLIcodec.h"
    click Mapper "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/Mapper.h"
    click HeaderH "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/Header.h"
    click PlaneModel "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/PlaneModel.h"
    click AdvPred "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/AdvancedPredictor.h"
    click Reorder "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/AutoReorder.h"
    click rANS "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/rANS.h"
    click Golomb "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/GolombCodeTree.h"
    click CRC32 "https://github.com/wangxuan95/nbli/blob/main/src/NBLI/CRC32.h"
    click NBLI_dir "https://github.com/wangxuan95/nbli/tree/main/NBLI"
    click fNBLI_dir "https://github.com/wangxuan95/nbli/tree/main/fNBLI"
    click NBLIexe "https://github.com/wangxuan95/nbli/blob/main/NBLI.exe"
    click fNBLIexe "https://github.com/wangxuan95/nbli/blob/main/fNBLI.exe"
    click Gray "https://github.com/wangxuan95/nbli/blob/main/image/Gray.pgm"
    click RGB "https://github.com/wangxuan95/nbli/blob/main/image/RGB.ppm"

    %% Styles
    classDef input fill:#E5E5E5,stroke:#333,stroke-width:1px
    classDef frontend fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef io fill:#ABEBC6,stroke:#333,stroke-width:1px
    classDef engine fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef engineAlt fill:#F5B7B1,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef output fill:#D7BDE2,stroke:#333,stroke-width:1px
```
