GIMP: Project-Specific Analysis & SOP

Architecture Summary

GIMP (GNU Image Manipulation Program) is a GTK-based raster image editor built on the GEGL (Generic Graphics Library) processing engine and Babl color management.

┌──────────────────────────────────────────────┐
│                  GIMP GUI                    │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
│  │  Canvas   │ │  Layers  │ │   Filters   │  │
│  │  (GTK)    │ │  (GTK)   │ │   (GTK)     │  │
│  └────┬──────┘ └────┬─────┘ └──────┬──────┘  │
│       │             │              │          │
│  ┌────┴─────────────┴──────────────┴───────┐ │
│  │       PDB (Procedure Database)          │ │
│  │  500+ registered procedures for all     │ │
│  │  image operations, filters, I/O         │ │
│  └─────────────────┬───────────────────────┘ │
│                    │                          │
│  ┌─────────────────┴───────────────────────┐ │
│  │       GEGL Processing Engine            │ │
│  │  DAG-based image processing pipeline    │ │
│  │  70+ built-in operations               │ │
│  └─────────────────┬───────────────────────┘ │
└────────────────────┼─────────────────────────┘
                     │
         ┌───────────┴──────────┐
         │  Babl (color mgmt)   │
         │  + GEGL operations   │
         │  + File format I/O   │
         └──────────────────────┘

CLI Strategy: Pillow + External Tools

Unlike Shotcut (which manipulates XML project files), GIMP's native .xcf format is a complex binary format. Our strategy:

1. Pillow — Python's standard imaging library. Handles image I/O (PNG, JPEG, TIFF, BMP, GIF, WebP, etc.), pixel manipulation, basic filters, color adjustments, drawing, and compositing. This is our primary engine.
2. GEGL CLI — If available, use gegl command for advanced operations.
3. GIMP batch mode — If gimp is installed, use gimp -i -b for XCF operations and advanced filters via Script-Fu/Python-Fu.

Why Not XCF Directly?

XCF is a tile-based binary format with compression, layers, channels, paths, and GEGL filter graphs. Parsing it from scratch is extremely complex (5000+ lines of C in GIMP's xcf-load.c). Instead:

• For new projects, we build layer stacks in memory using Pillow
• For XCF import/export, we delegate to GIMP batch mode if available
• Our "project file" is a JSON manifest tracking layers, operations, and history

The Project Format (.gimp-cli.json)

Since we can't easily manipulate XCF directly, we use a JSON project format:

{
  "version": "1.0",
  "name": "my_project",
  "canvas": {
    "width": 1920,
    "height": 1080,
    "color_mode": "RGB",
    "background": "#ffffff",
    "dpi": 300
  },
  "layers": [
    {
      "id": 0,
      "name": "Background",
      "type": "image",
      "source": "/path/to/image.png",
      "visible": true,
      "opacity": 1.0,
      "blend_mode": "normal",
      "offset_x": 0,
      "offset_y": 0,
      "filters": [
        {"name": "brightness", "params": {"factor": 1.2}},
        {"name": "gaussian_blur", "params": {"radius": 3}}
      ]
    },
    {
      "id": 1,
      "name": "Text Layer",
      "type": "text",
      "text": "Hello World",
      "font": "Arial",
      "font_size": 48,
      "color": "#000000",
      "visible": true,
      "opacity": 0.8,
      "blend_mode": "normal",
      "offset_x": 100,
      "offset_y": 50,
      "filters": []
    }
  ],
  "selection": null,
  "guides": [],
  "metadata": {}
}

Core Operations via Pillow

Image I/O

Filters & Adjustments

Compositing & Drawing

Blend Modes

Pillow doesn't natively support Photoshop/GIMP blend modes. We implement the most common ones using NumPy-style pixel math:

Command Map: GUI Action -> CLI Command

Filter Registry

Image Adjustments

Blur & Sharpen

Stylize

Transform

Export Formats

Rendering Pipeline

For GIMP CLI, "rendering" means flattening the layer stack with all filters applied and exporting to a target format.

Pipeline Steps:

1. Start with canvas (background color or transparent)
2. For each visible layer (bottom to top): a. Load/create the layer content b. Apply all layer filters in order c. Position at layer offset d. Composite onto canvas using blend mode and opacity
3. Export final composited image

Rendering Gap Assessment: Medium

• Most operations (resize, crop, filters, compositing) work via Pillow directly
• Advanced GEGL operations (high-pass filter, wavelet decompose) not available
• No XCF round-trip without GIMP installed
• Blend modes require custom implementation but are mathematically straightforward

Test Coverage Plan

1. Unit tests (test_core.py): Synthetic data, no real images needed

   • Project create/open/save/info
   • Layer add/remove/reorder/properties
   • Filter application and parameter validation
   • Canvas operations (resize, scale, crop, mode conversion)
   • Session undo/redo
   • JSON project serialization/deserialization

2. E2E tests (test_full_e2e.py): Real images

   • Full workflow: create project, add layers, apply filters, export
   • Format conversion (PNG->JPEG, etc.)
   • Blend mode compositing verification
   • Filter effect pixel-level verification
   • Multi-layer compositing
   • Text rendering
   • CLI subprocess invocation