< Previous | Contents | Manuals Home | Boris FX | Next >
Workflow Presets (WFPreset)
The workflow preset system stores “preferences” data that includes built-in values, user-specific values, scene-specific values, and optionally facility-specific data or even additional libraries of setup-type information. It replaces and greatly enhances the legacy SynthEyes preferences system, with enhanced visibility and control through the workflow preset manager. You’ll want to be familiar with the workflow preset manager to understand what you can change and monitor what your scripts have done.
These presets include settings not only for importer, tool, and exporter scripts (including libraries of different settings), but also for rooms, viewports, etc. So there’s a lot you might want to adjust from a script, and the global WFPreset object is your entry into doing so.
Note that the builtin and facility presets are stored as JSON files in the SynthEyes application folder; the user presets are stored as a JSON file in your File/User Data Folder, and the scene presets are stored as JSON data within the SynthEyes .sni file. While SynthEyes is running, presets reside in memory; they are only written to disk or the sni file when necessary or in response to Sizzle commands to do so.
WFPreset Global: Attributes and Functions
Note that all WFPreset attributes are read-only.
.AddSource(filename, [name]) Add a new source from the given filename,
which must be a JSON file written by SynthEyes (or a tool following the same format). The optional name will be used as the name of the source; if no name is supplied, the base-name of the filename is used. The filename is store as an value on the top-level preset for the source. The return value is a list consisting of the new source’s index and any error message. If the error message is an empty string, the operation succeeded. Call SaveSourceList() after adding the source if you want the new source to persist to future SynthEyes runs. (Don’t call
it if you just want to add a source, grab some stuff from it, then remove it.)
.builtin Points to the top-level preset for the builtin presets initially supplied by SynthEyes; not user-changeable.
.current This is the “Current” preset in the Scene, the overall holder for all the data that SynthEyes may use. Each source has a top-level Current folder; other folders and presets outside of current may hold libraries of presets that aren’t currently active.
.Current(idx/name) The Current preset in the source specified by index or name, ie WFPreset.Current(“Scene”) is the same as WFPreset.current.
.current_preset_version The internal current version number of the
presets. This is unrelated to the SynthEyes version --- it changes whenever the structure of the presets changes and necessitates updating older preset information.
.DeleteSource(idx/name) Delete the source, specified by index or
name. Only user-added sources can be deleted, not .user or .facility etc. Call SaveSourceList() after deleting the source if you want the deletion to persist to future SynthEyes runs. Any error message is returned; if that string is empty, the operation succeeded.
.facility Points to the top-level preset for presets supplied by your facility (company, organization, school, workgroup, boss, etc).
.FindByFullPathName(fullpath) Finds and returns the preset (if any) at this full
path name, or null if it isn’t found. See the WFPreset instance attribute .fullPathName for discussion.
.FindSourceIndex(name) Finds the index number of the source given
its name. Note that these indices can change during a run if sources are loaded or unloaded.
.IsSourceLocked(idx/name) Whether or not the source, specified by index
or name, is locked. Note that only the user and scene presets are unlocked by default. (See UnlockSource.)
.LockSource(idx/name) Lock the source (and all presets under it),
specified by index or name. If the source was
previously unlocked, the source is now written to disk to finalize those changes.
.NSource() The number of preset sources, including not only builtin, facility, user, and scene but also any preset libraries that have been loaded.
.OrdinalPreset(idx) Returns the i’th preset overall, making it possible to efficiently iterate over all of them in conjunction with TotalPresets(). Adding or removing presets while iterating will be upredictable and is not recommended (though the order will be chronological).
.ReloadSource(idx/name) Reload the source specified by index or name
from disk or the stored scene file. This will erase any unsaved changes. Any error message is returned; if that string is empty, the operation succeeded.
.root Top-level preset that has each of the data sources as a child. You can’t change this, though you can add and remove preset libraries that appear as children to the root.
.SaveSource(idx/name) Save the source’s presets, updating their files
on disk. The scene preset is written to a text string within the sni file; the sni file isn’t saved to disk. If you use Scene.Save() to write the sni file disk, it will automatically save the scene preset data, so SaveSource isn’t very useful for the scene presets. Any error message is returned; if that string is empty, the operation succeeded.
.SaveSourceList() Updates the preset containing the list of user- added sources, which is read each time SynthEyes starts.
.SaveUnlockedSources() Saves all unlocked sources to their
respectively locations. This is what happens normally when SynthEyes closes, for example. Any error message is returned; if that string is empty, the operation succeeded.
.scene Points to the top-level preset for the current
.sni scene file, for example exporter settings for the current shot.
.script This is the holding preset for the current script within the scene. It holds presets describing any Sizzle user-interface dialogs, and may be used to hold other presets required for this script’s operation. Note that during multiple-
stage exporters, this preset will be pointing at a preset holder specific to the stage being processed: this is important when the one exporter is run repeatedly with different settings, for example, different filmbox exports for different applications.
.SourceName(idx) The name of the idx’th source (as shown as the name of the child within the root). See also NSource().
.SourcePreset(idx/name) The top preset for the source, specified as
either its index or its name.
.TaskPreset(idx/name, [noCreate]) Returns the preset holder preset for the
current script in the specified source. TaskPreset(“User”) is equivalent to .script. Any multi-export-related redirection happens only in the user source.
.TotalPresets() The total number of preset objects being managed by SynthEyes; with OrdinalPreset this makes it possible to iterate over them all, perhaps to make some update.
.UnlockSource(idx/name) Unlock the source (and all presets under it),
specified by index or name. You can then changes those presets; when you later call LockSource(), the presets will be written back to disk for safe-keeping.
.user Points to your own top-level presets; this is where things you save as your preferences go.
WFPreset Instances: Basics
We’ll now describe the workflow preset objects that are supplied by the global WFPreset object. These WFPreset objects are used to build a hierarchical tree of presets, each containing any number of values. The WFPreset objects have only a few basic shared attributes; what values they contain are determined by the code using them in SynthEyes…. Or in your scripts!
You’ve already seen that the global WFPreset object manages various sources, which supply a top-level preset that contains presets with presets in presets etc. It’s presets all the way down!
Presets have a name, which isn’t important and isn’t at all unique to it, a uniqueID numeric identifier which is unique, and more importantly: a presetType that controls what type of preset it really is, how it is used within SynthEyes.
These preset types are managed by SynthEyes behind the scenes, though you can adjust them using Sizzle.
A preset (except the root) always has a (single) non-null parent. Each preset has a child list of presets it owns. The list is ordered; although presets have names, there can be multiple presets with the same name on a child list, and changing the order of the children may produce a different result in SynthEyes. For example, changing the order of the room preset children within the Rooms preset will change the order of the Room tabs across the top of the SynthEyes user interface. While it may be convenient sometimes to access child presets by name, whether that is appropriate depends on the data being managed. Instead, you may need to access the child presets primarily by index (as an array). The tools are present to use either style depending on the situation. You can remove a child from its parent, deleting it. Any subsequent attempt to reference it from Sizzle will cause an error.
Similarly, each preset has a list of values. The values are distinct from the preset’s attributes: you might have a value named “nm” in addition to the preset’s own standard “nm” attribute, and they’d both be different. The preset’s own attributes always take precedence, ie wfp.nm will always refer to the preset’s name even if there is also a nm value. To access the nm value, use the value list or related functions, ie wfp.value[“nm”], wfp.value.nm, or wfp.Value(“nm”)
And like the child list, the value list is positional: values have not- necessarily-unique names and they are also stored in any ordered list (array). The strategy for any particular preset’s values is up to its clients; the preset offers methods to support different strategies. In many cases, accessing the values by name is convenient, but with unordered data the indices will be best. As another example, color preference values are accessed by index for speed and compatibility with the rest of SynthEyes; changing their order will mangle the user interface colors!
For both child presets and values you’ll notice a number of similar but different functions to support these different styles and usage models.
Now a word on preset values: the WFPreset system uses its own more- detailed and numerous set of data types than Sizzle, for efficient interaction with the rest of SynthEyes.
Here’s the set of WFPreset data types
|
WFPreset type specification string. |
Sizzle Type |
What it is. |
|
“dbl” |
A Sizzle number. |
A double-precision floating-point number, which may be treated as a 32-bit integer by SynthEyes. |
|
“i64” |
A text string of digits that |
A 64-bit signed integer |
|
|
is the numeric equivalent |
|
|
“str” |
A Sizzle text string. |
A text string |
|
“rgb” |
A Sizzle number – the 24-bit RGB value used for .color attributes elsewhere in Sizzle. |
An RGB color, available in 24-bit integer form or 3-element list form. |
|
“pnt” |
List: [x, y] |
A 2-D [x, y] point (integers or floating-point) |
|
“vec” |
List: [x, y, z] |
A 3-D [x, y, z] vector (integer or floating-point) |
|
“rect” |
List: [left, top, right, bottom] |
A rectangle (integers or floating-point) |
|
“octet” |
List of eight values |
Eight values (integer or floating-point). The viewport management system interprets this as two rectangles: a “current” viewport position and a “reset” viewport position (ie if you right-click in the gutter). In this subsystem, the reset values are used only in the Scene, not for the viewport manager. |
|
“xform” |
List of twelve values. |
A 4x3 transform matrix. |
|
“hwnd” |
Hexadecimal string for 64-bit address, in the form 0xg00df00d. |
A window handle. |
|
“missing” |
Null |
Indicates a problem |
|
“null” |
Null |
A null pointer, generally indicates a problem! |
|
“json” |
Text string |
A string containing encoded JSON data |
|
|
|
(future use) |
WFPreset data types can be converted to Sizzle data types, but converting from Sizzle data to WFPreset can require a little more attention to resolve ambiguity in specific cases (to be described).
Note that “str”, “i64”, “hwnd”, and “json” all get converted to Sizzle text strings. The default conversion of strings is to preset strings, of course. To convert to “i64”, “hwnd”, or “json” types (rarely necessary), the desired type must be specified using one of the functions that accepts an optional type_hint argument.
Similarly, “dbl” and “rgb” both get converted to Sizzle numbers; converting numbers to presets, “dbl” is the default conversion. To convert to “rgb”, either the type must be specified, or the color must be specified as a Sizzle list of [r, g, b] values.
Any type can be converted to a string using the .ValueString(idx/str) call. Those strings can be converted back to a preset value by giving an equivalent string and the corresponding type_hint for the desired type.
WFPreset Instances: Attributes and Functions
With that background in hand, here are the attributes and functions offered by the WFPreset instances.
Tip: all values are automatically attributes of the preset for both reading and assignment, ie if a preset has a value “valid”, you can say “if (myPreset.valid)…” or “myPreset.valid = 1”. If a value has the same name as a pre-defined attribute, the pre-defined attribute “wins.” Assigning to a name that has neither an attribute nor value does not create a value : it is an error. Create values using the value attribute or the functions below.
.AddChild(name, type) Add a new preset with this name and type to
the end of the child list. Returns the new preset.
.AddChildBeforeIndex(index, name, type) Add a new preset with this name
and type, before the index’d one. The index can be one greater to the number of children to add to the end.
.AddValue(name, value [, type_hint]) Add a new value to the end of the value
list, using the optional type_hint to help set its value if needed. A string can be supplied for any type_hint; it will be decoded, reversing
.ValueString(). See also ReplaceNameValue and SetValue routines.
.AddValueBeforeindex(index, name, value [, type_hint]) Add a new value to
the value list before the given index, using the optional type_hint to help set its value if needed. A string can be supplied for any type_hint; it will be decoded, reversing
.ValueString(). See also ReplaceNameValue and SetValue routines.
.child The list of child presets. You can’t write to this list, use “new”, or “delete” with it, but you can access the children by numeric index or by name, ie child[2] or child[“Summary”] or #myPreset.child. Read-only.
.ChildByName(name) The (first) child preset with this name, or null.
.ChildByType(type) The (first) child preset with this type, or null.
.ChildIndexByName(name) The index of the (first) child preset with this
name, or zero if there is none.
.ChildIndexByType(type) The index of the (first) child preset with this
type, or zero if there is none.
.ChildIndexOf(preset) The index of this preset in its parent.
.DeleteValue(index/name) Delete the index’th or named value. Not an
error to delete by name and it doesn’t exist.
.DeleteAllValues() Delete all the values from this preset.
.description User-supplied text about what the preset is for etc, visible from the Workflow Preset Manager tooltips for the preset.
.Duplicate(preset [, kind]) Makes a duplicate of the given preset and
adds it to the end of the child list of this preset. If kind is present, it specifies what kind of duplicate is made: a string of either “shallow”, “deep”, or “self” – the latter meaning any links are resolved and elided so the result is self-contained. See also Transfer().
.DuplicateBeforeIndex(index, preset [, kind]) Makes a duplicate of the given
preset and adds it before this index in this preset’s child list. If kind is present, it specifies what kind of duplicate is made: a string of either “shallow”, “deep”, or “self” – the latter meaning any links are resolved and elided so the result is self-contained.
.FindByPathName(path) Find and return the (grand etc?) child preset
at the specified relative path. The (relative) path can consist of multiple slash-separated preset names; this routine digs through multiple child arrays at once to save effort.
Each preset name is backslash-quoted to protect against slashes or back-slashes in the preset names. See PathNameRelativeTo().
.FindOrCreate(name, type [, noCreate]) Looks for a preset with the specified
type within this preset’s children; if it isn’t found, a new preset with this name and type are created… unless the noCreate argument is present and nonzero.
.FindNamedOrCreate(name, type [, noCreate]) Looks for a preset with the
specified name and type within this preset’s children; if it isn’t found, a new preset with this name and type are created… unless the noCreate argument is present and nonzero.
.fullPathName The (absolute) full path name from the root preset to this preset, perhaps something like “/Scene/Current/Rooms/Summary”. Note that this is not at all necessarily a unique identifier for the preset, since names can/will often be duplicated at various levels. It only may be unique or useful. Note that slashes and backslashes within preset names are backslash-escaped into the fullPathName, so that the fullPathName can be reliably inverted. See also WFPreset.FindByFullPathName(). Read-only.
.isLink Whether this preset is a link to another preset. (Usage to be determined!) Read-only.
.isLocked Whether the preset is locked; if so, it can’t be changed. To change it, unlock it then lock it back up.
.IsMatchToLinkFrom(originating) Whether or not this preset matches the link on
originating, ie it checks the .link* specifications of the link on originating to see if this preset satisfies them (fairly loosely, debatable).
.isRoot Whether or not this is root preset. Read-only.
.isSource Whether or not this is the root preset of a source, ie a child of the root. Read-only.
.isValid Whether or not the preset is still valid, ie hasn’t been deleted. This is the only access or operation that can be performed on a dead preset reference; anything else is flagged as an error. This may be useful to verify that a reference is still good. Read only.
.link The preset to which this preset points, if it is a link. Otherwise, null. Assign to .link to create a link.
.linkID The uniqueID of the target to which the preset is linked, if any. Read-only.
.linkPathName The .fullPathName of the target of this preset if it is a link. Read-only.
.linkPresetType The .presetType of the target of this preset if it is a link. Read-only.
.LoadWindowStateFromPreset() When called on a preset in “Viewport
Settings” (or any preset with a HWND value), sends it a command to load its internal state from the presets. Use after calling SaveWindowStateToPreset to make selective modifications to the window’s internal state even when it is open. Does nothing if the window is not currently open; the values can still be changed and will be used when the window is later reopened.
.MoveChild(fromIndex, toIndex) Moves the fromIndex’th child to the toIndex’th
spot (with both indices evaluated before anything starts to move). Use to rearrange child presets into a different order.
.nm The name of the preset. There’s no requirement that it be globally unique or even unique with respect to its parent’s children.
.NChild() The number of child presets of this preset.
.NValue() The number of values on this preset.
.parent The parent preset of this preset. Null for the root. Read-only.
.PathNameRelativeTo(parent_preset) The relative path from parent_preset
down to “this” preset, ie the inverse function to FindByPathName().
.presetType The preset’s type, a text string which determines how it is used or was created by SynthEyes. You can see these values in the tooltips of presets in the Workflow Preset Manager.
.RemoveChild(preset) The given preset is removed from this
preset’s children. It’s an error if the preset isn’t one of this preset’s children (safety check).
.RemoveAllChildren() Remove all children from this preset.
.ReplaceNameValue(index, name, value [, type_hint]) Replace an existing
index’th value with a new name/value pair,
using the optional type_hint to help set its value. A string can be supplied for any type_hint; it will be decoded, reversing
.ValueString(). This allows you to change not only the value but also the name when the semantics are strictly index-based, ie there may be other values with the same name.
.SaveToFile(filename [, noDate]) The preset and its children are written to the
file in JSON format. The date information is suppressed if the optional noDate value is non-zero (convenient for automated testing). The return value is an error message or an empty string.
.SaveToString([noDate]) The preset and its children are converted to a
string in JSON format. The date information is suppressed if the optional noDate value is non-zero (convenient for automated testing). The return value is the string; it is empty if an error was encountered.
.SetValue(index/name, value [, type_hint]) Set an existing value, using the
optional type_hint to help set its value if needed. No help is usually needed if the value exists; the existing type is used if none is supplied. A string can be supplied for any type_hint; it will be decoded, reversing
.ValueString(). If the value doesn’t exist, it is created and added to the end of the value list. These semantics correspond to the most typical usage. See also ReplaceNameValue and AddValue routines when other semantics are needed.
.SaveWindowStateToPreset() When called on a preset in “Viewport
Settings” (or any preset with a HWND value), sends it a command to save its internal state to the presets. Use before calling LoadWindowStateToPreset to be able to make selective modifications to the window’s internal state even when it is open. Does nothing if the window is not currently open; the state values can still be changed and will be used when the window is later reopened.
.source The name of the source that this preset is attached to, ie Scene, User, Builtin, etc.
Read-only.
.Transfer(preset) Transfers the given preset from its current location and adds it to the end of the child list of this preset. See also MoveChild() and Duplicate().
.TransferBeforeIndex(index, preset) Transfers the given preset from its
current location and adds it before this index in this preset’s child list. See also MoveChild() to move within the same parent.
.uniqueID The unique ID for this preset (like other Sizzle objects). Read-only.
.value The list of values. You can read or write values three different ways using this list: myPreset.value.flag = 1, myPreset.value[“flag”] = 1, or maybe myPreset.value[3] = 1. Only the first two forms allow you to create a new value; you can’t create a value by index because there’s no name available. And none of these three methods allow you to specify an alternate type for the value. Use the AddValue, SetValue, or ReplaceNameValue routines for more options.
.Value(idx/name) The idx’th value or value with this name.
.ValueIndex(valuename) The index of the (first) value with this value name.
.ValueName(idx) The value name for the idx’th value.
.ValueString(idx/name) The idx’th value or named value is converted
to a string format, as shown in the Workflow Preset Manager.
©2025 Boris FX, Inc. — UNOFFICIAL — Converted from original PDF.