# Inkscape: Project-Specific Analysis & SOP

## Architecture Summary

Inkscape is a vector graphics editor whose native format is **SVG (XML)**. This is
a major advantage -- we can directly parse, generate, and manipulate SVG files
using Python's `xml.etree.ElementTree` module. No binary format parsing needed.

```
┌─────────────────────────────────────────────────┐
│                 Inkscape GUI                     │
│  ┌──────────┐ ┌──────────┐ ┌───────────────┐   │
│  │  Canvas   │ │  Layers  │ │  Object Props │   │
│  │  (GTK)    │ │  (GTK)   │ │  (GTK)        │   │
│  └────┬──────┘ └────┬─────┘ └──────┬────────┘   │
│       │             │              │             │
│  ┌────┴─────────────┴──────────────┴──────────┐  │
│  │        SVG Document Object Model           │  │
│  │  XML tree of <svg>, <rect>, <circle>,      │  │
│  │  <path>, <text>, <g> elements              │  │
│  └─────────────────┬──────────────────────────┘  │
│                    │                             │
│  ┌─────────────────┴──────────────────────────┐  │
│  │       lib2geom (geometry engine)           │  │
│  │  Path operations, boolean ops, transforms  │  │
│  └─────────────────┬──────────────────────────┘  │
└────────────────────┼────────────────────────────┘
                     │
          ┌──────────┴────────────┐
          │  Cairo/librsvg        │
          │  (SVG rendering)      │
          │  + File format I/O    │
          └───────────────────────┘
```

## CLI Strategy: Direct SVG Manipulation

Unlike GIMP (which has a complex binary .xcf format) or Blender (binary .blend),
Inkscape's SVG format is plain XML. Our strategy:

1. **xml.etree.ElementTree** -- Python's standard XML library for SVG parsing
   and generation. This is our primary engine.
2. **Pillow** -- For PNG rasterization of basic shapes (rect, circle, text, etc.)
3. **Inkscape CLI** -- If available, use `inkscape --actions` for advanced
   operations (PDF export, path boolean ops, text-to-path conversion).

### Why SVG is Ideal for CLI Manipulation

- **Human-readable** -- SVG is XML text, not binary
- **1:1 mapping** -- SVG elements map directly to Inkscape's GUI objects
- **CSS styling** -- Fill, stroke, opacity are CSS properties we can parse/set
- **Standard transforms** -- translate(), rotate(), scale() are SVG attributes
- **DOM structure** -- Layers are <g> elements, gradients in <defs>, etc.
- **Browser viewable** -- Generated SVG can be opened in any browser

## The Project Format (.inkscape-cli.json)

We maintain a JSON project file alongside SVG for state tracking:

```json
{
  "version": "1.0",
  "name": "my_drawing",
  "document": {
    "width": 1920,
    "height": 1080,
    "units": "px",
    "viewBox": "0 0 1920 1080",
    "background": "#ffffff"
  },
  "objects": [
    {
      "id": "rect1",
      "name": "MyRect",
      "type": "rect",
      "x": 100, "y": 100,
      "width": 200, "height": 150,
      "style": "fill:#ff0000;stroke:#000;stroke-width:2",
      "transform": "translate(10, 20) rotate(45)",
      "layer": "layer1"
    }
  ],
  "layers": [
    {
      "id": "layer1",
      "name": "Layer 1",
      "visible": true,
      "locked": false,
      "opacity": 1.0,
      "objects": ["rect1"]
    }
  ],
  "gradients": [
    {
      "id": "linearGradient1",
      "type": "linear",
      "x1": 0, "y1": 0, "x2": 1, "y2": 0,
      "stops": [
        {"offset": 0, "color": "#ff0000", "opacity": 1},
        {"offset": 1, "color": "#0000ff", "opacity": 1}
      ]
    }
  ],
  "metadata": {
    "created": "2024-01-01T00:00:00",
    "modified": "2024-01-01T00:00:00",
    "software": "inkscape-cli 1.0"
  }
}
```

