# Node Expressions

(also known as Dynamic Maths Expressions)

The Node Expressions add-on adds a new option in the Node Editor - to add a Maths Expression. The Maths Expression consists of a 'Group' node with the internal nodes automatically generated from an entered mathematical expression. Within the Maths Expression is a custom node which allows the Maths Expression to be managed - allowing it to be edited or updated, as well as showing the expression used to generate the nodes.

â€‹

Node Expressions is available in two "flavours", 'Full' and 'Lite'. The 'Lite' version is available for free from Github and allows you to create 'simple' expressions - where only a single line of text is entered and sub-expressions do not refer to each other, while the 'Full' version allows fully 'compound' expresions, sub-groups, expression optimisation, multi-line editing in the Text Editor window, node optimisations and sub-grouping, a set of 'preset' configurable expressions you can immediately inspect and use in your own projects, and more. The 'Full' version is available on Blender Market or can now also be downloaded for free from Github.

# Comparison of 'Full' and 'Lite' functionality

The following list shows which features are available in the 'Lite' and 'Full' versions of the add-on.

Feature | 'Lite' | 'Full' | Description |
---|---|---|---|

Simple Expressions | Yes | Yes | Create simple expressions such as 'Output = a+b+c' |

Basic Mathematical Operators | Yes | Yes | +, -, *, /, ** (power) |

Operator Precedence | Yes | Yes | Standard mathematical operator precedence, including brackets to change precedence - ie, Brackets over Division, Multiplication, Addition, Subtraction |

Edit Expressions | Yes | Yes | Easily edit existing expressions |

Trigonometric and other basic functions | Yes | Yes | Sine, Cosine, Round, Absolute, Maximum, Minimum, etc. |

Vector manipulation and functions | Yes | Yes | Split and combine vectors, vector maths, etc. |

Multiple Outputs | Yes | Yes | Expressions can contain multiple sub-expressions, separated by commas |

Compound Expressions | No | Yes | Sub-expressions can be combined with each other to create 'compound' expressions (ie, can one one sub-expression directly in anothe sub-expression within the same node group) |

Explicit Inputs/Outputs | No | Yes | Define inputs and outputs explicitly without having to prefix each 'internal' variable |

Default Input Values | Yes | Yes | Ability to set default values when using an expression to create a new node. |

Basic Texture Nodes | Yes | Yes | Noise, Musgrave, Voronoi |

Advanced Texture Nodes | No | Yes | Point, Image |

Text Block Editing | No | Yes | Use a text block as the source of the expression rather than having to enter as only a single line of text |

Named group inputs/outputs | No | Yes | |

Special Variables | Yes | Yes | Use 'special' variables to reference specific input nodes (Texture Coordinate, Geometry, etc.) |

Presets | No | Yes | Preset expressions that can be used in your own projects and that provide examples of how to use the various expression features |

User-Defined Functions | No | Yes | Create additional functions that can be used in your own expressions |

Sub-Group nodes | No | Yes | Create and use sub-group nodes in your own expressions (useful for iterative expressions such as Mandelbulb) |

Import Text | No | Yes | Import text (such as library functions) from other text blocks |

## What does it do?

The add-on provides a new option to add a Maths Expression in the Node Editor. This allows you to enter a mathematical expression (such as "a+b * 5 * sin(angle)") which is then parsed and used to generate nodes to produce that function within a new 'Group' node.

â€‹

## How does it work?

When you add a Maths Expression you will be prompted to enter the expression. The expression is validated and, if valid, generates the nodes for that function. The syntax of the entered expression follows natural mathematical precedence and multiple expressions can be entered by separating with commas and inputs and outputs to the group are automatically generated from the expression. For example, the expression "Max = max(a,b,c,d,e), Sum = a+b+c+d+e" will generate a group node with inputs of 'a', 'b', 'c', 'd', 'e' and with outputs of 'Max' (outputting the maximum of the input values) and 'Sum' (outputting the sum of the input values).

Within the node group is a custom node that provides facilities to manage the group (eg, Edit, Update or Revert to a previous state of the expression).

## Why would I want to do that?

Implementing complicated calculations using nodes can be extremely time consuming - and can be prone to error with jujst one node socket mis-connected resulting in the wrong result. By generating the nodes from a textual expression the nodes can be created effortlessly at the click of a button. Changing the expression is simply a matter of amending the text and clicking 'update' so you can try out different expressions immediately without having to re-link multiple nodes to re-build your node tree manually.

â€‹

When using the 'Full' expression you can edit your expression within the Node Editor window and this can be spread over mulitple lines and can include blank lines, spacing and 'comments' - so you can annotate your expression for future reference, as well as being able to define and re-use 'sub-groups' to allow you to build really complicated node trees effortlessly.

