beffroi-tools/docs/interfaces/midra-layout-exchange.md

9.0 KiB
Raw Blame History

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:

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. 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. 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:

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 and desktop CLI.