Documentation / user-guide.md
Core 11629ae · View or edit Markdown on GitHub ↗

Schemaxis user guide

For a completed OpenFOAM-format CFD case, use the dedicated CFD post-processing tutorial, with reusable inputs, execution order, filters, camera windows and numerical exports.

Schemaxis describes application work as JSON, runs it through bounded native adaptors, and retains editable outputs and evidence. The package and executable are named Schemaxis: use python3 -m schemaxis or the installed schemaxis command. The schemaxis console command also accepts schemaxis schemaxis as a subcommand alias. The terminal and browser consoles use the same durable session model.

This guide covers the current implementation. Use discover, describe, schema --help and console help from your checkout for exact available contracts. The adaptors expose declared subsets of their native applications; a registered operation is not a guarantee that every native property or workflow is supported.

New here? Follow the ten-minute walkthrough first and enable editor completion and validation.

Contents#

1. Choose a working mode
2. Set up and complete a first run
3. Understand JSON input
4. Validate: schema, plan, run and verify
5. Choose a document family
6. Reuse values, vary parameters and select times
7. Connect jobs and run them in parallel
8. Use the terminal console
9. Configure native applications and manage documents
10. Use the visual console
11. Save, recover and verify work
12. Troubleshoot
13. Find deeper documentation

1. Choose a working mode#

Use a JSON run when you need a repeatable, checked publication. Use the console when developing a document interactively, then save its authored JSON for batch execution. A live checkpoint has its own, narrower verification scope: it does not automatically acquire the batch adaptor's independent-reopening guarantees. Neither console is an unrestricted Python interpreter or a general natural-language modelling agent.

2. Set up and complete a first run#

Host and native applications#

The host requires Python 3.10 or newer and has no third-party runtime Python dependencies. From the repository root, use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
export PYTHONPATH=src
python3 -m schemaxis --help
python3 -m schemaxis discover

Optionally install the checkout in editable mode within that environment:

python3 -m pip install -e .
schemaxis --help
schemaxis console --help

Installation may need the build tools declared in pyproject.toml. The checkout form with PYTHONPATH=src avoids that installation step. All examples below use python3 -m schemaxis; installed users can substitute schemaxis.

Native applications are separate installations. Registered runtime families include ParaView 5.13.3, Blender 5.2.2, FreeCAD 1.1.x, Godot 4.x and Aseprite 1.3.x, plus FFmpeg/FFprobe and QGIS Python. Discovery reports declared requirements, not whether an installation is available. Supply explicit absolute locations for reliable reproduction:

See installation for numerical, structural, workbook and other runtime setup.

Replace /absolute/path/to/... placeholders with your installation. Run repository examples from the repository root. Some use relative resources; case/import templates may contain machine-specific paths that must be changed.

First batch publication#

python3 -m schemaxis query examples/schemaxis/freecad-bracket.json
python3 -m schemaxis plan examples/schemaxis/freecad-bracket.json
python3 -m schemaxis run examples/schemaxis/freecad-bracket.json \
  --freecad /absolute/path/to/freecadcmd \
  --output-directory evidence/my-first-bracket
python3 -m schemaxis verify evidence/my-first-bracket

For standalone adaptor runs, choose a new output directory with its parent already present for portability. Workflow runs create missing parents and also accept an existing empty directory. Do not reuse an old run directory by deleting individual receipts or artifacts. Workflow --resume is described later.

Require successful verification under the adaptor's contract, then open the native model or image and check that it is what you intended. Keep the complete output directory: input, plan, logs, receipts and companion resources matter. Verification establishes declared checks, not engineering correctness, manufacturability or subjective visual quality.

First console session without native execution#

python3 -m schemaxis console --workspace .schemaxis-guide

At the schemaxis> prompt:

rectangle profile 80 50
extrude plate profile 6
inspect plate
save plate-intent.json
status
quit

The default provider is FreeCAD. These commands retain authored intent without launching FreeCAD. Console inspect shows authored data, not native topology. Saving JSON saves intent, not an FCStd model.

3. Understand JSON input#

Use ordinary JSON: double-quoted strings, no comments or trailing commas, and finite numbers. Avoid duplicate keys. A typical graph node is:

{"id":"rounded","filter":"bevel","inputs":{"input":"box"},"options":{"width":0.1,"segments":3}}

