Drawing cleanup

Clean up (Ctrl/Cmd+Shift+L) standardizes each molecule in place. The browser, desktop, vibe-sketch clean, REST clean routes and MCP clean_up all use vibesketch.document.clean.clean. Arrows, text, species identities, charge and stored 3D coordinates are retained. The browser edit is undoable.

from vibesketch.document import load, save
from vibesketch.document.clean import clean

result, report = clean(load("drawing.vsk"))
save(result.document, "cleaned.vsk")
print(report.cleaned, report.left)

Conventions and coverage

The packaged chem/data/depiction.json version 1 records numerical drawing conventions and citations per rule. It covers uniform bond lengths, ordinary organic chain angles, linear sp centres (including allenes), selected four-coordinate styles, isolated small rings, and substituents on a ring atom that has two ring bonds and lies in one ring. One substituent bisects the angle outside the ring (GR-4.2.1). Two sit 60 degrees apart, centred on that bisector (GR-4.2.3), as in 1,1-dimethylcyclohexane. These are normalized 2D units, never distances in Å or a physical force field. Formal charge and isotopes remain unchanged; labelled atoms reserve additional clearance.

Fused, bridged, spiro and large ring systems take their bond lengths, ring distances and angles from a reference layout, including unequal bond lengths where a projection needs them. The reference starts as the existing cleanup’s layout. Another generated layout replaces it for a ring system only when it crowds that system’s atoms less, or draws its bonds more evenly by more than shape_margin (0.01 of the mean bond). The candidates are RDKit’s depictor, its distance-mimicking layout, CoordGen and RDKit’s ring-template API. Every candidate and the existing cleanup are measured against the same reference, so the quality gate compares like with like. A taxane-like polycycle, which CoordGen draws with uneven ring bonds, now takes RDKit’s even ring system. Unsupported coordination and other four-coordinate styles retain seed angles. The table implements a subset of the IUPAC 2008 recommendations, not a complete IUPAC conformance checker. See source and licensing.

Refinement and refusal

RDKit, its distance-mimicking layout and CoordGen supply the existing seed and fallback. A vectorized objective applies bond and angle restraints, nonbonded atom/label clearance, complex-ring restraints and a weak positional restraint. The clearance penalty pushes pairs to repulsion_margin (0.02) beyond the clearance the overlap gate measures, so its soft equilibrium does not leave pairs just inside it. Atoms two bonds apart keep the ordinary atom clearance (two_bond_clearance, 0.55): a larger value conflicts with bridged projections such as norbornane’s. FIRE minimizes that objective; the drawing’s centre, orientation and chain-side choices are retained during alignment and checks.

A refinement must converge and must not worsen bond-length spread, bond error, angle error or overlap metrics relative to the existing cleanup. Numerical allowances are 0.001 drawing bond length and 0.1 degree; no extra clash is accepted. The overlap model uses conservative atom-centre radii, not font-specific label bounding boxes, and cannot guarantee an overlap-free drawing. Existing difficult layouts may therefore remain unchanged.

FIRE is capped at 400 steps per candidate and skipped above 200 atoms. Refusal, nonconvergence or a failed quality check retains the existing cleanup. After re-deriving wedges, canonical isomeric SMILES must match the input; a stereo failure retries the legacy layout. If neither layout passes, the molecule stays as drawn and the normal cleanup notice reports it. The low-level clean_2d result identifies accepted converged refinements as fire-v1:<seed>; a fallback retains its original seed name. Use the document API for the complete stereo check.

The initial regression set includes the Claisen mechanism, small and complex rings, quaternary centres, alkynes, allenes and charged species. The opt-in VIBESKETCH_REQUIRE_CLEAN_LATENCY=1 test checks a warm 95th-percentile target below 100 ms for 50-atom chain, branched and aromatic examples. This is a hardware-dependent interactive target, not a worst-case timing guarantee. For molecules with a perceived ring larger than eight atoms, cleanup skips CoordGen’s potentially unbounded macrocycle search. RDKit’s standard, distance-mimicking and ring-template candidates remain available, with the same quality and stereo checks. Small-ring molecules still use CoordGen. This topology-based fallback launches no worker process and removes the known 50-membered-ring hang; it is not a universal time limit on RDKit or on the complete cleanup operation.

Scheme-wide spacing belongs to the separate Tidy scheme action. Cleanup does not yet select or use a physical reference-geometry database.

Large molecules

The candidate layouts cost more than in proportion to the molecule, so above 500 atoms only the distance-mimicking layout runs: the fastest at that size, and the one that follows the drawing most closely. A molecule of more than 3,000 atoms is left as drawn, and the cleanup notice says so; it is drawn with its coordinates and keeps working everywhere else. A drawn 2,000-atom chain cleans in about 2.5 s; the measurements are in Performance and accessibility checks.