Operators

 

Overview

Operators are used to transform or modify the behaviour of nodes in the Style Editor. There are currently three types of operator, those that work on segments, those that only work on other operators, and those that work with parameters. Click on the name of the operator for more detailed information.

Operators that require Segments as inputs (will also work with composite operators like sequence and compose)

 

Material

Overview

The Material operator uses a designated Material ID from the input segment and replaces it with a new value identified in the From/To range. If the From and To value are identical, the ID is simply swapped for a single value. If the From/To values form a range, then the operator can either replace the IDs in a looping sequence or pick values at random.

Material IDs reassigned in sequence

Material IDs reassigned at random

 

This operator is only compatible with V-Ray. To use with other renderers it is necessary to disable Display > Use Instancing Engine. See  Best Rendering Practices for more information about the rendering modes.

Usage

A single Material Operator is used to reassign a material ID from the input Segment.

If you would like to reassign multiple IDs in the same segment, several material operators can be wired in series, each controlling a different input ID.

Interface

Random. Selects a value at random between the From/To ID range. 
Sequence. Cycles through the From/To Id range values, looping when it reaches the end.
From/To. Defines the start and end values of a range for the Material IDs.

 

 

 

Selector

Overview

The selector operator allows you to choose from a list of segments using a numerical index. This operator allows a segment to be selected manually from the operator’s properties, wired to a numerical node for easy manipulation without opening the style editor (as illustrated below), or derived from the material ID assigned to a spline segment.

Segments controlled by a numerical node accessed from the parameters rollout of the Max plugin.

Usage

  1. Wire segments to the Selector operator’s inputs. The order is important - the index numbering is built from the top of the list with an origin of 1.
  2. If you need to change the order, use the up and down arrows that appear when you select the segment name on the Selector node.
  3. Choose a method to control selection. To use the index spinner to switch between segments, go to Properties>Selector and ensure it is set to Index. If the segments will be selected automatically by the material ID of a spline segment, change the Properties>Selector setting to Mat ID.

It is useful to export the Index parameter to make changes without opening the style editor

  1. Right click on the Selector node and choose Export>Index

  2. Create a new Numerical node and wire it to the Index input.
  3. You can now control the selection from the Parameters rollout of the plugin without opening the style editor.

To change a spline’s material ID

  1. Go to the Base Spline’s segment sub object level
  2. Select the segments you wish to change and go to the Surface Properties rollout. Enter a new Material ID in the Set ID field.

Interface

Selector

Pick between two modes:

Index mode. Chooses a segment from the array using the number displayed in the Index spinner
Spline Mat ID mode. Chooses a segment from the array using the material ID of the base spline’s segments.

Index

Used with Index mode to control the segment chosen from the array. Can be exported.

 

 

Mirror

Overview

Makes a mirror copy of a segment's geometry using a combination of the XYZ axes as a mirror plane.

The first half of the spline uses standard segment, the second half uses segment attached to mirror operator.

Usage

  1. Attach the segment to be mirrored to the input slot of the Mirror node and select the axis for the mirror operation.

Interface

Axis

Chooses the axis to be used as a mirror plane, multiple axes can be selected.

X. Mirrors the segment on the X Axis
Y. Mirrors the segment on the Y Axis
Z. Mirrors the segment on the Z Axis


 

Randomize

Overview.

Returns a random Segment from the list of inputs. Each segment has a presence value that determines the probability of it being selected. These values are normalised so there is no need to ensure they add up to 100%

Random selection from 4 segments

Usage

  1. Connect a number of segments to the input slots of a Randomize node.
  2. Set the presence of each segment to control probability. If you would like an equal chance of each segment being selected, leave the values at their default 100%.
  3. This example will randomly select between the 3 attached segments with the Middle segment having a 35% chance of being selected.

Interface

Presence (%). A normalised value that determines the probability of an individual segment being selected

 

 

Sequence

Overview

Creates sequences of the segments used as inputs, starting at the top of the list and working downward. Each segment can be repeated using a simple counter, when the counter reaches its limit, RailClone moves on to the next item in the list. When the sequence reaches the end of the list, it starts again from the beginning.

