`reftrack`¶

This module features classes and interfaces to track references and loaded data and manipulate it.

Overview¶

It is the main lib for the reference workflow of the pipeline. It revoles around a Reftrack object. Each Reftrack instance is responsible for one entity. It holds information about the entity, can query the entity and manipulate the entity.

One entity might be a character asset, an alembic cache for the character, a camera or a lightrig. The Reftrack instance can reference, load, unload, import, replace or delete the entity. Once an entity is loaded into your programm, the Reftrack object holds a refobject.

A refobject can be anything, from a node that is in your programm, to a simple string. Important is, that it can be used by the RefobjInterface to identify the entity in your scene and query information. E.g. in Maya, one would create a special Node for each loaded entity. The node can be used to query the reference status, it can identify what entity is loaded etc. So in this case the refobj would be either the node, or the name of the node. Whatever your RefobjInterface accepts.

Again, the RefobjInterface is used to identify the entity, query the parent, status, create new refobjects and manipulate them. It is specific for each software you use. So there should be one implementation of the RefobjInterface for each software. The Reftrack object will interact with the interface to manipulate the scene.

Entity Types¶

Each entity has a certain type. For example one type might be "Asset" and another might be "Shader". Depending on the type and of course the software you are in (or in this case simply the RefobjInterface), you want to perform different actions on loading or deleting the entity. E.g. when loading a shader, you might want to apply the shaders to another entity etc. Or for each type you have special nodes in your software you want to use. The Reftrack object simply asks the RefobjInterface to reference, load, delete or whatever the entity. The RefobjInterface will decide upon the type of the Reftrack to use another interface. This interface is called ReftypeInterface.

The ReftypeInterface should be implemented for each type of entities for each software. So if your software supports assets, shaders and alembic caches as types then you need 3 implementations of the ReftypeInterface for this software. The interface actually manipulates the content of the entity. For example, in Maya it will create a reference node and group the loaded data under a transform node for assets. For shaders it might also assing the shaders to certain objects. Make sure that your ReftypeInterface classes are registered at the appropriate RefobjInterface. Use the classmethod RefobjInterface.register_type() on your refobj interface subclass or but them directly in RefobjInterface.types when defining the class.

Parents¶

Each Reftrack object can have a parent. A parent is another Reftack object and is responsible for its children. If the parent is deleted, all other children should be deleted too. This might be the case for a shader. Imagine assigning a shader to an asset. The asset would be the parent and the shader the child. If the asset gets deleted the shader should be deleted to. The Reftrack objects handle such cases by themselves.

Root¶

There is also a ReftrackRoot class. It is important to group all reftracks of your current scene under the same root. The root object is mainly used to find parent Reftrack objects. But it also provides a Qt model that you can use for views. It holds all Reftrack objects in a tree model.

Creating a Reftrack¶

You can create a Reftrack objects on two ways.

First case would be, you have a scene with refobjs. This would mean, you want to wrap all refobjs in a Reftrack object. There is only a slight problem. If you want to wrap a refobj that defines a shader and has a parent refobj (e.g. an asset) you cannot create set the parent on initialisation, beacause the parent refobj might not be wrapped in a Reftrack object. So you have to wrap all refobjs first, and in a second step find the parent Reftrack and set it. For convenience, there is a class method Reftrack.wrap(). It wraps all refobjs and finds the parents afterwards. This is also why the ReftrackRoot is so important.

The second case would be, you want to add a new Reftrack that is not in your scene. The user would see, that it is not loaded and could choose to reference it or import it. In this case you initialize a Reftrack with a type, element and parent. The type is for example "Shader". The element would be either a Shot or Asset in your database. So you would choose the character asset. The parent would be an already existing Reftrack of the character asset with type "Asset". In other cases, you do not need a parent. E.g. you create a new Reftrack for the character asset. It would have no parent.

Restrictions¶

You can restrict certain actions on a Reftrack instance. All methods that have the decorator restrictable() can be restricted by using Reftrack.set_restricted(). Usually this is automatically done. E.g. you cannot replace an entity if it is not already in the scene. In this case a ReftrackIntegrityError would be raised by the decorated method automatically. See: Reftrack.fetch_reference_restriction(), Reftrack.fetch_load_restriction(), Reftrack.fetch_unload_restriction(), Reftrack.fetch_import_ref_restriction(), Reftrack.fetch_import_f_restriction(), Reftrack.fetch_replace_restriction().

The RefobjInterface or ReftypeInterface can customize the rules for restrictions. For example you could create a rule, that nested references in Maya cannot be replaced.

Usage¶

If you have implementations for each interface, it should be fairly easy to use:

Create a new RefobjInterface instance:
refobjinter = RefobjInterface()  # use a subclass that implemented the abstract methods here.
Create a new ReftrackRoot instance. It needs a root jukeboxcore.gui.treemodel.TreeItem for the model and and a jukeboxcore.gui.treemodel.ItemData subclass to create new items. The item data subclass should accept a Reftrack object for the initialisation and returns data for several attributes of the Reftrack instance. You do not have to specify a rootitem or itemdataclass necessarily. If you do not the root object will create standard ones. Only if you need custom ones you can specify them:
from jukeboxcore.gui.treemodel import TreeItem, ListItemData
rootdata = ListItemData(["Name", "Status", "Version"])  # root data will be used for headers in views
rootitem = TreeItem(rootdata)
reftrackroot = ReftrackRoot(rootitem, myitemdataclass)  # use your ItemData subclass here.
Now lets create new Reftrack instances. First lets create a reftrack for every refobj in the current scene:
# get all refobjs in the scene
refobjs = refobjinter.get_all_refobjs()
# wrap them in reftrack instances
reftracks = Reftrack.wrap(reftrackroot, refobjinter, refobjs)
# alternatively if you only want to wrap the ones you haven't
# this would return all refobjects that are not in root
newrefobjs = Reftrack.get_unwrapped(reftrackroot, refobjinter)
newreftracks = Reftrack.wrap(reftrackroot, refobjinter, newrefobjs)
# convenience function to wrap unwrapped refobjects and also get suggestions:
newrefobjs = Reftrack.wrap_scene(reftrackroot, refobjinter)
Done. Now to display that in a view you can get the model of the root:
model = reftrackroot.get_model()
# set it on a view. we assume you already have a subclass of QtGui.QAbstractItemView
view.setModel(model)
Now lets say the scene is incomplete. You want to add a new asset (e.g. a tree asset) to the scene. First we need to create a Reftrack object:
# get the tree asset from the database
tree = ...
reftrack = Reftrack(reftrackroot, refobjinter, typ="Asset", element=tree, parent=None)
The model will get updated automatically and the view should automatically update. Lets say you want to reference the tree into your scene. An asset has different deparments or tasks and in each task there are multiple releases. Each Reftrack object can give you options from which to choose a file to load or replace. The options are a jukeboxcore.gui.treemodel.TreeModel with jukeboxcore.filesys.TaskFileInfo as leafes. I explicitly say leafes because the options might be sorted in a tree like strucure. So the user could first select a task and then the apropriate release. You can take the model and display it to the user so he can select a file.:
# get the treemodel for the options
options = reftrack.get_options()
# put it in another view
optionsview.setModel(options)
# let the user select a option
# get the selected index (make sure it is a leaf)
sel = optionsview.selectedIndexes()
# sel might be a empty list if the user has not made an selection!
# but lets assume he has selected one index
index = sel[0]
# get the TaskFileInfo for this index.
taskfileinfo = index.internalPointer().internal_data()
reftrack.reference(taskfileinfo)
You could also simply get a list of the avaliable TaskFileInfo of the options by using:
# get all options
options = reftrack.get_option_taskfileinfos()
# assert that there are any available options
if options:
    # pick one
    reftrack.import_entity(options[0])

