143 lines
8.6 KiB
Markdown
143 lines
8.6 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.
|
|
|
|
## 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).
|