Asset API (C++)

group FnAsset

This API allows the implementation of two plugin types:

  • Asset Plugin - which implements the connection of Katana with an Asset Management System (see Asset).

  • File Sequence Plugin - which tells Katana how a fileSequence should be described as a string, and how to resolve that string into a real file path when given a frame number (see FileSequence).

Each Katana Scene will have one Asset plugin and one FileSequence plugin associated with it (see in the Katana UI: Project Settings tab-> plugins -> asset / fileSequence) Which can be accessed from other plugins using the classes DefaultAssetPlugin and DefaultFileSequencePlugin

Both Plugins can also be implemented in Python with a very similar interface (see the documentation for the AssetAPI Python module). Python plugins will be accessed by Katana and by any plugin using the DefaultAssetPlugin and DefaultFileSequencePlugin classes in a transparent way.

General design

An asset, as used in Katana, is a reference to input/output data – usually files on disk. The reference typically resolves to a file path or sequence on disk, but this is not a requirement. It could resolve to a colorspace name or shader library version string, for instance. Scene files, input geometry/images, look files, and more can be referenced as assets in Katana. Although all these inputs and outputs can be specified directly as file system paths, asset systems exist to provide higher-level tracking, versioning, and publishing of this data than the file system alone provides.

Assumptions about asset systems

  • A reference to an asset can be uniquely serialized to/from a single string value (referred to as an AssetId). In Imageworks’ Vnp system, this is the spref url syntax(e.g. {spref:product.type?v=current}), but could just as easily be a guid or a serialized python dict.
  • Each asset has at least two levels of hierarchy: the basic asset container, which may contain multiple asset versions.
  • Each asset reference has some basic required Fields associated with it (“name” and “version” are currently the only two mandatory fields for every asset).
  • Each asset can have a set of non-mandatory Attributes (name/value pairs) in which some meta-data related with the asset can be stored or used by the Asset Management System (Example: an image asset might have its LUT name, file type and resolution associated with it)

File Plugins

File sequence Plugins allow to set the way file sequence paths are represented and resolved by Katana. Check the documentation about the FileSequence class for more information.

class DefaultAssetPlugin
#include <FnDefaultAssetPlugin.h>

Allows the access to the currently set Asset Management System plugin.

This class can be used when a plugin (a Scenegraph Generator, for example) needs to resolve or publish assets using the Asset Management System Plugin set on the current scene (regardless if it is implemented in C++ or Python)....

Public Static Functions

static bool isAssetId(const std::string &str, bool throwOnError = false)

Return whether the input string represents a valid asset id.

Should parse the input string to determine whether it is a valid asset id. Should not attempt to determine whether the asset actually exists in the asset database.

Return
True if the string is valid asset id syntax.
Parameters
  • str -

    The string to test.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static bool containsAssetId(const std::string &str, bool throwOnError = false)

Return whether the input string contains a valid asset id anywhere within it.

Should parse the input string to determine whether it contains a valid asset id. Should not attempt to determine whether any asset ids found in the string actually exist in the asset database.

Return
True if the string contains a valid asset id.
Parameters
  • str -

    The string to test.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string resolveAsset(const std::string &assetId, bool throwOnError = false)

Lookup asset id in asset system and return path (or other string) that it references.

Return
The resolved asset string.
Parameters
  • assetId -

    Asset id to resolve.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string resolveAllAssets(const std::string &inputString, bool throwOnError = false)

Replace any asset ids found in the given input string with resolved asset strings.

Return
The string with all asset ids replaced with resolved asset strings.
Parameters
  • inputString -

    The string to be searched for asset ids.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string resolvePath(const std::string &path, int frame, bool throwOnError = false)

Resolve env vars in input path string, then resolve asset ids and file sequences.

File sequence will most likely be resolved using default file sequence plugin from host. This is a good candidate for some base functionality in the C++ wrappers on the plugin side.

Return
The resolved path string.
Parameters
  • path -

    Input path string to resolve.

  • frame -

    Frame number to resolve file sequences with.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string getUniqueScenegraphLocationFromAssetId(const std::string &assetId, bool includeVersion, bool throwOnError = false)