Get Started¶

So before you start, here is a list of things to do:

Implement a ReftypeInterface for each type.

Implement RefobjInterface. Make sure it has all the types registered. See RefobjInterface.register_type().

Think about creating your custom jukeboxcore.gui.treemodel.ItemData for Reftrack objects.

Create a RefobjInterface instance.

Create a ReftrackRoot instance.

For refobjs in your scene use Reftrack.wrap() or Reftrack.wrap_scene().

Add new reftracks.

class jukeboxcore.reftrack.ReftrackRoot(rootitem=None, itemdataclass=None)[source]¶

Bases: object

Groups a collection of Reftrack objects.

Enables the search for parents via the refobject. Provides a jukeboxcore.gui.treemodel.TreeModel that can be used in views, to display all reftracks.

The model that is created and also updated uses the root item and itemdata class you provided in the constructor. The root item is used for headers in your views. So you could create a root item like this:

rootdata = ListItemData(["Name", "Status", "Version"])  # root data will be used for headers in views
rootitem = TreeItem(rootdata)

The itemdata class will be used to provide data for the model about Reftrack object. You can provide your own subclass or omit the rootitem and itemdataclass. Then a default root item and itemdata class will be used.

Initialize a new Reftrack root with a given root tree item and a jukeboxcore.gui.treemodel.ItemData class to wrap the Reftrack objects.

The ItemData class should accept a Reftrack object as first argument in the constructor.

Parameters:

rootitem (jukeboxcore.gui.treemodel.TreeItem | None) – the root tree item for the treemodel. The root tree item will be responsible for the headers in a view. If no rootitem is provided, a default one is used.
itemdataclass (jukeboxcore.gui.treemodel.ItemData | None) – the itemdata subclass to be used for wrapping the Reftrack objects in the model. Not an instance! A class! The constructor should accept a Reftrack object as first argument. If no class is provided, a default one is used. See: ReftrackItemData

Raises:

None

get_model()[source]¶

Return the treemodel that contains all reftracks of this root

The model uses the provided jukeboxcore.gui.treem.ItemData. The model is automatically updated.

Returns:	The treemodel
Return type:	`TreeModel`
Raises:	None

get_rootitem()[source]¶

Return the rootitem of the treemodel

The root item is responsible for the headers. When adding new TreeItems to the root level use this item as parent.

Returns:	the rootitem
Return type:	`TreeItem`
Raises:	None

add_reftrack(reftrack)[source]¶

Add a reftrack object to the root.

This will not handle row insertion in the model! It is automatically done when setting the parent of the Reftrack object.

Parameters:	reftrack (`Reftrack`) – the reftrack object to add
Returns:	None
Return type:	None
Raises:	None

remove_reftrack(reftrack)[source]¶

Remove the reftrack from the root.

This will not handle row deletion in the model! It is automatically done when calling Reftrack.delete().

Parameters:	reftrack (`Reftrack`) – the reftrack object to remove
Returns:	None
Return type:	None
Raises:	None

update_refobj(old, new, reftrack)[source]¶

Update the parent search dict so that the reftrack can be found with the new refobj and delete the entry for the old refobj.

Old or new can also be None.

Parameters:	old – the old refobj of reftrack new – the new refobj of reftrack reftrack (`Reftrack`) – The reftrack, which refobj was updated
Returns:	None
Return type:	None
Raises:	None

get_reftrack(refobj)[source]¶

Return a the Reftrack instance that wraps around the given refobj

Parameters:	refobj (refobj \| None) – a ref object. See `Reftrack.get_refobj()`
Returns:	The reftrack instance that wraps the given refobj. If no instance is found in this root, a KeyError is raised. If None was given, None is returned
Return type:	`Reftrack` \| None
Raises:	`KeyError`

create_itemdata(reftrack)[source]¶

Return a itemdata for the given reftrack

Parameters:	reftrack (`Reftrack`) – the reftrack to wrap in a itemdata
Returns:	a Itemdata with the reftrack wrapped. The ItemData class depends on what was provided for initialisation of the root.
Return type:	`jukeboxcore.gui.treemodel.ItemData`
Raises:	None

get_scene_suggestions(refobjinter)[source]¶

Return a list of suggested Reftracks for the current scene, that are not already in this root.

A suggestion is a combination of type and element.

Parameters:	refobjinter (`RefobjInterface`) – a programm specific reftrack object interface
Returns:	A list of suggestions
Return type:	`list`
Raises:	None

jukeboxcore.reftrack.restrictable(m)[source]¶

Decorator for Reftrack methods. A decorated method will check if its restriction with Reftrack.is_restricted() and raises a RestrictionError if it is restricted.

Parameters:	m (`Reftrack` method) – The `Reftrack` method to wrap
Returns:	a wrapped method
Return type:	method
Raises:	None

class jukeboxcore.reftrack.Reftrack(root, refobjinter, typ=None, element=None, parent=None, refobj=None)[source]¶

Bases: object

Represents one entity of the reference workflow in a programm

Stores information like the status, options for replacing the entity etc. Delegates actions to the appropriate interfaces. So no matter what kind of programm you are in and what type your entity is, the Reftrack object can carry out all actions as long as you provide 2 interfaces.

A refobj interface will interact will query information about the entity and can create a new refobj, which will store the information in the scene. E.g. in Maya it might be a node which has a connection to the reference node, stores the type of the entity etc. The refobj interface is responsible for creating, editing, deleting the refobj. The refobj interface can query the reftrack object which element the entity represents (which Shot or Asset).

The typ interface is programm and type specific. It manipulates the actual content of the entity. E.g. it will assign shaders upon loading, create references, connect nodes or group the referenced objects.

The Reftrack object only interacts with the RefobjInterface. The interface will interact with the appropriate ReftypeInterface. So whatever type your Reftrack object will be, make sure, your RefobjInterface supports it.

The reftrack has 3 different statuses:

uptodate: If the current loaded version is the newest (does not consider other departments!)

alien: If the reftrack does not belongs to the currently open scene and is not linked as such in the database.

status: Reftrack.LOADED, Reftrack.UNLOADED, Reftrack.IMPORTED, None (If there is no refobj in the scene)

Initialize a new container with a reftrack object interface and either a reftrack object or typ, element, and an optional parent.

Warning