id is your identifier; filter names a declared operation. inputs connects named ports to other nodes; options configures the operation. Names are case-sensitive and provider-specific. FreeCAD cut uses base and tool, whereas Blender boolean uses input and operand.

Omitted options use declared defaults; null is not a request for a default. Unknown keys and wrong types are errors. Write 3, not 3.0, for an integer option. A JSON boolean is not a number.

Do not copy one family's root keys into another. Assemblies have no modelling node graph; Godot and Aseprite do not use ParaView's scenes/axes contract. ParaView/Blender graphs can resolve forward references and prune unused nodes. FreeCAD inputs must refer to earlier nodes; Godot materials precede their consumers; Aseprite mutations form one linear chain. Use each family's planner.

4. Validate: schema, plan, run and verify#

There are three layers. Passing an earlier layer does not replace a later one.

Export a schema for your input#

The public schema CLI exports JSON Schema Draft 2020-12 without starting native applications. --all means the eleven Schemaxis CLI document versions in the table above. It does not cover the retained python3 -m schemaxis.adaptors.paraview.mvp parser's distinct documentVersion / resources / steps / outputs format.

# All eleven Schemaxis document versions, authored syntax by default:
python3 -m schemaxis schema --all > schemaxis-authored.schema.json

# One exact document version, including its supported authoring conveniences:
python3 -m schemaxis schema --version schemaxis.freecad/1 --authored > cad.schema.json
python3 -m schemaxis schema --version schemaxis.workflow/1 --authored > workflow.schema.json

# Expanded/literal input instead of authored composition:
python3 -m schemaxis schema --all --expanded > schemaxis-expanded.schema.json
python3 -m schemaxis schema --provider blender --expanded > blender.schema.json

# A particular option dictionary, not a complete document:
python3 -m schemaxis schema --provider blender --operation bevel > bevel.schema.json
python3 -m schemaxis schema --section camera > camera.schema.json

--authored and --expanded are mutually exclusive. Without --all, the default is expanded input. Select --version when the provider alone is ambiguous, for example FreeCAD features versus FreeCAD assemblies. An authored schema admits only the authoring constructs supported by that document family; it is not permission to use every marker everywhere.

--expand is a different action: it expands an input file, rather than selecting a schema dialect:

python3 -m schemaxis schema --expand design.json > expanded.json
python3 -m schemaxis plan design.json

Configure your editor or external validator to associate the appropriate schema with the file; see ready-to-use editor settings. Do not insert a $schema property into Schemaxis input: closed root contracts reject unknown keys. Schema defaults are annotations; Schemaxis applies its own declared defaults. JSON Schema considers 3.0 an integer value, whereas Schemaxis integer options require an integer token such as 3.

Reference existence, cycles, resolved expression values, cross-option relations, active axes, time availability, publication budgets and native capabilities need the planner or runner. x-schemaxis-checks and related metadata are not additional standard JSON Schema keywords that an external validator automatically enforces. See the schema guide for exact exports and native guards.

Schemas describe the active declaration registry. An example that needs a trusted ParaView extension capsule can be rejected by a stock schema until that capsule is configured and the schema is regenerated. Exporting the schema does not load or qualify the native plugin. Duplicate keys, non-finite numbers and expansion limits also remain parser checks, not guarantees supplied by an editor's schema.

For an optional command-line schema check, install jsonschema in your development virtual environment (python3 -m pip install jsonschema). After exporting schemaxis-authored.schema.json as above, run this Python snippet from the directory containing that schema and your design.json:

import json
from pathlib import Path
from jsonschema import Draft202012Validator
from schemaxis.core.documents import load_document

schema = json.loads(Path("schemaxis-authored.schema.json").read_text())
document = load_document(Path("design.json").read_text())
if not Draft202012Validator(schema).is_valid(document):
    raise SystemExit("Schema check failed; inspect editor diagnostics and run schemaxis plan.")
print("Structure accepted. Run schemaxis plan before native execution.")

The Schemaxis package must be installed or PYTHONPATH=src set for its strict input loader. This optional validation package is not needed for normal Schemaxis planning, execution or schema export.

Plan before running; retain the evidence#

