Object Matching

When an animation plays, Molkit pairs each atom, bond, and annotation in one state with its counterpart in the next state. Matched objects tween between their two positions; unmatched objects get an enter or exit behavior instead. Matching usually works without your help, but the Match Editor lets you inspect and correct every pairing.

Automatic matching

Molkit matches objects between each pair of adjacent states using several passes, in order:

Provenance. Objects created by Duplicate State, or copied and pasted from one state frame into another, remember their source object and pair with it at full confidence. This is the most reliable signal.
Custom labels. A label that appears exactly once in each state matches even if the element changed (for example a generic “Nu” drawn as carbon in one state and nitrogen in the next). Repeated labels match within their label group by proximity.
Connectivity. Unlabeled atoms match through their bonded neighbors, iterating outward from atoms already matched. Bond angles and wedge/dash stereo break ties.
Displayed label, then element plus proximity. Remaining atoms match by what is visibly drawn, falling back to same-element nearest-position pairing.

Bonds are matched implicitly: when both endpoint atoms match, the bond between them matches too. Text annotations match by identical text content; shapes, images, and LaTeX match by type and proximity (content-bearing types must have identical content).

Unmatched objects

An object that exists only in the first state fades out during the transition. If it is bonded to a matched atom, it instead slides into that neighbor (collapse-into). An object that exists only in the second state pops in early in the transition, or slides out from a matched neighbor it is bonded to (emerge-from). These behaviors are chosen automatically.

The Match Editor

Open it with the Match button in the animation toolbar, which is enabled once the animation has at least two states.

The editor shows both states with numbered badges on every object. The same number on both sides marks a matched pair; gray dash badges mark unmatched objects. Pairs whose elements differ get a warning highlight. Use [ and ] to step between state pairs and F to fit the view.

Fixing a match

Wire mode (W): click an object in one state, then its partner in the other. The new pair is pinned, replaces any conflicting match, and survives re-running Auto.
Renumber: double-click a badge, type a pair number, press Enter.
Auto (A): re-run automatic matching while keeping your pinned pairs and exclusions.

Breaking a match

Click a badge (Shift-click to multi-select) and press Delete. Both objects become excluded, so Auto will not re-pair them; they animate as unmatched instead. Clear (C) unpairs everything for the current state pair, and Reset (R) discards all edits and reruns matching from scratch. Wiring an excluded object pairs it again.

Transfer mode (T) wires an electron-transfer dot from a source in the first state to a target in the second. Pin marks an annotation pair as static so it is held in place rather than re-animated. Ctrl+Z undoes within the editor session; press M or Esc to leave the current mode, then again to close the editor.

Gotchas

Duplicate, don’t redraw. Duplicate State or copy-paste between state frames preserves provenance and gives perfect matches. Redrawing the same molecule from scratch forces heuristic matching, which can mispair symmetric atoms.
Editing after matching. Adding or deleting atoms in either state invalidates stored matches for that pair, and matching recomputes automatically. Re-check the Match Editor after structural edits.
Changed text breaks text matches. A text annotation whose content differs between states will not pair by provenance; it crossfades instead. Wire it manually if you want it to move.