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.

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