drawio2tikz

name	drawio2tikz
description	Convert one sheet of a .drawio file into a coordinate-exact TikZ fragment for embedding in LaTeX. Use when the user asks to turn a draw.io diagram/figure into TikZ, when a LaTeX figure must reproduce a draw.io sheet exactly (mechanical drawings, flowcharts, module layouts), or for /drawio2tikz. Drives scripts/drawio2tikz.py (absolute coordinates, group-offset resolution, edge anchoring to shape perimeters, waypoints, braces, FR->EN translation).
allowed-tools	["Read","Write","Edit","Bash"]
permissions	["write"]

drawio2tikz Skill

Deterministic, by-script conversion of a single <diagram> (sheet) from a .drawio file into a TikZ fragment using absolute coordinates. The script encodes every conversion rule that is easy to get wrong by hand; do not re-transcribe diagrams manually and do not eyeball coordinates.

When to use

• A LaTeX figure must reproduce a draw.io sheet exactly (no simplification): mechanical drawings, battery/module layouts, flowcharts, schematics.
• The user provides a .drawio path and names a sheet, or asks for /drawio2tikz.
• Re-running after the .drawio changed (regenerate, then re-embed).

This script is the source of conversion truth. If a figure already in a .tex looks wrong, prefer diffing the existing TikZ against the drawio and patching the offending lines (see "Fixing an existing figure"); regenerate only when the whole figure is being (re)built.

Prerequisites

1. python reachable from the shell.
2. Recommended: pip install defusedxml (the script falls back to the stdlib parser for trusted local files, but defusedxml avoids the XXE warning).
3. The consuming LaTeX preamble must load:

   \usetikzlibrary{arrows.meta,decorations.pathreplacing}
   

   (arrows.meta for arrow tips, decorations.pathreplacing for braces.) xcolor is pulled in by most classes (mdpi.cls, etc.); colours are emitted inline as {rgb,255:...}.

Usage

# 1. list the sheets
python .claude/skills/drawio2tikz/scripts/drawio2tikz.py FILE.drawio --list

# 2. convert one sheet to a fragment
python .claude/skills/drawio2tikz/scripts/drawio2tikz.py FILE.drawio \
    --diagram "Scenario 2" --out fragment.tex

# with FR->EN label translation and a full figure skeleton
python .claude/skills/drawio2tikz/scripts/drawio2tikz.py FILE.drawio \
    --diagram "Scenario 2" --translate labels.json --wrap --out fragment.tex

--diagram takes a case-insensitive substring of the sheet name and must match exactly one sheet (accents in .drawio names can be awkward in the shell; a partial like tude 2 is fine).

Flag	Effect
--list	Print sheet names and exit
--diagram NAME	Substring of the target sheet name (must be unique)
--scale F	cm per draw.io px (default 0.0264); irrelevant for fit if wrapped in \resizebox
--translate JSON	{ "french": "english" } applied to label text after HTML stripping
--brace-amplitude P	Brace size in pt (default 10)
--brace-mirror auto|on|off	Bulge side of curlyBracket braces (default auto = mirror when horizontal)
--wrap	Emit a figure+\resizebox+tikzpicture skeleton with a TODO caption
--out FILE	Write to FILE (default stdout)

Workflow

1. --list to confirm the exact sheet name.
2. If labels need translating, write a small JSON dict (French key -> English value), one entry per distinct label string (exact match after HTML strip). Translate only toward the target document's language: if the consuming document is French, keep French labels (or translate EN->FR); respect the document's original language (the scientific-writing language rule).
3. Run the script with --out to a temp fragment.
4. Embed: paste the fragment inside the target figure environment, wrapped in \resizebox{\linewidth}{!}{ \begin{tikzpicture} ... \end{tikzpicture} } so it fits the column regardless of --scale. Keep the existing \caption/\label. The embedded figure must follow the scientific-writing float rules: a fig:three-words \label, a citation via \ref{} with at least two explanatory sentences, and a real caption (replace the --wrap TODO). See .claude/skills/scientific-writing/references/float_authoring_rules.md.
5. Compile and verify visually (render the figure page with pdftoppm and compare against the draw.io sheet). Check especially: connectors meeting their shapes, brace direction, rotated labels.

The converted output is intentionally NOT TiKZiT-editable and uses absolute coordinates by design (the documented exception to the scientific-writing / /tikz relative-positioning rule). Running /tikz on it may flag arrow tips or spacing, but the absolute coordinates and inline colours are expected here and are not defects; only arrow tips, true overlaps, and connectors that miss their shapes are worth acting on.

Fixing an existing figure (no full reconversion)

When a figure is mostly right but has a defect, do not regenerate blindly:

1. Read the TikZ lines in the .tex.
2. Read the corresponding cells in the .drawio sheet.
3. Diff numerically; the usual culprits are listed in references/conversion-rules.md (edge endpoints, braces, rotation).
4. Patch the offending \draw/\node line(s) directly.

Brace direction caveat

curlyBracket orientation (which way the tongue points) is the one thing the script infers heuristically: it mirrors horizontal braces (underbrace, opening down toward a label) and leaves vertical ones un-mirrored. Always eyeball braces after compiling; flip with --brace-mirror on|off or edit the single \draw line if the bulge points the wrong way.

Error handling

Symptom	Cause / action
--diagram matched N diagrams	Substring not unique; pass a longer, unique fragment of the name
Connector line floats off a box	Edge anchored via exit/entry — the script handles this; if it still floats, the shape has no exit/entry and no useful mxPoint (rare) — add the anchor in draw.io or patch the endpoint
A line stops short of where it should meet	Missing <Array> waypoint in the source, or the waypoint extends past the target (script includes waypoints; verify the source)
Brace looks flat / points wrong way	--brace-amplitude too small, or wrong --brace-mirror; see caveat above
Rotated label misplaced	draw.io rotation is about the cell centre; the script emits rotate=-rotation (Y flip) about the node centre — verify the cell really rotates about its centre in draw.io
Garbled accents in --list output	Console codepage only; the conversion itself is UTF-8 safe
XXE warning on Write/run	Install defusedxml; the stdlib fallback is acceptable for a trusted local file

See also

• Converter: scripts/drawio2tikz.py
• Conversion rules and pitfalls (read before editing the script): references/conversion-rules.md