Create 2d Composition

---
name: create-2d-composition
locale: wenyan-ultra
source_locale: en
source_commit: "75ded7a1"
fence_basis_commit: 75ded7a1
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"
description: >
  Compose 2D graphics programmatically using SVG generation, diagram layout
  algorithms, image compositing, and batch processing workflows. Use when
  generating diagrams, flowcharts, or infographics programmatically, creating
  reproducible scientific figures, automating production of badges or visual
  assets, building custom chart types not in standard libraries, or batch
  generating graphics with parameter variations.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: visualization
  complexity: intermediate
  language: Python
  tags: svg, 2d, graphics, composition, diagrams, scripting, batch-processing
---

# 造二維構圖

以 SVG 建、圖排、像合、批作程生二維像。

## 用

- 程生圖、流、信息圖
- 可重科圖或刊像
- 自生徽、標、視資
- 合多像或數視
- 築自定圖型
- 批生含參變之像
- 為網或印建 SVG 模

## 入

| 入 | 型 | 述 | 例 |
|---|---|---|---|
| 排規 | 設 | 寸、邊、格排 | 畫 800x600px、20px 邊 |
| 視素 | 數/資 | 形、字、像、點 | 矩坐、標、標 |
| 風參 | CSS/屬 | 色、體、筆寬、透 | `fill="#3366cc"`、`stroke-width="2"` |
| 數源 | 檔/陣 | 所視或注之值 | CSV 數、JSON 設 |
| 出式 | 串 | SVG、PNG、PDF、合式 | `output.svg`、300 DPI PNG |

## 行

### 一、設 Python 境

裝二維構所需庫：

```bash
# Core libraries
pip install svgwrite pillow cairosvg

# Optional: advanced features
pip install drawsvg reportlab pycairo

# For data-driven graphics
pip install matplotlib numpy pandas
```

**得：** 庫裝成
**敗：** 察 Python 版（3.7+）、用虛境避衝

### 二、建基 SVG 像

以 svgwrite 生 SVG：

```python
import svgwrite
from svgwrite import cm, mm

def create_basic_svg(output_path):
    """Create a simple SVG graphic."""
    # Initialize drawing (use mm for precise dimensions)
    dwg = svgwrite.Drawing(output_path, size=('180mm', '120mm'), profile='full')

    # Add background rectangle
    dwg.add(dwg.rect(
        insert=(0, 0),
        size=('100%', '100%'),
        fill='white'
    ))

    # Add shapes
    dwg.add(dwg.circle(
        center=(90*mm, 60*mm),
        r=30*mm,
        fill='lightblue',
        stroke='navy',
        stroke_width=2
    ))

    dwg.add(dwg.rect(
        insert=(30*mm, 30*mm),
        size=(60*mm, 40*mm),
        fill='lightgreen',
        stroke='darkgreen',
        stroke_width=2,
        rx=5,  # Rounded corners
        ry=5
    ))

    # Add text
    dwg.add(dwg.text(
        'Example Graphic',
        insert=(90*mm, 20*mm),
        text_anchor='middle',
        font_size='18pt',
        font_family='Arial',
        fill='black'
    ))

    dwg.save()
    print(f"Saved: {output_path}")
```

**得：** SVG 檔生含形與字
**敗：** 察 svgwrite 版、驗出目可寫

### 三、以排輯築圖解

建算位之結構圖解：

```python
def create_flowchart(steps, output_path):
    """Generate a flowchart from list of steps."""
    dwg = svgwrite.Drawing(output_path, size=('800px', '600px'))

    # Layout parameters
    box_width = 120
    box_height = 60
    spacing_y = 100
    start_x = 340
    start_y = 50

    for i, step in enumerate(steps):
        y_pos = start_y + i * spacing_y

        # Draw box
        box = dwg.add(dwg.g(id=f'step_{i}'))

        box.add(dwg.rect(
            insert=(start_x, y_pos),
            size=(box_width, box_height),
            fill='lightblue',
            stroke='navy',
            stroke_width=2,
            rx=5,
            ry=5
        ))

        # Add text (wrapped if needed)
        text_lines = wrap_text(step, max_width=16)
        text_y = y_pos + box_height/2 - (len(text_lines)-1) * 7

        for j, line in enumerate(text_lines):
            box.add(dwg.text(
                line,
                insert=(start_x + box_width/2, text_y + j*14),
                text_anchor='middle',
                font_size='12pt',
                font_family='Arial',
                fill='black'
            ))

        # Draw arrow to next step
        if i < len(steps) - 1:
            arrow_start_y = y_pos + box_height
            arrow_end_y = y_pos + spacing_y

            dwg.add(dwg.line(
                start=(start_x + box_width/2, arrow_start_y),
                end=(start_x + box_width/2, arrow_end_y),
                stroke='black',
                stroke_width=2,
                marker_end=dwg.marker(
                    id='arrow',
                    viewBox='0 0 10 10',
                    refX=5,
                    refY=5,
                    markerWidth=6,
                    markerHeight=6,
                    orient='auto'
                )
            ))

    dwg.save()

def wrap_text(text, max_width=20):
    """Simple text wrapping."""
    words = text.split()
    lines = []
    current_line = []

    for word in words:
        test_line = ' '.join(current_line + [word])
        if len(test_line) <= max_width:
            current_line.append(word)
        else:
            if current_line:
                lines.append(' '.join(current_line))
            current_line = [word]

    if current_line:
        lines.append(' '.join(current_line))

    return lines
```

