Scripting Guide¶
This document covers ways to control the steamshovel visualization tool through python scripting. There are several ways to execute python commands in Steamshovel:
Typing code directly in the embedded python prompt
Executing a file by running
exec(open("file.py").read())
or%run -i file.py
in the embedded promptExecuting a file at the command line as
steamshovel -s file.py
Some of the Qt-based python bindings (e.g. for controlling the window or application objects) have more commands than are documented here. These commands generally correspond to the Qt slots and properties of these objects. They can be explored using tab completion in an ipython prompt, or by reading the Qt documentation.
Basic program control¶
Variable names at interpreter scope (i.e. in the __main__
namespace).
The app
object:
This object refers to the global SteamshovelApp object. Some useful commands on this object:
app.aboutQt()
: Show an information dialog with the current Qt version number
app.quit
: Tells steamshovel to shut down. Warning: this call does not block, so make sure that your script is not running things after you call app.quit. Optionally, you can pass an integer, which will be used as the return code of steamshovel at exit.
The app.files
object:
This object is the program’s global FileService object, which loads I3 files.
app.files.nFrames
: the number of currently loaded I3Frames
app.files.openLocalFile(filename)
: add the named file to the currently open file collection. Also use this for sockets and pipes (a pipe is recognized by passing-
).
app.files.openRemoteFile(url)
: open the given URL using I3FileStager and add the resulting file to the currently open file collection
app.files.selectFrame(n)
: Select then
’th frame in the currently open files. Returns a boolean to indicate success of the operation.
app.files.advanceFrame(x)
: If then
’th frame is currently selected, move to then+x
the frame.x
may be negative. Returns a boolean to indicate success of the operation.
app.files.nextMatchingFrame(stream)
: Go forward until a frame that matchesstream
is found. Returns a boolean to indicate success of the operation.
app.files.prevMatchingFrame(stream)
: Likewise, but going backwards.
app.files.currentIndex
: Index of the currently selected frame, or -1 if none selected
app.files.currentFrame
: The I3Frame currently selected.
The frame
object:
Global synonym for
app.files.currentFrame
.
The window
object:
This corresponds to the current ShovelMainWindow object.
window.doFileOpen()
: Behave as if the user had selected “Open file” from the file menu.
window.doFileCloseAll()
: Closes all open files.
window.showFullScreen()
: Go into presentation mode.
window.showNormal()
: Return from presentation mode.
window.doToggleTVMode()
: Go into TV mode or come back.
window.finfo_filter
: Python source code of the frame information filter.
window.frame_filter
: Python source code of the frame filter.
The window.timeline
object:
This corresponds to the animation and color controller widget at the bottom of the window.
window.timeline.eventBeginTime
and.eventEndTime
: Read/writable integers indicating the first and last nanoseconds visible in the animation
window.timeline.minTime
and.maxTime
: Badly named integers reflecting the beginning and end of the color map in times. These are always bounded by the event begin and end times.
window.timeline.time
: The currently selected time.
window.timeline.reset()
: Reset the timeline
window.timeline.stepBack()
and.stepForward()
: Move the currently time forward or back by one nanosecond.
window.timeline.setEventTimeWindow(x,y)
: Equivalent to setting the event begin time to x and the event end time to y.
window.timeline.fastFoward()
and.rewind()
: Move the current time to the beginning or the end of the displayed time window.
window.timeline.stop()
: Stop current animation.
window.timeline.play([speed])
: Start the animation. If speed is given, each frame of animation will cover that number of nanoseconds; larger numbers will play the event more rapidly.
The window.gl
object:
This corresponds to the I3GLWidget object that presents the window’s 3D view.
window.gl.cameraLoc
: Location of the camera as ashovelart.vec3d
.
window.gl.cameraPivot
: Location of the camera’s focus point as ashovelart.vec3d
.
window.gl.cameraOrientation
: Ashovelart.vec3d
for the “up” direction of the camera.
window.gl.focusCameraOn(point)
: Move the camera’s pivot to the specified point (ashovelart.vec3d
or adataclasses.I3Position
.) The camera’s location will be moved by the same distance as the pivot, so that the relative viewing angle remains the same. This has the same effect as the “Focus on…” item in the view menu.
window.gl.setPerspective(bool)
: Set to true for a perspective camera (the default), or false for an orthographic camera.
window.gl.setBackgroundColor(r,g,b)
: Set the background color of the window with a tuple of red, green, and blue values. The values should be in the range [0,1].
window.gl.scenario
: The window’s active Scenario object (see below).
window.gl.referenceDpi
: The screen’s current pixel density in dots per inch. This is used in calculating scaling factors for the density-aware screenshot functions. It can be set to a new value, but this is not normally required.
window.gl.debugInfo
: Get a string with some information about your OpenGL context, such as the Qt library’s dpi estimates, the maximum OpenGL line width, and the estimated maximum screenshot size.
Creating Images and Movies¶
Screenshots can be made in several ways. The basic screenshot functon:
window.gl.screenshot([x,y],[filename])
: Save a screenshot to disk. Thex
andy
sizes of the screenshot are optionally given first. if they are omitted, or set to zero, the screenshot will take on the dimensions of the current view. An optional filename is given last; if omittedShovelScreen.png
will be used. The program will attempt to save in the format given in the filename. .png is the recommended suffix.
To create higher-DPI screenshots for print purposes, two additional methods are available:
window.gl.screenshotDpi(dpi,[filename])
: Save a screenshot with the current visible dimensions, but specifying a new pixel density in dots per inch (DPI). Content will be scaled to this new density. The scaling factor is calculated asdpi / window.gl.referenceDpi
. This is the method to use if you want to create a high-res screenshot that looks exactly like what you see on the screen.
window.gl.screenshotInches( width, height, dpi, [filename])
: Save a screenshot with the specified dimension. Thewidth
andheight
parameters are floating point values representing inches, anddpi
is an integer representing density in dots per inch. This method is useful for creating an image to a particular print size requirement. As withscreenshotDpi
, scaling is calculated relative towindow.gl.referenceDpi
.
Because movie production has many parameters, they are not given in a single function call.
Instead, parameters are set as properties of the object window.movieEngine
:
window.movieEngine.height
: Y dimension of the movie output in pixels.
window.movieEngine.width
: X dimension of the movie output in pixels.
window.movieEngine.fps
: Frames per second of the output movie.
window.movieEngine.nframes
: Number of frames to render.
window.movieEngine.rotation
: Movie camera rotation in degrees per second. Positive numbers rotate thecamera counterclockwise, and negative numbers clockwise.
window.movieEngine.starttime
: Nanosecond of event time on which to begin the movie recording.
window.movieEngine.endtime
: Nanosecond of event time on which to end the movie recording.
All of these parameters have sane defaults.
The following properties are read-only data generated based on the values above:
window.movieEngine.duration
: The runtime of the movie to be generated, in seconds.
window.movieEngine.rotPerFrame
: Degrees of rotation between each frame.
The following two properties are strings:
window.movieEngine.imageOutputDir
: Directory into which steamshovel will write frames of a movie as individual png files. It is usually not necessary to set this property directly (see theproduceStills()
method).
window.movieEngine.movieFileName
: Output file name of an MP4 movie to be generated by steamshovel. This is a read-only property; callproduceMovie()
to set it.
Finally, there are two properties controlling image scaling and antialiasing:
window.movieEngine.scaleFactor
: Floating-point scaling factor to apply to the output. Images will be rendered atwidth*scalingFactor
pixels wide andheight*scalingFactor
pixels high. The saved image size will depend on the value of therescaleFlag
.
window.movieEngine.rescaleFlag
: Boolean value controlling output size whenscaleFactor
is set to a value other than 1. WhenrescaleFlag
is true, rendered frames will be smoothly resized to the originalwidth
andheight
settings. If false, no resizing takes place. Rescaling takes place within the program, so large images are not written to disk if this flag is true.
To create antialiased movies, set width
and height
to be your intended output size, set scaleFactor
to a number
greater than 1 (2 or 4 is recommended), and set the rescaleFlag
to true.
There are two methods to create output:
window.movieEngine.produceStills( dir )
: Create a movie according to the properties set above, exporting it as png files into the named directory.
window.movieEngine.produceMovie( output_file )
: Create a movie using ffmpeg. Theoutput_file
should probably end with .mp4. Intermediate still images will be exported as png files to the directory named inwindow.movieEngine.imageOutputDir
. If this property is blank, a temporary directory will be created and the property will be set to its path– this can be useful to recover the still images if ffmpeg transcoding fails.
While movies are being produced, they can be canceled by calling:
window.movieEngine.cancelCurrentProduction()
: Stop the current movie production.
Additional scripting control over movies can be gained by setting a “preframe hook”:
window.movieEngine.setPreframeHook( hook )
: Specify a callable python object that will be called before each frame of movie production. It will be passed a single argument, the zero-indexed frame number of the frame about to be rendered.
By setting a preframe hook, a user can control the state of artist settings, the position of the camera, or the animation time. This is useful for cases where the basic movie parameters are not sufficient.
Controlling Scenarios and Artists¶
The Scenario object represents the list of current Artists (displays) in the view; the view can be controlled by adding, modifying, and removing Artists. Artists are handled in scripting as opaque, read-only handles, which can only be modified through APIs in the Scenario object.
Artists have a name, a set of keys, and some settings.
The scenario
object (usually as window.gl.scenario
): This corresponds to shovelart’s Scenario class.
scenario.listAvailableArtists()
: Return a list of strings that can be used as artist names.
scenario.registerArtist( artistClass )
: Add a new type of artist to the scenario by passing a reference to its class.
scenario.getArtists()
: Get a list of handles to currently active artists.
scenario.clear()
: Remove all artists from the scene.
scenario.add( name, [keys] )
: Add a new artist with the given name, optionally providing a list of keys to set up the artist with. A handle to the artist is returned.
scenario.remove(artist)
: Remove the given handle from the scene. The handle is thereafter invalid.
scenario.setIsActive(artist, bool)
: Set whether the given handle is active (visible) or not.
scenario.setKey( artist, idx, value )
: Set theidx
th key of the given artist tovalue
.
scenario.changeSetting( artist, settingkey, value )
: Set the setting with valuesettingkey
to the givenvalue
.
The artist
handles have the following properties:
artist.description
: The name of the artist
artist.isActive
: Whether or not the artist is currently active
artist.numRequiredKeys
: The number of keys this artist requires
artist.keys
: The keys currently set in the artist
artist.settings
: A dictionary of the artist’s current settings.
artist.settingValue(settingkey)
: Get the value of a setting by name.