If you initialize with typ, element and parent, never set the parent later, because the parent cannot be changed. Only if the parent was None it is possible. Only when you provide a refobj, you should call Reftrack.set_parent() after you created all Reftrack objects for all refobjs in your scene. In this case it is adviced to use Reftrack.wrap()

Parameters:

root (ReftrackRoot) – the root that groups all reftracks and makes it possible to search for parents
refobjinter (RefobjInterface) – a programm specific reftrack object interface
refobj – a physical representation in your scene of the entity, if it already exists. If you do not specify a reftrack object, then you have to provide at least a typ and element. The refobj type does not matter as long as your reftrack object interface can handle it.
typ (str) – the type of the entity (e.g. Asset, Alembic, Camera etc.). If no refobject is given, this is required
element (jukeboxcore.djadapter.models.Asset | jukeboxcore.djadapter.models.Shot) – the element the entity represents, e.g. an Asset or a Shot.
parent (Reftrack | None) – the parent Reftrack object. All children will be deleted automatically, when the parent gets deleted.

Raises:

TypeError, ValueError

LOADED = 'Loaded'¶: Status for when the entity is referenced in the scene and the reference is loaded.

UNLOADED = 'Unloaded'¶: Status for when the entity is referenced but the reference is not loaded into the scene.

IMPORTED = 'Imported'¶: Status for when the entity is imported.

classmethod wrap(root, refobjinter, refobjects)[source]¶

Wrap the given refobjects in a Reftrack instance and set the right parents

This is the preferred method for creating refobjects. Because you cannot set the parent of a Reftrack before the parent has been wrapped itselfed.

Parameters:	root (`ReftrackRoot`) – the root that groups all reftracks and makes it possible to search for parents refobjinter (`RefobjInterface`) – a programm specific reftrack object interface refobjects (list) – list of refobjects
Returns:	list with the wrapped `Reftrack` instances
Return type:	list
Raises:	None

classmethod wrap_scene(root, refobjinter)[source]¶

Wrap all refobjects in the scene in a Reftrack instance and set the right parents, also add suggestions for the current scene

When you want to quickly scan the scene and display the reftracks in a tool, this is the easiest function.

It uses wrap on all refobjects in the scene, then adds suggestions for the current scene.

Parameters:	root (`ReftrackRoot`) – the root that groups all reftracks and makes it possible to search for parents refobjinter (`RefobjInterface`) – a programm specific reftrack object interface
Returns:	list with the wrapped `Reftrack` instances
Return type:	list
Raises:	None

classmethod get_unwrapped(root, refobjinter)[source]¶

Return a set with all refobjects in the scene that are not in already wrapped in root.

Parameters:	root (`ReftrackRoot`) – the root that groups all reftracks and makes it possible to search for parents refobjinter (`RefobjInterface`) – a programm specific reftrack object interface
Returns:	a set with unwrapped refobjects
Return type:	set
Raises:	None

get_root()[source]¶

Return the ReftrackRoot this instance belongs to.

Returns:	the root
Return type:	`ReftrackRoot`
Raises:	None

get_refobj()[source]¶

Return the reftrack object, the physical representation of your Reftrack object in the scene. If the entity is not loaded, None is returned.

Returns:	the reftrack object
Return type:	None \| reftrack object
Raises:	None

set_refobj(refobj, setParent=True)[source]¶

Set the reftrack object.

The reftrack object interface will determine typ, element, taskfileinfo, status and parent and set these values. If the reftrack object is None, the Reftrack object will keep the initial typ, element but will loose it’s parent, status and taskfileinfo

Parameters:	refobj (None \| reftrack object) – a reftrack object or None setParent (`bool`) – If True, set also the parent
Returns:	None
Return type:	None
Raises:	None

get_typ()[source]¶

Return the type of the entity

E.g. Asset, Alembic, Camera etc. The type will also be a key in RefobjInterface.types.

Returns:	the type of the entity
Return type:	str
Raises:	None

set_typ(typ)[source]¶

Set the type of the entity

Make sure the type is registered in the RefobjInterface.

Parameters:	typ (str) – the type of the entity
Returns:	None
Return type:	None
Raises:	ValueError

get_typ_icon()[source]¶

Return the icon for the type

Returns:	the icon that should be used in UIs to identify the type
Return type:	`QtGui.QIcon` \| None
Raises:	None

get_refobjinter()[source]¶

Return the refobject interface

Returns:	the refobject interface
Return type:	`RefobjInterface`
Raises:	None

get_taskfileinfo()[source]¶

Return the jukeboxcore.filesys.TaskFileInfo that the refobject represents.

Returns:	the taskfileinfo for the refobject or None if nothing is loaded.
Return type:	`jukeboxcore.filesys.TaskFileInfo` \| None
Raises:	None

set_taskfileinfo(tfi)[source]¶

Set the jukeboxcore.filesys.TaskFileInfo that the refobject represents.

Parameters:	tfi (`jukeboxcore.filesys.TaskFileInfo` \| None) – the taskfileinfo for the refobject or None if nothing is loaded.
Returns:	None
Return type:	None
Raises:	None

get_element()[source]¶

Return the element the reftrack represents.

The element is either an Asset or a Shot. Depending on the type only certain files are considered for loading or referencing. See Reftrack.get_options() and Reftrack.fetch_options(). The ReftypeInterface.fetch_options is responsible for providing a treemodel with jukeboxcore.gui.treemodel.TaskFileInfo as leaves.

So if the element is be a character asset and the type is “Shader”, only the shading handoff files for this asset would be considered.

Returns:	The element the reftrack represents
Return type:	`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`
Raises:	None

set_element(element)[source]¶

Set the element for the reftrack to represent.

The element is either an Asset or a Shot. Depending on the type only certain files are considered for loading or referencing. See Reftrack.get_options() and Reftrack.fetch_options(). The ReftypeInterface.fetch_options is responsible for providing a treemodel with jukeboxcore.gui.treemodel.TaskFileInfo as leaves.

So if the element is be a character asset and the type is “Shader”, only the shading handoff files for this asset would be considered.

This will also set the available options and set the alien status.

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element the reftrack represents.
Returns:	None
Return type:	None
Raises:	None

get_parent()[source]¶

Return the parent Reftrack instance

Returns:	None
Return type:	`Reftrack` \| None
Raises:	None

set_parent(parent)[source]¶

Set the parent reftrack object

If a parent gets deleted, the children will be deleted too.

Note

Once the parent is set, it cannot be set again!

Parameters:	parent (`Reftrack` \| None) – the parent reftrack object
Returns:	None
Return type:	None
Raises:	AssertionError

get_id()[source]¶

Return the id of the reftrack

An id is a integer number that will be unique between all reftracks of the same parent, element and type, that have a refobject

Returns:	the id
Return type:	int
Raises:	None

set_id(identifier)[source]¶

Set the id of the given reftrack

This will set the id on the refobject

Parameters:	identifier (int) – the identifier number
Returns:	None
Return type:	None
Raises:	None

fetch_new_id()[source]¶

Return a new id for the given reftrack to be set on the refobject

The id can identify reftracks that share the same parent, type and element.

Returns:	A new id
Return type:	int
Raises:	None

