Working with Projects¶

Loading and Saving¶

KatanaFile.New()¶

Replaces the current file with a new one.

This operation cannot be undone and clears the undo stack.

KatanaFile.Revert()¶

Reloads the current file from disk. This can only succeed if the current scene was loaded or saved to a file.

This operation cannot be undone and clears the undo stack.

@raise ValueError: If file not on disk.

KatanaFile.Load(fileName, isCrashFile=False)¶

Replaces the current scene with a newly loaded one. The filename can either be a filename or an asset ID.

This operation cannot be undone and clears the undo stack.

Parameters:	fileName (`str`) – filename or asset ID isCrashFile (`bool`) – Flag to indicate whether the file to load is a crash file.

KatanaFile.Save(fileNameOrAssetId, extraOptionsDict=None)¶

Saves a Katana scene. If fileNameOrAssetId is an assetId then the scene will be published via the asset management system plugin (internally calling createAssetAndPath(), then save the file and finally calling postCreateAsset()).

Return type:	`str`
Parameters:	fileNameOrAssetId (`str`) – The name of the file or the ID of the asset under which to save the current scene. extraOptionsDict (`dict`) – A dictionary with extra options that will be passed to the createAssetAndPath() and postCreateAsset() functions as args.
Returns:	The name of the saved project file, or the ID of the published project asset, or `None` if the project could not be saved or published.
Raises:	ValueError – If the given filename or asset ID is not valid.

KatanaFile.IsFileDirty()¶

Determines if the file has been altered since the last load or save operation.

Return type:	`bool`
Returns:	`True` if the file has been modified, otherwise `False`.

KatanaFile.IsFileSavedAsAsset()¶

Return type:	`bool`
Returns:	`True` if the current session is saved as an asset, `False` if the session is saved to a file.

Importing and Exporting¶

KatanaFile.Paste(nodeXML, parent)¶

Creates new nodes that are encoded in XML.

Katana uses XML to load, save, copy, and paste its nodes. The new nodes can be parented into any group.

The nodeXML argument can either be a string of XML data, a string from a Katana file, or an Katana XmlIO Element. Strings will attempt to be upgraded, but elements will not.

Parameters:	nodeXML (`str`) – The string or element of nodes to paste. parent (`GroupNode`) – The group node to set as the parent for the given node structure.

KatanaFile.Import(fileName, floatNodes=False, parentNode=None)¶

Loads and merges a Katana file into the current one.

Return type:	`list` of `Node`
Parameters:	fileName (`str`) – The name of the file or the ID of the asset to import. floatNodes (`bool`) – Flag that controls whether to make nodes interactively moveable. If `True` the new nodes will be set to a floating state in the node graph editor. parentNode (`GroupNode` or `None`) – The group node where parsed nodes will be inserted.
Returns:	A list of all newly created nodes.
Raises:	ValueError – If unable to read from the file.

KatanaFile.Export(fileNameOrAssetId, nodes, extraOptionsDict=None)¶

Exports the selected nodes in the node graph into a new Katana scene. If fileNameOrAssetId is an assetId then the scene will be published via the asset management system plugin (internally calling createAssetAndPath(), then save the file and finally calling postCreateAsset()).

Return type:	`str`
Parameters:	fileNameOrAssetId (`str`) – The name of the file or the ID of the asset under which to save the current scene. nodes (`list` of `NodegraphAPI.Node`) – The list of nodes to export to the file or asset with the given name or ID. extraOptionsDict (`dict`) – A dictionary with extra options that will be passed to the createAssetAndPath() and postCreateAsset() functions as args.
Returns:	The name of the saved project file, or the ID of the published project asset, or `None` if the project could not be saved or published.
Raises:	ValueError – If the given filename or asset ID is not valid.

Autosaving¶

KatanaFile.CrashSave(forceSave=False, logCompletion=False)¶

Forces a crash file to be saved.

Katana automatically writes crash files based on user preferences. A crash file can be manually be written before potentially risky operations.

Parameters:	forceSave (`bool`) – Flag that controls whether to force a crash file save, even if the write is redundant. logCompletion (`bool`) – Flag that controls whether to log the result of trying to save the crash file.

KatanaFile.CrashSaveEnable()¶

KatanaFile.CrashSaveDisable()¶

KatanaFile.GetCrashActions()¶

Return type:	`int`
Returns:	The number of actions since the last crash save.

KatanaFile.GetCrashTime()¶

Return type:	`float`
Returns:	The time (as provided by the `time` module) of the last autosave.

KatanaFile.GetViableCrashFiles(smartPrune=True)¶

