Silhouette 4.1 Scripting Guide

Silhouette 4 Scripting Guide

•
•
2 • About this Guide
•
•
•
ABOUT THIS GUIDE
This User Guide is a reference for Silhouette scripting and is available as an
Acrobat PDF file. You can read from start to finish or jump around as you
please.
Copyright
No part of this document may be reproduced or transmitted in any form or by
any means, electronic or mechanical, including photocopying and recording,
for any purpose without the express written consent of SilhouetteFX, LLC.
Copyright © SilhouetteFX, LLC 2010. All Rights Reserved

January 7, 2011
About Us
SilhouetteFX brings together the unbeatable combination of superior software
designers and visual effects veterans. Add an Academy Award for Scientific
and Technical Achievement, 3 Emmy Awards and experience in creating visual
effects for hundreds of feature films, commercials and television shows and you
have a recipe for success.
•
•
• Silhouette 4 Scripting Guide
•
•
•
•
•
User Interface Scripting Reference • 3
•
•
•
USER INTERFACE SCRIPTING REFERENCE
Silhouette has an embedded Python interpreter that can be used to control key
bindings and control some other features. When Silhouette starts up, it
executes the startup.py script, which in turn runs the keybinds.py script. There
is a search path when looking for these scripts, so users can modify their scripts
without modifying the default scripts.
First, Silhouette looks in $(SFX_USER_PATH)/scripts, where the