create_treeitem()[source]¶

Create a new treeitem for this reftrack instance.

Note

Parent should be set, Parent should already have a treeitem. If there is no parent, the root tree item is used as parent for the treeitem.

Returns:	a new treeitem that contains a itemdata with the reftrack instanec.
Return type:	`TreeItem`
Raises:	None

get_treeitem()[source]¶

Return the treeitem that wraps this instance.

There is only a treeitem if the parent has been set once. If you use Reftrack.wrap() or initialize a new Reftrack object with type and element, it will have one. Only if you initialize a new Reftrack with a given refobj, Reftrack.set_parent() will not be called automatically.

Returns:	the treeitem for this instance
Return type:	`TreeItem` \| None
Raises:	None

add_child(reftrack)[source]¶

Add the given reftrack object as child

Note

Does not set the parent of the child! Use Reftrack.set_parent() instead.

Parameters:	reftrack (`Reftrack`) – the child `Reftrack` instance
Returns:	None
Return type:	None
Raises:	None

remove_child(reftrack)[source]¶

Remove the given reftrack from children

Note

Does not set the parent of the child to None! Use Reftrack.delete() instead.

Parameters:	reftrack (`Reftrack`) – the child `Reftrack` instance
Returns:	None
Return type:	None
Raises:	ValueError

get_options()[source]¶

Return a jukeboxcore.gui.treemodel.TreeModel with possible options for the reftrack to load, replace, import etc.

The leafes of the jukeboxcore.gui.treemodel.TreeModel should be TreeItems with TaskFileInfo as internal data.

Returns:	a treemodel with options
Return type:	`jukeboxcore.gui.treemodel.TreeModel`
Raises:	None

fetch_options()[source]¶

Set and return the options for possible files to load, replace etc. The stored element will determine the options.

The refobjinterface and typinterface are responsible for providing the options

Returns:	the options
Return type:	`jukeboxcore.gui.treemodel.TreeModel`
Raises:	None

get_option_taskfileinfos()[source]¶

Return a list of all TaskFileInfo that are available as options for referencing, importing, replacing etc.

Returns:	list of TaskFileInfos
Return type:	`TaskFileInfo`
Raises:	None

get_option_labels()[source]¶

Return labels for each level of the option model.

The options returned by Reftrack.fetch_options() is a treemodel with n levels. Each level should get a label to describe what is displays.

E.g. if you organize your options, so that the first level shows the tasks, the second level shows the descriptors and the third one shows the versions, then your labels should be: ["Task", "Descriptor", "Version"].

Returns:	label strings for all levels
Return type:	list
Raises:	None

get_option_columns()[source]¶

Return the column of the model to show for each level

Because each level might be displayed in a combobox. So you might want to provide the column to show.

Returns:	a list of columns
Return type:	list
Raises:	None

uptodate()[source]¶

Return True, if the currently loaded entity is the newest version. Return False, if there is a newer version. Return None, if there is no current scene object.

Returns:	whether the reftrack is uptodate
Return type:	bool \| None
Raises:	None

fetch_uptodate()[source]¶

Set and return whether the currently loaded entity is the newest version in the department.

Returns:	True, if newest version. False, if there is a newer version. None, if there is nothing loaded yet.
Return type:	bool \| None
Raises:	None

alien()[source]¶

Return True, if the reftrack element is not linked to the current scene

Returns:	whether the element is linked to the current scene
Return type:	bool
Raises:	None

fetch_alien()[source]¶

Set and return, if the reftrack element is linked to the current scene.

Askes the refobj interface for the current scene. If there is no current scene then True is returned.

Returns:	whether the element is linked to the current scene
Return type:	bool
Raises:	None

status()[source]¶

Return the status of the reftrack

The status indicates, whether the entity is loaded, unloaded etc. None if there is no refobj in the scene.

See: Reftrack.LOADED, Reftrack.UNLOADED, Reftrack.IMPORTED.

Returns:	the status
Return type:	str \| None
Raises:	None

set_status(status)[source]¶

Set the status of the reftrack

The status indicates, whether the entity is loaded, unloaded etc. None if there is no refobj in the scene.

See: Reftrack.LOADED, Reftrack.UNLOADED, Reftrack.IMPORTED.

Parameters:	status (str \| None) – the status
Returns:	None
Return type:	None
Raises:	None

create_refobject()[source]¶

Create a refobject in the scene that represents the Reftrack instance.

Note

This will not set the reftrack object.

Returns:	the created reftrack object
Return type:	scene object
Raises:	None

reference(*args, **kwds)[source]¶

Reference the entity into the scene. Only possible if the current status is None.

This will create a new refobject, then call RefobjInterface.reference() and afterwards set the refobj on the Reftrack instance.

Parameters:	taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo to reference
Returns:	None
Return type:	None
Raises:	`ReftrackIntegrityError`

load(*args, **kwds)[source]¶

If the reference is in the scene but unloaded, load it.

Note

Do not confuse this with reference or import. Load means that it is already referenced. But the data from the reference was not read until now. Load loads the data from the reference.

This will call RefobjInterface.load() and set the status to Reftrack.LOADED.

Returns:	None
Return type:	None
Raises:	`ReftrackIntegrityError`

unload(*args, **kwds)[source]¶

If the reference is loaded, unload it.

Note

Do not confuse this with a delete. This means, that the reference stays in the scene, but no data is read from the reference.

This will call RefobjInterface.unload() and set the status to Reftrack.UNLOADED. It will also throw away all children Reftrack. They will return after Reftrack.load().

The problem might be that children depend on their parent, but will not get unloaded. E.g. you imported a child. It will stay in the scene after the unload and become an orphan. In this case an error is raised. It is not possible to unload such an entity. The orphan might get its parents back after you call load, but it will introduce bugs when wrapping children of unloaded entities. So we simply disable the feature in that case and raise an IntegrityError

Returns:	None
Return type:	None
Raises:	`ReftrackIntegrityError`

import_file(*args, **kwds)[source]¶

Import the file for the given taskfileinfo

This will also update the status to Reftrack.IMPORTED. This will also call fetch_new_children(). Because after the import, we might have new children.

Parameters:	taskfileinfo (`jukeboxcore.filesys.TaskFileInfo` \| None) – the taskfileinfo to import. If None is given, try to import the current reference
Returns:	None
Return type:	None
Raises:	`ReftrackIntegrityError`

import_reference(*args, **kwds)[source]¶

Import the currently loaded reference

This will also update the status to Reftrack.IMPORTED.

Returns:	None
Return type:	None
Raises:	`ReftrackIntegrityError`

replace(*args, **kwds)[source]¶

Replace the current reference or imported entity.

If the given refobj is not replaceable, e.g. it might be imported or it is not possible to switch the data, then the entity will be deleted, then referenced or imported again, depending on the current status.

A replaced entity might have other children. This introduces a problem:

A child might get deleted, e.g. an asset which itself has another child, that will not get deleted, e.g. an imported shader. In this case the imported shader will be left as an orphan. This will check all children that will not be deleted (Reftrack.get_children_to_delete()) and checks if they are orphans after the replace. If they are, they will get deleted!

