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

ParaView adaptor documentation guide

Code snapshot: 2026-10-06. This guide describes Schemaxis's registered ParaView input contract (schemaxis/1), captured against ParaView 5.13.3. A document version is not an upstream application version. Coordinates and field units come from the dataset; no unit conversion is implied.

Reading map#

• Complete operation reference: all 645 identifiers, every input port, option, nested proxy choice, command, output kind, declaration gap, and syntax example.
• Settings and function signatures: complete camera/direction grammar, appearance constraints, and all registered value functions.
• Shared $ language: references, expressions, functions, analytics, inline objects, workflow handoffs and draft placeholders.
• Machine-readable authored schema and expanded schema.
• Catalogue qualification and extensions, parallel execution, and installation.

There are 61 curated interfaces, 535 generated pipeline bindings, five resource bindings and 44 writer bindings. Some expose the same native algorithm. Curated names such as slice use Schemaxis options and defaults; generated names such as pvSlice preserve captured native spelling and usually omit defaults. Capitalisation matters: input and Input are distinct ports.

The operation appendix gives declared syntax examples for every operation and example values for every option. These are not 645 qualified scientific recipes. File readers need real files, filters need compatible fields/data, and native default values can be data-dependent. Where the retained declaration has no human property description, the appendix explicitly identifies the native property assigned rather than inventing a scientific interpretation. coverage.gaps identifies native properties not exposed in authored input.

1. Complete first workflow#

Save this as section.json in the repository root:

{
  "version": "schemaxis/1",
  "nodes": [
    {"id": "data", "filter": "wavelet"},
    {"id": "cut", "filter": "slice", "inputs": {"input": "data"},
     "options": {"normal": [0, 0, 1], "origin": [0, 0, 0]}}
  ],
  "scenes": [{
    "id": "section",
    "geometry": ["cut"],
    "visible": {"cut": {"field": ["POINTS", "RTData"], "legend": true}},
    "measurements": [{"node": "cut", "association": "POINTS"}],
    "images": [{"id": "view", "size": [640, 480],
                "cameras": [{"direction": [1, -1, 1]}]}]
  }]
}

From the repository root, use the CLI's plan, run and verify commands; --help lists their positional arguments and execution flags:

PYTHONPATH=src python3 -m schemaxis plan section.json
PYTHONPATH=src python3 -m schemaxis run section.json --output-directory /tmp/schemaxis-section-new
PYTHONPATH=src python3 -m schemaxis plan --help
PYTHONPATH=src python3 -m schemaxis run --help
PYTHONPATH=src python3 -m schemaxis verify --help
PYTHONPATH=src python3 -m schemaxis describe slice
PYTHONPATH=src python3 -m schemaxis schema --operation pvClip
PYTHONPATH=src python3 -m schemaxis functions

Planning/discovery do not import ParaView. Native execution uses a configured application installation in a separate process. The output directory must be new; the ordinary ParaView runner does not create missing parent directories. ParaView PATH management is unnecessary for authoring or host planning.

flowchart TD
  A[Strict JSON input] --> B[Resolve document references and pure functions]
  B --> C[Compile inline objects and analytics]
  C --> D[Validate graph and publication declarations]
  D --> E[Select scene roots and dependency closure]
  E --> F[Expand active axes and selected times]
  F --> G[Run frozen runtime in native pvbatch]
  G --> H[Update and observe upstream data]
  H --> I[Resolve runtime values and assign validated properties]
  I --> J[Publish requested artifacts]
  J --> K[Read back and verify outputs]
  K --> L[Host verifies plan, lifecycle, membership and hashes]
  L --> M[Verified result and retained evidence]

2. Every top-level input#

JSON uses double quotes, no comments, no trailing commas, no duplicate keys and finite numbers. Unknown keys are rejected by closed contracts. IDs follow [A-Za-z][A-Za-z0-9_-]* and must be unique in their relevant namespace.

Example reuse: "dimensions":{"radius":2} and a sphere option "radius":{"$document":"/dimensions/radius"}.

Node fields and connection syntax#

A single data port accepts "producer" or {"node":"producer","port":1}. Ports are zero-based; a string selects the default output. A multiple port accepts a nonempty array, e.g. {"input":["a","b"]} for curated append. Resource ports accept compatible graph node IDs, not numeric data ports. Authored graph inputs can also use $object and $create; see the shared section.

