Working Sets¶

class WorkingSet.WorkingSet¶

Bases: object

A class encapsulating a map of Scene Graph locations to states, to which elements can be added and removed, triggering callbacks if specified.

class State¶

Bases: object

An ‘enumeration’ of possible location states for use in a WorkingSet.

Empty = 1¶

Excluded = 8¶

ExcludedWithChildren = 16¶

Included = 2¶

IncludedWithChildren = 4¶

classmethod coerceToBitmask(bitmaskOrStates)¶

Return type:	`int`
Parameters:	bitmaskOrStates (`int` or `list` of `int` or `None`) – A numerical value representing some state values bitwise combined into a single value, or a list of state values, or `None` to indicate all possible states.
Returns:	A bitmask representing the states represented by the given bitmask or states.
Note:	A `bitmaskOrStates` value of None, 0 or an empty list will return a bitmask representing all possible states.

classmethod fromStateString(stateString)¶

Turns the given state string representation into the actual state value.

Return type:	`int` or `None`
Parameters:	stateString (`str`) – The string representation of the state.
Returns:	The state value, or `None` if the given state string doesn’t map to a known state.

classmethod getBitmaskFromStates(states)¶

Turns the given list of state values into a numerical value representing a combination of those states.

Return type:	`int`
Parameters:	states (`list` of `int`) – A list of the states values for which a bitmask should be returned.
Returns:	A numerical value representing the given state values bitwise combined into a single value.

classmethod getStateString(state)¶

Turns the given state into a string that represents it. e.g. WorkingSet.State.Included will return “Included”.

Return type:	`str`
Parameters:	state (`int`) – The state to convert to a string.
Returns:	The string representation of the given state.

classmethod getStatesFromBitmask(bitmask)¶

Turns the given numerical value representing a combination of states into a list of state values.

Return type:	`list` of `int`
Parameters:	bitmask (`int`) – A numerical value representing some state values bitwise combined into a single value.
Returns:	A list of the states which match the given bitmask.

classmethod getValidStates()¶

Return type:	`list` of `int`
Returns:	A list of all valid states.

classmethod getValidStatesBitmask()¶

Return type:	`int`
Returns:	A bitmask representing all valid states.

classmethod validate(state)¶

Validates the given state against the list of all valid states. If the given state is found to not be valid, a ValueError is raised.

Parameters:	state (`int`) – The state to validate.
Raises:	ValueError – When the given state is not valid.

WorkingSet.__init__()¶: Initializes an instance of the class.

WorkingSet.addAllowedStatesChangedCallback(callback)¶

Adds the given callback function to a list of functions that will be executed when the Working Set’s allowed states change.

The callback is expected to have the following signature:

function(allowedStates, workingSet, sender)

allowedStates is a list of int representing the new allowed states for the Working Set
workingSet is the WorkingSet that is causing the callback
sender is the object that caused the request to change the Working Set, or None if one wasn’t provided.

Parameters:	callback (`callable`) – The callback to be called when the allowed states for the Working Set are changed.
Raises:	ValueError – If the given callback doesn’t have the expected signature.

WorkingSet.addLocationStateChangedCallback(callback)¶

Adds the given callback function to a list of functions that will be executed when a location in the Working Set’s state changes.

The callback is expected to have the following signature:

function(locationStateChanges, workingSet, sender)

locationStateChanges is a list of tuples of the form (locationPath, oldState, newState).
- When the location path is first added to the Working Set, the oldState will be None
- When the location path is removed from the Working Set, the newState will be None
workingSet is the WorkingSet that is causing the callback
sender is the object that caused the request to change the Working Set, or None if one wasn’t provided.

Parameters:	callback (`callable`) – The callback to set to be called when locations are added, removed, or have their states changed in the Working Set.
Raises:	ValueError – If the given callback doesn’t have the expected signature.

WorkingSet.addWorkingSetClearedCallback(callback)¶

Adds the given callback function to a list of functions that will be executed when the Working Set is cleared via a call to clear().

The callback is expected to have the following signature:

function(workingSet)

workingSet is the WorkingSet that is causing the callback

Parameters:	callback (`callable`) – The callback to set to be called when the Working Set is cleared.
Raises:	ValueError – If the given callback doesn’t have the expected signature.

WorkingSet.asGroupAttribute()¶

Return type:	`FnAttribute.GroupAttribute`
Returns:	A group attribute containing child attributes representing the locations which have been added to the maps for this Working Set.

WorkingSet.clear(clearAllowedStates=False, sender=None, useCallbacks=True)¶

Removes all locations that are currently stored in the Working Set.

Return type:	`bool`
Parameters:	sender (`object` or `None`) – The object that initiated the change. clearAllowedStates (`bool`) – A flag indicating whether locations with a subset of allowed states should have this restriction cleared. useCallbacks (`bool`) – Whether or not to raise callbacks if any changes are made.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

