Transfer a selected structure to vibe-viewer¶
Select every atom of one connected molecule, then choose Export → Transfer selected structure… (also searchable in Commands). Click Prepare transfer. If the molecule has no 3D conformer, first enable Generate a 3D conformer if needed (transfer only). Preparation uses the same ETKDG/MMFF94 service as Generate 3D; an existing conformer is kept exactly.
Use Drag selected structure to 3D to drag the prepared molecule onto vibe-viewer. Desktop sketcher creates a native QVF file drag; the browser sends the existing structure drag record. You can also use Copy for vibe-viewer, then paste into the viewer canvas or directory launcher. Older viewers support the drag route but do not handle this copied record. Ordinary canvas Copy/Paste remains the drawing editor’s own clipboard operation.
Only that connected molecule is included. Partial molecules, selections across multiple structures (even identical copies), missing atom slots, unsupported chemistry and ambiguous stored species are refused. Drawing annotations are excluded. Limits are 500 selected atoms and a 4 MiB canvas. The source drawing, conformers and undo history are unchanged; a generated conformer belongs to the transfer only. This is structure transfer, not a calculation or a geometry-return transaction. Use the existing species hand-off for the geometry-return workflow.
Clipboard contents are a short-lived link, not the molecule’s bytes. Keep the sketcher server running and paste within ten minutes. A changed local drawing, document or selection invalidates the prepared action; prepare again. Browser cross-window transfer is intended for local loopback servers. Clipboard writes require the browser’s clipboard permission. QVF preparation needs the optional qvf-writer integration; missing integrations report an install hint.
Programmatic preparation¶
Atom references are {node, atom} slots in the exact source document’s KET.
The atom-query API supplies these references. Never reuse them after editing.
from vibesketcher.document import load
from vibesketcher.document.transfer import TransferSelection, prepare_transfer
source = load("drawing.vsk")
selection = TransferSelection.model_validate(
{
"atoms": [{"node": "mol0", "atom": i} for i in range(3)],
"generate": True,
}
)
transfer = prepare_transfer(source, selection)
with open("selected.qvf", "wb") as stream:
stream.write(transfer.data)
The CLI writes the same QVF, using an atoms/generate JSON file:
vibe-sketcher transfer-selection drawing.vsk selection.json -o selected.qvf
POST /api/documents/{id}/selection-transfer takes
{"revision": 0, "selection": {"atoms": [...], "generate": true}}.
The server refuses a stale revision before or after preparation. The reply has
species, generated, revision and the existing drag ticket fields:
schema, url, path, name, format, expires_in. The native path is
local-only; clipboard/browser records omit it and make url absolute.
MCP transfer_selection(document, revision, selection) calls that same endpoint.
All interfaces require explicit permission through generate: true to generate
a missing conformer. No document mutation or background calculation is performed.
From vibe-viewer back to sketcher¶
In viewer choose Export → Transfer structure to sketcher…, then Copy for vibe-sketcher and paste into the sketcher canvas, or drag Drag to vibe-sketcher onto it. Viewer captures its complete active molecule; select all atoms or clear the selection first. Partial atom selections and periodic structures are refused. The reverse packet contains a geometry-only QVF rather than an expiring link.
Sketcher appends the molecule’s 2D drawing and retains its 3D conformer. When the same species already exists, its existing conformers remain and a distinct incoming conformer is added. A conflicting spin state is refused. The receiver refuses imported chemistry warnings and explicitly recorded connectivity that its 2D import would change; use a reviewed file import for those cases. Limits are 500 atoms and a 4 MiB QVF. This imports a new drawing fragment; it does not replace a source sketch or return calculation results.
SDK import_transfer(document, qvf_bytes) returns (document, warnings).
CLI vibe-sketcher import-structure drawing.vsk structure.qvf -o updated.vsk
uses the same checks. REST POST /api/documents/{id}/structure-import takes
revision and base64 data; MCP import_structure(document, revision, data)
uses that endpoint. Stale revisions are refused. Ordinary drawing Copy/Paste
and paste in text fields continue to work normally.