From c29b6aa8f19f6150ec9ff3b26e2f3df00497f197 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 15 Nov 2026 12:56:59 +0100 Subject: [PATCH] Document optional VectorCraft CLI requirement and prefer SVG exchange --- README.md | 4 +++ docs/interfaces/midra-layout-exchange.md | 4 +++ docs/midra-layout/README.md | 4 ++- docs/midra-layout/changelog.md | 4 +++ docs/midra-layout/guide/files.md | 43 ++++++++++++++++++++++++ docs/templates/midra-layout/README.md | 6 +++- 6 files changed, 63 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c6b9049..a731231 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,10 @@ Matching Full HD and UHD 4K layouts are available in SVG, draw.io, geometry JSON CSV, DXF/DWG, HTML, PPTX, Figma FIG, FigCraft and Illustrator AI. The catalog contains every base file, import guidance and format dependencies. +**Prefer SVG for Illustrator exchange.** AI is an optional compatibility target +and requires a separately installed **VectorCraft CLI** for import and export. +[AI requirements and setup](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/midra-layout/guide/files.md#illustrator-ai-optional-converter-required). + ## Explore further | Resource | Links | diff --git a/docs/interfaces/midra-layout-exchange.md b/docs/interfaces/midra-layout-exchange.md index 333e79e..b62526d 100644 --- a/docs/interfaces/midra-layout-exchange.md +++ b/docs/interfaces/midra-layout-exchange.md @@ -183,6 +183,10 @@ Tests cover native resaving, bare JSON, geometry, artwork and both starter sizes ### Illustrator AI +Optional compatibility target: **prefer SVG for Illustrator exchange**. AI import +and export require a separately installed VectorCraft CLI; it remains external +and is not embedded or bundled. See the [manual setup instructions](../midra-layout/guide/files.md#illustrator-ai-optional-converter-required). + Uses [VectorCraft CLI](https://github.com/storytold/vectorcraft), discovered through `MIDRA_VECTORCRAFT_CLI`, beside the Midra executable, in its `bin/` subdirectory, then on PATH. Conversion runs locally in safe mode in a temporary directory, with diff --git a/docs/midra-layout/README.md b/docs/midra-layout/README.md index 74f3a47..2863ee7 100644 --- a/docs/midra-layout/README.md +++ b/docs/midra-layout/README.md @@ -70,7 +70,9 @@ See [formats and crop](guide/formats-and-crop.md) and - **Work with another application:** drop a supported geometry file into the window, use **Import → Geometry file…**, or **Project → Export → Export layers…**. The [starter-file catalog](../templates/midra-layout/README.md) has matching Full HD and 4K files in SVG, draw.io, geometry JSON, CSV, DXF/DWG, - HTML, PPTX, Figma FIG, FigCraft and Illustrator AI. It also lists format dependencies. + HTML, PPTX, Figma FIG, FigCraft and Illustrator AI. Prefer SVG for Illustrator + exchange: AI requires a separately installed VectorCraft CLI for both import + and export. See [AI setup](guide/files.md#illustrator-ai-optional-converter-required). - **Use an Eikos 4K:** connect, review layer mappings, then explicitly load or send the chosen layers. Ordinary editing does not send commands to the device. Follow the [connection and transfer guide](guide/device.md) and its linked diff --git a/docs/midra-layout/changelog.md b/docs/midra-layout/changelog.md index 6bc1da0..07dc5a2 100644 --- a/docs/midra-layout/changelog.md +++ b/docs/midra-layout/changelog.md @@ -4,6 +4,10 @@ ## Unreleased +- Recommend SVG for Illustrator exchange in the README, manual and template + catalog. Keep AI as an optional compatibility target requiring external + VectorCraft CLI, with executable discovery and setup documented. + - Group viewport context-menu property windows under Properties and capture under Input preview & crop guides, with quick preview/opacity controls. Keep common editing actions direct, move Delete after Lock/Hide, and group canvas options diff --git a/docs/midra-layout/guide/files.md b/docs/midra-layout/guide/files.md index f37aabc..eb9c2d6 100644 --- a/docs/midra-layout/guide/files.md +++ b/docs/midra-layout/guide/files.md @@ -314,3 +314,46 @@ Other programs may remove the extra data when resaving. **Save project** remains the complete save, including reference images and captured previews. See the [format-by-format audit and metadata contract](../../interfaces/midra-extra-parameters.md). + +## Illustrator AI: optional converter required + +**SVG is the preferred format for exchanging layer layouts with Illustrator.** +Midra imports and exports SVG directly, without Illustrator or VectorCraft installed. +AI remains an optional compatibility format; both AI import and AI export require +**VectorCraft CLI**, which is not bundled with Midra Layout. Installing the +VectorCraft graphical application alone does not guarantee that its CLI is +available to Midra. + +The normal build includes all other supported exchange formats without external +applications: SVG, draw.io, geometry JSON/CSV, HTML, DXF/DWG, PPTX, FIG and FIGCRAFT. +A build made with `no_proprietary` disables DWG, PPTX, FIG, FIGCRAFT and AI support. +Installing a converter does not re-enable formats excluded from that build. + +Obtain VectorCraft CLI from the [VectorCraft project](https://github.com/storytold/vectorcraft). +Midra searches in this order: + +1. The executable path set in `MIDRA_VECTORCRAFT_CLI`. +2. `vectorcraft-cli` beside the Midra Layout executable. +3. `vectorcraft-cli` in the adjacent `bin/` folder. +4. `vectorcraft-cli` on `PATH`. + +On Windows the executable is named `vectorcraft-cli.exe`. For an explicit location, +start Midra from the same terminal in which you set the variable: + +```sh +MIDRA_VECTORCRAFT_CLI=/absolute/path/to/vectorcraft-cli midra-layout +``` + +```powershell +$env:MIDRA_VECTORCRAFT_CLI = 'C:\Tools\VectorCraft\vectorcraft-cli.exe' +.\midra-layout.exe +``` + +Select **Illustrator · AI (VectorCraft)** in Export layers, or import an `.ai` file +through Geometry file. Conversion is local and temporary; it does not use a cloud +service. A missing converter produces an error without changing the project. +Use SVG if you do not want to install or configure the converter. + +AI exchanges layer geometry and optional artwork, not the complete editor project. +Use a `.midra.json` project to preserve all settings. See the +[AI format contract and round-trip checks](../../interfaces/midra-layout-exchange.md#illustrator-ai). diff --git a/docs/templates/midra-layout/README.md b/docs/templates/midra-layout/README.md index 5a1d55b..3baa81a 100644 --- a/docs/templates/midra-layout/README.md +++ b/docs/templates/midra-layout/README.md @@ -30,12 +30,16 @@ Review the detected rectangles and their destination layers before applying. | PowerPoint | [Download .pptx](midra-layout-1080p-2-layers.pptx) | [Download .pptx](midra-layout-4k-2-layers.pptx) | PowerPoint, LibreOffice Impress or DeckCraft | | Figma FIG | [Download .fig](midra-layout-1080p-2-layers.fig) | [Download .fig](midra-layout-4k-2-layers.fig) | Figma or FigCraft | | FigCraft | [Download .figcraft](midra-layout-1080p-2-layers.figcraft) | [Download .figcraft](midra-layout-4k-2-layers.figcraft) | FigCraft | -| Illustrator AI | [Download .ai](midra-layout-1080p-2-layers.ai) | [Download .ai](midra-layout-4k-2-layers.ai) | Illustrator or VectorCraft | +| Illustrator AI (optional) | [Download .ai](midra-layout-1080p-2-layers.ai) | [Download .ai](midra-layout-4k-2-layers.ai) | Requires VectorCraft CLI for Midra import/export; prefer SVG | FIG, FIGCRAFT, DXF and DWG import/export were confirmed working by the user on 2026-11-15. PPTX, draw.io and SVG were previously confirmed; see the [format acceptance list](../../midra-layout/plan.md#confirmed-format-acceptance). +**Prefer SVG when exchanging layouts with Illustrator.** The AI templates remain +available for compatibility, but Midra needs the separately installed VectorCraft +CLI to import or export them. See [AI setup](../../midra-layout/guide/files.md#illustrator-ai-optional-converter-required). + ## Geometry files and saved projects These files exchange visible layer boxes. They do not store the complete editor