WorkingSet.clearLocations(locationPathOrPaths, clearAllowedStates=False, clearGiven=True, clearChildren=False, sender=None, useCallbacks=True)¶

Removes the given location path or location paths from the Working Set. Optionally also removes all states for child location paths of the given location paths.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be removed. clearAllowedStates (`bool`) – Flag to control whether to clear the allowed states for the given location paths, and their children if `clearChildren` is `True`. clearGiven (`bool`) – Flag to control whether to remove the state for the given location paths. If `clearChildren`, `clearGiven` and `clearAllowedStates` are all `False`, this function will have no effect. clearChildren (`bool`) – Flag to control whether to clear all location paths beneath the given location paths. sender (`object` or `None`) – The object that initiated the change. useCallbacks (`bool`) – Whether or not to raise callbacks if any changes are made.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

WorkingSet.containsLocation(locationPath)¶

Return type:	`bool`
Parameters:	locationPath (`str`) – The path of the location whose membership of this Working Set will be tested.
Returns:	`True` if the given location path has an entry in the Working Set, otherwise `False`.

WorkingSet.excludeLocations(locationPathOrPaths, allowedStates=None, sender=None)¶

Convenience function that calls setLocationStates() with WorkingSet.State.Excluded as the given locations’ state.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be set to Excluded. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

WorkingSet.excludeLocationsWithChildren(locationPathOrPaths, allowedStates=None, sender=None)¶

Convenience function that calls setLocationStates() with WorkingSet.State.ExcludedWithChildren as the given locations’ state.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be set to ExcludedWithChildren. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

classmethod WorkingSet.fromGroupAttribute(groupAttribute, sender=None, useCallbacks=True, workingSetInstance=None)¶

Populates a Working Set from a GroupAttribute that was previously created via asGroupAttribute().

In addition to being able to be called as a class method, this is also available as an instance method, in the form myWorkingSet.fromGroupAttribute(myGroupAttribute). When called as a class method, a new WorkingSet will be constructed and populated from the GroupAttribute. When called as an instance method, the WorkingSet on which it was called will be cleared and updated using the GroupAttribute’s contents.

Return type:	`WorkingSet`
Parameters:	groupAttribute (`FnAttribute.GroupAttribute`) – The GroupAttribute whose children should be used to populate the Working Set. This GroupAttribute is expected to have been created through a call to `asGroupAttribute()`. sender (`object` or `None`) – The object that initiated the change. useCallbacks (`bool`) – Whether or not to raise callbacks if any changes are made. workingSetInstance (`WorkingSet` or `None`) – An optional `WorkingSet` to (clear and) update using the GroupAttribute. If this is `None`, a new `WorkingSet` will be created and updated.
Returns:	The Working Set that was updated with the GroupAttribute.
Raises:	TypeError – If the given groupAttribute argument is not a valid `FnAttribute.GroupAttribute`.

WorkingSet.getAllowedStates()¶

Return type:	`list` of `int`
Returns:	A list of numerical values representing the states which this Working Set can contain.
See:	`setAllowedStates`

WorkingSet.getLocationAllowedStates(locationPath)¶

Return type:	`list` of `int`
Parameters:	locationPath (`str`) – The path of the location for which the allowed states should be returned.
Returns:	A list of numerical values representing the states which the given location is allowed to have.

WorkingSet.getLocationState(locationPath)¶

Return type:	`int`
Parameters:	locationPath (`str`) – The location path to query the state for.
Returns:	The state associated with the given location path. This will be `WorkingSet.State.Empty` if the location path is not found.

WorkingSet.getLocations(rootPath=None)¶

Return type:	`list` of `str`
Parameters:	rootPath (`str` or `None`) – The path beneath which (excluding itself) locations should be returned. If `None`, all locations in the tree are returned.
Returns:	A list of all locations that are currently known by the Working Set, regardless of their assigned state.

WorkingSet.getLocationsAndStates(rootPath=None)¶

Return type:	`list` of `tuple` of `(str, int)`
Parameters:	rootPath (`str` or `None`) – The path beneath which (excluding itself) locations should be returned. If `None`, all locations in the tree are returned.
Returns:	A list of all locations and their states that are currently known by the Working Set.

WorkingSet.getLocationsByState(state, rootPath=None)¶

Return type:	`list` of `str`
Parameters:	state (`int`) – The state to get the locations for. rootPath (`str` or `None`) – The path beneath which (excluding itself) matching locations should be returned. If `None`, all matching locations in the tree are returned.
Returns:	A list of all locations that are currently set to the given state.

WorkingSet.getMinimumAllowedStateForLocation(locationPath)¶