static std::string getRelatedAssetId(const std::string &assetId, const std::string &relation, bool throwOnError = false)
static bool getAssetAttributes(const std::string &assetId, const std::string &scope, std::map<std::string, std::string> &attributesMap, bool throwOnError = false)

Gets metadata associated with an asset or a scoped item in the asset hierarchy.

Return
Parameters
  • assetId -

    The id of the asset to search for metadata.

  • scope -

    A scoped item name.

  • attributesMap -

    A map to be filled with the metadata attributes of the given asset.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static bool checkPermissions(const std::string &assetId, const std::map<std::string, std::string> &context, bool throwOnError = false)

Returns whether permissions for the given asset id are valid in the given context.

Return
Parameters
  • assetId -

    The id of the asset to check permission for.

  • context -

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string resolveAssetVersion(const std::string &assetId, const std::string &versionTag = std::string(), bool throwOnError = false)

Returns the version for a given asset id. If it is a partial asset id (which does not have a version) then an empty string is returned.

Return
String with the integer version number that this asset id resolves to, or an empty string if an error occurs.
Parameters
  • assetId -

    The asset id to resolve.

  • versionTag -

    An optional version tag to use for determining the resulting version. Can be an explicit version number or a special tag such as “latest” or “approved”.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string getAssetDisplayName(const std::string &assetId, bool throwOnError = false)

Returns a name suitable for displaying to the user for the given asset id.

Return
The display name of the given asset.
Parameters
  • assetId -

    The asset id to look for display name.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static bool getAssetVersions(const std::string &assetId, std::vector<std::string> &versions, bool throwOnError = false)

Gets a list of all the available versions of the given asset.

Return
True on success.
Parameters
  • assetId -

    The asset id to look for available versions.

  • versions -

    The vector to be filled with the available versions of the given asset.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static bool getAssetFields(const std::string &assetId, bool includeDefaults, std::map<std::string, std::string> &returnFields, bool throwOnError = false)

Convert from asset id to a set of named string fields defining the asset.

The minimum set of fields are “name” and “version”. Other fields are preserved but ignored by Katana.

Return
True on success.
Parameters
  • assetId -

    Input asset id.

  • includeDefaults -

    If true, return the full set of fields for this asset system, including defaults not specified in the asset id. If false, return only the fields specified in the asset id.

  • returnFields -

    A map to be filled with the asset fields.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string buildAssetId(const std::map<std::string, std::string> &fields, bool throwOnError = false)

Builds and return a new asset id using the given fields.

Return
The new asset id, on success. Otherwise an empty string.
Parameters
  • fields -

    A map of fields used to build the new asset id.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string getAssetIdForScope(const std::string &assetId, const std::string &scope, bool throwOnError = false)

Gets an asset id scoped to the specified level in the asset hierarchy.

Should return a more general asset reference to the given asset id. For instance, if scope is “name”, returns an asset id that doesn’t include a specific version number. This may not make sense in some asset systems, in which case, return the input asset id.

Return
A string containing the result asset id.
Parameters
  • assetId -

    The input asset id.

  • scope -

    A string specifying scope for result asset id, such as “name” or “version”.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

class DefaultFileSequencePlugin
#include <FnDefaultFileSequencePlugin.h>

Allows the access to the currently set File Sequence plugin.

This class can be used when a plugin (a Scenegraph Generator, for example) needs to do build or resolve a file sequence using the File Sequence Plugin set in the current Katana scene.

Public Static Functions

static bool isFileSequence(const std::string &path, bool throwOnError = false)

Return true if string is a valid file sequence.

Parameters
  • path -

    The string to test.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string buildFileSequenceString(const std::string &prefix, const std::string &suffix, int padding, bool throwOnError = false)

Return a valid file sequence string built from input prefix/suffix/padding.

Parameters
  • prefix -

    A string with the portion of the sequence path before the frame symbol(s)

  • suffix -

    A string with the portion of the sequence path after the frame symbol(s)

  • padding -

    The size of the zero padding for the frame number

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static std::string resolveFileSequence(const std::string &path, int frame, bool throwOnError = false)