After the replace, all children will be reset. This will simply throw away all children reftracks (the content will not be deleted) and wrap all new children again. See: Reftrack.fetch_new_children().

Parameters:	taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo that will replace the old entity
Returns:	None
Return type:	None
Raises:	ReftrackIntegrityError

delete(*args, **kwds)[source]¶

Delete the current entity.

This will also call RefobjInterface.get_children_to_delete() and delete these children first by calling Reftrack.delete(). To delete the content it will call RefobjInterface.delete(). Then the refobject will be set to None. If the Reftrack object is an alien to the current scene, because it is not linked in the database, it will also remove itself from the root and from the treemodel. If it is not an alien, it will just empty all of tis children and update its status.

Parameters:	removealien (`bool`) – If True, remove this reftrack, if it is an alien
Returns:	None
Return type:	None
Raises:	None

duplicate()[source]¶

Return a new Reftrack instance that has the same typ, element and parent. The new reference will be not referenced or imported!

Returns:	a new reftrack instance with same typ, element and parent
Return type:	`Reftrack`
Raises:	None

get_all_children()[source]¶

Get all children including children of children

Returns:	all children including children of children
Return type:	list of `Reftrack`
Raises:	None

get_children_to_delete()[source]¶

Return all children that are not referenced

Returns:	list or `Reftrack`
Return type:	list
Raises:	None

get_suggestions()[source]¶

Return a list with possible children for this reftrack

Each Reftrack may want different children. E.g. a Asset wants to suggest a shader for itself and all assets that are linked in to it in the database. Suggestions only apply for enities with status other than None.

A suggestion is a tuple of typ and element. It will be used to create a newlen Reftrack. The parent will be this instance, root and interface will of course be the same.

This will call RefobjInterface.get_suggestions() which will delegate the call to the appropriate ReftypeInterface. So suggestions may vary for every typ and might depend on the status of the reftrack.

Returns:	list of suggestions, tuples of type and element.
Return type:	list
Raises:	None

fetch_new_children()[source]¶

Collect all new children and add the suggestions to the children as well

When an entity is loaded, referenced, imported etc there might be new children. Also it might want to suggest children itself, like a Shader for an asset.

First we wrap all unwrapped children. See: Reftrack.get_unwrapped(), Reftrack.wrap(). Then we get the suggestions. See: Reftrack.get_suggestions(). All suggestions that are not already a child of this Reftrack instance, will be used to create a new Reftrack with the type and element of the suggestion and the this instance as parent.

Returns:	None
Return type:	None
Raises:	None

throw_children_away()[source]¶

Get rid of the children Reftrack by deleting them from root, and unparenting them. The content of the children will stay in the scene.

You can wrap them again. It is a simple way to reset all children, e.g. after a replace. Because they might have changed completly.

Returns:	None
Return type:	None
Raises:	None

set_parent_on_new(*args, **kwds)[source]¶

Contextmanager that on close will get all new unwrapped refobjects, and for every refobject with no parent sets is to the given one.

Returns:	None
Return type:	None
Raises:	None

is_restricted(obj)[source]¶

Returns True if the given object is listed under Reftrack.restricted.

This is mainly used to restrict functions in certain situations.

Parameters:	obj – a hashable object
Returns:	True, if the given obj is restricted
Return type:	`bool`
Raises:	None

set_restricted(obj, restricted)[source]¶

Set the restriction on the given object.

You can use this to signal that a certain function is restricted. Then you can query the restriction later with Reftrack.is_restricted().

Parameters:	obj – a hashable object restricted (`bool`) – True, if you want to restrict the object.
Returns:	None
Return type:	None
Raises:	None

update_restrictions()[source]¶

Update all restrictions for the common Reftrack actions.

Update restrictions for:

Reftrack.reference()

Reftrack.load()

Reftrack.unload()

Reftrack.import_reference()

Reftrack.import_file()

Reftrack.replace()

Returns:	None
Return type:	None
Raises:	None

fetch_reference_restriction()[source]¶

Fetch whether referencing is restricted

Returns:	True, if referencing is restricted
Return type:	`bool`
Raises:	None

fetch_load_restriction()[source]¶

Fetch whether loading is restricted

Returns:	True, if loading is restricted
Return type:	`bool`
Raises:	None

fetch_unload_restriction()[source]¶

Fetch whether unloading is restricted

Returns:	True, if unloading is restricted
Return type:	`bool`
Raises:	None

fetch_import_ref_restriction()[source]¶

Fetch whether importing the reference is restricted

Returns:	True, if importing the reference is restricted
Return type:	`bool`
Raises:	None

fetch_import_f_restriction()[source]¶

Fetch whether importing a file is restricted

Returns:	True, if import is restricted
Return type:	`bool`
Raises:	None

fetch_replace_restriction()[source]¶

Fetch whether unloading is restricted

Returns:	True, if unloading is restricted
Return type:	`bool`
Raises:	None

fetch_delete_restriction()[source]¶

Fetch whether deletion is restricted

Returns:	True, if deletion is restricted
Return type:	`bool`
Raises:	None

emit_data_changed()[source]¶

Emit the data changed signal on the model of the treeitem if the treeitem has a model.

Returns:	None
Return type:	None
Raises:	None

get_additional_actions()[source]¶

Return a list of additional actions you want to provide for the menu of the reftrack.

E.e. you want to have a menu entry, that will select the entity in your programm.

This will call RefobjInterface.get_additional_actions().

The base implementation returns an empty list.

Returns:	A list of `ReftrackAction`
Return type:	list
Raises:	None

class jukeboxcore.reftrack.RefobjInterface[source]¶

Bases: object

Interface to interact with a refernece object that is in your scene.

This interface is abstract. You should implement it for every software where you need a reference workflow. To interact with the content of each entity, there is a special reftyp interface that is not only software specific but also handles only a certain type of entity. You can register additional type interfaces, so plugins can introduce their own entity types. See RefobjInterface.types. When subclassing you could replace it in your class with a dictionary of ReftypeInterface. Or you can call RefobjInterface.register_type() at runtime. A type could be “Asset”, “Alembic”, “Camera” etc.

Methods to implement:

RefobjInterface.exists()

RefobjInterface.get_parent()

RefobjInterface.set_parent()

RefobjInterface.get_children()

RefobjInterface.get_typ()

RefobjInterface.set_typ()

RefobjInterface.get_id()

RefobjInterface.set_id()

RefobjInterface.create_refobj()

RefobjInterface.referenced_by()

RefobjInterface.delete_refobj()

RefobjInterface.get_all_refobjs()

RefobjInterface.get_current_element()

RefobjInterface.set_reference()

RefobjInterface.get_reference()

RefobjInterface.get_status()

RefobjInterface.get_taskfile()

You might also want to reimplement fetch_action_restriction()

Initialize a new refobjinterface.

Raises:	None

types = {}¶: A dictionary that maps types of entities (strings) to the reftypinterface class

classmethod register_type(typ, interface)[source]¶

Register a new type with the given interface class

