lib-tiny-png 0.1.0__tar.gz

lib_tiny_png-0.1.0/CMakeLists.txt

@@ -0,0 +1,135 @@
+cmake_minimum_required(VERSION 4.0)
+project(TinyPNG)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+option(TINY_PNG_ENABLE_TESTS "Build tests" OFF)
+option(TINY_PNG_ENABLE_STRICT "Use strict compile options" OFF)
+option(TINY_PNG_ENABLE_COVERAGE "Enable coverage reporting" OFF)
+option(TINY_PNG_BIND_PYTHON "Enable Python binding" OFF)
+option(TINY_PNG_BIND_ES "Enable ECMAScript binding" OFF)
+
+if(APPLE)
+    set(ENV{PKG_CONFIG_PATH} "/opt/homebrew/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
+endif()
+
+if(TINY_PNG_ENABLE_STRICT)
+    if (CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+        add_compile_options(
+                -Wall
+                -Wextra
+                -Werror
+                -Wpedantic
+                -Wmissing-include-dirs
+                -Wundef
+                -Wredundant-decls
+        )
+    endif()
+endif()
+
+if(TINY_PNG_ENABLE_COVERAGE)
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+        add_compile_options(--coverage -O0 -g -fno-elide-constructors)
+        add_link_options(--coverage)
+    endif()
+endif()
+
+add_library(TinyPNG STATIC
+        include/tiny_png/constants.h
+        include/tiny_png/lz77.h
+        src/lz77.cpp
+        include/tiny_png/bit_stream.h
+        src/bit_stream.cpp
+        include/tiny_png/huffman.h
+        src/huffman.cpp
+        include/tiny_png/deflate.h
+        src/deflate.cpp
+        include/tiny_png/png_chunk.h
+        src/png_chunk.cpp
+        include/tiny_png/tiny_png.h
+        src/tiny_png.cpp
+)
+
+target_include_directories(TinyPNG
+        PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+if(TINY_PNG_ENABLE_TESTS)
+    enable_testing()
+
+    include(FetchContent)
+
+    FetchContent_Declare(
+            googletest
+            GIT_REPOSITORY https://github.com/google/googletest.git
+            GIT_TAG v1.17.0
+    )
+
+    FetchContent_MakeAvailable(googletest)
+
+    add_executable(runTests
+            tests/test_lz77.cpp
+            tests/test_bit_stream.cpp
+            tests/test_huffman.cpp
+            tests/test_deflate.cpp
+            tests/test_png_chunk.cpp
+            tests/test_tiny_png.cpp
+    )
+
+    target_link_libraries(runTests
+            PRIVATE TinyPNG
+            PRIVATE gtest gtest_main
+    )
+
+    target_compile_definitions(runTests
+            PRIVATE TINY_PNG_TEST_DATA_DIR="${CMAKE_CURRENT_SOURCE_DIR}/tests/data"
+    )
+
+    add_test(NAME TinyPNGTests COMMAND runTests)
+endif()
+
+if(TINY_PNG_BIND_PYTHON)
+    include(FetchContent)
+    FetchContent_Declare(
+            pybind11
+            GIT_REPOSITORY https://github.com/pybind/pybind11.git
+            GIT_TAG v3.0
+    )
+    FetchContent_MakeAvailable(pybind11)
+
+    pybind11_add_module(_core
+            python/binding.cpp
+    )
+    target_link_libraries(_core
+            PRIVATE TinyPNG
+    )
+    install(TARGETS _core
+            LIBRARY DESTINATION tiny_png)
+    install(FILES python/wrapper/__init__.py DESTINATION tiny_png)
+endif()
+
+if(TINY_PNG_BIND_ES)
+    add_executable(TinyPNGWASM
+            wasm/binding.cpp
+    )
+
+    target_link_libraries(TinyPNGWASM
+            PRIVATE TinyPNG
+    )
+
+    target_compile_options(TinyPNGWASM PRIVATE "-O3" "-sNO_DISABLE_EXCEPTION_CATCHING")
+
+    set_target_properties(TinyPNGWASM PROPERTIES SUFFIX ".js")
+
+    target_link_options(TinyPNGWASM PRIVATE
+            "--bind"
+            "-sMODULARIZE=1"
+            "-sEXPORT_ES6=1"
+            "-sEXPORT_NAME=TinyPNGWASMModule"
+            "-sALLOW_MEMORY_GROWTH=1"
+            "-sNO_DISABLE_EXCEPTION_CATCHING"
+    )
+endif()

lib_tiny_png-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.2
+Name: lib-tiny-png
+Version: 0.1.0
+Summary: A lightweight, minimal PNG library.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: OS Independent
+Project-URL: Homepage, https://github.com/CyberZHG/TinyPNG
+Project-URL: Repository, https://github.com/CyberZHG/TinyPNG
+Project-URL: Issues, https://github.com/CyberZHG/TinyPNG/issues
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: black; extra == "test"
+Requires-Dist: isort; extra == "test"
+Requires-Dist: flake8; extra == "test"
+Description-Content-Type: text/markdown
+
+# TinyPNG
+
+A lightweight, minimal PNG library.
+
+## Installation
+
+```bash
+pip install lib-tiny-png
+```
+
+## Usage
+
+```python
+from tiny_png import ColorType, load_image, save_image
+
+width, height = 4, 2
+pixels = bytes([255, 0, 0, 255] * (width * height))  # Red RGBA pixels
+save_image("red.png", width, height, pixels)
+
+image = load_image("red.png")
+if image.error:
+    print(image.error)
+else:
+    print(image.width, image.height, image.color_type)  # 4 2 ColorType.RGBA
+    print(image.buffer == pixels)  # True
+
+gray = bytes(range(16))
+save_image("gray.png", 4, 4, gray, ColorType.GRAYSCALE)
+```
+
+## API Reference
+
+### `ColorType`
+
+`GRAYSCALE` (1 byte per pixel), `GRAYSCALE_ALPHA` (2), `RGB` (3), `RGBA` (4).
+
+### `save_image(file_path, width, height, data, color_type=ColorType.RGBA)`
+
+Saves row-major 8-bit pixels as a PNG file.
+
+**Parameters:**
+- `file_path` (`str`) - The output file path.
+- `width`, `height` (`int`) - The image size in pixels.
+- `data` (`bytes`, `bytearray` or any uint8 buffer) - Pixels of size `width * height * channels`.
+- `color_type` (`ColorType`, optional) - The color type of the pixels.
+
+**Returns:**
+- `bool` - `True` if the image is saved.
+
+**Raises:**
+- `ValueError` - If the size of `data` does not match the image size.
+
+### `load_image(file_path)`
+
+Loads a PNG file.
+
+**Returns:**
+- `PNGData` - With fields `width`, `height`, `color_type`, `buffer` (`bytes`) and `error` (`str`, empty on success).

lib_tiny_png-0.1.0/include/tiny_png/bit_stream.h

@@ -0,0 +1,44 @@
+#ifndef TINYPNG_BIT_STREAM_H
+#define TINYPNG_BIT_STREAM_H
+
+#include <cstdint>
+#include <vector>
+#include <string>
+
+namespace tiny_png {
+
+    class BitStream {
+    public:
+        BitStream();
+
+        [[nodiscard]] const std::vector<uint8_t>& getBytes() const {
+            return _buffer;
+        }
+        template<typename InputIterator>
+        void setBytes(InputIterator first, InputIterator last) {
+            _buffer.assign(first, last);
+            _index = _buffer.size();
+            _pos = 0;
+            _readIndex = 0;
+        }
+
+        void writeInt(std::int32_t value, std::int32_t numBits, bool msb);
+
+        void rewind();
+        bool nextBit();
+        void alignToByte();
+        std::int32_t readInt(std::int32_t numBits, bool msb);
+
+        [[nodiscard]] std::string toString() const;
+
+    private:
+        std::size_t _index;
+        std::uint8_t _pos;
+        std::vector<std::uint8_t> _buffer;
+
+        std::size_t _readIndex;
+    };
+
+}
+
+#endif //TINYPNG_BIT_STREAM_H

lib_tiny_png-0.1.0/include/tiny_png/constants.h

@@ -0,0 +1,29 @@
+#ifndef TINYPNG_CONSTANTS_H
+#define TINYPNG_CONSTANTS_H
+
+#include <cstdint>
+
+namespace tiny_png {
+
+    enum class ColorType {
+        Grayscale = 0,
+        RGB = 2,
+        GrayscaleAlpha = 4,
+        RGBA = 6
+    };
+
+    enum class FilterType {
+        None = 0,
+        Sub = 1,
+        Up = 2,
+        Average = 3,
+        Paeth = 4,
+    };
+
+    constexpr std::uint16_t LZ77_MIN_MATCH_LEN = 3;
+    constexpr std::uint16_t LZ77_MAX_MATCH_LEN = 258;
+    constexpr std::uint16_t LZ77_MAX_MATCH_OFFSET = 32768;
+
+}
+
+#endif //TINYPNG_CONSTANTS_H

lib_tiny_png-0.1.0/include/tiny_png/deflate.h

@@ -0,0 +1,14 @@
+#ifndef TINYPNG_DEFLATE_H
+#define TINYPNG_DEFLATE_H
+
+#include <cstdint>
+#include <vector>
+
+namespace tiny_png {
+
+    std::vector<std::uint8_t> deflate_encode(const std::uint8_t* data, std::size_t len);
+    std::vector<std::uint8_t> deflate_decode(const std::vector<std::uint8_t>& data);
+
+}
+
+#endif //TINYPNG_DEFLATE_H

lib_tiny_png-0.1.0/include/tiny_png/huffman.h

@@ -0,0 +1,14 @@
+#ifndef TINYPNG_HUFFMAN_H
+#define TINYPNG_HUFFMAN_H
+
+#include "tiny_png/bit_stream.h"
+#include "tiny_png/lz77.h"
+
+namespace tiny_png {
+
+    BitStream huffman_encode(const std::vector<LZ77Seq>& seqs);
+    std::vector<LZ77Seq> huffman_decode(BitStream& bits);
+
+}
+
+#endif //TINYPNG_HUFFMAN_H

lib_tiny_png-0.1.0/include/tiny_png/lz77.h

@@ -0,0 +1,27 @@
+#ifndef TINYPNG_LZ77_H
+#define TINYPNG_LZ77_H
+
+#include <cstdint>
+#include <vector>
+
+namespace tiny_png {
+
+    struct LZ77Seq {
+        std::uint8_t byte;
+        std::uint16_t len;
+        std::uint16_t dist;
+
+        LZ77Seq(const std::uint8_t byte, const std::uint16_t len, const std::uint16_t dist) : byte(byte), len(len), dist(dist) {}
+
+        bool operator==(const LZ77Seq& other) const {
+            return byte == other.byte && len == other.len && dist == other.dist;
+        }
+    };
+
+    std::vector<LZ77Seq> lz77_encode(const std::uint8_t* data, std::size_t len);
+
+    std::vector<std::uint8_t> lz77_decode(const std::vector<LZ77Seq>& seqs);
+
+}
+
+#endif //TINYPNG_LZ77_H

lib_tiny_png-0.1.0/include/tiny_png/png_chunk.h

@@ -0,0 +1,29 @@
+#ifndef TINYPNG_PNG_CHUNK_H
+#define TINYPNG_PNG_CHUNK_H
+
+#include <cstdint>
+#include <vector>
+#include <utility>
+#include "tiny_png/constants.h"
+
+namespace tiny_png {
+
+    enum class ChunkType {
+        I_HEADER, I_DATA, I_END, OTHER
+    };
+
+    struct Header {
+        std::uint32_t width, height;
+        std::uint8_t bitDepth, colorType, compressionMethod, filterMethod, interlaceMethod;
+    };
+
+    void addHeaderChunk(std::vector<std::uint8_t>& buffer, std::uint32_t width, std::uint32_t height, ColorType colorType);
+    void addDataChunk(std::vector<std::uint8_t>& buffer, const std::vector<std::uint8_t>& data);
+    void addEndChunk(std::vector<std::uint8_t>& buffer);
+
+    std::pair<std::uint32_t, ChunkType> readChunkInfo(const std::vector<std::uint8_t>& buffer, std::size_t& pos);
+    Header readHeaderChunk(const std::vector<std::uint8_t>& buffer, std::size_t& pos);
+
+}
+
+#endif //TINYPNG_PNG_CHUNK_H

lib_tiny_png-0.1.0/include/tiny_png/tiny_png.h

@@ -0,0 +1,25 @@
+#ifndef TINYPNG_TINY_PNG_H
+#define TINYPNG_TINY_PNG_H
+
+#include <string>
+#include <vector>
+#include "tiny_png/constants.h"
+
+namespace tiny_png {
+
+    struct PNGData {
+        std::size_t width;
+        std::size_t height;
+        ColorType colorType;
+        std::vector<std::uint8_t> buffer;
+        std::string error;
+
+        PNGData();
+    };
+
+    bool save_image(const std::string& filePath, std::uint32_t width, std::uint32_t height, const std::uint8_t* data, ColorType colorType = ColorType::RGBA);
+    PNGData load_image(const std::string& filePath);
+
+}
+
+#endif //TINYPNG_TINY_PNG_H

lib_tiny_png-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["scikit-build-core", "pybind11"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "lib-tiny-png"
+version = "0.1.0"
+description = "A lightweight, minimal PNG library."
+requires-python = ">=3.8"
+readme = "python/README.md"
+license = { text = "MIT" }
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/CyberZHG/TinyPNG"
+Repository = "https://github.com/CyberZHG/TinyPNG"
+Issues = "https://github.com/CyberZHG/TinyPNG/issues"
+
+[tool.scikit-build]
+build-dir = "../cmake-build-python/{wheel_tag}"
+build.verbose = true
+
+[tool.scikit-build.cmake.define]
+TINY_PNG_BIND_PYTHON = "ON"
+
+[tool.scikit-build.sdist]
+exclude = [
+    ".*",
+    "build*",
+    "cmake-build*",
+    "dist",
+    "demo",
+    "tests",
+    "wasm",
+    "*.md",
+    "python/tests",
+]
+include = [
+    "python/README.md",
+]
+
+[tool.black]
+line-length = 120
+
+[tool.isort]
+profile = "black"
+line_length = 120
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "black",
+    "isort",
+    "flake8",
+]

lib_tiny_png-0.1.0/python/README.md

@@ -0,0 +1,58 @@
+# TinyPNG
+
+A lightweight, minimal PNG library.
+
+## Installation
+
+```bash
+pip install lib-tiny-png
+```
+
+## Usage
+
+```python
+from tiny_png import ColorType, load_image, save_image
+
+width, height = 4, 2
+pixels = bytes([255, 0, 0, 255] * (width * height))  # Red RGBA pixels
+save_image("red.png", width, height, pixels)
+
+image = load_image("red.png")
+if image.error:
+    print(image.error)
+else:
+    print(image.width, image.height, image.color_type)  # 4 2 ColorType.RGBA
+    print(image.buffer == pixels)  # True
+
+gray = bytes(range(16))
+save_image("gray.png", 4, 4, gray, ColorType.GRAYSCALE)
+```
+
+## API Reference
+
+### `ColorType`
+
+`GRAYSCALE` (1 byte per pixel), `GRAYSCALE_ALPHA` (2), `RGB` (3), `RGBA` (4).
+
+### `save_image(file_path, width, height, data, color_type=ColorType.RGBA)`
+
+Saves row-major 8-bit pixels as a PNG file.
+
+**Parameters:**
+- `file_path` (`str`) - The output file path.
+- `width`, `height` (`int`) - The image size in pixels.
+- `data` (`bytes`, `bytearray` or any uint8 buffer) - Pixels of size `width * height * channels`.
+- `color_type` (`ColorType`, optional) - The color type of the pixels.
+
+**Returns:**
+- `bool` - `True` if the image is saved.
+
+**Raises:**
+- `ValueError` - If the size of `data` does not match the image size.
+
+### `load_image(file_path)`
+
+Loads a PNG file.
+
+**Returns:**
+- `PNGData` - With fields `width`, `height`, `color_type`, `buffer` (`bytes`) and `error` (`str`, empty on success).

lib_tiny_png-0.1.0/python/binding.cpp

@@ -0,0 +1,102 @@
+#include <stdexcept>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include "tiny_png/tiny_png.h"
+using namespace tiny_png;
+
+namespace py = pybind11;
+
+static std::size_t getBytesPerPixel(const ColorType colorType) {
+    switch (colorType) {
+        case ColorType::Grayscale: return 1;
+        case ColorType::RGB: return 3;
+        case ColorType::GrayscaleAlpha: return 2;
+        case ColorType::RGBA: return 4;
+    }
+    return 4;
+}
+
+static bool saveImage(const std::string& filePath,
+                      const std::uint32_t width,
+                      const std::uint32_t height,
+                      const py::buffer& data,
+                      const ColorType colorType) {
+    const py::buffer_info info = data.request();
+    if (info.itemsize != 1) {
+        throw py::value_error("data must be a buffer of uint8 values");
+    }
+    const auto expected = static_cast<std::size_t>(width) * height * getBytesPerPixel(colorType);
+    if (static_cast<std::size_t>(info.size) != expected) {
+        throw py::value_error("data size mismatch: expected " + std::to_string(expected) +
+                              " bytes, got " + std::to_string(info.size));
+    }
+    return save_image(filePath, width, height, static_cast<const std::uint8_t*>(info.ptr), colorType);
+}
+
+static PNGData loadImage(const std::string& filePath) {
+    try {
+        return load_image(filePath);
+    } catch (const std::exception& e) {
+        PNGData imageData;
+        imageData.error = std::string("Failed to load image: ") + e.what();
+        return imageData;
+    }
+}
+
+PYBIND11_MODULE(_core, m, py::mod_gil_not_used()) {
+    m.doc() = "A lightweight, minimal PNG library.";
+
+    py::enum_<ColorType>(m, "ColorType")
+        .value("GRAYSCALE", ColorType::Grayscale)
+        .value("RGB", ColorType::RGB)
+        .value("GRAYSCALE_ALPHA", ColorType::GrayscaleAlpha)
+        .value("RGBA", ColorType::RGBA);
+
+    py::class_<PNGData>(m, "PNGData")
+        .def_readonly("width", &PNGData::width)
+        .def_readonly("height", &PNGData::height)
+        .def_readonly("color_type", &PNGData::colorType)
+        .def_property_readonly("buffer", [](const PNGData& self) {
+            return py::bytes(reinterpret_cast<const char*>(self.buffer.data()), self.buffer.size());
+        })
+        .def_readonly("error", &PNGData::error)
+        .def("__repr__", [](const PNGData& self) {
+            return "<PNGData width=" + std::to_string(self.width) +
+                   " height=" + std::to_string(self.height) +
+                   " color_type=" + std::to_string(static_cast<int>(self.colorType)) +
+                   " error='" + self.error + "'>";
+        });
+
+    m.def("save_image", &saveImage,
+          py::arg("file_path"), py::arg("width"), py::arg("height"), py::arg("data"),
+          py::arg("color_type") = ColorType::RGBA,
+          R"pbdoc(
+Save raw pixels as a PNG file.
+
+Args:
+    file_path: The output file path.
+    width: Image width in pixels.
+    height: Image height in pixels.
+    data: Row-major pixel bytes (bytes, bytearray or any uint8 buffer) of size
+          width * height * channels.
+    color_type: The color type of the pixels (default: ColorType.RGBA).
+
+Returns:
+    True if the image is saved.
+
+Raises:
+    ValueError: If the size of data does not match the image size.
+)pbdoc");
+
+    m.def("load_image", &loadImage,
+          py::arg("file_path"),
+          R"pbdoc(
+Load a PNG file.
+
+Args:
+    file_path: The input file path.
+
+Returns:
+    A PNGData object. If loading fails, its error field is non-empty.
+)pbdoc");
+}

lib_tiny_png-0.1.0/python/wrapper/__init__.py

@@ -0,0 +1,3 @@
+from ._core import ColorType, PNGData, load_image, save_image
+
+__all__ = ["ColorType", "PNGData", "load_image", "save_image"]