Resolves a file sequence string into an single real file path.

Given a sequence path string and a frame number, it returns the actual file path for that frame.

Parameters
  • path -

    The sequence path string.

  • frame -

    The frame number.

  • throwOnError -

    Boolean setting whether to throw an exception on error.

static bool isFrameInFileSequence(const std::string &path, int frame, bool throwOnError = false)

Returns whether or not a given frame is a part of the file sequence.

Return
true if the frame is a part of the file sequence, false otherwise
Parameters
  • path -

    The sequence path string

  • frame -

    The frame number

  • throwOnError -

    Boolean setting whether to throw an exception on error.

class Asset
#include <FnAsset.h>

Primary class to derive from when implementing asset system plugin.

This is a virtual base class to be extended in your plugin.

In addition to implementing all the pure virtual functions in this class, you must also implement a static method in your derived class:

 // return a new instance of your derived class, owned by caller.
 static Asset *create();

To indicate an error to the caller, your implemntation may throw an exception derived from std::exception.

Subclassed by FileAsset

Public Types

typedef std::map<std::string, std::string> StringMap
typedef std::vector<std::string> StringVector

Public Functions

Asset()
virtual ~Asset()
virtual void reset() = 0

Reset will be called when Katana flushes its caches, giving the plugin a chance to reset.

virtual bool isAssetId(const std::string &str) = 0

Return whether the input string represents a valid asset id.

Should parse the input string to determine whether it is a valid asset id. Should not attempt to determine whether the asset actually exists in the asset database.

Return
True if the string is valid asset id syntax.
Parameters
  • str -

    The string to test.

virtual bool containsAssetId(const std::string &str) = 0

Return whether the input string contains a valid asset id anywhere within it.

Should parse the input string to determine whether it contains a valid asset id. Should not attempt to determine whether any asset ids found in the string actually exist in the asset database.

Return
True if the string contains a valid asset id.
Parameters
  • str -

    The string to test.

virtual bool checkPermissions(const std::string &assetId, const StringMap &context) = 0

Returns whether permissions for the given asset id are valid in the given context.

Return
True if permissions for the given asset id are valid in the given context.
Parameters
  • assetId -

    Asset id to check permissions for.

  • context -

    Additional strings used to specify more details about permissions to be checked. Examples include current user or current show environment.

virtual bool runAssetPluginCommand(const std::string &assetId, const std::string &command, const StringMap &commandArgs) = 0

Runs a custom command for the given asset id.

Return
True if the command execution succeeds.
Parameters
  • assetId -

    Asset id the command will be run on.

  • command -

    Name of the command to run.

  • commandArgs -

    Key-string pair representing the command arguments.

virtual void resolveAsset(const std::string &assetId, std::string &ret) = 0

Lookup asset id in asset system and return path (or other string) that it references.

Parameters
  • assetId -

    Asset id to resolve.

  • ret -

    Set to resolved asset string.

virtual void resolveAllAssets(const std::string &str, std::string &ret) = 0

Replace any asset ids found in input string with resolved asset strings.

Parameters
  • str -

    Input string to resolve.

  • ret -

    Set to resolved asset string.

virtual void resolvePath(const std::string &str, const int frame, std::string &ret) = 0

Resolve env vars in input path string, then resolve asset ids and file sequences.

File sequence will most likely be resolved using default file sequence plugin from host. This is a good candidate for some base functionality in the C++ wrappers on the plugin side.

Parameters
  • str -

    Input path string to resolve.

  • frame -

    Frame number to resolve file sequences with.

  • ret -

    Set to resolved path string.

virtual void resolveAssetVersion(const std::string &assetId, std::string &ret, const std::string &versionStr = std::string()) = 0

Return the version that this asset id resolves to.