Repeating sequence of 3 segments

The sequence can be reset at either the start of each spline or the start of a new section. The latter is defined as a length of path found between two segments of the Start, End, Corner, or Evenly type.

Usage

  1. Attach Segments to the input slots of a Sequence node

  2. To change the order, use the up and down arrow tools that appear when you select the segment name on the Sequence node

  3. From the Properties view, adjust the counters for any segments you wish to repeat

  4. When using a 2D array, choose the axis

  5. you wish to use to create the sequence.
  6. Set the Sequence Reset to either Spline or Segment start

Interface

Increment at X/Y. When using a 2D array, chooses the axis used to create the sequence.

Reset at Spline Start/Spline Section. Determines when the sequence starts again.

Counter. A numerical value that allows you to repeat segments without having to attach them to the Sequence node multiple times.

 

 

Compose

Overview

The compose node allows you to build a new geometry object by combining several segments together. When attached they will array along the path one after the other (similar to the sequence node, above). However when used in conjunction with a Segment's padding and transform settings, segments can be moved rotated and scaled on any axis to make a complex composite object.

4 segments combined using a compose node (marked with a white outline).

Usage

  1. Attach segments to the input slots of a Compose Node
  2. Adjust the order using the up and down arrow tools that appear when you select the segment name on the Compose Nose
  3. Adjust the location of each Segment using its Padding and transform settings.

Mode 

  • Sequence uses the default behaviour, Segments are placed one after another in order.
  • Grouped uses the first Segment as the main, which defines the composed geometry's size and placement in the Generator sequence. Other segments are placed stacked in same position, according to their alignment settings. Note that some advanced operations such as Bevel Corner, are not compatible with Stack mode and can generate incorrect results.

Tips on moving segments.

To move an object to the left, adjust the preceding segment's right padding

To move an object up or down adjust the segment's Transform>Fixed>Translation>Z value

To control the spacing between the Compose object and the next item of geometry, adjust the right padding of the final Segment node used in the Compose node inputs.

To rotate a segment use the Segment>Transform>Rotation values.

 

 

 

 

Conditional

Overview

Accepts two Segments as input, returning one of them (true or false), depending on whether certain conditions have been met. These can be nested to create a complex decision tree.

Usage

This node will be configured according to the condition you wish to test for, based on the following options.

Spline

Checks if the length of the underlying spline is greater or less than a specified value. The condition can be checked over the full length of the spline, or only for the current section. A section is the path between two segments of the type Start, End, Corner or Evenly.

Position

Displays 1 unless segment location is greater than 60% of total spline length, in which case 2 is displayed.

Checks if the position of the segment along the spline is greater or less than a certain value (defined in length percentage of the full path / section).

Type

Displays 1 on curved segments, 2 on line segments

Checks if the current spline segment is either a line or curve.

 

Right click to set the segment type of a spline

Setting spline segment types.

To set the spline segment type property on a spline used as a base object, go to the segmentsub objects of an editable spline, choose a segment, right click to set as either a Line or Curve.

 

Material ID

Checks the current segment's material ID. Returns a true or false value if this value is equal to, not, greater than, less than or a multiple of the ID identified in the material ID value of the conditional node.

Vertex

Example displays 2 on spline vertices unless it is a corner, in which case 3 is displayed, or smooth when 4 is displayed.

Returns true if the vertex just below the segment is of a certain type: Corner, Bezier, Bezier-Corner or Smooth. The Angle condition checks the angle formed by the spline at this vertex.

Usually this conditional is used together the Corner construction rule, to create different types of corners but it can also be used with the default input in which case the conditional node tests for the vertex at the beginning of the current spline segment.

Segment

Example displays 1 unless segment count = 3, when it displays 3, or segment count is a multiple of 5 when it displays 2.

Counts the number of segments placed on the path, before the current position. Returns true or false if the values entered in this node meets certain conditions, i.e.EqualNot equalGreater than, Lessthan, or a Multiple of the value.

This operator can be used to create sequences of segments a certain intervals. It is possible to check the X and Y counters independently (for array generators).

Interface

