VisualBasilisk

A reproducible Basilisk VOF-to-Blender visualization bridge.

VisualBasilisk is a small bridge/workflow tool for moving Basilisk output_facets(f) style interface data and frame manifests into reviewable Blender/media pipelines. It is source-first: Python utilities, schemas, tiny examples, tests, and documentation.

It is not a CFD solver, not a validation package, and not a predictive spray model.

What It Does

• Reads compact surface/frame manifests.
• Parses simple Basilisk facet polygon files.
• Checks frame completeness and manifest consistency.
• Generates contact sheets from existing image frames.
• Writes review-packet manifests for internal or public-safe inspection.
• Prepares a dry-run sample-output plan for a checked manifest.
• Runs a minimal headless Blender smoke render for the tiny synthetic facet fixture.
• Provides schemas and tiny synthetic fixtures for reproducible tests.

What It Does Not Do

• It does not run Basilisk simulations.
• It does not vendor Basilisk, Blender, or ffmpeg.
• It does not include raw solver outputs, checkpoint dumps, surface folders, frame folders, .blend files, or full-size videos.
• It does not claim validation, production CFD, experimental agreement, stationary spray, true atomisation prediction, pressure-atomized-nozzle validation, or final predictive modeling.

Quickstart

python3 -m pip install -e .
visualbasilisk check examples/minimal_vof_smoke/surface_manifest.json
visualbasilisk sample-output examples/minimal_vof_smoke/surface_manifest.json sample_outputs/minimal_vof_smoke --dry-run
visualbasilisk render-blender examples/minimal_vof_smoke/surface_manifest.json /tmp/visualbasilisk-render --dry-run
visualbasilisk render-blender examples/minimal_vof_smoke/surface_manifest.json /tmp/visualbasilisk-render --dry-run --frame-range 0:1 --resolution 640x480 --camera-preset orbit --material-preset blue
visualbasilisk render-blender examples/minimal_vof_smoke/surface_manifest.json /tmp/visualbasilisk-render --frames 1 --overwrite
visualbasilisk review-packet examples/minimal_vof_smoke/review_packet_manifest.json

sample-output writes a checked handoff plan. It does not start Blender. render-blender --dry-run writes the exact headless Blender command plan; omit --dry-run only when Blender is available and generated images should stay outside Git.

render-blender refuses to overwrite an existing render plan or rendered-frame folder unless --overwrite is supplied. It supports --frame, --frame-range, --resolution, --camera-preset, and --material-preset for small fixture reviews.

The actual render path is intentionally limited to the tiny synthetic fixture and a reviewed manifest. It is a bridge proof, not a production rendering product.

For architecture and rendering boundaries, see docs/pipeline.md, docs/architecture.md, docs/blender_rendering.md, and docs/fixture_inventory.md. For day-to-day usage and support boundaries, see docs/cli_reference.md, docs/troubleshooting.md, docs/provenance_and_assets.md, docs/real_fixture_policy.md, and docs/faq.md.

Current Status

This repository is public as a source-first VisualBasilisk v0.3 snapshot from a local Basilisk-to-Blender evidence workflow. Treat it as a modest bridge utility with tiny synthetic fixtures, not as a full renderer, CFD validation package, or released distribution.

Draft public-facing copy and release blockers are kept in docs/public_page_draft.md, docs/public_status.md, PROFILE_CASE_STUDY_DRAFT.md, and RELEASE_BLOCKERS.md. GitHub visibility is complete, but GitHub Releases, package/container publishing, site deployment, real Basilisk fixtures, and scientific validation claims remain unapproved.

Smoke Test

python3 scripts/run_minimal_smoke.py
python3 -m pytest -q

The smoke test uses synthetic facet fixtures only.