camera
Dragonframe scripting and automation
Dragonframe / High-resolution RAW capture and video assist in stop motion
Definition
Dragonframe scripting and automation covers the ways the capture software tells other software what it is doing, and lets other code act on it. There are three layers. Action scripts are shell or batch files that Dragonframe runs on capture events. OSC output sends the current frame position to outside programs. A Python and PySide interface, still in development for Dragonframe 2027, lets studio tools listen to events, read a scene's frames and add their own menus. None of it changes how a frame is animated. It changes what happens around each frame, such as backups, RAW processing, reference playback and production tracking.
Overview
A stop-motion stage spends almost all of its time waiting on a person. The animator moves the puppet, steps back, and fires one frame. Everything that happens between those frames is overhead that a computer can do better than a person, if it knows when to do it: copying the new RAW file to a second drive, converting it for review, logging the frame to a tracking system, cueing a reference clip. Dragonframe's automation features exist to supply that 'when'. This book treats them as one subject because they share one idea. The capture software announces events, and the studio's own tools listen and respond.
The oldest and simplest layer is the action script. Dragonframe can call a local script file whenever certain events occur. That file is a bash script (.sh) on macOS or Linux, or a batch file (.bat) on Windows. The documented events follow the life of a frame and a take: SHOOT, CAPTURE COMPLETE when the high-resolution download finishes, FRAME COMPLETE when every exposure for the frame is done, POSITION FRAME when the software is ready for the next capture, TEST for a test shot, and DELETE, EDIT, CONFORM and NEW_TAKE for changes to the timeline. Dragonframe's own suggested uses are telling. They are backing up high-resolution images as they arrive, colour-processing RAW files as they download, and notifying a content management system when a frame is captured. These are production-office jobs, done at frame rate.
The second layer faces outward to other real-time software. Dragonframe can send OSC (Open Sound Control) messages on its Position Frame event. Its FAQ shows how to keep a reference video in Resolume Arena or MadMapper locked to the current frame, sending the frame time in milliseconds or the frame number to the address each program expects. The practical case is projection and live reference. When a projected image or a playback clip has to match the frame being animated, it can follow the timeline instead of being scrubbed by hand. The same protocol drives Arc motion-control axes from an outside console (see Arc motion control).
The third layer is still being built. Dragonframe documents a Python and PySide (Qt 6.11) integration for its 2027 release, available at present as the 2027.01 development build. At startup it reads ~/Dragonframe/scripts/__init__.py and any further init files listed in DRAGONFRAME_PYTHON_INIT. Its modules let a script add menu items and shortcuts (ui), register callbacks for events such as Shoot, CaptureComplete, FrameComplete, Delete, Position and Save (events), read frame and exposure file paths, manage notes, load reference images or movies (scene), and safely hand work back to the main thread (util). Two warnings come straight from the documentation. Calls must be made from the main thread apart from the two util helpers, and the interface may change before the final release. Until then, a studio should treat Python tooling as an experiment and put the jobs a production depends on in action scripts.
Workflow
- List the jobs that happen around every frame, such as backup, RAW conversion, logging and reference playback, and decide which ones the stage crew currently does by hand.
- Pick the event that each job should hang on. Backups and RAW processing belong on CAPTURE COMPLETE, because the file is only safe to copy once the high-resolution download has finished. Per-frame logging belongs on FRAME COMPLETE when a frame has several exposure passes.
- Start from Dragonframe's sample action script for your operating system (.sh on macOS/Linux, .bat on Windows) and test it on a scratch scene, including DELETE and EDIT, so the script copes when frames are removed or the timeline is changed.
- For live reference or projection, enable OSC input in the receiving program and note its port. Then, in Dragonframe's Preferences | OSC, set the matching output port, enable OSC output and enter the Position Frame Event address that program expects.
- Prototype richer studio tools, such as custom menus or reference loaders, in the Python API on the 2027.01 development build only, and keep them off production stages until the interface is released as stable.