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)

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)

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)

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)

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:

• holder_node (NcNode) – Represents a Maya node
• attrs (str or list or NcAttrs) – Represents attrs on the Maya node

_holder_node

NcNode instance this NcAttrs belongs to.

Type:NcNode

_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

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)

Regular addition operator for NodeCalculator objects.

Example

Node("pCube1.ty") + 4

__div__(other)

Regular division operator for NodeCalculator objects.

Example

Node("pCube1.ty") / 4

__eq__(other)

Equality operator for NodeCalculator objects.

Returns:Instance of a newly created Maya condition-node Return type:NcNode

Example

Node("pCube1.ty") == 4

__ge__(other)

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)

Greater than operator for NodeCalculator objects.

Returns:Instance of a newly created Maya condition-node Return type:NcNode

Example

Node("pCube1.ty") > 4

__init__()

Initialize NcBaseClass instance.

__le__(other)

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)

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)

Regular multiplication operator for NodeCalculator objects.

Example

Node("pCube1.ty") * 4

__ne__(other)

Inequality operator for NodeCalculator objects.

Returns:Instance of a newly created Maya condition-node Return type:NcNode

Example

Node("pCube1.ty") != 4

__neg__()

Leading minus sign multiplies by -1.

Example

- Node("pCube1.ty")

__pos__()

Leading plus signs are ignored, since they are redundant.

Example

+ Node("pCube1.ty")

__pow__(other)

Regular power operator for NodeCalculator objects.

Example

Node("pCube1.ty") ** 4

__radd__(other)

Reflected addition operator for NodeCalculator objects.

Note

Fall-back method if regular addition is not defined/fails.

Example

4 + Node("pCube1.ty")

__rdiv__(other)

Reflected division operator for NodeCalculator objects.

Note

Fall-back method if regular division is not defined/fails.

Example

4 / Node("pCube1.ty")

__rmul__(other)

Reflected multiplication operator for NodeCalculator objects.

Note

Fall-back method if regular multiplication is not defined/fails.

Example

4 * Node("pCube1.ty")

__rpow__(other)

Reflected power operator for NodeCalculator objects.

Example

4 ** Node("pCube1.ty")

__rsub__(other)

Reflected subtraction operator for NodeCalculator objects.

Note

Fall-back method if regular subtraction is not defined/fails.

Example

4 - Node("pCube1.ty")

__sub__(other)

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)

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)

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)

Add a value to the class-variable _traced_values.

Parameters:value (NcValue) – Value with metadata. Check docString of NcValue.

_compare(other, operator)

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:

NcNode

classmethod _flush_command_stack()

Reset class-variable _executed_commands_stack to an empty list.

classmethod _flush_traced_nodes()

Reset class-variable _traced_nodes to an empty list.

classmethod _flush_traced_values()

Reset class-variable _traced_values to an empty list.

classmethod _get_next_value_name()

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()

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

classmethod _get_tracer_variable_for_node(node)

Try to find and return traced variable for given node.

Parameters:node (str) – Name of Maya node Returns:

If there is a traced variable for this node:

Return the variable, otherwise return None

Return type:str or None

classmethod _initialize_trace_variables()

Reset all class variables used for tracing.

class core.NcBaseNode

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__()

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__()

Iterate over list of attributes.

Yields:NcNode – Next item in list of attributes. Raises:StopIteration – If end of .attrs_list is reached.

__len__()

Return the length of the stored attributes list.

Returns:Length of stored NcAttrs list. 0 if no Attrs are defined. Return type:int

__repr__()

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)

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:

• name (str) – Name of the attribute to be set
• value (NcNode or NcAttrs or str or int or float or list or tuple) – Connect attr to this object or set attr to this value/array

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)

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:

• index (int) – Index of item to be set
• value (NcNode or NcAttrs or str or int or float) – Set/connect item at index to this.

__str__()

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()

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)

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:

NcNode

_define_add_attr_method(attr_type, default_data_type)

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)

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:

NcNode

Example

Node("pCube1").add_enum(cases=["A", "B", "C"], value=2)

add_int(*args, **kwargs)

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:

NcNode

add_separator(name=<sphinx.ext.autodoc.importer._MockObject object>, enum_name=<sphinx.ext.autodoc.importer._MockObject object>, cases=None, **kwargs)

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:

NcNode

Example

Node("pCube1").add_separator()

attr(attr=None)

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

auto_state()

Print the status of _auto_unravel and _auto_consolidate.

get()

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)

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)

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)

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)

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)

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)

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__()

Behavior for copy.copy().

Returns:Shallow copy of this NcList instance. Return type:NcList

__deepcopy__(memo=None)

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)

Delete the item at the given index from this NcList instance.

Parameters:index (int) – Index of the item to be deleted.

__getattr__(name)

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)

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)

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__()

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__()

Return the length of the NcList.

Returns:Number of items stored in this NcList instance. Return type:int

__repr__()

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__()

Reverse the list of stored items on this NcList instance.

Returns:New instance with reversed list of items. Return type:NcList

__setattr__(name, value)

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:

• name (str) – Name of the attribute to be set. “attrs” is keyword!
• value (NcNode or NcAttrs or str or int or float or list or tuple) – Connect attr to this object or set attr to this value/array

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)

Set or connect attribute at index to the given value.

Note

This looks at the _items list of this NcList instance

Parameters:

• index (int) – Index of item to be set
• value (NcNode or NcAttrs or str or int or float) – Set/connect item at index to this.

__str__()

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)

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)

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)

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)

Extend NcList with another list.

Parameters:other (NcList or list) – List to be added to the end of this NcList.

get()

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)

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:

• index (int) – Index at which the value should be inserted.
• value (NcNode or NcAttrs or str or int or float) – Value to insert.

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

set(value)

Set or connect the value of all NcNode/NcAttrs-attributes in NcList.

Note

Similar to a cmds.setAttr() on a list of plugs.

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.

class core.NcNode(node, attrs=None, auto_unravel=None, auto_consolidate=None)

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)

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)

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)

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

_held_attrs

NcAttrs instance that defines the attrs.

Type:NcAttrs

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)

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:

NcNode or NcList or NcValue

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)

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)

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)

OperatorMetaClass-class constructor

Note

name, bases, body are necessary for __metaclass__ to work properly

__weakref__

list of weak references to the object (if defined)

available(full=False)

Print all available operators.

Parameters:full (bool) – If False only the operator-names are printed. If True the docString of all operators is printed. Defaults to False.

class core.Tracer(trace=True, print_trace=False, pprint_trace=False, cheers_love=False)

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__()

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)

Print executed commands at the end of the with-statement.

__init__(trace=True, print_trace=False, pprint_trace=False, cheers_love=False)

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)

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.__load_extensions()

Import the potential NodeCalculator extensions.

core._add_to_node_bin(node)

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)

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)

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)

Create a procedural Maya node name that is as descriptive as possible.

Parameters:

• operation (str) – Operation the new node has to perform
• args (MPlug or NcNode or NcAttrs or list or numbers or str) – Attributes connecting into the newly created node.

Returns:

Generated name for the given node operation and args.

Return type:

str

core._create_operation_node(operation, *args)

Create & connect adequately named Maya nodes for the given operation.

Parameters:

• operation (str) – Operation the new node has to perform
• args (NcNode or NcAttrs or str) – Attrs connecting into created node

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:

NcNode or NcList

core._create_traced_operation_node(operation, attrs)

Create named Maya node for the given operation & add cmds to _command_stack if Tracer is active.

Parameters:

• operation (str) – Operation the new node has to perform
• attrs (MPlug or NcNode or NcAttrs or list or numbers or str) – Attrs that will be connecting into the newly created node.

Returns:

Name of newly created Maya node.

Return type:

str

core._format_docstring(*args, **kwargs)

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)

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:

• operation (str) – Operation the new node has to perform.
• new_node (str) – Name of newly created Maya node.
• args_list (NcNode or NcAttrs or NcValue) – Attrs/Values the node attrs will be connected/set to.

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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:

NcNode

Example

a = noca.create_node("transform", "myTransform")
a.t = [1, 2, 3]

core.locator(name=None, **kwargs)

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:

NcNode

Example

a = noca.locator("myLoc")
a.t = [1, 2, 3]

core.noca_op(func)

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.reset_cleanup()

Empty the cleanup queue without deleting the nodes.

core.set_global_auto_consolidate(state)

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)

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)

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:

NcNode

Example

a = noca.transform("myTransform")
a.t = [1, 2, 3]