Parameters
  • assetId -

    Input asset id resolve.

  • ret -

    Returns the version that this asset id resolves to.

  • versionStr -

    In some asset management systems the version can be specified by keywords (example: latest, aproved, etc) that might be associated to a specific version number. If versionStr is specified, then the plugin will try to return (on ret) the resolved string number for the assetId specified by str and the given version keyword (the versionStr value).

virtual void getUniqueScenegraphLocationFromAssetId(const std::string &assetId, bool includeVersion, std::string &ret) = 0

Return a valid scenegraph location path that uniquely represents the input asset id.

This will be used as the default location for look file materials loaded into the Katana scene, for example. (Example: /name/version/other/fields).

Parameters
  • assetId -

    Input asset id to represent as scenegraph location path.

  • includeVersion -

    allows to specify if the scenegraph location path should contain the asset version

  • ret -

    Set to scenegraph location path.

virtual void getAssetDisplayName(const std::string &assetId, std::string &ret) = 0

Returns a string that can be used in GUIs, for example.

Parameters
  • assetId -

    The asset for which the display name is required

  • ret -

    Return value with the display name.

virtual void getAssetVersions(const std::string &assetId, StringVector &ret) = 0

Returns a vector of strings listing the available versions for the given asset.

Parameters
  • assetId -

    The asset who’s versions we want

  • ret -

    The string vector of available versions

virtual void getRelatedAssetId(const std::string &assetId, const std::string &relation, std::string &ret) = 0

Return asset id that is related to input asset, given a relationship type.

A general function for getting related assets. An current example in Katana is an “argsxml” asset defining the UI for a renderer procedural asset.

Parameters
  • assetId -

    Input asset id for which to find related asset.

  • relation -

    String representing relationship type.

  • ret -

    Set to related assed id (or empty string if no related asset is found).

virtual void getAssetFields(const std::string &assetId, bool includeDefaults, StringMap &returnFields) = 0

Convert from asset id to a set of named string fields defining the asset.

The minimum set of fields are “name” and “version”. Other fields are preserved but ignored by Katana.

Parameters
  • assetId -

    Input asset id.

  • includeDefaults -

    If true, return the full set of fields for this asset system, including defaults not specified in the asset id. If false, return only the fields specified in the asset id.

  • returnFields -

    Fill map with key/value strings representing asset fields.

virtual void buildAssetId(const StringMap &fields, std::string &ret) = 0

Convert from asset fields to asset id.

The inverse of getAssetFields, this takes a set of asset fields and returns an asset id string.

Parameters
  • fields -

    String map containing key/value strings representing asset fields.

  • ret -

    Set to asset id.

virtual void getAssetAttributes(const std::string &assetId, const std::string &scope, StringMap &returnAttrs) = 0

Get metadata associated with an asset or a scoped item in the asset hierarchy.

This differs from the above “asset fields” which are the fields that uniquely define the asset itself. This metadata may include fields such as asset creator, creation time, etc.

Parameters
  • assetId -

    Asset for which to return metadata.

  • scope -

    Optional string specifying scope for metadata lookup, such as “name” or “version”.

  • returnAttrs -

    Fill with key/value strings representing metadata attributes.

virtual void setAssetAttributes(const std::string &assetId, const std::string &scope, const StringMap &attrs) = 0

Set metadata associated with an asset or a scoped item in the asset hierarchy.

This differs from the above “asset fields” which are the fields that uniquely define the asset itself. This metadata may include fields such as asset creator, creation time, etc.

Parameters
  • assetId -

    Asset for which to set metadata.

  • scope -

    Optional string specifying scope for metadata lookup, such as “name” or “version”.

  • attrs -

    String map containing key/value strings representing metadata attributes.

virtual void getAssetIdForScope(const std::string &assetId, const std::string &scope, std::string &ret) = 0

Get partial asset id scoped to the specified level in the asset hierarchy.

Should return a more general asset reference to the given asset id. For instance, if scope is “name”, return an asset id that doesn’t include a specific version number. This may not make sense in some asset systems, in which case, return the input asset id.

Parameters
  • assetId -

    Input asset id.

  • scope -

    String specifying scope for result asset id, such as “name” or “version”.

  • ret -

    Set to result asset id.