Spline Length. Activate to test for spline length
Full Spline/Current Section. Measures either the length of the entire spline or the curent segment
Greater/Less. Return true if spline or segment is greater or less than this value
Position. Activate to test for the position along the spline, measured as a percentage. 
On Spline/On Section. Measures position of either the entire spline or the current section
Greater/less. Return true if position is greater or less that this value.

Vertex. Activate to test for vertex type.
Corner/bezier/smooth/bezier/corner/not corner/not bezier/not smooth/not bezier - corner. Type of vertex that returns a true value
Angle. Activate to test for vertex angle
Greater/less. Return true if the angle is greater or less than this angle.
Chck wider angles (>180). When on, checks angles in the range 0 to 360 degrees, according to the path's direction. If disabled, angle checking is limited to 0-180 degrees.

Segment. Activate to test for segment count. 
X counter/Y Counter. Counts segment on either/and the x and y axis of an array
Equal/not equal/greater/less/multiple of. Returns true if the current segment is equal, greater, lesser, or a multiple of this value


 

Transform

Overview

Used to adjust the padding, alignment, and transform settings of a segment. This can be useful where you wish to reuse a segment multiple times but with different properties.

It is also necessary to use the Transform operator when dynamically controlling a segment’s properties using arithmetic expressions. Due to limitations in the current workflow, connecting a arithmetic node containing an expression directly to a Segment object is not possible. In this case connect the Arithmetic node to a transform as shown in the node diagram shown below.

 

Usage

To adjust the padding, alignment or transform settings of a segment:

  1. Wire the segment to the transform node’s input.

  2. In the Transform node’s properties, activate any settings you wish to use by clicking on the appropriate tick-box. This will override the values set in the Segment’s properties.

  3. If necessary, expose settings so that they can be controlled by numeric, constant, or arithmetic operators by right clicking on the Transform node and selecting Export>[properties]

  4. Connect the Transform nodes output to the generator or another operator’s input.

Interface

Padding. Controls the distance between adjacent segments with separate controls for left, right, top and bottom.
Fixed Size. Controls the size of the segment. If Scale Mode is off the values are used only for calculating the position of adjacent segments.
Alignment. Selects the pivot point position used to calculate the location of the segment on the X, Y, and Z axis
Pivot Offset. Offsets the pivot of the source geometry on the X,Y and Z axis. Pivot alignment should be used to see the effect.
Transform Fixed. Allow you to adjust the translation, rotation and scale of a segment.
Transform Random. Allows you to randomise the translation, rotation and scale of a segment by picking values from a range defined by a minimum and maximum value.
Color Seed. Used with RailClone Color to coordinate the randomisation of maps and tints, segments with the same colour seed in the same part of the array will get the same map and tint.

For detailed explanations of padding, alignment, transforms and randomisation please see the Segment reference.

 

UVW XForm

Overview

The UVW XForm operator allows you to manipulate the mapping coordinates already applied to a segment. These coordinates could be from the segment's original geometry, or they could have been created using RailClone's Automatic Box Mapping tools. There are two modes available: Fixed mode enables you to adjust the tiling, offset and rotation of UVW coordinates, in this case all segment's will have the same results; Random mode allows you to randomise within a range the tiling, offset and rotation of UVW coordinate to create unlimited variation.

Compatibility

V-Ray is required to maintain instancing when using this operator. Other renderers are supported by disabling instancing. To do this, turn off Display->Use Instancing Engine. To see a full list of which features are supported by your renderer, see the compatibility list.

 

The texture used in the following examples.

In fixed mode, the UVW coordinates are adjusted for all segments

In random mode, offset, rotation and tiling can be varied per segment within a range

In random mode with stepped offsets, the random values increment using a set value




Usage

To adjust UVWs
  1. Wire segment(s) to the UVW XForm operator’s input.
  2. Go the the UVW XForm operator's properties and change the Map Channel value to select the channel you wish to edit. To affect all channels turn on Apply to All Channels.
  3. Edit the Tile, Offset and Rotation values for the U,V and W axes.