SFX_USER_PATH environment variable can be set by the user. Then
Silhouette looks in $(SFX_RESOURCE_PATH)/scripts, where
SFX_RESOURCE_PATH is the path to the resources directory on Windows
and Linux, and the Resources bundle folder on Macintosh OSX.
•
•
•
•
•
•
•
•
4 • User Interface Scripting Reference
•
•
•
Keyboard Binds
The default set of key bindings are set up in the keybinds.py script located at:
• Windows: C:\Program Files\SilhouetteFX\Silhouette4\resources\scripts
• Linux: /opt/SilhouetteFX/silhouette4/resources/scripts
• Macintosh: /Applications/Silhouette4/Contents/Resources/scripts
Refer to that file to see how the default bindings are created. There are two
methods of binding keys: binding a key directly to a specific tool or control, and
calling an object method in response to a key press.
The viewer and player have methods to bind a key directly to a control. This has
the advantage of updating the control's tool-tip to display the bound key. For
more complex manipulation of the user interface state, such as cycling through
values or controlling the zoom level, keys can be bound to functions which call
methods directly.
•
•
•
•
•
•
•
•
•
•
Silhouette Scripting Objects - The fx Module
Silhouette exposes a module called fx that serves as the access point for
everything else. It has some global methods and some child objects, each with
their own methods.
Table 1: fx Module
Functions/Attributes Description
fx.bind(key, function) Bind a key to a Python callable (function or method)
fx.unbind(key) Unbind the key
fx.status(message) Display a message in the status bar
fx.showView(view, Show or hide the specified view (console, nodes, nodeProps, objects,
show=True) objectProps, project, timeline)
fx.viewVisible(view) Return True if the view is visible/open
fx.viewer The viewer object
fx.player The player object
fx.prefs The preferences object
fx.paint The paint object
•
•
•
•
•
•
•
•
•
•
•
The Viewer
The viewer object exposes methods and attributes related to the Viewer: the
viewer display controls, the node toolbar, image zoom level, etc.
Table 2: Viewer Attributes
Attributes Description
channelMask The visible channel mask as a Color
magnify True if the magnifier is enabled
maskEnabled True if the viewer mask overlay is enabled
overlay True if the tool overlay is enabled
stabilize True if stabilization is enabled
stereoAlign True if stereo alignment mode is enabled
streamMode The current stereoscopic view mode (0=L, 1=R, 2=L/R)
toolName The current tool name
updateMode The current update mode (0=Drag, 1=Release, 2=Manual)
updateModes The list of supported update modes (Drag, Release, Manual)
viewMode The current view mode (depends on active node)
zoom The current zoom level
•
•
•
•
•
•
•
•
•
•
Table 3: Viewer Methods
Methods Description
queryTool(state) Query tool-specific state (see below)
selectTool(name) Select the tool
setChannelMask(color) Set the channel mask
setControlBind(control, key) Bind the key to the control (see Viewer controls)
setMagnify(state) Enable or disable the magnifier
setMask(maskName) Set the current overlay mask
setOverlay(state) Enable or disable the tool overlay
setStabilize(state) Enable or disable stabilization
setStereoAlign(state) Enable or disable stereo align mode
setStreamMode(mode) Set the stereoscopic view mode
setUpdateMode(mode) Set the update mode
setViewMode(mode) Set the current view mode
setZoom(zoom) Set the zoom level
toolCommand(command, Pass the command string to the current tool (see below)
state)
•
•
•
•
•
•
•
•
•
•
•
The Viewer Controls table lists the controls that can be accessed using the
setControlBind method. Keys can only be bound to buttons, but it can also be
used to set the tool tip for menus and custom controls (such as the channels
control).
Table 4: Viewer Controls
Controls Description
viewMode View mode menu (tool tip only)
updateMode Update mode menu (tool tip only)
leftView Left View button
rightView Right View button
leftRightView Left/Right View button
stereoAlign Stereo Align mode button
magnify Magnifier button
mask Mask button
stabilize Stabilize button
overlay Overlay button
channels Channels control (tool tip only)
viewAspect Aspect ratio button
•
•
•
•
•
•
•
•
•
•
Tools
The Tool State table lists the tools that have custom tool states that can be
queried or manipulated.
Table 5: Tool State
State Description
Transform (Roto, Effects) toggleAnchor – toggle the current anchor on/off
setAnchor – set anchor point at cursor position
translate (0 or 1) – turn quick translate on/off
rotate (0 or 1) – turn quick rotate on/off
scale (0 or 1) – turn quick scale on/off
Query State:
anchorEnabled – 1 if enabled, 0 if not
translate – 1 if quick translate is enabled, 0 if not
scale – 1 if quick scale is enabled, 0 if not
rotate – 1 if quick rotate is enabled, 0 if not
Bezier (Roto, Effects) closeShape – close the current shape
B-Spline (Roto, Effects)
X-Spline (Roto, Effects)
Color (Paint) pickColor – pick color from image at cursor position
•
•
•
•
•
•
•
•
10 •• User Interface Scripting Reference
•
•
State Description
Clone (Paint) viewClone (0 or 1) – turn clone overlay on/off
translate (0 or 1) – turn quick translate on/off
rotate (0 or 1) – turn quick rotate on/off
scale (0 or 1) – turn quick scale on/off
Query State:
translate – 1 if quick translate is enabled, 0 if not
scale – 1 if quick scale is enabled, 0 if not
rotate – 1 if quick rotate is enabled, 0 if not
•
•
•
•
•
•
•
•
•
•
The Player
The player object exposes methods and attributes related to the Player.
Table 6: Player Attributes
frame The current frame
playing True if playing
Table 7: Player Methods
Methods Description
setControlBind(control, key) Bind the key to the control (see Player controls)
play Start playing
stop Stop playing
gotoHome Go to the start of the work range
gotoEnd Go to the end of the work range
gotoPrevEdit Go to the previous edit
gotoNextEdit Go to the next edit
setFrame Go to the specified frame
stepForward Step to the next frame
stepBackward Step to the previous frame
•
•
•
•
•
•
•
•
•
•
Table 8: Player Controls
Controls Description
fieldMode Field mode
prev_key Previous key frame
next_key Next key frame
home Home
step_backward Step backward
play_backward Play backward
stop Stop
play_forward Play forward
step_forward Step forward
end End
•
•
•
•
•
•
•
•
•
•
Paint
The paint object exposes methods and attributes related to Paint.
Table 9: Paint Attributes
align True if align mode is enabled (Clone)
brush The current brush name
brushes The list of available brushes
brushEditModifier The modifier key used for interactive adjustment of the brush size
(default is ControlModifier)
brushSize The current brush size
channelMask The current paint channel mask as a tuple (r, g, b, a)
cloneOffset The current clone offset as a tuple (x, y)
cloneOffsetModifier The modifier key used for interactive adjustment of the clone offset
(default is ShiftModifier)
cloneSetup The current clone setup index
invertAlpha The current alpha invert mode when using obey mask
obeyAlpha True if obeying mask
onionSkin True if onion skin is on (Clone)
opacity The current brush opacity
profileType The current brush profile type
transformMode True if in interactive transform mode (Clone)
•
•
•
•
•
•
•
•
•
•
Table 10: Paint methods
Methods Description
setAlign(state) Enable or disable align mode (Clone)
setBrushSize(size) Set the current brush size
setChannelMask(r, g, b, a) Set the channels to paint on
setCloneSetup(index) Set the current clone setup (0-4)
setCloneOffset(x, y) Set the clone offset
setInvertAlpha(state) Set alpha invert state when obeying mask
setObeyAlpha(state) Set obey mask state
setOnionSkin(state) Set onion skin state (Clone)
setOnionSkinMix(mix_value) Set the onion skin mix percentage (Clone)
setOpacity(opacity) Set the brush opacity
setProfileType(profile) Set the brush profile type (0=Soft, 1=Hard, 2=Square)
setTransformMode(state) Enable or disable interactive clone transform edit mode
•
•
•
•
•
•
•
•
•
•
Preferences
The prefs object exposes the Silhouette preferences map. Most preferences
are visible from the Preferences dialog box in the user interface, but there are
some hidden preferences, and scripting is the only method of changing them.
There are numerous preferences, and they will not all be listed here. The
internal preference identifiers can be discovered by examining the Silhouette
preference file or registry entries.
•
•
•
•
•
•
•
•
16 •• Object Model Scripting Reference
•
•
OBJECT MODEL SCRIPTING REFERENCE
Much of the Silhouette object model is exposed to the Python scripting
language. Arbitrary operations can be run on a project using the –script option.
For instance, when using the –info option, the resources/scripts/info.py script
is loaded and used to dump project, session, node, and session information.
Actions, which show up in the Silhouette user interface in the Actions menu, are
also implemented using Python and the object model. All attributes are read
only unless explicitly marked as read/write. Silhouette comes with a basic
Python standard library, located in Silhouette/resources/python. For additional
Python library support, users should install Python 2.6 and ensure that
PYTHONPATH is set properly.
•
•
•
•
•
•
•
Object Model Scripting Reference • 17
•
•
•
The fx module
This module exposes global constants, attributes, and classes for interfacing to
the Silhouette environment.
Constants
Depth_Default
Depth_8
Depth_16
Depth_Float
Used when getting and setting session or Raster depths.
Attributes
actions
A dictionary of registered actions. The key is the Action ID (or class name) and
the value points to the Action class. When invoking an action from sfxcmd, the
Action ID should be used.
gui
True if running in Silhouette. False if running in sfxcmd.
prefs
Silhouette’s preferences exposed as a map of keys and values.
version
The host version as a string.
Methods
buildPath(path)
Does environment variable replacement on the specified path. Sub-strings of
the form $(VARIABLE) in path will be replaced with the environment variable, if
found.
Silhouette pre-defines some variables:
• SFX_APP_PATH - path to the location of the Silhouette binary. On Mac systems,
this will be the MacOS folder of the application bundle.
• SFX_RESOURCE_PATH - path to the Silhouette resources directory.
• SFX_APP_ROOT - path to the root directory of the Silhouette application. On Mac
systems, this is the folder the application bundle is in.
•
•
•
•
•
•
•
•
•
•
• SFX_USER_PATH - location of user-specific Silhouette resources.
bind(key, function)
Binds a function to the key and is called when the key is pressed.
Note: Only available when fx.gui is True.
unbind(key)
Un-binds the specified key from whatever function it was previously bound to.
Note: Only available when fx.gui is True.
activeNode()
Returns the currently active Node.
activeProject()
Returns the currently active Project.
activeSession()
Returns the currently active Session.
•
•
•
•
•
•
•
•
•
•
class fx.Object
The fx.Object class is the base class for most of the custom Silhouette classes.
All Object sub-classes have the following attributes and members.
Attributes
children
A List containing the child objects, or None if there are not any.
id
The unique object ID represented as a UUID.
label
The object label as used in the user interface (read/write).
locked
The locked state as a boolean.
note
The value of the note property as a String (read/write).
parent
The Object’s parent Object, or None.
properties
A List containing the object’s Properties.
selected
The selected state as a boolean.
type
The object type as a string.
visible (read/write)
The visibility state as a boolean.
Methods
clone()
Makes a deep copy of the object. Useful for making a copy of the Session in
Actions and when running in the gui, temporary changes can be made to the
object mode.
property(name)
Finds the child property by name and returns it, or None if not found.
•
•
•
•
•
•
•
•
•
•
For example, if object is a Shape object, the opacity can be set to a constant
value like this:
object.property(“opacity”).setValue(0.5)
•
•
•
•
•
•
•
•
•
•
class fx.Property
A fx.Property represents a constant or keyframable value used for animation.
Constants
Hold
Linear
EaseIn
EaseOut
EaseInOut
Interpolation types used between a keyframe and the following keyframe.
Attributes
constant
True if the property is constant. False if it has key frames.
keyframeable
True if the property is keyframable. If False, constant is always True.
keys
A List of keyframe times.
name
The internal property name; this may include one or more property group
names separated by dots.
numKeys
The number of keyframes the property contains. This may be zero if the
property is constant, though it may be non-zero as well if the property contains
the keyframes but is currently set to be constant.
type
The property type as a string.
Methods
interpolation(index)
Returns the interpolation type for the specified key frame index.
•
•
•
•
•
•
•
•
•
•
getValue(frame=0.0)
Returns the value for the specified frame. If the Property is constant, the frame
is ignored and the constant value is returned. If the frame is between
keyframes, the value will be interpolated depending on the leading keyframe’s
interpolation setting.
The returned value type depends on the type of the Property.