## What are the limitations?

Node Expressions currently only supports 'Shader' node trees - so it isn't yet available for editing Compositor node trees, for example.

â€‹

Blender Node Editor appears to slow down considerably as the complexity of the node tree increases. Since the Node Expressions add-on allows you to build very complicated node trees very easily, this can become a problem. Note that this issue affect the responsiveness of the node editor when manipulating the nodes, rather than a performance issue when actually rendering using those nodes.

â€‹

## How to install it

Download the ZIP file and use the 'Install from Zip' button (renamed to just 'Install...' at Blender version 2.8) within the Add-Ons section of the preferences to install it. Once installed, don't forget to tick the Enable checkbox alongside the add-on.

## How to use it

Once enabled, you should see the new Maths Expression option within the Add menu of the Node Editor. Simply select that option and you can start entering your expression - try something simple such as 'a+b' and work up from there - click the Documentation button within the add-on to see the list of available operations and expressions.

â€‹

A really simple example that demonstrates the ease of use. For more terms, simply edit the expression as desired e.g. (to sum 8 inputs) :

â€‹

a+b+c+d+e+f+g+h

â€‹

# Amplitude = sin(Input * Frequency)

# Amplitude = sin(Input * Frequency) / 2 + 0.5

A slightly more complicated example including constant values in the calculation - in this case to shift the output of Sine so it varies from 0.0 to 1.0 instead of -1.0 to 1.0.

# Angle = atan(x/y), Distance = (x**2 + y**2) ** 0.5

This example is defining two expressions using the same input values and produces a node group with two outputs.

# Angle = atan(Input[x]/Input[y]), Distance = (Input[x]**2 + Input[y]**2) ** 0.5

Vectors can be used for input and output. Elements of each vector (in this case 'Input') are used by adding a suffix specifying the component - in this case 'Input[x]' and 'Input[y]' to access the X and Y channels of the input vector.

â€‹

Note that a 'combine(x,y,z)' function is provided to allow expressions to generate vector outputs.

# _dist=(Input[x]**2+Input[y]**2)**0.5, _angle=atan2(Input[y],Input[x]), _edge=sin(_angle*Points)/2+0.5, Output=_dist>_edge*(Outer-Inner)+Inner

Note : This example requires the 'Full' version of Node Expressions since it is a 'compound' expression (outputs from one sub-expression feed into another sub-expression). The expression first defines '_dist' as the distance from the centre and '_angle' as the angle around the centre (the leading '_' indicates it's an 'internal' value that shouldn't be given an 'output' socket). The angle is used to calculate '_edge' by varying based on the Sine of the angle multiplied by the number of Points. Finally, the Output is calculated based on '_dist' lies outside the '_edge', using Inner and Outer to allow the star to be adjusted.

Note that in this particular case the expression can be 'folded together to create a single expression that can be used in the 'Lite' version of the add-on by taking the 'Output' expression and expanding each of the sub-expressions. ie,

â€‹

Output=_dist>_edge*(Outer-Inner)+Inner

â€‹

Substitite '_dist' :

Output=(Input[x]**2+Input[y]**2)**0.5>_edge*(Outer-Inner)+Inner

â€‹

Substitite '_edge' :

Output=(Input[x]**2+Input[y]**2)**0.5>sin(_angle*Points)/2+0.5*(Outer-Inner)+Inner

â€‹

Substitite '_angle' :

Output=(Input[x]**2+Input[y]**2)**0.5>sin(atan2(Input[y],Input[x])*Points)/2+0.5*(Outer-Inner)+Inner

â€‹

The above expression is less readable but can be used directly in the 'Lite' version of the add-on.

# Expressions in the Text Editor

â€‹

With the 'Full' version of Node Expressions, the expression can be edited directly in the Text Editor window in a text block. This provides improved readability (and can include blank lines, spacing and comments) and easier editing and the nodes can be updated at the click of a button.

The above example is the 'hexagons' preset expression provided with the 'full' version of the add-on - edited to use Generated coordinates - and is a good example of what can be achieved. The 'presets' provide working examples of what is possible with Node Expressions. Any node groups generated using Node Expressions can be exported and used independently of the add-on in any of your own projects.

# See Also

See the Tutorials section for some further examples of using this add-on and the Documentation section for additional documentation (as well as the in-built documentation within the add-on itself).

# Submit Your Expressions

Created an expression that you want to share? Something novel or interesting? I'd love to hear from you. Send me a message with your expression and a brief explaination. I'll collect the best submissions together and maintain a gallery so that others can benefit from your experience.