# firefares2005/frs architecture

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

- Interactive diagram: https://gitdiagram.com/firefares2005/frs
- Repository: https://github.com/firefares2005/frs

## Overview

FRS is a lossy image codec exposed through a command-line tool, a C++ facade, and Python bindings. The main workflow reads an image, encodes it into FRS bytes, and writes the result; decoding reads FRS bytes and writes a restored image. The README documents the codec stages and Python utilities, but most encoder and decoder implementations were not sampled, so internal stage links follow that documentation rather than inspected call sites.

Main entry points: [`src/main.cpp`](https://github.com/firefares2005/frs/blob/main/src/main.cpp) (CLI), [`python_bind/pyfrs.cpp`](https://github.com/firefares2005/frs/blob/main/python_bind/pyfrs.cpp) (Python bindings), [`src/encoder.cpp`](https://github.com/firefares2005/frs/blob/main/src/encoder.cpp) (Image encoder), [`src/decoder.cpp`](https://github.com/firefares2005/frs/blob/main/src/decoder.cpp) (Image decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.cpp]"]
  node_cpp["C++ facade<br/>[frs.cpp]"]
  node_py["Python bindings<br/>[pyfrs.cpp]"]
end

subgraph group_codec["Codec runtime"]
  node_encoder["Image encoder<br/>[encoder.cpp]"]
  node_color["Color conversion<br/>[encoder.cpp]"]
  node_wavelet["Wavelet transform<br/>[wavelet.h]"]
  node_quant["Subband quantization<br/>[encoder.cpp]"]
  node_spiht["SPIHT coding<br/>[spiht.h]"]
  node_entropy["Range coder<br/>[entropy.cpp]"]
  node_decoder["Image decoder<br/>[decoder.cpp]"]
end

subgraph group_format["Image and format I/O"]
  node_imageio["Image I/O<br/>[image_io.cpp]"]
  node_frsfile["FRS bytes"]
end

subgraph group_python["Python utilities"]
  node_pyutils["Python utilities<br/>[pyfrs.cpp]"]
end

node_user(("Caller"))
node_image["Image file"]

node_user -->|"invokes"| node_cli
node_user -->|"calls"| node_cpp
node_user -->|"calls"| node_py
node_cli -->|"reads image"| node_imageio
node_cli -->|"encodes image"| node_encoder
node_encoder -->|"produces bytes"| node_frsfile
node_cli -->|"writes bytes"| node_frsfile
node_cli -->|"reads bytes"| node_frsfile
node_cli -->|"decodes bytes"| node_decoder
node_cli -->|"writes image"| node_imageio
node_cpp -->|"loads or saves"| node_imageio
node_cpp -->|"encodes image"| node_encoder
node_cpp -->|"decodes bytes"| node_decoder
node_py -->|"calls facade"| node_cpp
node_py -->|"encodes image"| node_encoder
node_py -->|"decodes bytes"| node_decoder
node_py -->|"writes image"| node_imageio
node_encoder -->|"converts color"| node_color
node_color -->|"transforms"| node_wavelet
node_wavelet -->|"provides coefficients"| node_quant
node_quant -->|"quantizes for"| node_spiht
node_spiht -->|"codes symbols"| node_entropy
node_decoder -->|"decodes symbols"| node_entropy
node_decoder -->|"reconstructs image"| node_wavelet
node_py -->|"provides"| node_pyutils
node_pyutils -->|"loads images"| node_imageio
node_pyutils -->|"benchmarks encode"| node_encoder
node_pyutils -->|"compares decode"| node_decoder

click node_cli "https://github.com/firefares2005/frs/blob/main/src/main.cpp"
click node_cpp "https://github.com/firefares2005/frs/blob/main/frs.cpp"
click node_py "https://github.com/firefares2005/frs/blob/main/python_bind/pyfrs.cpp"
click node_imageio "https://github.com/firefares2005/frs/blob/main/src/image_io.cpp"
click node_encoder "https://github.com/firefares2005/frs/blob/main/src/encoder.cpp"
click node_color "https://github.com/firefares2005/frs/blob/main/src/encoder.cpp"
click node_wavelet "https://github.com/firefares2005/frs/blob/main/src/wavelet.h"
click node_quant "https://github.com/firefares2005/frs/blob/main/src/encoder.cpp"
click node_spiht "https://github.com/firefares2005/frs/blob/main/src/spiht.h"
click node_entropy "https://github.com/firefares2005/frs/blob/main/src/entropy.cpp"
click node_decoder "https://github.com/firefares2005/frs/blob/main/src/decoder.cpp"
click node_pyutils "https://github.com/firefares2005/frs/blob/main/python_bind/pyfrs.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_cli,node_cpp,node_py toneBlue
class node_encoder,node_color,node_wavelet,node_quant,node_spiht,node_entropy,node_decoder toneAmber
class node_imageio,node_frsfile toneMint
class node_pyutils toneRose
class node_user,node_image toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/firefares2005/frs/blob/main/src/main.cpp): `src/main.cpp`
- [C++ facade](https://github.com/firefares2005/frs/blob/main/frs.cpp): `frs.cpp`
- [Python bindings](https://github.com/firefares2005/frs/blob/main/python_bind/pyfrs.cpp): `python_bind/pyfrs.cpp`

### Codec runtime

- [Image encoder](https://github.com/firefares2005/frs/blob/main/src/encoder.cpp): `src/encoder.cpp`
- [Color conversion](https://github.com/firefares2005/frs/blob/main/src/encoder.cpp): `src/encoder.cpp`
- [Wavelet transform](https://github.com/firefares2005/frs/blob/main/src/wavelet.h): `src/wavelet.h`
- [Subband quantization](https://github.com/firefares2005/frs/blob/main/src/encoder.cpp): `src/encoder.cpp`
- [SPIHT coding](https://github.com/firefares2005/frs/blob/main/src/spiht.h): `src/spiht.h`
- [Range coder](https://github.com/firefares2005/frs/blob/main/src/entropy.cpp): `src/entropy.cpp`
- [Image decoder](https://github.com/firefares2005/frs/blob/main/src/decoder.cpp): `src/decoder.cpp`

### Image and format I/O

- [Image I/O](https://github.com/firefares2005/frs/blob/main/src/image_io.cpp): `src/image_io.cpp`
- **FRS bytes**

### Python utilities

- [Python utilities](https://github.com/firefares2005/frs/blob/main/python_bind/pyfrs.cpp): `python_bind/pyfrs.cpp`

### Other components

- **Caller**
- **Image file**

## Connections

- Caller → CLI: invokes
- Caller → C++ facade: calls
- Caller → Python bindings: calls
- CLI → Image I/O: reads image
- CLI → Image encoder: encodes image
- Image encoder → FRS bytes: produces bytes
- CLI → FRS bytes: writes bytes
- CLI → FRS bytes: reads bytes
- CLI → Image decoder: decodes bytes
- CLI → Image I/O: writes image
- C++ facade → Image I/O: loads or saves
- C++ facade → Image encoder: encodes image
- C++ facade → Image decoder: decodes bytes
- Python bindings → C++ facade: calls facade
- Python bindings → Image encoder: encodes image
- Python bindings → Image decoder: decodes bytes
- Python bindings → Image I/O: writes image
- Image encoder → Color conversion: converts color
- Color conversion → Wavelet transform: transforms
- Wavelet transform → Subband quantization: provides coefficients
- Subband quantization → SPIHT coding: quantizes for
- SPIHT coding → Range coder: codes symbols
- Image decoder → Range coder: decodes symbols
- Image decoder → Wavelet transform: reconstructs image
- Python bindings → Python utilities: provides
- Python utilities → Image I/O: loads images
- Python utilities → Image encoder: benchmarks encode
- Python utilities → Image decoder: compares decode