Skip to content

Add timestamped scene frame capture to Manager - #5008

Open
behackl wants to merge 1 commit into
refactor/timeline-exportfrom
refactor/manager-targeted-frame
Open

behackl wants to merge 1 commit into
refactor/timeline-exportfrom
refactor/manager-targeted-frame

Conversation

@behackl

@behackl behackl commented Sep 9, 2026

Copy link
Copy Markdown
Member

Overview: What does this pull request change?

Stacked on #5006.

Adds Manager.capture_frame_at(timestamp) to execute a fresh scene up to a requested frame and return its image and timing information. Both Cairo and OpenGL use the same Manager implementation.

with tempconfig({"frame_rate": 4, "live_preview": False}):
    scene = MyScene()
    manager = Manager(scene)
    frame = manager.capture_frame_at(0.3)
    if frame is not None:
        print(frame.time)  # 0.25
        frame.image.save("frame.png")

The new RenderedFrame result contains an independent PIL image, the requested time, the selected frame's start time, and its zero-based index. Requests at or beyond the end of the frame sequence return None.

Motivation and Explanation: Why and how do your changes improve the library?

Preview tools often need the image displayed at a particular animation time. This provides a public operation that runs the scene's Python code and normal animation steps, draws the preceding frames, and captures the selected frame.

Manager coordinates execution through the existing renderer drawing and pixel-readback methods. A shared delivery helper sends frames to the writer during ordinary rendering or captures the requested image. Frozen waits use their repeated frame intervals, and stop-condition waits contribute the frames actually reached.

At the selected frame, playback stops with the current animation at its captured state. Python finally blocks run, followed by tear_down() for cleanup. The returned image retains its pixels after cleanup and renderer closure. Successful capture respects an enclosing with manager: resource scope; scene errors propagate after cleanup is attempted.

Each request uses a fresh scene configured with live_preview=False. For an image of an existing scene's current state, get_image() remains the appropriate operation. The method documentation cross-references these two uses.

Links to added or changed documentation pages

  • Manager.capture_frame_at, Manager.get_image, and the new RenderedFrame reference documentation, including an executable usage example.

@behackl
behackl added this pull request to stack #5003 September 9, 2026 10:17
@behackl behackl added the new feature Enhancement specifically adding a new feature (feature request should be used for issues instead) label Sep 9, 2026
@behackl
behackl force-pushed the refactor/manager-targeted-frame branch from 0fc4f75 to 4dd018e Compare September 10, 2026 08:24
@behackl
behackl force-pushed the refactor/manager-targeted-frame branch from 4dd018e to 9efbbe0 Compare September 10, 2026 09:51
@behackl behackl mentioned this pull request Sep 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

new feature Enhancement specifically adding a new feature (feature request should be used for issues instead)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant