hufi 0.1.0__tar.gz

hufi-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hufi
+Version: 0.1.0
+Summary: A Python library for encoding and decoding .hufi image files.
+Project-URL: Homepage, https://github.com/yourusername/hufipy
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9.0.0
+
+```markdown
+# HUFI (`hufipy`)
+
+A lightweight Python library for encoding, decoding, and inspecting **`.hufi`** (Hagan's Ultimate Format for Images) files. 
+
+`.hufi` is a custom binary image format that pairs horizontal predictive sub-filtering with zlib Deflate compression to achieve fast, efficient, lossless image storage.
+
+---
+
+## Installation
+
+Install via `pip`:
+
+```bash
+pip install hufi
+
+```
+
+---
+
+## Quickstart
+
+### 1. Save and Open `.hufi` Files
+
+```python
+import hufi
+
+# Convert standard image formats (PNG, JPG, WEBP, etc.) to .hufi
+hufi.save("input.png", "output.hufi")
+
+# Load a .hufi file directly as a Pillow (PIL) Image
+img = hufi.open_hufi("output.hufi")
+img.show()
+
+```
+
+### 2. Extract Metadata Fast
+
+Inspect header details without decompressing the entire image payload:
+
+```python
+import hufi
+
+metadata = hufi.get_metadata("output.hufi")
+print(f"Dimensions: {metadata['width']}x{metadata['height']} px")
+print(f"Channels:   {metadata['channels']}")
+print(f"Magic:      {metadata['magic']}")
+
+```
+
+### 3. In-Memory Encoding & Decoding
+
+Work with bytes and Pillow image objects in memory without writing to disk:
+
+```python
+import hufi
+from PIL import Image
+
+# Encode a PIL Image to raw .hufi bytes
+img = Image.open("photo.jpg")
+hufi_bytes = hufi.encode(img, level=6)
+
+# Decode raw .hufi bytes back to a PIL Image
+restored_img = hufi.decode(hufi_bytes)
+
+```
+
+---
+
+## Technical Specification
+
+The `.hufi` format consists of a 13-byte binary header followed by a compressed payload:
+
+| Field | Type | Size | Description |
+| --- | --- | --- | --- |
+| **Magic Signature** | ASCII String | 4 Bytes | Magic bytes `b"HUFI"` |
+| **Width** | Uint32 (Little-Endian) | 4 Bytes | Image width in pixels |
+| **Height** | Uint32 (Little-Endian) | 4 Bytes | Image height in pixels |
+| **Channels** | Uint8 | 1 Byte | Color channels (default `3` for RGB) |
+| **Payload** | Deflate Bytes | Variable | Horizontal sub-filtered byte deltas compressed via Zlib |
+
+---
+
+## License
+
+Licensed under the Apache License, Version 2.0. See `LICENSE` for details.

hufi-0.1.0/README.md

@@ -0,0 +1,86 @@
+```markdown
+# HUFI (`hufipy`)
+
+A lightweight Python library for encoding, decoding, and inspecting **`.hufi`** (Hagan's Ultimate Format for Images) files. 
+
+`.hufi` is a custom binary image format that pairs horizontal predictive sub-filtering with zlib Deflate compression to achieve fast, efficient, lossless image storage.
+
+---
+
+## Installation
+
+Install via `pip`:
+
+```bash
+pip install hufi
+
+```
+
+---
+
+## Quickstart
+
+### 1. Save and Open `.hufi` Files
+
+```python
+import hufi
+
+# Convert standard image formats (PNG, JPG, WEBP, etc.) to .hufi
+hufi.save("input.png", "output.hufi")
+
+# Load a .hufi file directly as a Pillow (PIL) Image
+img = hufi.open_hufi("output.hufi")
+img.show()
+
+```
+
+### 2. Extract Metadata Fast
+
+Inspect header details without decompressing the entire image payload:
+
+```python
+import hufi
+
+metadata = hufi.get_metadata("output.hufi")
+print(f"Dimensions: {metadata['width']}x{metadata['height']} px")
+print(f"Channels:   {metadata['channels']}")
+print(f"Magic:      {metadata['magic']}")
+
+```
+
+### 3. In-Memory Encoding & Decoding
+
+Work with bytes and Pillow image objects in memory without writing to disk:
+
+```python
+import hufi
+from PIL import Image
+
+# Encode a PIL Image to raw .hufi bytes
+img = Image.open("photo.jpg")
+hufi_bytes = hufi.encode(img, level=6)
+
+# Decode raw .hufi bytes back to a PIL Image
+restored_img = hufi.decode(hufi_bytes)
+
+```
+
+---
+
+## Technical Specification
+
+The `.hufi` format consists of a 13-byte binary header followed by a compressed payload:
+
+| Field | Type | Size | Description |
+| --- | --- | --- | --- |
+| **Magic Signature** | ASCII String | 4 Bytes | Magic bytes `b"HUFI"` |
+| **Width** | Uint32 (Little-Endian) | 4 Bytes | Image width in pixels |
+| **Height** | Uint32 (Little-Endian) | 4 Bytes | Image height in pixels |
+| **Channels** | Uint8 | 1 Byte | Color channels (default `3` for RGB) |
+| **Payload** | Deflate Bytes | Variable | Horizontal sub-filtered byte deltas compressed via Zlib |
+
+---
+
+## License
+
+Licensed under the Apache License, Version 2.0. See `LICENSE` for details.

hufi-0.1.0/hufi/__init__.py

@@ -0,0 +1,3 @@
+from .core import encode, decode, save, open_hufi, get_metadata
+
+__all__ = ["encode", "decode", "save", "open_hufi", "get_metadata"]

hufi-0.1.0/hufi/core.py

@@ -0,0 +1,119 @@
+import struct
+import zlib
+from typing import Union, Dict, Any
+from PIL import Image
+
+# Format Specifications
+MAGIC_HEADER = b"HUFI"
+HEADER_FORMAT = "<4sIIB"  # Magic (4s), Width (uint32), Height (uint32), Channels (uint8)
+HEADER_SIZE = struct.calcsize(HEADER_FORMAT)  # 13 bytes
+
+
+def apply_sub_filter(raw_bytes: bytes, width: int, height: int, channels: int = 3) -> bytes:
+    """Applies horizontal predictive sub-filter: delta[x] = (pixel[x] - pixel[x-1]) & 0xFF."""
+    filtered = bytearray(len(raw_bytes))
+    stride = width * channels
+
+    for y in range(height):
+        row_start = y * stride
+        # First pixel in each row remains unchanged
+        filtered[row_start : row_start + channels] = raw_bytes[row_start : row_start + channels]
+
+        # Calculate byte deltas for remaining pixels in row
+        for x in range(1, width):
+            curr_i = row_start + x * channels
+            prev_i = curr_i - channels
+            for c in range(channels):
+                filtered[curr_i + c] = (raw_bytes[curr_i + c] - raw_bytes[prev_i + c]) & 0xFF
+
+    return bytes(filtered)
+
+
+def undo_sub_filter(filtered_bytes: bytes, width: int, height: int, channels: int = 3) -> bytes:
+    """Reconstructs raw pixel data from horizontal byte deltas."""
+    raw = bytearray(len(filtered_bytes))
+    stride = width * channels
+
+    for y in range(height):
+        row_start = y * stride
+        # First pixel in each row
+        raw[row_start : row_start + channels] = filtered_bytes[row_start : row_start + channels]
+
+        # Reconstruct pixel values from left neighbors
+        for x in range(1, width):
+            curr_i = row_start + x * channels
+            prev_i = curr_i - channels
+            for c in range(channels):
+                raw[curr_i + c] = (filtered_bytes[curr_i + c] + raw[prev_i + c]) & 0xFF
+
+    return bytes(raw)
+
+
+def encode(image_input: Union[str, Image.Image], level: int = 6) -> bytes:
+    """Encodes a file path or PIL Image into .hufi binary bytes."""
+    if isinstance(image_input, str):
+        img = Image.open(image_input).convert("RGB")
+    else:
+        img = image_input.convert("RGB")
+
+    width, height = img.size
+    channels = 3
+    raw_rgb = img.tobytes()
+
+    filtered_data = apply_sub_filter(raw_rgb, width, height, channels)
+    compressed_payload = zlib.compress(filtered_data, level=level)
+    header = struct.pack(HEADER_FORMAT, MAGIC_HEADER, width, height, channels)
+
+    return header + compressed_payload
+
+
+def decode(hufi_bytes: bytes) -> Image.Image:
+    """Decodes .hufi binary bytes into a PIL Image object."""
+    if len(hufi_bytes) < HEADER_SIZE:
+        raise ValueError("Data is too small to contain a valid .hufi header.")
+
+    magic, width, height, channels = struct.unpack(HEADER_FORMAT, hufi_bytes[:HEADER_SIZE])
+    if magic != MAGIC_HEADER:
+        raise ValueError(f"Invalid format signature: expected {MAGIC_HEADER}, got {magic}")
+
+    compressed_payload = hufi_bytes[HEADER_SIZE:]
+    filtered_data = zlib.decompress(compressed_payload)
+    raw_rgb = undo_sub_filter(filtered_data, width, height, channels)
+
+    return Image.frombytes("RGB", (width, height), raw_rgb)
+
+
+def save(image_input: Union[str, Image.Image], output_path: str, level: int = 6) -> None:
+    """Encodes an image and writes it directly to disk as a .hufi file."""
+    binary_data = encode(image_input, level=level)
+    with open(output_path, "wb") as f:
+        f.write(binary_data)
+
+
+def open_hufi(filepath: str) -> Image.Image:
+    """Reads a .hufi file from disk and returns a PIL Image."""
+    with open(filepath, "rb") as f:
+        return decode(f.read())
+
+
+def get_metadata(filepath_or_bytes: Union[str, bytes]) -> Dict[str, Any]:
+    """Reads header information without decompressing the payload."""
+    if isinstance(filepath_or_bytes, str):
+        with open(filepath_or_bytes, "rb") as f:
+            header_bytes = f.read(HEADER_SIZE)
+    else:
+        header_bytes = filepath_or_bytes[:HEADER_SIZE]
+
+    if len(header_bytes) < HEADER_SIZE:
+        raise ValueError("Header is corrupted or too short.")
+
+    magic, width, height, channels = struct.unpack(HEADER_FORMAT, header_bytes)
+    if magic != MAGIC_HEADER:
+        raise ValueError(f"Invalid HUFI signature: {magic}")
+
+    return {
+        "magic": magic.decode("ascii"),
+        "width": width,
+        "height": height,
+        "channels": channels,
+    }

hufi-0.1.0/hufi.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hufi
+Version: 0.1.0
+Summary: A Python library for encoding and decoding .hufi image files.
+Project-URL: Homepage, https://github.com/yourusername/hufipy
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9.0.0
+
+```markdown
+# HUFI (`hufipy`)
+
+A lightweight Python library for encoding, decoding, and inspecting **`.hufi`** (Hagan's Ultimate Format for Images) files. 
+
+`.hufi` is a custom binary image format that pairs horizontal predictive sub-filtering with zlib Deflate compression to achieve fast, efficient, lossless image storage.
+
+---
+
+## Installation
+
+Install via `pip`:
+
+```bash
+pip install hufi
+
+```
+
+---
+
+## Quickstart
+
+### 1. Save and Open `.hufi` Files
+
+```python
+import hufi
+
+# Convert standard image formats (PNG, JPG, WEBP, etc.) to .hufi
+hufi.save("input.png", "output.hufi")
+
+# Load a .hufi file directly as a Pillow (PIL) Image
+img = hufi.open_hufi("output.hufi")
+img.show()
+
+```
+
+### 2. Extract Metadata Fast
+
+Inspect header details without decompressing the entire image payload:
+
+```python
+import hufi
+
+metadata = hufi.get_metadata("output.hufi")
+print(f"Dimensions: {metadata['width']}x{metadata['height']} px")
+print(f"Channels:   {metadata['channels']}")
+print(f"Magic:      {metadata['magic']}")
+
+```
+
+### 3. In-Memory Encoding & Decoding
+
+Work with bytes and Pillow image objects in memory without writing to disk:
+
+```python
+import hufi
+from PIL import Image
+
+# Encode a PIL Image to raw .hufi bytes
+img = Image.open("photo.jpg")
+hufi_bytes = hufi.encode(img, level=6)
+
+# Decode raw .hufi bytes back to a PIL Image
+restored_img = hufi.decode(hufi_bytes)
+
+```
+
+---
+
+## Technical Specification
+
+The `.hufi` format consists of a 13-byte binary header followed by a compressed payload:
+
+| Field | Type | Size | Description |
+| --- | --- | --- | --- |
+| **Magic Signature** | ASCII String | 4 Bytes | Magic bytes `b"HUFI"` |
+| **Width** | Uint32 (Little-Endian) | 4 Bytes | Image width in pixels |
+| **Height** | Uint32 (Little-Endian) | 4 Bytes | Image height in pixels |
+| **Channels** | Uint8 | 1 Byte | Color channels (default `3` for RGB) |
+| **Payload** | Deflate Bytes | Variable | Horizontal sub-filtered byte deltas compressed via Zlib |
+
+---
+
+## License
+
+Licensed under the Apache License, Version 2.0. See `LICENSE` for details.

hufi-0.1.0/hufi.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+hufi/__init__.py
+hufi/core.py
+hufi.egg-info/PKG-INFO
+hufi.egg-info/SOURCES.txt
+hufi.egg-info/dependency_links.txt
+hufi.egg-info/requires.txt
+hufi.egg-info/top_level.txt

hufi-0.1.0/hufi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hufi-0.1.0/hufi.egg-info/requires.txt

@@ -0,0 +1 @@
+Pillow>=9.0.0

hufi-0.1.0/hufi.egg-info/top_level.txt

@@ -0,0 +1 @@
+hufi

hufi-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hufi"
+version = "0.1.0"
+description = "A Python library for encoding and decoding .hufi image files."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "Pillow>=9.0.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/yourusername/hufipy"

hufi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+