IO-PNG: A Modern C++ PNG Library

IO-PNG is a lightweight, object-oriented C++17 library for encoding and decoding PNG (Portable Network Graphics) images from scratch. It is designed with a focus on modern C++ practices, simplicity, and portability, offering full control over the PNG file format without relying on external imaging libraries like libpng.

The library correctly implements the PNG specification, including critical chunks, filtering, and DEFLATE compression, making it a powerful tool for projects that require direct, low-level control over PNG data streams.

Table of Contents

1. Core Philosophy
2. Key Features
3. Performance
4. Prerequisites
5. Building from Source
   • On Linux / macOS
   • On Windows
6. Getting Started
7. API Documentation
8. Author
9. License

💡 Core Philosophy

The goal of IO-PNG was to create a PNG library that is simple, lightweight, and written in a modern, object-oriented style. Many existing libraries are C-based, heavy, or have complex build requirements. IO-PNG provides a powerful yet easy-to-integrate solution for developers who want to understand and manipulate the PNG format at a fundamental level.

✨ Key Features

• Modern C++ Design: Built with C++17, emphasizing an Object-Oriented paradigm with clear class responsibilities (PNG, IHDR_CHUNK, etc.) and exception handling for robust error management.
• No External Image Dependencies: Reads and writes PNG files from scratch. The only dependency is zlib for DEFLATE compression, which is a standard part of most systems.
• High-Performance Encoding: Utilizes multi-threading to dynamically select the best scanline filter for each line of the image. This unique approach optimizes the time-to-compression ratio, resulting in smaller file sizes without a significant performance penalty.
• Cross-Platform Portability: Automatically handles big-endian and little-endian systems to ensure correct file I/O on any architecture.
• Full PNG Specification Support:
  • Color Modes: Grayscale, Grayscale with Alpha, RGB, and RGBA.
  • Bit Depths: Supports 8-bit and 16-bit per channel.
  • Multi-IDAT Chunk Handling: Correctly reads and writes PNG files that split image data across multiple IDAT chunks.
  • Ancillary Chunk Support: Includes support for the pHYs (Physical Pixel Dimensions) chunk.
• Compression Control: Allows developers to choose the compression level (from no compression to best compression) when saving files.

📋 Prerequisites

Before building the project, ensure you have the following installed:

• A C++17 compliant compiler (e.g., GCC, Clang, or MinGW for Windows).
• Make (for Linux/macOS).
• zlib development library.

Dependency Installation

• On Debian / Ubuntu:

  sudo apt-get update
  sudo apt-get install build-essential zlib1g-dev

• On macOS (with Homebrew):

  brew install gcc zlib

• On Windows: Use a development environment like MinGW-w64 (installable via MSYS2). Ensure the bin directory of your toolchain is in your system's PATH.

⚙️ Building from Source

First, clone the repository:

git clone https://github.com/IgorGreenIGM/IO_PNG
cd IO_PNG

On Linux / macOS

Use the provided Makefile to build the project.

1. Open a terminal in the project's root directory.
2. Run make:

   make

3. The executable will be created at bin/output.

To clean up build files:

make clean    # Removes object files (*.o)
make mrproper # Removes object files and the final executable

On Windows

Batch scripts are provided for compiling with a MinGW-w64 toolchain.

1. Open a Command Prompt (cmd) or PowerShell in the project's root directory.
2. Step 1: Compile Sources Run compile.bat to compile all .cpp files into object files.

   compile.bat

3. Step 2: Link Executable Run link.bat to link the object files and create the final executable.

   link.bat

4. The executable will be created at bin\output.exe.

🚀 Getting Started

The project includes a simple main.cpp that demonstrates how to read a PNG file and write it back out.

1. Place an input image named origin.png in the root directory of the project.
2. Build the project using the instructions above for your operating system.
3. Run the executable:
   • On Linux / macOS:

     ./bin/output

   • On Windows:

     .\bin\output.exe

4. Check the output: The program will read origin.png and create two new files:
   • out.png: A copy of the original, re-encoded with the best compression.
   • out2.png: A copy created using the PNG copy constructor.

📖 API Documentation

This project is documented using Doxygen-style comments. You can generate a full HTML and LaTeX API reference.

1. Ensure you have Doxygen installed.
2. From the project root, run:

   doxygen doxyfile

3. The documentation will be generated in the html/ and latex/ directories. Open html/index.html in your browser to view it.

✍️ Author

• @igorgreenIGM - Idea & Initial work

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.