python3 -m schemaxis describe --provider freecad
python3 -m schemaxis query design.json
python3 -m schemaxis plan design.json
python3 -m schemaxis run design.json --freecad /absolute/path/to/freecadcmd \
  --output-directory evidence/design-001 --timeout 300
python3 -m schemaxis verify evidence/design-001

describe is the operation catalogue; query reports the document's declared requirements. Neither proves that your native installation satisfies them. plan does not load the native application. run creates the publication and its evidence; verify checks an existing evidence directory under its adaptor contract. Read the structured fault and native log if either fails. A PNG alone, or a native process exiting with code zero, is not a verified job.

5. Choose a document family#

The following starter documents are complete inputs unless marked as fragments or templates. Save one to a JSON file and run plan first. Longer examples are linked for features that need more context.

FreeCAD: constrained sketch to solid#

{
  "version": "schemaxis.freecad/1",
  "units": "mm",
  "nodes": [
    {"id": "profile", "filter": "rectangle", "options": {"width": 80, "height": 50}},
    {"id": "plate", "filter": "extrude", "inputs": {"profile": "profile"}, "options": {"length": 6}}
  ],
  "output": "plate"
}

FreeCAD dimensions are millimetres. Rectangle and circle operations construct declared constrained sketches; this does not imply arbitrary polygon sketches are fully constrained. The console permits a sketch-only draft and can display its native edges with zero triangles. A batch feature publication requires a solid output. The standard batch artifacts are model.step, model.stl and model.FCStd in that order; the editable native document is the last of these.

Boolean features use named inputs, for example cut has base and tool. Edges used for fillets or chamfers are one-based native topology selections; inspect the current shape rather than assuming an old Edge number survives an edit. CLI native inspection is different from console authored inspection:

python3 -m schemaxis inspect examples/schemaxis/freecad-bracket.json --node blank \
  --freecad /absolute/path/to/freecadcmd --output-directory evidence/bracket-inspect

linearDeflection controls tessellation, not CAD dimensions. See the bracket, flange and CAD/mesh guide.

FreeCAD assembly: components and fixed joints#

Assemblies use schemaxis.freecad.assembly/1, not a feature-node graph. The complete assembly example declares reusable box/cylinder parts, component instances, one grounded component, and a rooted tree of fixed joints. Joints identify parent/child component connectors using top or bottom; offsets are in the parent component frame. Component rotation is a yaw angle in degrees. These are bounded native fixed-joint assemblies, not a general kinematic mechanism or arbitrary joint solver.

python3 -m schemaxis plan examples/schemaxis/freecad-assembly.json
python3 -m schemaxis run examples/schemaxis/freecad-assembly.json \
  --freecad /absolute/path/to/freecadcmd \
  --output-directory evidence/assembly-001

Optional --freecad-gui /absolute/path/to/FreeCAD enables the supported GUI evidence path. In the console, open the assembly JSON and edit complete fields with set document; feature-node commands and live assembly execution are not supported. Assemblies are not workflow child documents. See FreeCAD assemblies.

ParaView: data pipelines and publications#

{
  "version": "schemaxis/1",
  "nodes": [{"id": "ball", "filter": "sphere", "options": {"radius": 2}}],
  "scenes": [{
    "id": "view",
    "visible": {"ball": {"colour": "steelblue"}},
    "images": [{"id": "front", "size": [640, 480], "cameras": [{"direction": [1, -2, 1]}]}]
  }]
}

Run with --paraview-root /absolute/path/to/ParaView. Nodes connect scientific datasets to declared filters. A scene's visible object maps node names to appearance settings; geometry and image publications are explicit. Use describe --provider paraview for readers, filters and their exact option names. For example, the OpenFOAM reader uses file, while some mesh readers use a files array: do not interchange them.

Scalar colouring needs the correct array name and point/cell association from the actual data. A generated catalogue entry does not guarantee a plugin exists in every ParaView build. Source-time selection requires discrete native TimestepValues; static sources do not acquire time steps merely because a times section is present. Decomposed-case reading by a serial process is not the same as distributed MPI execution.

Blender: editable meshes and rendered scenes#

{
  "version": "schemaxis.blender/1",
  "nodes": [
    {"id": "paint", "filter": "material", "options": {"colour": [0.1, 0.4, 0.8, 1]}},
    {"id": "block", "filter": "cube", "options": {"size": 2}, "inputs": {"material": {"$object": "paint"}}}
  ],
  "scenes": [{
    "id": "view",
    "visible": ["block"],
    "images": [{"id": "front", "size": [640, 480], "cameras": [{"direction": [1, -2, 1]}]}]
  }]
}

