# bigcat88/pillow_heif architecture

> Architecture diagram of the GitHub repository bigcat88/pillow_heif, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bigcat88/pillow_heif
- Repository: https://github.com/bigcat88/pillow_heif

## Overview

##### Project Type and Purpose
- This is a Python plugin and C extension project that bridges Pillow (a popular image library) with libheif for HEIF encoding/decoding.
- The primary goal is to integrate HEIF support (both decoding and encoding) into Pillow, making it accessible with one line of registration code.
- It additionally contains a streamlined “pi-heif” version (a light version without encoding) for specialized use cases.

##### Analyzing the File Structure (Key Findings)
- Top-level directories include source code (pillow_heif, libheif, pi-heif), tests, documentation (docs), examples, and CI/CD support (e.g., .github, docker, benchmarks).
- The “pillow_heif” directory contains the core Python modules responsible for managing the plugin interface (e.g., register_heif_opener), handling image formats, metadata, and wrapping the underlying C extension.
- The “libheif” and “pi-heif/libheif” directories include the native C library (and wrapper code for multiple platforms) that is central to HEIF image processing.
- The presence of a C extension (_pillow_heif.c) and associated build configurations (setup.py, setup.cfg, pyproject.toml) indicate that part of the processing is done at native speed.
- Directories like “docker”, “ci”, and “.github” show dedicated infrastructure for cross-platform build and continuous integration testing.

##### Incorporating Technologies and Frameworks
- Python (with Pillow, numpy, and OpenCV usage in examples).
- The C extension module written for performance-critical sections.
- libheif as the native underlying library.
- Docker, GitHub Actions, and associated CI configuration for testing and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Processing Layers
    subgraph "Image Processing Flow"
        UserApp["User Application (Pillow Usage)"]:::python
        Plugin["Pillow Plugin Integration (pillow_heif)"]:::python
        CoreProc["Python Core Processing (e.g., HeifImagePlugin.py, heif.py)"]:::python
        CExt["C Extension Layer (_pillow_heif)"]:::extension
        
        UserApp -->|"calls"| Plugin
        Plugin -->|"invokes"| CoreProc
        CoreProc -->|"delegates to"| CExt
        
        %% Native libheif Subgraph
        subgraph "Native libheif"
            LibMain["libheif"]:::native
            LibPi["pi-heif/libheif"]:::native
        end
        CExt -->|"interfaces with"| LibMain
        CExt -->|"interfaces with"| LibPi
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        Tests["Tests (tests)"]:::infra
        CICD["CI/CD (.github)"]:::infra
        Docker["Docker Build Environment (docker)"]:::infra
        Docs["Documentation (docs)"]:::infra
    end

    %% Auxiliary connections (dotted arrows for build/test support)
    Plugin ---|"triggers"| Tests
    Plugin ---|"triggers"| CICD
    Plugin ---|"triggers"| Docker
    Plugin ---|"provides info"| Docs

    %% Click Events
    click UserApp "https://github.com/bigcat88/pillow_heif/tree/master/examples/"
    click Plugin "https://github.com/bigcat88/pillow_heif/tree/master/pillow_heif/"
    click CoreProc "https://github.com/bigcat88/pillow_heif/blob/master/pillow_heif/heif.py"
    click CExt "https://github.com/bigcat88/pillow_heif/blob/master/pillow_heif/_pillow_heif.c"
    click LibMain "https://github.com/bigcat88/pillow_heif/tree/master/libheif/"
    click LibPi "https://github.com/bigcat88/pillow_heif/tree/master/pi-heif/libheif/"
    click Tests "https://github.com/bigcat88/pillow_heif/tree/master/tests/"
    click CICD "https://github.com/bigcat88/pillow_heif/tree/master/.github/"
    click Docker "https://github.com/bigcat88/pillow_heif/tree/master/docker/"
    click Docs "https://github.com/bigcat88/pillow_heif/tree/master/docs/"

    %% Styles
    classDef python fill:#cfe2f3,stroke:#0d6efd,stroke-width:2px;
    classDef extension fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef native fill:#d1e7dd,stroke:#198754,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#e0a800,stroke-width:2px;
```