Parameters:	typ (str) – the entity typ that you want to register interface (`ReftypeInterface`) – the interface class
Returns:	None
Return type:	None
Raises:	None

get_typ_interface(typ)[source]¶

Return an appropriate interface for the given entity type

Parameters:	typ (str) – the entity type
Returns:	a interface instance
Return type:	`ReftypeInterface`
Raises:	KeyError

exists(refobj)[source]¶

Check if the given refobj is still in the scene or if it has been deleted/dissapeared

Parameters:	refobj (refobj) – a reference object to query
Returns:	True, if it still exists
Return type:	`bool`
Raises:	NotImplementedError

get_parent(refobj)[source]¶

Return the refobj of the parent of the given refobj

Parameters:	refobj (refobj) – a reference object to query
Returns:	the parent refobj
Return type:	refobj \| None
Raises:	None

set_parent(child, parent)[source]¶

Set the parent of the child refobj

E.g. in Maya you would connect the two refobj nodes so you can later query the connection when calling RefobjInterface.get_parent()

Parameters:	child (refobj) – the child refobject parent (refobj) – the parent refobject
Returns:	None
Return type:	None
Raises:	None

get_children(refobj)[source]¶

Get the children refobjects of the given refobject

It is the reverse query of RefobjInterface.get_parent()

Parameters:	refobj (refobj) – the parent refobj
Returns:	a list with children refobjects
Return type:	list
Raises:	NotImplementedError

get_typ(refobj)[source]¶

Return the entity type of the given refobject

See: RefobjInterface.types.

Parameters:	refobj (refobj) – the refobj to query
Returns:	the entity type
Return type:	str
Raises:	NotImplementedError

set_typ(refobj, typ)[source]¶

Set the type of the given refobj

Parameters:	refobj (refobj) – the refobj to edit typ (str) – the entity type
Returns:	None
Return type:	None
Raises:	NotImplementedError

get_id(refobj)[source]¶

Return the identifier of the given refobject

Parameters:	refobj (refobj) – the refobj to query
Returns:	the refobj id. Used to identify refobjects of the same parent, element and type in the UI
Return type:	int
Raises:	NotImplementedError

set_id(refobj, identifier)[source]¶

Set the identifier on the given refobj

Parameters:	refobj (refobj) – the refobj to edit identifier (int) – the refobj id. Used to identify refobjects of the same parent, element and type in the UI
Returns:	None
Return type:	None
Raises:	NotImplementedError

create_refobj()[source]¶

Create and return a new refobj

E.g. in Maya one would create a custom node that can store all the necessary information in the scene. The type and parent will be set automatically, because one would normally call RefobjInterface.create().

Returns:	the new refobj
Return type:	refobj
Raises:	NotImplementedError

referenced_by(refobj)[source]¶

Return the reference that holds the given refobj.

Returns None if it is imported/in the current scene.

Parameters:	refobj (refobj) – the refobj to query
Returns:	the reference that holds the given refobj
Return type:	reference \| None
Raises:	NotImplementedError

create(typ, identifier, parent=None)[source]¶

Create a new refobj with the given typ and parent

Parameters:	typ (str) – the entity type identifier (int) – the refobj id. Used to identify refobjects of the same parent, element and type in the UI parent (refobj) – the parent refobject
Returns:	The created refobj
Return type:	refobj
Raises:	None

delete_refobj(refobj)[source]¶

Delete the given refobj

Parameters:	refobj (refobj) – the refobj to delete
Returns:	None
Return type:	None
Raises:	None

delete(refobj)[source]¶

Delete the given refobj and the contents of the entity

Parameters:	refobj (refobj) – the refobj to delete
Returns:	None
Return type:	None
Raises:	None

get_all_refobjs()[source]¶

Return all refobjs in the scene

Returns:	all refobjs in the scene
Return type:	list
Raises:	None

get_current_element()[source]¶

Return the currently open Shot or Asset

Returns:	the currently open element
Return type:	`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot` \| None
Raises:	None

set_reference(refobj, reference)[source]¶

Set the reference of the given refobj to reference

This will be called by the typinterface after the reference has been made. The typinterface should deliver an appropriate object as reference that can be used to track the reference in the scene.

Parameters:	refobj (refobj) – the refobj to update reference – the value for the refobj
Returns:	None
Return type:	None
Raises:	None

get_reference(refobj)[source]¶

Return the reference that the refobj represents or None if it is imported.

E.g. in Maya this would return the linked reference node.

Parameters:	refobj (refobj) – the refobj to query
Returns:	the reference object in the scene \| None
Raises:	None

reference(taskfileinfo, refobj)[source]¶

Reference the given taskfile info and set the created reference on the refobj

This will call ReftypeInterface.reference(), then ReftypeInterface.set_reference().

Parameters:	taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – The taskfileinfo that holds the information for what to reference refobj (refobj) – the refobj that should represent the new reference
Returns:	None
Return type:	None
Raises:	None

load(refobj)[source]¶

Load the given refobject

Load in this case means, that a reference is already in the scene but it is not in a loaded state. Loading the reference means, that the actual data will be read.

This will call ReftypeInterface.load().

Parameters:	refobj (refobj) – the refobject
Returns:	None
Return type:	None
Raises:	None

unload(refobj)[source]¶

Load the given refobject

Unload in this case means, that a reference is stays in the scene but it is not in a loaded state. So there is a reference, but data is not read from it.

This will call ReftypeInterface.unload().

Parameters:	refobj (refobj) – the refobject
Returns:	None
Return type:	None
Raises:	None

replace(refobj, taskfileinfo)[source]¶

Replace the given refobjs reference with the taskfileinfo

This will call ReftypeInterface.replace().

Parameters:	refobj (refobj) – the refobject taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo that will replace the old entity
Returns:	None
Return type:	None
Raises:	None

is_replaceable(refobj)[source]¶

Return whether the given reference of the refobject is replaceable or if it should just get deleted and loaded again.

This will call ReftypeInterface.is_replaceable().

Parameters:	refobj (refobj) – the refobject to query
Returns:	True, if replaceable
Return type:	bool
Raises:	None

import_reference(refobj)[source]¶

Import the reference of the given refobj

Here we assume, that the reference is already in the scene and we break the encapsulation and pull the data from the reference into the current scene. This will call ReftypeInterface.import_reference() and set the reference on the refobj to None.

Parameters:	refobj (refobj) – the refobj with a reference
Returns:	None
Return type:	None
Raises:	None

import_taskfile(refobj, taskfileinfo)[source]¶

Import the given taskfileinfo and update the refobj

This will call ReftypeInterface.import_taskfile().

Parameters:	refobj (refobject) – the refobject taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo to reference
Returns:	None
Return type:	None
Raises:	None

get_status(refobj)[source]¶

Return the status of the given refobj

See: Reftrack.LOADED, Reftrack.UNLOADED, Reftrack.IMPORTED.

Parameters:	refobj (refobj) – the refobj to query
Returns:	the status of the given refobj
Return type:	str
Raises:	None

get_taskfile(refobj)[source]¶

