152 lines
9.0 KiB
Markdown
152 lines
9.0 KiB
Markdown
# Midra Layout SVG and draw.io exchange
|
||
|
||
The Export menu writes **SVG geometry v2** and **draw.io geometry v1**. Project
|
||
JSON remains version 9 and is the full-fidelity save format. These exchanges
|
||
preserve layer **visible-box geometry**, not sources, crop settings, zoom, pivots,
|
||
Midra links, locks, visibility, camera or selection. Pictures illustrate current
|
||
cropping; importing a picture does not reconstruct its crop or source settings.
|
||
|
||
Ready-to-open two-layer templates are published under
|
||
`docs/templates/midra-layout/` for Full HD (1920 × 1080) and UHD 4K
|
||
(3840 × 2160), in both SVG v2 and draw.io v1. The 4K geometry is an exact 2×
|
||
scale of the Full HD layout. Regenerate them with:
|
||
|
||
```sh
|
||
cargo run --locked -p midra-layout --example check_geometry_exchange -- templates docs/templates/midra-layout
|
||
```
|
||
|
||
## Scope, coordinates and artwork
|
||
|
||
Both formats offer Current layer (exactly one selected), Selected layers,
|
||
Specific layer (including hidden), All layers and Visible layers only. Stable IDs
|
||
are `layer-N`; order is document stacking order, independent of selection order.
|
||
All chosen layers are exported visibly, even if hidden in the editor. No layers,
|
||
unknown/duplicate IDs, invalid project geometry or dimensions rounding below one
|
||
pixel reject export. X/Y are top-left output pixels, relative to the **whole output
|
||
screen**, including for single-layer exports. X, Y, width and height round
|
||
independently to nearest integer; halves round away from zero. Negative positions
|
||
are retained. No stroke expansion is necessary: exported boxes have no outline.
|
||
|
||
Options are shared by the SVG/draw.io menus for the current session, default off;
|
||
they do not modify the project/settings schema:
|
||
|
||
- **Include background layer** adds a first, full-screen image with ID
|
||
`midra-background`, explicitly marked as background. A visible reference is
|
||
composited over a dark backdrop using the current fit/stretch/native-size,
|
||
offset and opacity. Otherwise it is a plain dark backdrop. This is a baked visual
|
||
reference, not an editable copy of reference settings. Image raster dimensions
|
||
are proportional to the screen, capped at 1920 pixels on the longest side;
|
||
the exported shape still has the exact screen dimensions.
|
||
- **Include placeholder pictures** uses embedded PNG source-grid patterns instead
|
||
of flat layer fills. The pattern reflects native input cropping and advanced
|
||
cropping, fitted into each visible box. Each raster is capped at 512 pixels on
|
||
its longest side. No live source image is available/captured by this exporter.
|
||
The images contain no external URLs and need no network access. Imported picture
|
||
layers are still geometry-only. Without this option, the layers are rectangles.
|
||
|
||
The background is detected and ignored by default on import and cannot be mapped
|
||
as a content layer. A legitimate full-screen layer is kept as a layer. Every
|
||
placeholder is **one** importable layer, not an image plus duplicate rectangle.
|
||
|
||
## SVG v2
|
||
|
||
Example: [midra-layout-svg-v2.example.svg](midra-layout-svg-v2.example.svg).
|
||
UTF-8 SVG; SVG namespace and optional XLink namespace. Root attributes:
|
||
|
||
- `data-midra-layout-geometry="2"`
|
||
- `width`, `height`: output screen dimensions in pixels
|
||
- `viewBox="0 0 W H"`
|
||
|
||
Each layer is a `<rect>` (plain) or `<image>` (placeholder), with `id="layer-N"`,
|
||
`data-midra-role="layer"`, `x`, `y`, `width`, `height`. A `<title>` carries its name
|
||
for external viewers; Midra import does not rename destinations. Images use
|
||
`xlink:href="data:image/png;base64,..."` and `preserveAspectRatio="none"`.
|
||
The optional background is an `<image>` with `data-midra-role="background"` and
|
||
full-page bounds. No visible text geometry, transforms, clipping or CSS is needed.
|
||
|
||
The importer supports v1 and v2 and explicitly rejects other marked versions.
|
||
Legacy `Project::to_svg`/`to_svg_ids` continue producing v1 rectangle-only SVG;
|
||
the GUI uses v2. Old applications cannot import v2 placeholder images; use JSON
|
||
or a plain rectangle-only export where required. Editors should retain role
|
||
markers. If they remove them, ordinary image import remains intentionally limited
|
||
to a first full-page background. Midra never fetches image URLs during import.
|
||
|
||
## draw.io v1
|
||
|
||
Example: [midra-layout-drawio-v1.example.drawio](midra-layout-drawio-v1.example.drawio).
|
||
UTF-8 uncompressed `<mxfile compressed="false">` with one `<diagram>` containing
|
||
an `<mxGraphModel data-midra-layout-geometry="1">`. `pageWidth`, `pageHeight`,
|
||
`pageScale="1"`, and `page="1"` establish the output canvas; diagram units are pixels.
|
||
Root cells `0` and `1` provide the required graph root and default layer.
|
||
|
||
Each exported shape is an `<mxCell vertex="1" parent="1">` with stable `id`,
|
||
escaped plain-text `value` (layer name), and `data-midra-role="layer"` or
|
||
`"background"`. Its single `<mxGeometry as="geometry">` stores pixel X/Y/width/
|
||
height. Styles disable outlines and rounding. Pictures use `shape=image`,
|
||
`imageAspect=0`, and draw.io's `image=data:image/png,BASE64` style syntax (without
|
||
`;base64`, which would split the style). Background label text is empty.
|
||
|
||
Import accepts raw/once-percent-encoded mxGraphModel clipboard XML, single-page
|
||
mxfile XML, and native compressed diagram text: Base64 → raw DEFLATE → percent
|
||
decode → mxGraphModel. Native re-saving may remove the model's Midra version
|
||
attribute; role attributes and stable IDs survive in the tested version. The
|
||
reserved `midra-background` ID also identifies the exported background. Unknown
|
||
marked draw.io exchange versions are rejected. Multiple pages are refused with an
|
||
instruction to export one page, rather than silently importing the wrong page.
|
||
Groups, edges, rotation, flips, relative/alternate bounds and nonrectangular
|
||
shapes remain unsupported; ordinary unrotated image cells now import their box.
|
||
|
||
## Limits, import and round trips
|
||
|
||
Import files and clipboard text, and generated exports, are capped at **16 MiB**
|
||
(to allow self-contained images). Decompression is bounded: at most 48 MiB of
|
||
percent-encoded text and 16 MiB decoded XML. Up to 256 layer boxes plus one
|
||
background are allowed. No imported image is decoded or downloaded by the
|
||
geometry importer. Export reference decoding retains the existing 8192-pixel
|
||
per-side/256 MiB decoder bounds. Oversized exports fail before writing a file.
|
||
|
||
Use **Import → SVG / draw.io file…**, or paste XML, then review and map shapes to
|
||
editor layers. Destination count need not match current selection. Import with
|
||
size and position enabled restores the rounded geometry in one Undo step. Output
|
||
screen resolution is not imported. Mapped names, sources and Midra links stay with
|
||
the destination layers. File replacement retains the existing explicit overwrite
|
||
confirmation and atomic-write path.
|
||
|
||
SVG files rendered by draw.io Desktop are also accepted. The importer recognizes
|
||
the `data-cell-id` wrapper groups retained by draw.io, reads the first rectangle,
|
||
image or symbol use in each cell, and ignores generated HTML labels, raster text
|
||
fallbacks, symbols and the draw.io help link. The standard SVG 1.1 public DOCTYPE
|
||
emitted by draw.io is accepted without fetching external content; XML parsing is
|
||
limited to 200,000 nodes. The reserved `midra-background` cell remains an ignored
|
||
background.
|
||
|
||
Draw.io's SVG export normally crops the canvas to the diagram content, adds one
|
||
pixel to its bounds and rebases cell coordinates. Those rebased coordinates are
|
||
the only positions present in that SVG. Include Midra Layout's background layer
|
||
before exporting through draw.io when the full output-screen origin must survive
|
||
the round trip.
|
||
|
||
Tests cover each format/artwork combination, full-screen layers vs backgrounds,
|
||
negative/fractional coordinates, repeat round trips, compressed clipboard/files,
|
||
embedded references, invalid IDs/versions and no-overwrite file handling.
|
||
A manual native-editor check is available:
|
||
|
||
```sh
|
||
cargo run --locked -p midra-layout --example check_geometry_exchange -- generate /tmp/midra-exchange-check
|
||
drawio -x --size page -o /tmp/midra-exchange-check/render.png /tmp/midra-exchange-check/illustrated.drawio
|
||
drawio -x -o /tmp/midra-exchange-check/resaved.xml /tmp/midra-exchange-check/illustrated.drawio
|
||
drawio -x -f svg -o /tmp/midra-exchange-check/drawio-rendered.svg /tmp/midra-exchange-check/illustrated.drawio
|
||
cargo run --locked -p midra-layout --example check_geometry_exchange -- verify /tmp/midra-exchange-check/resaved.xml
|
||
cargo run --locked -p midra-layout --example check_geometry_exchange -- verify /tmp/midra-exchange-check/drawio-rendered.svg
|
||
```
|
||
|
||
On 2026-11-14, installed **draw.io Desktop 31.7.0** (`/usr/bin/drawio`, not Flatpak)
|
||
rendered the illustrated diagram correctly, and its re-saved XML returned both
|
||
layer boxes unchanged. Its SVG export, including `<symbol>/<use>` image cells and
|
||
HTML/raster label fallbacks, also returned both layer boxes unchanged when the
|
||
background preserved the page. Generated plain/illustrated SVG and draw.io files
|
||
passed geometry verification. Native output artifacts remain in `/tmp`, not Git.
|
||
|
||
Protocol references: [draw.io diagram format](https://www.drawio.com/docs/reference/diagram-generation/)
|
||
and [desktop CLI](https://github.com/jgraph/drawio/wiki/Desktop-App).
|