claude-obsidian 스킬 뜯어보기 (9): canvas

The three knowledge capture layers:
- `/save` → text synthesis (wiki/questions/, wiki/concepts/)
- `/autoresearch` → structured knowledge (wiki/sources/, wiki/concepts/)
- `/canvas` → visual references (wiki/canvases/)

claude-obsidian/
├── skills/canvas/
│   ├── SKILL.md                        # 스킬 본체 — 9가지 오퍼레이션, 배치 알고리즘
│   └── references/
│       └── canvas-spec.md              # JSON Canvas 스펙 — 좌표계, 노드 타입, 색상
└── commands/
    └── canvas.md                       # /canvas 커맨드 라우터 — 9종 커맨드 매핑

A canvas is a JSON file Obsidian renders as an infinite visual board.
This skill reads and writes canvas JSON directly.
Read `references/canvas-spec.md` for the full format reference
before making any edits.

{
  "nodes": [ ... ],
  "edges": []
}

`wiki/canvases/main.canvas`

{
  "nodes": [
    {
      "id": "title",
      "type": "text",
      "text": "# Visual Reference\n\nDrop images, PDFs, and notes here.",
      "x": -400, "y": -300, "width": 400, "height": 120, "color": "6"
    },
    {
      "id": "zone-default",
      "type": "group",
      "label": "General",
      "x": -400, "y": -140, "width": 800, "height": 400, "color": "4"
    }
  ],
  "edges": []
}

**Detect aspect ratio:**
Use `python3 -c "from PIL import Image; img=Image.open('[path]');
print(img.width, img.height)"` or `identify -format '%w %h' [path]`.
See `references/canvas-spec.md` for the full aspect ratio →
canvas size table (7 ratios including 4:3, 3:4, ultra-wide).

{
  "id": "text-[timestamp]",
  "type": "text",
  "text": "[content]",
  "x": "[auto]", "y": "[auto]",
  "width": 300, "height": 120,
  "color": "4"
}

Same as add image. Obsidian renders PDFs natively as file nodes.
- Copy to `_attachments/pdfs/canvas/` if outside vault.
- Fixed size: width=400, height=520.

Use `"type": "file"` (not `"type": "link"`):
`.md` files use file nodes, not link nodes.
`"type": "link"` takes a `url: "https://..."`:
it is for web URLs only.

{
  "id": "note-[timestamp]",
  "type": "file",
  "file": "wiki/concepts/LLM Wiki Pattern.md",
  "x": "[auto]", "y": "[auto]",
  "width": 300, "height": 100
}

{
  "id": "zone-[slug]",
  "type": "group",
  "label": "[name]",
  "x": -400,
  "y": "[max_y]",
  "width": 1000,
  "height": 400,
  "color": "[color or '3']"
}

def next_position(canvas_nodes, target_zone_label, new_w, new_h):
    # Find zone group node
    zone = next((n for n in canvas_nodes
                 if n.get('type') == 'group'
                 and n.get('label') == target_zone_label), None)
 
    if zone is None:
        # No zone: place below all content
        max_y = max((n['y'] + n.get('height', 0)
                     for n in canvas_nodes), default=-140)
        return -400, max_y + 60

    # Nodes inside this zone
    inside = [n for n in canvas_nodes
              if n.get('type') != 'group'
              and zx <= n['x'] < zx + zw
              and zy <= n['y'] < zy + zh]
 
    if not inside:
        return zx + 20, zy + 20

    rightmost_x = max(n['x'] + n.get('width', 0) for n in inside)
    next_x = rightmost_x + 40
 
    if next_x + new_w > zx + zw:
        # New row
        max_row_y = max(n['y'] + n.get('height', 0) for n in inside)
        return zx + 20, max_row_y + 20
 
    # Same row: align to the top of all existing nodes in the zone
    current_row_y = min(n['y'] for n in inside)
    return next_x, current_row_y

Safe ID pattern: `[type]-[content-slug]-[full-unix-timestamp]`
 
Use the full Unix timestamp (10 digits)
to avoid collisions in batch operations.
 
Examples: `img-cover-1744032823`, `text-note-1744032845`,
          `zone-branding-1744032901`
 
If a collision is detected (ID already exists in the canvas),
append `-2`, `-3`, etc.

If `wiki/canvases/.recent-images.txt` exists,
append any new image path written to `_attachments/images/`
during this session (one path per line, keep last 20).
 
`/canvas from banana` reads this file first,
making it instant without filesystem search.

After any `/banana` run in the same session,
if the user says "add to canvas" or "put on canvas",
treat it as `/canvas from banana`.
 
When `/banana` finishes generating images, suggest:
> "Add generated images to canvas? Run `/canvas from banana`"

python3 -c "import time,os; open('/tmp/ten-min-ago','w').close(); \
os.utime('/tmp/ten-min-ago',(time.time()-600,time.time()-600))"
find _attachments/images -newer /tmp/ten-min-ago \
\( -name "*.png" -o -name "*.jpg" \)

