pylibheif 1.21.2__tar.gz

pylibheif-1.21.2/.github/workflows/build.yml

@@ -0,0 +1,105 @@
+name: Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-14]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Linux dependencies
+      - name: Install Linux dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libopenjp2-7-dev nasm
+
+      # macOS dependencies
+      - name: Install macOS dependencies
+        if: runner.os == 'macOS'
+        run: |
+          brew install openjpeg nasm
+
+      # Windows dependencies
+      - name: Install Windows dependencies
+        if: runner.os == 'Windows'
+        run: |
+          choco install nasm
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.0
+        env:
+          # Build for Python 3.11-3.14
+          CIBW_BUILD: cp311-* cp312-* cp313-* cp314-*
+          # Skip 32-bit builds and musllinux
+          CIBW_SKIP: "*-win32 *-manylinux_i686 *musllinux*"
+          # Install build dependencies
+          CIBW_BEFORE_BUILD_LINUX: |
+            yum install -y openjpeg2-devel nasm || apt-get install -y libopenjp2-7-dev nasm
+          CIBW_BEFORE_BUILD_MACOS: |
+            brew install openjpeg nasm
+          # Test the wheel
+          CIBW_TEST_REQUIRES: pytest numpy
+          CIBW_TEST_COMMAND: pytest {project}/tests -v
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pylibheif
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pylibheif-1.21.2/.gitignore

@@ -0,0 +1,41 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# CMake build files
+build_*/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Compiled extensions
+*.so
+*.dylib
+*.pyd
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Test output files
+images/output_*
+
+# Lock files (optional, comment out if you want to track)
+# uv.lock
+
+.cache

pylibheif-1.21.2/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "third_party/libheif"]
+	path = third_party/libheif
+	url = https://github.com/strukturag/libheif

pylibheif-1.21.2/.python-version

@@ -0,0 +1 @@
+3.12

pylibheif-1.21.2/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.15)
+project(pylibheif LANGUAGES C CXX)
+
+# Find pybind11
+find_package(pybind11 REQUIRED)
+
+# libheif options
+set(WITH_EXAMPLES OFF CACHE BOOL "Build examples" FORCE)
+set(WITH_RAV1E OFF CACHE BOOL "Build rav1e" FORCE)
+set(WITH_DAV1D ON CACHE BOOL "Build dav1d" FORCE)
+set(WITH_AOM ON CACHE BOOL "Build aom" FORCE)
+set(WITH_X265 ON CACHE BOOL "Build x265" FORCE)
+set(WITH_LIBDE265 ON CACHE BOOL "Build libde265" FORCE)
+set(WITH_OpenJPEG_ENCODER ON CACHE BOOL "Build OpenJPEG encoder" FORCE)
+set(WITH_OpenJPEG_DECODER ON CACHE BOOL "Build OpenJPEG decoder" FORCE)
+
+# Disable plugin mode - build codecs as built-in
+set(WITH_DAV1D_PLUGIN OFF CACHE BOOL "Build dav1d as plugin" FORCE)
+set(WITH_AOM_DECODER_PLUGIN OFF CACHE BOOL "Build AOM decoder as plugin" FORCE)
+set(WITH_AOM_ENCODER_PLUGIN OFF CACHE BOOL "Build AOM encoder as plugin" FORCE)
+set(WITH_OpenJPEG_ENCODER_PLUGIN OFF CACHE BOOL "Build OpenJPEG encoder as plugin" FORCE)
+set(WITH_OpenJPEG_DECODER_PLUGIN OFF CACHE BOOL "Build OpenJPEG decoder as plugin" FORCE)
+set(ENABLE_PLUGIN_LOADING OFF CACHE BOOL "Disable plugin loading" FORCE)
+
+# Add libheif submodule
+set(BUILD_SHARED_LIBS OFF CACHE BOOL "Build shared libraries" FORCE)
+add_subdirectory(third_party/libheif)
+
+# Define the extension module
+pybind11_add_module(pylibheif
+    src/main.cpp
+    src/context.cpp
+    src/image.cpp
+    src/encoder.cpp
+)
+
+# Link with libheif
+target_link_libraries(pylibheif PRIVATE heif)
+
+# Include directories
+target_include_directories(pylibheif PRIVATE
+    src
+    third_party/libheif/libheif/api
+    ${CMAKE_CURRENT_BINARY_DIR}/third_party/libheif
+)
+
+# C++ standard
+target_compile_features(pylibheif PRIVATE cxx_std_17)
+
+# Install the module
+install(TARGETS pylibheif DESTINATION .)

