95 lines
8.0 KiB
Markdown
95 lines
8.0 KiB
Markdown
# Extra Midra parameters in geometry exports
|
|
|
|
This optional extension is selected by **Export layers → Include extra Midra
|
|
parameters (experimental)**. It defaults off. Plain exports retain their existing
|
|
representation. Native **Save project** already saves the full project and needs
|
|
no additional switch.
|
|
|
|
Use **Project → Restore parameters from export…** to recover the original snapshot
|
|
into a new, unsaved project. The existing replacement review applies. The source
|
|
artwork never becomes the project-save/autosave path. Geometry import and clipboard
|
|
paste continue to import the artwork's current geometry; they do not silently
|
|
restore old positions, links or crop settings from metadata. This matters when an
|
|
external editor moves/resizes a shape without updating the embedded snapshot.
|
|
|
|
## Format audit and implemented carriers
|
|
|
|
| Format | Carrier / result | Compatibility limits |
|
|
| --- | --- | --- |
|
|
| SVG | `<metadata><parameters xmlns="urn:beffroi:midra:parameters:1">BASE64</parameters></metadata>` inside the SVG root | Non-rendered foreign-namespace metadata. SVG geometry exchange remains v2. Tested with librsvg rendering. Optimizers may remove metadata. |
|
|
| draw.io | Global root-cell custom property: `<object id="0" beffroi_midra_parameters="BASE64"><mxCell/></object>` | Graph model/geometry version stays 1. Installed draw.io Desktop opened and exported this to SVG; parameters also recovered from the SVG's embedded diagram. Compressed single-page draw.io models are supported through the existing bounded decoder. |
|
|
| Geometry JSON | Version **2**, required root string `beffroi_midra_parameters` | All v1 geometry fields unchanged. Versions 1 and 2 import; v1 exporters remain byte-compatible when the option is off. Older strict readers reject v2 rather than misread it. |
|
|
| Geometry CSV | Version **2** in every row; added `beffroi_midra_parameters` column | The first data row holds BASE64; remaining rows contain empty cells. Header/row widths remain equal and ordinary CSV quoting is used. No nonstandard comment lines. Versions 1 and 2 import; older schema-aware readers reject v2. |
|
|
| ASCII DXF | Group **999** comments after the existing geometry marker, each `beffroi-midra-parameters:CHUNK` | Ordered base64 chunks of at most 200 characters (comment lines under 255). Craft still reads the same rectangles. Comments may be stripped on CAD resave; binary DXF does not use group 999. |
|
|
| HTML | `<meta name="beffroi_midra_parameters" content="BASE64"/>` in `<head>` | Inert document metadata, no scripts or hidden visible objects. HTML geometry version stays 1. |
|
|
| PPTX | `docProps/custom.xml`, string property `beffroi_midra_parameters` | Standard custom-properties content type and package-root relationship; `vt:lpwstr`, pid 2, fmtid `{D5CDD505-2E9C-101B-9397-08002B2CF9AE}`. Existing ZIP parts are preserved; native DeckCraft import checks unchanged geometry. Microsoft PowerPoint resave not tested here. |
|
|
| DWG | Not enabled | DXF comments do not provide a reliable binary-DWG carrier. XRECORD/XData are potential future paths, but the current Craft conversion bridge has no verified application-payload round trip. No bytes are appended to the binary file. |
|
|
| FigCraft FIGCRAFT | Not enabled | Native geometry and image exchange only; no Midra snapshot field is emitted or restored. |
|
|
| Figma FIG | Not enabled | Figma has plugin data, but the installed FigCraft 0.5.1 native exporter explicitly warns `plugin data was left out`. Its model field is not evidence of native preservation. |
|
|
| Illustrator AI | Not enabled | PDF-compatible AI can have document metadata, but the current VectorCraft SVG↔AI conversion path has no verified application-payload preservation. No unverified PDF/AI trailer changes are made. |
|
|
| Midra project JSON | Already complete | Project v12 remains the authoritative full-fidelity save. This task does not change its schema. |
|
|
|
|
Unsupported codecs disable the option with an explanation. Programmatic attempts
|
|
to request the extension on those codecs fail explicitly, never silently discard
|
|
it. Vendor availability and the `no_proprietary` build flag still apply.
|
|
|
|
## Payload contract (extension version 1)
|
|
|
|
`BASE64` is standard padded RFC 4648 base64 of UTF-8, pretty-printed
|
|
[project JSON](midra-layout.md), currently version 12. It is inert data, not an
|
|
executable instruction, URL or file path. Project format/version and validation
|
|
remain authoritative. Future incompatible carrier/payload meanings require a new
|
|
extension version and explicit migration or rejection.
|
|
|
|
The snapshot includes only exported layer IDs, in document stack order, with
|
|
full-precision bounds, names, folders, visibility, locks, pivots, Midra links,
|
|
source/input crop and advanced crop. Only referenced input slots are included;
|
|
source IDs are remapped consecutively, preserving shared source relationships.
|
|
Selection, explicit folders and collapsed folders are filtered to retained layers; unrelated empty folders are omitted. Output resolution,
|
|
positioning, camera, guide and workspace settings remain available. Pixel-rounded
|
|
artwork and full-precision stored coordinates are intentionally distinct.
|
|
|
|
All reference-image objects and preview assignments/images/device-address bindings
|
|
are omitted. Artwork background/placeholder options operate independently; they do
|
|
not embed capture settings. Application preferences, connection history, active
|
|
connections, pending device edits/jobs and undo history are never included.
|
|
|
|
The decoded metadata JSON is limited to **1 MiB**, and the complete exchange file
|
|
still must fit within **16 MiB** after embedding. PPTX custom-properties XML reads
|
|
are bounded to 2 MiB. No archive members are extracted onto the filesystem. Invalid
|
|
base64 or project data rejects explicit snapshot restoration. For geometry JSON
|
|
and CSV, the known v2 extension is removed before strict v1 geometry validation;
|
|
invalid optional payload contents do not prevent importing otherwise valid artwork.
|
|
Unknown versions and unknown geometry fields remain errors. More than one nonempty
|
|
CSV snapshot is rejected on restoration.
|
|
|
|
The [JSON v2 example](midra-geometry-v2-metadata.example.json) is a tested example;
|
|
its decoded snapshot is also validated as a project. Plain v1 fixtures remain
|
|
unchanged. Other carriers use the same payload bytes and are round-trip tested
|
|
with background on/off and optional placeholders. The regression suite also checks
|
|
that edited artwork is imported as edited, unsupported codecs refuse the option,
|
|
and recovered exports are never reused as project-save paths.
|
|
|
|
## Standards and codec evidence
|
|
|
|
- [W3C SVG extensibility](https://www.w3.org/TR/SVG11/extend.html) explicitly allows
|
|
application metadata for round trips; [SVG 2 structure](https://www.w3.org/TR/SVG2/struct.html)
|
|
describes metadata containers.
|
|
- [draw.io global custom properties](https://www.drawio.com/docs/manual/advanced/global-custom-properties/)
|
|
documents root-cell custom data.
|
|
- [Autodesk DXF group codes](https://help.autodesk.com/cloudhelp/2024/ENU/AutoCAD-DXF/files/GUID-3F0380A5-1C15-464D-BC66-2C5F094BCFB9.htm)
|
|
documents group 999 comments. [Binary DXF](https://help.autodesk.com/cloudhelp/2023/ENU/AutoCAD-DXF/files/GUID-FC1C3C69-DBC2-49E4-893A-000D6538C0FE.htm)
|
|
does not use that comment group.
|
|
- [WHATWG document metadata](https://html.spec.whatwg.org/dev/semantics.html)
|
|
describes name/content metadata. [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180)
|
|
describes CSV fields and quoting; this extension adds a regular column.
|
|
- [Microsoft custom properties](https://learn.microsoft.com/en-us/office/open-xml/word/how-to-set-a-custom-property-in-a-word-processing-document)
|
|
describes the shared Open XML custom-property representation; its package
|
|
relationship applies to presentations too.
|
|
- [Figma plugin data](https://developers.figma.com/docs/rest-api/file-endpoints/)
|
|
exists in the platform. The local `figcraft-format 0.5.1/src/fig/export.rs`
|
|
exporter nevertheless rejects preservation in `plugin_data`; support stays off.
|
|
- Craft DWG source inspected at revision
|
|
`79e97b6febcb62de406e5bcf5a724bd3f7333065`; current native adapter conversion
|
|
boundaries are in `crates/midra-layout/src/vendor_formats.rs`.
|