Run with --blender /absolute/path/to/blender. Blender uses a visible list, not ParaView's visible/style mapping. Material colours use floating-point RGBA; the console material example below shows object-reference input syntax. The pipeline supports one scene and one image publication containing multiple cameras. CPU is the default rendering path; requesting CUDA or OPTIX does not silently fall back when the requested backend is unavailable.

Transform rotations are XYZ degrees; bend/twist angles have their own declared radian units. Modifier distances operate in object-local coordinates. Bake transforms when you need those distances in the transformed geometry's units. join is not a solid Boolean union. Requested mesh publications are evaluated world-coordinate STL; STL itself carries no unit metadata. A CAD millimetre to metre handoff commonly requires an explicit 0.001 scale.

Use prepareOnly for the supported scene-preparation path; its input still requires the declared publication/camera configuration. See the mesh workshop and CAD/mesh guide for modifiers and handoffs.

Blender saved-scene render#

schemaxis.blender.render/1 renders a prepared Schemaxis .blend instead of rebuilding a node graph. Its root contains sceneFile, cameras, and optional render and size. Use an absolute native scene path, or a workflow artifact reference. This is not an arbitrary .blend automation interface: the runner requires Schemaxis's saved scene metadata and a supported self-contained scene. Linked libraries and unpacked external images are rejected by the batch contract.

See render groups for a complete preparation/render workflow. Keep the preparation receipt to identify the exact scene artifact rather than guessing a filename or artifact index.

Godot: editable 3D projects#

{
  "version": "schemaxis.godot/1",
  "units": "m",
  "nodes": [
    {"id": "paint", "filter": "material", "options": {"colour": [0.12, 0.42, 0.85]}},
    {"id": "block", "filter": "box", "options": {"size": [2, 1, 1]}, "inputs": {"material": "paint"}},
    {"id": "view", "filter": "camera", "options": {"position": [6, 4, 8], "target": [0, 0, 0]}},
    {"id": "sun", "filter": "directionalLight"}
  ]
}

Run with --godot /absolute/path/to/godot. Godot uses metres and a Y-up scene. Materials must precede their consumers; every declared material must be used. A complete scene requires geometry and exactly one camera. Declared primitives, materials, light, orbit camera and a restricted .gltf import are supported, not arbitrary GDScript, physics or general transform hierarchies.

Keep the whole generated project, including project.godot, scene.tscn and the supplied orbit script. Default execution is headless. Root "preview": true requests an actual native PNG through the isolated Xvfb/OpenGL path and needs its system prerequisites, including xvfb-run. Console drafts may be incomplete, but preview requires a complete scene. No retained live client, CLI inspect, workflow child or single-file native save is offered for this provider. See Godot and primitives.

Aseprite: pixel art and animation#

{
  "version": "schemaxis.aseprite/1",
  "nodes": [
    {"id": "canvas", "filter": "sprite", "options": {"width": 8, "height": 8}},
    {"id": "square", "filter": "rect", "inputs": {"sprite": "canvas"}, "options": {"layer": "base", "x": 1, "y": 1, "width": 6, "height": 6, "colour": [30, 130, 230, 255]}},
    {"id": "cutout", "filter": "circle", "inputs": {"sprite": "square"}, "options": {"layer": "base", "x": 3, "y": 3, "radius": 1, "colour": [0, 0, 0, 0]}}
  ],
  "output": "cutout"
}

Run with --aseprite /absolute/path/to/aseprite. The sprite graph is one linear mutation chain. Pixel coordinates start at zero; authored frame numbers start at one. Colours are integer RGBA channels: the declared subset supports opaque pixels or fully transparent black, not arbitrary partial alpha. Appending a frame creates an empty frame; it does not implicitly copy the preceding one.

Outputs include sprite.aseprite, a first-frame composite preview.png, a horizontal sheet.png and sheet.json. Layers, frames, palette changes and tags have declared operations; arbitrary Lua, indexed modes, layer groups, blend modes, fonts and general imports are not implied. There is no live client, CLI inspect or workflow-child support. See Aseprite and animation.