To randomise UVWs within a range
  1. Wire segment(s) to the UVW XForm operator’s input.
  2. Go the the UVW XForm operator's properties and change the Map Channel value to select the channel you wish to edit. To affect all channels turn on Apply to All Channels.
  3. Make any adjustments required to the mapping in the Fixed tab of the properties panel as described above.
  4. Click on the Random tab in the Properties panel
  5. Add a Start and an End value to define the range for each of the attributes you wish to randomise.
To randomise UVWs using stepped increments
  1. Wire segment(s) to the UVW XForm operator’s input.
  2. Go the the UVW XForm operator's properties and change the Map Channel value to select the channel you wish to edit. To affect all channels turn on Apply to All Channels.
  3. Make any adjustments required to the mapping in the Fixed tab of the properties panel as described above.
  4. Click on the Random tab in the Properties panel
  5. Add a Start and an End value to define the range for each of the attributes you wish to randomise.
  6. Enter a Step Increment value. The random values returned by the operator will be multiples of this figure.

All the UVW XForm operator's parameters can be exported by right clicking on the node. This can be useful if you wish to enter a value in scene units for the Step Increment parameter. Below is a graph that will automatically set up the UVW XForm operator in the event that you have a texture that contains multiple tiles (equal number, equally spaced on the U and V axes) and you wish to randomise them with stepped increments. This is often a faster alternative to creating a complex multi-sub object material and randomising the material IDs.

 

The graph

The output, on a tile segment

 

Interface

Fixed

Use this tab to adjust the existing UVW mapping on the attached segments.

Map Channel Chooses the UVW Map channel to affected by the operator. Multiple operators can be use to assign map different map channels unique settings
Apply to all channels When on, all UVW map channels are affected by the operator.
U/V/W Tile Adjust the tiling with individual controls for UVW coordinates
U/V/W Offset
Adjust the offset with individual controls for UVW offsets.
Rotation
  Adjust the W Rotation.

Random

Use this tab to randomise the existing UVW mapping on the attached segments.

Tile U/V/W Start/End Define the start and end of a range from which random tiling values are returned.
Offset U/V/W Start/End Define the start and end of a range from which random offset values are returned.
Rotate Start/End Define the start and end of a range from which random rotation values are returned.
Step Increment If greater than 0, random values are derived from multiples of this number found within the range.

Operators that require other operators as inputs

Reverse

Overview

Reverses the order of elements in a Compose operator. If "Mirror Segments on X" is enabled, creates a mirror copy of each segment on the X axis.

Top Row: Standard Compose Node. Bottom Row: with reverse added. Note that unlike the mirror operator, segments are not flipped.

Usage

  1. Attach a Compose node to the Reverse node's input slot
  2. If you would like each segment to be mirrored on its X axis, select Mirror Segment on X from the properties editor.

Interface

Mirror Segments on X. When this is enabled each segment is individually flipped on its X axis.

Sequence reversed and flipped on the X axis.

 

Operators that require Parameters as inputs or generate values

 

 

Random

Overview

Used to generate random numbers that can be used in conjunction with exported properties and the arithmetic operator.

Usage

  1. From the Type list, choose either, integer, float, percentage, or scene units
  2. In the Range>Min and Max properties, define that start and end values of the range from which a random number will be generated.
  3. From the Generate On list, choose the condition that will cause a new random value to be generated.
  4. Wire the Random parameter’s output to any node that accepts a numerical input.

Interface

Type. Defines the type of number to be generated. Choices are integer, float, percentage, or scene units. 
Range. Sets the extents of the range from which a random value will be derived. 
Seed. If enabled, uses the seed value specified. If disabled using the global seed value defined in the General rollout.
Generate On. The condition in which a new random value will be generated. Choices are:

  • Start - Generates a new random number once for each instance of the RailClone object.
  • Segment - Generates a new random number for each individual segment.
  • X Spline Start - Generates a new random number for each spline sub-object found in the X Spline input of the Generator.
  • X Spline Section - Generates a new random number for each spline segment. For the purposes of this calculation a segment is the section of spline between two Corners or Evenly segments.
  • Array Y Row - Generates a random number at the start of each new Row. Only works in conjunction with the 2D arrays - Generator A2S

 

 

 

conditional operator

 

Arithmetic

Overview