**得：** 流圖含連匣與箭
**敗：** 調排算、驗箭標定

### 四、合柵像

以 Pillow 合多像：

Pillow 合成例（網格/橫/縱+注），見 [references/EXAMPLES.md](../../../../skills/create-2d-composition/references/EXAMPLES.md)。

**得：** 合像成含正排
**敗：** 察諸入像存、驗像模相容

### 五、生數驅像

依數建視：

```python
import numpy as np

def create_bar_chart_svg(data, labels, output_path):
    """Generate SVG bar chart from data."""
    dwg = svgwrite.Drawing(output_path, size=('600px', '400px'))

    # Chart area
    margin = 50
    chart_width = 500
    chart_height = 300
    bar_spacing = 10

    # Calculate bar dimensions
    n_bars = len(data)
    bar_width = (chart_width - (n_bars - 1) * bar_spacing) / n_bars

    # Scale data to fit chart
    max_value = max(data)
    scale = chart_height / max_value

    # Draw axes
    dwg.add(dwg.line(
        start=(margin, margin),
        end=(margin, margin + chart_height),
        stroke='black',
        stroke_width=2
    ))
    dwg.add(dwg.line(
        start=(margin, margin + chart_height),
        end=(margin + chart_width, margin + chart_height),
        stroke='black',
        stroke_width=2
    ))

    # Draw bars
    for i, (value, label) in enumerate(zip(data, labels)):
        x = margin + i * (bar_width + bar_spacing)
        bar_height = value * scale
        y = margin + chart_height - bar_height

        # Bar
        dwg.add(dwg.rect(
            insert=(x, y),
            size=(bar_width, bar_height),
            fill='steelblue',
            stroke='navy',
            stroke_width=1
        ))

        # Value label
        dwg.add(dwg.text(
            f'{value:.1f}',
            insert=(x + bar_width/2, y - 5),
            text_anchor='middle',
            font_size='10pt',
            fill='black'
        ))

        # X-axis label
        dwg.add(dwg.text(
            label,
            insert=(x + bar_width/2, margin + chart_height + 20),
            text_anchor='middle',
            font_size='10pt',
            fill='black'
        ))

    dwg.save()
```

**得：** SVG 柱圖含按比之數
**敗：** 理邊例（空數、負值）、加驗

### 六、批生像

自多像建：

```python
def batch_generate_badges(users, template_path, output_dir):
    """Generate badge for each user."""
    os.makedirs(output_dir, exist_ok=True)

    for user in users:
        output_path = os.path.join(output_dir, f"{user['id']}_badge.svg")

        dwg = svgwrite.Drawing(output_path, size=('300px', '100px'))

        # Background
        dwg.add(dwg.rect(
            insert=(0, 0),
            size=('100%', '100%'),
            fill='#3366cc',
            rx=10,
            ry=10
        ))

        # User name
        dwg.add(dwg.text(
            user['name'],
            insert=(150, 40),
            text_anchor='middle',
            font_size='20pt',
            font_weight='bold',
            fill='white'
        ))

        # User role
        dwg.add(dwg.text(
            user['role'],
            insert=(150, 70),
            text_anchor='middle',
            font_size='14pt',
            fill='lightblue'
        ))

        dwg.save()
        print(f"Generated badge: {output_path}")
```

**得：** 各數項生一像
**敗：** 察數構、以默處缺欄

### 七、SVG 轉柵

為諸用出 SVG 至 PNG/PDF：

```python
import cairosvg

def svg_to_png(svg_path, png_path, dpi=300):
    """Convert SVG to PNG with specified DPI."""
    # Calculate pixel dimensions from DPI
    # Assuming A4 size as example
    width_inches = 8.27
    height_inches = 11.69

    width_px = int(width_inches * dpi)
    height_px = int(height_inches * dpi)

    cairosvg.svg2png(
        url=svg_path,
        write_to=png_path,
        output_width=width_px,
        output_height=height_px
    )
    print(f"Converted to PNG: {png_path}")

def svg_to_pdf(svg_path, pdf_path):
    """Convert SVG to PDF."""
    cairosvg.svg2pdf(url=svg_path, write_to=pdf_path)
    print(f"Converted to PDF: {pdf_path}")
```

**得：** 柵出於定解
**敗：** 缺則裝 cairo 系庫、察 SVG 有效

## 驗

- [ ] 像於標應中正渲
- [ ] 字可讀位正
- [ ] 色合規、寸合用
- [ ] SVG 合準、柵出 DPI 正
- [ ] 排適數變、批畢無誤
- [ ] 出檔理組、碼含誤理

## 忌

1. **單位惑**：SVG 單與屏素印 DPI
2. **字溢**：過界→換行
3. **體可用**：系異→嵌或網安
4. **坐算**：格差一誤
5. **色式**：hex 串、非元
6. **SVG 有效**：XML 構、閉諸標
7. **檔路**：特符、檔名空格
8. **存用**：大批需塊、比例保、PNG 支 alpha 而 JPEG 否

## 參

- **[render-publication-graphic](../render-publication-graphic/SKILL.md)**：刊特出需
- **[create-3d-scene](../../blender/create-3d-scene/SKILL.md)**：三維之類程法
- **[generate-quarto-report](../../reporting/generate-quarto-report/SKILL.md)**：像融於報