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 needs no help from you. When it does, the Match Editor shows every pairing and lets you correct it.
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 and 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.
When an atom collapses into a neighbor that carries a label (for example, CH3 and O in one state drawn as the single label CH3O in the next), the bond that led to the collapsing atom is paired with the bond to the new label. It slides to the label instead of fading out and back in.
Whole molecules that exist in only one state drift out or in as they fade. See Reaction Choreography.
Match quality
Each pair of states gets a rating, shown as the tint of its duration chip in the state strip and as a label in the Animation panel when the transition is selected:
| Tint | Rating | Meaning |
|---|---|---|
| Green | Smooth morph | Every object is matched one to one with a confident pairing. |
| Amber | Partial morph | Some objects fade in or out, or some pairings are uncertain. |
| Red | Mostly cross-fade | Most objects are unmatched. |
Amber is normal when atoms enter or leave on purpose. When you expected every object to carry over, an amber or red chip is the cue to open the Match Editor.
The Match Editor
Open it with the Match button in the animation toolbar, which is enabled once the animation has at least two states, or with Edit matches… in the Animation panel when a transition is selected.
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
- Inspect (the default mode): click badges to select them.
- Wire (
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.
Carry forward (T) wires an electron-transfer dot from a source in the first state to a target in the second. Pin static marks an annotation pair as static, so it holds still through the transition. Ctrl+Z undoes within the editor session; press M or Esc to leave the current mode, then again to close the editor, or click Done.
Example: fix a mispaired hydrogen
Suppose you drew state 2 of a bromomethane SN2 from scratch instead of duplicating state 1. In the preview, two hydrogens on the carbon cross paths as the molecule inverts, because matching paired each with the wrong partner.
- Click the chip between the two states, then Edit matches… in the Animation panel. The Match Editor opens on that pair.
- Find the two hydrogens whose numbers cross: the number on the upper hydrogen in state 1 appears on the lower hydrogen in state 2.
- Press
Wfor Wire mode, click the upper hydrogen in state 1, then the hydrogen you want it to become in state 2. Wire the other hydrogen the same way. - Click Done and preview again. The wired pairs are pinned, so pressing Auto later keeps them.
Common mistakes
Redrawing a molecule in the next state, instead of duplicating the state or copying and pasting between frames, loses provenance. Matching then falls back to heuristics, which can mispair symmetric atoms such as the three hydrogens of a methyl group.
Adding or deleting atoms in either state clears the stored matches for that pair, and matching runs again. Re-check the Match Editor after structural edits.
A text annotation whose content differs between states cannot pair by provenance, so it crossfades. Wire it by hand if you want it to move.