virtual void createAssetAndPath(AssetTransaction *txn, const std::string &assetType, const StringMap &assetFields, const StringMap &args, bool createDirectory, std::string &assetId) = 0

Create asset and optional directory path.

Parameters
  • txn -

    Handle to transaction object. If null, asset/directory creation is done immediately.

  • assetType -

    Type of Katana asset to create (e.g. katana scene, image, shadow, etc)

  • assetFields -

    GroupAttribute representing asset fields for asset to create (same as getAssetFields output).

  • args -

    Additional args used to specify more details (may differ based on assetType). Examples include “versionUp”, which is a boolean determining whether to version up an existing asset or “colorspace” if the assetId is of the type “image” (in which if this is provided it should be seen as an Attribute to be associated with the asset)

  • createDirectory -

    Boolean specifying whether to create the directory associated with this asset.

  • assetId -

    Set to the asset id created (or that will be created on transaction commit).

virtual void postCreateAsset(AssetTransaction *txn, const std::string &assetType, const StringMap &assetFields, const StringMap &args, std::string &assetId) = 0

Creates an asset after the creation of the files to be published.

Parameters
  • txn -

    Handle to transaction object. If null, asset/directory creation is done immediately.

  • assetType -

    Type of Katana asset to create (e.g. katana scene, image, shadow, etc)

  • assetFields -

    GroupAttribute representing asset fields for asset to create (same as getAssetFields output).

  • args -

    Additional args used to specify more details (may differ based on assetType). Examples include “versionUp”, which is a boolean determining whether to version up an existing asset.

  • assetId -

    Set to the asset id created (or that will be created on transaction commit).

virtual AssetTransaction *createTransaction()

Create a transaction object.

Transaction objects are used to group asset/directory creation actions to allow them to succeed or fail as a unit.

Return
Pointer to heap-allocated instance of derived AssetTransaction. Caller owns returned instance. If asset plugin does not support transactions, always return 0x0.

class AssetTransaction
#include <FnAsset.h>

Virtual base for asset transactions.

Derive from this in your plugin to support transactions. A SimpleTransaction class is included here that maintains a list of actions to be executed on commit().

Subclassed by Foundry::Katana::SimpleTransaction

Public Functions

AssetTransaction()
virtual ~AssetTransaction()
virtual void cancel() = 0

Cancel transaction.

virtual bool commit() = 0

Commit transaction.

class SimpleAction
#include <FnAsset.h>

Simple action base class for performing an action (doit) and rolling it back (rollback) in case of error in this or subsequent action.

Public Functions

virtual ~SimpleAction()
virtual bool doit() = 0
virtual void rollback() = 0
class SimpleTransaction
#include <FnAsset.h>

Simple transaction maintains a list of actions. If an action returns failure during commit, execution is canceled and rollback() is called on all previously executed actions in transaction.

Inherits from Foundry::Katana::AssetTransaction

Public Functions

virtual ~SimpleTransaction()
void addAction(SimpleAction *action)
virtual void cancel()

Cancel transaction.

virtual bool commit()

Commit transaction.

class FileSequence
#include <FnFileSequence.h>

Primary class to derive from when implementing file sequence plugin.

File sequences are closely related to the asset system. A file sequence spec is a file path that contains tokens to be substituted with the current frame number. Some file sequence specs may also specify the frame range of the sequence.

An example from the FileSeq plugin: /path/to/image.1-10#.exr

This example references a sequence of images, frames 1 through 10, with the frame number zero-padded to length 4.

Resolving this sequence at frame 5 would result in: /path/to/image.0005.exr

In addition to implementing all the pure virtual functions in this class, you must also implement static methods in your derived class:

 // return a new instance of your derived class, owned by caller.
 static FileSequence * create(const char *);

 // return true if string is a valid file sequence
 static bool isFileSequence(const char*);

 // return a valid file sequence string built from input prefix/suffix/padding
 std::string buildFileSequenceString(const std::string &prefix, const std::string &suffix, int padding);

 // return a new FileSequenceArray instance containing sequences and non-sequence file paths found
 // in input file path list
 FileSequenceArray* findSequence(const char** fileList, unsigned int fileCount);

