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)¶

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.
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 seconds since the last crash save.

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¶

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¶

build()¶

deleteDynamicEntry()¶

deleteStaticEntry()¶

setDiskCachingAllowed()¶

setDynamicEntry()¶

setExternalRenderAllowed()¶

setHotRender()¶

setIgnoreTaskCaching()¶

setMaxTimeSamples()¶

setROI()¶

setRenderMethodName()¶

setSampleRateX()¶

setSampleRateY()¶

setShutterClose()¶

setShutterOpen()¶

setStaticEntry()¶

setTime()¶

setView()¶