vibeview.api

High-level Python API for vibe-view — programmatic access to all QVF operations.

Import with from vibeview.api import * or use individual functions.

All functions accept QVFReader instances or file paths. They are the programmatic equivalents of the vibe-view CLI commands.

Functions

capture_structure(source, path, **kwargs)

Render the structure to a PNG file.

capture_volume(source, section_id, path, ...)

Render a volume section to a PNG file.

diff(source_a, source_b)

Compare two QVFs: return energy delta, section overlap, geometry RMSD.

export_xyz(source)

Return the structure as an XYZ string.

get_structure(source)

Return structure data as a dict with atoms, pbc, and lattice_vectors.

get_table(source, kind)

Extract tabular data (same as vibe-view table --kind).

get_volume(source, section_id)

Return a JSON-serializable summary of a volume section's grid.

has_section(source, section_id)

Check if a section exists in the QVF.

info(source)

Return full metadata for a QVF file as a dict.

render_terminal(source[, section_id, size, ...])

Render a section as terminal text and return it.

sections(source)

Return a list of {id, kind} dicts for all sections.

slice_qvf(source, output, *[, keep, drop])

Extract sections without discarding metadata.

validate(source)

Validate QVF integrity: schema + all SHA-256 hashes.
vibeview.api.info(source)[source]

Return full metadata for a QVF file as a dict.

Equivalent to vibe-view info --json.

Parameters:

source (str | Path | bytes | bytearray | memoryview | IO[bytes])

Return type:

dict[str, Any]

vibeview.api.sections(source)[source]

Return a list of {id, kind} dicts for all sections.

Parameters:

source (str | Path | bytes | bytearray | memoryview | IO[bytes])

Return type:

list[dict[str, str]]

vibeview.api.has_section(source, section_id)[source]

Check if a section exists in the QVF.

Parameters:
Return type:

bool

vibeview.api.get_structure(source)[source]

Return structure data as a dict with atoms, pbc, and lattice_vectors.

Parameters:

source (str | Path | bytes | bytearray | memoryview | IO[bytes])

Return type:

dict[str, Any]

vibeview.api.export_xyz(source)[source]

Return the structure as an XYZ string.

Parameters:

source (str | Path | bytes | bytearray | memoryview | IO[bytes])

Return type:

str

vibeview.api.diff(source_a, source_b)[source]

Compare two QVFs: return energy delta, section overlap, geometry RMSD.

Parameters:
Return type:

dict[str, Any]

vibeview.api.get_volume(source, section_id)[source]

Return a JSON-serializable summary of a volume section’s grid.

Gives the grid geometry (origin, voxel_vectors, shape) plus the value range (data_shape, data_min, data_max) – not the voxels themselves, so the result stays serializable. For the ndarray use vibeview.QVFReader.read_volume_data().

Returns None if the section is absent or is not a volume.

Parameters:
Return type:

dict[str, Any] | None

vibeview.api.get_table(source, kind)[source]

Extract tabular data (same as vibe-view table --kind).

Parameters:
Return type:

tuple[list[str], list[list]]

vibeview.api.validate(source)[source]

Validate QVF integrity: schema + all SHA-256 hashes.

Returns {"valid": True, "n_sections": N, "n_members": M} on success, or {"valid": False, "error": "..."} on failure.

Parameters:

source (str | Path | bytes | bytearray | memoryview | IO[bytes])

Return type:

dict[str, Any]

vibeview.api.capture_structure(source, path, **kwargs)[source]

Render the structure to a PNG file.

Parameters:
Return type:

bool

vibeview.api.capture_volume(source, section_id, path, **kwargs)[source]

Render a volume section to a PNG file.

Parameters:
Return type:

bool

vibeview.api.render_terminal(source, section_id=None, *, size=(100, 30), plain=False, **kwargs)[source]

Render a section as terminal text and return it.

The text counterpart of capture_structure() / capture_volume(): same renderers, same colours, but the output is a string of braille characters instead of a PNG — and unlike the capture functions it needs no OpenGL context, so it works on a headless compute node.

section_id defaults to the structure section. plain=True drops the ANSI colour for logs and pipes. Extra keyword arguments are passed to vibeview.tui.show.render_section() (mode, representation, color_mode, replication, isovalue, rotation, show_labels, frame, chart).

Returns a human-readable explanation rather than raising when the section has no graphical form (a citations block, say), so a caller sweeping every section never has to pre-filter by kind.

Parameters:
Return type:

str

vibeview.api.slice_qvf(source, output, *, keep=None, drop=None)[source]

Extract sections without discarding metadata. Refuse dangling references.

Viewer hints for removed sections are pruned. All other source fields and kept member bytes are preserved; the output is validated before replacement.

Parameters:
Return type:

Path