Find drawn atoms¶
Open Commands… (Ctrl/Cmd+K), search Find drawn atoms… and enter an RDKit SMARTS pattern, or choose Simple filters. Filters combine element, formal charge, aromatic and ring predicates with AND; multiple elements are alternatives. Select the species to search, then choose Search atoms.
For example, open the public esterification sketch.
[#8] finds six oxygen atoms; [OX2H] finds the two hydroxyl oxygen atoms
at mol0:3 and mol1:2. Match lists identify each drawn occurrence and its
species IDs. Query policy and source records the snapshot revision,
canonical document and canvas SHA-256 digests, and software versions.
Blue preview marks are transient. Searching never edits chemistry, moves atoms, changes the editor selection or adds an undo step. Apply selection explicitly replaces, adds to or removes from the native editor selection. Add/remove preserve unrelated selected drawing entities; replace clears them. An empty match set can clear the selection in replace mode. Selection itself is transient too. Close, Escape, Cancel search or changed query options clear the preview and restore previously displayed figure marks. Stored highlight colours and exports (including SVG, PDF and chemfig) are unaffected. Use the existing Mark selection action afterwards to create persistent publication marks.
Matching policy and limits¶
Matching uses RDKit aromaticity through the existing KET bridge. Aromatic SMARTS such as
cmatch aromatic atoms, including supported Kekulé drawings.Implicit H is a count predicate (
[OX2H]); only explicitly drawn H has a selectable atom reference. The search never generates hydrogen atoms.Stereochemistry is ignored unless Match stereochemistry is selected. That option enables RDKit chirality and enhanced-stereo matching. Filters have no stereochemistry option. Unsupported stereo or drawing constructs produce per-fragment warnings; supported fragments can still match.
Identical atom sets are deduplicated within a drawn occurrence. Repeated drawings, even at coincident coordinates, retain distinct identities. A species can have multiple occurrences; equivalent stored species IDs can share an occurrence. Missing supported occurrences are reported.
Recursive SMARTS (
$(...)) are refused: RDKit’s recursive-match cap could otherwise silently hide matches. Queries are explicit atom/bond patterns, never natural-language instructions or executable code.Limits are 500 SMARTS characters, 128 query atoms, 1,000 fragments, 25,000 canvas atoms, 10,000 matches, 8 MiB result JSON and the existing 64 MiB document/input limit. Exceeding a limit refuses the complete result rather than returning an apparently complete truncated match set.
Native parsing and matching run in an isolated worker with a maximum ten-second deadline. At most two workers run per server process; additional requests receive a busy refusal. SDK cancellation and timeout kill and reap the worker. Cancelling the browser request immediately discards its preview and late responses; a server worker can continue until its bounded deadline.
References are zero-based {node, atom} KET slots in that exact source
snapshot, not canonical species atom numbers. Do not reuse them after an edit,
reload or source change. The browser verifies graph fields, slot identities and
the loader’s single scale/translation, then maps slots to exact editor IDs. It
does not select by proximity. Changed source documents, native drawing history,
closed dialogs, changed options and superseded responses cannot apply old hits.
If source/display identity cannot be established, the operation refuses.
SDK, CLI, REST and MCP¶
from vibesketcher.document import load
from vibesketcher.document.queries import query_atoms
document = load("esterification.vsk")
result = query_atoms(document, "[OX2H]")
assert [(a["node"], a["atom"]) for a in result["atoms"]] == [("mol0", 3), ("mol1", 2)]
filtered = query_atoms(document, {"filter": {"elements": ["O"], "charge": 0}})
query_atoms also accepts an AtomQuery model, optional species and
use_chirality for the string form, a timeout no greater than ten seconds,
and a cancelled() callback. Structured queries carry species/chirality in
the object. Invalid queries, bounds and worker failures raise QueryRefused;
QueryCancelled and QueryBusy are its subclasses. Neither success nor failure
changes the supplied document.
vibe-sketcher match esterification.vsk --smarts '[OX2H]' --json
vibe-sketcher match esterification.vsk --element O --charge 0 --species m1
CLI filters also include --aromatic/--not-aromatic and
--in-ring/--not-in-ring. Repeat --element or --species for alternatives.
Use --use-chirality with SMARTS. --output matches.json writes the full JSON
envelope; default text lists counts, atom references and warnings. Ctrl+C
cleans up the worker and exits 130; query refusals exit 3.
POST /api/documents/{id}/atom-query takes revision and exactly one of
smarts or filter, plus optional species, use_chirality and
source_sha256. A revision/digest mismatch gives 409, invalid input or worker
refusal 422 and occupied workers 429. Success returns
vibesketcher.atom-query/1: source, query, software, policy, counts,
matches, union atoms and per-fragment/species warnings.
MCP query_atoms takes the same options and a document handle; it obtains
the current revision if omitted. All interfaces return the same snapshot atom
identities. These read operations never create persistent query fields.