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.

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

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: list, workingSet: WorkingSet, sender: object)

Where:

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.

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: list, workingSet: WorkingSet, sender: object)

Where:

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.

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)

Where:

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.

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.

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.

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.

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.

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.

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 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.

getAllowedStates()¶

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

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.

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.

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.

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.

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.

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

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.

getRootLocations()¶

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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

removeAllowedStatesChangedCallback(callback)¶

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

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

removeLocationStateChangedCallback(callback)¶

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

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

removeWorkingSetClearedCallback(callback)¶

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

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

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.

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.

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.