FFmpeg and QGIS#

Use media workflows for video from PNG sequences or sprite sheets, and the QGIS guide for the supported vector pipeline. These families accept literal inputs and explicit workflow artifact handoffs. Their options and verification contracts differ from ParaView and Blender graphs.

6. Reuse values, vary parameters and select times#

Start with a literal document. Add authoring conveniences only where the selected family supports them; use schema --authored, schema --expand and plan to inspect what they mean. The JSON input guide and human input guide cover the full syntax.

For example, the following is an option-value fragment, not a whole job:

{"$document": "/dimensions/plateThickness"}

Place the number in the root dimensions object and use that reference for a supported option. $document uses document paths, not filesystem imports. definitions and settings can retain reusable authored data. Pure $expr operations and registered $value functions compose values without running arbitrary Python. List the declared functions with python3 -m schemaxis functions. Inline $create / $object construction and $analytic sequences are separate authoring tools, not interchangeable with native reference chips in the console.

ParaView and Blender axes describe parameter visits. Values sharing an axis advance together; independent active axes form a Cartesian product. Unused axes do not justify executing unused branches. Increasing two independent counts can multiply the work: check the plan's visits and publication budget first.

Analytic camera sequences are useful for repeatable views. This fragment produces three orbit directions in a supported cameras position:

{"$analytic": {"type": "orbit", "start": 30, "end": 150, "count": 3, "elevation": 25}}

Camera direction points from the focal point towards the camera. Shared camera names do not erase native differences: ParaView's parallel scale is a vertical half-height, while Blender's orthographic scale is a horizontal full width. Use the generated settings reference rather than transferring numbers blindly. Browser orbit/walk controls do not edit these authored cameras.

For time-dependent ParaView input, choose from times actually exposed by native sources. Blender visit times are explicit, not discovered OpenFOAM times. See parallel timesteps for a complete example. Plan-time acceptance does not prove a reader has the requested native time or array; those checks occur when the application loads the data.

7. Connect jobs and run them in parallel#

A schemaxis.workflow/1 document lists named operations, each containing a child document. Supported child versions are exactly schemaxis/1, schemaxis.freecad/1, schemaxis.blender/1, schemaxis.blender.render/1, schemaxis.godot/1, schemaxis.aseprite/1, schemaxis.ffmpeg/1 and schemaxis.qgis/1. FreeCAD assemblies remain standalone. See media workflows and QGIS.

An artifact reference is an input-value fragment:

{"$artifact": "surface", "index": 0}

It selects the zero-based publication index of an earlier operation named surface. It is not a filename glob. Artifact type and consumer restrictions still apply. Inspect the producer's plan and receipts: enabling images or mesh publications can change which artifact an index denotes. A FreeCAD batch feature job publishes STEP at index 0, STL at index 1 and FCStd at index 2; choose the format the next reader actually accepts.

Try the complete ParaView-to-Blender workflow:

python3 -m schemaxis plan examples/schemaxis/paraview-to-blender.json
python3 -m schemaxis run examples/schemaxis/paraview-to-blender.json \
  --paraview-root /absolute/path/to/ParaView --blender /absolute/path/to/blender \
  --output-directory evidence/handoff-001
python3 -m schemaxis verify evidence/handoff-001

The direct CAD handoff and Blender-to-ParaView workflow show other supported boundaries. Handoffs do not preserve every material, unit, topological identifier or external dependency across formats.

Workflow root execution budgets constrain concurrent workers, CPUs, memory and GPU slots. Per-operation execution requests threads, ranks and other declared resources. Memory budgets are scheduling estimates, not operating-system memory limits. GPU scheduling is bounded to the supported slot model, not a cluster scheduler. ParaView MPI is an explicit supported subset and requires a suitable MPI launcher; more than one rank is not automatically valid for every pipeline. See parallel execution before enabling concurrency.

New workflow runs accept a nonexistent or empty output directory and create missing parents automatically. Files, symlinks and directories containing any entries (including hidden files) are refused without replacing retained results. An exclusive authored-input record reserves the destination before execution.

Use run ... --resume only for the supported workflow path, with the unchanged workflow and the same output directory. Resume rechecks retained evidence; it does not mean “trust any files already there”. A failed standalone run is not made resumable by adding this flag. Preserve failure logs and choose a fresh output directory when changing the job.

