# lclevy/libcraw2 architecture

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

- Interactive diagram: https://gitdiagram.com/lclevy/libcraw2
- Repository: https://github.com/lclevy/libcraw2

## Overview

##### Project Type & Purpose
- This is a mixed-language C/Python framework (“CRaw2”) for parsing, manipulating and rendering Canon CR2 (Raw v2) files.
- It comprises three primary deliverables:
– libcraw2: a native C library implementing CR2 file parsing, TIFF/JPEG handling, pixel-level operations.
– craw2tool: a CLI binary (in C) exposing libcraw2’s API for shell‐based workflows.
– PyCraw2: a Python extension module (C under the hood, built via setup.py) plus pure-Python utilities (in the python/ folder) that wrap libcraw2 and offer NumPy-driven image processing.

##### File Structure Analysis
Top‐level:
- Makefile, setup/config scripts (src/setup.py), VS2015 solution for Windows build
- Shell scripts (cr2_database.sh, dng_info.sh, unknow_tags.sh) to generate camera-specific data files
- python/ – pure-Python demos & tools (cr2_analysis.py, thumbnails.py, PyCanonRaw2.py, etc.)
- src/ – C source & headers for libcraw2, craw2tool, yuv, lljpeg, tiff modules; setup.py glue for PyCraw2
- pics/ – sample CR2 inputs

##### Key README Insights
- Layered design: core C library → C CLI → Python extension → Python tooling
- Supports TIFF tag introspection, lossless JPEG operations, RGGB and YCbCr data export/import, 16-bit TIFF output
- Camera-specific data is externalized (cr2_database.txt, dng_info.txt) – keeps core code camera-agnostic

##### Diagramming the Architecture
- libcraw2 Core (C library)
- craw2tool CLI (C binary)
- PyCraw2 Extension (built from C code, loaded into Python)
- Python Utilities (pure-Python modules under python/)
- Shell Scripts (camera data generation)
- Data Repositories (cr2_database.txt, dng_info.txt, sample .CR2)
- Build System (Makefile, setup.py, VS2015 proj)

- CLI & Python modules → link/load → libcraw2
- Shell scripts → generate → camera data files
- Input: .CR2 files (pics/) → processed by libcraw2 via either CLI or PyCraw2 → Outputs: TIFF/CSV/console logs
- PyCraw2 → interacts with NumPy for array operations → delivers rendered RGB arrays

c. Architectural Patterns & Principles:
- Layering: Core (performance‐critical C) vs. Bindings (extension) vs. High-level scripting
- Separation of concerns:
– Parsing & pixel ops in libcraw2
– User interaction via CLI or Python
– Camera metadata kept external for flexibility
- Modularity: distinct modules for JPEG, TIFF, YUV, RGB pipelines