Return type:	`list`
Parameters:	smartPrune (`bool`) – Flag that controls whether to skip empty files or old files that share a common prefix.
Returns:	A list of dictionaries containing data for all crash save files that match the `/TMPDIRp/*.katana` filename pattern.

KatanaFile.WasFileLoadedFromCrashFile()¶

Return type:	`bool`
Returns:	`True` if the file was loaded from a crash file, otherwise `False`.
Attention:	The user interface will not allow a regular save to overwrite a file that has been loaded this way. There is no restriction at the API level, but be aware.

Timeline¶

NodegraphAPI.GetInTime()¶

Get the in frame. The in time must be lesser than the out time.

Return type:	`number`

NodegraphAPI.SetInTime(inTime, final=True)¶

Set the in frame. The in time must be lesser than the out time.

NodegraphAPI.SetOutTime(outTime, final=True)¶

Set the end frame. The out time must be greater than the in time.

NodegraphAPI.GetOutTime()¶

Get the end frame. The out time must be greater than the in time.

Return type:	`number`

NodegraphAPI.GetWorkingInTime()¶

Get the start frame of the working range. The in time is guaranteed to be less than or equal to the out time.

Return type:	`number`

NodegraphAPI.SetWorkingInTime(workingInTime, final=True)¶

Set the working-range in time.

NodegraphAPI.GetWorkingOutTime()¶

Get the end frame of the working range. The out time is guaranteed to be less than or equal to the in time.

Return type:	`number`

NodegraphAPI.SetWorkingOutTime(workingOutTime, final=True)¶

Set the working-range out time.

NodegraphAPI.GetCurrentTime()¶

Return type:	`number`
Returns:	The current time on the timeline.
See:	`GetInTime`, `GetOutTime`

NodegraphAPI.SetCurrentTime(newTime, final=True)¶

Sets the current time on the timeline to the given time.

Parameters:	newTime (`number`) – The time to set as the current time on the timeline. final (`bool`) – Flag to control whether to add a `"parameter_finalizeValue"` event to Katana’s event queue.
See:	`GetInTime`, `GetOutTime`

NodegraphAPI.GetTimeIncrement()¶

Get the time increment when a single frame is advanced. This value is usually 1.

Return type:	`float`

NodegraphAPI.SetTimeIncrement(incTime, final=False)¶

Set the time increment when a single frame is advanced. This value is usually 1.

NodegraphAPI.GetAutoKeyAll()¶

True of auto keyframing is turned on. When autokeying is turned on, parameter value changes on parameters that are curves will be automatically keyed. Otherwise changes are applied to a temporary floating keyframe.

Return type:	`bool`

NodegraphAPI.SetAutoKeyAll(autoKeyAll)¶

Set the auto keyframing on or off. When autokeying is turned on, parameter value changes on parameters that are curves will be automatically keyed. Otherwise changes are applied to a temporary floating keyframe.

Project Asset¶

NodegraphAPI.GetProjectAssetID()¶

Return type:	`str`
Returns:	The name of the file or the ID of the asset that the current project was loaded from.

NodegraphAPI.GetOriginalProjectAssetID()¶

Return type:	`str`
Returns:	The name of the original file or the ID of the original asset that the current project was last saved as before loading.
Note:	Example: A file is saved to an asset and subsequently copied to “/tmp/a.katana”. When the file is loaded from “/tmp/a.katana”, `GetProjectAssetID` returns `'/tmp/a.katana'`, and `GetOriginalProjectAssetID` returns the ID of the original asset.

NodegraphAPI.GetProjectFile()¶

Return type:	`str`
Returns:	The resolved file system location path of the .katana file from which the node graph document of the current project was loaded.
Note:	Returns the Katana project’s unresolved asset ID (the result of `GetProjectAssetID`) if no default asset plug-in is available.

NodegraphAPI.GetProjectDir()¶

Return type:	`str`
Returns:	The resolved file system location path of the directory that contains the .katana file from which the node graph document of the current project was loaded.

NodegraphAPI.GetKatanaSceneName()¶

Get the current asset name being used. Used by exporters to generate asset names.

Returns:	asset name
Return type:	`str` or `None`

NodegraphAPI.IsLoading()¶

Return type:	`bool`
Returns:	`True` if node graph is being loaded from a serialized form, otherwise `False`.
See:	`IsLoadingAsync` for an event-based equivalent for use in event handlers.
Note:	Examples of loading node graph from a serialized form: Loading a Katana project from a `katana` file Loading a LiveGroup node’s contents from a `livegroup` file Pasting some previously copied nodes from the clipboard