8. Use the terminal console#

Start a durable workspace from your shell:

python3 -m schemaxis console --workspace .schemaxis

An existing workspace restores its documents; the initial --provider default does not replace them. At the console prompt enter console commands, without the python3 -m schemaxis prefix. Commands use shell-style quoting but do not run a shell. Enclose JSON arguments in single quotes and paths containing spaces in quotes. # begins a comment outside quotes.

Build and edit a plate#

new "Plate design" freecad
rectangle profile 80 50
extrude plate 6
inspect plate
set plate length 8
preview
save "plate-intent.json"
undo
redo
status

rectangle selects its new profile, so extrude plate 6 uses that selection. Use extrude plate profile 6 to name it explicitly. set plate length 8 edits the extrusion's declared length, not an arbitrary native property. With no configured executable, preview produces a plan checkpoint, not a native model.

For a hole through the plate, continue with:

circle hole 3
add bore extrude '{"length":10}' '{"profile":"hole"}'
add cut cut '{}' '{"base":"plate","tool":"bore"}'
show cut
inspect cut

Each candidate edit is validated before becoming the authored document. Remove consumers before removing nodes they depend on. Undo/redo restore authored content but advance the workspace revision; they do not make old picks current. The bounded sentence draw a rectangle 80 x 50 mm centred on the origin is also recognised. This convenience is not general natural-language modelling.

Command reference#

Aliases include ls for list, ? for help and rect for rectangle. quit/exit are terminal-loop controls, not remote browser command jobs.

Other provider drafts#

The console uses provider-specific declarations, not one universal node grammar:

new "Mesh design" blender
add paint material '{"colour":[0.1,0.4,0.8,1]}'
add cube cube '{"size":2}' '{"material":{"$object":"paint"}}'
preview
new "Game scene" godot
add paint material
add block box '{}' '{"material":"paint"}'
add camera camera
preview
new "Pixel sprite" aseprite
add canvas sprite '{"width":16,"height":16}'
preview

Blender/ParaView draft graphs may lack publications; the first renderable node creates a default scene. Resources do not automatically become visible. ParaView does not automatically add image publications. preview still needs a complete provider publication plan. For assemblies, open the assembly JSON and replace whole parts, components or joints fields instead of using add.

Editing, history and scripted commands#

On a real terminal, optional standard-library readline supplies line editing, Up/Down history and Tab completion for commands, node IDs, document UUIDs and providers. The latest 500 command-history entries persist in the workspace. Platforms without readline use plain input. Console history is the separate authored edit history, not the input-line history.

For repeatable host-only authoring, pass multiple --command options from the shell. They execute in order and print results, then exit unless --web is set:

python3 -m schemaxis console --workspace .schemaxis-scripted \
  --command 'rectangle profile 80 50' \
  --command 'extrude plate 6' \
  --command 'save plate-intent.json'

Use a new workspace for that exact example: replaying it into an existing document can conflict with its node IDs. Paths are resolved by the server/console process, not by a browser file picker. open accepts authored Schemaxis JSON; it does not import an arbitrary .FCStd, .blend or native GUI session.

9. Configure native applications and manage documents#

Configuration and a running connection are different states. The following commands retain locations without changing the active document:

configure freecad /absolute/path/to/freecadcmd
configure blender /absolute/path/to/blender
configure paraview /absolute/path/to/ParaView
configure godot /absolute/path/to/godot
configure aseprite /absolute/path/to/aseprite

Executable locations must be absolute executable files; ParaView also accepts an installation root. Configuration is persisted in the workspace. connect is the active-provider convenience. Do not confuse the FreeCAD batch command-line launcher with the GUI-capable launcher used for live:

provider freecad
live /absolute/path/to/FreeCAD
preview
geometry
image

Live clients are supported for FreeCAD feature documents, Blender and ParaView. Godot, Aseprite and FreeCAD assemblies use the supported batch preview path. For ParaView live work, use its supported Python executable or installation root; a generic Python interpreter is not a replacement.

Multiple documents can retain independent native clients and caches. Switch with the UUID returned by status or the browser document list. provider freecad does not guarantee selection of a particular FreeCAD document when several exist; use its UUID. unload affects the active client's residency and geometry, not the authored document or saved provider configuration. disconnect also removes the active provider configuration; other documents' retained clients are not globally torn down.