setValue(value, frame=0.0)
Sets the value for the specified frame. If the Property is constant, the frame is
ignored and the constant value is set. If the frame is between keyframes, a new
keyframe will be created with the specified value. The interpolation setting will
be set to the same value as the previous keyframe.
•
•
•
•
•
•
•
•
•
•
class fx.Project
Derives from fx.Object. Represents a Silhouette project.
Attributes
items
A List of Items in the Project, representing the referenced Sources and
Sessions.
path
The project file path.
Methods
load(path)
Load the project data at the specified path into the Project.
save(path)
Save the project to the specified file path.
•
•
•
•
•
•
•
•
•
•
class fx.Item
Derives from fx.Object. A Project stores a list of top-level objects called Items,
accessible with the Project.items attribute. Items are usually pointers to certain
types of data.
Attributes
info
The item information as a string. This is the same information displayed in the
Silhouette Project Window.
•
•
•
•
•
•
•
•
•
•
class fx.SourceItem
Derives from fx.Item. A fx.SourceItem points to a fx.Source object.
Attributes
source
The fx.Source the item refers to.
•
•
•
•
•
•
•
•
•
•
class fx.SessionItem
Derives from fx.Item. A fx.SessionItem points to a fx.Session object.
Attributes
session
The fx.Session the item refers to.
•
•
•
•
•
•
•
•
•
•
class fx.Source
Derives from fx.Object. A fx.Source refers to source data, usually a sequence
of video frames.
Attributes
video
True if the source has video data.
audio
True if the source has audio data.
numStreams
The number of streams the source represents. Usually 1, though Stereoscopic
EXR files can contain 2 (left and right) streams.
defaultStream
The default (dominant) stream number when referring to Stereoscopic sources,
usually multi-view EXR files. Stream 0 represents the left eye/view, and stream
1 represents the right eye/view.
key
The unique key used to cache frames from this source.
fieldHandling
The field handling value. Refer to fx.RenderOptions for supported values.
fieldDominance
The field dominance value. Refer to fx.RenderOptions for supported values.
Methods
path(frame)
Returns the path to the file for the specified frame.
•
•
•
•
•
•
•
•
•
•
class fx.Session
Derives from fx.Object. Represents a Session in a Project.
Attributes
depth
The session depth. See fx.Project.Depth* constants.
duration
The overall duration in frames.
frameRate
The frame rate.
nodes
A List of Nodes defined in the session.
pixelAspect
The pixel aspect.
size
The Session size as a tuple (width, height).
startFrame
The start frame, used as the offset for the work and render ranges.
workRange
The work range, as a tuple of (start, end).
renderInfo
The fx.RenderInfo object containing the rendering settings.
Methods
node(name or type)
Returns the Node with the specified type or name, or None if the session does
not contain the node. For example, to find the Roto Node, there are two ways
to do it:
node = session.node(type=”RotoNode”)
node = session.node(name=“Roto”)
or just …
node = session.node(“Roto”)
•
•
•
•
•
•
•
•
•
•
class fx.Node
Derives from fx.Object. Represents a Node.
Attributes
active
Returns True if the Node is the active one (set by the UI).
enabled (read/write)
True if the Node is enabled, otherwise False.
Methods
render(frame, stream=0, type=default, depth=default)
Renders the given frame and stream number with optional type (see
RenderInfo output types) and depth (defaults to session depth), and returns a
Raster with the resulting image. If type is Output_Alpha, a single channel
Raster will be returned. Otherwise a four channel Raster is returned.
•
•
•
•
•
•
•
•
•
•
class fx.RenderInfo
Stores the rendering settings for a Session.
Constants
Output_RGBA
Output_RGB
Output_Alpha
Output_Paint
Used by the type attribute to control what type of data is rendered and saved.
View_Both
View_Left
View_Right
Used by the view and viewDominance attributes to control which Stereoscopic
views are rendered and how they are saved.
Fields_None
Fields_Interlaced
Fields_AA
Fields_BB
Fields_BC
Fields_CD
Fields_DD
Used by the fieldHandling attribute to control field rendering behavior. The AA,
BB, BC, CD, and DD options assume 3:2.
Dominance_Even
Dominance_Odd
Used by the fieldDominance attribute to specify field dominance.
Attributes
All RenderInfo attributes are read/write.
combinedStereo
True if stereoscopic views are combined into one file, otherwise False. The
format must be EXR for this to have any effect.
depth
The render depth. Must be one of the fx.Depth* constant values.
•
•
•
•
•
•
•
•
•
•
directory
The output directory.
externalAlpha
Save alpha to a separate file from the RGB. Only useful when type is set to
Type_RGBA.
fieldDominance
The render field dominance. Only useful when fieldHandling is not
Fields_None.
fieldHandling
Controls field rendering. Must be one of the Fields* constants.
file
The root filename. The frame number and output extension will be appended
automatically.
format
The file format. Must be one of the supported writable file formats.
formatOptions
The file format specific options as a Dictionary of name=value pairs. When
setting format options, the entire dictionary must be assigned at once. It cannot
be modified in place. For example:
fopts = renderOpts.formatOptions
fopts[“compression”] = True
renderOpts.formatOptions = fopts
padding
The number of zeros to pad frame numbers with. 0 or 1 is no padding.
premultiply
True if the RGB should be premultiplied by the alpha channel. Some file formats
require this in their specification but do not do it automatically, while others will
do it automatically. Use whatever is appropriate for your format and
environment.
step
The frame step value. Use 1 for every frame, 2 for every other frame, etc.
•
•
•
•
•
•
•
•
•
•
scale
Output scaling; 1.0 is full resolution, 0.5 if scaled down by 50%, etc.
type
The output type. Must be one of the RenderInfo.Output* constants. Note that
using Output_Paint requires a PaintNode to be present in the Session.
view
The Stereoscopic view to render. Must be View_Left, View_Right, or
View_Both.
viewDominance
The Stereoscopic view dominance. Used when combineStereo is enabled and
writing both views to a single file.
•
•
•
•
•
•
•
•
•
•
class fx.Color
Represents a RGBA color with floating-point components.
Attributes
r (read/write)
The red component.
g (read/write)
The green component.
b (read/write)
The blue component.
a (read/write)
The alpha component.
Methods
Color(r, g, b, a=1.0) - constructor
Constructs a new Color with the given components.
set(r, g, b, a=1.0)
Sets the specified components of the Color.
•
•
•
•
•
•
•
•
•
•
class fx.Rect
Represents a floating point rectangle.
Attributes
x, left (read/write)
The left x coordinate.
y, top (read/write)
The top y coordinate.
width (read/write)
The width.
height (read/write)
The height.
right (read/write)
The right x coordinate. Same as x + width.
bottom (read/write)
The bottom y coordinate. Same as y + height.
size (read only)
The size as a tuple of (width, height).
Methods
Rect(x, y, width, height) - constructor
Constructs a new Rect with the given dimensions.
adjusted(dx1, dy1, dx2, dy2)
Returns a new Rect(x + dx1, y + dy1, width + dx2, height + dy2).
moveTo(x, y)
Moves the rectangle to the new x,y location. Width and height are unchanged.
set(x, y, width, height)
Sets all of the dimensions at once.
setSize(width, height)
Sets the size.
translate(dx,d y)
Translates the rectangle by the given deltas.
•
•
•
•
•
•
•
•
•
•
translated(dx,d y)
Returns a new Rect(x + dx, y + dy, width, height).
•
•
•
•
•
•
•
•
•
•
class fx.Raster
Represents a Raster image of a given depth.
Constants
Red
Green
Blue
Alpha
Channel indexes, used by channel manipulation methods.
Attributes
channels
Returns the number of channels.
channelSize
Returns the channel size, in bytes. Note that Silhouette's default float format is
half-float, so channelSize will be 2 for both 16 bit and float pixel formats.
format
Returns the pixel format, one of Depth_8, Depth_16, Depth_Float.
width
The width, in pixels.
height
The height, in pixels.
rect
A Rect(0, 0, width, height).
rowBytes
The number of bytes each row requires. The total buffer memory size the image
requires is rowBytes * height.
Methods
Raster(width, height, depth) - constructor
Creates a new 4 channel Raster with the given size and format depth (one of
Depth_8, Depth_16, Depth_Float). The contents of the image buffer after
construction are undefined.
•
•
•
•
•
•
•
•
•
•
clear(color=Color(0, 0, 0, 0))
Clears the Raster to the specified color.
getChannel(channel)
Extracts the desired channel from a four channel Raster and returns it in a one
channel Raster.
putChannel(source, channel)
Copies the provided one channel source Raster into the desired channel of the
target four channel Raster. The size and format of the source and target must
match.
save(format, path, aspect=1.0, rate=24.0, options=None)
Saves the Raster to a file with the specified path and file format.
•
•
•
•
•
•
•
•
•
•
class fx.Renderer
The Renderer is used to render a Session. This class has callback methods
and is designed to be sub-classed in scripts. See the Callbacks section below
for methods that can be overridden by sub-classes.
Attributes
duration
The number of frames to be rendered. This attribute is only valid after rendering
has been started.
outputRange
The range of frames in output numbers as a tuple(first,last). This attribute is
only valid after rendering has been started.
session
The session being rendered.
outputNode (read/write)
The Node being rendered.
outputPort (read/write)
The Node's output port being rendered.
writeEnable (read/write)
Set to False to disable writing of rendered files. This attribute can be used to
test rendering setups during script development.
averageTime
The average time in seconds spent on each frame.
elapsedTime
The time in seconds since rendering started
lastTime
The time in seconds of the last frame rendered.
remainingTime
The estimated time in seconds left before rendering completes.
Methods
Renderer(session) - constructor
Constructs a new Renderer for the specified Session.
•
•
•
•
•
•
•
•
•
•
buildPath(frame, stream=0, alpha=False)
Builds a full path for the given output frame number and stream. Set alpha to
True for the “external alpha” form of the path. Uses the Session's current
RenderInfo for the directory, root name, padding, view and format extension.
render(frame= -1, start= -1, end= -1)
Starts rendering. By default the Session's RenderInfo is used to determine the
range of frames to render. A single frame or range of frames can be passed to
override the default range. The input frame ranges are from 0 to session
duration - 1.
Callbacks
beginRender()
Called just before rendering begins. At this point, the duration and outputRange
attributes are valid.
endRender()
Called just after rendering ends.
beginFrame(frame)
Called just before a frame is rendered. The first frame is frame 0 and the last is
duration - 1. Sub-classes can return False to abort the rendering.
endFrame(frame)
Called just after a frame is rendered. The time information attributes have been
updated before this is called.
beginStream(stream)
Called just before the stream for the current frame is rendered. Sub-classes
can return False to abort the rendering.
endStream(stream)
Called just after the stream for the current frame is rendered.
processRaster(raster)
Called after a complete frame is rendered. This method can do post-processing
on the Raster or display it in a preview window.
error(message)
Called when an error occurs.
•
•
•
•
•
•
•
•
•
•
message(message)
Called with status information such as the frame being worked on or when
writing begins.
progress(frame)
Called at the beginning of each frame. Sub-classes can check for abort
conditions and return False to abort the rendering.
•
•
•
•
•
•
•
•
•
•
class fx.RenderDialog
Use RenderDialog to open the Silhouette Render dialog. This allows you to
change session rendering options before a render begins. This is only available
in Silhouette, not in sfxcmd, so check fx.gui before attempting to create one.
Methods
RenderDialog(session) - constructor
Constructs a new RenderDialog for the specified Session.
execute()
Opens the dialog and returns True if it was accepted, or False if it was
canceled.
•
•
•
•
•
•
•
•
•
•
class fx.ProgressHandler
Use a ProgressHandler to show progress information to the user. In gui mode,
progress can be aborted by the user.
Attributes
canceled
True if canceled by the user--gui mode only.
percent (read/write)
Percent complete, from 0-100.
title (write only)
Sets the progress title if in gui mode.
total (read/write)
The total items/frames in the progress.
value (read/write)
The current item/frame/value in the progress. The percent complete is
calculated automatically from the value and total.
Methods
ProgressHandler() - constructor
Constructs a new ProgressHandler.
begin(title=None)
Begins the progress. In gui mode, opens the standard progress dialog with a
progress bar, message area and cancel button.
end()
Ends the progress. In gui mode, closes the progress dialog.
message(message)
In gui mode, updates the progress dialog status text. In text mode, prints the
message to the console.
•
•
•
•
•
•
•
•
•
•
class fx.PreviewProgressHandler
Use a PreviewProgressHandler to show rendering progress information to the
user, with a preview and timing information when in gui mode. Derives from
ProgressHandler and supports all standard ProgressHandler attributes and
methods.
Typically, this class will be used in conjunction with the utility class
RenderHandler, found in the tools.renderHandler module.
Attributes
averageTime (write only)
Sets the Average Time field of the preview progress dialog (gui only).
elapsedTime (write only)
Sets the Elapsed Time field of the preview progress dialog (gui only).
lastTime (write only)
Sets the Last Time field of the preview progress dialog (gui only).
remainingTime (write only)
Sets the Remaining Time field of the preview progress dialog (gui only).
raster (write only)
Sets the preview Raster of the preview progress dialog (gui only).
Methods
PreviewProgressHandler() - constructor
Constructs a new PreviewProgressHandler.
•
•
•
•
•
•
•
•
•
•
class fx.Action
Actions act as commands that will show up in the Actions menu in Silhouette.
They are also available from sfxcmd using the -action command-line option.
Actions must be sub-classed and added to the action list to become functional.
To register an action, place your action module in the
Silhouette/resources/scripts/actions directory. The default startup script will
import all of the script modules in this directory, and any actions will become
available inside Silhouette.
Actions are registered with the fx.addAction(action) method.