Used to perform common mathematical operations on two or more Parameter Nodes, useful for creating complex parameterized objects using Parameter nodes wired to multiple inputs.

Usage


  1. Attach 2 or more parameter nodes to the Arithmetic node's input slots
  2. Select the equation type from the drop down list
  3. Expose the target node property by right clicking, select export and pick the value you wish to parameterise.
  4. Wire the Arithmetic output to this new slot.

Interface

Several operations are available:

Add. Returns the sum of an addition operation
Subtract. Returns the difference of a subtract operation
Multiply. Returns the product of a multiplication operation
Divide. Returns the quotient of a division operation
Maximum. Returns the larger of the input values
Minimum. Returns the less of the input values
Expression. Create equations using common functions and variables.

Expressions Editor

To add an expression, select Operation>Expression and press Edit Expression to open the Expression Editor

To create complex parametric relationships, the Expressions Editor uses a straightforward mathematical syntax comprising operators (+, -, *, /, etc.), constants (pi, e, etc.), RailClone's built-in variables, numerical inputs, and functions (including standard, trigonometric, vector, rounding, and conditional functions that take one or more arguments and return a result). To find out which built in functions, operators and constants are available, a full list is included in the Expressions Pane on the left hand side of the window. To see an explanation for each function, single click on it and a description and example syntax will display in the Expressions Help Pane at the bottom of the interface.

Interface

Expressions pane. Found on the left, lists all usable variables and functions. Double click a list item to add it to the edit window or single click to display help. 
Edit Window. Used to create and edit the expression, to see the effects of an expression press Update. To construct a variable you can either type it in manually or add variables and functions by double clicking them from the expressions list.  
Expressions Help. This window provides information about the currently selected variable or function.

RailClone 3 included a new expressions engine. Be aware that there are a couple of key changes to remember.

  • The new version uses a double == for conditional tests 
  • The way you write numbers is now important, for example in RailClone 3:

    1 = an integer
    1.0 = a float

    This means that in RailClone 3 the expressions:

    return 1/2;
    Will result in 0, because both values are integers.

    To return a float value you would use:
    Return 1.0/2.0;
  • To send a value to the arithmetic node's output you must add a return command, for example:

    return degToRad(90);


 

Using expressions to control a segment's transform properties

When using expressions to control a segment’s transform properties it is necessary to use aTransform operator. The current workflow will not allow you to connect an expression directly to a segment node.  RailClone will detect an incompatible connection and display a warning.

Expressions Syntax

Expressions use a straightforward mathematical syntax comprising operators (+, -, *, /, etc.), mathematical Functions that take one or more arguments and return a result, RC's built in variables (which we have called Attributes for clarity), user declarable Variables, and customisable Inputs.  There are many built in functions, and attributes already available and these are all documented in the Command List on the left hand side of the Expressions Editor. To see an explanation for each entry, single click on it and a description and example syntax will display in the Help pane at the bottom of the interface. General syntax rules are describe below.

Return

To send a value to the node's output you use the return command. For example: return degToRad(90);

Only one return command can be used in an expression.

Functions

Functions provide pre-built commands that can be used to perform common mathematical expressions. To use a function you use the name followed by any required arguments enclosed in parenthesis. For example, to convert 90 degrees to radians you use the degToRad function as follows:

degToRad(90);

Where a function requires multiple arguments, these should be separated using commas. For example to generate a random integer between 0 and 350 you would use the randomInt function as shown below:

randomInt(0,359);

Functions can also be nested by including them as arguments, for example:

degToRad(randomInt(0,359));

You can find a full list of supported functions, including information about the arguments they require here.

Attributes

Attributes are RailClone's pre-defined variables. Dot syntax is used to access an attribute's values. This means that when using an attribute, the statement must always start with a reference to some object, followed by a full stop (. or dot) and then the name of the property you wish to access. Each dot represents a move from more general access to the object to more specific levels of parameter detail. For example XSplineCoords refers to a vector value. Continuing down the hierarchy,  XSplineCoords.Z refers only to the Z axis.

Be aware that attributes in the Command List cannot be edited using expressions.

Variables