The authored document remains the source of intent. Editing the native GUI does not reverse-synchronise its changes into JSON. When native state diverges, geometry/reference guards can reject it, and an uncertain client may be discarded. Re-establish the intended state with a new supported live preview; do not treat the last mesh still on screen as current.

10. Use the visual console#

Start and connect#

python3 -m schemaxis console --workspace .schemaxis --web --port 8765

Open the printed loopback URL, including its ?token=... query. Omitting --port uses an available port. The token authorises local API requests; do not publish it, place it in documentation, or expose this server through an untrusted network proxy. The server binds locally and is not a multi-user hardened service. Closing the browser tab does not stop the console server. Stop it from its owning terminal when finished; shutdown also requests active-operation cancellation.

The panels show the workspace/documents, native 3D geometry, current PNG, command history and a rich request composer. The command log scrolls internally and retains expandable details; a large JSON result should not need to displace the viewport. On smaller displays, scroll the page/panels to reach the composer.

Enter the same console commands in the command field. live, followed by preview, provides supported native geometry. A batch screenshot and a live tessellation are distinct capabilities: a valid PNG does not imply a 3D mesh is available. If WebGL is unavailable, the 3D viewer cannot render; the textual console and other available panels remain useful.

Orbit, section and walk through geometry#

Focus the viewport before using navigation keys. Walk permits movement past surfaces and into interiors; it has no collision or physical clearance model. Section clipping removes geometry beyond the selected plane for display and picking; it does not create a new CAD cut, cap face or referenceable surface. These controls change the browser view, not the authored geometry or native publication camera. Use Fit if you lose the model.

Native edge polylines and vertices are rendered as well as face triangles. A fresh sketch can therefore be a real native wire loop with zero triangles. An empty triangle list alone does not mean that no geometry exists.

Compose a sentence with exact references#

1. Place the caret where the reference should appear in the request composer.
2. Click a visible native face, edge or vertex, or choose an available element from the element list. The pick is checked against current native geometry.
3. The returned reference is inserted as an atomic chip at the retained caret. Its readable label identifies the object/element; details retain the exact point, units, document and revision.
4. Continue typing around the chip, or type @ to reuse an existing reference. Use the chooser's arrows and Enter/Tab; Escape dismisses it.
5. Select Save request to retain the sentence and reference segments.

For example, type “Increase the clearance beside ”, pick a face, then finish “ while preserving the outside dimensions.” The chip might identify refA and plate.Face1; it is not editable prose pretending to be a reference. Backspace or Delete next to a chip removes the whole token. Merely typing refA into ordinary text does not create a reference segment.

Face points are native tessellation picks, edge points lie on native segments, and vertex picks retain native points. They are revision-bound selections, not permanent topological names. Hidden/clipped geometry is not a shortcut for inventing a pick. If only a previous-revision mesh is available, the UI can retain it for context but blocks current picking.

Refer to a PNG pixel honestly#

Click within the drawn image, not the blank margins around it. The browser maps the contained image rectangle back to integer native pixels, with (0, 0) at the top left. The reference retains image size, px units and the exact PNG digest. It says “image preview pixel (x,y)”, not “CAD face at this screen point”. An Aseprite preview pixel is not automatically a particular layer or authored animation frame; it references the displayed image.

Image metadata is fetched before loading the digest-bound PNG. If the current image/document changes during a pick, stale selection is rejected. Zooming the browser or resizing the pane does not change the underlying pixel coordinate system. PNG and 3D references can coexist in the same composed sentence.

Staleness, drafts and saved requests#

Model edits advance the revision. Old chips are visibly stale, and saving a request containing stale references is disabled. Refresh the native preview and replace/re-pick the affected references; undo does not make an old revision current again. Image references additionally depend on the exact PNG digest. The server also guards against native GUI divergence before accepting model references.

Saving captures the composer document UUID, current revision and segments together. A delayed response must not attach prose to a different document after you switch. Saving a request retains intent only: it does not execute arbitrary natural language, modify the model or submit the sentence as a console command.

The collapsible saved-requests section lets you revisit retained requests and their reference details. Restore brings a request back into the matching document's draft; it is not re-execution and does not refresh old references. Historical saved requests retain their original identity and revision.