Note: Actions that run inside the Silhouette ui must not permanently alter the object
model, as there is currently no way of manipulating the undo state from within a script.
If changes need to be made to implement some specific rendering or export behavior,
make a copy of the Project or Session before manipulating the state.
Attributes
id
The Action id, which is the action class name.
label
The Action label, which is displayed in the Action menu.
Methods
available()
This method is called by the UI when the Actions menu is opened. Sub-classes
should check preconditions in this function, and if some condition fails, throw
an exception. This easiest way to do this is with assert statements. If an
assertion fails, the assert description will be displayed in the status bar (in gui
mode), or thrown as an exception when invoked from a command-line script.
execute()
Called to execute the Action. At this point available() has returned True so all
preconditions have been met.
See the included Actions in Silhouette/resources/scripts/actions for examples
of how to implement new Actions.
•
•
•
•
•

Silhouette 4.1 Scripting Guide

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Silhouette 4.1 Scripting Guide

Diunggah oleh

Hak Cipta:

Format Tersedia

Silhouette 4 Scripting Guide

Silhouette 4 Scripting Guide

Copyright © SilhouetteFX, LLC 2010. All Rights Reserved

First, Silhouette looks in $(SFX_USER_PATH)/scripts, where the

fx.bind(key, function) Bind a key to a Python callable (function or method)