Return type:	`int` or `None`
Parameters:	locationPath (`str`) – The path of the location whose minimum allowed state should be returned.
Returns:	The state with the smallest value which is allowed for the given location

WorkingSet.getNumLocations(rootPath=None)¶

Return type:	`int`
Parameters:	rootPath (`str` or `None`) – The path beneath which (excluding itself) the number of locations should be returned. If `None`, the total number of locations in the tree is returned.
Returns:	The number of locations known by this Working Set.

WorkingSet.getRootLocations()¶

Return type:	`list` of `str`
Returns:	A list of all “root” (top most) locations stored in the Working Set.

WorkingSet.includeLocations(locationPathOrPaths, allowedStates=None, sender=None)¶

Convenience function that calls setLocationStates() with WorkingSet.State.Included as the given locations’ state.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be set to Included. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

WorkingSet.includeLocationsWithChildren(locationPathOrPaths, allowedStates=None, sender=None)¶

Convenience function that calls setLocationStates() with WorkingSet.State.IncludedWithChildren as the given locations’ state.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be set to IncludedWithChildren. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.

WorkingSet.isIncludedLeafLocation(locationPath)¶

Determines whether the given location path is a leaf location with respect to the Working Set, i.e. if it is “Included”, does not include children by inheritance, and does not have any explicitly included children.

Return type:	`bool`
Parameters:	locationPath (`str`) – The location path to check.
Returns:	`True` if the given location path is an included leaf location, otherwise `False`.

WorkingSet.isStateAllowed(state)¶

Return type:	`bool`
Parameters:	state (`int`) – The state to test whether the Working Set can contain it.
Returns:	`True` if the Working Set can contain the given state, otherwise `False`.
See:	`setAllowedStates`

WorkingSet.isStateAllowedForLocation(locationPath, state)¶

Return type:	`bool`
Parameters:	locationPath (`str`) – The path of the location to test whether it can have the given state. state (`int`) – The state to test whether the given location is allowed to have.
Returns:	`True` if the given location path can have the given state, otherwise `False`.

WorkingSet.iterateLocationAncestors(locationPath, includeLocation=False)¶

An iterator over tuples of absolute location paths and their assigned states, in decreasing depth order, for ancestors of the given location path whose state is not “Empty”.

Return type:	`generator`
Parameters:	locationPath (`str`) – The location path to test. includeLocation (`bool`) – If `True`, iterate from `locationPath`, rather than its parent.
Returns:	A `generator` object that will walk over ancestor (location, state) tuples.

WorkingSet.matchesAnyChildren(locationPath, checkInheritance=False)¶

Determines whether any descendants of the given location path are included in the Working Set. By default, only checks whether descendants of the given location path are explicitly included.

Return type:	`bool`
Parameters:	locationPath (`str`) – The location path to search beneath for included locations. checkInheritance (`bool`) – Flag indicating whether to also consider inclusion by inheritance from the given location path and its ancestors.
Returns:	`True` if any locations beneath the given location path match the Working Set, otherwise `False`.

WorkingSet.matchesChildrenByInheritance(locationPath)¶

Determines whether children of the given location path would be included by inheritance (in the absence of local state).

Return type:	`bool`
Parameters:	locationPath (`str`) – The location path to check.
Returns:	`True` if children of the given location path would be included by inheritance.

WorkingSet.matchesLocation(locationPath)¶

Determines whether the given location path is logically included, i.e. is explicitly included, or is included by inheritance and is not explicitly excluded.

Return type:	`bool`
Parameters:	locationPath (`str`) – The location path to test.
Returns:	`True` if the location matches, otherwise `False`.

WorkingSet.removeAllCallbacks()¶: Removes all currently registered callbacks from the Working Set.

WorkingSet.removeAllowedStatesChangedCallback(callback)¶

Removes a callback for when the Working Set’s allowed states are changed.

Parameters:	callback (`callable`) – The callback function to remove.

WorkingSet.removeLocationStateChangedCallback(callback)¶

Removes a callback for when a location’s state is changed.

Parameters:	callback (`callable`) – The callback function to remove.

WorkingSet.removeWorkingSetClearedCallback(callback)¶

Removes a callback for when a location’s state is changed.

Parameters:	callback (`callable`) – The callback function to remove.

WorkingSet.setAllowedStates(allowedStates, sender=None)¶

Sets the allowed states of the Working Set. Note that a state of “Empty” is always implicitly allowed for a Working Set, as this represents a location not being present in the map.

Return type:	`bool`
Parameters:	allowedStates (`int` or `list` of `int` or `None`) – A list of states which the Working Set should be be able to contain, or a single numerical value created from the bit-wise OR of such states, or `None` if the Working Set should be able to contain any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if the allowed states of the Working Set changed, otherwise `False` if no changes were made to the Working Set.
Note:	Any locations currently in the map which have a state which is not in the given allowed states will be removed from the the Working Set.