d. Key Technologies & Frameworks:
- C99, Make & autotools (Makefile), VS2015 projects
- Python 3.6, setup.py for extension build
- NumPy (for Python rendering)
- Standard TIFF/JPEG libs & custom “lljpeg” for lossless operations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% C Core Layer
    subgraph "libcraw2 Core (C Library)"
        direction TB
        BITS["bits.c / bits.h"]:::clib
        CRAW2["craw2.c / craw2.h"]:::clib
        LLJPEG["lljpeg.c / lljpeg.h"]:::clib
        RGB["rgb.c / rgb.h"]:::clib
        TIFF["tiff.c / tiff.h"]:::clib
        UTILS["utils.c / utils.h"]:::clib
        YUV["yuv.c / yuv.h"]:::clib
        YUVIM["yuv_import.c"]:::clib
    end

    %% CLI Layer
    CLI["craw2tool CLI (src/craw2tool.c)"]:::clib

    %% Python Extension Layer
    subgraph "PyCraw2 Extension"
        direction TB
        PYEXT["pyCraw2.c"]:::clib
        SETUP["setup.py"]:::build
    end

    %% Python Utilities
    subgraph "Python Utilities (python/)"
        direction TB
        PCANON["PyCanonRaw2.py"]:::python
        PTIFF["PyTiffParser.py"]:::python
        CR2AN["cr2_analysis.py"]:::python
        CR2DUST["cr2_analysis_dust.py"]:::python
        THUMB["thumbnails.py"]:::python
        UNKTAG["unknown_tags.py"]:::python
        DEMO["pycraw2_demo.py"]:::python
    end

    %% Shell Scripts
    subgraph "Shell Scripts"
        direction TB
        SCR1["cr2_database.sh"]:::build
        SCR2["dng_info.sh"]:::build
        SCR3["unknow_tags.sh"]:::build
    end

    %% Data Repositories
    subgraph "Data Repositories"
        direction TB
        DNGTXT["dng_info.txt"]:::data
        CR2DB["docs/cr2_database.txt"]:::data
        DNGDOC["docs/dng_info.txt"]:::data
        CAMTXT["docs/cameras.txt"]:::data
        PICS["pics/"]:::data
    end

    %% Build System
    subgraph "Build System"
        direction TB
        MKROOT["Makefile"]:::build
        MKSRC["src/Makefile"]:::build
        SLN["vs2015/libcraw2/libcraw2.sln"]:::build
        PROJ1["vs2015/libcraw2/*.vcxproj"]:::build
        PROJ2["vs2015/craw2tool/craw2tool.vcxproj"]:::build
        PROJ3["vs2015/PyCraw2/PyCraw2.vcxproj"]:::build
    end

    %% NumPy
    NUMPY["NumPy"]:::python

    %% Connections
    CLI -->|links to| BITS
    CLI -->|links to| CRAW2
    CLI -->|links to| LLJPEG
    CLI -->|links to| RGB
    CLI -->|links to| TIFF
    CLI -->|links to| UTILS
    CLI -->|links to| YUV
    CLI -->|links to| YUVIM

    PYEXT -->|loads| BITS
    PYEXT -->|loads| CRAW2
    PYEXT -->|loads| LLJPEG
    PYEXT -->|loads| RGB
    PYEXT -->|loads| TIFF
    PYEXT -->|loads| UTILS
    PYEXT -->|loads| YUV
    PYEXT -->|loads| YUVIM

    PCANON -->|imports| PYEXT
    PTIFF -->|imports| PYEXT
    CR2AN -->|imports| PYEXT
    CR2DUST -->|imports| PYEXT
    THUMB -->|imports| PYEXT
    UNKTAG -->|imports| PYEXT
    DEMO -->|imports| PYEXT

    PCANON -->|uses| NUMPY
    PTIFF -->|uses| NUMPY
    THUMB -->|uses| NUMPY
    DEMO -->|uses| NUMPY

    SCR1 -->|generates| CR2DB
    SCR2 -->|generates| DNGDOC
    SCR3 -->|generates| CAMTXT

    PICS -->|input| CLI
    PICS -->|input| PYEXT

    CLI -->|outputs| TIFF
    CLI -->|logs to console| UTILS

    PYEXT -->|returns arrays| NUMPY

    MKROOT -->|builds| CLI
    MKROOT -->|builds| BITS
    MKROOT -->|builds| PYEXT
    MKSRC -->|builds| BITS
    SLN -->|builds| BITS
    PROJ1 -->|builds| BITS
    PROJ2 -->|builds| CLI
    PROJ3 -->|builds| PYEXT

    %% Click Events
    click BITS "https://github.com/lclevy/libcraw2/blob/master/src/bits.c"
    click BITS "https://github.com/lclevy/libcraw2/blob/master/src/bits.h"
    click CRAW2 "https://github.com/lclevy/libcraw2/blob/master/src/craw2.c"
    click CRAW2 "https://github.com/lclevy/libcraw2/blob/master/src/craw2.h"
    click LLJPEG "https://github.com/lclevy/libcraw2/blob/master/src/lljpeg.c"
    click LLJPEG "https://github.com/lclevy/libcraw2/blob/master/src/lljpeg.h"
    click RGB "https://github.com/lclevy/libcraw2/blob/master/src/rgb.c"
    click RGB "https://github.com/lclevy/libcraw2/blob/master/src/rgb.h"
    click TIFF "https://github.com/lclevy/libcraw2/blob/master/src/tiff.c"
    click TIFF "https://github.com/lclevy/libcraw2/blob/master/src/tiff.h"
    click UTILS "https://github.com/lclevy/libcraw2/blob/master/src/utils.c"
    click UTILS "https://github.com/lclevy/libcraw2/blob/master/src/utils.h"
    click YUV "https://github.com/lclevy/libcraw2/blob/master/src/yuv.c"
    click YUV "https://github.com/lclevy/libcraw2/blob/master/src/yuv.h"
    click YUVIM "https://github.com/lclevy/libcraw2/blob/master/src/yuv_import.c"
    click CLI "https://github.com/lclevy/libcraw2/blob/master/src/craw2tool.c"
    click PYEXT "https://github.com/lclevy/libcraw2/blob/master/src/pyCraw2.c"
    click SETUP "https://github.com/lclevy/libcraw2/blob/master/src/setup.py"
    click PCANON "https://github.com/lclevy/libcraw2/blob/master/python/PyCanonRaw2.py"
    click PTIFF "https://github.com/lclevy/libcraw2/blob/master/python/PyTiffParser.py"
    click CR2AN "https://github.com/lclevy/libcraw2/blob/master/python/cr2_analysis.py"
    click CR2DUST "https://github.com/lclevy/libcraw2/blob/master/python/cr2_analysis_dust.py"
    click THUMB "https://github.com/lclevy/libcraw2/blob/master/python/thumbnails.py"
    click UNKTAG "https://github.com/lclevy/libcraw2/blob/master/python/unknown_tags.py"
    click DEMO "https://github.com/lclevy/libcraw2/blob/master/pycraw2_demo.py"
    click SCR1 "https://github.com/lclevy/libcraw2/blob/master/cr2_database.sh"
    click SCR2 "https://github.com/lclevy/libcraw2/blob/master/dng_info.sh"
    click SCR3 "https://github.com/lclevy/libcraw2/blob/master/unknow_tags.sh"
    click DNGTXT "https://github.com/lclevy/libcraw2/blob/master/dng_info.txt"
    click CR2DB "https://github.com/lclevy/libcraw2/blob/master/docs/cr2_database.txt"
    click DNGDOC "https://github.com/lclevy/libcraw2/blob/master/docs/dng_info.txt"
    click CAMTXT "https://github.com/lclevy/libcraw2/blob/master/docs/cameras.txt"
    click PICS "https://github.com/lclevy/libcraw2/tree/master/pics/"
    click MKROOT "https://github.com/lclevy/libcraw2/tree/master/Makefile"
    click MKSRC "https://github.com/lclevy/libcraw2/tree/master/src/Makefile"
    click SLN "https://github.com/lclevy/libcraw2/blob/master/vs2015/libcraw2/libcraw2.sln"
    click PROJ1 "https://github.com/lclevy/libcraw2/blob/master/vs2015/libcraw2/libcraw2.vcxproj"
    click PROJ2 "https://github.com/lclevy/libcraw2/blob/master/vs2015/craw2tool/craw2tool.vcxproj"
    click PROJ3 "https://github.com/lclevy/libcraw2/blob/master/vs2015/PyCraw2/PyCraw2.vcxproj"

    %% Styles
    classDef clib fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef python fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef data fill:#ffcc80,stroke:#fb8c00,color:#e65100
    classDef build fill:#e0e0e0,stroke:#757575,color:#212121
```