fx.unbind(key) Unbind the key

fx.status(message) Display a message in the status bar

fx.viewVisible(view) Return True if the view is visible/open

fx.viewer The viewer object

fx.player The player object

fx.prefs The preferences object

fx.paint The paint object

Table 2: Viewer Attributes

channelMask The visible channel mask as a Color

magnify True if the magnifier is enabled

maskEnabled True if the viewer mask overlay is enabled

overlay True if the tool overlay is enabled

stabilize True if stabilization is enabled

stereoAlign True if stereo alignment mode is enabled

streamMode The current stereoscopic view mode (0=L, 1=R, 2=L/R)

toolName The current tool name

updateMode The current update mode (0=Drag, 1=Release, 2=Manual)

updateModes The list of supported update modes (Drag, Release, Manual)

viewMode The current view mode (depends on active node)

zoom The current zoom level

queryTool(state) Query tool-specific state (see below)

selectTool(name) Select the tool

setChannelMask(color) Set the channel mask

setMagnify(state) Enable or disable the magnifier

setMask(maskName) Set the current overlay mask

setOverlay(state) Enable or disable the tool overlay

setStabilize(state) Enable or disable stabilization

setStereoAlign(state) Enable or disable stereo align mode

setStreamMode(mode) Set the stereoscopic view mode

setUpdateMode(mode) Set the update mode

setViewMode(mode) Set the current view mode

setZoom(zoom) Set the zoom level

Table 4: Viewer Controls

viewMode View mode menu (tool tip only)

updateMode Update mode menu (tool tip only)

leftView Left View button

rightView Right View button

leftRightView Left/Right View button

stereoAlign Stereo Align mode button

magnify Magnifier button

mask Mask button

stabilize Stabilize button

overlay Overlay button

channels Channels control (tool tip only)

viewAspect Aspect ratio button

Table 5: Tool State

Transform (Roto, Effects) toggleAnchor – toggle the current anchor on/off

setAnchor – set anchor point at cursor position

translate (0 or 1) – turn quick translate on/off

rotate (0 or 1) – turn quick rotate on/off

scale (0 or 1) – turn quick scale on/off

anchorEnabled – 1 if enabled, 0 if not

translate – 1 if quick translate is enabled, 0 if not

scale – 1 if quick scale is enabled, 0 if not

rotate – 1 if quick rotate is enabled, 0 if not

Bezier (Roto, Effects) closeShape – close the current shape

B-Spline (Roto, Effects)

X-Spline (Roto, Effects)