NodegraphAPI.UpdatePluginsFromGlobals()¶

Graph State¶

NodegraphAPI.GetCurrentGraphState(**kwargs)¶

Get the current graph state. Like GetCurrentTime(), but with all graph state information (such as variables)

Returns:	GraphState

NodegraphAPI.GetGraphState(timeval, **kwargs)¶

Get the graph state for the specified time

Return type:	`GraphState`
Parameters:	timeval (`float`) – Specified time
Returns:	the graphState

NodegraphAPI.GetGraphStateAtPort(searchPort, startPort, startGraphState)¶

Get the graph state at searchPort, starting with startPort and accumulating graph state modifications during upstream node graph traversal.

Traverses the node graph in depth-first order, starting at startPort, accumulating graph state (starting with startGraphState), and returning the graph state found at searchPort on first encounter, or None if it is not encountered.

Given ports must be output (producer) ports. Only contributing ports are traversed.

Parameters:	searchPort (`Port`) – The target output `Port` at which to obtain `GraphState`. startPort (`Port`) – The output `Port` at which to start traversal. startGraphState (`GraphState`) – The `GraphState` with which to start traversal.
Return type:	`GraphState` or `None`
Returns:	The `GraphState` at `searchPort` as a result of traversal from `startPort` with `startGraphState`, or `None` if `searchPort` is not encountered during traversal.

NodegraphAPI.GetSampleTimesFromGraphState(graphState, useSinglePrecision=False)¶

Get the frame-relative times at which time-varying Parameters (or other well-defined functions) should be sampled, according to the given GraphState.

For details, see GetSampleTimes.

Parameters:	graphState (`GraphState`) – `GraphState` from which timing parameters (`shutterOpen`, `shutterClose`, `maxTimeSamples`) are obtained. useSinglePrecision (`bool`) – If `True`, sample times are limited to single precision (C++ float). This guarantees that the sample times can be used in constructing a multisampled `FnAttribute`.
Return type:	`tuple` of `float`
Returns:	A `tuple` of frame-relative sample times.
Raises:	ValueError – Invalid GraphState timing parameters.

NodegraphAPI.GetSingleSampleTimeFromGraphState(graphState)¶

Get the frame-relative time at which time-varying Parameters (or other well-defined functions) should be sampled if using a single sample, according to the given GraphState.

This returns the sample that would be returned by an equivalent call to GetSampleTimesFromGraphState() where maxTimeSamples is 1.

For details, see GetSampleTimes.

Parameters:	graphState (`GraphState`) – `GraphState` from which timing parameters (`shutterOpen`, `shutterClose`) are obtained.
Return type:	`float`
Returns:	Frame-relative sample time.
Raises:	ValueError – Invalid GraphState timing parameters.

NodegraphAPI.StackedLocalGraphState(*args, **kwds)¶

Context manager to temporarily push the given Local Graph State into the global stack of Local Graph States.

Return type:	`None`
Parameters:	graphState (`NodegraphAPI.GraphState`) – The Local Graph State that is going to be pushed at the top of the stack temporarily.
Returns:	Yields after inserting the given Local Graph State at the top of the stack. On resuming, the top element of the stack is removed.

class NodegraphAPI.GraphState¶

Bases: pybind11_builtins.pybind11_object

__init__() → None¶

edit() → SPI_Nodegraph_v1::GraphStateBuilder¶: Returns a GraphStateBuilder configured so as to produce this GraphState.

getDynamicEntry(path: unicode) → object¶: Returns the dynamic entry with the given path, or None if it cannot be found.

getDynamicHash() → int¶: Returns the hash of the dynamic portion of this GraphState.

getHash() → int¶: Returns the hash of this GraphState.

getMaxTimeSamples() → int¶: Returns the maximum number of time samples allowed in this GraphState.

getOpSystemArgs() → Geolib3::internal::FnAttribute::GroupAttribute¶: Returns a GroupAttribute containing the system Op arguments in this GraphState.

getROI() → tuple¶: Returns the region of interest used by this GraphState, as a 4-tuple of integers, ordered as x-offset, y-offset, width, height.

getRenderMethodName() → str¶: Returns the name of the render method used by this GraphState.

getSampleRateX() → float¶: Returns the sample rate in the x-direction set in this GraphState.

getSampleRateY() → float¶: Returns the sample rate in the y-direction set in this GraphState.

getShutterClose() → float¶: Returns the shutter close time set in this GraphState.

getShutterOpen() → float¶: Returns the shutter open time set in this GraphState.

