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.

Raises:

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. :return: asset name :rtype: 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(graphState)

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_object

__init__() → None
edit() → SPI_Nodegraph_v1::GraphStateBuilder

Returns a GraphStateBuilder configured so as to produce this GraphState.

getDynamicEntry(path: str) → Geolib3::internal::FnAttribute::Attribute

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: str) → Geolib3::internal::FnAttribute::Attribute

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.

getTraversalInitialTime() → float

Returns the initial time of traversal set in this GraphState.

getView() → str

Returns the same of the view used by this GraphState.

hasTraversalInitialTime() → bool

Returns whether the initial time of traversal is set in 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: str, celStatement: str) → bool

Returns whether the given variableName matches the given celStatement.

class NodegraphAPI.GraphStateBuilder

Bases: 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: str) → NodegraphAPI.GraphStateBuilder

Removes the dynamic entry with the given path, if it exists.

deleteStaticEntry(path: str) → 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.

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

Sets the dynamic entry with the given path to attr, overwriting it if it already exists.

  1. setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: int) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the dynamic entry with the given path to an IntAttribute initialized with value.

  1. setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: float) -> NodegraphAPI_cmodule.GraphStateBuilder

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

  1. setDynamicEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: str) -> 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: Annotated[List[float], FixedSize(4)]) → NodegraphAPI.GraphStateBuilder

Sets the region of interest used by the GraphState under construction by this builder. roi must be a 4-tuple of numbers (which will be truncated to int), ordered as x-offset, y-offset, width, height.

setRenderMethodName(name: str) → 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.

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

Sets the static entry with the given path to attr, overwriting it if it already exists.

  1. setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: int) -> NodegraphAPI_cmodule.GraphStateBuilder

Sets the static entry with the given path to an IntAttribute initialized with value.

  1. setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: float) -> NodegraphAPI_cmodule.GraphStateBuilder

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

  1. setStaticEntry(self: NodegraphAPI_cmodule.GraphStateBuilder, path: str, value: str) -> 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.

setTraversalInitialTime(time: float) → NodegraphAPI.GraphStateBuilder

Sets initial time of traversal in the GraphState under construction by this builder.

setView(view: str) → NodegraphAPI.GraphStateBuilder

Sets the name of the view used by the GraphState under construction by this builder.