# hzeller/timg architecture

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

- Interactive diagram: https://gitdiagram.com/hzeller/timg
- Repository: https://github.com/hzeller/timg

## Overview

##### Project Type and Core Components
This is a terminal-based image and video processing application with multiple rendering backends. The system design should focus on the following main components:

a. Input Sources
- Image Sources (various formats)
- Video Sources
- Device Sources (e.g., webcam)

b. Processing Pipeline
- Image/Video Decoders
- Scaling/Processing
- Threading System

c. Output Renderers
- Terminal-based renderers (Half/Quarter blocks)
- High-resolution renderers (Sixel, Kitty, iTerm2)

**[Input Layer]**

- Image Sources (GraphicsMagick, JPEG, QOI, STB, etc.)
- Video Sources (FFmpeg)
- Device Sources (V4L2, etc.)

**[Processing Layer]**

- Image Processing
- Scaling
- Format Conversion

- Thread Pool
- Parallel Processing

- Buffer Management
- Write Sequencer

**[Output Layer]**

- High Resolution Renderers
- Sixel Canvas
- Kitty Canvas
- iTerm2 Canvas

- Terminal Block Renderers
- Unicode Block Canvas
- Terminal Canvas

##### Key Relationships to Highlight

a. Input Processing:
- How different file formats are handled by respective decoders
- Parallel processing capabilities via thread pool
- Format-specific optimizations (e.g., TurboJPEG)

b. Core Processing:
- Buffered write sequencer's role
- How the image scaler interfaces with different input sources
- Demonstrate thread pool integration

c. Output Generation:
- Terminal capability detection flow
- Fallback mechanisms between renderers
- How different canvas types are selected and utilized

##### Additional Elements

- Notes about configuration options affecting the pipeline
- Version/build-time feature toggles
- Error handling and fallback paths

##### Implementation Details to Consider

- How the CMake build system affects available features
- Optional components (e.g., OpenSlide support)
- Demonstrate how environment variables influence behavior
- Integration points with external libraries

##### Optimization Flows

- Compression options for high-res modes
- Frame-skipping mechanisms for video
- Demonstrate parallel processing paths

- Clear hierarchical representation
- Different connection types
- Proper spacing for readability
- Export to common formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Define styles
    classDef input fill:#b3d9ff,stroke:#333,stroke-width:2px
    classDef processing fill:#b3ffb3,stroke:#333,stroke-width:2px
    classDef output fill:#ffd9b3,stroke:#333,stroke-width:2px
    classDef utility fill:#e6e6e6,stroke:#333,stroke-width:2px

    %% Input Layer
    subgraph InputLayer["Input Layer"]
        ImageSources["Image Sources"]
        VideoSources["Video Sources"]
        DeviceSources["Device Sources"]

        subgraph ImageFormats["Image Format Handlers"]
            GM["GraphicsMagick"]
            JPEG["JPEG/TurboJPEG"]
            QOI["QOI"]
            STB["STB"]
            SVG["SVG"]
            PDF["PDF"]
            OpenSlide["OpenSlide"]
        end

        subgraph VideoFormats["Video Format Handlers"]
            FFmpeg["FFmpeg Handler"]
            V4L2["V4L2 Device"]
        end
    end

    %% Processing Layer
    subgraph ProcessingLayer["Processing Layer"]
        ImageProc["Image Processing"]
        ThreadPool["Thread Pool"]
        BufferMgmt["Buffer Management"]

        subgraph ImageProcessing["Image Processing Components"]
            Scaling["Scaling"]
            ColorProc["Color Processing"]
            FormatConv["Format Conversion"]
        end

        subgraph BufferComponents["Buffer Components"]
            WriteSeq["Write Sequencer"]
            FrameBuffer["Frame Buffer"]
        end
    end

    %% Output Layer
    subgraph OutputLayer["Output Layer"]
        HighRes["High Resolution Renderers"]
        TermBlock["Terminal Block Renderers"]

        subgraph HRRenderers["High-Res Canvas Types"]
            Sixel["Sixel Canvas"]
            Kitty["Kitty Canvas"]
            iTerm2["iTerm2 Canvas"]
        end

        subgraph BlockRenderers["Block Renderers"]
            Unicode["Unicode Block Canvas"]
            Terminal["Terminal Canvas"]
        end
    end

    %% Core Components
    MainRenderer["Main Renderer"]
    TermQuery["Terminal Query"]
    DisplayOpts["Display Options"]

    %% Relationships
    ImageSources --> ImageFormats
    VideoSources --> VideoFormats
    DeviceSources --> V4L2

    ImageFormats --> ImageProc
    VideoFormats --> ImageProc
    V4L2 --> ImageProc

    ImageProc --> ThreadPool
    ThreadPool --> BufferMgmt
    BufferMgmt --> MainRenderer

    MainRenderer --> HighRes
    MainRenderer --> TermBlock
    TermQuery --> MainRenderer
    DisplayOpts --> MainRenderer

    %% Click events for component mapping
    click GM "https://github.com/hzeller/timg/blob/main/src/graphics-magick-source.h"
    click JPEG "https://github.com/hzeller/timg/blob/main/src/jpeg-source.h"
    click QOI "https://github.com/hzeller/timg/blob/main/src/qoi-image-source.h"
    click STB "https://github.com/hzeller/timg/blob/main/src/stb-image-source.h"
    click SVG "https://github.com/hzeller/timg/blob/main/src/svg-image-source.h"
    click PDF "https://github.com/hzeller/timg/blob/main/src/pdf-image-source.h"
    click OpenSlide "https://github.com/hzeller/timg/blob/main/src/openslide-source.h"
    click FFmpeg "https://github.com/hzeller/timg/blob/main/src/video-source.h"
    click Scaling "https://github.com/hzeller/timg/blob/main/src/image-scaler.h"
    click ThreadPool "https://github.com/hzeller/timg/blob/main/src/thread-pool.h"
    click WriteSeq "https://github.com/hzeller/timg/blob/main/src/buffered-write-sequencer.h"
    click FrameBuffer "https://github.com/hzeller/timg/blob/main/src/framebuffer.h"
    click Sixel "https://github.com/hzeller/timg/blob/main/src/sixel-canvas.h"
    click Kitty "https://github.com/hzeller/timg/blob/main/src/kitty-canvas.h"
    click iTerm2 "https://github.com/hzeller/timg/blob/main/src/iterm2-canvas.h"
    click Unicode "https://github.com/hzeller/timg/blob/main/src/unicode-block-canvas.h"
    click Terminal "https://github.com/hzeller/timg/blob/main/src/terminal-canvas.h"
    click MainRenderer "https://github.com/hzeller/timg/blob/main/src/renderer.h"
    click TermQuery "https://github.com/hzeller/timg/blob/main/src/term-query.h"
    click DisplayOpts "https://github.com/hzeller/timg/blob/main/src/display-options.h"

    %% Style applications
    class ImageSources,VideoSources,DeviceSources,ImageFormats,VideoFormats input
    class ImageProc,ThreadPool,BufferMgmt,ImageProcessing,BufferComponents processing
    class HighRes,TermBlock,HRRenderers,BlockRenderers output
    class MainRenderer,TermQuery,DisplayOpts utility
```
