vibeview.api

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

Import with from vibeview.api import * (__all__ lists the public functions) 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.

closing_reader(source)

Borrow an existing reader, or close a reader opened from a source.

diff(source_a, source_b)

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

export_xyz(source[, section_id])

Return the structure as an XYZ string (section_id as in get_structure()).

get_structure(source[, section_id])

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, *[, limits])

Validate with qvf's reference validator (requires the validation extra).
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.closing_reader(source)[source]

Borrow an existing reader, or close a reader opened from a source.

Only readers created by this context are closed, on both normal return and exceptions. Caller-owned readers and binary streams remain open.

Parameters:

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

Return type:

Iterator[QVFReader]

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

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

geo_rmsd_a is None when the RMSD cannot be taken, and geo_rmsd_skipped then says why: a structure that cannot be read, a structure with no atoms, or atom counts that differ (#60). It is None when the RMSD was taken.

Parameters:
Return type:

dict[str, Any]

vibeview.api.export_xyz(source, section_id=None)[source]

Return the structure as an XYZ string (section_id as in get_structure()).

Parameters:
Return type:

str

vibeview.api.get_structure(source, section_id=None)[source]

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

section_id names a structure section; by default the shown one, the archive’s first structure (QVF spec § 4.1) for a fresh reader.

Parameters:
Return type:

dict[str, Any]

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

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

Parameters:
Return type:

tuple[list[str], list[list[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().

The range is that of the field the viewer draws: the array goes through vibeview.renderers.volume.stored_volume_field(), as in the browser and the terminal. A real array is summarised as stored. A complex one, which is not valid QVF v1, is reduced by the section’s component label first (#61).

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

Parameters:
Return type:

dict[str, Any] | None

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

Check if a section exists in the QVF.

Parameters:
Return type:

bool

vibeview.api.info(source)[source]

Return full metadata for a QVF file as a dict.

Equivalent to vibe-view info --json. A section’s generic label is included when it has one, and a structure section carries its chemical identity (name, charge, multiplicity, smiles, inchi, inchikey; QVF spec § 5.1) as far as it states it. first_structure is the structure a viewer shows first and an export without a section takes (spec § 4.1), or None.

Parameters:

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

Return type:

dict[str, Any]

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, band_energy_unit).

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.sections(source)[source]

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

Parameters:

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

Return type:

list[dict[str, 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

vibeview.api.validate(source, *, limits=None)[source]

Validate with qvf’s reference validator (requires the validation extra).

Returns valid, errors, warnings and structured findings (severity, code, where, message). Invalid archives include error; valid archives include n_sections and n_members. Hash/layout failures retain the member diagnostic fields when available. A viewer readability failure adds reader_error separately from qvf findings. An unreadable container or manifest raises QVFOpenError with the reference report retained in its validation_report attribute.

limits supplies overrides to qvf’s Limits.from_dict; unknown keys raise. The reference validator checks resource limits before reading payloads. Caller-owned streams and readers remain open and keep their stream position. An existing reader validates its original archive, without applying geometry edits. Missing validation support raises QVFError rather than silently performing a partial check.

Parameters:
Return type:

dict[str, Any]