Return the taskfile that is loaded and represented by the refobj

Parameters:	refobj (refobj) – the refobj to query
Returns:	The taskfile that is loaded in the scene
Return type:	`jukeboxcore.djadapter.TaskFile`
Raises:	None

get_taskfileinfo(refobj)[source]¶

Return the jukeboxcore.filesys.TaskFileInfo that is loaded by the refobj

Parameters:	refobj (refobj) – the refobject to query
Returns:	the taskfileinfo that is loaded in the scene
Return type:	`jukeboxcore.filesys.TaskFileInfo`
Raises:	None

get_element(refobj)[source]¶

Return the element the refobj represents.

The element is either an Asset or a Shot.

Parameters:	refobj (refobj) – the refobject to query
Returns:	The element the reftrack represents
Return type:	`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`
Raises:	None

fetch_options(typ, element)[source]¶

Fetch the options for possible files to load replace etc for the given element.

This will call ReftypeInterface.fetch_options().

Parameters:	typ (str) – the typ of options. E.g. Asset, Alembic, Camera etc element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	the option model and a list with all TaskFileInfos
Return type:	( `jukeboxcore.gui.treemodel.TreeModel`, list of `TaskFileInfo` )
Raises:	None

fetch_option_taskfileinfos(typ, element)[source]¶

Fetch the options for possible files to load, replace etc for the given element.

Thiss will call ReftypeInterface.fetch_option_taskfileinfos().

Parameters:	typ (str) – the typ of options. E.g. Asset, Alembic, Camera etc element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	The options
Return type:	list of `TaskFileInfo`

get_option_labels(typ, element)[source]¶

Return labels for each level of the option model.

The options returned by RefobjInterface.fetch_options() is a treemodel with n levels. Each level should get a label to describe what is displays.

E.g. if you organize your options, so that the first level shows the tasks, the second level shows the descriptors and the third one shows the versions, then your labels should be: ["Task", "Descriptor", "Version"].

Parameters:	typ (str) – the typ of options. E.g. Asset, Alembic, Camera etc element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	label strings for all levels
Return type:	list
Raises:	None

get_option_columns(typ, element)[source]¶

Return the column of the model to show for each level

Because each level might be displayed in a combobox. So you might want to provide the column to show.

Parameters:	typ (str) – the typ of options. E.g. Asset, Alembic, Camera etc element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for wich the options should be fetched.
Returns:	a list of columns
Return type:	list
Raises:	None

get_suggestions(reftrack)[source]¶

Return a list with possible children for this reftrack

Each Reftrack may want different children. E.g. a Asset wants to suggest a shader for itself and all assets that are linked in to it in the database. Suggestions only apply for enities with status other than None.

A suggestion is a tuple of typ and element. It will be used to create a newlen Reftrack. The parent will be this instance, root and interface will of course be the same.

This will delegate the call to the appropriate ReftypeInterface. So suggestions may vary for every typ and might depend on the status of the reftrack.

Parameters:	reftrack (`Reftrack`) – the reftrack which needs suggestions
Returns:	list of suggestions, tuples of type and element.
Return type:	list
Raises:	None

get_typ_icon(typ)[source]¶

Get the icon that should be used to identify the type in an UI

Parameters:	typ (str) – the typ. E.g. Asset, Alembic, Camera etc
Returns:	a icon for this type
Return type:	`QtGui.QIcon` \| None
Raises:	NotImplementedError

fetch_action_restriction(reftrack, action)[source]¶

Return wheter the given action is restricted for the given reftrack

available actions are:

reference, load, unload, replace, import_reference, import_taskfile, delete

If action is not available, True is returned.

Parameters:	reftrack (`Reftrack`) – the reftrack to query action (str) – the action to check.
Returns:	True, if the action is restricted
Return type:	`bool`
Raises:	None

get_additional_actions(reftrack)[source]¶

Return a list of additional actions you want to provide for the menu of the reftrack.

E.e. you want to have a menu entry, that will select the entity in your programm.

This will call ReftypeInterface.get_additional_actions().

The base implementation returns an empty list.

Parameters:	reftrack (`Reftrack`) – the reftrack to return the actions for
Returns:	A list of `ReftrackAction`
Return type:	list
Raises:	None

get_available_types_for_scene(element)[source]¶

Return a list of types that can be used in combination with the given element to add new reftracks to the scene.

This allows for example the user, to add new reftracks (aliens) to the scene. So e.g. for a shader, it wouldn’t make sense to make it available to be added to the scene, because one would use them only as children of let’s say an asset or cache. Some types might only be available for shots or assets etc.

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – the element that could be used in conjuction with the returned types to create new reftracks.
Returns:	a list of types
Return type:	`list`
Raises:	None

class jukeboxcore.reftrack.ReftrackAction(name, action, icon=None, checkable=False, checked=False, enabled=True)[source]¶

Bases: object

A little container for additional actions for reftracks. A action can call an arbitrary function, has a name and optional an Icon.

Initialize a new action with the given name, actionfunction and optional an icon

Parameters:

name (str) – the name of the action. Will be shown in GUIs
action (callable) – the function that should be called when the action is triggered.
icon (QtGui.QIcon) – Optional Icon for GUIs
checkable (bool) – If true, the action will be checkable in the UI
checked (bool) – If True, the action wil be checked by default
eneabled (bool) – Whether the action should be enabled

Raises:

None

class jukeboxcore.reftrack.ReftypeInterface(refobjinter)[source]¶

Bases: object

Interface for manipulating the content of an entity in the scene

This interface is abstract. You should implement it for every software and type where you need a reference workflow. The ReftypeInterface is responsible for the main reference workflow actions like loading, referencing and importing. Depending on the type of your entity, additional actions may be appropriate. E.g. if the type is a shader, then you might want to assign the shader to the parent of the shader refobject.

Methods to implement:

ReftypeInterface.reference()

ReftypeInterface.load()

ReftypeInterface.unload()

ReftypeInterface.replace()

ReftypeInterface.delete()

ReftypeInterface.import_reference()

ReftypeInterface.import_taskfile()

ReftypeInterface.is_replaceable()

ReftypeInterface.fetch_option_taskfileinfos()

ReftypeInterface.create_options_model()

ReftypeInterface.get_suggestions()

ReftypeInterface.get_option_labels()

ReftypeInterface.get_option_columns()

ReftypeInterface.is_available_for_scene()

You might also want to reimplement:

ReftypeInterface.get_typ_icon()

ReftypeInterface.get_scene_suggestions()

ReftypeInterface.is_reference_restricted()

ReftypeInterface.is_load_restricted()

ReftypeInterface.is_unload_restricted()

ReftypeInterface.is_import_ref_restricted()

ReftypeInterface.is_import_f_restricted()

ReftypeInterface.is_replace_restricted()

ReftypeInterface.get_additional_actions()

Initialize a new ReftypeInterface

Parameters:	refobjinter (`RefobjInterface`) – the refobject interface
Raises:	None

get_refobjinter()[source]¶

Return the RefobjInterface that initialized the interface

Returns:	the refobj interface that initialized the interface
Return type:	`RefobjInterface`
Raises:	None