getStaticEntry(path: unicode) → object¶: Returns the static entry with the given path, or None if it cannot be found.

getStaticHash() → int¶: Returns the hash of the static portion of this GraphState.

getTime() → float¶: Returns the time set in this GraphState.

getView() → str¶: Returns the same of the view used by this GraphState.

isDiskCachingAllowed() → bool¶: Returns whether this GraphState allows disk caching.

isExternalRenderAllowed() → bool¶: Returns whether this GraphState allows external renders.

isHotRender() → bool¶: Returns whether this GraphState is used by a hot render.

isROIAbsolute() → bool¶: Returns whether the region of interest used by this GraphState was explicitly set.

isTaskCachingIgnored() → bool¶: Returns whether task caching is ignored in this GraphState.

matchVariableWithCEL(variableName: unicode, celStatement: unicode) → bool¶: Returns whether the given variableName matches the given celStatement.

class NodegraphAPI.GraphStateBuilder¶

Bases: pybind11_builtins.pybind11_object

__init__() → None¶

build() → NodegraphAPI.GraphState¶: Returns the GraphState currently under construction. This does not affect the internal state of this builder, so subsequent calls to build() without updating the builder will produce the same GraphState

deleteDynamicEntry(path: unicode) → NodegraphAPI.GraphStateBuilder¶: Removes the dynamic entry with the given path, if it exists.

deleteStaticEntry(path: unicode) → NodegraphAPI.GraphStateBuilder¶: Removes the static entry with the given path, if it exists.

setDiskCachingAllowed(allowCaching: bool) → NodegraphAPI.GraphStateBuilder¶: Sets whether disk caching will be allowed in the GraphState under construction by this builder.

setDynamicEntry(*args, **kwargs)¶

Overloaded function.

setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, attr: Geolib3::internal::FnAttribute::Attribute) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the dynamic entry with the given path to attr, overwriting it if it already exists.
setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: int) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the dynamic entry with the given path to an IntAttribute initialized with value.
setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: float) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the dynamic entry with the given path to a DoubleAttribute initialized with value.
setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: unicode) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the dynamic entry with the given path to a StringAttribute initialized with value.

setExternalRenderAllowed(allowExternal: bool) → NodegraphAPI.GraphStateBuilder¶: Sets whether external renders will be allowed in the GraphState under construction by this builder.

setHotRender(isHot: bool) → NodegraphAPI.GraphStateBuilder¶: Sets whether the GraphState under construction by this builder is used by a hot render.

setIgnoreTaskCaching(ignoreCaching: bool) → NodegraphAPI.GraphStateBuilder¶: Sets whether to ignore task caching in the GraphState under construction by this builder.

setMaxTimeSamples(maxSamples: int) → NodegraphAPI.GraphStateBuilder¶: Sets the maximum number of time samples in the GraphState under construction by this builder.

setROI(roi: List[float[4]]) → NodegraphAPI.GraphStateBuilder¶: Sets the region of interest used by the GraphState under construction by this builder. roi must be a 4-tuple of ints, ordered as x-offset, y-offset, width, height.

setRenderMethodName(name: unicode) → NodegraphAPI.GraphStateBuilder¶: Sets the render method name used by the GraphState under construction by this builder.

setSampleRateX(sampleRate: float) → NodegraphAPI.GraphStateBuilder¶: Sets the sample rate in the x-direction in the GraphState under construction by this builder.

setSampleRateY(sampleRate: float) → NodegraphAPI.GraphStateBuilder¶: Sets the sample rate in the y-direction in the GraphState under construction by this builder.

setShutterClose(time: float) → NodegraphAPI.GraphStateBuilder¶: Sets the shutter close time in the GraphState under construction by this builder.

setShutterOpen(time: float) → NodegraphAPI.GraphStateBuilder¶: Sets the shutter open time in the GraphStae under construction by this builder.

setStaticEntry(*args, **kwargs)¶

Overloaded function.

setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, attr: Geolib3::internal::FnAttribute::Attribute) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the static entry with the given path to attr, overwriting it if it already exists.
setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: int) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the static entry with the given path to an IntAttribute initialized with value.
setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: float) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the static entry with the given path to a DoubleAttribute initialized with value.
setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: unicode, value: unicode) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the static entry with the given path to a StringAttribute initialized with value.

setTime(time: float) → NodegraphAPI.GraphStateBuilder¶: Sets time in the GraphState under construction by this builder.

setView(view: unicode) → NodegraphAPI.GraphStateBuilder¶: Sets the name of the view used by the GraphState under construction by this builder.