In addition to built-in attributes, variables can be created and edited in the expression script. They are declared as one of three types, either real for float values or scene units, int for whole numbers, or vectors. They are not case sensitive but there are a few restrictions on naming:

  • Cannot be the same as an existing attribute, function, variable or parameter.
  • Must only consist of alpha-numeric symbols and underscores (_).
  • Cannot start with a number.
  • Cannot contain spaces.
  • Variables are local to the RailClone Object, this means you can use the same variable name in different objects without problems.

Below are examples that illustrate how to create each of the three types of variable as well as illustrating some acceptable ways to construct variable names based on the rules outlined above. Green text illustrates the variable type, blue the name, and red the assigned value.

int objectCount = 3;
real object_rotate_z = 10.5;
vector objectPosition1 = [10,10,0];

 You can also create variables without assigning a value as follows:

int objectCount ;
real object_rotate_z ;
vector objectPosition1;


Once a variable has been declared, you assign a new value using
equals (=). For example  

objectCount = 5;
object_rotate_z = 22.5;
objectPosition1 = [20,20,20];

Variable types cannot be changed once created and though you can assign an integer value to a real variable , you can't assign a real value to an integer. In this case you will need to use the rounding functions ceil(), floor(), trunc(), or round() to convert the real value to an integer, for example:

int integer;
real float = 12.3;
integer = floor(float);
print integer;

If you evaluate this code then 12 will display in the output window. This is because the floor function rounds 12.3 to the lowest adjacent whole number which can then be assigned to the integer variable with no errors.

Inputs

Inputs are a special type of variable whose values are assigned in tan attached Numeric or Constant node, this enables a user to control effects without needing to understand the code. An input is named after the order in which is is attached to the Node, Input1 in the first slot, Input2 in the second and so on.

Operators

The operators described below can be used to manipulate data.

Mathematical Operators

The following arithmetic operators are supported:

Operator Example Use Description
+ p+q Addition
- p-q Subtraction
- -p Returns the negative of a variable's value

*

p * q Multiplication
/ p/q Division
^ p^q Power

Vector Operators

When using vectors the following operators apply:

Operator Example Use Description
.x V.x (eg. XSplineCoords.x) Returns the 1st component of a vector
.y V.y (eg. XSplineCoords.y) Returns the 2nd component of a vector
.z V.x (eg.XSplineCoords.z) Returns the 3rd component of a vector
+ V+W (eg. XSplineCoords+YSplineCoords) Addition
- V-W (eg. XSplineCoords-YSplineCoords) Subtraction
* V*W (eg. XSplineCoords*YSplineCoords) Dot Product
* V*p (eg XSplineCoords*5) Scalar Multiplication
/ V/p (e.g. XSplineCoords/2) Scalar Division
^ V^W (eg. XSplineCoords^YSplineCoords) Cross Product

Comparative Operators

RailClone includes an If function to allow you to create conditional rules.

This function uses the following syntax:

if(p,q,r) 

Where p is a logic test which returns q if it returns true or r if it returns false. 

To create the conditional tests for an IF function you use following operators:

Operator Example Use Description
== p==q Return true if p is equal to q
< p<q Return true if p is less than q
> p>q Return true if p is greater than q
>= p>=q Return true if p is greater than or equal to q
<= p<=q Return true if p is less than or equal to q
| p|q Return true if p or q are true
& p&q Returns true if p and q are true

Instruction separation

Each command must be terminated by a semi-colon ( ; ).

Comments

Comments are added by starting the line with a # symbol. Anything after the # on the same line will be ignored:

# This is a comment
# This is another comment

Note that comment lines do not need to be terminated with a semi-colon, though it won't affect anything if you do so.

Debugging

To help debug effects we have provided a print command that displays the results of an expression or contents of a variable, parameter or attribute to the Output window. For example

real exampleVariable = 5.0;
print exampleVariable;

will print 5.0 to the output window.

Because you are often creating scripts designed to manipulate the values on thousands of scattered items it is not possible, or desirable, to see the results for every instance. Therefore the print command displays values for only the first scattered object

Case Sensitivity

Functions, variables, properties and attributes are not case sensitive.