pylibheif-1.21.2/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.2
+Name: pylibheif
+Version: 1.21.2
+Summary: Python bindings for libheif - HEIC/AVIF/JPEG2000 image codec
+Keywords: heif,heic,avif,jpeg2000,image,codec,libheif
+Author-Email: Curry Tang <twn39@163.com>
+License: LGPL-3.0-or-later
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C++
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Project-URL: Homepage, https://github.com/twn39/pylibheif
+Project-URL: Repository, https://github.com/twn39/pylibheif
+Project-URL: Documentation, https://github.com/twn39/pylibheif#readme
+Project-URL: Issues, https://github.com/twn39/pylibheif/issues
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26.0
+Description-Content-Type: text/markdown
+
+# pylibheif
+
+Python bindings for [libheif](https://github.com/strukturag/libheif) using pybind11.
+
+## Features
+
+- **HEIC/HEIF Support**: Read and write HEIC images (HEVC/H.265 encoded)
+- **AVIF Support**: Read and write AVIF images (AV1 encoded)
+- **JPEG2000 Support**: Read and write JPEG2000 images in HEIF container
+- **NumPy Integration**: Zero-copy access to image data via Python Buffer Protocol
+- **Metadata Support**: Read EXIF and XMP metadata from images
+- **RAII Resource Management**: Automatic resource cleanup with context managers
+
+## Supported Formats
+
+| Format | Decoding | Encoding | Codec |
+|--------|----------|----------|-------|
+| HEIC (HEVC/H.265) | ✅ | ✅ | libde265 / x265 |
+| AVIF (AV1) | ✅ | ✅ | DAV1D + AOM |
+| JPEG2000 | ✅ | ✅ | OpenJPEG |
+
+## Requirements
+
+- Python >= 3.12
+- NumPy >= 1.26.0
+- CMake >= 3.15
+- C++17 compatible compiler
+
+### System Dependencies
+
+```bash
+# macOS
+brew install openjpeg
+
+# Ubuntu/Debian
+sudo apt install libopenjp2-7-dev
+```
+
+## Installation
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/your-username/pylibheif.git
+cd pylibheif
+
+# Install with uv (recommended)
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+## Usage
+
+### Reading HEIC/AVIF Images
+
+**Using context manager (recommended):**
+
+```python
+import pylibheif
+import numpy as np
+
+# Open HEIC file with context manager
+with pylibheif.HeifContext() as ctx:
+    ctx.read_from_file('image.heic')
+    
+    # Get primary image handle
+    handle = ctx.get_primary_image_handle()
+    print(f'Image size: {handle.width}x{handle.height}')
+    print(f'Has alpha: {handle.has_alpha}')
+    
+    # Decode to RGB
+    img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                        pylibheif.HeifChroma.InterleavedRGB)
+    
+    # Get as NumPy array (zero-copy)
+    plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+    arr = np.asarray(plane)  # shape: (height, width, 3)
+```
+
+**Explicit creation (for more control):**
+
+```python
+import pylibheif
+import numpy as np
+
+# Create context explicitly
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('image.heic')
+
+handle = ctx.get_primary_image_handle()
+img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                    pylibheif.HeifChroma.InterleavedRGB)
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+arr = np.asarray(plane)
+
+# Resources are automatically freed when objects go out of scope
+```
+
+### Writing HEIC/AVIF Images
+
+```python
+import pylibheif
+import numpy as np
+
+# Create image from NumPy array
+width, height = 1920, 1080
+img = pylibheif.HeifImage(width, height, 
+                          pylibheif.HeifColorspace.RGB,
+                          pylibheif.HeifChroma.InterleavedRGB)
+img.add_plane(pylibheif.HeifChannel.Interleaved, width, height, 8)
+
+# Fill with data
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, True)
+arr = np.asarray(plane)
+arr[:] = your_image_data  # your RGB data
+
+# Encode and save
+ctx = pylibheif.HeifContext()
+
+# For HEIC (HEVC)
+encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.HEVC)
+# For AVIF (AV1)
+# encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.AV1)
+# For JPEG2000
+# encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.JPEG2000)
+
+encoder.set_lossy_quality(85)
+encoder.encode_image(ctx, img)
+ctx.write_to_file('output.heic')
+```
+
+### Converting HEIC to JPEG
+
+```python
+import pylibheif
+import numpy as np
+from PIL import Image
+
+# Decode HEIC
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('input.heic')
+handle = ctx.get_primary_image_handle()
+img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                    pylibheif.HeifChroma.InterleavedRGB)
+
+# Get NumPy array
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+arr = np.asarray(plane)
+
+# Save as JPEG using PIL
+pil_img = Image.fromarray(arr)
+pil_img.save('output.jpg', 'JPEG', quality=85)
+```
+
+### Reading Metadata
+
+```python
+import pylibheif
+
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('image.heic')
+handle = ctx.get_primary_image_handle()
+
+# Get metadata block IDs
+exif_ids = handle.get_metadata_block_ids('Exif')
+for id in exif_ids:
+    metadata_type = handle.get_metadata_block_type(id)
+    metadata_bytes = handle.get_metadata_block(id)
+    print(f'Metadata type: {metadata_type}, size: {len(metadata_bytes)}')
+```
+
+## API Reference
+
+### Classes
+
+- `HeifContext`: Main context for reading/writing HEIF files
+- `HeifImageHandle`: Handle to a decoded image with metadata
+- `HeifImage`: Raw image data with buffer protocol support
+- `HeifEncoder`: Encoder for creating HEIF files
+- `HeifPlane`: Image plane with NumPy buffer protocol
+
+### Enums
+
+- `HeifColorspace`: RGB, YCbCr, Monochrome
+- `HeifChroma`: C420, C422, C444, InterleavedRGB, InterleavedRGBA
+- `HeifChannel`: Y, Cb, Cr, R, G, B, Alpha, Interleaved
+- `HeifCompressionFormat`: HEVC, AV1, JPEG, JPEG2000
+
+### Exceptions
+
+- `HeifError`: Base exception for all libheif errors
+
+## Building from Source
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/your-username/pylibheif.git
+cd pylibheif
+
+# Build
+uv pip install -e .
+```
+
+## License
+
+This project is licensed under the LGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [libheif](https://github.com/strukturag/libheif) - HEIF/AVIF codec library
+- [pybind11](https://github.com/pybind/pybind11) - C++/Python bindings

pylibheif-1.21.2/README.md

@@ -0,0 +1,212 @@
+# pylibheif
+
+Python bindings for [libheif](https://github.com/strukturag/libheif) using pybind11.
+
+## Features
+
+- **HEIC/HEIF Support**: Read and write HEIC images (HEVC/H.265 encoded)
+- **AVIF Support**: Read and write AVIF images (AV1 encoded)
+- **JPEG2000 Support**: Read and write JPEG2000 images in HEIF container
+- **NumPy Integration**: Zero-copy access to image data via Python Buffer Protocol
+- **Metadata Support**: Read EXIF and XMP metadata from images
+- **RAII Resource Management**: Automatic resource cleanup with context managers
+
+## Supported Formats
+
+| Format | Decoding | Encoding | Codec |
+|--------|----------|----------|-------|
+| HEIC (HEVC/H.265) | ✅ | ✅ | libde265 / x265 |
+| AVIF (AV1) | ✅ | ✅ | DAV1D + AOM |
+| JPEG2000 | ✅ | ✅ | OpenJPEG |
+
+## Requirements
+
+- Python >= 3.12
+- NumPy >= 1.26.0
+- CMake >= 3.15
+- C++17 compatible compiler
+
+### System Dependencies
+
+```bash
+# macOS
+brew install openjpeg
+
+# Ubuntu/Debian
+sudo apt install libopenjp2-7-dev
+```
+
+## Installation
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/your-username/pylibheif.git
+cd pylibheif
+
+# Install with uv (recommended)
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+## Usage
+
+### Reading HEIC/AVIF Images
+
+**Using context manager (recommended):**
+
+```python
+import pylibheif
+import numpy as np
+
+# Open HEIC file with context manager
+with pylibheif.HeifContext() as ctx:
+    ctx.read_from_file('image.heic')
+    
+    # Get primary image handle
+    handle = ctx.get_primary_image_handle()
+    print(f'Image size: {handle.width}x{handle.height}')
+    print(f'Has alpha: {handle.has_alpha}')
+    
+    # Decode to RGB
+    img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                        pylibheif.HeifChroma.InterleavedRGB)
+    
+    # Get as NumPy array (zero-copy)
+    plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+    arr = np.asarray(plane)  # shape: (height, width, 3)
+```
+
+**Explicit creation (for more control):**
+
+```python
+import pylibheif
+import numpy as np
+
+# Create context explicitly
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('image.heic')
+
+handle = ctx.get_primary_image_handle()
+img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                    pylibheif.HeifChroma.InterleavedRGB)
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+arr = np.asarray(plane)
+
+# Resources are automatically freed when objects go out of scope
+```
+
+### Writing HEIC/AVIF Images
+
+```python
+import pylibheif
+import numpy as np
+
+# Create image from NumPy array
+width, height = 1920, 1080
+img = pylibheif.HeifImage(width, height, 
+                          pylibheif.HeifColorspace.RGB,
+                          pylibheif.HeifChroma.InterleavedRGB)
+img.add_plane(pylibheif.HeifChannel.Interleaved, width, height, 8)
+
+# Fill with data
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, True)
+arr = np.asarray(plane)
+arr[:] = your_image_data  # your RGB data
+
+# Encode and save
+ctx = pylibheif.HeifContext()
+
+# For HEIC (HEVC)
+encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.HEVC)
+# For AVIF (AV1)
+# encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.AV1)
+# For JPEG2000
+# encoder = pylibheif.HeifEncoder(pylibheif.HeifCompressionFormat.JPEG2000)
+
+encoder.set_lossy_quality(85)
+encoder.encode_image(ctx, img)
+ctx.write_to_file('output.heic')
+```
+
+### Converting HEIC to JPEG
+
+```python
+import pylibheif
+import numpy as np
+from PIL import Image
+
+# Decode HEIC
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('input.heic')
+handle = ctx.get_primary_image_handle()
+img = handle.decode(pylibheif.HeifColorspace.RGB, 
+                    pylibheif.HeifChroma.InterleavedRGB)
+
+# Get NumPy array
+plane = img.get_plane(pylibheif.HeifChannel.Interleaved, False)
+arr = np.asarray(plane)
+
+# Save as JPEG using PIL
+pil_img = Image.fromarray(arr)
+pil_img.save('output.jpg', 'JPEG', quality=85)
+```
+
+### Reading Metadata
+
+```python
+import pylibheif
+
+ctx = pylibheif.HeifContext()
+ctx.read_from_file('image.heic')
+handle = ctx.get_primary_image_handle()
+
+# Get metadata block IDs
+exif_ids = handle.get_metadata_block_ids('Exif')
+for id in exif_ids:
+    metadata_type = handle.get_metadata_block_type(id)
+    metadata_bytes = handle.get_metadata_block(id)
+    print(f'Metadata type: {metadata_type}, size: {len(metadata_bytes)}')
+```
+
+## API Reference
+
+### Classes
+
+- `HeifContext`: Main context for reading/writing HEIF files
+- `HeifImageHandle`: Handle to a decoded image with metadata
+- `HeifImage`: Raw image data with buffer protocol support
+- `HeifEncoder`: Encoder for creating HEIF files
+- `HeifPlane`: Image plane with NumPy buffer protocol
+
+### Enums
+
+- `HeifColorspace`: RGB, YCbCr, Monochrome
+- `HeifChroma`: C420, C422, C444, InterleavedRGB, InterleavedRGBA
+- `HeifChannel`: Y, Cb, Cr, R, G, B, Alpha, Interleaved
+- `HeifCompressionFormat`: HEVC, AV1, JPEG, JPEG2000
+
+### Exceptions
+
+- `HeifError`: Base exception for all libheif errors
+
+## Building from Source
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/your-username/pylibheif.git
+cd pylibheif
+
+# Build
+uv pip install -e .
+```
+
+## License
+
+This project is licensed under the LGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [libheif](https://github.com/strukturag/libheif) - HEIF/AVIF codec library
+- [pybind11](https://github.com/pybind/pybind11) - C++/Python bindings

pylibheif-1.21.2/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["scikit-build-core>=0.10.0", "pybind11>=2.13.0"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "pylibheif"
+version = "1.21.2"
+description = "Python bindings for libheif - HEIC/AVIF/JPEG2000 image codec"
+readme = "README.md"
+license = {text = "LGPL-3.0-or-later"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Curry Tang", email = "twn39@163.com"}
+]
+keywords = ["heif", "heic", "avif", "jpeg2000", "image", "codec", "libheif"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: C++",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+]
+dependencies = [
+    "numpy>=1.26.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/twn39/pylibheif"
+Repository = "https://github.com/twn39/pylibheif"
+Documentation = "https://github.com/twn39/pylibheif#readme"
+Issues = "https://github.com/twn39/pylibheif/issues"
+
+
+[tool.scikit-build]
+cmake.version = ">=3.15"
+ninja.version = ">=1.10"
+wheel.expand-macos-universal-tags = true
+
+[tool.scikit-build.cmake.define]
+WITH_EXAMPLES = "OFF"
+WITH_RAV1E = "OFF"
+WITH_DAV1D = "ON"
+WITH_AOM = "ON"
+WITH_X265 = "ON"
+WITH_LIBDE265 = "ON"
+WITH_OpenJPEG_ENCODER = "ON"
+WITH_OpenJPEG_DECODER = "ON"