This spec aligns with the JSON Canvas open standard
(https://jsoncanvas.org/).
If the kepano/obsidian-skills plugin is installed,
its json-canvas skill is the authoritative canvas spec reference.
Otherwise, use the guidance below.

Canvas files are JSON with two top-level keys:
`nodes` (array) and `edges` (array).
Obsidian reads and writes them as UTF-8 JSON files
with `.canvas` extension.

All structures support arbitrary additional fields
(`[key: string]: any`) for forward compatibility.
Obsidian will preserve unknown fields
when reading and writing canvas files.

**ID format**: The JSON Canvas 1.0 spec recommends
16-character lowercase hexadecimal IDs
(e.g., `"a1b2c3d4e5f67890"`).
Obsidian itself generates IDs in this format.
The descriptive ID examples in this reference
(`"text-title-4821"`, `"img-cover-7823"`)
are an alternative naming convention
that this plugin uses for human readability.
Both are valid JSON Canvas.

        x increases →
   ┌─────────────────────────────────
   │  (-920, -2400)      (0, -2400)
   │
y  │  (-920, 0)          (0, 0) ← origin
↓  │
   │  (-920, 540)        (500, 540)

**Negative y confusion**: `y: -2400` is ABOVE `y: -1000`
(more negative = higher up)

{
  "id": "text-title-4821",
  "type": "text",
  "text": "# Heading\n\nParagraph with **bold** and `code`.",
  "x": -400, "y": -300,
  "width": 400, "height": 120,
  "color": "6"
}

{
  "id": "img-cover-7823",
  "type": "file",
  "file": "_attachments/images/example.png",
  "x": -900, "y": -100,
  "width": 420, "height": 236
}

{
  "id": "zone-branding-3391",
  "type": "group",
  "label": "Brand Identity",
  "x": -920, "y": -880,
  "width": 1060, "height": 290,
  "color": "6",
  "background": "_attachments/images/grid-bg.png",
  "backgroundStyle": "cover"
}

Groups do not affect auto-layout:
they are purely visual containers.

{
  "id": "link-karpathy-2233",
  "type": "link",
  "url": "https://github.com/karpathy",
  "x": 200, "y": -300,
  "width": 400, "height": 120
}

{
  "id": "e-hub-cidx",
  "fromNode": "hub",
  "fromSide": "right",
  "fromEnd": "none",
  "toNode": "c-idx",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "concepts",
  "color": "5"
}

`fromEnd` *(optional)*: end-cap on the source side.
  Defaults to `"none"`.
`toEnd` *(optional)*: end-cap on the target side.
  **Defaults to `"arrow"`**:
  note the asymmetric default vs `fromEnd`.

- `label` *(optional)*: text shown on the edge.

| Code | Color         | Hex (approx) | Use case              |
|------|---------------|-------------|-----------------------|
| "1"  | Red / Tomato  | #e03e3e     | Warnings, archive     |
| "2"  | Orange        | #d09035     | Active work           |
| "3"  | Yellow / Gold | #d0a023     | WIP, notes            |
| "4"  | Green / Teal  | #448361     | Content, sources      |
| "5"  | Blue / Cyan   | #3ea7d3     | Navigation, info      |
| "6"  | Purple/Violet | #9063d2     | Title, identity       |

| Aspect ratio    | Condition      | Canvas width | Canvas height |
|-----------------|----------------|-------------|--------------|
| 16:9 (wide)     | ratio 1.6–2.0  | 420         | 236          |
| 2:1 (ultra wide)| ratio > 2.0    | 440         | 220          |
| 4:3             | ratio 1.2–1.6  | 380         | 285          |
| 1:1 (square)    | ratio 0.9–1.1  | 280         | 280          |
| 3:4             | ratio 0.6–0.9  | 240         | 320          |
| 9:16 (portrait) | ratio < 0.6    | 200         | 356          |
| PDF             | any            | 400         | 520          |
| Unknown         | fallback       | 320         | 240          |

python3 -c "from PIL import Image; \
img=Image.open('path.png'); print(img.width, img.height)"
# or
identify -format '%w %h' path.png

function place_node(canvas, zone_label, new_w, new_h):
  zone = find group node where label == zone_label
  padding = 20
 
  if zone not found:
    max_y = max(n.y + n.height for n in canvas.nodes) + 60
    return (-400, max_y)

  if next_x + new_w > zone.x + zone.width - padding:
    # Overflow → new row
    bottom_of_row = max(n.y + n.height for n in inside)
    return (zone.x + padding, bottom_of_row + padding)

| Command                     | What it does                                      |
|-----------------------------|---------------------------------------------------|
| `/canvas`                   | Status check — report node counts, list zones     |
| `/canvas new [name]`        | Create a new named canvas in wiki/canvases/       |
| `/canvas add image [path]`  | Add image to canvas (download if URL, copy if outside vault) |
| `/canvas add text [content]`| Add a text card to the canvas                     |
| `/canvas add pdf [path]`    | Add a PDF document node                           |
| `/canvas add note [page]`   | Add a wiki page as a linked card                  |
| `/canvas zone [name] [color]`| Add a new labeled zone group                     |
| `/canvas list`              | List all canvases with node counts                |
| `/canvas from banana`       | Find recent generated images and add them         |

---
description: Open, create, or update a visual canvas —
  add images, text, PDFs, wiki pages, and banana-generated
  assets to Obsidian canvas files.
---

Default canvas: `wiki/canvases/main.canvas`
 
If the canvas file does not exist, create it before adding anything.

If yes: read it, count nodes by type,
list all group node labels (zone names).
Report: "Canvas has N nodes: X images, Y text cards,
Z wiki pages. Zones: [list]"

Add entry to `wiki/overview.md` under a "## Canvases" subsection.
Do not modify `wiki/index.md`.
It uses a fixed section schema
(Domains, Entities, Concepts, Sources, Questions, Comparisons).

For standalone visual production (12 templates, 6 layout algorithms,
AI generation, presentations),
see claude-canvas (https://github.com/AgriciDaniel/claude-canvas).
This skill handles wiki-scoped visual boards.
claude-canvas handles full-featured canvas orchestration
for any project.