How adrienb2/qoi-encoder-go works
Project Type and Purpose
• This is a single-binary Command Line Interface (CLI) tool written in Go.
• Purpose: lossless image conversion between PNG and QOI formats, with optional benchmarking and batch processing.
File Structure
Top-level directories and files:
• cmd/
– root.go (defines the CLI root command and common flags)
– encode.go (implements the “encode” subcommand)
– decode.go (implements the “decode” subcommand)
• qoi/
– encoder.go, decoder.go (core QOI algorithm implementations)
– spec.go (format definitions)
– *_test.go (unit tests)
• png/
– png.go (PNG decoding/encoding wrapper)
• imageUtils/
– image.go (helpers for image manipulation, pixel buffers)
• utils/
– utils.go (shared utilities: file traversal, error handling, benchmarking helper)
• main.go (initializes CLI application by importing cmd package)
• Makefile, go.mod/sum (build, dependency management)
• assets/ (test images, not part of production flow)
README Insights
• CLI offers two commands: encode and decode.
• Flags: input/output path, batch mode, benchmark mode, help.
• Performance metrics (benchmarking) are part of the tool’s feature set.
Main Components & Their Relationships
A. CLI Layer
• root command (common flags parser)
• encode subcommand
• decode subcommand
B. Core Processing Layer
1. QOI Package
• qoi.encoder.Encode(inputImage) → byte stream
• qoi.decoder.Decode(byte stream) → image data
2. PNG Package
• png.Decode(file) → image data
• png.Encode(image data) → file
encode command → png.Decode → image data → qoi.encoder.Encode → QOI output
decode command → qoi.decoder.Decode → image data → png.Encode → PNG output
C. Utility Layer
• imageUtils – image buffer and pixel operations
• utils –
– FileSystem walker (batch mode)
– Benchmark timer & reporter
– Error & logging helpers
D. File System & External Interfaces
• File System (read/write)
• STDOUT/STDERR (benchmark results, error messages)
• OS Environment (flags, exit codes)
Architectural Patterns
• Command Pattern: each subcommand (encode/decode) encapsulates one operation.
• Layered Architecture: CLI → Core Algorithm → Utilities → I/O.
• Package Modularization:
• qoi package is self-contained for format logic.
• png package isolates PNG details.
• utils and imageUtils provide cross-cutting concerns.
Detailed Elements to Capture
• Flag parsing & validation module inside cmd/root.go
• Subcommand handlers in cmd/encode.go and cmd/decode.go
• QOI spec reference in qoi/spec.go (annotate as “Format Definition”)
• Unit tests in qoi/*_test.go and encoder/decoder_test.go (optionally shown as a testing overlay)
• Benchmarking hook in utils (timers around encode/decode calls)
• File traversal logic for batch mode in utils