> ## Documentation Index > Fetch the complete documentation index at: https://10play-session-status-checl.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Movies, Scenes, States/Frames, Sequence Viewer > Map of four coupled PyMOL subsystems. The engine (packages/engine/, C++ + Python cmd) is unmodified upstream and is reached over the Python bridge. Every… # Movies, Scenes, States/Frames, Sequence Viewer Map of four coupled PyMOL subsystems. The engine (`packages/engine/`, C++ + Python `cmd`) is unmodified upstream and is reached over the Python bridge. Every claim below is anchored to a `file:line` that was read. **Where the port stands.** Movie panel and transport: `apps/web/src/features/movie/` (`MovieTimeline`, `TransportBar`, `MovieEditors`, `ExportDialog`, `msetParser.ts`, `timeline.ts`, `mvprg.ts`) over `packages/bridge/tenmol_bridge/panels/movie.py` and `packages/protocol/src/topics/movie{,_panel}.ts`. Scenes: `apps/web/src/features/scenes/` over `packages/protocol/src/topics/scenes.ts`. Sequence viewer: `apps/web/src/features/seqview/` over `packages/bridge/tenmol_bridge/panels/seqview.py`. The clock stays on the backend (§0), and the frame stream arrives on `packages/protocol/src/topics/frame.ts`. *** ## 0. Executive summary of the area Four coupled subsystems live here: 1. **States vs. frames.** Objects have *states* (coordinate sets). The viewer has *frames*. By default 1 frame = 1 state; `mset` defines an arbitrary frame→state map (`packages/engine/modules/pymol/moving.py:691`, `packages/engine/layer1/Movie.cpp:979` `MovieFrameToIndex`). 2. **Movies.** Per-frame command strings (`mdo`/`mappend`), per-frame *key frames* (`mview`, `CViewElem`) for camera and per-object matrices, plus playback (`mplay`/`mstop`/`mtoggle`) and export (`mpng`, `movie.produce`). 3. **Scenes.** Named snapshots of view + colors + reps + enabled-state + frame + message * a PNG thumbnail (`packages/engine/layer3/MovieScene.h:73`, `packages/engine/layer3/MovieScene.cpp:173`). 4. **Sequence viewer ("Seeker").** An in-viewport text grid built in C++ (`packages/engine/layer3/Seeker.cpp:969` `SeekerUpdate`) and drawn as GL text (`packages/engine/layer1/Seq.cpp:259` `CSeq::draw`). Selection interaction mutates the *active selection* via generated `cmd.select(...)` strings (`packages/engine/layer3/Seeker.cpp:169`, `:70`). Two of these (movie panel, sequence viewer) are **Ortho blocks drawn inside the GL viewport** upstream (`packages/engine/layer1/Movie.cpp:1741`, `packages/engine/layer1/Seq.cpp:259`, `packages/engine/layer1/Control.cpp:536`), plus **scene buttons** drawn as an overlay on the Scene block (`packages/engine/layer1/Scene.cpp:2885` `SceneDrawButtons`, gated by `scene_buttons`, `packages/engine/layer1/Scene.cpp:3456`). All three are React components in the port and are never drawn by the engine. ### Why parts of this area are server-rendered raster, not geometry The molecular scene reaches the browser as geometry, but four features here produce *server-rendered raster images*: * `cmd.ray` → `_cmd.render` (`packages/engine/modules/pymol/viewing.py:1581`) writes into `G->Scene->Image`. * `cmd.draw` → `_cmd.draw` needs a live GL context (`packages/engine/modules/pymol/viewing.py:1652`, wrapped in `_self._call_with_opengl_context` at `:1660`). * `cmd.mpng` / `movie.produce` render every frame to PNG on disk (`packages/engine/modules/pymol/moving.py:366`, `packages/engine/layer1/Movie.cpp:626` `MovieModalPNG`, `packages/engine/modules/pymol/movie.py:846`). * Scene **thumbnails** come from `SceneDeferImage` into a 220×124 PNG buffer (`packages/engine/layer3/MovieScene.cpp:225-233`, dims at `packages/engine/layer3/MovieScene.h:97-99`). None of those can be produced client-side, so the bridge owns an offscreen GL context (`packages/bridge/tenmol_bridge/glcontext/` — CGL, EGL, WGL) and streams encoded bytes (`packages/bridge/tenmol_bridge/render/encode.py`, `render/framestream.py`). `cmd.draw` documents that it "does not work when running in the command-line only mode" (`packages/engine/modules/pymol/viewing.py:1630-1632`), which is why a context-less bridge falls back to `ray`. **Movie playback is driven by the backend idle loop** (`packages/engine/layer1/Scene.cpp:2432` `SceneIdle`, frame pacing at `:2453-2480`, rock at `:2477-2484`). The backend stays the single clock and pushes frame-change events; the browser never runs its own playback timer, which is what keeps the two from double-timing. *** ## 1. Frames & states — exact semantics ### 1.1 Frame/state queries | cmd | source | returns | | --------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `cmd.get_frame()` | `packages/engine/modules/pymol/moving.py:984` | 1-based current frame; **no lock taken** | | `cmd.get_state()` | `packages/engine/modules/pymol/moving.py:958` | 1-based current state; **no lock taken** | | `cmd.count_frames()` | `packages/engine/modules/pymol/querying.py:759` | frames defined for the movie | | `cmd.get_movie_length(images=-1)` | `packages/engine/modules/pymol/querying.py:730` | frames *explicitly* defined by `mset`; negative internal value is folded per `images` arg (`:746-753`) | | `cmd.count_states(selection)` | `packages/engine/modules/pymol/querying.py:703` | states in selection | | `cmd.get_movie_playing()` | `packages/engine/modules/pymol/moving.py:64` | bool | | `cmd.get_movie_locked()` | `packages/engine/modules/pymol/querying.py:814` | bool (movie commands suppressed) | `MoviePlaying()` returns true also while movie commands are being evaluated (`packages/engine/layer1/Movie.cpp:540-551`), and returns false when `I->Locked`. ### 1.2 `SceneSetFrame(G, mode, frame)` — the whole navigation vocabulary `packages/engine/layer1/Scene.cpp:2121-2184`. Modes: | mode | meaning | Python entry | | ---- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | -1 | movie/frame override — go to this **state** absolutely | — | | 0 | absolute frame | `cmd.set_frame(frame, 0)` (`packages/engine/modules/pymol/moving.py:898`) | | 1 | relative frame | used internally after `mview` (`packages/engine/layer1/Movie.cpp:1372`) | | 2 | end | — | | 3 | middle + auto movie command | `cmd.middle()` (`packages/engine/modules/pymol/moving.py:934`) | | 4 | absolute + auto movie command | `cmd.rewind()` = `set_frame(4,0)` (`packages/engine/modules/pymol/moving.py:874`) | | 5 | relative + auto movie command | `cmd.forward()` = `(5,+1)` (`:819`), `cmd.backward()` = `(5,-1)` (`:846`) | | 6 | end + auto movie command | `cmd.ending()` (`packages/engine/modules/pymol/moving.py:911`) | | 7 | absolute + **forced** movie command | scrollbar drag (`packages/engine/layer1/Movie.cpp:1535`, `:1783`) | | 8 | relative + forced movie command | — | | 9 | end + forced movie command | — | | 10 | seek forward to the frame carrying the current scene | `MovieSeekScene` (`packages/engine/layer1/Movie.cpp:1008`), used by scene recall while playing (`packages/engine/layer3/MovieScene.cpp:408-409`) | `cmd.frame(n, trigger=-1, scene=0)` is a separate entry (`packages/engine/modules/pymol/moving.py:460`) calling `_cmd.frame(COb, n-1, trigger)`. Side effects of a frame change (`packages/engine/layer1/Scene.cpp:2185-2210`): clamp to `[0, NFrame)`, compute `newState = MovieFrameToIndex(...)`, at frame 0 recall the `mmatrix` matrix and abort any running animation, set settings `frame` and `state`, invalidate selection indicator CGOs and picking, optionally run the frame's movie command, and set `MovieFrameFlag` if `cache_frames`. ### 1.3 Playback loop `SceneIdle` (`packages/engine/layer1/Scene.cpp:2432`): * FPS from `movie_fps`; `fps <= 0` → use `movie_delay` ms; `fps < 0` → full speed (`:2453-2464`; same logic duplicated in `SceneGetFPS` `packages/engine/layer1/Scene.cpp:342`). * Adaptive `LastFrameAdjust` smoothing (`:2465-2475`). * At last frame: if `movie_loop` → `SceneSetFrame(G,7,0)`, else `MoviePlay(G,cMovieStop)` (`:2485-2492`). * If not playing but `ControlRocking(G)` → `SceneUpdateCameraRock` every `rock_delay` ms (`:2477-2484`). `MoviePlay` (`packages/engine/layer1/Movie.cpp:555`): `cMovieToggle=-1`, `cMovieStop=0`, `cMoviePlay=1` (`packages/engine/layer1/Movie.h:118-120`). When not looping and already at the last frame, play/toggle first rewinds via `SceneSetFrame(G,7,0)` (`:561-567`, `:573-579`). *** ## 2. `mset` — the frame↔state program `cmd.mset(specification, frame=1, freeze=0)` — `packages/engine/modules/pymol/moving.py:691`. The *entire mini-language is parsed in Python* (`:733-764`) then handed to `_cmd.mset(space-separated 0-based state list, start-1, freeze)`: * bare integer `N` → one frame showing state N. * `xN` → repeat previous state N times total (`:743-751`); if no previous, uses current state. * `-N` → ramp from previous state to N inclusive, direction auto (`:752-760`). * whitespace normalized, `x`/`-` split off adjacent tokens (`:734-739`). Examples from the docstring (`:709-722`): `mset 1`, `mset 1 x10`, `mset 1 x30 1 -15 15 x30 15 -1`. `cmd.madd` (`packages/engine/modules/pymol/moving.py:677`) is literally `mset(..., frame, freeze)` — it appends using the same syntax. C side: `MovieSet` / `MovieAppendSequence` (`packages/engine/layer1/Movie.cpp:877`, `:890`). Redefining the movie clears existing `mdo` commands (documented at `packages/engine/modules/pymol/moving.py:307-308`, `:349-351`). **Frame → state resolution**: `MovieFrameToIndex` (`packages/engine/layer1/Movie.cpp:979`) — a per-frame `ViewElem[frame].state_flag` (set by `mview store, state=…`) *overrides* the `Sequence[]` map; otherwise `Sequence[frame]`; if no movie, frame == state. *** ## 3. Movie commands (`mdo` / `mappend`) * `cmd.mdo(frame, command)` → `_cmd.mdo(COb, frame-1, command, 0)` — replaces (`packages/engine/modules/pymol/moving.py:274`, C: `MovieSetCommand` `packages/engine/layer1/Movie.cpp:1074`). * `cmd.mappend(frame, command)` → `_cmd.mdo(COb, frame-1, ";"+command, 1)` — appends (`packages/engine/modules/pymol/moving.py:323`, C: `MovieAppendCommand` `packages/engine/layer1/Movie.cpp:1378`). * `cmd.mdump()` prints all defined commands to the feedback stream, format `"%5d: %s\n"` (`packages/engine/modules/pymol/moving.py:81`, C: `MovieDump` `packages/engine/layer1/Movie.cpp:378-403`). **There is no structured getter** — see §12 gaps. * Execution: `MovieDoFrameCommand` (`packages/engine/layer1/Movie.cpp:1045`) — at frame 0 recall `mmatrix`; if not locked, `PParse` the command string, then if the frame carries a `scene_flag` and the scene differs from `scene_current_name`, `MovieSceneRecall(...)` with view=false/frame=false (`:1058-1065`), then `SceneFromViewElem`. `cmd.mmatrix(action)` with `clear|store|recall|check` → `_cmd.mmatrix(0..3)` (`packages/engine/modules/pymol/moving.py:772-816`; C `MovieMatrix` `packages/engine/layer1/Movie.cpp:589`, constants `packages/engine/layer1/Movie.h:161-164`). Docstring warns not to mix with `mview`. `cmd.mclear()` clears the cached frame images (`packages/engine/modules/pymol/moving.py:436`; C `MovieClearImages` `packages/engine/layer1/Movie.cpp:1432`). *** ## 4. Key frames — `mview` and `CViewElem` ### 4.1 Python surface `cmd.mview(action='store', first=0, last=0, power=0.0, bias=-1.0, simple=-1, linear=0.0, object='', wrap=-1, hand=0, window=5, cycles=1, scene='', cut=0.5, quiet=1, auto=-1, state=0, freeze=0)` — `packages/engine/modules/pymol/moving.py:160`. Actions (`packages/engine/modules/pymol/moving.py:145-156`, mirrored in `packages/engine/layer1/MViewAction.h:3-14`): | name | int | C behavior | | --------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `store` | 0 | `packages/engine/layer1/Movie.cpp:1155-1196` — writes camera/object matrix into frame(s), sets `specification_level=2`, optional `state`, `power`, `bias`, `scene_name` | | `clear` | 1 | `:1197-1211` — zeroes the `CViewElem` in the range | | `interpolate` | 2 | `:1212-1343` — fills only *unspecified* gaps between key frames | | `reinterpolate` | 3 | `:1212-1343` — recomputes all in-between frames | | `smooth` | 4 | `:1129-1152` — `ViewElemSmooth` × `cycles` with `window`; auto-reinterpolates if `movie_auto_interpolate` | | `reset` | 5 | `:1344-1349` — reallocates the whole `ViewElem` VLA (drops everything) | | `uninterpolate` | 6 | `:1350-1366` — deletes frames whose `specification_level < 2` | | `toggle` | 7 | `:1105-1110` — store if not a key frame, else clear | | `toggle_interp` | 8 | `:1111-1127` — flips between reinterpolate and uninterpolate | | `purge` | 9 | (object motions; menu `obj_motion` uses it, `packages/engine/modules/pymol/menu.py:136`) | Python-side pre/post logic worth cloning verbatim: * negative `first`/`last` are counted from `count_frames()` (`packages/engine/modules/pymol/moving.py:214-219`). * `scene='auto'` or `None` → current `scene_current_name`; a non-empty `scene` triggers `scene(scene,"recall",animate=0,frame=0)` **before** the store (`:221-225`). * args are 0-based on the wire: `first-1`, `last-1`, `state-1` (`:228-232`). * auto-reinterpolate: unless `freeze`, and if `auto>0` or (`auto<0` and `movie_auto_interpolate`), actions store/clear/toggle are followed by a second `_cmd.mview(action=3, first=-1, last=-1, …)` (`:233-241`). ### 4.2 `CViewElem` — what a key frame holds `packages/engine/layer1/View.h:24-63`: 4×4 `matrix` (+flag), `pre[3]`, `post[3]`, `front`/`back` clip (+`clip_flag`), `ortho` (+flag), `state` (+`state_flag`), `view_mode` (0 relative / 1 absolute), `specification_level` (0 none, 1 interpolated, 2 key frame), `timing` (+flag), `scene_name` lexicon key (+`scene_flag`), `power` (+flag), `bias` (+flag). Interpolation entry point: `ViewElemInterpolate(G, first, last, power, bias, simple, linearity, hand, cut)` (`packages/engine/layer1/View.h:93`). Smoothing: `ViewElemSmooth(first,last,window,loop)` (`packages/engine/layer1/View.h:92`). ### 4.3 Frame-range editing (`mmove` / `mcopy` / `mdelete` / `minsert`) All four funnel into `_cmd.mmodify(COb, action, index, count, target, object, freeze, quiet)`: | cmd | action | source | | -------------------------------------- | ------ | --------------------------------------------- | | `mdelete(count=-1, frame=0, …)` | -1 | `packages/engine/modules/pymol/moving.py:591` | | `minsert(count, frame=0, …)` | 1 | `packages/engine/modules/pymol/moving.py:640` | | `mmove(target, source=0, count=-1, …)` | 2 | `packages/engine/modules/pymol/moving.py:493` | | `mcopy(target, source=0, count=-1, …)` | 3 | `packages/engine/modules/pymol/moving.py:545` | Semantics: `0` means "current frame" (`get_frame()-1`), negative counts back from the end and clamps so `frame+count <= cur_len` (`:520-535`, `:621-630`). `count<0` in `mdelete` means "to the end" (`:629-630`). C side: `MovieViewModify` (`packages/engine/layer1/Movie.cpp:89`), enum `ViewElemAction {Delete=-1, Insert=1, Move=2, Copy=3}` (`packages/engine/layer1/View.h:100-106`). When not frozen/localized it calls `ExecutiveMotionExtend` (`packages/engine/layer1/Movie.cpp:157-159`). *** ## 5. The Movie Panel (in-viewport upstream) `CMovie` is an Ortho `Block` (`packages/engine/layer1/Movie.h:52`). Height: `MovieGetPanelHeight` (`packages/engine/layer1/Movie.cpp:1701`) = `movie_panel_row_height` × `ExecutiveCountMotions(G)`, or a single row when `presentation` is on (`:1716-1721`); zero when `movie_panel==0` or there is nothing to show (`:1703-1711`). Rows come from `ExecutiveMotionDraw` (`packages/engine/layer3/Executive.cpp:697`): one row for the global camera (`cExecAll`, drawn by `MovieDrawViewElem` → `ViewElemDraw(..., "camera", …)`, `packages/engine/layer1/Movie.cpp:1728-1734`) and one row per object that has motions (`ObjectDrawViewElem`, `packages/engine/layer3/Executive.cpp:727`). Row count = `ExecutiveCountMotions` (`packages/engine/layer3/Executive.cpp:664`), which falls back to 1 when `SceneGetNFrame(G) > 1` (`:684-685`). Per-frame cell painting (`packages/engine/layer1/View.cpp:158-260`): color by `specification_level` — level 1 (interpolated) draws a thin center bar (`bar_color {0.3,0.3,0.6}` with `key_color` top edge and `bot_color` bottom edge, `:189-232`); level 2 (key frame) draws a full-height block in `key_color {0.4,0.4,0.8}` (`:233-248`). `top_color {0.6,0.6,1.0}` and `bot_color {0.2,0.2,0.4}` are the remaining palette entries (`:172-175`). X↔frame mapping: `ViewElemXtoFrame(rect, frames, x, nearest)` (`packages/engine/layer1/View.h:98`, wrapper `MovieXtoFrame` `packages/engine/layer1/Movie.cpp:72`). A horizontal `ScrollBar` doubles as the frame slider (`packages/engine/layer1/Movie.cpp:1775-1793`); dragging it issues `SceneSetFrame(G, 7, value)` (`:1781-1784`, and on click `:1535`). When there are no `ViewElem`s at all the row is labelled `"states"` (`packages/engine/layer1/Movie.cpp:1842-1844`). ### 5.1 Complete mouse grammar of the panel `CMovie::click` (`packages/engine/layer1/Movie.cpp:1488`), `::drag` (`:1574`), `::release` (`:1609`). `tmpRect.right -= LabelIndent` where `LabelIndent = 8*8 dip` unless `presentation` (`packages/engine/layer1/Movie.cpp:1864-1868`). | input | drag mode | released action | | ------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Right-drag | `cMovieDragModeMoveKey` | `cmd.mmove(cur+1, start+1, 1, object=…)` (`:1639`) | | Shift + Right-drag | `cMovieDragModeCopyKey` | `cmd.mcopy(cur+1, start+1, 1, object=…)` (`:1653`) | | Ctrl+Shift + Right | as above, but `DragColumn=true` → `object=''` i.e. all rows (`:1501-1502`, `:1620-1621`) | | | Right-click past the end of the movie | — | opens the motion context menu immediately (`:1512`) | | Right-click without moving >3px/5px | — | opens the motion context menu (`:1629-1634`, `:1643-1648`) | | Ctrl + Left-drag | `cMovieDragModeInsDel` | drag right → `cmd.minsert(n, first, object=…)`; drag left → `cmd.mdelete(n, first+1, object=…)` (`:1671-1685`) | | Ctrl+Shift + Left-drag | same, `DragColumn` | | | Left-drag (no mod) | scrollbar | `SceneSetFrame(G,7,value)` (`:1533-1536`) | | Ctrl + Middle-drag | `cMovieDragModeOblate` | `cmd.mview('clear', first=…, last=…, object=…)`; `DragColumn` → `object='same'` (`:1656-1669`) | | Wheel | — | `SceneSetFrame(G, 5, ±1)` (`:1567`) | | Ctrl+Shift + Wheel | — | adjust `movie_panel_row_height` ± 1 and reshape (`:1561-1564`) | | Shift + Left | reserved ("TEMPORAL SELECTIONS -- TO COME") (`:1519-1520`) | no-op | Drag feedback rectangles (`packages/engine/layer1/Movie.cpp:1797-1840`): white outline on the source frame + grey filled box on the target; oblate = white outline + grey fill over the range; ins/del = green fill when inserting, red fill when deleting. Drag is abandoned if the pointer leaves ±50px vertically (`:1580`). ### 5.2 Panel context menus Activated by `ExecutiveMotionMenuActivate` (`packages/engine/layer3/Executive.cpp:737`), which resolves which row was hit and passes the 1-based frame number as a string. **`camera_motion`** (`packages/engine/modules/pymol/menu.py:108-124`): * `store` → `cmd.mview("store",first=F)` * `store with scene` → submenu of up to 40 scene names, each `cmd.mview("store",scene=NAME,first=F)` (`packages/engine/modules/pymol/menu.py:54-59`) * `store with state` → submenu `current` (`state=-1`), `1`, `n_state`, plus 8 evenly spaced states (`packages/engine/modules/pymol/menu.py:62-80`) * `clear` → `cmd.mview("clear",first=F)` * `reset camera motions` → `cmd.mview("reset")` * `purge entire movie` → `cmd.mset()` * `smooth key frames` → `a little` / `more (window=15)` / `a lot (window=30)` (`packages/engine/modules/pymol/menu.py:103-106`) * `interpolate`, `reinterpolate`, `uninterpolate` **`obj_motion`** (`packages/engine/modules/pymol/menu.py:126-143`): `drag`, `store`, `store with state`, `reset` (`cmd.reset(object=…)`), `clear`, `reset object motions`, `purge object motions` (`mview("purge",object=…)`), `smooth key frames`, `interpolate` / `reinterpolate` / `uninterpolate`, all with `object="…"`. *** ## 6. Movie menu (menu bar) — full enumeration Source: `packages/engine/modules/pymol/_gui.py:234-376` (toolkit-independent; consumed by `packages/engine/modules/pmg_qt/pymol_qt_gui.py:353` and `packages/engine/modules/pmg_tk/skins/normal/__init__.py:1072`). ``` Movie ├── Append ▸ 0.25 / 0.5 / 1 / 2 / 3 / 4 / 6 / 8 / 12 / 18 / 24 / 30 / 48 / 60 second │ → cmd.movie.add_blank(i) (_gui.py:235-238) ├── ───── ├── Program ▸ │ ├── Camera Loop ▸ │ │ ├── Nutate ▸ 15°/4s, 15°/8s, 15°/12s | 30°/4s, 30°/8s, 30°/12s, 30°/16s | │ │ │ 60°/8s, 60°/16s, 60°/24s, 60°/32s │ │ │ → movie.add_nutate(sec,deg,start=%d) (_gui.py:242-256) │ │ ├── X-Rock ▸ 30°/{2,4,8}s | 60°/{4,8,16}s | 90°/{6,12,24}s | 120°/{8,16,32}s | │ │ │ 180°(179.99)/{12,24,48}s → movie.add_rock(sec,deg,axis='x',start=%d) │ │ │ (_gui.py:258-278) │ │ ├── X-Roll ▸ 4 / 8 / 16 / 32 seconds → movie.add_roll(sec,axis='x',start=%d) │ │ │ (_gui.py:279-284) │ │ ├── Y-Rock ▸ (same grid as X-Rock, axis='y') (_gui.py:286-306) │ │ └── Y-Roll ▸ 4 / 8 / 16 / 32 seconds (_gui.py:307-312) │ ├── Scene Loop ▸ │ │ ├── Nutate ▸ / X-Rock ▸ / Y-Rock ▸ (rock = 4 / 2 / 1) │ │ │ each: 30°/{2,4,8}s, 60°/{4,8,16}s, 90°/{6,12,24}s, 120°/{8,16,32}s │ │ │ → "set sweep_angle,A;cmd.movie.add_scenes(None,S,rock=R,start=%d)" │ │ │ (_gui.py:315-327) │ │ └── Steady ▸ 1/2/4/8/12/16/24 seconds each │ │ → movie.add_scenes(None,V,rock=0,start=%d) (_gui.py:329-333) │ ├── State Loop ▸ Full Speed / 1/2 / 1/3 / 1/4 / 1/8 / 1/16 Speed │ │ ▸ no pause / 1 / 2 / 4 second pause │ │ → movie.add_state_loop(speed,pause,start=%d) (_gui.py:336-348) │ └── State Sweep ▸ (identical grid) → movie.add_state_sweep(...) (_gui.py:336-348) ├── Update Last Program → self.mvprg() (_gui.py:350) ├── Remove Last Program → self.mvprg_remove_last() (_gui.py:351) ├── ───── ├── Reset → "mset;rewind" (_gui.py:353) ├── ───── ├── Frame Rate ▸ 30 / 15 / 5 / 1 / 0.3 FPS (radio on movie_fps) │ ───── │ ☑ Show Frame Rate (show_frame_rate) │ Reset Meter → cmd.meter_reset() (_gui.py:355-364) ├── ───── ├── ☑ Auto Interpolate (movie_auto_interpolate) ├── ☑ Show Panel (movie_panel) ├── ☑ Loop Frames (movie_loop) ├── ☑ Draw Frames (draw_frames) ├── ☑ Ray Trace Frames (ray_trace_frames) ├── ☑ Cache Frame Images (cache_frames) ├── Clear Image Cache → cmd.mclear (_gui.py:366-372) ├── ───── ├── ☑ Static Singletons (static_singletons, on=1) └── ☑ Show All States (all_states, on=1) (_gui.py:374-375) ``` Also in the File menu: **Export Movie As ▸ MPEG… / Quicktime… / ─── / PNG Images…** (`packages/engine/modules/pymol/_gui.py:105-110`). ### 6.1 "Last program" bookkeeping `PyMOLDesktopGUI.mvprg(command=None)` (`packages/engine/modules/pymol/_gui.py:958-968`): remembers `movie_start = cmd.get_movie_length() + 1` and `movie_command = command % movie_start`, then `cmd.do(movie_command)`. Calling with `None` re-runs the stored command ("Update Last Program"). `mvprg_remove_last` (`:950-956`) issues `cmd.mdelete(-1, self.movie_start)`. **This is client-side state** — it must live in the React store, not the bridge. *** ## 7. Movie programs (`pymol.movie`) — full API `packages/engine/modules/pymol/movie.py`. FPS helper: `get_movie_fps` returns `movie_fps` or 30 if ≤0 (`:26`). ### 7.1 Legacy `mdo`-based generators (write per-frame commands) | function | signature | source | behavior | | ------------ | ------------------------------------------------------ | ------ | -------------------------------------------------------------------------------------- | | `sweep` | `(pause=0, cycles=1)` | `:32` | builds an `mset` string `1 -N N -1` (or with `xpause` padding) repeated `cycles` times | | `pause` | `(pause=15, cycles=1)` | `:44` | `1 x{p} 1 -N N x{p}` per cycle | | `load` | `(pattern, nam="mov", **kw)` | `:56` | glob + `cmd.load` each match sorted into one object | | `rock` | `(first=1,last=-1,angle=30,phase=0,loop=1,axis='y')` | `:64` | per-frame `mdo "turn axis,Δ"` from a sine sweep | | `roll` | `(first=1,last=-1,loop=1,axis='y')` | `:93` | constant `turn axis,deg`; leading `-` in axis inverts | | `tdroll` | `(first,rangex,rangey,rangez,skip=1)` | `:118` | sequential X then Y then Z rolls, `skip°` per frame | | `zoom` | `(first,last,step=1,loop=1,axis='z')` | `:167` | `mdo "move axis,±step"`, reverses at halfway when looping | | `nutate` | `(first,last,angle=30,phase=0,loop=1,shift=π/2)` | `:185` | 4 chained `turn` per frame (undo x/y, apply next x/y) | | `screw` | `(first,last,step=1,angle=30,phase=0,loop=1,axis='y')` | `:214` | rock + `move z` | | `timed_roll` | `(period=12.0,cycles=1,axis='y')` | `:247` | `mset 1 x{total}`, `mview reset`, then per-frame `turn` + `mview store` | ### 7.2 Key-frame based generators (the ones the Movie menu uses) All take `start=0` meaning "append at `get_movie_length()+1`". | function | signature | source | notes | | ----------------- | ------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `add_blank` | `(duration=12.0, start=0)` | `:268` | `mset "1 x{fps*duration}"` at `start`, then `frame(start)` | | `add_roll` | `(duration=12.0, loop=1, axis='y', start=0)` | `:296` | 3 key frames at 0/⅓/⅔ with `power=1`; wrap-interpolate when `loop` and `start==1`, else an adjustment turn of `360/n_frame`; final `mview reinterpolate` if `movie_auto_interpolate` (`:342-344`) | | `add_rock` | `(duration=8.0, angle=30.0, loop=1, axis='y', start=0)` | `:346` | key frames at ¼ and ¾ with `power=-1` | | `add_nutate` | `(duration=8.0, angle=30.0, spiral=0, loop=1, offset=0, phase=0, shift=π/2, start=0)` | `:433` | stores **every** frame; `spiral=±1` ramps the amplitude in/out (`:472-477`); `loop` and `offset` documented as unused (`:450-452`) | | `add_state_sweep` | `(factor=1, pause=2.0, first=-1, last=-1, loop=1, start=0)` | `:384` | 5 key frames 1→N→1 with pauses; `mview store …, state=…` | | `add_state_loop` | `(factor=1, pause=2.0, first=-1, last=-1, loop=1, start=0)` | `:409` | 4 key frames 1→N | | `add_scenes` | `(names=None, pause=8.0, cut=0.0, loop=1, rock=-1, period=8.0, animate=-1, start=0)` | `:562` | per scene: `mview store …, scene=NAME`; between scenes runs `_rock`/`_nutate` per `sweep_mode`; `rock` arg is `sweep_mode+1` (2=x-rock, 3=y-rock, 4=nutate); `animate<0` → `scene_animation_duration`; ends with `mview interpolate cut=…, wrap=loop` and `mview smooth` | Internal helpers: `_rock` (`:490`, uses `sweep_angle`, `power=-1` keys), `_nutate_sub` (`:517`), `_nutate` (`:543`). ### 7.3 Export `cmd.mpng(prefix, first=0, last=0, preserve=0, modal=0, mode=-1, quiet=1, width=0, height=0)` — `packages/engine/modules/pymol/moving.py:366`. `mode`: `2=ray`, `1=draw`, `0=normal`, `-1=check ray_trace_frames/draw_frames` (`:392-393`). Asserts `mode in (-1,0,1,2)` (`:427`). Routes through `_self._call_with_opengl_context` unless ray (`:431-434`). C side `MoviePNG` (`packages/engine/layer1/Movie.cpp:819`) drives the modal loop `MovieModalPNG` (`packages/engine/layer1/Movie.cpp:626`) with stages in `CMovieModal` (`packages/engine/layer1/Movie.h:22-50`). `movie.produce(filename, mode='', first=0, last=0, preserve=0, encoder='', quality=-1, quiet=1, width=0, height=0)` — `packages/engine/modules/pymol/movie.py:846`: * `mode` shortcut dict `normal|draw|ray` → `0|1|2` (`:815-821`). * Encoder autodetect: `.mpeg/.mpg` → `mpeg_encode`, else `ffmpeg`, else `convert`, else raise (`:915-925`). * `mpeg_encode` uses `.ppm` frames; others `.png` and force `opaque_background` (`:928-936`). * mp4/mov/webm: dimensions forced even, aspect-preserving from the viewport (`:938-951`). * Temp dir is `.tmp`; `preserve<1` deletes it at the end (`:906-963`, `:812-813`). * `mpng` writes `mov%04d.png` (`_prefix="mov"`, `:656`), then `_encode` (`:687`) waits for all files (polling `get_modal_draw()`, `:701`) and shells out. * ffmpeg branches: GIF uses a two-pass palettegen/paletteuse (`:765-771`); webm uses `libvpx-vp9` with `crf = 65 - quality/2` (`:778-781`); otherwise `crf` 10/15/20 by quality and `-pix_fmt yuv420p` (`:782-785`). * `convert` uses `-delay 100/fps` (`:794-802`). * `mpeg_encode` maps quality to `1 + (100-q)*29/100` and snaps fps to `[23.976,24,25,29.97,30,50,59.94,60]` with a warning (`:732-743`). * Sets `keep_alive` during export and `unset`s it afterwards (`:971`, `:811`). * A `_watch` thread prints byte counts while encoding (`:658-685`). ### 7.4 Export dialog (Qt) `packages/engine/modules/pmg_qt/file_dialogs.py:691` `file_save_mpeg(parent, _preselect=None)`, form `packages/engine/modules/pmg_qt/forms/movieexport.ui`: Fields: `input_width`, `input_height` (QSpinBox, seeded from `get_viewport()`, `file_dialogs.py:795-797`); preset buttons `button_720p`, `button_480p`, `button_360p` which set height and clamp aspect to ≤16:9 (`:788-793`, `:808-811`); `input_encoder` combo — `""`, `ffmpeg`, `mpeg_encode`, `convert` (`movieexport.ui:161-177`); `input_quality` spinbox seeded from `movie_quality`, disabled for `""`/`convert` (`:725`, `:798`); `input_ray` checkbox seeded from `ray_trace_frames` (`:799-800`); format radios `format_png/mp4/mpg/mov/gif` enabled per encoder support matrix (`:702-707`); `button_ok`. `_preselect='png'` hides the format group (`:737-739`); `_preselect='mov'` forces ffmpeg (`:747-750`). Run: png → `cmd.mpng(fname, width, height, mode=2 if ray else 1, quiet=0, modal=-1)` (`:772-777`); otherwise `cmd.movie.produce(fname, width, height, quality, mode, encoder, quiet=0)` (`:781-785`). Legacy Tk equivalent: a Pmw "Movie Settings" dialog with Encoding Quality / Ray Trace Frames / Width / Height (`packages/engine/modules/pmg_tk/skins/normal/__init__.py:964-987`). *** ## 8. Scenes ### 8.1 `cmd.scene` — the one entry point `packages/engine/modules/pymol/viewing.py:1034`: ``` scene(key='auto', action='recall', message=None, view=1, color=1, active=1, rep=1, frame=1, animate=-1, new_key=None, hand=1, quiet=1, sele="all") ``` Accepted actions (`viewing.py:56-60`): `store, recall, clear, insert_before, insert_after, next, previous, start, update, rename, delete, order, sort, first, append`. Python normalization before the C call (`viewing.py:1086-1115`): * `key='auto'` + `action='recall'` → `action='next'` (that's why bare `scene` advances). * `action='update'` preserves the existing message via `_scene_get_current_message` (`viewing.py:1007`, which reads the Message wizard that carries a `from_scene` attr). * Deprecated aliases: `clear` → `delete`; `append`/`update` → `store`. * Presentation auto-quit: if the same next/previous action repeats while `presentation` and `presentation_auto_quit` are on and `scene_current_name` is empty, try `chain_session()` (loads the next numbered `.pse/.psw`, `viewing.py:935-959`), else `cmd.quit()`. * The C call is wrapped in `_self._call_with_opengl_context` (`viewing.py:1125`) because storing a scene grabs a thumbnail. ### 8.2 C implementation — `MovieSceneFunc` `packages/engine/layer3/MovieScene.cpp:755`: * `insert_before` / `insert_after` → remembers `scene_current_name`, rewrites action to `store`, then reorders with `MovieSceneOrderBeforeAfter` (`:772-777`, `:814-815`, `:733`). * `next` / `previous` → `MovieSceneGetNextKey` then `recall` (`:779-783`). Wrap behavior: if `scene_loop` is off and we run off either end, returns `""`; an empty `scene_current_name` forces looping (`:700-728`). * `start` → first key in order, then `recall` (`:784-788`). * `key == "auto"` → `scene_current_name` (`:789-791`). * `recall` with `key=="*"` → `MovieScenePrintOrder` (`:794-795`). * `recall` with an empty key → clear `scene_current_name`, `ExecutiveSetObjVisib(G,"*",false)` (blank screen), clear the message (`:797-801`). * `store`, `delete`, `rename`, `order`, `sort` (sorted natural order), `first` (move to top) (`:808-826`). * Always sets `scenes_changed=true` and fires side effects — this is the **GUI refresh signal** the React scene panel should subscribe to (`:832-834`). **Store** (`packages/engine/layer3/MovieScene.cpp:173`): key `""`/`"new"` → `getUniqueKey()`; new keys are appended to `order`; `SceneSetNames` refreshes the scene-button list; `scene_current_name` is set. `storemask` bits `STORE_VIEW|ACTIVE|COLOR|REP|FRAME|THUMBNAIL` (`packages/engine/layer3/MovieScene.h:27-34`). Stores: message, `SceneGetView`, `SceneGetFrame`, a 220×124 PNG thumbnail via `SceneDeferImage` (`:225-233`), per-atom `{color, visRep}` keyed by `unique_id` for atoms of *enabled* objects only (`:236-252`), and per-object `{color, visRep}` with the enabled bit packed into bit 0 of `visRep` (`:254-265`). **Recall** (`packages/engine/layer3/MovieScene.cpp:458`, impl `:485`): each `recall_*` flag is ANDed with the stored `storemask` (`:491-495`); atom color/rep restored by `unique_id` (`:506-528`); objects invalidated with `cRepInvVisib`/`cRepInvColor` (`:571`); camera restored with `SceneSetView(G, view, true, animate, 1)` where `animate == -1` resolves to `get_scene_animation_duration` (`:576-579`). `get_scene_animation_duration` (`:429-438`): `scene_animation` (-1 → fall back to `animation`), 0 → no animation, else `scene_animation_duration`. Frame recall (`MovieSceneRecallFrame`, `:404-424`): if the movie is playing use `SceneSetFrame` mode 10 (seek to this scene's frame); if the frame is unchanged do nothing; otherwise honor `scene_frame_mode` (0, or -1 with a movie defined ⇒ don't change the frame). Note it round-trips through Python `cmd.set_frame` to avoid a `PBlock` deadlock (`:421-423`) — relevant if we ever run the bridge on a non-main thread. **Order** (`packages/engine/layer3/MovieScene.cpp:88`/`:95`, Python `cmd.scene_order` `packages/engine/modules/pymol/viewing.py:961`): args `names` (space-separated string or list), `sort` (bool), `location` ∈ `top|current|bottom` (`viewing.py:997-1005`). Duplicate keys are an error (`MovieScene.cpp:126-128`); invalid location is an error (`:132-135`). ### 8.3 Scene helper cmds | cmd | source | wire type | | ---------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `cmd.get_scene_list()` | `packages/engine/modules/pymol/viewing.py:919` → `_cmd.get_scene_order` | `list[str]` in display order | | `cmd.get_scene_thumbnail(name)` | `packages/engine/modules/pymol/viewing.py:923` | **PNG byte buffer** (used as `QPixmap.loadFromData(buf,"PNG")`, `packages/engine/modules/pmg_qt/scene_bin_gui.py:189-192`) | | `cmd.get_scene_message(name)` | `packages/engine/modules/pymol/viewing.py:927` | `str` | | `cmd.set_scene_message(name, message)` | `packages/engine/modules/pymol/viewing.py:931` | — | | `cmd.scene_order(names, sort, location)` | `packages/engine/modules/pymol/viewing.py:961` | — | `cmd.scene_recall_message` (`packages/engine/modules/pymol/viewing.py:1013`) is INTERNAL: it drives the `message` wizard, tagging it `from_scene = 1`; an empty message tears the wizard down. In React this becomes a scene-message overlay component, not a wizard. Legacy compatibility (session loading only): `_legacy_scene` (`viewing.py:1132`), `session_restore_scenes` (`:1199`), `_convert_legacy_scene` (`:1232`). Old scenes stored `get_view()/get_vis()/get_frame()/get_colorection()` plus `_scene__` selections over `rep_list` (`viewing.py:52-54`). ### 8.4 Scene menu (menu bar) `packages/engine/modules/pymol/_gui.py:775-805`: ``` Scene ├── Scenes... → self.scene_panel_menu_dialog (_gui.py:776) ├── ───── ├── Next [PgDn] → cmd.scene('', 'next') ├── Previous [PgUp] → cmd.scene('', 'previous') ├── ───── ├── Append → "scene new, store" ├── Append... ▸ Camera → "scene new, store, color=0, rep=0" │ Color → "scene new, store, view=0, rep=0" │ Reps → "scene new, store, view=0, color=0" │ Reps + Color → "scene new, store, view=0" ├── Insert Before → cmd.scene('', 'insert_before') ├── Insert After → cmd.scene('', 'insert_after') ├── Update → cmd.scene('auto','update') ├── ───── ├── Delete → cmd.scene('auto','clear') ├── ───── ├── Recall ▸ F1 … F12 → cmd.scene(k,'recall') (_gui.py:61-65) ├── Store ▸ F1 … F12 → cmd.scene(k,'store') ├── Clear ▸ F1 … F12 → cmd.scene(k,'clear') ├── ───── ├── ☑ Buttons (scene_buttons) └── Cache ▸ Enable / Optimize / Read Only / Disable → cmd.cache(...) ``` ### 8.5 Scene Panel dialog (Qt) `packages/engine/modules/pmg_qt/scene_bin_gui.py:29` `ScenePanel(QWidget)`: * Title "Scene Panel", 365×700 (`:45`, `:52`). * Instruction label "Double click selected thumbnail to \nload into Workspace." (`:64-66`). * **Add Scene** button → `cmd.scene('new','append',quiet=0)` then scroll to bottom (`:253-260`). * Table columns enum `NAME=0, IMAGE=1, MESSAGE=2, ACTIONS=3` (`:16-20`), but the "condensed" layout shows only 2 columns `['Name','Scene Preview']` (`:213-215`), row height 100 (`:130`). * Vertical headers are `↕` glyphs used as drag handles for reordering (`:231-242`), reorder → `cmd.scene_order(' '.join(names))` (`:379-387`). * Rename by editing the NAME cell → `cmd.scene(old,'rename',new_key=new)`; names with spaces and blank names are rejected with a printed error (`:360-377`). * **Update Scene** → `cmd.scene(name,'update')` + refresh thumbnail (`:262-274`). * **Delete Scene** → `cmd.scene(name,'clear')` (`:276-290`). * Double-click row → `cmd.scene(name,'recall')` (`:292-299`). * Delete/Update buttons enabled only with a selection (`:351-358`). * **Known placeholders**: message and actions columns are hard-coded strings `'This is a base message'` / `'Rock, zoom, something'` (`:170-171`) — the React version should use `cmd.get_scene_message` / `cmd.set_scene_message` instead. * Repopulates on paint/focus events via an event filter (`:102-113`) — replace with the `scenes_changed` event. ### 8.6 Scene buttons (in-viewport overlay) `SceneDrawButtons` (`packages/engine/layer1/Scene.cpp:2885`), enabled by `scene_buttons` (`packages/engine/layer1/Scene.cpp:3456`). Names come from `SceneSetNames` (`:2870`) into `CScene::SceneVec` of `SceneElem{name, rect, drawn}` (`packages/engine/layer1/SceneElem.h:7-12`, `packages/engine/layer1/SceneDef.h:145`). Layout: `internal_gui_control_size` line height (`:2901`), 8dip char width (`:2896`), a vertical scrollbar when entries exceed the visible rows (`:2924-2946`), name truncated to `max_char` (`:3014-3016`). Colors: pressed `{0.7,0.7,0.7}`, current scene `{0.5,0.5,0.5}`, others `{0.25,0.25,0.25}` (`:2891-2893`, `:3029-3038`). Mouse (`packages/engine/layer1/SceneMouse.cpp:179` `SceneClickSceneButton`): * Left press → `PressMode=1`; on release over the same button → `cmd.scene('NAME')` (`SceneMouse.cpp:1097-1104`). * Middle press → *rapid browse*: recalls immediately on press, `animate=0` when Ctrl is held (`:196-212`); continues to recall while dragging over other buttons (`:1105-1114`). * Right press → `PressMode=3`; on release over the same button opens the `scene_menu` popup (`:1117-1126`). * Dragging with `PressMode=4` reorders: `cmd.scene_order([a,b])` or `cmd.scene_order([name], location='top')` when dropped on the first slot (`SceneMouse.cpp:1274-1300`). `scene_menu` (`packages/engine/modules/pymol/menu.py:1842-1850`): header `Scene `, `rename` → `cmd.wizard("renaming", name, mode="scene")`, `update` → `cmd.scene(name,"update")`, `delete` → `cmd.scene(name,"delete")`. *** ## 9. Camera: view get/set, interpolate, turn/move/zoom/orient/clip, rock ### 9.1 View vector `cmd.get_view(output=1, quiet=1)` — `packages/engine/modules/pymol/viewing.py:634`. `_cmd.get_view` returns 25 floats; Python slices to **18**: `r[0:3]+r[4:7]+r[8:11]+r[16:25]` (`:731`). Layout documented at `:661-678`: * 0–8: column-major 3×3 model→camera rotation * 9–11: origin of rotation relative to camera (camera space) * 12–14: origin of rotation (model space) * 15: front plane distance * 16: rear plane distance * 17: orthoscopic flag (sign) and field of view when `abs(value) > 1` * camera looks down −Z, +X left, +Y down. `output` modes: 0 = print, 1 = don't, 2 = force print even while logging, 3 = return a formatted `set_view (...)` string (`:651-657`, `:723-730`). When `logging` is on it writes the matrix to the log file (`:695-712`). `cmd.set_view(view, animate=0, quiet=1, hand=1)` — `packages/engine/modules/pymol/viewing.py:734`. Accepts a string (parsed by `safe_list_eval`) or a sequence; **must be exactly 18 floats** or it raises "bad view argument; should be a sequence of 18 floats" (`:764-769`). It re-expands to the 25-float form with an embedded 4×4 (`:772-780`). `cmd.view(key, action='recall'|'store'|'clear', animate=-1)` — `packages/engine/modules/pymol/viewing.py:783`. This is a **pure-Python dictionary** `pymol._view_dict` + `_view_dict_sc` shortcut (`:819-850`); `key='*'` lists or clears all (`:821-830`). Saved into sessions by `session_save_views`/`session_restore_views` (`:1187`, `:1192`). F1–F12 fall back to views when no scene matches (see §11). ### 9.2 Camera animation `SceneSetView(G, view, quiet, animate, hand)` interpolates through `ani_elem` key frames using `ViewElemInterpolate(..., 2.0F, 1.0F, true, 0.0F, hand, 0.0F)` (`packages/engine/layer1/Scene.cpp:411-427`), with `timing` stamps for start and `start+duration`. ### 9.3 Camera commands | cmd | signature | source | | -------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `zoom` | `(selection="all", buffer=0.0, state=0, complete=0, animate=0)` | `packages/engine/modules/pymol/viewing.py:66`; `animate<0` = default duration, `0` = none, `>0` = seconds (`:98-102`) | | `center` | `(selection="all", state=0, origin=1, animate=0)` | `:134` | | `orient` | `(selection="(all)", state=0, animate=0)` | `:310` — aligns principal components to XYZ | | `origin` | `(selection="(all)", object=None, position=None, state=0)` | `:256` — `position` overrides selection (`:299-302`) | | `clip` | `(mode, distance, selection=None, state=0)` | `:181`; modes `near, far, move, slab, atoms, near_set, far_set` (`:179`) | | `get_clip` | `(quiet=1)` | `:228` → `_cmd.get_clip` | | `turn` | `(axis, angle)` | `:1300` — rotates camera about a primary axis, centered on the origin | | `move` | `(axis, distance)` | `:352` — translates the camera | | `reset` | `(object='')` | `:1774` — identity rotation, origin ≈ center of mass, zoom to all; with an object name resets that object's matrix | | `viewport` | `(width=-1, height=-1)` | `:1459`; tuple syntax deprecated with a warning (`:1476-1478`); off-GUI-thread calls are deferred through `cmd.do` (`:1480-1482`) | | `get_viewport` | `(output=1, quiet=1)` | `:853`; `output==3` returns a deprecated string (`:893-895`) | | `stereo` | `(toggle='on', quiet=1)` | `:1266`; `on, off, crosseye, walleye, quadbuffer, sidebyside, geowall, openvr` (`:1278`) | | `full_screen` | `(toggle=-1)` | `:1329`; must run on the GUI thread, else deferred (`:1355-1357`) | | `refresh` | `()` | `:1750` | | `meter_reset` | `()` | `:1800` → `_cmd.reset_rate` (FPS counter) | | `load_png` | `(filename, movie=1, stereo=-1, quiet=0)` | `:1814` | ### 9.4 Rock / spin / nutate (live, not movie) `cmd.rock(mode=-1)` → `_cmd.rock` → `ControlRock(G, mode)` (`packages/engine/modules/pymol/viewing.py:1360`, `packages/engine/layer1/Control.cpp:415-439`): * `-2` = query only (returns the current `rock` setting without touching it) * `-1` = toggle (default), `0` = off, `1` = on * turning on restarts the sweep timer; any non-`-2` mode restarts the frame timer. `cmd.ray` uses the `-2` query then `rock(0)` to stop rocking before rendering (`packages/engine/modules/pymol/viewing.py:1738-1739`). `SceneUpdateCameraRock` (`packages/engine/layer1/Scene.cpp:2373-2427`) — `sweep_mode`: * 0 = Y-axis rock, 1 = X-axis rock, 2 = Z-axis rock ("useless!", `:2405`) * 3 = nutate (combined X/Y sinusoid with a π/2 phase shift, amplitude ramped in over the first half period, `:2411-2425`) * `sweep_angle <= 0` degenerates into a **continuous spin** at `10*sweep_speed/0.75` deg-ish per render second (`:2390-2392`). * Phase from `sweep_phase`, speed from `sweep_speed`, tick rate from `rock_delay` ms. `ControlIdling` (`packages/engine/layer1/Control.cpp:397-403`) keeps the idle loop alive while any of sdof / movie playing / `rock` / `sculpting` is active. *** ## 10. Internal GUI control bar (9 buttons, in-viewport) `CControl` block, `NButton = 9` (`packages/engine/layer1/Control.h`/`packages/engine/layer1/Control.cpp:62`), hit test `which_button` = `(NButton * x) / control_width` (`packages/engine/layer1/Control.cpp:243-252`). Release actions (`packages/engine/layer1/Control.cpp:290-380`): | # | glyph | action | logged as | | - | ----- | ----------------------------------------------------- | ------------------------------- | | 0 | `\|<` | `SceneSetFrame(G,4,0)` | `cmd.rewind()` | | 1 | `<` | `SceneSetFrame(G,5,-1)` | `cmd.back()` | | 2 | `■` | `MoviePlay(stop)`, also clears `sculpting` and `rock` | `cmd.mstop()` | | 3 | `▶` | toggle play; Ctrl → rewind first | `cmd.mplay()` / `cmd.mstop()` | | 4 | `>` | `SceneSetFrame(G,5,1)` | `cmd.forward()` | | 5 | `>\|` | `ending`; Ctrl → `middle` | `cmd.ending()` / `cmd.middle()` | | 6 | seq | toggle `seq_view` + `SeqChanged` | `cmd.set('seq_view',0/1)` | | 7 | rock | toggle `rock` + restart sweep/frame timers | `cmd.rock(1)` / `cmd.rock(0)` | | 8 | full | full screen | `cmd.full_screen()` | Double-clicking the left margin collapses/restores `internal_gui_width` to `cControlMinWidth` (`packages/engine/layer1/Control.cpp:449-464`); dragging it resizes. External Qt quick-button rows (`packages/engine/modules/pmg_qt/pymol_qt_gui.py:223-253`) — the movie row is `|<`, `<`, `Stop`, `Play`, `>`, `>|`, `MClear` bound to `cmd.rewind/backward/mstop/mplay/ forward/ending/mclear`; the row above has `Unpick`, `Deselect`, `Rock` (`cmd.rock`), `Get View`; the top row has `Reset`, `Zoom (animate=1.0)`, `Orient (animate=1.0)`, `Draw/Ray`. Legacy Tk equivalents at `packages/engine/modules/pmg_tk/skins/normal/__init__.py:266-281`. *** ## 11. Keyboard bindings in this area `packages/engine/modules/pymol/shortcut_dict.py` (defaults; user-overridable through `cmd.set_key`, `packages/engine/modules/pymol/controlling.py:746-757`): | key | command | line | | ----------------- | ---------------------------- | ---------- | | `left` | `_ backward` | `:11` | | `right` | `_ forward` | `:12` | | `pgup` | `scene action=previous` | `:13` | | `pgdn` | `scene action=next` | `:14` | | `home` | `zoom animate=-1` | `:15` | | `end` | `mtoggle` | `:16` | | `insert` | `rock` | `:17` | | `SHFT-left/right` | `backward` / `forward` | `:18-19` | | `SHFT-pgup/pgdn` | previous / next scene | `:20-21` | | `SHFT-home` | `rewind` | `:22` | | `SHFT-end` | `ending` | `:23` | | `SHFT-insert` | `rock` | `:24` | | `CTRL-left/right` | `backward` / `forward` | `:25-26` | | `CTRL-pgup` | `_ scene new, insert_before` | `:27` | | `CTRL-pgdn` | `_ scene new, insert_after` | `:28` | | `CTRL-home` | `zoom animate=-1` | `:29` | | `CTRL-end` | `scene new, store` | `:30` | | `CTRL-insert` | `scene auto, store` | `:31` | | `ALT-left/right` | `backward` / `forward` | `:43-44` | | `ALT-pgup/pgdn` | `rewind` / `ending` | `:45-46` | | `ALT-home` | `zoom animate=-1` | `:47` | | `ALT-end` | `ending` | `:48` | | `ALT-insert` | `rock` | `:49` | | `CTRL-F1..F12` | `scene F, store` | `:112-135` | | `CTSH-F1..F12` | `scene SHFT-F, store` | `:112-135` | Bare **F1–F12 have no default binding**; `_special` (`packages/engine/modules/pymol/internal.py:447-484`) first checks explicit `set_key` mappings, then tries `cmd.scene` against `get_scene_list()`, then `cmd.view` against `pymol._view_dict_sc`, including a prefix auto-completion pass with `key + '-'` (`:469-480`). Special key codes are at `packages/engine/modules/pymol/internal.py:398-424`; modifier prefixes `'', SHFT, CTRL, CTSH, ALT` (`:395-401`). **Spacebar** (`packages/engine/layer1/Ortho.cpp:855-874`): only when the command line is empty. In `presentation` mode plain space = `cmd.scene('','next')`, Shift+space = `rewind;mplay`. Otherwise plain space = `mtoggle`, Shift+space = `rewind;mplay`. *** ## 12. Sequence viewer ("Seeker") ### 12.1 What it is today Two C++ pieces: * **`CSeq`** — the Ortho block: layout, scrollbar, hit-testing, GL text drawing (`packages/engine/layer1/Seq.h:73`, `packages/engine/layer1/Seq.cpp:259` `CSeq::draw`). Metrics: `LineHeight = 13`, `CharWidth = 8`, `ScrollBarWidth = 16`, `ScrollBarMargin = 2`, `CharMargin = 2` (`packages/engine/layer1/Seq.h:84-88`), all scaled by `DIP2PIXEL`. Total height = `LineHeight*NRow + 4` (+ scrollbar) (`packages/engine/layer1/Seq.cpp:190-201`). * **`CSeeker`** — the data model + interaction handler (`packages/engine/layer3/Seeker.cpp:38`), installed via `SeqSetHandler` at the end of `SeekerUpdate` (`packages/engine/layer3/Seeker.cpp:1948`). Refresh protocol: `SeqChanged` marks "rebuild" and `SeqDirty` marks "recompute selection highlight" (`packages/engine/layer1/Seq.cpp:136-148`); `SeqUpdate` runs `SeekerUpdate` then `Handler->refresh` (`packages/engine/layer1/Seq.cpp:88-102`). ### 12.2 Row/column data model `CSeqRow` (`packages/engine/layer1/Seq.h:42-57`): `txt` (one flat char buffer for the row), `col[]`, `fill[]`, `char2col[]` (character-offset → 1-based column index), `atom_lists[]` (a packed, `-1`-terminated list of atom indices per column), `name` (object name), `color` (object color), `label_flag`, `column_label_flag`, `ext_len`, `title_width`. `CSeqCol` (`packages/engine/layer1/Seq.h:25-37`): `start`/`stop` (slice into `txt`), `offset` (aligned character column), `atom_at` (index into `atom_lists`), `inverse` (**selected** — drives the inverted-video highlight, `packages/engine/layer1/Seq.cpp:465-482`), `unaligned`, `spacer`, `state`, `color` (PyMOL color index), `tag` (alignment tag), `is_abbr`, `hint_no_space`. So the wire payload for a React sequence viewer is, per object row: `{ object, objectColor, isLabelRow, cells: [{ text, offset, colorIndex|rgb, selected, spacer, unaligned, state, tag, atomIndices }] }`, plus the label rows. **No such cmd API exists today** — see §14. ### 12.3 Display modes (`seq_view_format`) `SeekerUpdate` (`packages/engine/layer3/Seeker.cpp:969`), `codes` read from `seq_view_format` (`:1016`), overridden to `4` for discrete objects when `seq_view_discrete_by_state` (`:1017-1020`): | value | mode | source | notes | | ----- | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0 | **one-letter residue codes** | `:1260-1328` | `SeekerGetAbbr` maps 3-letter → 1-letter (`:685-906`); water → `'O'`; organic/inorganic get no abbreviation and fall back to the full `resn` padded with spaces (`:1284-1311`) | | 1 | **explicit residue codes** (3-letter) | `:1329-1370` | space-separated; empty `resn` renders `''` | | 2 | **atom names** | `:1371-1395` | one column per atom | | 3 | **chain identifiers** | `:1396-1422` | one column per chain | | 4 | **state names** | `:1423-1482` | discrete objects list per-CoordSet names; non-discrete objects enumerate all states with `r1->state = b+1` and a shared atom list (`:1448-1481`) | | 5 | movie frames | `:1483-1484` | **declared but empty — no-op** | Menu labels (`packages/engine/modules/pymol/_gui.py:379-387`): Residue Codes (0), Residue Names (1), Chain Identifiers (3), Atom Names (2), States (4). ### 12.4 Label modes (`seq_view_label_mode`, global, default 2) `packages/engine/layer3/Seeker.cpp:987`, `:1028-1101`: * **2 — All Residue Numbers**: a dedicated label row above *every* object row. * **1 — Top Sequence Only**: a single label row for the first object only. * **0 — Object Names Only**: no label rows; the object name `/name` occupies the left-hand column of the sequence row itself (`column_label_flag`, `:1079-1092`). * **3 — No Labels**: a zero-length spacer column (`:1093-1101`). Label rows also carry `/segi/chain/` breadcrumbs, re-emitted whenever the segment (`:1147-1182`) or chain (`:1183-1215`) changes. Residue-number labels are laid out in a third pass (`packages/engine/layer3/Seeker.cpp:1820-1914`): drawn every `seq_view_label_spacing` residues (default 5) offset by `seq_view_label_start` (default 1) (`:1842-1843`, `:1858-1862`), forced at sequence gaps (`:1866-1867`), forced if more than `2*div` were skipped (`:1868-1869`), never twice for the same residue (`:1871-1872`), and suppressed if they would collide with a fixed label (`:1895-1904`). In atom-name mode the label is `resn` + `` ` `` + `resi` (`:1878-1887`). ### 12.5 Gaps (`seq_view_gap_mode`, global, default 1) `packages/engine/layer3/Seeker.cpp:1009`, `:1230-1258`. `GapMode::NONE / ALL(1) / SINGLE(2)`. Gaps are only inserted between atoms in the same chain, both polymer, and only when no alignment is active (`:1232-1235`). Gap count = `resv - last_resv - 1`; SINGLE clamps to 1 (`:1238-1240`). More than `MAXCONSECUTIVEGAPS = 9` (`:983`) collapses to `"---...---"` (mode 0) / `"---...--- "` (mode 1) (`:1275-1277`, `:1346-1348`). Gap columns get `color = seq_view_fill_color` and `spacer = true` (`:1250-1251`). Menu labels: No Gaps (0), All Gaps (1), Single Gap (2) (`packages/engine/modules/pymol/_gui.py:401-405`). ### 12.6 Alignment mode When an alignment is active (`ExecutiveGetActiveAlignmentSele`, `packages/engine/layer3/Executive.cpp:3375`, resolved from `seq_view_alignment` or the first enabled alignment object, `:3391-3409`), the second pass lines rows up by `tag` instead of by column index (`packages/engine/layer3/Seeker.cpp:1584-1818`). Tags come from `SeekerFindTag` (`:928-967`), which prefers the guide atom for residue-level modes. `seq_view_unaligned_mode` (0–5) decides staggering (`:1590-1599`) and how unaligned residues are colored (`packages/engine/layer1/Seq.cpp:320-339`, `:423-455`): modes 1/4 average the residue color with the background, 2/5 average with `seq_view_unaligned_color`, 3 leaves the color alone; otherwise the unaligned color is used flat. `seq_view_fill_char` (default `-`) fills alignment gaps in `seq_view_fill_color` (`packages/engine/layer1/Seq.cpp:316`, `:341-346`, `:488-505`). ### 12.7 Coloring Per-column color (`packages/engine/layer3/Seeker.cpp:1313-1318` and mirrored in the other code paths): * atom not present in the current state → `seq_view_fill_color` * `seq_view_color < 0` (default `-1`) → `SeekerFindColor` (`:908-926`): prefer the guide atom's color, else the last carbon's color, else the first atom's color * otherwise the explicit `seq_view_color`. Row label text uses `seq_view_label_color` (default `front`) (`packages/engine/layer1/Seq.cpp:269-271`). Background is `bg_rgb`, or `bg_rgb_top`/`bg_rgb_bottom` when `bg_gradient` and depending on `seq_view_location` (`packages/engine/layer1/Seq.cpp:273-281`). ### 12.8 Placement / overlay `seq_view_location` — 0 = top, 1 = bottom (`packages/engine/layer1/Ortho.cpp:2181`, `:2418`). `seq_view_overlay` — draw over the 3D scene instead of reserving space (`packages/engine/layer1/Seq.cpp:282-289`, `packages/engine/layer1/Ortho.cpp:2425-2437`, `packages/engine/layer5/main.cpp:817`, `:1500`). The whole viewer is gated per object by the `seq_view` setting **and** the object being enabled, and `_`-prefixed objects are skipped when `hide_underscore_names` (`packages/engine/layer3/Seeker.cpp:991-993`). Max 50 rows (`max_row = 50`, `packages/engine/layer3/Seeker.cpp:980`, `:1013`). ### 12.9 Interaction — the full grammar Hit test: `SeqFindRowCol` (`packages/engine/layer1/Seq.cpp:36-86`) maps (x,y) → (row, col) via `char2col`, accounting for `NSkip` (horizontal scroll) and `label_flag` rows (which are not clickable). During a drag the row is pinned to `LastRow` (`packages/engine/layer1/Seq.cpp:158`, `:175`). `SeekerClick` (`packages/engine/layer3/Seeker.cpp:317`): | input | effect | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Left click on a cell** | toggles that residue in the active selection: `SeekerSelectionToggle(..., inc_or_excl = !col->inverse)` (`:450-456`). Starts a drag range (`dragInfo.start_col/last_col/row/dir`). | | **Shift + Left click** on the same row | *continuation* — extends the existing range (`:350-355`, `:447-448` → `SeekerDrag`) | | **Ctrl + Left click** | additionally `SeekerSelectionCenter(G, 2)` = center on the active selection (`:419-421`, `:460-461`) | | **Left drag** | extends/retracts the range with correct direction flipping; `SeekerSelectionToggleRange` per span (`:527-624`). Ctrl during drag re-centers each step (`:619-621`) | | **Middle click** | *browse*: builds `cTempCenterSele` from that column and `cmd.center`s it (`:397-412` → `SeekerSelectionUpdateCenter` `:248`, `SeekerSelectionCenter` `:275`) | | **Ctrl + Middle** | same but `cmd.zoom` instead of `cmd.center` (action 1, `:405`, `:291-298`) | | **Shift + Middle drag** | accumulates columns into the center selection instead of restarting (`:633-664`) | | **Right click on a selected cell** | opens the `pick_sele` menu for the active selection (`:363-364`) | | **Right click on an unselected cell** | builds `cTempSeekerSele` and opens the `seq_option` menu, titled with `ObjectMoleculeGetAtomSele(...)` truncated at the last `/` (`:365-393`, menu at `packages/engine/modules/pymol/menu.py:1800-1840`) | | **Right click outside any cell** | `pick_sele` menu for the active selection (`packages/engine/layer1/Seq.cpp:240-248`) | | **Left double-click outside any cell** (\<0.35 s, `cDoubleTime` `packages/engine/layer3/Seeker.cpp:315`) | clears the active selection: `cmd.select('','none', enable=1)` (`:328-341`) | | **Wheel** | horizontal scroll by ±1 (`packages/engine/layer1/Seq.cpp:218-223`) | | **Click on the scrollbar strip** | scrollbar drag (`packages/engine/layer1/Seq.cpp:226-231`) | | Clicking a cell that carries a `state` | sets that object's `state` setting and `SceneChanged` (`packages/engine/layer3/Seeker.cpp:463-466`, `:408-411`) | | State-mode guard | in `codes == 4` on non-discrete objects the columns are **not** selectable (`:427`) | Selection algebra (`SeekerSelectionToggle`, `packages/engine/layer3/Seeker.cpp:169-246`; range variant `:70-167`): * The active selection name comes from `ExecutiveGetActiveSeleName(create_new=true)` (`packages/engine/layer3/Executive.cpp:3420`), auto-numbered `selNN` when `auto_number_selections` (`:3436-3443`). * `sele_mode_kw` = `SceneGetSeleModeKeyword` (`packages/engine/layer1/Scene.cpp:504`), one of `"" \| byresi \| bychain \| bysegi \| byobject \| bymol \| bca.` indexed by `mouse_selection_mode` (`packages/engine/layer1/Scene.cpp:460-468`). * Include: `((KW(?sele)) or KW(?tmp))`; Exclude: `((KW(?sele)) and not KW(?tmp))`; Fresh: `KW(?tmp)` (`packages/engine/layer3/Seeker.cpp:130-140`, `:202-221`). * Emits an equivalent `cmd.select("","",enable=1)` line to the log (`:146-149`, `:227-230`) — **this is exactly the API the React component should call**. * `auto_show_selections` → `ExecutiveSetObjVisib(sele, 1)` (`:161-162`, `:241-242`). Highlight sync: `SeekerRefresh` (`packages/engine/layer3/Seeker.cpp:475-525`) recomputes `col->inverse` for every column by testing `SelectorIsMember(atInfo[at].selEntry, sele)` against the active selection (falling back to a selection literally named `_seeker_hilight`, `:484`). Drag box overlay: `CSeqHandler::box_active / box_row / box_start_col / box_stop_col` (`packages/engine/layer1/Seq.h:67-70`), drawn as a line loop with spacer trimming (`packages/engine/layer1/Seq.cpp:510-563`). The scrollbar itself renders a **mini-map** of the selection: colored ticks per contiguous `inverse` run, one horizontal band per non-label row (`packages/engine/layer1/Seq.cpp:564-696`). *** ## 13. Settings that this area owns From `packages/engine/layer1/SettingInfo.h` (id, name, scope, default): **Movie:** `single_image` 15 g 0 (`:99`) · `movie_delay` 16 g 30.0 (`:100`) · `ray_trace_frames` 30 g 0 (`:114`) · `cache_frames` 31 g 0 (`:115`) · `all_states` 49 object 0 (`:133`) · `static_singletons` 82 object 1 (`:166`) · `movie_loop` 299 object 1 (`:388`) · `movie_fps` 550 g 30.0 (`:650`) · `movie_animate_by_frame` 565 g 0 (`:665`) · `movie_rock` 572 g -1 (`:672`) · `keep_alive` 607 g 0 (`:707`) · `show_frame_rate` 617 g 0 (`:717`) · `movie_panel` 618 g 1 (`:718`) · `movie_auto_store` 620 object -1 (`:720`) · `movie_auto_interpolate` 621 object 1 (`:721`) · `movie_panel_row_height` 622 g 15 (`:722`) · `movie_quality` 634 g 90 (`:734`) · `frame` 194 g 1 (`:279`) · `state` 193 object 1 (`:278`). Also `draw_frames` (referenced by the menu, `packages/engine/modules/pymol/_gui.py:369`, and by `cmd.mpng` mode resolution `packages/engine/modules/pymol/moving.py:392-393`). **Rock / sweep:** `sweep_angle` 26 g 20.0 (`:110`) · `sweep_speed` 27 g 0.75 (`:111`) · `rock_delay` 56 g 30.0 (`:140`) · `sweep_mode` 401 g 0 (`:496`) · `sweep_phase` 402 g 0.0 (`:497`). **Scene:** `animation` 388 g 1 (`:483`) · `animation_duration` 389 g 0.75 (`:484`) · `scene_animation` 390 g -1 (`:485`) · `scene_current_name` 396 g "" (`:491`) · `presentation` 397 g 0 (`:492`) · `presentation_mode` 398 g 1 (`:493`) · `scene_loop` 400 g 0 (`:495`) · `scene_restart_movie_delay` 403 g 1 (`:498`) · `mouse_restart_movie_delay` 404 g 0 (`:499`) · `scene_animation_duration` 411 g 2.25 (`:506`) · `presentation_auto_quit` 415 g 1 (`:510`) · `presentation_auto_start` 417 g 1 (`:512`) · `scene_buttons_mode` 598 **unused** 1 (`:698`) · `scene_buttons` 599 g 1 (`:699`) · `scene_frame_mode` 623 g -1 (`:723`) · `scenes_changed` (change signal, `packages/engine/layer3/MovieScene.cpp:833`). **Sequence viewer:** `seq_view` 353 object 0 (`:448`) · `seq_view_label_spacing` 355 object 5 (`:450`) · `seq_view_label_start` 356 object 1 (`:451`) · `seq_view_format` 357 object 0 (`:452`) · `seq_view_location` 358 g 0 (`:453`) · `seq_view_overlay` 359 g 0 (`:454`) · `seq_view_color` 362 ostate "-1" (`:457`) · `seq_view_label_mode` 363 g 2 (`:458`) · `seq_view_discrete_by_state` 410 object 1 (`:505`) · `seq_view_alignment` 513 g "" (`:613`) · `seq_view_unaligned_mode` 514 g 0 (`:614`) · `seq_view_unaligned_color` 515 g "-1" (`:615`) · `seq_view_fill_char` 516 g "-" (`:616`) · `seq_view_fill_color` 517 g "104" (`:617`) · `seq_view_label_color` 518 g "front" (`:618`) · `seq_view_gap_mode` 767 g 1 (`:877`). Related: `mouse_selection_mode` 354 g 1 (`:449`), `auto_show_selections`, `hide_underscore_names`. Display menu entries that map to these: `packages/engine/modules/pymol/_gui.py:378-406`. *** ## 14. What upstream does not expose, and what the bridge added Four things this area needs have no upstream Python API. Each is now supplied by a bridge module that installs extra callables onto the `cmd` namespace, so the client reaches them the same way it reaches any other `cmd.*` symbol. 1. **No structured movie-panel data upstream.** `cmd.mdump` only prints (`packages/engine/layer1/Movie.cpp:378-403`). `MovieGetSpecLevel(G, frame)` (`packages/engine/layer1/Movie.cpp:163`) is C-only; it is not in the `_cmd` method table (`packages/engine/layer4/Cmd.cpp:6549-6562`). Supplied as `cmd.get_movie_panel` / `get_movie_status` / `get_movie_key_frames` (`packages/bridge/tenmol_bridge/panels/movie.py`, `EXPORTS`), typed in `packages/protocol/src/topics/movie_panel.ts`, consumed by `apps/web/src/features/movie/movieSource.ts`. 2. **No structured sequence-viewer data upstream.** `SeekerUpdate` writes only into `G->Seq->Row` (`packages/engine/layer3/Seeker.cpp:1947`). `cmd.get_fastastr` (`packages/engine/modules/pymol/exporting.py:170`) gives sequences but **no colors, no per-cell atom indices, no selection state, no gaps, no alignment offsets**, and it only covers polymers (`:198`). `cmd.get_seq_align_str` exists (`packages/engine/layer4/Cmd.cpp:6490`) but is an alignment export, not the viewer model. The §12.2 payload is rebuilt from `cmd` queries in `packages/bridge/tenmol_bridge/panels/seqview.py` (entry point `tenmol_seqview`), consumed by `apps/web/src/features/seqview/source.ts`. 3. **No scene metadata bundle upstream.** Qt makes N round-trips (`get_scene_list` + `get_scene_thumbnail` per scene, `scene_bin_gui.py:169-192`). Supplied as `cmd.get_scene_panel` + `cmd.get_scene_thumbnail_png` (`panels/movie.py`), backed by the existing `MovieSceneGetThumbnail` / `MovieSceneGetMessage` (`packages/engine/layer3/MovieScene.h:170-173`). 4. **No event stream upstream.** Everything is polled or push-from-C via `OrthoDirty`. The bridge publishes `frame`, `view`, `settings`, `objects`, `feedback` and the rest as protocol topics (`packages/protocol/src/topics/`), with scene changes reaching the client through `scenes.ts` and playback state through `movie.ts`. **Menus are Python data, not C.** `get_menudata` (`packages/engine/modules/pymol/_gui.py:55`) and `packages/engine/modules/pymol/menu.py` return plain nested lists of `('command'|'menu'|'check'|'radio'|'separator', label, payload)`, which the port consumes nearly verbatim (compare the Qt walker at `packages/engine/modules/pmg_qt/pymol_qt_gui.py:298-342` with `apps/web/src/features/menubar/menuSource.ts`). *** ## 15. Where each surface lives now | Surface | Replaces | Backend contract | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `features/movie/movieMenu.ts` | `_gui.py:234-376` | `cmd.movie.*`, `cmd.mset/mclear/meter_reset`, settings | | `features/movie/MovieTimeline.tsx` | `CMovie` block (`packages/engine/layer1/Movie.cpp:1741`) | `cmd.get_movie_panel`; writes via `cmd.mmove/mcopy/minsert/mdelete/mview` | | `features/movie/TransportBar.tsx` | `CControl` (`packages/engine/layer1/Control.cpp:288` release, `:536` draw) + Qt row (`pymol_qt_gui.py:241-247`) | `rewind/backward/mstop/mplay/mtoggle/forward/ending/middle/mclear/rock/full_screen` | | `features/movie/MovieTimeline.tsx` state slider | scrollbar in `CMovie::draw` (`packages/engine/layer1/Movie.cpp:1775`) | `cmd.frame`, `cmd.set_frame`, `count_frames`, `count_states` | | `features/scenes/ScenePanel.tsx` | `scene_bin_gui.py:29` | `cmd.get_scene_panel`, `cmd.scene`, `cmd.scene_order`, `set_scene_message` | | `features/scenes/sceneButtonGeometry.ts` | `SceneDrawButtons` (`packages/engine/layer1/Scene.cpp:2885`) | `get_scene_list`, `scene_current_name`, `cmd.scene`, `cmd.scene_order` | | `features/scenes/SceneMenu.tsx` | `menu.py:1842` | `cmd.scene(...,'update'/'delete'/'rename')` | | `features/seqview/SequenceViewer.tsx` | `CSeq`+`CSeeker` (`packages/engine/layer1/Seq.cpp:259`, `packages/engine/layer3/Seeker.cpp:969`) | `tenmol_seqview`; writes via `cmd.select(name, expr, enable=1)`, `cmd.center/zoom`, `cmd.set('state',…)` | | `features/seqview/grammar.ts` | `menu.py:1800`, `:1709` | the literal command strings in those menus | | `features/movie/ExportDialog.tsx` | `file_dialogs.py:691` + `movieexport.ui` | `cmd.mpng`, `cmd.movie.produce`, `get_viewport` | | `features/movie/motionMenu.ts` | `menu.py:108`, `:126` | `cmd.mview(...)`, `cmd.mset()`, `cmd.reset(object=)` | | `packages/viewport/src/resize.ts` | `cmd.viewport` (`viewing.py:1459`) | resizes the WebGL canvas *and* the backend offscreen buffer | Paths are relative to `apps/web/src/` unless stated otherwise. \| Key handler | `shortcut_dict.py`, `internal.py:447` | forward to `cmd.do`, with F1–F12 scene/view fallback replicated client-side | Rendering notes for the timeline and sequence viewer: both are dense 1-D grids (hundreds to tens of thousands of cells). Use a canvas/WebGL2 layer with an offscreen color-index texture for hit-testing rather than one DOM node per cell — the existing C code already thinks in terms of "column index → pixel offset" (`CSeqCol::offset`, `ViewElemXtoFrame`), so the same math ports directly.