Merge pull request #14 from serguei-k/v1.5.0

V1.5.0

CMakeLists.txt

@@ -3,7 +3,7 @@
 
 # Define project
 cmake_minimum_required(VERSION 3.3)
-project(maya-math-nodes VERSION 1.4.0)
+project(maya-math-nodes VERSION 1.5.0)
 
 # Set project version macro
 add_definitions(-DPROJECT_VERSION="${PROJECT_VERSION}")
@@ -37,6 +37,7 @@ add_library(mayaMathNodes SHARED
     src/Array.h
     src/Condition.h
     src/Clamp.h
+    src/Debug.h
     src/Distance.h
     src/Divide.h
     src/Convert.h

docs/source/conf.py

@@ -40,9 +40,11 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -164,4 +166,5 @@
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+todo_include_todos = True
+autodoc_mock_imports = ['maya']

docs/source/expressionLanguage.rst → docs/source/expression_language.rst

@@ -1,4 +1,4 @@
-.. _expressionLanguage:
+.. _expression_language:
 
 Expression Language
 ===================
@@ -25,17 +25,23 @@ The language supports the following data types:
 numeric
    float and int types are supported, ex: :code:`-1, 0, 1.0`
 
+boolean
+   boolean **true** and **false** values are supported and can cast to POD numeric types
+
 string
    string literals are used to reference Maya attributes, ex: :code:`node.attribute[0]`,
-   note that there are no quatation marks around the string literals!
+   note that there are no quotation marks around the string literals!
 
 complex
    complex types such as vector, matrix, rotation, and quaternion are specified by using cast functions, ex: :code:`vec(0, 1, 0)`
 
+geometry
+   a small subset of functions also supports geometry types such as mesh, nurbsCurve, and nurbsSurface
+
 Operators
 ---------
 
-The language supports a limited set of arithmetic operators: :code:`+, -, *, /, %,`
+The language supports a limited set of arithmetic and logical operators: :code:`+, -, *, /, %, &, |, ^, !`
 
 Conditionals
 ------------
@@ -51,7 +57,7 @@ The language supports calling functions with arguments.
 These functions map directly to the node operators available in the plugin.
 
 For example :code:`Absolute` node is made available through the :code:`abs()` function call.
-Please see the :ref:`Node Reference <nodeReference>` for the mapping between node type and function name.
+Please see the :ref:`Node Reference <node_reference>` for the mapping between node type and function name.
 
 The function arguments correspond with node attributes. For example the :code:`Clamp` node has two input
 attributes, therefore the :code:`clamp(arg1, arg2)` function will take two arguments.
@@ -66,7 +72,8 @@ Cast Functions
 Several functions that output complex data types can take constant values as input.
 
 mat
-  :code:`mat(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)` can be used to specify constat matrix value
+  :code:`mat(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)` can be used to specify constant matrix value,
+  :code:`mat()` also maps to several math nodes and can take other arguments, ex: :code:`mat(node.rotate, 0)`
 
 rot
   :code:`rot(0, 1, 0)` can be used to specify constant rotation value, :code:`rot()` also maps to several
@@ -81,29 +88,31 @@ vec
 
 .. warning::
    | Currently, some nodes do not have expression bindings!
-   | See :ref:`Node Reference <nodeReference>` section for details.
+   | See :ref:`Node Reference <node_reference>` section for details.
 
 .. note::
-   Default and keyword arguments are currently not supported!
+   Function calls require at least one argument to be specified!
 
 Evaluation Order
 ----------------
 
 Expressions are evaluated left to right with the following operator precedence, listed from lowest to highest:
 
-+----------------------+-------------------------------------+
-| Operator             | Description                         |
-+----------------------+-------------------------------------+
-| +, -                 | Addition and subtraction            |
-+----------------------+-------------------------------------+
-| \*, /, %             | Multiplication, division, remainder |
-+----------------------+-------------------------------------+
-| <, <=, >, >=, !=, == | Comparisons                         |
-+----------------------+-------------------------------------+
-| func()               | Function call                       |
-+----------------------+-------------------------------------+
-| (...)                | Grouping                            |
-+----------------------+-------------------------------------+
++----------------------------+-------------------------------------+
+| Operator                   | Description                         |
++----------------------------+-------------------------------------+
+| <, <=, >, >=, !=, ==, ?, : | Comparisons and ternary             |
++----------------------------+-------------------------------------+
+| &, |, ^, !                 | Logical operators                   |
++----------------------------+-------------------------------------+
+| +, -                       | Addition and subtraction            |
++----------------------------+-------------------------------------+
+| \*, /, %                   | Multiplication, division, remainder |
++----------------------------+-------------------------------------+
+| func()                     | Function call                       |
++----------------------------+-------------------------------------+
+| (...)                      | Grouping                            |
++----------------------------+-------------------------------------+
 
 Type Resolution
 ---------------
@@ -141,7 +150,7 @@ Examples
   from maya_math_nodes import eval_expression
 
   # get twist value for roll joint
-  eval_expression('twist(ctrl.worldMatrix[0], 0, 0) * 0.5', 'roll')
+  eval_expression('twist(ctrl.worldMatrix[0]) * 0.5', 'roll')
 
   # get toe pivot value for foot roll
   eval_expression('ctrl.roll > ctrl.break ? ctrl.roll - ctrl.break : 0', 'toeroll')

docs/source/index.rst

@@ -10,15 +10,15 @@ Welcome to Maya Math Nodes Documentation
    :maxdepth: 1
    :caption: User Documentation
 
-   nodeReference
-   expressionLanguage
+   node_reference
+   expression_language
 
 Maya Math Nodes is a plugin for Autodesk Maya that provides a set of atomic nodes to perform various common math operations.
 The purpose of these nodes is to streamline the creation of complex and highly performant rigging systems.
 
-To see the list of nodes made available by the plugin, please refer to the :ref:`Node Reference <nodeReference>` section.
+To see the list of nodes made available by the plugin, please refer to the :ref:`Node Reference <node_reference>` section.
 
-Additionaly, this plugin provides a simple expression language that can be used to describe a series of mathematical operations inline, which can then be interpreted to generate a math node network for you, see :ref:`Expression Language <expressionLanguage>` section for details.
+Additionally, this plugin provides a simple expression language that can be used to describe a series of mathematical operations inline, which can then be interpreted to generate a math node network for you, see :ref:`Expression Language <expression_language>` section for details.
 
 .. note::
    At this time there are no distributable binaries available for download.

docs/source/nodeReference.rst → docs/source/node_reference.rst

@@ -1,4 +1,4 @@
-.. _nodeReference:
+.. _node_reference:
 
 Node Reference
 ==============
@@ -52,6 +52,7 @@ AndBool
 -------
 :description: Gets logical *and* of two values
 :type variants: AndInt
+:expression: x & b
 
 AngleBetweenVectors
 -------------------
@@ -77,6 +78,7 @@ Average
 -------
 :description: Computes average value
 :type variants: AverageAngle, AverageInt, AverageMatrix, AverageQuaternion, AverageRotation, AverageVector
+:expression: average([x, y, ...])
 
 AxisFromMatrix
 --------------
@@ -98,7 +100,7 @@ Clamp
 Compare
 -------
 :description: Compute how the two values compare to each other
-:type variants: CompareAngle
+:type variants: CompareAngle, CompareInt
 :expression: compare(x, y)
 
 CosAngle
@@ -111,6 +113,11 @@ CrossProduct
 :description: Computes the cross product of two vectors
 :expression: cross(x, y)
 
+DebugLog
+--------
+:description: Pass-through node that will log the value to Maya Script Editor
+:type variants: DebugLogAngle, DebugLogInt, DebugLogMatrix, DebugLogQuaternion, DebugLogVector
+
 Divide
 ------
 :description: Computes the quotient of two values
@@ -133,10 +140,10 @@ Floor
 :description: Computes the largest integer value less than or equal to input
 :expression: floor(x)
 
-InverseMatrix
--------------
+Inverse*
+--------
 :description: Computes the inverse of value
-:type variants: InverseQuaternion, InverseRotation
+:type variants: InverseMatrix, InverseQuaternion, InverseRotation
 :expression: inverse(x)
 
 Lerp
@@ -145,9 +152,21 @@ Lerp
 :type variants: LerpAngle, LerpMatrix, LerpVector
 :expression: lerp(x, y, alpha)
 
+MatrixFrom*
+-----------
+:description: Computes a rotation matrix from input
+:type variants: MatrixFromRotation, MatrixFromQuaternion
+:expression: mat(x, rot_order)
+
+MatrixFromDirection
+-------------------
+:description: Computes a rotation matrix from direction and up vector
+:expression: direction(dir_vec, up_vec)
+
 MatrixFromTRS
 -------------
 :description: Computes a matrix from translation, rotation and scale
+:expression: trs(translation, rotation, scale)
 
 Max
 ---
@@ -159,7 +178,7 @@ MaxElement
 ----------
 :description: Gets the largest value in array
 :type variants: MaxAngleElement, MaxIntElement
-:expression: maxelement(x, y)
+:expression: maxelement([x, y, ...])
 
 Min
 ---
@@ -171,7 +190,7 @@ MinElement
 ----------
 :description: Gets the smallest value in array
 :type variants: MinAngleElement, MinIntElement
-:expression: minelement(x, y)
+:expression: minelement([x, y, ...])
 
 ModulusInt
 ----------
@@ -199,55 +218,70 @@ NormalizeVector
 NormalizeArray
 ---------------
 :description: Normalize array of values
-:expression: normalizearray(x)
+:expression: normalizearray([x, y, ...])
 
 NormalizeWeightsArray
 ---------------------
 :description: Normalize array of weight values
+:expression: normalizeweights([x, y, ...])
+
+NotBool
+-------
+:description: Logical *not*
+:expression: !x
 
 OrBool
 -------
 :description: Gets logical *or* of two values
 :type variants: OrInt
+:expression: x | y
 
 Power
 -----
 :description: Computes the value raised to power of the exponent
 :expression: power(x, exp)
 
-QuaternionFromMatrix
---------------------
+QuaternionFrom*
+---------------
 :description: Gets quaternion from matrix or rotation
-:type variants: QuaternionFromRotation
+:type variants: QuaternionFromMatrix, QuaternionFromRotation
 :expression: quat(x, rot_order)
 
+Remap
+-----
+:description: Remap value from old range to new range
+:type variants: RemapAngle, RemapInt
+:expression: remap(x, low1, high1, low2, high2)
+
 Round
 -----
 :description: Computes rounded value
 :type variants: RoundAngle
 :expression: round(x)
 
-RotationFromMatrix
-------------------
+RotationFrom*
+-------------
 :description: Gets rotation from matrix or quaternion
-:type variants: RotationFromQuaternion
+:type variants: RotationFromMatrix, RotationFromQuaternion
 :expression: rot(x, rot_order)
 
 ScaleFromMatrix
 ---------------
 :description: Gets scale from matrix
+:expression: scale(x)
 
 Select
 ------
 :description: Toggles output
-:type variants: SelectAngle, SelectInt, SelectMatrix, SelectQuaternion, SelectRotation,
-   SelectVector
+:type variants: SelectAngle, SelectCurve, SelectInt, SelectMatrix, SelectMesh, SelectQuaternion, SelectRotation,
+   SelectSurface, SelectVector
 :expression: select(x, y, state)
 
 SelectArray
 -----------
 :description: Toggles array output
 :type variants: SelectAngleArray, SelectIntArray, SelectMatrixArray, SelectVectorArray
+:expression: selectarray(x, y, state)
 
 SinAngle
 --------
@@ -256,9 +290,14 @@ SinAngle
 
 SlerpQuaternion
 ---------------
-:description: Comptues slerp interpolation between two quaternions
+:description: Computes slerp interpolation between two quaternions
 :expression: slerp(x, y)
 
+Smoothstep
+----------
+:description: Computes smoothstep interpolation of value within [0.0, 1.0] range
+:expression: smoothstep(x)
+
 Subtract
 --------
 :description: Computes the difference between two values
@@ -269,6 +308,7 @@ Sum
 ---
 :description: Computes the the sum of values
 :type variants: SumAngle, SumInt, SumVector
+:expression: sum([x, y, ...])
 
 TanAngle
 --------
@@ -278,11 +318,12 @@ TanAngle
 TranslationFromMatrix
 ---------------------
 :description: Get translation from matrix
+:expression: translation(x)
 
-TwistFromMatrix
----------------
+TwistFrom*
+----------
 :description: Computes twist around axis from matrix or rotation
-:type variants: TwistFromRotaiton
+:type variants: TwistFromMatrix, TwistFromRotaiton
 :expression: twist(x, axis, rot_order)
 
 VectorLength
@@ -305,3 +346,4 @@ XorBool
 -------
 :description: Gets logical *xor* of two values
 :type variants: XorInt
+:expression: x ^ b