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.NodegraphGlobals.GetInTime()¶

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

Return type:	`number`

NodegraphAPI.NodegraphGlobals.SetInTime(inTime, final=True)¶

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

NodegraphAPI.NodegraphGlobals.SetOutTime(outTime, final=True)¶

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

NodegraphAPI.NodegraphGlobals.GetOutTime()¶

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

Return type:	`number`

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.SetWorkingInTime(workingInTime, final=True)¶

Set the working-range in time.

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.SetWorkingOutTime(workingOutTime, final=True)¶

Set the working-range out time.

NodegraphAPI.NodegraphGlobals.GetCurrentTime()¶

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

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.GetTimeIncrement()¶

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

Return type:	`float`

NodegraphAPI.NodegraphGlobals.SetTimeIncrement(incTime, final=False)¶

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

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.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.NodegraphGlobals.GetProjectAssetID()¶

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

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.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.

NodegraphAPI.NodegraphGlobals.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.NodegraphGlobals.GetKatanaSceneName()¶

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

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

NodegraphAPI.NodegraphGlobals.IsLoading()¶

NodegraphAPI.NodegraphGlobals.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

class NodegraphAPI.GraphState¶

Bases: object

__init__¶: x.__init__(...) initializes x; see help(type(x)) for signature

__new__(S, ...) → a new object with type S, a subtype of T¶

edit()¶

getDynamicEntry()¶

getDynamicHash()¶

getHash()¶

getMaxTimeSamples()¶

getOpSystemArgs()¶

getROI()¶

getRenderMethodName()¶

getSampleRateX()¶

getSampleRateY()¶

getShutterClose()¶

getShutterOpen()¶

getStaticEntry()¶

getStaticHash()¶

getTime()¶

getView()¶

isDiskCachingAllowed()¶

isExternalRenderAllowed()¶

isHotRender()¶

isROIAbsolute()¶

isTaskCachingIgnored()¶

matchVariableWithCEL()¶

class NodegraphAPI.GraphStateBuilder¶

Bases: object

__init__¶: x.__init__(...) initializes x; see help(type(x)) for signature

__new__(S, ...) → a new object with type S, a subtype of T¶

build()¶

deleteDynamicEntry()¶

deleteStaticEntry()¶

setDiskCachingAllowed()¶

setDynamicEntry()¶

setExternalRenderAllowed()¶

setHotRender()¶

setIgnoreTaskCaching()¶

setMaxTimeSamples()¶

setROI()¶

setRenderMethodName()¶

setSampleRateX()¶

setSampleRateY()¶

setShutterClose()¶

setShutterOpen()¶

setStaticEntry()¶

setTime()¶

setView()¶