Unsaved drafts are retained per document in browser local storage, using workspace/document identity and plain text/reference-ID segments, never the authentication token. Switching documents and reloading the same origin can recover them. Browser storage is not a backup: clearing it, private browsing, another browser, or a different port can make a local draft unavailable. Use a stable port if you rely on reload recovery, and save important requests to the server workspace. Saved requests and authored JSON are separate records; save design.json does not embed the request history.

Long-running commands and Cancel#

Submitting a command starts a job. The UI polls that job until it succeeds or fails and exposes expandable result/fault details. Avoid submitting the same edit again merely because it is slow. If the UI offers Refresh to resume polling, it follows the existing job rather than creating another one.

Cancel current operation requests cancellation of the active job, disables repeat cancellation and continues polling until the final result. Cancellation is not an undo or an immediate success response. An operation can finish before the request takes effect. Uncertain native state after cancellation or timeout may cause the affected client to be discarded; the authored document and previous verified checkpoint remain separately tracked. Read the final status before previewing or saving again.

See visual console for the detailed UI/API contract.

11. Save, recover and verify work#

Know what is being saved#

Native save is not “copy whichever file was written last”. The console checks document identity, revision, authored digest, receipt, artifact digest and containment. After an edit, run a successful matching native preview before saving native output. Existing destination files are not overwritten; choose a new name. If several native artifacts are plausible, an ambiguity fault is safer than silently choosing the wrong one.

A native file can still depend on other files. ParaView state may refer to external datasets; a live Blender scene can depend on external resources. Keep the evidence directory and dependencies, not just a renamed native file.

Batch evidence and live evidence are different#

Batch adaptors perform their declared native publication/reopen checks. Live snapshots have deliberately narrower scopes. In particular, a FreeCAD live snapshot's nativeLiveSnapshot scope records independentReopen: false; ZIP/XML container and digest checks are not an independent geometric reopen. Live Blender checks native library/object/material membership, and live ParaView checks state/proxy membership, not an independent reload of every dataset. Read the actual receipt scope rather than assuming all previews are equivalent.

For reproducible release evidence, save authored JSON and run the appropriate batch job into a fresh directory, then verify it. Do not describe a successful live screenshot as a full native qualification of every feature.

Workspace recovery#

The workspace retains documents, edit history, provider configurations, checkpoint provenance, references and saved requests. Session persistence uses a checksum and an advisory workspace lock. Only one console should own a workspace at a time. Do not delete a lock file to bypass a running owner.

After restart, the authored documents and retained evidence are available, but live native processes and geometry caches are not silently resurrected. Start the required live client and preview again. Interrupted attempts are recorded as interrupted, not successful. A failed retry does not turn the last successful checkpoint into a success for a different revision; check both the latest attempt and the last successful preview.

If persistence reports an error with published: true but durable: false, some state may already have been published. Inspect/reconcile the workspace before blindly retrying the action. Preserve a damaged workspace for diagnosis rather than editing its checksum or deleting receipts. Back up the complete workspace and external publication directories when they contain work you need to retain.

12. Troubleshoot#

Start with the fault code/message and the affected document/revision. Expand the browser result details, inspect status/artifacts, or retain CLI stderr and native logs. Do not assume that the most recent visible image is current.

Do not “fix” a failure by inventing geometry, changing a receipt, pretending an image pixel is a surface, or silently falling back to a different execution mode. If a capability is outside the declared subset, retain the input and fault and use the native application directly or request an explicit adaptor extension.

13. Find deeper documentation#

• JSON input: authoring syntax and document examples.
• Schema guide: exact export modes, validation boundaries and native guards.
• Human input: dimensions, settings and reusable authoring constructs.
• Console: session commands, persistence and live/batch behaviour.
• Visual console: viewer, composer, references and API.
• Console audit: tested behaviour and remaining boundaries.
• CAD and mesh workflows: native geometry and format handoffs.
• FreeCAD assemblies, Godot, Aseprite: provider-specific contracts.
• Parallel execution: scheduling, time chunks, MPI and resume.
• Example inputs: complete jobs; check resource paths before execution.

For declarations matching your checkout, use schemaxis discover, schemaxis describe --provider PROVIDER, schemaxis schema --help, schemaxis functions and schemaxis colours. schemaxis reference --check checks generated reference drift; it does not qualify an installed native application.