Python API¶
The complete public API is the vixar.Viewer class plus the lightweight
LayerRef / SlicerRef handles it returns. The reference below is generated
from the source docstrings.
Viewer¶
vixar.Viewer ¶
add_point_cloud ¶
add_point_cloud(source, color_by=None, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear', point_size=2.0, name=None, x_col='x', y_col='y', z_col='z', attributes=None, flat_color=None, src_epsg=None)
Add a point-cloud layer from a LAS file, CSV, DataFrame, or numpy.
add_tiled_point_cloud ¶
add_tiled_point_cloud(meta_path, name=None, color_by=None, cmap='spectral', vmin=None, vmax=None, point_size=2.0)
Add a streaming point cloud from a pre-tiled dataset (plan Phase 3).
Point geometry is not loaded into memory or embedded in the scene
config; instead the engine fetches binary tiles on demand and frustum-
culls / LODs them, so multi-gigabyte clouds render without exhausting
RAM. Produce the tiles first with the vixar tile CLI or
:func:vixar.tiler.tile_point_cloud, then point this method at the
resulting meta.json.
Because tiles are baked relative to the origin computed at tile time, a tiled layer fixes the scene origin: any in-memory layers added alongside it are rebased onto the same origin. Mixing two tiled layers with different origins is not supported.
:param meta_path: Path to the meta.json written by the tiler.
:param name: Display name for the layer.
:param color_by: Attribute baked into the tiles to colour by (the tiler
must have been run with the matching --color-by).
:param cmap: Colour palette.
:param point_size: Splat size in pixels.
add_boreholes ¶
add_boreholes(source, id_col, x_col, y_col, z_col, from_col=None, to_col=None, color_by=None, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear', radius=2.0, name=None, src_epsg=None)
Add a borehole layer from a CSV of desurveyed samples.
add_block_model ¶
add_block_model(source, x_col='x', y_col='y', z_col='z', block_size=None, color_by=None, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear', threshold=None, iso_threshold=None, azimuth_deg=0.0, name=None)
Add a regular block model from a CSV file or DataFrame.
block_size is inferred from the grid spacing if omitted.
threshold hides blocks below this grade value.
iso_threshold renders a Marching Cubes isosurface at this value.
azimuth_deg rotates the blocks about +Z (CCW of the I-axis from
+X/East) for rotated grids; the spacing is recovered along the rotated
basis and the cubes are oriented to match.
add_ore_body ¶
add_ore_body(source, color=(0.78, 0.44, 0.22), opacity=0.65, solid=False, wireframe=False, name=None)
Add an ore body shell from an OBJ file or (vertices, faces) tuple.
solid=True enables an opaque fill + wireframe edge overlay.
wireframe=True adds an edge overlay on top of the mesh.
add_surface ¶
add_surface(source, color_by=None, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear', flat_color=None, opacity=1.0, wireframe=False, name=None)
Add a stratigraphic surface from an OBJ file, GOCAD TS file, or
(vertices, faces) tuple. Optionally colour by a per-vertex attribute.
add_volume ¶
add_volume(source, color_by=None, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear', threshold=None, opacity=0.6, steps=128, name=None, spacing=None, origin=None, scalar=None)
Add a volume (regular 3-D scalar grid) rendered by ray marching.
source may be a 3-D numpy array (shape (nx, ny, nz)), a
(data, spacing, origin) tuple, a .npy path, or a VTK / GOCAD
SGrid file readable by meshio. spacing/origin give the cell
size and the real-world (0,0,0) grid corner; threshold hides
samples below a value; opacity scales the integrated density.
set_isosurface_threshold ¶
set_isosurface_threshold(ref, value)
Update the Marching Cubes isosurface threshold for a block model layer.
Pass None to remove the isosurface. Triggers a scene rebuild when a
live widget is active (same behaviour as :meth:set_colour).
set_camera ¶
set_camera(position, target)
Position the camera at position looking at target (local coords).
add_slicer ¶
add_slicer(axis='z', position=0.0, label=None)
Add a cross-section slicer plane at a real-world axis position.
position is given in absolute (real-world) units; it is converted to
local coordinates against the scene origin at build time.
animate_slicer ¶
animate_slicer(ref, start, end, fps=10.0)
Animate a slicer scrubbing between two real-world axis positions.
The plane sweeps from start to end (and back, ping-pong),
advancing one slab-thickness frame every 1 / fps seconds. start
and end are real-world axis values, converted to local coordinates
against the scene origin at build time (like add_slicer's position).
measure_distance ¶
measure_distance()
Activate the click-to-measure distance tool in a live viewer.
Click two points in the 3D view to drop a measured segment; the distance
(and both UTM endpoints) is shown on a label. Press M to toggle or
Esc to cancel. Requires an active viewer (show() or serve()).
measure_angle ¶
measure_angle()
Activate the three-point angle measurement tool in a live viewer.
Click three points (arm, vertex, arm) to measure the angle at the
vertex. Requires an active viewer (show() or serve()).
add_annotation ¶
add_annotation(position, text, color=None, leader_from=None, id=None)
Add a programmatic 3-D text label at a real-world position.
position (and optional leader_from anchor) are in working-CRS
coordinates, converted to local at build time. Returns the annotation id.
record_video ¶
record_video(path, camera_path, duration_s=8.0, fps=30)
Record a camera fly-through to a WebM file (requires show()).
camera_path is a list of keyframes, each either a mapping with
position/target or a (position, target) pair, in local
coordinates (same space as :meth:set_camera). The camera is
interpolated through the keyframes over duration_s at fps and the
canvas is captured via MediaRecorder.
set_high_contrast ¶
set_high_contrast(enabled=True)
Toggle the high-contrast accessibility theme in a live viewer.
High-contrast mode switches the canvas to a pure-black background and
forces strong black/white panel styling for low-vision users. It can
also be toggled in the viewer with the ◐ Contrast button or the
H key.
on_tile_loaded ¶
on_tile_loaded(callback)
Register a Python callback fired on tile load/evict events.
on_pick ¶
on_pick(callback)
Register a callback fired when a block is hovered/picked in the viewer.
The callback receives a dict with layerId, value, localXYZ
and utmXYZ. Pick events only flow in widget (show()) sessions.
set_threshold ¶
set_threshold(ref, value)
Hide blocks/samples below value (block model or volume layer).
Pass None to show everything. Updates live in a widget and persists
into :meth:build_config output. For block models this drives the same
hide-below control exposed by the in-viewer block-model panel.
set_colour ¶
set_colour(ref, color_by, cmap='spectral', vmin=None, vmax=None, units=None, color_scale='linear')
Recolour a layer by an attribute, with an optional explicit value range.
color_by is the attribute name (or "rgb"), cmap one of the
built-in palettes. vmin/vmax fix the colour range; when omitted it
is auto-computed. units sets the physical unit label on the colorbar.
color_scale controls mapping ("linear", "log", "percentile").
set_color is a US-spelling alias.
serve ¶
serve(port=8050, open_browser=True)
Start a local FastAPI server hosting the viewer; returns the server.
Tiled layers (:meth:add_tiled_point_cloud) are served automatically:
their tile directories are mapped onto the URL prefixes the engine
streams from.
to_html ¶
to_html(path)
Write a standalone HTML file with the scene embedded inline.
Not available for tiled layers: standalone HTML has no server to stream
tiles from. Use :meth:serve for tiled datasets.
screenshot ¶
screenshot(path, width=1920, height=1080)
Request a PNG from a live viewer (requires show()/serve()).