Workflow problem
A loosely documented visualization session can lose native-time mappings, field meanings, thresholds, units, camera choices, and the boundary between source data and generated media.
Linux scientific-visualization CLI
VisualOpenFOAM
A Linux-first CLI for turning OpenFOAM and VTK data into reproducible Blender scenes and field reports.
An inspect → manifest → plan → render/export workflow that preserves field meanings, native times, units, transforms, and camera intent across tools.
Workflow
Preserve scientific intent along the OpenFOAM → VTK → Blender or field-report path.
Scientific visualization on Linux often crosses case files, VTK exports, Python analysis, and headless rendering. The contribution is a command-line workflow that carries scientific intent and field semantics between those tools.
Engineering contribution
VisualOpenFOAM inventories inputs, serializes scientific intent, exposes dry-run plans, and uses exact commands, opt-in execution, and fail-closed readers before any external process starts.
Inspectcase, regions, arrays, times
Manifestsemantics, units, capabilities
Plantransforms, cameras, output paths
Render/exportBlender scenes, figures, field reports
Current capabilities
The CLI, schemas, dry-run planning, tests, and synthetic examples are in place.
Ten non-interactive commands cover case inspection, versioned manifests, field and Blender plans, contract checks, and small reference outputs. Dry-run planning remains the default.
Inspect
Case and VTK-family inventories keep numeric native times, field headers, regions, dimensions, meanings, and detected backends explicit.
Plan
JSON-serializable field and Blender plans expose transforms, cameras, native-time mappings, output paths, timeouts, and exact argv before execution.
Test and preview
Twenty-one pytest checks, six meta-validated schemas, deterministic dry runs, a labeled SVG, and one tiny 128 × 128 Blender smoke image cover the current alpha.
Example outputs
External case figures show the scientific context the workflow must preserve.
These figures come from the companion rectangular-slot case study and illustrate the geometry, fields, units, and native-time semantics the readers are designed to preserve.
Developer notes
Schemas, safeguards, and an alpha quickstart.
Implementation details remain available here without interrupting the overview, workflow, capabilities, and examples above.
Open developer notes: schemas, safeguards, and commands
Inputs and readers
Tool discovery reports available backends. Executable examples currently use synthetic fixtures and dry-run plans; real OpenFOAM and VTK readers are the present development focus.
| OpenFOAM case | Read-only inventory of numeric native times, field headers, regions, dimensions, and field meanings |
|---|---|
| VTK family | Exported PVD, VTU, and VTP routes with explicit array, time, unit, and coordinate checks |
| Synthetic fixture | Tiny non-physical metadata fixture for deterministic execution and CI |
| Capability detection | doctor reports Python, Blender, ffmpeg, OpenFOAM utilities, pvpython, VTK, and optional PyVista |
| Reader safeguards | Fails closed unless a reader adapter provides regions, arrays, units, native times, checksums, and timeouts |
Contracts, manifests, and overwrite behavior
Versioned case, field, Blender, command-result, and report documents retain deterministic ordering, SHA-256 checksums, scientific labels, native times, coordinate and unit checks, command results, captions, and reproduction notes.
Outputs use explicit paths and refuse overwrite unless --overwrite is supplied. Rendering and field execution require --execute; planning starts no Blender, OpenFOAM utility, or solver process.
Tests and data boundaries
The test suite exercises contracts and process boundaries with tiny synthetic fixtures rather than a bundled real case.
| Version | 0.1.0a1 |
|---|---|
| CLI | 10 non-interactive commands with stable exit meanings |
| Tests | 21 pytest checks; CI runs the test suite, contract validation, and source/data-boundary checks |
| Contracts | Six Draft 2020-12 JSON Schemas meta-validated |
| Dry runs | Field and Blender plans start no external process |
| Preview outputs | Labeled SVG and one tiny 128 × 128 Blender smoke image |
| Source/data boundary | 67 files checked; raw CFD fields, media, frames, .blend files, and credentials excluded |
Execution safeguards
The suite covers containment, symlink components, special files, explicit overwrite, asset-root escape, missing executables, timeouts, and diagnostic redaction. Subprocesses receive argv arrays with shell=False.
Source and data boundary
Source, documentation, schemas, tests, and tiny synthetic manifests belong in Git. Raw CFD fields, VTK exports, scenes, frames, videos, generated figures, private paths, and credentials remain external.
Alpha quickstart
Alpha quickstartbash
python3 -m venv /tmp/visualopenfoam-venv
/tmp/visualopenfoam-venv/bin/python -m pip install -e '.[test]'
PYTHONPATH=src python3 -m visualopenfoam --help
PYTHONPATH=src python3 -m visualopenfoam doctor --json
PYTHONPATH=src python3 -m visualopenfoam inspect-case examples/synthetic/minimal_case --json
PYTHONPATH=src python3 -m visualopenfoam manifest examples/synthetic/minimal_case /tmp/visualopenfoam-case.json --json
PYTHONPATH=src python3 -m visualopenfoam plan-fields /tmp/visualopenfoam-case.json /tmp/visualopenfoam-fields.json --json
PYTHONPATH=src python3 -m visualopenfoam render-blender /tmp/visualopenfoam-case.json /tmp/visualopenfoam-render --dry-run --json
python3 scripts/validate_contracts.py
python3 -m pytest -qRelated tools
VisualBasilisk and the rectangular-slot OpenFOAM study.
VisualOpenFOAM and VisualBasilisk both use source-first manifests, dry-run render plans, synthetic fixtures, and explicit scientific semantics. The rectangular-slot study supplies a separate real-case example of the fields and native-time context the OpenFOAM readers are intended to retain.
Ecosystem context
OpenFOAM and VTK provide simulation-data formats, ParaView and Python libraries provide analysis paths, Blender provides rendering, and JSON manifests support automation. The contribution is their disciplined integration into a reproducible CLI, not a claim to have invented the underlying formats, readers, or visualization methods.
Compare the VisualBasilisk bridgeDevelopment status
Private alpha focused on external-case readers.
The CLI, schemas, dry-run planning, tests, and synthetic examples are in place.
Current work focuses on validating real OpenFOAM and VTK readers and preparing the first public source release.