{"id":"cut","filter":"pvClip","inputs":{"Input":"data"},
 "options":{"ClipType":{"type":"Plane","options":{"Origin":[0,0,0],"Normal":[1,0,0]}},"Invert":false}}

Nested proxy values contain type (a declared choice) and options (that choice's property object). These are typed data, not Python expressions. Generated top-level omitted options use native initialisation; omitted nested options on later visits retain native values. Specify varying nested properties explicitly.

Constructor options, especially reader filenames, are fixed across visits. Native resources preserve identity and participate in invalidation, but cannot be selected for dataset geometry or measurement publication. Data type and array requirements are checked after upstream data updates; host schema validity alone cannot establish those requirements.

Axes and series#

{"axes":[{"name":"offset","series":{"start":-2,"end":2,"count":5}}]}

Use {"$axis":"offset"} in a varying option, e.g. inside a three-element slice origin. values can hold scalars, vectors or objects; select object members with path. Independent active axes form a Cartesian product. Unused axes do not expand a scene's geometry selection. Scene-only expressions may use active geometry axes, not introduce an unrelated presentation axis; use explicit camera lists for camera-only variation.

Series keys: start and end are numeric endpoints, spacing is distance between positions, count is a positive integer, padding is a nonnegative absolute bounds inset, and paddingFraction is a bounds inset fraction from 0 to 0.5. The general series resolver accepts any consistent combination of three of start/end/spacing/count, with optional bounds-derived endpoints. Ordinary standalone axes have no native bounds supplied, so provide enough explicit values. Example: {"start":0,"spacing":0.5,"count":3} produces [0,0.5,1].

Simulation time selection#

{"times":{"source":"case","select":{"values":[0.1,0.5],"tolerance":0.02}}}

The source must exist, have no connected inputs, and have constant options. Schemaxis inspects metadata after configuring it, then resolves the selection and replans. Exactly one selector is required:

No stored times or an empty selection is a fault. Selected times are deduplicated and returned in time order, with provenance. Explicit [0,1] times do not perform this nearest-stored-time selection.

3. Every scene and output input#

Images/glTF require visible objects. Geometry, measurements and explicit exports do not. visible by itself is not a requested output. Geometry/measurement/export entries publish once per selected state. Images/glTF additionally multiply by appearances; PNG count also multiplies by each writer's camera count.

Per state: geometry count + measurement count + export count + appearance count × (glTF enabled + sum of camera counts). Total publications sum each scene's count across its selected visits. Native handles and resources do not become durable cross-workflow artifacts.

Appearance keys#

{"visible":{"cut":{"field":["POINTS","U"],"component":0,"range":[0.01,10],
 "preset":"Cool to Warm","legend":true,"legendTitle":"Velocity","logScale":true,
 "opacity":0.8,"representation":"Surface With Edges"}}}

Field existence and component count are checked natively. Constant observed ranges are widened for rendering. Camera/style runtime expressions resolve after upstream observations. All exact constraints.

Image and camera keys#

Image writer id names the writer; size is [width,height], default [640,480], integer dimensions from 32 to 8192. cameras is a required nonempty array. An empty camera object uses camera defaults.

{"id":"views","size":[800,600],"cameras":[
 {"direction":[1,-1,1],"up":[0,0,1],"parallel":true,"padding":0.2},
 {"direction":"y-","focalPoint":[0,0,0],"distance":20,"scale":5}]}

Rendering sets the native view time to the selected pipeline time. PNG verification decodes the file, checks dimensions/scalars and rejects uniform pixels; it does not independently prove scientific correctness of the chosen colour map. Complete structured direction choices are in the camera signature.

Explicit exports: every key#

{"id":"mesh","node":"cut","writer":"pvWriteXMLPolyDataWriter",
 "options":{"DataMode":"Binary","CompressorType":"ZLib"},"comparison":"exact"}

{"id":"surface","node":"cut","writer":"pvWritePSTLWriter",
 "comparison":"geometry","tolerance":0.000001,
 "acceptLosses":["fields","point-identity","interior-cells","structure"]}

Filenames, timestep selection and file-series controls belong to Schemaxis; do not supply FileName or time-series writer controls. Table exports and JSONImageWriter/HoudiniWriter use direct verifiers and reject a custom readback reader. JSONImageWriter requires pixels comparison. A writer may exist in the catalogue yet fail on a native format or unsupported dataset; explicit verification is mandatory.

Automatic geometry selects the supported VTK XML format for the observed native type (including supported table/composite/specialised types). glTF is a visible scene interchange, not an exact scientific dataset replacement. Measurements contain numeric arrays; they do not preserve arbitrary string columns. Every writer's extensions, defaults, loss contract and options appear in the operation reference.

4. Lifecycle, ordering and invalidation#

flowchart TD
  A[Next selected scene and state] --> B[Retain shared active proxies; delete inactive proxies]
  B --> C[Create missing proxies in dependency order]
  C --> D{Options, time, dependencies or onVisit changed?}
  D -->|yes| E[Resolve values; validate; assign and read back]
  E --> F[Run declared commands in authored order]
  F --> G[Update native data and observe result]
  G --> H[Invalidate downstream consumers]
  D -->|no| I[Reuse existing updated object]
  H --> J[Publish state outputs]
  I --> J
  J --> K[Verify artifacts and retain evidence]
  K --> A

Scene roots include visible nodes, geometry/measurement/export nodes, writer resources and observation/sample dependencies. Only their closure executes. Graph cycles, unknown nodes and incompatible kinds fail. Independent sweeps form products; synchronized analytics zip matching samples. Surviving proxies retain native identity. Effective option changes invalidate the node and consumers. Time changes invalidate selected nodes. onVisit requests force updates and downstream invalidation even if time/options stay equal. At completion proxies are deleted in reverse dependency order.

5. Retained output and evidence#

The ordinary serial runner retains these named files. Common runtime studies and MPI dispatch may wrap results with additional visit/batch evidence; use receipt identities rather than assuming one flat directory layout.

Successful ordinary result keys: status:"succeeded", verified:true, directory (absolute output directory), artifacts (count), planDigest and runtimeSha256. Failed results carry status:"failed", verified:false, directory and fault. Faults identify a stable code, location and available recovery/observation information.

Artifact receipts contain identity (scene, timeIndex, indices, kind and kind-specific selectors), file, sha256, verified, and format-specific verification evidence. Geometry/measurement/export identities add output and node; exports add the export writer ID. Images add appearance, writer and camera indices; glTF adds appearance. Multi-file formats additionally retain member file hashes. Image receipts retain effective camera/appearance and view-time evidence; export receipts retain writer, comparison, tolerance, accepted losses, readback, effective options and resource identity evidence.

flowchart LR
  A[Requested publication] --> B[Write managed file]
  B --> C[Reopen or decode]
  C --> D[Compare selected contract]
  D --> E[Hash file and members]
  E --> F[Native receipt]
  F --> G[Host checks planned identities and lifecycle]
  G --> H[Verified artifact available for handoff]

A file's existence or successful process exit alone is insufficient. Host verification checks publication order/membership, plan digest, states, effective settings, object reuse, update invalidation, commands and file hashes. Do not edit outputs and expect old hashes to remain valid. See native job implementation and publication implementation.

Automatic geometry formats#

Other native types fail automatic publication explicitly. Empty geometry is normally rejected. MPI geometry uses its separate admitted parallel XML publication path.

Native observation output keys#

These are available to $observe and retained in each state's observations map:

Each array record's components is its component count; range is the native range, null for strings or nonfinite/empty ranges. A resource observation instead contains kind, nativeIdentity and inputContracts. Observation metadata is not a full copy of dataset arrays; use $sample for individual numeric tuples.

Example observation access: {"$observe":"data","path":["fields","POINTS","RTData","range"]}.

6. Worked examples and scope#

MPI support is bounded to admitted operations and whole-document constraints; it is not catalogue-wide qualification. Captured domains/metadata and generated bindings do not mean exhaustive native acceptance. The cell-grid probe example explicitly records an unqualified failing native fixture. Plugins/extensions are trusted developer-installed packages, never arbitrary authored import paths. See catalogue scope for extension capture and qualifications.

7. Keeping this guide current#

Regenerate the operation/settings appendices from current host declarations:

PYTHONPATH=src python3 tools/generate_paraview_guide.py

Then review this narrative against schema.py, publication.py, writers.py, job.py, pipeline.py, adaptor_runtime.py, and the shared authoring code. Generation does not launch ParaView or certify native algorithms. Native testing requires independently selected fixtures and readback evidence.