​

Movies, Scenes, States/Frames, Sequence Viewer

​

0. Executive summary of the area

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).

​

Why parts of this area are server-rendered raster, not geometry

• 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).

​

1. Frames & states — exact semantics

​

1.1 Frame/state queries

​

1.2 SceneSetFrame(G, mode, frame) — the whole navigation vocabulary

​

1.3 Playback loop

• 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).

​

2. mset — the frame↔state program

• 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).

​

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.

​

4. Key frames — mview and CViewElem

​

4.1 Python surface

• 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

​

4.3 Frame-range editing (mmove / mcopy / mdelete / minsert)

​

5. The Movie Panel (in-viewport upstream)

​

5.1 Complete mouse grammar of the panel

​

5.2 Panel context menus

• 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

​

6. Movie menu (menu bar) — full enumeration

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)

​

6.1 “Last program” bookkeeping

​

7. Movie programs (pymol.movie) — full API

​

7.1 Legacy mdo-based generators (write per-frame commands)

​

7.2 Key-frame based generators (the ones the Movie menu uses)

​

7.3 Export

• 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 <basename>.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 unsets it afterwards (:971, :811).
• A _watch thread prints byte counts while encoding (:658-685).

​

7.4 Export dialog (Qt)

​

8. Scenes

​

8.1 cmd.scene — the one entry point

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")

• 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

• 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).

​

8.3 Scene helper cmds

​

8.4 Scene menu (menu bar)

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)

• 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)

• 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).

​

9. Camera: view get/set, interpolate, turn/move/zoom/orient/clip, rock

​

9.1 View vector

• 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.

​

9.2 Camera animation

​

9.3 Camera commands

​

9.4 Rock / spin / nutate (live, not movie)

• -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).

• 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.

​

10. Internal GUI control bar (9 buttons, in-viewport)

​

11. Keyboard bindings in this area

​

12. Sequence viewer (“Seeker”)

​

12.1 What it is today

• 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).

​

12.2 Row/column data model

​

12.3 Display modes (seq_view_format)

​

12.4 Label modes (seq_view_label_mode, global, default 2)

• 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).

​

12.5 Gaps (seq_view_gap_mode, global, default 1)

​

12.6 Alignment mode

​

12.7 Coloring

• 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

​

12.9 Interaction — the full grammar

• 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("<name>","<expr>",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).

​

13. Settings that this area owns

​

14. What upstream does not expose, and what the bridge added

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.

​

15. Where each surface lives now