Core¶
This is the main NodeCalculator file!
Create a node-network by entering a math-formula.
author: | Mischa Kolbe <mischakolbe@gmail.com> |
---|---|
credits: | Mischa Kolbe, Steven Bills, Marco D’Ambros, Benoit Gielly, Adam Vanner, Niels Kleinheinz, Andres Weber |
version: | 2.1.2 |
Note
In any comment/docString of the NodeCalculator I use this convention:
- node: Name of a Maya node in the scene (dagPath if name isn’t unique)
- attr/attribute: Attribute on a Maya node in the scene
- plug: Combination of node and attribute; node.attr
NcNode and NcAttrs instances provide these keywords:
- attrs: Returns currently stored NcAttrs of this NcNode instance.
- attrs_list: Returns list of stored attrs: [attr, …] (list of strings).
- node: Returns name of Maya node in scene (str).
- plugs: Returns list of stored plugs: [node.attr, …] (list of strings).
NcList instances provide these keywords:
- nodes: Returns Maya nodes inside NcList: [node, …] (list of strings)
- Supported operations:
# Basic math +, -, *, /, ** # To see the available Operators, use: Op.available() # Or to see all Operators and their full docString: Op.available(full=True)
Example
import node_calculator.core as noca
a = noca.Node("pCube1")
b = noca.Node("pCube2")
c = noca.Node("pCube3")
with noca.Tracer(pprint_trace=True):
e = b.add_float("someAttr", value=c.tx)
a.s = noca.Op.condition(b.ty - 2 > c.tz, e, [1, 2, 3])
-
class
core.
NcAttrs
(holder_node, attrs)[source]¶ NcAttrs are linked to an NcNode instance & represent attrs on Maya node.
Note
Getting attr X from an NcAttrs that holds attr Y returns: NcAttrs.Y.X In contrast; NcNode instances do NOT “concatenate” attrs: Getting attr X from an NcNode that holds attr Y only returns: NcNode.X
-
__getattr__
(name)[source]¶ Get a new NcAttrs instance with the requested attribute.
Note
The requested attr gets “concatenated” onto the existing attr(s)!
There are certain keywords that will NOT return a new NcAttrs:
- attrs: Returns this NcAttrs instance (self).
- attrs_list: Returns stored attrs: [attr, …] (list of strings).
- node: Returns name of Maya node in scene (str).
- nodes: Returns name of Maya node in scene in a list ([str]).
- plugs: Returns stored plugs: [node.attr, …] (list of strings).
Parameters: name (str) – Name of requested attribute Returns: New NcAttrs instance OR self, if keyword “attrs” was used! Return type: NcAttrs Example
a = Node("pCube1") # Create new NcNode-object a.tx.ty # invokes __getattr__ on NcNode "a" first, which returns an NcAttrs instance with node: "a" & attrs: "tx". The __getattr__ described here then acts on the retrieved NcAttrs instance and returns a new NcAttrs instance. This time with node: "a" & attrs: "tx.ty"!
-
__getitem__
(index)[source]¶ Get stored attribute at given index.
Note
This looks through the list of stored attributes.
Parameters: index (int) – Index of desired item Returns: New NcNode instance, solely with attribute at index. Return type: NcNode
-
__init__
(holder_node, attrs)[source]¶ Initialize NcAttrs-class instance.
Note
__setattr__ is altered. The usual “self.node=node” results in loop! Therefore attributes need to be set a bit awkwardly via __dict__!
Parameters: -
_held_attrs_list
¶ Strings that represent attrs on Maya node.
Type: list
Raises: TypeError
– If the holder_node isn’t of type NcNode.-
-
_auto_consolidate
¶ Get _auto_consolidate attribute of _holder_node.
Returns: Whether auto consolidating is allowed Return type: bool
-
_auto_unravel
¶ Get _auto_unravel attribute of _holder_node.
Returns: Whether auto unravelling is allowed Return type: bool
-
_node_mobj
¶ Get the MObject this NcAttrs instance refers to.
Note
MObject is stored on the NcNode this NcAttrs instance refers to!
Returns: MObject instance of Maya node in the scene Return type: MObject
-
attrs
¶ Get this NcAttrs instance.
Returns: NcAttrs instance that represents Maya attributes. Return type: NcAttrs
-
attrs_list
¶ Get list of stored attributes of this NcAttrs instance.
Returns: List of strings that represent Maya attributes. Return type: list
-
node
¶ Get name of the Maya node this NcAttrs is linked to.
Returns: Name of Maya node in the scene. Return type: str
-
-
class
core.
NcBaseClass
[source]¶ Base class for NcLists & NcBaseNode (hence indirectly NcNode & NcAttrs).
Note
NcNode, NcAttrs and NcList are the “building blocks” of NodeCalculator calculations. Having NcBaseClass as their common parent class makes sure the overloaded operators apply to each of these “building blocks”.
-
__add__
(other)[source]¶ Regular addition operator for NodeCalculator objects.
Example
Node("pCube1.ty") + 4
-
__div__
(other)[source]¶ Regular division operator for NodeCalculator objects.
Example
Node("pCube1.ty") / 4
-
__eq__
(other)[source]¶ Equality operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") == 4
-
__ge__
(other)[source]¶ Greater equal operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") >= 4
-
__gt__
(other)[source]¶ Greater than operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") > 4
-
__le__
(other)[source]¶ Less equal operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") <= 4
-
__lt__
(other)[source]¶ Less than operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") < 4
-
__mul__
(other)[source]¶ Regular multiplication operator for NodeCalculator objects.
Example
Node("pCube1.ty") * 4
-
__ne__
(other)[source]¶ Inequality operator for NodeCalculator objects.
Returns: Instance of a newly created Maya condition-node Return type: NcNode Example
Node("pCube1.ty") != 4
-
__pos__
()[source]¶ Leading plus signs are ignored, since they are redundant.
Example
+ Node("pCube1.ty")
-
__pow__
(other)[source]¶ Regular power operator for NodeCalculator objects.
Example
Node("pCube1.ty") ** 4
-
__radd__
(other)[source]¶ Reflected addition operator for NodeCalculator objects.
Note
Fall-back method if regular addition is not defined/fails.
Example
4 + Node("pCube1.ty")
-
__rdiv__
(other)[source]¶ Reflected division operator for NodeCalculator objects.
Note
Fall-back method if regular division is not defined/fails.
Example
4 / Node("pCube1.ty")
-
__rmul__
(other)[source]¶ Reflected multiplication operator for NodeCalculator objects.
Note
Fall-back method if regular multiplication is not defined/fails.
Example
4 * Node("pCube1.ty")
-
__rpow__
(other)[source]¶ Reflected power operator for NodeCalculator objects.
Example
4 ** Node("pCube1.ty")
-
__rsub__
(other)[source]¶ Reflected subtraction operator for NodeCalculator objects.
Note
Fall-back method if regular subtraction is not defined/fails.
Example
4 - Node("pCube1.ty")
-
__sub__
(other)[source]¶ Regular subtraction operator for NodeCalculator objects.
Example
Node("pCube1.ty") - 4
-
__weakref__
¶ list of weak references to the object (if defined)
-
classmethod
_add_to_command_stack
(command)[source]¶ Add a command to the class-variable _executed_commands_stack.
Parameters: command (str or list) – String or list of strings of Maya command(s)
-
classmethod
_add_to_traced_nodes
(node)[source]¶ Add a node to the class-variable _traced_nodes.
Parameters: node (TracerMObject) – MObject with metadata. Check docString of TracerMObject for more detail!
-
classmethod
_add_to_traced_values
(value)[source]¶ Add a value to the class-variable _traced_values.
Parameters: value (NcValue) – Value with metadata. Check docString of NcValue.
-
_compare
(other, operator)[source]¶ Create a Maya condition node, set to the correct operation-type.
Parameters: - other (NcNode or int or float) – Compare self-attrs with other
- operator (string) – Operation type available in Maya condition-nodes
Returns: Instance of a newly created Maya condition-node
Return type:
-
classmethod
_flush_command_stack
()[source]¶ Reset class-variable _executed_commands_stack to an empty list.
-
classmethod
_get_next_value_name
()[source]¶ Return the next available value name.
Note
When Tracer is active, queried values get a value name assigned.
Returns: Next available value name. Return type: str
-
classmethod
_get_next_variable_name
()[source]¶ Return the next available variable name.
Note
When Tracer is active, created nodes get a variable name assigned.
Returns: Next available variable name. Return type: str
-
-
class
core.
NcBaseNode
[source]¶ Base class for NcNode and NcAttrs.
Note
This class will have access to the .node and .attrs attributes, once it is instantiated in the form of a NcNode or NcAttrs instance.
-
__init__
()[source]¶ Initialize of NcBaseNode class, which is used for NcNode & NcAttrs.
Note
For more detail about auto_unravel & auto_consolidate check docString of set_global_auto_consolidate & set_global_auto_unravel!
Parameters: - auto_unravel (bool) – Should attrs of this instance be unravelled.
- auto_consolidate (bool) – Should instance-attrs be consolidated.
-
__iter__
()[source]¶ Iterate over list of attributes.
Yields: NcNode – Next item in list of attributes. Raises: StopIteration
– If end of .attrs_list is reached.
-
__len__
()[source]¶ Return the length of the stored attributes list.
Returns: Length of stored NcAttrs list. 0 if no Attrs are defined. Return type: int
-
__repr__
()[source]¶ Print unambiguous format of NcBaseNode instance.
Note
For example invoked by running highlighted code in Maya.
Returns: String of concatenated class-type, node and attrs. Return type: str
-
__setattr__
(name, value)[source]¶ Set or connect attribute to the given value.
Note
Attribute setting works the same way for NcNode and NcAttrs instances. Their difference lies within the __getattr__ method.
setattr is invoked by equal-sign. Does NOT work without attr:
a = Node(“pCube1.ty”) # Initialize Node-object with attr given
a.ty = 7 # Works fine if attribute is specifically called
a = 7 # Does NOT work!
It looks like the same operation as above, but here Python calls the assignment operation, NOT setattr. The assignment operation can’t be overridden.
Parameters: Example
a = Node("pCube1") # Create new NcNode-object a.tx = 7 # Set pCube1.tx to the value 7 a.t = [1, 2, 3] # Set pCube1.tx|ty|tz to 1|2|3 respectively a.tx = Node("pCube2").ty # Connect pCube2.ty to pCube1.tx
-
__setitem__
(index, value)[source]¶ Set or connect attribute at index to the given value.
Note
Item setting works the same way for NcNode and NcAttrs instances. Their difference lies within the __getitem__ method.
This looks at the list of attrs stored inside NcAttrs.
Parameters:
-
__str__
()[source]¶ Print readable format of NcBaseNode instance.
Note
For example invoked by using print() in Maya.
Returns: String of concatenated node and attrs. Return type: str
-
_add_all_add_attr_methods
()[source]¶ Add all possible attribute types for add_XYZ() methods via closure.
Note
Allows to add attributes, similar to addAttr-command.
Example
Node("pCube1").add_float("my_float_attr", defaultValue=1.1) Node("pCube1").add_short("my_int_attr", keyable=False)
-
_add_traced_attr
(attr_name, **kwargs)[source]¶ Create a Maya-attribute on the Maya-node this NcBaseNode refers to.
Parameters: - attr_name (str) – Name of new attribute.
- kwargs (dict) – Any user specified flags & their values. Gets combined with values in DEFAULT_ATTR_FLAGS!
Returns: NcNode instance with the newly created attribute.
Return type:
-
_define_add_attr_method
(attr_type, default_data_type)[source]¶ Closure to add add_XYZ() methods.
Note
Check docString of _add_all_add_attr_methods.
Parameters: - attr_type (str) – Name of data type of this attr: bool, long, …
- default_data_type (str) – Either “attributeType” or “dataType”. See Maya docs for more info.
Returns: Function that will be added to class methods.
Return type: executable
-
add_enum
(name, enum_name='', cases=None, **kwargs)[source]¶ Create an enum-attribute with given name and kwargs.
Note
kwargs are exactly the same as in cmds.addAttr()!
Parameters: - name (str) – Name for the new attribute to be created.
- enum_name (list or str) – User-choices for the resulting enum-attr.
- cases (list or str) – Overrides enum_name, which is a horrific name.
- kwargs (dict) – User specified flags to be set for the new attr.
Returns: NcNode-instance with the node and new attribute.
Return type: Example
Node("pCube1").add_enum(cases=["A", "B", "C"], value=2)
-
add_int
(*args, **kwargs)[source]¶ Create an integer-attribute on the node associated with this NcNode.
Note
This function simply redirects to add_long, but most people will probably expect an “int” data type.
Parameters: - args (list) – Arguments that will be passed on to add_long()
- kwargs (dict) – Key/value pairs that will be passed on to add_long()
Returns: NcNode-instance with the node and new attribute.
Return type:
-
add_separator
(name=<sphinx.ext.autodoc.importer._MockObject object>, enum_name=<sphinx.ext.autodoc.importer._MockObject object>, cases=None, **kwargs)[source]¶ Create a separator-attribute.
Note
Default name and enum_name are defined by the globals DEFAULT_SEPARATOR_NAME and DEFAULT_SEPARATOR_VALUE! kwargs are exactly the same as in cmds.addAttr()!
Parameters: - name (str) – Name for the new separator to be created.
- enum_name (list or str) – User-choices for the resulting enum-attr.
- cases (list or str) – Overrides enum_name, which is a horrific name.
- kwargs (dict) – User specified flags to be set for the new attr.
Returns: NcNode-instance with the node and new attribute.
Return type: Example
Node("pCube1").add_separator()
-
attr
(attr=None)[source]¶ Get new NcNode instance with given attr (using keywords is allowed).
Note
It is pretty difficult to get an NcNode instance with any of the NodeCalculator keywords (node, attr, attrs, …), except for when they are initialized. This method helps for those special cases.
Parameters: attr (str) – Attribute on the Maya node this instance refers to. Returns: - Instance with the given attr in its Attrs, or None
- if no attr was specified.
Return type: NcNode or None
-
get
()[source]¶ Get the value of a NcNode/NcAttrs-attribute.
Note
Works similar to a cmds.getAttr().
Returns: Value of the queried attribute. Return type: int or float or list
-
get_shapes
(full=False)[source]¶ Get shape nodes of self.node.
Parameters: full (bool) – Return full or shortest dag path Returns: List of MObjects of shapes. Return type: list
-
nodes
¶ Property that returns node within list.
Note
This property mostly exists to maintain consistency with NcList. Even though nodes of a NcNode/NcAttrs instance will always be a list of length 1 it might come in handy to match the property of NcLists!
Returns: Name of Maya node this instance refers to, in a list. Return type: list
-
plugs
¶ Property to allow easy access to the Node-plugs.
Note
A “plug” stands for “node.attr”!
Returns: List of plugs. Empty list if no attributes are defined! Return type: list
-
set
(value)[source]¶ Set or connect the value of a NcNode/NcAttrs-attribute.
Note
Similar to a cmds.setAttr().
Parameters: value (NcNode or NcAttrs or str or int or float or list or tuple) – Connect attribute to this value (=plug) or set attribute to this value/array.
-
set_auto_consolidate
(state)[source]¶ Change the auto consolidating state.
Note
Check docString of set_global_auto_consolidate for more info!
Parameters: state (bool) – Desired auto consolidate state: On/Off
-
set_auto_unravel
(state)[source]¶ Change the auto unravelling state.
Note
Check docString of set_global_auto_unravel for more info!
Parameters: state (bool) – Desired auto unravel state: On/Off
-
to_py_node
(ignore_attrs=False)[source]¶ Get a PyNode from a NcNode/NcAttrs instance.
Parameters: ignore_attrs (bool) – Don’t use attrs when creating PyNode instance. When set to True only the node will be used for PyNode instantiation. Defaults to False. Returns: PyNode-instance of this node or plug Return type: pm.PyNode Raises: RuntimeError
– If the user requested a PyNode of an NcNode/NcAttrs with multiple attrs. PyNodes can only contain one attr max.
-
-
class
core.
NcList
(*args)[source]¶ NcList is a list with overloaded operators (inherited from NcBaseClass).
Note
NcList has the following keywords:
- nodes: Returns Maya nodes in NcList: [node, …] (list of strings)
NcList inherits from list, for things like isinstance(NcList, list).
-
__copy__
()[source]¶ Behavior for copy.copy().
Returns: Shallow copy of this NcList instance. Return type: NcList
-
__deepcopy__
(memo=None)[source]¶ Behavior for copy.deepcopy().
Parameters: memo (dict) – Memo-dictionary to be passed to deepcopy. Returns: Deep copy of this NcList instance. Return type: NcList
-
__delitem__
(index)[source]¶ Delete the item at the given index from this NcList instance.
Parameters: index (int) – Index of the item to be deleted.
-
__getattr__
(name)[source]¶ Get a list of NcAttrs instances, all with the requested attribute.
Note
There are certain keywords that will NOT return a new NcAttrs:
- attrs: Returns currently stored NcAttrs of this NcNode instance.
- attrs_list: Returns stored attrs: [attr, …] (list of strings).
- node: Returns name of Maya node in scene (str).
- nodes: Returns name of Maya node in scene in a list ([str]).
- plugs: Returns stored plugs: [node.attr, …] (list of strings).
Parameters: name (str) – Name of requested attribute Returns: New NcList with requested NcAttrs. Return type: NcList Example
# getattr is invoked by .attribute: a = Node(["pCube1.ty", "pSphere1.tx"]) # Initialize NcList. Op.average(a.attrs) # Average .ty on first with .tx on second. Op.average(a.tz) # Average .tz on both nodes.
-
__getitem__
(index)[source]¶ Get stored item at given index.
Note
This looks through the _items list of this NcList instance.
Parameters: index (int) – Index of desired item Returns: Stored item at index. Return type: NcNode or NcValue
-
__init__
(*args)[source]¶ Initialize new NcList-instance.
Parameters: args (NcNode or NcAttrs or NcValue or str or list or tuple) – Any number of values that should be stored as an array of values.
-
__iter__
()[source]¶ Iterate over items stored in this NcList instance.
Yields: NcNode or NcAttrs or NcValue – Next item in list of attributes. Raises: StopIteration
– If end of NcList._items is reached.
-
__len__
()[source]¶ Return the length of the NcList.
Returns: Number of items stored in this NcList instance. Return type: int
-
__repr__
()[source]¶ Unambiguous format of NcList instance.
Note
For example invoked by running highlighted NcList instance in Maya
Returns: String of concatenated class-type, node and attrs. Return type: str
-
__reversed__
()[source]¶ Reverse the list of stored items on this NcList instance.
Returns: New instance with reversed list of items. Return type: NcList
-
__setattr__
(name, value)[source]¶ Set or connect list items to the given value.
Note
Attribute setting works similar to NcNode and NcAttrs instances, in order to provide a (hopefully) seamless workflow, whether using NcNodes, NcAttrs or NcLists.
Parameters: Example
setattr is invoked by equal-sign. Does NOT work without attr: a = Node(["pCube1.ty", "pSphere1.tx"]) # Initialize NcList. a.attrs = 7 # Set list items to 7; .ty on first, .tx on second. a.tz = 7 # Set the tz-attr on all items in the NcList to 7. a = 7 # Does NOT work! It looks like same operation as above, but here Python calls the assignment operation, NOT setattr. The assignment-operation can't be overridden.
-
__setitem__
(index, value)[source]¶ Set or connect attribute at index to the given value.
Note
This looks at the _items list of this NcList instance
Parameters:
-
__str__
()[source]¶ Readable format of NcList instance.
Note
For example invoked by using print(NcList instance) in Maya
Returns: String of all NcList _items. Return type: str
-
__weakref__
¶ list of weak references to the object (if defined)
-
static
_convert_item_to_nc_instance
(item)[source]¶ Convert given item into a NodeCalculator friendly class instance.
Parameters: item (NcNode or NcAttrs or str or int or float) – Item to be converted into either an NcNode or an NcValue. Returns: Given item in the appropriate format. Return type: NcNode or NcValue Raises: RuntimeError
– If the given item cannot be converted into an NcNode or NcValue.
-
append
(value)[source]¶ Append value to list of items.
Note
Given value will be converted automatically to appropriate NodeCalculator type before being appended!
Parameters: value (NcNode or NcAttrs or str or int or float) – Value to append.
-
attr
(attr=None)[source]¶ Get new NcList instance with given attr (using keywords is allowed).
Note
Basically a new NcList with .attr() run on all its items.
Parameters: attr (str) – Attribute on the Maya nodes. Returns: - Instance containing NcAttrs or an empty NcList when no attr
- was specified.
Return type: NcList
-
extend
(other)[source]¶ Extend NcList with another list.
Parameters: other (NcList or list) – List to be added to the end of this NcList.
-
get
()[source]¶ Get current value of all items within this NcList instance.
Note
NcNode & NcAttrs instances in list are queried. NcValues are added to return list unaltered.
Returns: - List of queried values. Can be list of (int, float, list),
- depending on “queried” attributes!
Return type: list
-
insert
(index, value)[source]¶ Insert value to list of items at the given index.
Note
Given value will be converted automatically to appropriate NodeCalculator type before being inserted!
Parameters:
-
node
¶ Property to warn user about inappropriate access.
Note
Only NcNode & NcAttrs allow to access their node via node-property. Since user might not be aware of creating NcList instance: Give a hint that NcList instances have a nodes-property instead.
-
nodes
¶ Sparse list of all nodes within NcList instance.
Note
Only names of Maya nodes are in return_list. Furthermore: It is a sparse list without any duplicate names.
This can be useful for example for cmds.hide(my_collection.nodes)
Returns: List of names of Maya nodes stored in this NcList instance. Return type: list
-
class
core.
NcNode
(node, attrs=None, auto_unravel=None, auto_consolidate=None)[source]¶ NcNodes are linked to Maya nodes & can hold attrs in a NcAttrs-instance.
Note
Getting attr X from an NcNode that holds attr Y only returns: NcNode.X In contrast; NcAttrs instances “concatenate” attrs: Getting attr X from an NcAttrs that holds attr Y returns: NcAttrs.Y.X
-
__getattr__
(name)[source]¶ Get a new NcAttrs instance with the requested attribute.
Note
There are certain keywords that will NOT return a new NcAttrs:
- attrs: Returns currently stored NcAttrs of this NcNode instance.
- attrs_list: Returns stored attrs: [attr, …] (list of strings).
- node: Returns name of Maya node in scene (str).
- nodes: Returns name of Maya node in scene in a list ([str]).
- plugs: Returns stored plugs: [node.attr, …] (list of strings).
Parameters: name (str) – Name of requested attribute Returns: New OR stored instance, if keyword “attrs” was used! Return type: NcAttrs Example
a = Node("pCube1") # Create new Node-object a.tx # invokes __getattr__ and returns a new Node-object. It's the same as typing Node("a.tx")
-
__getitem__
(index)[source]¶ Get stored attribute at given index.
Note
Looks through list of attrs stored in the NcAttrs of this NcNode.
Parameters: index (int) – Index of desired item Returns: New NcNode instance, only with attr at index. Return type: NcNode
-
__init__
(node, attrs=None, auto_unravel=None, auto_consolidate=None)[source]¶ Initialize NcNode-class instance.
Note
__setattr__ is altered. The usual “self.node=node” results in loop! Therefore attributes need to be set a bit awkwardly via __dict__!
NcNode uses an MObject as its reference to the Maya node it belongs to. Maya node MUST therefore exist at instantiation time!
Parameters: - node (str or NcNode or NcAttrs or MObject) – Represents a Maya node
- attrs (str or list or NcAttrs) – Represents Maya attrs on the node
- auto_unravel (bool) – Should attrs be auto-unravelled? Check set_global_auto_unravel docString for more details.
- auto_consolidate (bool) – Should attrs be auto-consolidated? Check set_global_auto_consolidate docString for more details.
-
_node_mobj
¶ Reference to Maya node.
Type: MObject
Raises: RuntimeError
– If number was given to initialize an NcNode with.RuntimeError
– If list/tuple was given to initialize an NcNode with.RuntimeError
– If the given string doesn’t represent a unique, existing Maya node in the scene.
Example
a = Node("pCube1") # Node invokes NcNode instantiation! b = Node("pCube2.ty") b = Node("pCube3", ["ty", "tz", "tx"])
-
attrs
¶ Get currently stored NcAttrs instance of this NcNode.
Returns: NcAttrs instance that represents Maya attributes. Return type: NcAttrs
-
attrs_list
¶ Get list of stored attributes of this NcNode instance.
Returns: List of strings that represent Maya attributes. Return type: list
-
node
¶ Get the name of Maya node this NcNode refers to.
Returns: Name of Maya node in the scene. Return type: str
-
-
class
core.
Node
(*args, **kwargs)[source]¶ Return instance of appropriate type, based on given args
Note
Node is an abstract class that returns components of appropriate type that can then be involved in a NodeCalculator calculation.
Parameters: - item (bool or int or float or str or list or tuple) – Maya node, value, list of nodes, etc.
- attrs (str or list or tuple) – String or list of strings that are an attribute on this node. Defaults to None.
- auto_unravel (bool) – Should attrs automatically be unravelled into child attrs when operations are performed on this Node? Defaults to None, which means GLOBAL_AUTO_UNRAVEL is used. NodeCalculator works best if this is left unchanged!
- auto_consolidate (bool) – Should attrs automatically be consolidated into parent attrs when operations are performed on this Node, to reduce the amount of connections? Defaults to None, which means GLOBAL_AUTO_UNRAVEL is used. Sometimes parent plugs don’t update/evaluate reliably. If that’s the case; use this flag or noca.set_global_auto_consolidate(False).
Returns: Instance with given args.
Return type: Example
# NcNode instance with pCube1 as node and tx as attr Node("pCube.tx") # NcNode instance with pCube1 as node and tx as attr Node("pCube", "tx") # NcNode instance with pCube1 as node and tx as attr Node("pCube", ["tx"]) # NcList instance with value 1 and NcNode with pCube1 Node([1, "pCube"]) # NcIntValue instance with value 1 Node(1)
-
__init__
(*args, **kwargs)[source]¶ Pass this init.
The Node-class only serves to redirect to the appropriate type based on the given args! Therefore the init must not do anything.
Parameters: - args (list) – This dummy-init accepts any arguments.
- kwargs (dict) – This dummy-init accepts any keyword arguments.
-
__weakref__
¶ list of weak references to the object (if defined)
-
class
core.
OperatorMetaClass
(name, bases, body)[source]¶ MetaClass for NodeCalculator operators that go beyond basic math.
Note
A meta-class was used to ensure the “Op”-class to be a singleton class. Some methods are created on the fly in the __init__ method.
-
__init__
(name, bases, body)[source]¶ OperatorMetaClass-class constructor
Note
name, bases, body are necessary for __metaclass__ to work properly
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
core.
Tracer
(trace=True, print_trace=False, pprint_trace=False, cheers_love=False)[source]¶ Class that returns all Maya commands executed by NodeCalculator formula.
Note
Any NodeCalculator formula enclosed in a with-statement will be logged.
Example
with Tracer(pprint_trace=True) as s: a.tx = b.ty - 2 * c.tz print(s)
-
__enter__
()[source]¶ Set up NcBaseClass class-variables for tracing.
Note
The returned variable is what X in “with noca.Tracer() as X” will be.
Returns: List of all executed commands. Return type: list
-
__exit__
(exc_type, value, traceback)[source]¶ Print executed commands at the end of the with-statement.
-
__init__
(trace=True, print_trace=False, pprint_trace=False, cheers_love=False)[source]¶ Tracer-class constructor.
Parameters: - trace (bool) – Enables/disables tracing.
- print_trace (bool) – Print command stack as a list.
- pprint_trace (bool) – Print command stack as a multi-line string.
- cheers_love (bool) – ;)
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
core.
__load_extension
(noca_extension)[source]¶ Load the given extension in the correct way for the NodeCalculator.
Note
Check the tutorials and example extension files to see how you can create your own extensions.
Parameters: noca_extension (module) – Extension Python module to be loaded.
-
core.
_add_to_node_bin
(node)[source]¶ Add a node to NODE_BIN to keep track of created nodes for easy cleanup.
Note
Nodes are stored in NODE_BIN by name, NOT MPlug! Therefore, if a node was renamed it will not be deleted by cleanup().
Parameters: node (str) – Name of Maya node to be added to the NODE_BIN.
-
core.
_check_for_parent_attribute
(plug_list)[source]¶ Reduce the given list of plugs to a single parent attribute.
Parameters: plug_list (list) – List of plugs: [“node.attribute”, …] Returns: - If parent attribute was found it
- is returned as an MPlug instance, otherwise None is returned
Return type: MPlug or None
-
core.
_consolidate_plugs_to_min_dimension
(*plugs)[source]¶ Try to consolidate the given input plugs.
Note
A full set of child attributes can be reduced to their parent attr: [“tx”, “ty”, “tz”] becomes [“t”]
A 3D to 3D connection can be 1 connection if both plugs have a parent attr! However, a 1D attr can not connect to a 3D attr and must NOT be consolidated!
Parameters: plugs (list(NcNode or NcAttrs or str or int or float or list or tuple)) – Plugs to check. Returns: - Consolidated plugs, if consolidation was successful.
- Otherwise given inputs are returned unaltered.
Return type: list
-
core.
_create_node_name
(operation, *args)[source]¶ Create a procedural Maya node name that is as descriptive as possible.
Parameters: Returns: Generated name for the given node operation and args.
Return type: str
-
core.
_create_operation_node
(operation, *args)[source]¶ Create & connect adequately named Maya nodes for the given operation.
Parameters: Returns: - Either new NcNode instance with the newly created
Maya-node of type OPERATORS[operation][“node”] and with attributes stored in OPERATORS[operation][“outputs”]. If the outputs are multidimensional (for example “translateXYZ” & “rotateXYZ”) a new NcList instance is returned with NcNodes for each of the outputs.
Return type:
-
core.
_create_traced_operation_node
(operation, attrs)[source]¶ Create named Maya node for the given operation & add cmds to _command_stack if Tracer is active.
Parameters: Returns: Name of newly created Maya node.
Return type: str
-
core.
_format_docstring
(*args, **kwargs)[source]¶ Format docString of a function: Substitute placeholders with (kw)args.
Note
Formatting your docString directly won’t work! It won’t be a string literal anymore and Python won’t consider it a docString! Replacing the docString (.__doc__) via this closure circumvents this issue.
Parameters: - args (list) – Arguments for the string formatting: .format()
- kwargs (list) – Keyword arguments for the string formatting: .format()
Returns: The function with formatted docString.
Return type: executable
-
core.
_get_node_inputs
(operation, new_node, args_list)[source]¶ Get node-inputs based on operation-type and involved arguments.
Note
To anyone delving deep enough into the NodeCalculator to reach this point; I apologize. This function in particular is difficult to grasp. The main idea is to find which node-inputs (defined in the OPERATORS- dictionary) are needed for the given args. Dealing with array-inputs and often 3D-inputs is the difficult part. I hope the following explanation will make it easier to understand what is happening.
Within this function we deal a lot with different levels of arguments:
- args_list (list)
- > arg_element (list)
- > arg_item (list or MPlug/value/…)
- > arg_axis (MPlug/value/…)
The arg_item-level might seem redundant. The reason for its existence are array-input attributes (input[0], etc.). They need to be a list of items under one arg_element. That way one can loop over all array-input arg_items in an arg_element and get the correct indices, even if there is a mix of non-array input attrs and array-input attrs. Without this extra layer an input before the array-input would throw off the indices by 1!
The ARGS_LIST is made up of the various arguments that will connect into the node.
> [array-values, translation-values, rotation-values, …]The ARG_ELEMENT is what will set/connect into an attribute “section” of a node. For array-inputs THIS is what matters(!), because one attribute section (input[{array}]) will actually be made up of many inputs.
> [array-values]The ARG_ITEM is one particular arg_element. For arg_elements that are array-input the arg_item is a specific input of a array-input. For non-array-inputs the arg_elements & the arg_item are equivalent!
> [array-input-value[0]]The ARG_AXIS is the most granular item, referring to a particular Maya node attribute.
> [array-value[0].valueX]Parameters: Raises: RuntimeError
– If trying to connect a multi-dimensional attr into a 1D attr. This is an ambiguous connection that can’t be resolved.Returns: - (clean_inputs_list, clean_args_list, max_arg_element_len, max_arg_axis_len)
> clean_inputs_list holds all necessary node inputs for given args. > clean_args_list holds args that were adjusted to match clean_inputs_list. > max_arg_element_len holds the highest dimension of array attrs. > max_arg_axis_len holds highest number of attribute axis involved.
Return type: tuple
Example
These are examples of how the different "levels" of the args_list look like, described in the Note-section. Notice how the args_list is made up of arg_elements, which are made up of arg_items, which in turn are composed of arg_axis. args_list = [ [ [<OpenMaya.MPlug X>, <OpenMaya.MPlug Y>, <OpenMaya.MPlug Z>], <OpenMaya.MPlug A>, 2 ] ] # Note: This example would be for an array-input attribute of a node! arg_elements = [ [<OpenMaya.MPlug X>, <OpenMaya.MPlug Y>, <OpenMaya.MPlug Z>], <OpenMaya.MPlug A>, 2 ] arg_item = [<OpenMaya.MPlug X>, <OpenMaya.MPlug Y>, <OpenMaya.MPlug Z>] arg_axis = <OpenMaya.MPlug X>
-
core.
_get_node_outputs
(operation, new_node, max_array_len, max_axis_len)[source]¶ Get node-outputs based on operation-type and involved arguments.
Note
See docString of _get_node_inputs for origin of max_array_len and max_axis_len, as well as what output_element or output_axis means.
Parameters: - operation (str) – Operation the new node has to perform.
- new_node (str) – Name of newly created Maya node.
- max_array_len (int or None) – Highest dimension of arrays.
- max_axis_len (int) – Highest dimension of attribute axis.
Returns: - List of NcNode instances that hold an attribute according to the
outputs defined in the OPERATORS dictionary.
Return type: list
-
core.
_is_consolidation_allowed
(inputs)[source]¶ Check for any NcBaseNode-instance that is NOT set to auto consolidate.
Parameters: inputs (NcNode or NcAttrs or str or int or float or list or tuple) – Items to check for a turned off auto-consolidation. Returns: True, if all given items allow for consolidation. Return type: bool
-
core.
_is_valid_maya_attr
(plug)[source]¶ Check if given plug is of an existing Maya attribute.
Parameters: plug (str) – String of a Maya plug in the scene (node.attr). Returns: Whether the given plug is an existing plug in the scene. Return type: bool
-
core.
_join_cmds_kwargs
(**kwargs)[source]¶ Concatenates Maya command kwargs for Tracer.
Parameters: kwargs (dict) – Key/value-pairs that should be converted to a string. Returns: String of kwargs&values for the command in the Tracer-stack. Return type: str
-
core.
_set_or_connect_a_to_b
(obj_a_list, obj_b_list, **kwargs)[source]¶ Set or connect the first list of inputs to the second list of inputs.
Parameters: - obj_a_list (list) – List of MPlugs to be set or connected into.
- obj_b_list (list) – List of MPlugs, int, float, etc. which obj_a_list items will be set or connected to.
- kwargs (dict) – Arguments used in _traced_set_attr (~ cmds.setAttr)
Returns: Returns False, if setting/connecting was not possible.
Return type: bool
Raises: RuntimeError
– If an item of the obj_a_list isn’t a Maya attribute.RuntimeError
– If an item of the obj_b_list can’t be set/connected due to unsupported type.
-
core.
_split_plug_into_node_and_attr
(plug)[source]¶ Split given plug into its node and attribute part.
Parameters: plug (MPlug or str) – Plug of a Maya node/attribute combination. Returns: - Strings of separated node and attribute part or None if
- separation was not possible.
Return type: tuple or None Raises: RuntimeError
– If the given plug could not be split into node & attr.
-
core.
_traced_add_attr
(node, **kwargs)[source]¶ Add attr to Maya node & add cmds to _command_stack if Tracer is active.
Note
This is simply an overloaded cmds.addAttr(node, **kwargs).
Parameters: - node (str) – Maya node the attribute should be added to.
- kwargs (dict) – cmds.addAttr-flags
-
core.
_traced_connect_attr
(plug_a, plug_b)[source]¶ Connect 2 plugs & add command to _command_stack if Tracer is active.
Note
This is cmds.connectAttr(plug_a, plug_b, force=True) with Tracer-stuff.
Parameters: - plug_a (MPlug or str) – Source plug
- plug_b (MPlug or str) – Destination plug
-
core.
_traced_create_node
(node_type, **kwargs)[source]¶ Create a Maya node and add it to the _traced_nodes if Tracer is active.
Note
This is simply an overloaded cmds.createNode(node_type, **kwargs). It includes the cmds.parent-command if parenting flags are given.
If Tracer is active: Created nodes are associated with a variable. If they are referred to later on in the NodeCalculator statement, the variable name will be used instead of their node-name.
Parameters: - node_type (str) – Type of the Maya node that should be created.
- kwargs (dict) – cmds.createNode & cmds.parent flags
Returns: Name of newly created Maya node.
Return type: str
-
core.
_traced_get_attr
(plug)[source]¶ Get attr of Maya node & add cmds to _command_stack if Tracer is active.
Note
This is a tweaked & overloaded cmds.getAttr(plug): Awkward return values of 3D-attrs are converted from tuple(list()) to a simple list().
Parameters: plug (MPlug or str) – Plug of Maya node, whose value should be queried. Returns: Queried value of Maya node plug. Return type: list or numbers or bool or str
-
core.
_traced_set_attr
(plug, value=None, **kwargs)[source]¶ Set attr on Maya node & add cmds to _command_stack if Tracer is active.
Note
This is simply an overloaded cmds.setAttr(plug, value, **kwargs).
Parameters: - plug (MPlug or str) – Plug of a Maya node that should be set.
- value (list or numbers or bool) – Value the given plug should be set to.
- kwargs (dict) – cmds.setAttr-flags
-
core.
_unravel_and_set_or_connect_a_to_b
(obj_a, obj_b, **kwargs)[source]¶ Set obj_a to value of obj_b OR connect obj_b into obj_a.
Note
Allowed assignments are: (1-D stands for 1-dimensional, X-D for multi-dim; 2-D, 3-D, …)
- > Setting 1-D attribute to a 1-D value/attr
- # pCube1.tx = 7
- > Setting X-D attribute to a 1-D value/attr
- # pCube1.t = 7 # equal to [7]*3
- > Setting X-D attribute to a X-D value/attr
- # pCube1.t = [1, 2, 3]
- > Setting 1-D attribute to a X-D value/attr
- # Error: Ambiguous connection!
- > Setting X-D attribute to a Y-D value/attr
- # Error: Dimension mismatch that can’t be resolved!
Parameters: - obj_a (NcNode or NcAttrs or str) – Needs to be a plug. Either as a NodeCalculator-object or as a string (“node.attr”)
- obj_b (NcNode or NcAttrs or int or float or list or tuple or string) – Can be a numeric value, a list of values or another plug either in the form of a NodeCalculator-object or as a string (“node.attr”)
- kwargs (dict) – Arguments used in _traced_set_attr (~ cmds.setAttr)
Raises: RuntimeError
– If trying to connect a multi-dimensional attr into a 1D attr. This is an ambiguous connection that can’t be resolved.RuntimeError
– If trying to connect a multi-dimensional attr into a multi-dimensional attr with different dimensionality. This is a dimension mismatch that can’t be resolved!
-
core.
_unravel_base_node_instance
(base_node_instance)[source]¶ Unravel NcBaseNode instance.
Get name of Maya node or MPlug of Maya attribute the NcBaseNode refers to.
Parameters: base_node_instance (NcNode or NcAttrs) – Instance to find Mplug for. Returns: - MPlug of the Maya attribute the given NcNode/NcAttrs
- refers to or name of node, if no attrs are defined.
Return type: MPlug or str
-
core.
_unravel_item
(item)[source]¶ Turn input into MPlugs or values that can be set/connected by Maya.
Note
The items of a list are all unravelled as well! Parent plug becomes list of child plugs: “t” -> [“tx”, “ty”, “tz”]
Parameters: (MPlug, NcList or NcNode or NcAttrs or NcValue or list or tuple or (item) – str or numbers): input to be unravelled/cleaned. Returns: MPlug or value Return type: MPlug or NcValue or int or float or list Raises: TypeError
– If given item is of an unsupported type.
-
core.
_unravel_item_as_list
(item)[source]¶ Convert input into clean list of values or MPlugs.
Parameters: item (NcNode or NcAttrs or NcList or int or float or list or str) – input to be unravelled and returned as list. Returns: List consistent of values or MPlugs Return type: list
-
core.
_unravel_list
(list_instance)[source]¶ Unravel list instance; get value or MPlug of its items.
Parameters: list_instance (list or tuple) – list to be unravelled. Returns: List of unravelled items. Return type: list
-
core.
_unravel_nc_list
(nc_list)[source]¶ Unravel NcList instance; get value or MPlug of its NcList-items.
Parameters: nc_list (NcList) – NcList to be unravelled. Returns: List of unravelled NcList-items. Return type: list
-
core.
_unravel_plug
(node, attr)[source]¶ Convert Maya node/attribute combination into an MPlug.
Note
Tries to break up a parent attribute into its child attributes: .t -> [tx, ty, tz]
Parameters: - node (str) – Name of the Maya node
- attr (str) – Name of the attribute on the Maya node
Returns: - MPlug of the Maya attribute, list of MPlugs
if a parent attribute was unravelled to its child attributes.
Return type: MPlug or list
-
core.
_unravel_str
(str_instance)[source]¶ Convert name of a Maya plug into an MPlug.
Parameters: str_instance (str) – Name of the plug; “node.attr” Returns: - MPlug of the Maya attribute, None if given
- string doesn’t refer to a valid Maya plug in the scene.
Return type: MPlug or None
-
core.
cleanup
(keep_selected=False)[source]¶ Remove all nodes created by the NodeCalculator, based on node names.
Note
Nodes are stored in NODE_BIN by name, NOT MPlug! Therefore, if a node was renamed it will not be deleted by this function. This is intentional; cleanup is for cases of fast iteration, where a lot of nodes can accumulate fast. It should interfere with anything the user wants to keep as little as possible!
Parameters: keep_selected (bool) – Prevent selected nodes from being deleted. Defaults to False.
-
core.
create_node
(node_type, name=None, **kwargs)[source]¶ Create a new node of given type as an NcNode.
Parameters: - node_type (str) – Type of Maya node to be created
- name (str) – Name for new Maya-node
- kwargs (dict) – arguments that are passed to Maya createNode function
Returns: Instance that is linked to the newly created transform
Return type: Example
a = noca.create_node("transform", "myTransform") a.t = [1, 2, 3]
-
core.
locator
(name=None, **kwargs)[source]¶ Create a Maya locator node as an NcNode.
Parameters: - name (str) – Name of locator instance that will be created
- kwargs (dict) – keyword arguments given to create_node function
Returns: Instance that is linked to the newly created locator
Return type: Example
a = noca.locator("myLoc") a.t = [1, 2, 3]
-
core.
noca_op
(func)[source]¶ Add given function to the Op-class.
Note
This is a decorator used in NodeCalculator extensions! It makes it easy for the user to add additional operators to the Op-class.
Check the tutorials and example extension files to see how you can create your own extensions.
Parameters: func (executable) – Function to be added to Op as a method.
-
core.
set_global_auto_consolidate
(state)[source]¶ Set the global auto consolidate state.
Note
Auto consolidate combines full set of child attrs to their parent attr: [“translateX”, “translateY”, “translateZ”] becomes “translate”.
Consolidating plugs is preferable: it will make your node graph cleaner and easier to read. However: Using parent plugs can sometimes cause update issues on attrs!
Parameters: state (bool) – State auto consolidate should be set to
-
core.
set_global_auto_unravel
(state)[source]¶ Set the global auto unravel state.
Note
Auto unravel breaks up a parent attr into its child attrs: “translate” becomes [“translateX”, “translateY”, “translateZ”].
This behaviour is desired in most cases for the NodeCalculator to work. But in some cases the user might want to prevent this. For example: When using the choice-node the user probably wants the inputs to be exactly the ones chosen (not broken up into child-attributes and those connected to the choice node).
Parameters: state (bool) – State auto unravel should be set to
-
core.
transform
(name=None, **kwargs)[source]¶ Create a Maya transform node as an NcNode.
Parameters: - name (str) – Name of transform instance that will be created
- kwargs (dict) – keyword arguments given to create_node function
Returns: Instance that is linked to the newly created transform
Return type: Example
a = noca.transform("myTransform") a.t = [1, 2, 3]