Trame visualization

The Trame viewer provides a read-only interactive view for parq_blockmodel.blockmodel.ParquetBlockModel.

Supported workflows

The viewer supports both:

• single-PBM launch from a specific file path,

• hive-style drill-down selection using key=value directories plus PBM name.

In both modes you can:

• choose an attribute,

• adjust a threshold slider,

• refresh the rendered scene without mutating source PBM files.

Data source loader

The left drawer now starts with a collapsible Data source panel containing a server path field and a Load button.

• If the path is a .pbm file, the app switches to single-model mode.

• If the path is a directory, the app treats it as a hive root and enables the hive selector panel.

Hive-style selector

When launched from a hive root, the left drawer shows an Asset selector panel. The selector exposes:

• one dropdown per hive level key (in discovered order),

• a PBM name dropdown (pbm.name / file stem),

• the resolved PBM file path.

Changing selection loads the matching PBM in-place in the same app session.

Navigation and hotkeys

The Trame view uses VTK-style camera interactions. Common controls are:

• Left drag: rotate/orbit camera

• Shift + left drag: translate (pan)

• Middle drag: translate (pan)

• Right drag: dolly/zoom

• Mouse wheel: zoom

When z_up_lock=True is enabled, hold z while rotating to keep +Z vertical on screen (turntable-style orbit with no roll).

Notes:

• In browser-based Trame sessions, click inside the 3D view first so keyboard events are captured by the app.

• Exact interaction feel can vary slightly by platform/browser.

API

Use explicit startup entry points:

from parq_blockmodel.visualization import BlockModelTrameApp

file_app = BlockModelTrameApp.from_pbm_file("path/to/model.pbm")
hive_app = BlockModelTrameApp.from_hive_directory("path/to/hive_root")

# Scaffold-only API for a future query-backed startup workflow.
query_app = BlockModelTrameApp.from_duckdb_query(
    "SELECT * FROM read_parquet('path/to/hive/**/*.parquet')"
)

file_app.launch()

Examples

One combined example is provided:

• examples/16_trame_threshold_viewer.py: combined file/hive demo. The DEMO_SOURCE_KIND constant in the script switches between: * file startup from a single .pbm path, * hive startup from a directory path with selector drill-down.

For interactive examples included in Sphinx-Gallery, gate app.launch() with pyvista.BUILDING_GALLERY so docs builds do not start a live Trame server.