Houdini’s various asset gallery panels (the snapshot gallery attached to the LOP Scene Viewer, the Working Set gallery in the Layout LOP’s brush panel, and the Asset Gallery pane) are all populated by pulling data from this class. This object is created by providing a source identifier, and an optional additional string argument. The source identifier is used to find or create a shared underlying data source implementation object (which may be a C++ or python object). These implementation objects are responsible for responding to the methods called on this object.
Houdini ships with three data source implementations. One uses an SQL database with read and write capabilities. This data source implementation type is used when the source identifier is a file path with a .db, .sqlite, or .sqlite3 extension. Another supports any file on disk with a USD file extension. This data source is read only, and accepts an additional argument specifying the primitive pattern indicating which primitives in the USD file should be presented as assets. Finally, if the source identifier beings with an op: prefix followed by a path to a LOP node, the stage for that LOP node is used as a read only data source, and again the additional argument specifies a primitive pattern to indicate which primitives on the source stage represent assets.
To create a new data source implementation in C++, you must create a subclass of UT_GalleryDataSourceImpl (see UT_GalleryDataSource.h), and register it by calling UT_GalleryDataSource::registerDataSourceImplementation. To create a new data source implementation in python, create a subclass of the DataSource object defined in the husd.datasource module, and place it in the $HFS/houdini/husdplugins/datasources directory. See the usdfile.py module for an example.
The methods on this class almost always simply forward the call to the underlying data source implementation object. So the decription of each method here also serves to document the action an that should be undertaken in each correspondingly named method on an implementation class.
Methods ¶
__init__(source_identifier, args=None)
→ AssetGalleryDataSource
Constructs or finds a matching existing data source implementation object based on the source_identifier and optional implementation-specific args parameter.
isValid()
→ bool
Return True if this data source has a valid implementation, otherwise return False. Returning False usually indicates that the source identifier does not represent an existing file or LOP node, or that the file type is not supported by any data source implementation classes.
isReadOnly()
→ bool
Return True if this data source only supports read operations, otherwise return False. A data source implementation that returns False for this method will never have any of its set methods called, and any attempts to call these methods on this object will immediately return False.
sourceIdentifier()
→ str
Return the source identifier string used to create this data source object.
sourceArgs()
→ str
Return the args string used to create this data source object.
startTransaction()
For writable data sources, this method can be used to group multiple calls to edit the data source. Once this method is called, requests to edit the data source do not actually need to edit the underlying data source until the endTransaction method is called.
endTransaction(commit=True)
This method is always called after a call to startTransaction, and indicates that the group of data source edits has been completed. When this method returns, all edits since the call to startTransaction should be committed to the data source. If the commit parameter is False, all edits since the call to startTransaction should be discarded, and none of them should be recorded to the data source.
itemIds()
→ tuple
of str
Return a unique identifier for each asset available in the data source. The ids returned by this method will be used to identify individual assets in every other method that gets or sets information associated with a specific asset.
updatedItemIds()
→ tuple
of str
Return a unique identifier for any asset that has changed since the last call to this method. This method is polled regularly by the asset gellery to handle cases where the underlying data source may change, or where data my not have been available when it was queried, but the item’s data has since become available.
childItemIds(item_id)
→ tuple
of str
Return a list of unique identifier for all assets that have this item set as its parent. Passing an empty string as the item_id will return a list of items that have the 'root' as their parent.
infoHtml()
→ str
Return a string in HTML format that will be displayed at the top of the asset gallery window. Provides custom information about the data source. Can return an empty string to indicate that the HTML info window at the top of the gallery should be hidden.
sourceTypeName(item_id=None)
→ str
Return the data source type of the asset identified by the id. The source type controls how the asset is instantiated in a Houdini LOP Network. Generally all the assets from a data source will return the same sourceTypeName, which is why the item_id parameter here is optional. Only data sources that aggregate data from multiple other sources would return per-asset values from this method.
typeName(item_id)
→ str
Return the type of asset identied by the id. This will either be snapshot (for a snapshot in a snapshot gallery) or asset (for an asset in an asset gallery).
label(item_id)
→ str
Return the user-facing string that identifies and describes the item. This value need not be unique, and is normally displayed under the item’s thumbnail image.
thumbnail(item_id)
→ bytes
Return the raw data for a thumbnail image that represents the item.
creationDate(item_id)
→ int
Return a long integer representing the unix timestamp at which the item was created.
modificationDate(item_id)
→ int
Return a long integer representing the unix timestamp at which the item was last modified.
isStarred(item_id)
→ bool
Return True if this item has been marked as a “favorite” by the user.
colorTag(item_id)
→ str
Return a string indicating a special color tag value that has been assigned by the user. These color strings are displayed as colored bars in the gallery browser UI. Supported values are blue, green, purple, yellow, teal, and red.
tags(item_id)
→ tuple
of str
Return a tuple of user defined tag strings that have been assigned to this item.
metadata(item_id)
→ dict
of str
to str
or float
Return a dictionary of metadata that has been associated with this item. This metadata may be user created, or automatically (such as by a renderer used to create an image in the snapshot gallery).
filePath(item_id)
→ str
Return a string that can be used to access the raw data assocaited with this item. In the case of a snapshot, this will be path to the snapshot image file on disk. In the case of an asset, this will be the path to a USD file on disk or a string representing a path to the LOP node which defines this asset.
ownsFile(item_id)
→ bool
Return True if the filePath for this item is a file on disk that should be deleted if the item is deleted. This is generally True for a snapshot image, but False for a USD asset file (though in a custom data source implementation, it may also be True for a USD asset).
blindData(item_id)
→ bytes
Return a block of data source implementation specific binary data associated with the item. For a snapshot item, this will be the binary representation of the contents of the LOP Network when the snapshot was taken. For a USD asset, this may be a string representing information needed to pull a specific primitive out of a USD file (such as the root primitive path and variant selections). This blind data on an asset can be used by the data source specific code for instantiating an asset in a LOP network.
status(item_id)
→ str
Return a string describing the current status of this item. This field is used for render gallery background renders to track when the render is running (render_active), has completed (render_complete), or there was an error while rendering (error).
parentId(item_id)
→ str
Return the unique identifier for this item’s parent item. If this item has no parent then an empty string is returned. This also indicates that the item is at thr 'root' of the tree.
prepareItemForUse(item_id)
→ str
Make sure that the item is ready to be used. For data sources that point to remote databases, this method may involve downloading the item’s data. Return an empty string if the item is ready for use, otherwise return an error string describing why the item could not be prepared.
setLabel(item_id, label)
→ bool
Set the value of the label for this item. Return True if this call resulted in a change to this value.
setThumbnail(item_id, thumbnail)
→ bool
Set the value of the thumbnail for this item. Return True if this call resulted in a change to this value.
setModificationDate(item_id, timestamp)
→ bool
Set the value of the modificationDate for this item. Return True if this call resulted in a change to this value.
setIsStarred(item_id, isstarred)
→ bool
Set the value of the isStarred flag for this item. Return True if this call resulted in a change to this value.
setColorTag(item_id, color_tag)
→ bool
Set the value of the colorTag for this item. Return True if this call resulted in a change to this value.
setMetadata(item_id, metadata)
→ bool
Set the value of the metadata dictionary for this item. Return True if this call resulted in a change to this value.
setFilePath(item_id, file_path)
→ bool
Set the value of the filePath for this item. Return True if this call resulted in a change to this value.
setOwnsFile(item_id, owns_file)
→ bool
Set the value of the ownsFile flag for this item. Return True if this call resulted in a change to this value.
setBlindData(item_id, data)
→ bool
Set the value of the blindData for this item. Return True if this call resulted in a change to this value.
setParentId(item_id, parent_item_id)
→ bool
Set the value of the parent of this item to be parent_item_id. Setting to an empty string indicates this item has no parent and is therefore at the root of the tree.
createTag(tag)
→ bool
Create a tag in the data source, but do not assign it to any items. Return True if the tag did not already exist and was created.
deleteTag(tag, delete_if_assigned)
→ bool
Delete a tag from the data source. Return True if the tag existed and was removed. If delete_if_assigned is False, and the tag is assigned to any item, this function will do nothing and return False. If delete_if_assigned is True and the tag is assigned to any items, the tag is first unassigned from those items, then the tag is deleted.
addTag(item_id, tag)
→ bool
Adds a tag to a specific item. Creates the tag if it does not already exist. Return True if the tag was added to the item. Return False if the tag was already assigned to the item.
removeTag(item_id, tag)
→ bool
Removes a tag from a specific item. Return True if the tag was removed from the item. Return False if the tag was not assigned to the item.
generateItemFilePath(item_id, file_ext)
→ str
Return a unique file path with an extension provided in file_ext. This helpful is useful for creating external files such as snapshot images on disk, as it automatically puts the image in the same location as the database file.
addItem(label, file_path=None, thumbnail=b'', type_name='asset', blind_data=b'', creation_date=0)
→ str
Adds a new item to the data source. Sets the label, filePath, thumbnail, typeName, blindData, and creationDate values for the item. Return the item_id of the newly created item, or an empty string if the item could not be added.
markItemsForDeletion(item_ids)
→ bool
Marks one or more items to be deleted. Ideally this deletion does not happen until the data source is destroyed, indicating that the user has switched data sources or shut down Houdini. By only marking the item for future deletion instead of deleting the items, it is possible to undo the deletion using the unmarkItemsForDeletion method. But while an item is marked for deletion, it should not be returned by the itemIds method, or return any values when queried by other methods. Return True if the items were successfully marked for deletion. If a data source cannot support undoing the deletion of an item, this method should delete the item and return True.
unmarkItemsForDeletion(item_ids)
→ bool
Remove the indicator in the data source that the supplied items should be deleted. This is used to undo the requested deletion of an item. Return True if the specified items were successfully undeleted. If a data source doesn’t support undoing the deletion of an item, return False.
saveAs(source_identifier)
→ bool
Create a copy of the data source, if supported. This will also create copies of the item files, if the ownsFile flag is True.