To indicate an error to the caller, your implemntation may throw an exception derived from std::exception.

Subclassed by FileSeq

Public Functions

FileSequence()
FileSequence(const std::string&)
virtual ~FileSequence()
virtual bool isValid() const = 0

Return whether this instance contains a valid file sequence.

virtual FileSequence *clone() const = 0

Return new copy of this class instance.

virtual void getAsString(std::string &retValue) = 0

Get string representation of the file sequence.

Parameters
  • retValue -

    Set to file sequence string.

virtual void getDirectory(std::string &retValue) = 0

Get the directory portion of file sequence.

Parameters
  • retValue -

    Set to directory portion of file sequence (e.g. “/a/b/c” for fileseq “/a/b/c/d.#.exr”).

virtual void getPrefix(std::string &retValue) = 0

Get the portion of file sequence before the frame number.

Parameters
  • retValue -

    Set to prefix portion of file sequence (e.g. “/a/b/c/d.” for fileseq “/a/b/c/d.#.exr”).

virtual void getSuffix(std::string &retValue) = 0

Get the portion of file sequence after the frame number.

Parameters
  • retValue -

    Set to suffix portion of file sequence (e.g. ”.exr” for fileseq “/a/b/c/d.#.exr”).

virtual unsigned int getPadding() = 0

Get the padding of the file sequence frame number.

Return
Padding amount of file sequence (e.g. 4 for fileseq that expands to image.0001.exr)

virtual void getResolvedPath(const int frame, std::string &retValue) = 0

Get the filename for file sequence with sequence portion replaced by correctly padded frame.

Parameters
  • frame -

    The frame to get the filename.

  • retValue -

    Set to resolved filename.

virtual bool hasFrameSet() = 0

Return whether file sequence has explicit frame set.

Return
True if file sequence has explicit frame range (set) embedded in it (e.g. “image.1-10#.exr”).

virtual bool isFrameInFrameSet(const int frame) = 0

Test whether frame is within explicit frame set.

Return
True if frame is in frame set. If file sequence does not have explicit frame set, always return true.

virtual int getFirstFrameInFrameSet() = 0

Return first frame in explicit frame set.

Return
First (minimum) frame in frame set. If file sequence does not have explicit frame set, always return 0.

virtual int getLastFrameInFrameSet() = 0

Return last frame in explicit frame set.

Return
Last (maximum) frame in frame set. If file sequence does not have explicit frame set, always return 0.

virtual void getNearestFramesInFrameSet(int frame, bool *hasLeft, int *nearestLeft, bool *hasRight, int *nearestRight) = 0

Return nearest frame to left and right of frame.

Set return values to (false, 0, false, 0) if file sequence does not have explicit fram set.

Parameters
  • frame -

    Frame number to return nearest frames of.

  • hasLeft -

    Set to true if frame exists in list to left of specified frame.

  • nearestLeft -

    Set to nearest frame in list to left of specified frame.

  • hasRight -

    Set to true if frame exists in list to right of specified frame.

  • nearestRight -

    Set to nearest frame in list to right of specified frame.

virtual void getFrameListFromFrameSet(std::vector<int> &returnList) = 0

Get frame set as list of integers.

Parameters
  • returnList -

    Fill with integer frame numbers (e.g. [1,2,3,4,5] for “image.1-5#.exr”).

class FileSequenceArray
#include <FnFileSequence.h>

Container class that holds a vector of FileSequence instances and a vector of non-sequence filenames.

Public Functions

FileSequenceArray(std::vector<FileSequence *> &seq, std::vector<std::string> &nonseq)
virtual ~FileSequenceArray()
virtual int getFileSequenceCount()

Number of file sequence objects in vector.

virtual FileSequence *getFileSequence(const unsigned int index)

Get FileSequence object ptr by index. The caller does not own the FileSequence object returned.

virtual void getFileNames(std::vector<std::string> &fileNames)

Get vector of non-sequence file names.