reference(refobj, taskfileinfo)[source]¶

Reference the given taskfileinfo into the scene and return the created reference object

The created reference object will be used on RefobjInterface.set_reference() to set the reference on a refobj. E.g. in Maya, one would return the reference node so the RefobjInterface can link the refobj with the refernce object. Do not call RefobjInterface.set_reference() yourself.

Parameters:	refobj – the refobj that will be linked to the reference taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – The taskfileinfo that holds the information for what to reference
Returns:	the reference that was created and should set on the appropriate refobj
Raises:	NotImplementedError

load(refobj, reference)[source]¶

Load the given reference

Load in this case means, that a reference is already in the scene but it is not in a loaded state. Loading the reference means, that the actual data will be read.

Parameters:	refobj – the refobj that is linked to the reference reference – the reference object. E.g. in Maya a reference node
Returns:	None
Return type:	None
Raises:	NotImplementedError

unload(refobj, reference)[source]¶

Unload the given reference

Unload in this case means, that a reference is stays in the scene but it is not in a loaded state. So there is a reference, but data is not read from it.

Parameters:	refobj – the refobj that is linked to the reference reference – the reference object. E.g. in Maya a reference node
Returns:	None
Return type:	None
Raises:	NotImplementedError

replace(refobj, reference, taskfileinfo)[source]¶

Replace the given reference with the given taskfileinfo

Parameters:	refobj – the refobj that is linked to the reference reference – the reference object. E.g. in Maya a reference node taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo that will replace the old entity
Returns:	None
Return type:	None
Raises:	NotImplementedError

delete(refobj)[source]¶

Delete the content of the given refobj

Parameters:	refobj (refobj) – the refobj that represents the content that should be deleted
Returns:	None
Return type:	None
Raises:	NotImplementedError

import_reference(refobj, reference)[source]¶

Import the given reference

The reference of the refobj will be set to None automatically afterwards with RefobjInterface.set_reference()

Parameters:	refobj – the refobj that is linked to the reference reference – the reference object. E.g. in Maya a reference node
Returns:	None
Return type:	None
Raises:	NotImplementedError

import_taskfile(refobj, taskfileinfo)[source]¶

Import the given taskfileinfo and update the refobj

Parameters:	refobj (refobject) – the refobject taskfileinfo (`jukeboxcore.filesys.TaskFileInfo`) – the taskfileinfo to reference
Returns:	None
Return type:	None
Raises:	NotImplementedError

is_replaceable(refobj)[source]¶

Return whether the given reference of the refobject is replaceable or if it should just get deleted and loaded again.

Parameters:	refobj (refobj) – the refobject to query
Returns:	True, if replaceable
Return type:	bool
Raises:	NotImplementedError

fetch_options(element)[source]¶

Fetch the options for possible files to load replace etc for the given element.

Options from which to choose a file to load or replace. The options are a jukeboxcore.gui.treemodel.TreeModel with jukeboxcore.filesys.TaskFileInfo as leafes internal data. I explicitly say leafes because the options might be sorted in a tree like strucure. So the user could first select a task and then the apropriate release. You can take the model and display it to the user so he can select a file.

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	the option model and a list with all TaskFileInfos
Return type:	( `jukeboxcore.gui.treemodel.TreeModel`, list of `TaskFileInfo` )
Raises:	None

fetch_option_taskfileinfos(element)[source]¶

Fetch the options for possible files to load, replace etc for the given element.

Options from which to choose a file to load or replace.

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	The options
Return type:	list of `TaskFileInfo`
Raises:	NotImplementedError

create_options_model(taskfileinfos)[source]¶

Create a new treemodel that has the taskfileinfos as internal_data of the leaves.

I recommend using jukeboxcore.gui.filesysitemdata.TaskFileInfoItemData for the leaves. So a valid root item would be something like:

rootdata = jukeboxcore.gui.treemodel.ListItemData(["Asset/Shot", "Task", "Descriptor", "Version", "Releasetype"])
rootitem = jukeboxcore.gui.treemodel.TreeItem(rootdata)

Returns:	the option model with `TaskFileInfo` as internal_data of the leaves.
Return type:	`jukeboxcore.gui.treemodel.TreeModel`
Raises:	NotImplementedError

get_option_labels(element)[source]¶

Return labels for each level of the option model.

The options returned by RefobjInterface.fetch_options() is a treemodel with n levels. Each level should get a label to describe what is displays.

E.g. if you organize your options, so that the first level shows the tasks, the second level shows the descriptors and the third one shows the versions, then your labels should be: ["Task", "Descriptor", "Version"].

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for which the options should be fetched.
Returns:	label strings for all levels
Return type:	list
Raises:	NotImplementedError

get_option_columns(element)[source]¶

Return the column of the model to show for each level

Because each level might be displayed in a combobox. So you might want to provide the column to show.

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – The element for wich the options should be fetched.
Returns:	a list of columns
Return type:	list
Raises:	NotImplementedError

get_suggestions(reftrack)[source]¶

Return a list with possible children for this reftrack

Each Reftrack may want different children. E.g. a Asset wants to suggest a shader for itself and all assets that are linked in to it in the database. Suggestions only apply for enities with status other than None.

A suggestion is a tuple of typ and element. It will be used to create a newlen Reftrack. The parent will be this instance, root and interface will of course be the same.

Parameters:	reftrack (`Reftrack`) – the reftrack which needs suggestions
Returns:	list of suggestions, tuples of type and element.
Return type:	list
Raises:	NotImplementedError

is_available_for_scene(element)[source]¶

Return True, if it should be possible to add a new reftrack with the given element and the type of the interface to the scene.

Some types might only make sense for a shot or asset. Others should never be available, because you would only use them as children of other reftracks (e.g. a shader).

Parameters:	element (`jukeboxcore.djadapter.models.Asset` \| `jukeboxcore.djadapter.models.Shot`) – the element that could be used in conjuction with the returned types to create new reftracks.
Returns:	True, if available
Return type:	`bool`
Raises:	NotImplementedError

get_typ_icon()[source]¶

Return a icon that should be used to identify the type in an UI

Returns:	a icon for this type
Return type:	`QtGui.QIcon` \| None
Raises:	NotImplementedError

get_scene_suggestions(current)[source]¶

Return a list with elements for reftracks for the current scene with this type.

For every element returned, the reftrack system will create a Reftrack with the type of this interface, if it is not already in the scene.

E.g. if you have a type that references whole scenes, you might suggest all linked assets for shots, and all liked assets plus the current element itself for assets. If you have a type like shader, that usually need a parent, you would return an empty list. Cameras might only make sense for shots and not for assets etc.

Do not confuse this with ReftypeInterface.get_suggestions(). It will gather suggestions for children of a Reftrack.

The standard implementation only returns an empty list!

Parameters:	reftrack (`Reftrack`) – the reftrack which needs suggestions
Returns:	list of suggestions, tuples of type and element.
Return type:	list
Raises:	None

is_reference_restricted(reftrack)[source]¶

Return whether referencing for the given reftrack should be restricted