WorkingSet.setLocationAllowedStates(locationPathOrPaths, allowedStates, sender=None)¶

Sets the allowed states of the given locations.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths whose allowed states should be set. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change.
Returns:	`True` if any of the locations had their allowed states changed, otherwise `False` no changes were made to the Working Set.

WorkingSet.setLocationStates(locationPathOrPaths, state, allowedStates=None, sender=None, useCallbacks=True)¶

Update the given location or list of locations to all have the given state value.

Return type:	`bool`
Parameters:	locationPathOrPaths (`str` or `list` of `str`) – Either a single location path string, or a list of location paths that should all be set to the given state. state (`int`) – The state to set all the given location paths to. allowedStates (`int` or `list` of `int` or `None`) – A list of states which the given locations should be allowed to have, or a single numerical value created from the bit-wise OR of such states, or `None` if the locations should be able to have any state. sender (`object` or `None`) – The object that initiated the change. useCallbacks (`bool`) – Whether or not to raise callbacks if any changes are made.
Returns:	`True` if any changes were made to the Working Set, otherwise `False`.
Raises:	ValueError – If the given state is not allowed for this Working Set.

Managing Working Sets¶

class WorkingSetManager.WorkingSetManager¶

Bases: object

Class implementing a global storage for WorkingSet instances. When a module wishes to access a Working Set they can call getOrCreateWorkingSet with the name of the WorkingSet instance they are interested in.

LiveRenderUpdatesWorkingSetName = 'liveRenderUpdates'¶

RenderWorkingSetName = 'render'¶

ViewerVisibilityWorkingSetName = 'viewerVisibility'¶

classmethod clearOnSceneChangeCallback()¶: Clears any previously set callback for onSceneLoad or onNewScene events. This restores the default Working Set manager behaviour.

classmethod clearWorkingSetOnSceneChange(workingSetName)¶

Adds the given named Working Set to the list of Working Sets to be cleared when an onNewScene or onSceneLoad callback occurs (when a new scene is opened, or when an existing scene is opened).

Parameters:	workingSetName (`str`) – The name of the Working Set to add to the list of those to be cleared.

static deleteWorkingSet(name)¶

Parameters:	name (`str`) – The name of the Working Set to delete.

static getOrCreateWorkingSet(name, sender=None)¶

Return type:	`WorkingSet`
Parameters:	name (`str`) – The name of the Working Set to get or create.
Returns:	The existing Working Set, or a newly created Working Set, if none existed with the specified name.

static getPersistentWorkingSetNames()¶

Return type:	`list` of `str`
Returns:	The names of Working Sets stored in the Working Set manager which cannot be deleted.

static getWorkingSetNames()¶

Return type:	`list` of `str`
Returns:	The names of Working Sets stored in the Working Set manager.

static isWorkingSetPersistent(name)¶

Return type:	`bool`
Parameters:	name (`str`) – The name of the Working Set to return whether it can be deleted.
Returns:	`True` if the Working Set with the given name can be deleted, otherwise `False`

classmethod setOnSceneChangeCallback(callback)¶

Sets a callback which will be triggered when onSceneLoad or onNewScene events take place. This allows users to customize the behaviour of the Working Set manager when scenes are changed. The callback is not expected to take any arguments.

Parameters:	callback (`callable`) – The callback to set.

static setOpArgs(op, opArgName, workingSetName, txn=None, opType=None, opArgs=None, updateOnWorkingSetChanges=True)¶

Sets the Op args for the given Op to contain information about the Working Set of the given name, and optionally registers a callback to update this Op arg when the contents of the Working Set changes.

This allows Working Sets to be used to modify Op args without any UI interaction - e.g. in script mode.

Parameters:

op (FnGeolibOp) – The Op which should have the contents of the Working Set of the given name passed into it as an Op arg.
opArgName (str) – The name of the Op arg into which the Working Set contents should be passed.
workingSetName (str) – The name of a Working Set registered in the Working Set manager.
txn (FnGeolib.GeolibRuntime.Transaction or None) – An optional transaction to use. If given, no commits will be made to the runtime. If None, a new transaction will be created and committed to the runtime.
opType (str or None) – The type of the Op. If None, the existing Op type for the given Op will be used.
opArgs (FnAttribute.GroupAttribute or None) – The args for the Op. If None, the existing args for the given Op will be used.
updateOnWorkingSetChanges (bool) – A flag indicating whether a callback should be registered to update the given Op’s args when the contents of the Working Set of the given name changes.

static setWorkingSetPersistent(name, persistent=True)¶

Parameters:	name (`str`) – The name of the Working Set to set whether it can be deleted. persistent (`bool`) – A flag indicating whether the Working Set with the given name name should be able to be deleted.