## SVG Element Mapping

| SVG Element | Inkscape Tool | CLI Command |
|-------------|--------------|-------------|
| `<rect>` | Rectangle | `shape add-rect` |
| `<circle>` | Circle | `shape add-circle` |
| `<ellipse>` | Ellipse | `shape add-ellipse` |
| `<line>` | Line | `shape add-line` |
| `<polygon>` | Polygon | `shape add-polygon` |
| `<path>` | Bezier/Pen | `shape add-path` |
| `<text>` | Text | `text add` |
| `<g>` | Layer/Group | `layer add` |
| `<linearGradient>` | Gradient | `gradient add-linear` |
| `<radialGradient>` | Gradient | `gradient add-radial` |
| CSS `style` | Fill/Stroke | `style set-fill`, `style set-stroke` |
| `transform` | Transform | `transform translate/rotate/scale` |

## Command Map: GUI Action -> CLI Command

| GUI Action | CLI Command |
|-----------|-------------|
| File -> New | `document new --width W --height H` |
| File -> Open | `document open <path>` |
| File -> Save | `document save [path]` |
| File -> Export PNG | `export png <output>` |
| File -> Export SVG | `export svg <output>` |
| Draw Rectangle | `shape add-rect --x X --y Y --width W --height H` |
| Draw Circle | `shape add-circle --cx X --cy Y --r R` |
| Draw Star | `shape add-star --points 5 --outer-r 50 --inner-r 25` |
| Edit -> Transform | `transform translate/rotate/scale INDEX` |
| Object -> Fill/Stroke | `style set-fill INDEX COLOR` |
| Layer -> Add | `layer add --name "Name"` |
| Layer -> Reorder | `layer reorder FROM TO` |
| Path -> Union | `path union A B` |
| Path -> Difference | `path difference A B` |
| Path -> Object to Path | `path convert INDEX` |
| Text Tool | `text add --text "Content" --x X --y Y` |
| Edit -> Undo | `session undo` |
| Edit -> Redo | `session redo` |

## Rendering Pipeline

### SVG Generation
1. Create root `<svg>` element with dimensions, viewBox, namespaces
2. Add `<defs>` with gradient definitions
3. Add `<g>` elements for each layer (with inkscape:groupmode="layer")
4. Add shape/text/path elements inside their layer groups
5. Apply style attributes, transforms, gradient references

### PNG Rendering (Pillow)
1. Create blank image at document dimensions
2. For each visible layer (bottom to top):
   - For each object in layer:
     - Parse style (fill, stroke, stroke-width)
     - Draw shape using Pillow's ImageDraw
3. Save as PNG

### Rendering Gap Assessment: **Low**
- SVG is the native format, so SVG export is exact
- PNG rendering via Pillow handles basic shapes (rect, circle, ellipse, line, text)
- Complex SVG features (filters, clip paths, masks) need Inkscape for rendering
- Path boolean operations are stored as metadata; Inkscape needed for actual computation

## Export Formats

| Format | Method | Fidelity |
|--------|--------|----------|
| SVG | Direct XML generation | Exact |
| PNG | Pillow (basic) / Inkscape (full) | Basic shapes / Full |
| PDF | Inkscape CLI | Full |
| EPS | Inkscape CLI | Full |

## Test Coverage Plan

1. **Unit tests** (`test_core.py`): Synthetic data, no real files needed
   - Document create/open/save/info
   - Shape add/remove/duplicate/list for all types
   - Text add/set properties
   - Style set/get for all properties
   - Transform translate/rotate/scale/skew
   - Layer add/remove/reorder/move objects
   - Path boolean operations
   - Gradient create/apply
   - Session undo/redo
   - SVG utility functions

2. **E2E tests** (`test_full_e2e.py`): Real SVG generation
   - SVG XML validity (well-formed, correct namespaces)
   - Document roundtrip (JSON save/load)
   - SVG export and parse-back
   - PNG export (pixel verification)
   - Multi-step workflow scenarios
   - CLI subprocess invocation