Waterline Real Flow Scripting

waterline magazine REALFLOW TUTORIALS BY THOMAS SCHLICK | NEXT LIMIT TECHNOLOGIES

SCRIPTING

WITH REALFLOW

Introduction to Python in RealFlow RealFlow's Scripting Editors Variables Data Types User Interfaces Coin Stacker Script Particle Swapping Colour Blending Crown Splashes Export Management Velocities Veloci ties from Ocean Statistical Spectrum Waves

CONTENTS

Welcome to waterline magazine

5

Annoations

5

What Is Scripting? The Software Development Kit (SDK) Getting Started Syntax, Syntax Errors, Indents Comments Variables Naming Data Types Integers and Real Numbers Strings Lists Accessing List Elements Looping Through List Elements Appending List Elements Counting List Elements Dictionaries Vectors Vector Maths Disassembling and Assembling Vectors Booleans Operators Conditions

7 7 8 10 12 13 13 16 16 16 17 17 17 18 18 19 19 21 22 23 23 24

RealFlow's Scripting Editors Batch Scripts Simulation Scripts Where to Add Simulation Scripts? Basic Workflows Node-Based Scripts

27 27 28 29 29 30

First Steps - Coin Stacker Coin Positions Adding Coins Changing Parameters Improvements and Suggestions

32 32 34 34 36

waterline water line magazine | magazine | Scripting with RealFlow

2

CONTENTS

First Steps - Particle Swapping Scene Setup Adding a Simulation Script Getting Emitters and Particles The Velocity Condition Randomizing the Threshold Improvements and Suggestions

38 38 39 39 41 42 43

First Steps - Colour Blending Analysing the Workflow Scene Setup Initial Variabl Variables es and Settings Getting a Particle's Neighbours Temperature Calculations

45 45 46 46 47 48

Custom-Tailored User Interfaces Custom-Tailored Coin Stacker GUI Other Field Types Particle Swapping GUI Local and Global Variabl Variables es GUIs and Lists Translating References Into Names

53 53 56 56 57 58 58

A Batch Simulation Script Initial Variables The GUI Processing the Input Values

61 61 62 63

Crown Splashes What the Script Should Do Force or Velocity? Scene Setup Defining a Ring Accelerating the Ring Particles Start and End Time Creating a Splash-Like Shape Tendril Creation Finding the Tendril Positions Circle Maths Getting the Tendril Particles

66 66 67 67 67 69 70 71 73 73 74 77


3

CONTENTS

Crown Splashes (continued) Accelerating Splashes and Tendrils Randomization Improvements and Suggestions Axis Setups

79 81 85 86

Export Path Manager Creating the GUI Evaluating the Input Changing the Export Path

88 88 89 90

Velocities Vel ocities from Ocean Statistical Spectrum Waves Definitions and Considerations Initial Velociti Velocities es Velocity Calculations Improvements and Suggestions

92 92 93 95 97


4

WELCOME

WELCOME

TO WATERLINE MAGAZINE

TO WATERLINE MAGAZINE!

Some of you might remember RF_magazine, a commercial special interest publication for RealFlow users. Although I had to discontinue this magazine I never really gave up the idea of renewing it one day. day. Now I am happy to present the first issue. Over the last years I also started several attempts with plugin development, a blog, and several free tutorials, but all this did not really satisfy me. The creation of plugins takes a lot of time, and it is actually a fulltime job. Time, I simply did not have besides my work at Next Limit Technologies. Anyway, Anyway, some of these projects and developments have found their way into this eZine, for example the crown splashes. And there is much more in my stash. In the tradition of RF_magazine this issue deals with Python scripting inside RealFlow and it is not just a copy of the old scripts and articles – it is completely new. This magazine is free, but it took me countless hours to complete it. Therefore I love to hear from you! Just drop me a line if you think this magazine is a good addition for your work. You You can also contact me if you have suggestions for upcoming issues and tutorial, or if you just want to say hello. I am always happy to get in touch with talented artists from all over the world. Your Your feedback is my motivation for creating the next issue. Enough said! Enjoy this first issue of waterline magazine. Happy reading,

Thomas Schlick


5

WELCOME

TO WATERLINE MAGAZINE

ANNOTATIONS All tutorials and scripts in this issue have been created with the latest version of RealFlow 2015. Some of the scripts and simulations can also be used with previous versions, but there is no guarantee that they will really work.

AXIS SETUP

AND SCALE

RealFlow provides the possibility of defining which axis should be the scene’s vertical axis. For some 3D programs it is Y, Y, for others it is Z. In this magazine, a Y setup is used by default, and for Z-based setups you have to swap Y and Z values. An example: •

•

•

(1.0,5.0 5.0,1.0) ,1.0) – a so-called vector. Let's say there is a scale value with three elements, e.g. (1.0, This means that the object's length and width are 1 m each, e ach, while height is 5 m. (1.0,1.0,5.0 5.0) ). With a Z-based setup, the vector must be changed to (1.0,1.0,

This notation is also interesting for scripts, because the magazine's programs are not axes-aware. You have to convert all XYZ vectors like position, velocity, velocity, force, or scale. The default scale, used in this magazine, is 1.0.

SHARING

WATERLINE MAGAZINE

There are just three golden rules – please be fair and repsect them: •

•

•

Do not share the magazine, but provide a link to waterline.tv instead. If you use the magazine's techniques and tutorials do not sell them as your own ideas. Do not translate this magazine without my permission.

Thank you!


6

HAT T IS SCRIPTING? WHA

WHAT IS SCRIPTING?

WHAT IS SCRIPTING Scripting is the development of custom tailored applications – here inside of RealFlow RealFlow.. The scripting language provides a set of statements and functions the programmer can use to solve a certain task. Scripts are normally interpreted. This means that all instructions are processed at runtime, and translated into a code the computer can understand You You know this from web browsers where the code (this is the sequence of statements in your program) is often directly visible to the user. user. At the moment a visitor calls a webpage, the code is sent to the interpreter and processed. With languages like C++ the code is preprocessed and converted into machine code. A compiled program is much faster than a script, because the compiler optimizes the code for certain hardware needs.

P Y

J S S

V B B A

C++

RealFlow uses the Python language. Python is easy to understand, supports all modern programming approaches, and has an active developer community.. It is also free, even for community commercial applications, and you have access to hundreds of free extensions – so-called libraries – for almost any need.

THE SOFTWARE DEVELOPMENT KIT When you download the Python bundle from the official website, and install it you will not find a single M E L RealFlow-related command. Python is simply not aware of RealFlow and this also applies to other applications with Python support. A program requires an extension that will make Python understand these specific commands. This interface is known as API (Application Programming Interface). This API is the basis for the Software Development Kit (SDK). The SDK contains all the application-specific commands and instructions you need for working with Python inside a program. In RealFlow the list of SDK commands can be viewed under HELP > SCRIPTING REFERENCE


8

WHAT IS SCRIPTING?

When you expand the “Scripting Reference” tree you will see a long list of keywords. Most of them sound familiar, familiar, for example “Daemon”, “HY_Bubbles”, or “Object”. Others, like “GUIFormDialog”, or “Vector”, are very abstract: These higher-ranking elements are also called classes. When you click on an entry you will see a list with commands. The commands are members of the currently viewed class. Every command provides access to one of RealFlow‘s functions. The SDK is your ticket to RealFlow‘s Python interface, and when you make your first steps with scripting, you will use the reference very often. You You will also be amazed by the number of commands and how deep you can go inside RealFlow to change and influence simulations, nodes, and parameters.

GETTING STARTED These commands open a whole new world and you can literally do everything, but the question is how? How can you do all these fancy things you have seen in simulations, or recreate the stuff you have read about? Many users have the strong conviction that it is a heavy task to get started, learn a new language, and convert ideas into code. There are also rumours that a deep knowledge of maths and physics is required. This is exactly the problem that keeps most artists away from scripting and programming. All this is only partially true. Scripts do not have to be sophisticated constructions with thousands of lines of code.


Scripted dust particles, emitted from a breaking object.

9

WHAT IS SCRIPTING?

Most scripts also do not require higher mathematics and complex functions. In fact, the big ma jority of scripts contains contains just a few lines, does not not use any maths at all, and and has been created to execute repetitive tasks, and ease your daily life. Think of scripting as a normal language. Not every sentence has to be a poem, but it is better to speak in a clear and simple way instead. Another, Another, very important, thing with scripting is the feeling of success. This feeling is exactly what keeps you motivated and lets you look for more advanced tasks. With every script you will get more routine, and a nd self-confidence. Of course, there will also be throwbacks, programs where you are not able to move forward, get stuck, or have to start from scratch. But these problems will improve your knowledge – not only about scripting, but also about fundamental processes in RealFlow. Anyway, the first steps are about the nuts and bolts, but I will keep things as easy as Anyway, a s possible and provide examples where ever they make sense.

SYNTAX, SYNTAX ERRORS, INDENTS This is perhaps the most scary word for beginners, and the term “syntax error” e rror” is a very good reason to stop reading, close Acrobat, and trash this magazine. But wait! In Python, many syntax errors have a very simple reason. Copy the first example below and start RealFlow: < py > for i in range(0, 3): scene.message("This is a message from waterline magazine.")

•

•

•

•

Hit F10 to open one of RealFlow‘s Python script editors. Paste the clipboard‘s content to the editor editor.. SCRIPT > RUN. Look at the “Messages” panel.

Congratulations! You You have just produced your first syntax error and the praised feeling of success is blown away already. I also want to welcome you to the colourful world of bug fixing ;-)


10

WHAT IS SCRIPTING?

Now,, remove the script, copy/paste the code from the next example, and execute it with “Run”: Now < py > for i in range(0, 3): scene.message("This is a message from waterline magazine.")

Take a look at the “Messages” panel, where you will see the script’s output:

The difference between both scripts are the indents and leading spaces, and this is exactly the reason for the syntax error. Python requires leading spaces and scripts with wrong indents will always fail. Especially with downloaded or copies scripts you have to be careful, and sometimes it is necessary to recreate the indents. After every colon (:) you have to add a new indent: < pseudo code > if ( condition ): statement 2 else: statement 3 loop:

statement 4 if ( condition ): statement 5 else: statement 6 statement 7

Quotation marks are another very common source of syntax errors, because Python only accepts a certain type. If the content between two quotation marks is displayed in red everything is Ok. With missing brackets it is very similar. similar. Complex commands sometimes have three or four nested brackets. If one of these brackets is missing you will get a syntax error.


11

WHAT IS SCRIPTING?

Aside from syntax errors and debugging, syntax itself plays an important role, because it is the logical structure of your program and its instructions. Every command has its own syntax and you can find it in the SDK, but I will introduce the individual components later with examples. There is not the one correct syntax. You You can build and structure the code the way you want it to be. There are many programmers out there who say that they really don’t care about highly-optimized code as long as their scripts are running. Why not? It should be fun to write a program and none of us is a professional coder. coder. Of course, there are ways to accelerate a script when you take a little time and think about it, but this feeling for the code is something that will come automatically with more practice, and also by analysing scripts from users.

COMMENTS Comments are one of the most important code elements, because they will help us to keep our scripts readable and understandable – even after months and years. A comment is a description and you should add them where ever you can. They are ignored by the Python interpreter and therefore they do not have influence on the script’s execution time. This also means that it is not possible to declare variables inside a comment, perform calculations, assemble vectors, etc. No matter what’s inside a comment – it will not be processed. A single-line comment is introduced this way – in RealFlow comments are printed in green: # This is my first comment

It is possible to add an unlimited number of comments: # This is my second comment, # and it covers three lines, # not more.

Another form are multi-line comments: """ This is my third comment. It also covers three lines, but this time it is a multi-line comment

""" If the script’s last line is a comment you will receive a syntax error.


12

WHAT IS SCRIPTING?

VARIABLES Here is the next reason for headaches: variables. Fortunately, Fortunately, the concept behind variables is very easy to understand. What make more users really desperate is the large number of different variable types and the contents they can store. Basically, Basically, a variable is nothing more than a placeholder that can be filled with a value. Think of your garage as a variable. For the garage itself it makes no difference whether you put a car, a bicycle, or your old furniture inside. But, of course it makes a huge difference for you, and you will see it when you try to ride a cupboard instead of a bike. With variables it is very similar, similar, because the variable’ variable’ss content determines its role and how it will be treated in the script. Variables have to be declared before they can be used within the program – this is also valid if the Variables variable’ss value is 0 or if it is empty at the beginning of the script. variable’

NAMING Let’s start with a simple example with three values: 27, female, Claudia. What we have to do is to Let’s set the values into a logical context to make use of them: Age = 27 Name = "Claudia" Gender = "female"

Now, the attributes make sense and you have just declared three variables. You can also see that Now, meaningful names are very important. The following variable names are valid, but it is very difficult to differentiate them within a more complex script – as shown here: A B C D

= = = =

27 "Claudia" "Beatrice" 56

Here it is difficult to find out what C and D actually stand for. Do they perhaps describe another person or something else? Here is the solving: Age Name SecondName Weight

= = = =

27 "Claudia" "Beatrice" 56


13

WHAT IS SCRIPTING?

It is important that a variable‘s name does not change during the script. Even lower and upper cases are differentiated. “Age” and “age” are not the same, but completely different variables. A variable’s variable’s value, on the other hand, can change during the execution of the script, because otherwise it is not possible to calculate with variables and get a result. A few more notes on naming: •

•

•

Allowed characters are A-Z, a-z, 0-9, and the underscore. Variables must start with a number number,, not a character Python and RealFlow’s SDK commands commands cannot be used a variable names.

When you perform a calculation or reassign the variable somewhere else in the script the old value will be overwritten: Name = "Claudia" Name = "Lydia"

If the variable’s value is printed the output will be “Lydia”.


14

DATA TYPES

DATA TYPES

ATA A TYPES DAT

It is true that the following explanations are not exactly exciting. Discussions about integers, lists, or strings are very theoretical, but they are a re absolutely essential. They are also important for the creation of custom GUIs, where we can assign initial values. In the previous chapters you have already used two data types: numbers and strings. A string can be a single character, but also a word, a sentence, or complete text from a book. Numbers, on the other hand, are subdivided into several classes like integers, reals, or complex numbers.

INTEGERS

AND REAL NUMBERS

When you take another look at the first example you will spot a difference in how the values are written: Age

= 27

Name = "Claudia" Gender = Gender = "female"

Age is treated as a number, or to be more precise: an integer, while Name and Gender are strings.

Integers are numbers like 64, 8524, -9610, or 7. When you perform calculations with integers then the result will always be an integer integer.. Real numbers are, for example, 3.1415, -0.758, 43.2, or -416.0003. This type is also called floats. When two real numbers are combined you will get a real number as well.

STRINGS Strings are always enclosed within quotation marks, and this also applies to numbers, as shown in the next example. Here, the numbers will be treated as strings, and one way to combine them is a process called concatenation. The operator is a + sign and the result is a new string: insuranceNumberClaudia = "1100" insuranceNumberLydia

= "2200"

insuranceNumberClaudia + insuranceNumberLydia = "11002200"

If you want to treat these numbers as integers you have to remove re move the quotation marks: insuranceNumberClaudia = 1100 insuranceNumberLydia = 2200 insuranceNumberClaudia + insuranceNumberLydia = 3300


16

DATA TYPES

LISTS Scalars can only store a single value, but we also need structures for multiple, maybe even millions of values. A good example are RealFlow particles. How can we access these huge amounts of data? For this purpose Python provides so-called lists. A list’s elements are always enclosed between brackets, and an empty list is declared as: emptyList = []

Here is an example with numbers: numberList = [10,20,30,40,50,60,70,80,90, [10,20,30,40,50,60,70,80,90,100] 100]

Strings are also supported, but they must be enclosed within quotation marks: stringList = ["this","list","contains","s ["this","list","contains","six","string","entries"] ix","string","entries"]

ACCESSING LIST ELEMENTS An individual element can be accessed via an internal index. This index always start with 0. In “stringList” we have seven elements, and the index ranges from 0 to 5: Value

this

l is t

contains

si x

string

entries

Index

0

1

2

3

4

5

Now we can use the index to access an element directly, directly, e.g. “contains”: listElement = stringList[2]

The result of this operation is a single value, but a list with just a single element will remain a list. LOOPING THROUGH LIST ELEMENTS

In the example above we have extracted a single element, but this is not a very efficient method with hundreds of thousands of entries. Therefore we need an instruction that will return the individual elements automatically. automatically. The following code snippet is a loop and it is one of the most fundamental actions with RealFlow and Python (see next page).


17

DATA TYPES

Always mind the leading tab. Without it you will get a syntax error and the script will not be executed): fruitList = ["peach","apple","apricot","pineapple","orange","strawberry","mango"] for element in fruitList: … print the element’s name

APPENDING LIST ELEMENTS

New elements are simply appended to an existing list as shown here: fruitList = ["peach","apple","apricot","p ["peach","apple","apricot","pineapple","orange","strawberr ineapple","orange","strawberry","mango"] y","mango"] newFruit = "lemon "lemon" " fruitList.append(newFruit) Result: fruitList = ["peach","apple","apricot" ["peach","apple","apricot","pineapple","orange","strawb ,"pineapple","orange","strawberry","mango"," erry","mango","lemon lemon"] "]

COUNTING LIST ELEMENTS

Another, often used, action is to count a list‘s number of elements – also called length – and comAnother, pare the result against a threshold. This way it is possible to trigger events within the script. If we want to know the length of the last version of fruitList we have to use the following command: numberOfListElements = len(fruitList) Result: 8

Python provides many other functions and commands in conjunction with lists, but they are not really relevant for an introduction to scripting. It is, for example, possible to use lists within a list and such an element is called a tuple. A typical application for tuples is a list with a polygon‘s vertices, but they are also often used for pairs of values, or complete data sets. Imagine you want to store a particle‘s Id and connect it with attributes like age and mass: tupleList = [(0 [(0,0.38 0.38, ,0.0004 0.0004),( ),(1 1,0.32 0.32, ,0.0004 0.0004),( ),(2 2,0.37 0.37, ,0.0004 0.0004),( ),(3 3,0.33 0.33, ,0.0004 0.0004)] )]


18

DATA TYPES

DICTIONARIES This variable type is comparable to a phone book. In contrast to lists, dictionaries do not require a specific order and there is no index for identifying an element. A dictionary uses key-value pairs instead. Similar to lists, dictionaries are declared with brackets: emptyDictionary = {}

Here is an example with names and phone numbers: phoneBook = {"Claudia":54388,"Lydia":4389 {"Claudia":54388,"Lydia":43891,"Agnes":75064,"Susan":97247 1,"Agnes":75064,"Susan":97247} }

The first entry of each pair is the key and it can be used to identify its associated value: phoneNumber = phoneBook["Agnes"] Result: 75064

As with lists, the number of key-value pairs is queried with the len command: numberOfPairs = len(phoneBook)

And here is also how to add new key-value pairs: phoneBook["Helen"] = 22972

VECTORS In 3D programs, vectors play a fundamental role: they are used to describe positions, dimensions, velocities, rotations, but also directions, and many other attributes. In RealFlow, a vector is always described through a trio of three values – one for each spatial direction (XYZ). You You can find some of the most important RealFlow vectors under a scene element's “Node” panel:


19

DATA TYPES

Velocity is a very good example for vectors, because we all have an idea of what it is. But, when we think about velocity and speed we normally have something like 10.6 m/s in mind, not a vector consisting of three values. Let me explain you the backgrounds and start with a velocity vector: velocityVector = (6.5,1.6,8.2)

What we have a here are values for X, Y, Y, and Z. In a variable-based notation, the vector can also be written as: velocityX = 6.5 velocityY = 1.6 velocityZ = 8.2 velocityVector = (velocityX, velocityY, velocityZ)

As you can see, the individual elements are single values – so-called scalars: •

•

•

The XYZ values are coordinates and determine a point in space. Now draw a line from the 3D system's origin at 0,0,0 and the velocityVector's coordinates. The direction of this line is indicated by an arrowhead.

Here is an illustration of an arbitrary 2D vector: Y

< x0,y0>

x0

d e u t i n a g m = t h n g e l

X y0

What we got now is an arrow arrow,, and this is the standard representation for vectors. The arrow does not only show the vector's direction, but its length has a certain meaning. If you measure the length you will roughly get 10.6.


20

DATA TYPES

So, a velocity vector's length, also known as module or magnitude, is what we call speed in daily life. Now you know what a vector's magnitude is, but you do not know how to get this value or how to use it. The calculation of the magnitude is done with a built-in function inside RealFlow: vectorMagnitude = vector.module()

What we get here is again a scalar and this value can be used for comparisons, e.g. for defining thresholds. It is not possible to compare two vectors against each other, other, and you cannot compare a scalar against a vector. vector. The following example notations are not allowed: allowed: if (velocityVector > positionVector) if (velocityVector == 2.5)

We always need two scalars as the example below illustrates: velocityVector = (6.5,1.6,8.2) velocityThreshold = 5.0 velocityMagnitude = velocityVector.module() if (velocityMagnitude >= velocityThreshold): … do something

VECTOR MATHS

The headline really spells trouble, but fortunately RealFlow will do all the maths for us. We can calculate with vectors in pretty much the same way as with numbers. The difference to numbers is that the result is a new vector vector.. vector1 = vector1 = (x1 (x1, , y1 y1, , z1 z1) ) vector2 = vector2 = (x2 (x2, , y2 y2, , z2 z2) )

Addition

vector1 + vector1 + vector2

Subtraction

vector1 – vector1 – vector2

Division

vector1 / vector1 / vector2

Vector multiplication multiplication has to be performed manually, because the * operator is reserved for another function – the dot product (see table next page): vector1 * vector2 = (x1 (x1 * * x2 x2, , y1 y1 * * y2 y2, , z1 z1 * * z2 z2) )


21

DATA TYPES

There are also more complex functions available, and some of them only require one vector: Cross product

vector1.cross( vector1 .cross(vector2 vector2) )

Returns a vector that is perpendicular to vector1 and vector2.

Dot product

vector1 * vector1 * vector2

Returns a single value – a scalar.

Distance

vector1.distance( vector1 .distance(vector2 vector2) )

Returns a single value – a scalar.

Normalization

vector1.normalize() vector1 .normalize()

Returns a vector with a magnitude of 1.

Magnitude

vector1.module() vector1 .module()

Returns the length of the vector. vector.

Scaling

vector1.scale(factor) vector1 .scale(factor)

Multiplies each component with the factor in brackets and returns a vector vector..

DISASSEMBLING AND ASSEMBLING VECTORS

In this last chapter about vector we want to take a closer look at how to disassemble a vector and get its XYZ components, but also how to combine three values to finally get a new vector. vector. Let's stay with our already introduced velocityVector and extract the individual elements: velocityVector velocityX velocityY velocityZ

= = = =

(6.5,1.6,8.2) velocityVector.getX() velocityVector.getZ() velocityVector.getZ()

A different notation is: velocityX = velocityVector.x velocityY = velocityVector.y velocityZ = velocityVector.z

With these separated values we are able to perform any operation, swap components, or leave certain elements untouched. We can do comparisons between another scalar and a single element, and so on. Once the components are defined they can be used to create an new vector: newVelocityVector = Vector.new(velocityNewX, velocityNewY, velocityNewZ)

This notation is also often used to introduce a standard vector, e.g. a null vector or a reference vector: nullVector = Vector.new(0,0,0) referenceVector = Vector.new(0,1,0)


22

DATA TYPES

BOOLEANS This is the last data type we have to discuss, and fortunately it will not take very long. With Booleans we can differentiate between true and false. These states represent yes and no, and they are used like a switch. A typical field of application is a script where the user is asked whether the scene objects' active rigid body property should be enabled or not. Another common application is the creation of so-called flags. A flag indeed acts as a switch and can be used to trigger events. RealFlow's “Visibility” “Visibility” option is another example for Booleans. Instead of the option's “Yes” and “No” states, we have to use “true” and “false”.

OPERATORS Operators are necessary to perform calculations and comparisons. Here are the most important arithmetic operators: Addition

+

15 + 1 7 = 3 2

Subtraction

-

64 - 3 0 = 3 4

Multiplication

*

10 * 12 = 120

Division

/

80 / 1 0 = 8

Exponentation

**

12 ** 2 = 144

Modulus

%

28 % 7 = 0

String concatenation

+

"John" + "Doe" = "JohnDoe"

String repetition

*

"Hi" * 3 = "HiHiHi"

There are also operators for incrementing an existing value. Here, the old/existing value is stored and we can add a new value, for example. In the next cycle this result will be used as the old value, and the increment is added again: +=

value = value + increment

-=

value = value - increment

*=

value = value * increment

/=

Value = value / increment


23

DATA TYPES

A list with comparison operators: Less than

<

Greater than

>

Less than or equal to

<=

Greater than or equal to

>=

Equal

==

Not equal

!=

Finally,, there are Boolean operators: Finally and or and

CONDITIONS Conditions are comparable to decisions. In programs this decision is made by comparing one or more values with an operator operator.. A condition is introduced with an if statement: if (particleVelocity > 5.0): … do something

It is also possible to compare against more than one value. This is often used to define ranges: if (particleVelocity >= 5.0 and particleVelocity <= 10.0): … do something

Another way is to perform the comparison with the “or” operator: if (particleVelocity <= 2.0 or particleVelocity >= 5.0): … do something

You can also define an alternative case or trigger another event with the “else” statement: if (particleVelocity < 5.0): accelerate particle else: stop particle emission


24

DATA TYPES

Sometimes you have to check for an exact value: if (currentTime == 2.5): … do something

Even calculations can be performed within in a condition: if (particleVelocity > velocityThreshold + randomVariation): … do something

Comparisons with Boolean variables are also allowed – quotation marks are not allowed here: if (objectVisibility == True): … do something


25

REALFLOW'S SCRIPTING EDITORS


REALFLOW'S SCRIPTING EDITORS Editors? Python is a universal programming language and why do we need several editor types to write scripts? Despite the universal approach the various applications with Python support have to follow the given syntax. RealFlow is now exception, but it makes a huge difference when and where a script is executed. Scripts can be run “offline” to make initial adjustments, create objects and scene nodes, change parameters, or open a GUI. Other scripts are used to manipulate fluids or the path of objects, and we can write our own daemons and RealWave deformers. RealFlow provides different editors, but the syntax, rules, and conventions are the same throughout all editors.

BATCH SCRIPTS This script type is mainly used for repetitive tasks. Typical applications are: •

•

•

•

•

•

•

•

•

Changing large amounts of parameters. Creating GUIs for initial user settings. Conversions, e.g. when animation curves are translated into splines. Building stacks, towers, or walls. Creating and manipulating objects. Setting up scenes with initial parameters. Manipulating export resources. Normalization of parameters. And many more.

In order to write and run those scripts you have to use RealFlow's “Batch Script” editor: LAYOUT > BATCH SCRIPT (F10)

You can open and use as many batch script editors as required. Batch scripts can also be attached to RealFlow's shelves and even embedded to use them in the same way as built-in commands.


27


SIMULATION SCRIPTS As the headline indicates, these scripts are created to influence simulations. One of the bestknown applications with this script type is particle swapping to simulate foam, but that is by far not everything. Here a few more suggestions: •

•

•

•

•

•

•

Melting, deforming, freezing. Foam creation on RealWave surfaces. Wet-dry map creation. Splash creation. Particle tracking. Emission of dust particles. Colour blending between particles.

Simulation scripts are executed within RealFlow's “Simulation Flow” environment: LAYOUT > SIMULATION FLOW (CTRL/CMD + F2)

Here you will find an events tree and scripts are attached to the tree's branches, e.g. “FramesPre” or “StepsPost”: •

•

Right-click on an event, e.g. "FramesPre", and choose “Add Script”. RealFlow adds a new tab with a Python editor.


28


You can also see a “Master” tab with several entries and functions. This tab is only there for compatibility reasons with RealFlow 4. Many old scripts still use the “Master” tab's structure, but it is really outdated. New scripts should always be applied to the events tree. WHERE TO ADD SIMULATION SCRIPTS

The most common question with simulation scripts is where to add them? With “SimulationPre” and “SimulationPost” it is pretty clear: these sections will only be executed once at the beginning and at the end of a simulation. “SimulationPre” is often used to initialize variables, add certain properties to particles (e.g. temperature), or gather objects for later usage. Scripts, located under “FramesPre” and “FramesPost” are executed once at the beginning or at the end of a frame during simulation.

When your script is executed under “StepsPre” or “StepsPost” it will be executed once per substep. RealFlow uses adaptive substeps, so in the worst case, it might happen that the script is executed several hundred times per frame. With large amounts of particles or complex calculations a simulation will become very slow. It is therefore a good idea to execute your scripts in the frames section whenever possible – at least for testing purposes. If the result does not satisfy your requirements you can shift the script to “StepsPre” or “StepsPost” for increasing precision. BASIC WORKFLOWS

You can add as many scripts as required. Just right-click on the appropriate event, and choose “Add Script”. If you have scripts stored on your hard disk or network drives it also also possible to load them with “Add Script From File”. The checkboxes allow you to activate and deactivate a script on demand, and scripts can be shifted from one event to another with drag and drop.


29


NODE-BASED SCRIPTS RealFlow provides the possibility of creating your own RealWave deformers, standard particle fluid solvers, and custom daemons. Each node has its own scripting editor and there you will find several predefined sections. These sections have names like def applyForceToBody( body ) or def computeInternalForces( emitter ), and they tell you where you have to put your script in order to influence a certain node type. If you want to write a •

•

•

daemon for MultiBodies put your script under def applyForceToMultiBody( multibody ). custom wave deformers use def updateWave( vertices, initPositions ). etc.

The individual editors can be found here: Scripted daemon

DAEMONS SHELF > SCRIPTED > NODE PARAMS > SCRIPTED > EDIT

Scripted RealWave deformer

REALWAVE NODE > RIGHT-CLICK > ADD WAVE > SCRIPTED

Scripted standard particle fluid

EMITTER NODE > NODE PARAMS > PARTICLES > TYPE > SCRIPT


30

FIRST STEPS COIN STACKER

FIRST STEPS – COIN STACKER

GETTING STARTED - COIN STACKER SCRIPT Different programs have different axis setups: some applications use the Y axis as the vertical axis, others have a Z setup. RealFlow provides functions for detecting the scene's axis setup, but these methods will be addressed later later.. For now, please change RealFlow's axis setup se tup to File | RealFlow > Preferences... > General > Axis setup > YXZ (Lightwave, cinema 4D) Enough theory! Let's start with something practical and write a batch script where we build a tower made of coins. This appears to be a manageable task and we can go ahead with our variable definitions. In this first version we need the following information: •

•

•

Number of coins Coin's height (“thickness”) Coin's diameter

Open the “Batch Script” editor with F10 and type: < py > numberOfCoins = 7 coinHeight = 1.0 coinDiameter = 1.5

These variables can be adjusted to our needs and changed freely, but for our basic considerations it is better to have something catchy. catchy. Are you able to determine the variables' data types already?

COIN POSITIONS When a new object is added to a scene it is positioned at the scene's origin at < 0,0,0 >. When cylinders are created they are placed at exactly the same position, but we want to stack the coins. Therefore we have to find out the vertical position for each individual coin. The first coin should be aligned with the scene's horizontal XZ plane (mind the axis setup!), and the others will be stacked on top of this object. Our task is now to find a vertical offset – here: along the Y axis – that will be applied to the coins.


32


An illustration will help us to find this offset:

7.0 6.5 6.0 5.5 5.0 4.5 4.0 3.5 3.0 2.5 2.0 1.5 1.0 0.5

1.0

From the illustration we can see that there is a common calculation rule: offset = offset = (coin number - 1) * 1.0 + 0.5

Let's check if this is formula is correct: Coi n # 1

Coin #2

Coin #3

Co i n # 4

Coin # 5

Coin #6

Coin #7

0 * 1.0 + 0.5

1 * 1.0 + 0.5

2 * 1.0 + 0.5

3 * 1.0 + 0.5

4 * 1.0 + 0.5

5 * 1.0 + 0.5

6 * 1.0 + 0.5

0.5

1.5

2. 5

3. 5

4.5

5.5

6. 5

The vertical positios we get here are a re exactly the same as in the illustration. But what do the values 1.0 and 0.5 represent? They stand for coinHeight and coinHeight / 2. Now we have everything for a variable-based formula: offset = offset = (coinNumber – 1) * coinHeight + coinHeight / 2


33


ADDING COINS In the next steps, the coins are created. We will position the coins using our offset formula and we also have to scale them accordingly. For this task a loop is added – something that has been introduced in the chapter about lists. There, a loop was used to go through a lists individual elements. Although we do not have a list here, the concept is the same. A loop is introduced this way: for currentNumber in range(start, stop):

A good idea is to start the loop with 0, not 1, because this has advantages: •

•

•

List indices always start at 0 and this makes it easier to find a specific elements. Particle Ids also start with 0. Therefore we can replace (coinNumber – 1) through coinNumber.

< py > for coinNumber in coinNumber in range(0, numberOfCoins numberOfCoins): ): coin = scene.addCylinder(50,1)

This code segment will add numberOfCoins cylinders. As you can see the cylinder object is stored in a variable named coin. With each cycle of the loop coin will be overwritten and contains the next cylinder.. The good thing is that RealFlow does not just store the object, but we also have direct cylinder access to all of its properties, like position and scale. The numbers in brackets – 50 and 1 – are called arguments, and define the cylinder's facets and number of height segments. This way it is possible to increase the cylinder's resolution and make it smoother. smoother. 50 facets are a good value.

CHANGING PARAMETERS It is time to create the coins' position and scale vectors. This means that we have to replace the cylinders' default parameter settings with our calculated values. For this purpose, RealFlow provides a very convenient method to access any parameter of an object. It is possible to read a value and overwrite it. The commands are: getParameter(name getParameter( name) ) setParameter(name setParameter( name, , value)


34


The name argument is just the parameter's name as it appears in a node's “Node Params” sections. Since a parameter's name is a string it has to be enclosed between quotation marks. If you set a value RealFlow does not only require the parameter's name, but also the new value itself. Here you have to take care about the value's data type (integer, (integer, list, vector, etc.). In this script, only the setParameter command is required and the new value is a position vector: •

•

the horizontal components X and Z are 0 offset represents the current Y value.

We already know how to assemble a new vector: positionVector = positionVector = Vector.new(0, offset offset, , 0)

It is also possible to assemble the scale vector, vector, because we already have the required data: scaleVector = scaleVector = Vector.new(coinDiameter, coinHeight, coinDiameter)

These two vectors will now substitute the current values. The order of the script's instructions is important. In the first step, the object is created and then we start to modify its properties using the calculated values. Here is the entire script: < py > numberOfCoins = 7 coinHeight = 1.0 coinDiameter = 1.5 for coinNumber in range(0, numberOfCoins): coin = scene.addCylinder(50,1) offset = offset = coinNumber * coinHeight + coinHeight / 2 positionVector = Vector.new(0, offset positionVector = offset, , 0) scaleVector = Vector.new(coinDiameter, coinHeight, coinDiameter)

coin.setParameter("Position", positionVector positionVector) ) coin.setParameter("Scale", scaleVector scaleVector) )

Now you can enter different initial values and execute the script with BATCH EDITOR > SCRIPT > RUN.


35


IMPROVEMENTS

AND SUGGESTIONS

This is a very basic script and there is much room for improvements – even for scripting novices. Here are few suggestions: •

•

•

•

•

Translate the script for a Z setup. Make the tower stand on a ground cube. Activate the coins' “Active rigid body” property. property. Use cubes instead of cylinders. Rotate each cube around the vertical axis using this formula: coinNumber * 10

The result of the Coin Stacker script in RealFlow's viewport.


36

FIRST STEPS PARTICLE SWAPPING

FIRST STEPS – PARTICLE SWAPPING

PARTICLE SWAPPING Although the Coin Stacker script contains just a few lines it already uses many of the concepts we need for most of our scripting tasks: •

•

•

•

•

Variable definitions Loops Create (or read out) scene nodes Manipulate values Write back the new values

With the following script we will make use of these concepts again. Particle swapping scripts have been discussed in many other publications, and there are also lots of free scripts available, but it is still a very good example for beginners. Particle swapping is used to separate particles, for example if you want to simulate foam. The idea is to measure one or more attributes of a fluid's particles, and compare them against a threshold. As soon as an attribute's value is greater than the associated threshold, the particle will be moved to a second emitter. Simultaneously, Simultaneously, the particle will be removed from the source emitter. This is exactly the main principle behind the “Filter” daemon, but scripting gives us a few more possibilities, e.g. for combining multiple thresholds in a single script.

SCENE SETUP We need a standard particle emitter, emitter, e.g. “Circle”, and a “Container” node. Both emitters must have exactly the same “Resolution”, otherwise the simulation will become unstable. Then, a glass or bin is added to catch the fluid. A “Vase” node is perfectly suited, but we will add this node with a script: Press F10 for a batch script editor and enter the following line of code: < py > scene.addVase(75,1,2.0)

The idea is to create an object with a higher resolution than the default node, and we did the same in the Coin Stacker script. Scale the vase if necessary.


38


Now we only need a “Gravity” and “k Vol Volume” ume” daemon to remove escaping particles. Close the batch script window without saving.

ADDING A SIMULATION SCRIPT This time, our script will be added to the “Simulation Flow” window: •

•

•

•

Press CTRL/CMD + F2 to open it, right-click on “FramesPre”, and choose “Add Script”. You will see something like “Script_embedded_407862257”. Right-click on this entry, choose “Rename”. Enter “Particle Swapping Script”.

Now we can start with the script. The first task is to define initial variables, get access to the emitters and their particles, and to specify specify,, which fluid attribute we want to use to filter the particles. For this purpose, a threshold is also required. Standard particle fluids provide almost a dozen channels, but velocity seems to be good for a first test. If necessary we can test against other channels later as well, and introduce additional thresholds.

GETTING EMITTERS

AND PARTICLES

We start with the velocity threshold (the value can be changed at any time). Then, there are two emitters, but we only have to gather the particles from “Circle01”, because “Container01” will receive the filtered particles. To do this, “Container01” has to be present in our script as well. Emitters are scene elements: < py > velocityThreshold = 7.5 waterEmitter

= scene.get_PB_Emitter("Circle01")

foamEmitter

= scene.get_PB_Emitter("Container01")

“PB” stands for particle-based, and if you change the emitters' names in the scene you also have to change their names in the script. What we will be doing now is to get the “Circle01” emitter's particles and loop through them. Within this loop, the particles' velocities are read and compared against the threshold.


39


The particles are stored in a list: particleList = particleList = waterEmitter.getParticles( waterEmitter.getParticles() )

As in the Coin Stacker script we create a loop where we have access to every particle. This time, the script will not go through a user-defined range, but loop through particleList: for particle in particleList particleList: : … get velocity and compare against velocityThreshold

THE VELOCITY CONDITION If we want to read out parameters from objects, daemons, emitters, and other scene nodes the “getParameter(name)” command is used. All we have to do is to enter the parameter's name and store it as a variable. With particles it is different, because attributes like velocity, vorticity, vorticity, age, etc. are not parameters, but channels, and they are accessed directly with appropriate commands: getVelocity() getVorticity getAge()

The entire bandwidth of particle channels can be accessed this way – something that also applies to Hybrido and Dyverso (RF2015) particles; for object vertices, getVelocity() is available too. A particle should be shifted if its speed is equal to or greater than velocityThreshold: < pseudo code > for particle in particleList: particleVelocity = particle.getVelocity() if (particleVelocity >= velocityThreshold velocityThreshold): ): … shift particle to “Container01”

Did you spot the error in the code segment above? The condition will not work, but why? The answer is that particleVelocity is a vector and it is not possible to compare vectors against real numbers. We need the vector's magnitude for this job.


40


So, the correct version is < pseudo code > for particle in particleList: particleVelocity = particle.getVelocity() particleVelocityMagnitude = particleVelocityMagnitude = particleVelocity.module() if (particleVelocityMagnitude (particleVelocityMagnitude >= >= velocityThreshold velocityThreshold): ): … shift particle to “Container01”

I have added this bug as a reminder, reminder, to tell you once more how important it is to understand data types. Finally, Finally, there has to be a function to identify the particle we want to remove. This can be done via the particle's Id Id:: < py > velocityThreshold = 7.5 waterEmitter = scene.get_PB_Emitter("Circle01") foamEmitter = scene.get_PB_Emitter("Container01") particleList

= waterEmitter.getParticles( waterEmitter.getParticles() )

for particle in particleList: particleVelocity = particle.getVelocity() particleVelocityMagnitude = particleVelocity.module() if (particleVelocityMagnitude (particleVelocityMagnitude >= velocityThreshold): particlePosition = particle.getPosition() particleId = particle.getId() foamEmitter.addParticle(particlePosition, foamEmitter.addParticle(parti clePosition, particleVelocity)

waterEmitter.removeParticle(particleId) waterEmitter.removeParticle(particleId )

Our Particle Swapping script is ready now and can be tested with different emitter “Speed” values, and thresholds. If you want to separate water and foam visually just assign another colour the “Container01” node: CONTAINER01 > NODE PARAMS > NODE > COLOR


41


RANDOMIZING

THE THRESHOLD

Now we want to randomize the threshold. This process is a very important concept with scripting and in most cases your results will look better and more natural. We only have to add a few lines and the most important code segment is: import random

This line has to be put at the beginning of the script. Python has no built-in functions for random numbers, but some clever guy has written a so-called module or library to fix this issue. Python comes bundled with several dozens of modules. With the import command, the module is loaded once and then kept. “random” provides a long list of types, but in most cases you will only need: random.randint(a, b) random.uniform(a, b)

The random number will be something between a and b. You You can use positive and negative values for a and b. So, what we do is to create a new random number for every particle and add it to the threshold. < py > import random velocityThreshold = 7.5 waterEmitter = scene.get_PB_Emitter("Circle01") foamEmitter = scene.get_PB_Emitter("Container01") particleList

= waterEmitter.getParticles( waterEmitter.getParticles() )

for particle in particleList: particleVelocity = particle.getVelocity() particleVelocityMagnitude = particleVelocity.module() velocityVariation

= random.uniform(-0.25, 0.25)

if (particleVelocityMagnitude (particleVelocityMagnitude >= velocityThreshold + velocityVariation velocityVariation): ): particlePosition = particle.getPosition() particleId = particle.getId()

foamEmitter.addParticle(particlePosition, particleVelocity) foamEmitter.addParticle(particlePosition, waterEmitter.removeParticle(particleId)


42


Left image: velocityThreshold = 6.0, no random variation. Right image: velocityThreshold = 6.0, random variation between -1.0 and 4.0

IMPROVEMENTS

AND SUGGESTIONS

Particle Swapping can be seen as the core of a whole series of foam-creation scripts. Nice additions are: •

•

•

Add pressure, density, and age filters. Turn particles colliding with the vase into foam and shift them to “Container01”. Synchronize the emitters' "Resolution" parameters automatically.


43

FIRST STEPS COLOUR BLENDING

FIRST STEPS – COLOUR BLENDING

COLOUR BLENDING The next example will be more challenging. In this script we want to create a smooth colour blending effect from mixing particles. The original idea has been developed by Karl Richter Richter,, a TD from Portland/Oregon. On his Vimeo account he also shares results of this technique together with some information about how the effect has been achieved. From this description, I recreated the following script. Here is Karl's original text: “I made a script to set one fluid's temperature to 1 and the other to 0. By averaging the temperature of each particle with some of its neighbors, this creates smoothly mixing colors.” It seems as if there is not very much information, but in fact we have almost everything we need to get a nice colour blending effect. The temperature channel can be used, because it is only relevant for gas particles: •

•

•

•

•

•

Get two standard particle fluid emitters and their particles. Loop through the particles. Set the values of the temperature particle channels to 0 (emitter1) and 1 (emitter2). Get a particle's neighbours. Sum up the neighbour's temperatures and calculate an average. Write back the average temperatures.

ANALYSING

THE WORKFLOW

This is a good recipe – although it is not 100% complete, because one important piece of information is missing. Before we start scripting it is necessary to find out where the problem lies. Reading out the emitters, storing the particles in lists, and creating loops are standard actions we know from the Particle Swapping script already. The difference is that we have to do this twice this time. So, the crucial point must be in the loop: We set temperature values (0 and 1), calculate new temperatures, and write them back to the particles. This is done with every frame and the consequence is that this new value will be overwritten with the next frame – the calculated value will be lost. But, how can we solve this problem? The solution is particle swapping. We need a modified version of our last script and introduce a third emitter (“Container01”).


45


SCENE SETUP The setup I have chosen here is almost the same as with the Particle Swapping script. The only change is a second “Circle” emitter. I also rotated the “Circle” emitters a little. The “Container01” node can be kept. Only the emitters are visible in this image:

Our script has to be added to the “Simulation Flow” window: •

Open it with CTRL/CMD + F2, right-click on “FramesPre”, and choose “Add Script”.

INITIAL VARIABLES

AND SETTINGS

Of course we need access to the two emitters and its particles, because we have to loop through them to do the temperature magic. And this time we really have to go through all emitters. < py > emitter1 = scene.get_PB_Emitter("Cir scene.get_PB_Emitter("Circle01") cle01") emitter2 = scene.get_PB_Emitter("Circle02") scene.get_PB_Emitter("Circle02") emitter3 = scene.get_PB_Emitter("Con scene.get_PB_Emitter("Container01") tainer01") particleList1 = emitter1.getParticles() particleList2 = emitter2.getParticles()


46


We can loop through a list's elements with a simple expression – here for particleList1: for particle1 in particleList1: … do something here

The trick is to create a new particle with the position and velocity vectors from the circle emitter's particles and store it. Then, the temperature value is applied to the new particle, and the original particle is removed from “Circle01”. Temperature is a particle channel, and we have direct access to this attribute with setTemperature(float). We also know the temperatures already. So, let's complete the first loop – the second loop uses particleList2, particle2, and setTemperature(1.0): < py > for particle1 in particleList1: particle1Position = particle1.getPosition() particle1Velocity = particle1.getVelocity() particle1Id = particle1.getId()

newParticle = emitter3.addParticle(particl emitter3.addParticle(particle1Position, e1Position, particle1Velocity) newParticle.setTemperature(0.0)

emitter1.remove(particle1Id)

GETTING A PARTICLE'S NEIGHBOURS Maybe you have asked yourself why particleList3 has not been defined so far? The answer, why we have to do this now is that we have to wait for the particle swapping event, because otherwise particleList3 will remain empty: particleList3 = emitter3.getParticles()

And we are ready to loop through the new list. Before we proceed we should take a look at the particle3's 's neighbours next steps. As written in the introduction (the “recipe”) we have to find particle3 and get their temperature values. By default, these values are 0 and 1. So we need another two variables, and these new variables have to be introduced within the loop, because they will be reset with every new particle from the list (please go the next page for the code).


47


< py > for particle3 in particle3 in particleList3: temperatureCurrent = 0 temperatureAverage = 0 neighbourParticleList = particle3 particle3. .getNeighbors(0.1) temperatureCurrent

= particle3.getTemperature()

The argument in getNeighbors(0.1) is the function's search radius All neighbours within this radius will be added to the list. With higher values the effect will turn out smoother, but simulation time will increase as well – 0.1 m is sufficient. It is possible to initialize this value as a variable.

TEMPERATURE CALCULATIONS The structures of neighbourParticleList and particleList1/2 are exactly the same, but we need one more indent: < pseudo code > for particle3 in particleList3: ... get neighbours and temperatures for neighbourParticle in neighbourParticleList neighbourParticleList: : … sum up all temperatures … calculate an average temperature … set the new average temperature

What we have here is a nested loop, and these loops can be very slow. Imagine a particle with 15 neighbours. The script has to process these 15 neighbours particles before it can proceed with the next particle from the main list, find its neighbours, go through them again, and so on. In order to calculate an average temperature we have to sum up the individual temperature values within the loop. This is a typical field of application for an increment operator. The average temperature is the result of a simple calculation: temperatureAverage = total temperature of all neighbor particles / number of neighbor particles


48


Before the loop starts we also check if neighbourParticleList contains any particles at all: < py > if (len(neighbourParticleList) > 0): for neighbour in neighbourParticleList: temperatureCurrent += neighbour.getTemperature() temperatureAverage

= temperatureCurrent / (len(neighbourParticleList) + 1)

Do you remember the chapter about lists, where we were talking about how to get the number of list elements? The key was the len(list) command. The reason, why we add 1 to the number of neighbour particles is that we also have to include the “seed” particle (= particle3). Finally, the new temperature value will be written to the neighbour particles and the currently Finally, processed particle3. In other words: we need another loop. < py > for neighbour in neighbourParticleList:

neighbour.setTemperature(temperatureAverage) particle3.setTemperature(temperatureAverage)

That's it! This is the complete script and it is a very nice example how we can achieve interesting results with standard procedures and some basic maths. Finally we have to find a way to visualize the result: •

•

Make “Circle01” and “Circle02” invisible. CONTAINER01 > NODE PARAMS > DISPLAY > PROPERTY > TEMPERATURE

The fluid's temperature channel can be mapped to particles meshes, and finally rendered.


49


< py > searchRadius

= 0.1

emitter1 emitter2 emitter3

= scene.get_PB_Emitter("Cir scene.get_PB_Emitter("Circle01") cle01") = scene.get_PB_Emitter("Cir scene.get_PB_Emitter("Circle02") cle02") = scene.get_PB_Emitter("Con scene.get_PB_Emitter("Container01") tainer01")

particleList1 = emitter1.getParticles() particleList1 = particleList2 = particleList2 = emitter2.getParticles() for particle1 in particle1 in particleList1 particleList1: : particle1Position = particle1 particle1.getPosition() .getPosition() particle1Velocity = particle1 particle1.getVelocity() .getVelocity() particle1Id = particle1 particle1.getId() .getId() newParticle = emitter3.addParticle(partic emitter3.addParticle(particle1Position, le1Position, particle1Velocity)

newParticle.setTemperature(0.0) emitter1.removeParticle(particle1Id)

for particle2 in particle2 in particleList2 particleList2: : particle2Position = particle2 particle2.getPosition() .getPosition() particle2Velocity = particle2 particle2.getVelocity() .getVelocity() particle2Id = particle2 particle2.getId() .getId() newParticle = emitter3.addParticle(partic emitter3.addParticle(particle2Position, le2Position, particle2Velocity)

newParticle.setTemperature(1.0) emitter2.removeParticle(particle2Id)

particleList3 = particleList3 = emitter3.getParticles() for particle3 in particle3 in particleList3 particleList3: : temperatureCurrent = 0 temperatureAverage = 0 neighbourParticleList = particle3 particle3.getNeighbors(searchRadius) .getNeighbors(searchRadius) temperatureCurrent = particle3 particle3.getTemperature() .getTemperature()

for neighbour in neighbour in neighbourParticleList neighbourParticleList: : temperatureCurrent += neighbour.getTemperature() if (len(neighbourParticleList (len(neighbourParticleList) ) > 0): temperatureAverage = temperatureCurrent / (len(neighbourParticleList (len(neighbourParticleList) ) + 1)

for neighbour in neighbour in neighbourParticleList neighbourParticleList: : neighbour.setTemperature(temperatureAverage)

particle3.setTemperature(temperatureAverage)


50

Particle view of the fluid with blended colours. The emitter's "Temperature" "Temperature" channel is active here.

Mesh with enabled "T "Temperature" emperature" channel in RealFlow's viewport.

CUSTOM-TAILORED USER INTERFACES


CUSTOM-TAILORED USER INTERFACES So far we have defined our initial variables and values at the beginning of script. This is also the place where they have to be changed – they are hardcoded. A much more convenient and fashionable way is to create an input mask with parameters and default values – a GUI. RealFlow's Python SDK provides a set of commands for creating GUIs and processing the settings. The best place for a GUI is a batch script that is attached to one of RealFlow's shelves. From there, the input values are transferred to another script, and used for the simulation or a batch job. Defining GUI values requires knowledge about data types (reals, list, vectors, etc.), because an input value's data type has to be determined before it can be processed. The procedure of creating GUIs is always the same: •

•

•

•

Define the GUI's input fields, names, and default values. Wait for the user's input. Read the input values from the fields and translate them into variables. Transfer the variables and values to another script or different parts of a script.

COIN STACKER GUI In the first example we want to create a GUI for the Coin Stacker batch script. There, we have three variables – one integer and two real numbers, also called floats, and we want to make them user-definable. These are the variables and they do not have to be added to the new script, becasue they will not be fixed anymore, but user-controlable: numberOfCoins = 7 coinHeight = 1.0 coinDiameter

= 1.5

Our first action is to initialize the GUI with the following command: < py > guiForm = GUIFormDialog.new()

In the second step, the input fields, their names, and default values are added to the GUI dialogue.


53


For this action, a fixed notation is required where the value's data type is included: < py > guiForm.addIntField("Number of coins", guiForm.addIntField("Number coins", 7) guiForm.addFloatField("Coin guiForm.addFloatField(" Coin height", height", 1.0) guiForm.addFloatField("Coin guiForm.addFloatField(" Coin diameter", diameter", 1.5)

The strings between the quotation marks do not represent the variables' names, but the names of the input fields, comparable to RealFlow's parameter names. These names have to be unique. Here is a preview of our GUI in RealFlow 2015:

Once we have made our settings we can process the values. This part is introduced with the statement below. The if condition is often used to write out a message, for example when the GUI has been closed with the “Cancel” button: < pseudo code > if (guiForm.show() == GUI_DIALOG_ACCEPTED): … read the field values and store them in variables (see below) … proceed with the script's functions else: scene.message("The script has been cancelled.")

Reading the field values always follows the same scheme. The T he data type does not play anymore role here, because it has been introduced with the creation of the GUI already. already. This is also the moment where the actual variable names will be used, as you will see on the following page.


54


Please double-check if the strings here are exactly the same as in the add...Field() commands, because otherwise you will receive a syntax error: < py > if (guiForm.show() == GUI_DIALOG_ACCEPTED): numberOfCoins = guiForm.getFieldValue(" guiForm.getFieldValue("Number Number of coins") coins") coinHeight

= guiForm.getFieldValue(" guiForm.getFieldValue("Coin Coin height") height")

coinDiameter

= guiForm.getFieldValue(" guiForm.getFieldValue("Coin Coin diameter") diameter")

Now that we have completed the definition of variables we can add the rest of the Coin Stacker script. < py > numberOfCoins = 7 coinHeight = 1.0 coinDiameter = 1.5 guiForm

= GUIFormDialog.new()

guiForm.addIntField("Number of coins", guiForm.addIntField("Number coins", 7) guiForm.addFloatField("Coin guiForm.addFloatField(" Coin height", height", 1.0) guiForm.addFloatField("Coin guiForm.addFloatField(" Coin diameter", diameter", 1.5) if (guiForm.show() == GUI_DIALOG_ACCEPTED): numberOfCoins = guiForm.getFieldValue("Num guiForm.getFieldValue("Number ber of coins") coinHeight = guiForm.getFieldValue("Coi guiForm.getFieldValue("Coin n height") coinDiameter

= guiForm.getFieldValue("Coi guiForm.getFieldValue("Coin n diameter")

for coinNumber in range(0, numberOfCoins): coin = scene.addCylinder(50,1) offset = coinNumber * coinHeight + coinHeight / 2 positionVector = Vector.new(0, offset, 0) scaleVector = Vector.new(coinDiameter, coinHeight, coinDiameter) coin.setParameter("Position", positionVector) coin.setParameter("Scale", scaleVector) else: scene.message("The script has been cancelled.")


55


OTHER FIELD TYPES

So far we have been working with integers and float/reals, but there are more data types: addIntField() addFloatField() addStringField() addListField() addVectorField() addBoolField()

We also have fields for adding files, directories, or choosing scene nodes: addFileField() addDirectoryField() addObjectField()

PARTICLE SWAPPING GUI In this example we want to create a GUI for the Particle Swapping simulation events script. The GUI part will be a batch script ( F10). Again, the input values are read out, and stored as variables, but then they have to be transferred to the events script. The initialization of the GUI is the same as before. < py | batch > guiForm = GUIFormDialog.new() guiForm.addFloatField("Velocity guiForm.addFloatField("Vel ocity threshold", 2.5) if (guiForm.show() = GUI_DIALOG_ACCEPTED): velocityThreshold = velocityThreshold = guiForm.getFieldValue("Velocity threshold") else: scene.message("The script has been cancelled.")

The GUI's velocityThreshold will replace the original definition we had at a t the beginning of the simulation events script. This variable has to be removed, because it will simply overwrite the GUI value. Now, Now, we can start the simulation, but we receive an error telling us that velocityThreshold is not defined. What went wrong here? It is obvious that the variable has not been transferred.


56


LOCAL AND GLOBAL VARIABLES velocityThreshold has been declared as a so-called local variable. This means that it can only be used locally within the GUI batch script. If we try to use velocityThreshold somewhere else we

will receive an error. error. We need a method to make the variable global and available to the simulation events script as well. For this purpose, the SDK provides a dedicated pair of functions: setGlobalVariableValue(string, setGlobalVariableValue(str ing, any) getGlobalVariableValue(string)

Both commands are members of the “scene” class. The string is the variable's name as it appears in the script, but set between quotation marks – "velocityThreshold velocityThreshold" ". “any” tells us that we can declare any variable, or better: data type, as global. Our GUI script has to be extended by the following line: < py | batch > if (guiForm.show() = GUI_DIALOG_ACCEPTED): velocityThreshold = guiForm.getFieldValue("Velo guiForm.getFieldValue("Velocity city threshold")

scene.setGlobalVariableValue("velocityThreshold", scene.setGlobalVariableValue("velocityThreshold ", velocityThreshold velocityThreshold) )

You might ask why velocityThreshold appears twice in the global variable's argument? •

•

•

In the first case it is treated as a string and it is the name of the variable. In the second case we use the variable itself, and this variable stores a value. The stored value is what we get from the user's input (2.5 by default).

Another,, shorter notation might make the idea clearer: Another scene.setGlobalVariableValue("velocityThreshold scene.setGlobalVariableValue(" velocityThreshold", ", guiForm.getFieldValue("Velocity threshold"))

Now we have to switch to the Particle Swapping script under “Simulation Flow” and add a new line at the beginning of the script: velocityThreshold = velocityThreshold = scene.getGlobalVariableValu scene.getGlobalVariableValue(" e("velocityThreshold velocityThreshold") ")

What we have done is to read the global variable and its value, and make it local again: velocityThreshold = velocityThreshold = get the global velocityThreshold velocityThreshold variable's variable's value = 2.5


57


GUIS

AND LISTS

In the last chapter of the GUI section I will show you how to work with lists, because they require a certain notation as well. As you know, lists store multiple elements and each entry has its own index starting with 0. So far we have been looping through a list's elements one by one, but did not access a specific entry. entry. In this example we add another extension to the Particle Swapping GUI and events script, where the user can choose which emitter is used for water and, which one for foam. Of course, this is not really necessary with just two emitters – one “Circle” and one “Container” – but the script illustrates the concepts. Instead of listing the scene's standard particle emitters manually, manually, we are going to use a convenient command where all emitters are added to a list automatically: emitterList = scene.get_PB_Emitters()

The problem is that we do not have direct access to these emitters, because they are not stored by their names, but as an internal structure – a reference. We can see this when we print the list's elements: for emitter in emitterList:

scene.message(str(emitter))

The output will look like this:

TRANSLATING REFERENCES INTO NAMES

What we can do is to define a new empty list where the emitter's names will be stored: < py | batch > emitterNameList = emitterNameList = [] emitterList

= scene.get_PB_Emitters()

for emitter in emitterList: emitterName = emitter.getName() emitterNameList.append(emitterName) emitterNameList .append(emitterName)


58


Now, emitterNameList contains two strings, and can we can print them to the GUI dialogue: < py > guiForm = GUIFormDialog.new() guiForm.addListField("Water", guiForm.addListField ("Water", emitterNameList emitterNameList, , 0) guiForm.addListField guiForm. addListField("Foam", ("Foam", emitterNameList emitterNameList, , 1) guiForm.addFloatField("Velocity guiForm.addFloatField("Vel ocity threshold", 2.5)

We can see that addListField(string, list, integer) takes three arguments: 1. Parameter name. 2. Name of the list with the emitters' names. 3. Position of the list elements – 0 stands for “Circle01”, 1 represents “Container01”. The problem is that addListField() does not return a name or a string, but a number number.. The name you can see in the GUI is just the names list's entry at position 0 or 1. The number, on the other hand, is reused to identify the appropriate name in emitterNameList: < py > if (guiForm.show() == GUI_DIALOG_ACCEPTED): waterEmitterIndex = waterEmitterIndex = guiForm.getFieldValue("Water guiForm.getFieldValue("Water") ") foamEmitterIndex = guiForm.getFieldValue("Foam" guiForm.getFieldValue("Foam") ) waterEmitterName foamEmitterName

= emitterNameList[ emitterNameList[waterEmitterIndex waterEmitterIndex] ] = emitterNameList emitterNameList[ [foamEmitterIndex] foamEmitterIndex]

waterEmitterName and foamEmitterName can now be stored as global variables, and transferred to

the simulation script. There we use the names to finally get the emitters. < py >

scene.setGlobalVariableValue("waterEmitterName", waterEmitterName waterEmitterName) ) scene.setGlobalVariableValue("foamEmitterName", foamEmitterName foamEmitterName) ) scene.setGlobalVariableValue("velocityThreshold", scene.setGlobalVariableValue ("velocityThreshold", velocityThreshold)


59


< py | batch > emitterNameList = [] emitterList = scene.get_PB_Emitters() for emitter in emitterList: emitterName = emitter.getName() emitterNameList.append(emitterName) guiForm = GUIFormDialog.new() guiForm.addListField("Water", emitterNameList, 0) guiForm.addListField("Water", guiForm.addListField("Foam", emitterNameList, 1) guiForm.addFloatField("Velocity guiForm.addFloatField("Veloc ity threshold", 2.5) if (guiForm.show() == GUI_DIALOG_ACCEPTED): waterEmitterIndex = guiForm.getFieldValue("Water guiForm.getFieldValue("Water") ") foamEmitterIndex = guiForm.getFieldValue("Foam") guiForm.getFieldValue("Foam") velocityThreshold = guiForm.getFieldValue("Velocity threshold") waterEmitterName = emitterNameList[waterEmitterI emitterNameList[waterEmitterIndex] ndex] foamEmitterName

= emitterNameList[foamEmitterIn emitterNameList[foamEmitterIndex] dex]

scene.setGlobalVariableValue("waterEmitterName", waterEmitterName) scene.setGlobalVariableValue("waterEmitterName", scene.setGlobalVariableValue("foamEmitterName", scene.setGlobalVariableValue( "foamEmitterName", foamEmitterName) scene.setGlobalVariableValue("velocityThreshold", scene.setGlobalVariableValue( "velocityThreshold", velocityThreshold)

< py | framespre > waterEmitterName = scene.getGlobalVariableValu scene.getGlobalVariableValue("waterEmitterName") e("waterEmitterName") foamEmitterName = scene.getGlobalVariableValue("foamEmitterName") scene.getGlobalVariableValue("foamEmitterName") velocityThreshold = scene.getGlobalVariableValu scene.getGlobalVariableValue("velocityThreshold") e("velocityThreshold") waterEmitter foamEmitter

= scene.get_PB_Emitter(waterE scene.get_PB_Emitter(waterEmitterName) mitterName) = scene.get_PB_Emitter(foamEm scene.get_PB_Emitter(foamEmitterName) itterName)

particleList

= waterEmitter.getParticles()

# Add the rest of the Particle Swapping script here (loop)


60


The GUI for the Particle Swapping script.

A BATCH SIMULATION SCRIPT When you start with a RealFlow simulation then you normally create several versions with different parameter settings, e.g. different viscosities, resolutions, object frictions, or daemon forces. A very good idea is to prepare simulation files and let them run over night. The problem is that RealFlow does not support batch simulating – a new scene file has to be loaded and started manually.. With a short script it is possible to change this. All we need for this script is a GUI and a few ually loops. Here is the idea behind the script: •

•

•

•

Create a GUI where we can specify the FLW scene files for the batch simulation. Store the paths to the FLW files in a list. Loop through the list, load and open the FLW files. Start the simulations one by one.

The name indicates that we will be creating a batch script here. Open the “Batch Script” editor with F10.

INITIAL VARIABLES When we take another look at the task list above then it seems as if we need just two initial variables: a list where the paths to the FLW files will be stored, and the number of GUI fields for the FLW paths: < py > projectFiles = [] numberOfFields = 10


61


THE GUI The structure of the GUI is really re ally straight-forward. All we need are 10 fields where we can specify the FLW files' paths. A loop is a quick solution, but we have to consider a few things. With a simple loop all fields will have exactly the same name, and this is not allowed. We have to keep kee p the fields separated, because every field contains its own file path. What we can do is to use the loop's current index and create a name out of it, e.g. “Project file 01”, “Project file 02”, …, “Project file 10”. The leading 0 is certainly not necessary, necessary, but a nicely formatted GUI does not only look better, it is also a good opportunity to show you how to combine strings. The first field here is “Project file 01” and therefore the loop will not start with 0 as usual, but with 1: < py > guiForm = GUIFormDialog.new() for fieldNumber fieldNumber in in range(1, numberOfFields + 1):

Strings are always enclosed in quotation marks, but fieldNumber is an integer. We have to convert the number into a string with str(fieldNumber str( fieldNumber) )

The first table in the chapter about operators contains an entry called “string “ string concatenation”, and this is exactly what we need here: it is a simple + operator operator.. It is also necessary to differentiate between numbers smaller than 10 and 10 (or greater): < py > if (fieldNumber (fieldNumber < < 10): fieldName fieldName = = "Project file 0" + str(fieldNumber str(fieldNumber) )

else: fieldName fieldName = = "Project file " + str(fieldNumber str(fieldNumber) )

Now, fieldNumber can be used as an argument for the add...Field() command: guiForm.addFileField(fieldName guiForm.addFileField( fieldName) )


62

CUSTOM-TAILORED USER INTERFACES GUIS

An here is a preview of the GUI window in RealFlow 2015:

PROCESSING THE INPUT VALUES

We can now read the user's input and append the paths to projectFiles with another loop. Here it is possible to reuse variable names, because the creation of the input fields is completed, and it is safe to overwrite the existing values. < py > if (guiForm.show() == GUI_DIALOG_ACCEPTED):

for fieldNumber fieldNumber in in range(1, numberOfFields + 1): if ( (fieldNumber fieldNumber < < 10): fieldName = fieldName = "Project file 0" + str(fieldNumber str(fieldNumber) ) else: fieldName = fieldName = "Project file " + str(fieldNumber str(fieldNumber) ) projectFiles.append(guiForm.getFieldValue( projectFiles .append(guiForm.getFieldValue(fieldName fieldName)) ))

A third loop will go through the entries of the projectFiles list, load the FLW files, and start the simulation. We also have to check if there are empty entries in projectFiles, because maybe we want to simulate just 3 or 4 project files. This can be achieved with an "is not" operator: if (currentProject (currentProject != != ""):

The line above is read as: “If the content of currentProject currentProject is is not empty”. We also print a message to give some information about the currently running simulation (see next page).


63


Here is the final part of the script: < py > for currentProject currentProject in in projectFiles: if (currentProject (currentProject != != ""):

scene.load(currentProject scene.load( currentProject) ) scene.simulate() scene.message("Simulating " + currentProject currentProject + + "…")

else: scene.message("Script cancelled by user.")

You should now be able to assemble the entire script from the previous explanations and code snippets.


64

CROWN SPLASHES

CROWN SPLASHES

CROWN SPLASHES We have gathered a lot of scripting knowledge already and now it is time for a more complex project. RealFlow 2015 provides a really cool new daemon called “Crown”. A viewport gizmo with editable control points is used to determine the number of tendrils and draw the splash's shape. The idea behind the new “Crown” “ Crown” daemon is a script I have written for RealFlow 2014. I wanted to have a tool for the creation of paint-like splashes with tendrils, but of course my program did not have all these nice viewport features. I have been adding other functions instead – functions which are missing with the daemon. The script's concept is also completely different and here I present a downgraded version, because “water “waterline line magazine – Scripting with RealFlow” is a publication for beginners. Despite of the magazine's beginner's approach you should not be under the illusion that the following scripts came out of thin air. air. It will take you some time to understand what happens. And the used formulas and a nd methods are the result of thinking! Sometimes it also requires time, a pencil, and paper to make sketches and to do some basic maths. The creation of artificial and user-controllable splashes, on the other hand, is a fascinating pro ject, and this is the reason why I chose to discuss discuss it. Of course you can improve the script, add more features, and change it to your needs.

WHA HAT T

THE SCRIPT SHOULD DO

I always recommend defining a script's purpose and what you expect it to do. Then I try to break down this goal into manageable parts and code segments, and start with the most fundamental functions. Once I got the individual pieces it is much easier to implement things like parametrization, randomness, or a generally valid version, e.g. with location-independent functions. Out task list includes the creation of crown splashes with a user-defined •

•

•

•

•

•

•

base radius width (“thickness”) number of tendrils velocity randomization start and end time splash position.

From now on I will use shortened variable names, but you should still be able to recognize their meaning.


66

CROWN SPLASHES

FORCE

OR VELOCITY ?

We also have to make a fundamental decision now about whether we want to use forces or velocities for accelerating the particles. The main difference lies in simulation speed. A force-based approach uses a scripted daemon, and the appropriate functions are executed per simulation step. This makes our daemon very accurate, but rather slow. A daemon can also be placed anywhere easily, easily, deactivated on demand, and combined with other forces. A velocity-driven method is added to the “Simulation Flow” panel's events tree, and we will get a sufficient level of quality under “FramesPre”. This will make the script much faster and with very large amounts of particles we will be able to create more versions in less time. Forces also evolve slowly, while velocities act immediately. Since time is always the most critical part in simulations we want to focus on the velocity-based method.

SCENE SETUP Our starting point is a shallow puddle of water water.. The fluid is calm and we have an initial state. In this example a standard particle emitter is used. Dyverso fluids are also possible, but at the time this magazine has been written, this solver type has not been fully supported by RealFlow's SDK. But, it should be no problem to translate the scripts for Dyverso. The scene's “Gravity” daemon can be disabled for the following simulations.

DEFINING A RING The entire script is mainly about finding and separating particles. Once they are stored we can treat them individually. individually. First of all we have to look for particles within a ring. These particles will be the seeds for the splashes.


67

CROWN SPLASHES

To find the appropriate candidates we have to check the particles' distances to the ring's centre. This means that we need a reference point to determine the centre, and this is done with a helper object – a null. A null's default position is < 0,0,0 > ( hPos) and we keep this position for now: •

•

•

A particle is inside the specified ring if its distance from the centre is inside an area around a circle with a given radius. We only use the horizontal values, because a particle's height plays no role. This can be achieved by setting a vector's horizontal component to 0 (see (se e hPosH and pPosH variables). Furthermore we have to store the particles from inside the ring, because we want to accelerate them separately, while the remaining particles should not be moved.

splash radius < 0,0 >

splash width

The initial variables are: < py | batch > splashRadius

= 0.5

splashWidth = splashParticles = splashParticles = helper = hPos = hPosH = emitter particleList

0.05 [] scene.getObject("Null01") helper.getParameter("Position") helper.getParameter("Positio n") Vector.new(hPos Vector.new( hPos.getX(), .getX(), 0, hPos hPos.getZ()) .getZ())

= scene.get_PB_Emitter("Sphere scene.get_PB_Emitter("Sphere01") 01") = emitter.getParticles()


68

CROWN SPLASHES

In the following loop we will calculate a particle's distance from the helper object. If this distance is inside the ring the particle is added to splashParticles: < py | batch > for particle in particleList: pPos = particle.getPosition() pPosH = Vector.new(pPos.getX(), 0, pPos.getZ()) p_hDistance = pPosH pPosH.distance( .distance(hPosH hPosH) ) if (p_hDistance >= splashRadius - splashWidth / 2 and p_hDistance <= splashRadius + splashWidth / 2): splashParticles.append(particle) splashParticles .append(particle) scene.setGlobalVariableValue("splashParticles", splashParticles splashParticles) )

This is already a very good intermediate result, but where do we have to place this code segment? It will be outsourced to a batch script, because it contains all initial variables we need for the GUI and the definition of the ring is also a process that has to be finished before the simulation starts.

ACCELERATING THE RING PARTICLES The particles from inside the ring are now stored in splashParticles, and we can loop through them. To To do this we add a new script to the “FramePre” branch of the “Simulation Flow” events tree. Of course, we first have to read the global variable: splashParticles = splashParticles = scene.getGlobalVariableValue scene.getGlobalVariableValue(" ("splashParticles splashParticles") ")

For our first test we just want to start with an acceleration along the positive vertical axis – here it is Y. Y. If you work with a Z-based Z -based setup use the Z axis. Of course, a velocity value is needed as well: < py | framespre > splashParticles = scene.getGlobalVariableValue splashParticles = scene.getGlobalVariableValue(" ("splashParticles splashParticles") ") velV = 1.0 for splash in splash in splashParticles splashParticles: : velVector = Vector.new(0.0, velV, 0.0) splash.setVelocity(velVector) splash .setVelocity(velVector)


69

CROWN SPLASHES

The code can be shortened by combining the last two lines. Of course, the following notation is valid for other variables as well: < py | framespre > splash.setVelocity(Vector.new(0.0 splash .setVelocity(Vector.new(0.0, , velV, 0.0))

Now,, deactivate the “Gravity” daemon, set the last simulation frame to 50, and start a first test. Now

What we get is a ring-shaped structure and we can also observe that our definition of splash particles works as expected. Currently, the particles are attracted during the entire simulation range, and there is no counteracting force, e.g. “Gravity”, because we want to see the pure result of our script.

START

AND END TIME

Setting a time limit for the attraction is just a matter of a few lines of code. We define the start and end frame variables and compare them against the scene's current simulation frame. As long as the simulation is within the given range the particles will be affected. Since these parameters will be part of our GUI they are added to the existing batch script and defined as global variables: < py | batch > startFrame = 0 startFrame = stopFrame = 20 scene.setGlobalVariableValue("startFrame", startFrame startFrame) ) scene.setGlobalVariableValue("stopFrame", stopFrame stopFrame) )


70

CROWN SPLASHES

In the "FramesPre" part of the script, the startFrame and stopFrame variables will be read: < py | framespre > splashParticles curFrame startFrame stopFrame

= = = =

scene.getGlobalVariableValue("splashParticles") scene.getGlobalVariableValue("splashParticles") scene.getCurrentFrame() scene.getGlobalVariableValue("startFrame") scene.getGlobalVariableValue ("startFrame") scene.getGlobalVariableValue("stopFrame") scene.getGlobalVariableValue ("stopFrame")

if ( (curFrame curFrame >= >= startFrame startFrame and and curFrame <= stopFrame stopFrame): ): for splash in splashParticles: … execute code from “Accelerating the Ring Particles”

CREATING A SPLASH-LIKE SHAPE Our next task is to give the fluid its typical shape, because by now we only have a cylindrical structure. Let's take another look at the definition of our velocity vector: Vector.new(0.0, velV, 0.0)

There is just a vertical component, while the horizontal values are both 0. It seems as if we only have to define X and Z values, right? Wrong! We have to consider the particles' positions and motion directions, because some particles will receive negative velocities, while others require positive values. But how can this be accomplished? The keyword is vector normalization. When a vector is normalized you can also think of this process as finding its direction. The normalized vector's components will help us to determine in which direction a particle has to be accelerated. Although this is a very reliable method we are facing one problem here: the usage of normalized vectors only works as long as our null helper is located at in the scene's origin at < 0,0,0 >. Fortunately, this can be solved easily by taking the helper object's position into consideration. We Fortunately, need a velocity direction ( velDir) from the splash's centre to its outside: velDir = velDir = pPosH – hPosH # particle position vector - helper position vector velDir.normalize() velDir .normalize()

Since the helper's postion is used here it must be declared as a global variable as well. Again, the horizontal components are enough (= hPosH)


71

CROWN SPLASHES

We will also outsource the initial velocity definitions to the batch script, because later we want them to be part of the GUI. Add these lines to the existing script: < py | batch > velH = 1.7 # The particles' initial vertical velocity velV = 2.0 # The particles' initial horizontal velocity scene.setGlobalVariableValue("velH", velH) scene.setGlobalVariableValue("velH", scene.setGlobalVariableValue("velV", scene.setGlobalVariableVal ue("velV", velV) scene.setGlobalVariableValue("hPosH", scene.setGlobalVariableVal ue("hPosH", hPosH)

And here is the complete "FramesPre" part of our script so far, where we use the normalized direction vectors. It will substitute the current code: < py | framespre > splashParticles = scene.getGlobalVariableValue scene.getGlobalVariableValue("splashParticles") ("splashParticles") velH = scene.getGlobalVariableValue("velH") scene.getGlobalVariableValue("velH") velV hPosH curFrame startFrame stopFrame

= = = = =

scene.getGlobalVariableValue("velV") scene.getGlobalVariableValue("velV") scene.getGlobalVariableValue() scene.getGlobalVariableValue () scene.getCurrentFrame("hPosH") scene.getCurrentFrame("hPosH ") scene.getGlobalVariableValue("startFrame") scene.getGlobalVariableValue ("startFrame") scene.getGlobalVariableValue("stopFrame") scene.getGlobalVariableValue ("stopFrame")

if (curFrame >= startFrame and curFrame <= stopFrame): for splash in splashParticles: pPosH = splash.getPosition() velDir = velDir = pPosH - hPosH velDir.normalize() velDir .normalize()

velVec = Vector.new(velH * velDir velDir.getX(), .getX(), velV, velH * velDir velDir.getZ()) .getZ()) splash.setVelocity(velVec)

Now it is possible to place the helper object anywhere inside the puddle and the particles will be accelerated correctly. correctly. Since we can accelerate the horizontal and vertical components individually we are able to control the crown's width. Our test uses a "Sheeter" daemon to fill the occurring holes, and shows the typical shape. We can proceed with the next task: the creation of the splash's tendrils.


72

CROWN SPLASHES

The script now creates the typical crown splash shape and is position-indep position-independent. endent.

TENDRIL CREATION Currently, all particles receive the same velocity value, but for the creation of tendrils we have to Currently, modify the velocities of specific particles and make them faster than the rest of the splash. The definition of the splash's tendrils is definitely the most difficult part, and requires some more advanced techniques. We also have to consider simulation speed, so we should look for an economic solution. Here are our subtasks: •

•

•

Find the positions of the tendrils. Save the tendril seed particles. Accelerate the tendril seeds separately from the ring/splash particles.

The first two topics will be part of the batch script, while the acceleration a cceleration happens inside the “FramesPre” part. FINDING THE TENDRIL POSITIONS

Our zone of action is a ring. The ring's inner radius describes a circle and this parameter has been defined already: splashRadius. What we need is a formula that will spread the tendril seeds evenly over this circle. Attention: The following illustrations show a top view of the splash ring and therefore the corresponding axes are X and Z. If you have a Z-based setup, the axes are X and Y. Y.


73

CROWN SPLASHES

A full circle has 360 degrees. With, for example, eight tendrils, a tendril seed is placed every 360 ° / 8 = 45 °

Z

α

r X

Or in a common formula with degPerTendril and numTendrils as a new variables: degPerTendril (here: degPerTendril (here: a) = 360.0 / numTendrils

CIRCLE MATHS

What we need now are the X and Z coordinates of the points on the circle. Again, height plays no role. We therefore have to find a method to describe the position of every point on a circle dependent on a given angle: degPerTendril. Maybe you still remember your time at school and there you have been dealing with the so-called unit circle – a circle with a radius of 1. The interesting thing about this certain type of circle is that it is used to illustrate sine and cosine functions. Just do a quick Internet search for: sine unit circle There you will find a detailed explanation. Here we just want to complete our illustration.


74

CROWN SPLASHES

Any coordinate on a unit circle can be found with sine, cosine, and and angle ( a): Z

α

)

α

(

n i s

r=1 cos (α)

X

With a = degPerTendril our coordinates are: xCoord = cos(degPerTendril cos(degPerTendril) ) zCoord = sin(degPerTendril sin(degPerTendril) )

There is one thing we have to consider: instead of degrees the radians is required. The formula for converting degrees into radians is: radians = degPerTendril degPerTendril * * Pi / 180.0

The two equations above are multiplied with splashRadius (r) to get a result for arbitrary circles. And of course, we have to consider the splash's centre, indicated by the helper object. When we work with mathematical functions a certain module is required: import.math radians = degPerTendril degPerTendril * * math.pi / 180.0 xCoord = math.cos(radians math.cos(radians) ) * splashRadius splashRadius + + hPos.getX() zCoord = math.sin( math.sin(radians radians) ) * splashRadius + splashRadius + hPos.getZ()


75

CROWN SPLASHES

The coordinates from the previous page are just for a single degPerTendril angle, but we need numOfTendrils angles. A loop will solve this: for i in range(0, numOfTendrils numOfTendrils): ): radians = radians = i * degPerTendril degPerTendril * * math.pi * 180.0 xCoord = math.cos( math.cos(radians radians) ) * splashRadius splashRadius + + hPos.getX() zCoord

= math.sin( math.sin(radians radians) ) * splashRadius splashRadius + + hPos.getZ()

These positions will be added to a separate list (tendrilSeeds). Since the previous descriptions are rather complex we want to take a look at the entire e ntire batch script so far. New code segments are printed in blue: < py | batch > import math # Define all initial variables, get the particles, and the helper object's position startFrame = 0 stopFrame = 20 velH = 1.7 velV splashRadius splashWidth numOfTendrils tendrilSeeds

= = = = =

2.0 0.5 0.05 8 []

splashParticles helper hPos hPosH emitter

= = = = =

[] scene.getObject("Null01") helper.getParameter("Position") helper.getParameter("Positio n") Vector.new(hPos.getX(), 0, hPos.getZ()) scene.get_PB_Emitter("Sphere01") scene.get_PB_Emitter("Sphere 01")

particleList

= emitter.getParticles()

# Find the ring/splash particles and add them to splashParticles for particle in particleList: pPos = particle.getPosition() pPosH = Vector.new(pPos.getX(), 0, pPos.getZ()) p_hDistance = pPosH.distance(hPosH) if (p_hDistance >= splashRadius - splashWidth / 2 and p_hDistance <= splashRadius + splashWidth / 2): splashParticles.append(particle)


76

CROWN SPLASHES

# Get the positions of the tendril seeds for i in range(0, numTendrils): radians = i * degPerTendril * xCoord = math.cos(radians) math.cos(radians) * zCoord = math.sin(radians) math.sin(radians) * tPosH = Vector.new(xCoord,

math.pi / 180.0 splashRadius + hPos.getX() splashRadius splashRadius + hPos.getZ() splashRadius 0.0, zCoord)

tendrilSeeds.append(tPosH tendrilSeeds.append( tPosH) ) # Define the global variables scene.setGlobalVariableValue("startFrame", scene.setGlobalVariableVal ue("startFrame", startFrame) scene.setGlobalVariableValue("stopFrame", stopFrame) scene.setGlobalVariableValue("stopFrame", scene.setGlobalVariableValue("velH", scene.setGlobalVariableVal ue("velH", velH) scene.setGlobalVariableValue("velV", scene.setGlobalVariableVal ue("velV", velV) scene.setGlobalVariableValue("hPosH", scene.setGlobalVariableVal ue("hPosH", hPosH) scene.setGlobalVariableValue("splashParticles", scene.setGlobalVariableVal ue("splashParticles", splashParticles)

GETTING THE TENDRIL PARTICLES

The tPosH vector is basically the same as the hPosH vector we have been using for detecting the ring particles. This means that we can calculate the distance between and tPosH and a particle's position (pPosH) in order to find a tendril particle. It is the same principle that we have used for finding the ring particles. It is, on the other hand, not very likely that there will be a particle at the specified position, so it is better to search within a given radius – the new searchRadius variable: searchRadius = 0.05

In the next step we loop through all particles again, but also through tendrilSeeds to calculate the distance between particles and seeds (= nested loop). We also need another list where we can store the found particles. And we must not forget to add the individual tendril seed particles to the splashParticles list, because searchRadius can be greater then splashWidth.

splashWidth searchRadius


77

CROWN SPLASHES

This is the last code segment of the batch script. I have added a few more annotations on the script below: < py | batch > # Add these new variables to the initial variable definition searchRadius = 0.05 tendrilIds = [] # Add this nested loop directly before the definition of the global variables for particle in particleList: pPos = particle.getPosition() pPosH = Vector.new(pPos.getX(), 0, pPos.getZ())

for tPosH in tPosH in tendrilSeeds: p_sDist = pPosH.distance( pPosH.distance(tPosH tPosH) ) if (p_sDist <= searchRadius): searchRadius): tendrilIds.append(particle.getId()) splashParticles.append(particle)

scene.setGlobalVariableValue("tendrilIds", scene.setGlobalVariableVal ue("tendrilIds", tendrilIds)

The if-condition if-condition defines defines the area in which we search for particles, but the last line is more interesting. Here, we do not store particles, but only their Ids. This trick will help us to avoid a time-consuming nested loop at simulation time.

The eight big spots are the tendril positions (splashWidth = 0.05, searchRadius = 0.15). A blossom-shaped splash appears during during the simulation, simulation, but the tendrils tendrils are not yet created.


78

CROWN SPLASHES

What we have scripted here is a very versatile approach. Imagine a spline, e.g. a spiral. In such a case we can read out the horizontal coordinates from the spline's control points directly. There is no need to search for these values with sine and cosine. Then, the control points are used as seeds for pulling out tendrils at specific positions. With the knowledge from this chapter you should be able to write such a script already!

ACCELERATING SPLASHES

AND TENDRILS

A huge advantage with our current approach is that we have to look for the splash and tendril particles only once in the batch part. All particles are defined before RealFlow starts to simulate and this makes our script very fast. The result of all the previously executed actions are two lists: •

•

splashParticles contains all particles inside the ring including the tendril particles. tendrilIds contains the Ids of the particles around a tendril seed within searchRadius.

This differentiation makes it possible to accelerate the tendril particles separately se parately from the splahes. For this purpose a factor is introduced. When the script detects the Id of a tendril particle a factor of 1.25 is used, if it is a ring splash particles the factor is 0.75: < py | framespre > splashParticles = getGlobalVariableValue("spla getGlobalVariableValue("splashParticles") shParticles") tendrilIds = getGlobalVariableValue("tendrilIds") getGlobalVariableValue("tendrilIds") if (curFrame >= startFrame and curFrame <= stopFrame): for splash in splashParticles: splashId = splash.getId() if (splashId in tendrilIds): factor factor = = 1.25 else : factor factor = = 0.75

In the next step, the factor has to be multiplied with the user-defined velocites and the XZ components of the normalized direction vector velDir. To give you a complete view of this part I have added the last code segment to the next page.


79

CROWN SPLASHES

Append the following code to the previous part of the "FramesPre" script: < py | framespre > sPosH

= splash.getPosition()

velDir = sPosH - hPosH velDir.normalize() velDir .normalize() velVecX = velH * velDir velDir.getX() .getX() * factor velVecY = velV * factor velVecZ = velH * velDir velDir.getZ() .getZ() * factor velVec = Vector.new(velVecX, velVecY, velVecZ) splash.setVelocity(velVec splash.setVelocity( velVec) )

The script's mode of operation is as follows: we just go through our splash/ring particles, get their positions as usual, and normalize these vectors. We also get the Id and then we check if the current Id is stored in the tendrilIds list. If this is the case, the particle gets an extra push to make it faster than the remaining splash particles. Here I am using fixed factor values, but of course you can add this parameter to a GUI as well. Below is a rendered version with 10 tendrils and "FPS Output" set to 100. 10 0. The tendrils' droplets are the result of a "Surface Tension" Tension" daemon.


80

CROWN SPLASHES

RANDOMIZATION At the moment we have a perfect splash, where the distances between the tendrils is fixed, and the accelrating forces are also the same for all particles. The resulting crown is nice, but too artificial for many applications. We need a more random appearance. Adding some noise is not difficult, and we did something very similar in the Particle Swapping script already, already, but here we have to be careful: If the random speed variation is added to the velocity vector velVec in the “FramesPre” script we might end up with something chaotic, because the particles' speed will change every time the calculated velocity is applied. It is better to define a fixed initial random value for every particle and apply it during the simulation. We therefore have to start with the batch script, load the "random" module, and define the range. We also need another list called velVariation. The number of entries in velVariation has to be equal to the number of particles in splashParticles: < py | batch > import math, random # Add these new variables to the initial variable definition velRange = 0.2 velVariation = velVariation = [] # Add this loop directly before the definition of the global variables for entry in splashParticles splashParticles: : velVariation.append(random.uniform(velVariation .append(random.uniform(-velRange velRange, , velRange velRange)) )) scene.setGlobalVariableValue("velVariation", velVariation velVariation) )

In the "FramesPre" section the required global variable is read as usual. What we also need is a method to get a splash particle's associated random velocity from the velVariation list. To do this, a counter is introduced: counter = counter = 0


81

CROWN SPLASHES

Inside the loop, 1 is added to the counter with every new particle. This process is also called incrementation (see “Operators”). Now it is possible to use the counter as an index to get the list positions. Since the counter is updated with every step of the loop we can go through all list elements automatically: velVariation velV ariation contains random values between -0.2 and 0.2 Value

-0.13

0.07

0.12

0.18

-0.02

-0.05

0.13

-0.17

0.11

0.16

-0.04

-0.10

Index

0

1

2

3

4

5

6

7

8

9

10

11

counter

0

1

2

3

4

5

6

7

8

9

10

11

A single element can be read out this way: rndVel = velVariation[counter]

The last question is where the random value should be used? After a few tests I found that the most effective method is to add the random values to the factor variable. Here is the shortened code: < py | framespre > # Add these variables to the other (global) variable definitions velVariation = velVariation = scene.getGlobalVariableVar scene.getGlobalVariableVariation("velVariation") iation("velVariation") counter

= 0

if (curFrame >= startFrame and curFrame <= stopFrame): for splash in splashParticles: if (splash.getId() in tendrilIds): factor factor = = 1.25 + velVariation velVariation[ [counter counter] ] else

: factor factor = = 0.75 + velVariation velVariation[ [counter counter] ]

# Do the velocity part here, assemble the vector, etc. # The last line in the loop is: counter += counter += 1

That's it! We are ready and our script contains all the features we have defined at the beginning of the chapter. chapter. We are able to user-define and control crown splashes, we have found a very fast approach, and avoided nested loops during simulation time. Of course, there is also room for improvements, but the most important goal with this project was to show you concepts.


82

CROWN SPLASHES

< py | batch > import math, random # Define all initial variables, get the particles, and the helper object's position startFrame = 0 stopFrame velH velV splashRadius splashWidth

= = = = =

15 1.7 2.0 0.5 0.05

searchRadius numOfTendrils velRange degPerTendril tendrilSeeds

= = = = =

0.05 8 0.5 360.0 / numOfTendrils []

tendrilIds splashParticles velVariation helper hPos hPosH

= = = = = =

[] [] [] scene.getObject("Null01") helper.getParameter("Position") helper.getParameter("Positio n") Vector.new(hPos.getX(), 0, hPos.getZ())

emitter particleList

= scene.get_PB_Emitter("Sphere scene.get_PB_Emitter("Sphere01") 01") = emitter.getParticles()

# Find the ring/splash particles and add them to splashParticles for particle in particleList: pPos = particle.getPosition() pPosH = Vector.new(pPos.getX(), 0, pPos.getZ()) p_hDistance = pPosH.distance(hPosH) if (p_hDistance >= splashRadius - splashWidth / 2 and p_hDistance <= splashRadius + splashWidth / 2): splashParticles.append(particle) # Get the positions of the tendril seeds for i in range(0, numOfTendrils): radians xCoord zCoord tPosH

= = = =

i * degPerTendril * math.pi / 180.0 math.cos(radians) * splashRadius math.cos(radians) splashRadius + hPos.getX() math.sin(radians) * splashRadius math.sin(radians) splashRadius + hPos.getZ() Vector.new(xCoord, 0.0, zCoord)

tendrilSeeds.append(tPosH)


83

CROWN SPLASHES

# Get the positions of the tendril seeds for particle in particleList: pPos = particle.getPosition() pPosH = Vector.new(pPos.getX(), 0, pPos.getZ()) for tPosH in tendrilSeeds: p_sDist = pPosH.distance(tPosH) if (p_sDist <= searchRadius): tendrilIds.append(particle.getId()) splashParticles.append(particle) # Create a unique random acceleration value for every splash particle for entry in splashParticles: velVariation.append(random.uniform(-velRange, velVariation.append(random.u niform(-velRange, velRange)) # Define the global variables scene.setGlobalVariableValue("startFrame", scene.setGlobalVariableValu e("startFrame", startFrame) scene.setGlobalVariableValue("stopFrame", scene.setGlobalVariableValu e("stopFrame", stopFrame) scene.setGlobalVariableValue("velH", scene.setGlobalVariableValu e("velH", velH) scene.setGlobalVariableValue("velV", scene.setGlobalVariableValu e("velV", velV) scene.setGlobalVariableValue("hPosH", scene.setGlobalVariableValu e("hPosH", hPosH) scene.setGlobalVariableValue("splashParticles", scene.setGlobalVariableValu e("splashParticles", splashParticles) scene.setGlobalVariableValue("tendrilIds", scene.setGlobalVariableValu e("tendrilIds", tendrilIds) scene.setGlobalVariableValue("velVariation", scene.setGlobalVariableValu e("velVariation", velVariation)

< py | framespre > curFrame velH velV

= scene.getCurrentFrame() = scene.getGlobalVariableValue scene.getGlobalVariableValue("velH") ("velH") = scene.getGlobalVariableValue scene.getGlobalVariableValue("velV") ("velV")

hPosH splashParticles tendrilIds startFrame stopFrame

= = = = =

velVariation counter

= scene.getGlobalVariableValue scene.getGlobalVariableValue("velVariation") ("velVariation") = 0

scene.getGlobalVariableValue("hPosH") scene.getGlobalVariableValue("hPosH") scene.getGlobalVariableValue("splashParticles") scene.getGlobalVariableValue ("splashParticles") scene.getGlobalVariableValue("tendrilIds") scene.getGlobalVariableValue ("tendrilIds") scene.getGlobalVariableValue("startFrame") scene.getGlobalVariableValue ("startFrame") scene.getGlobalVariableValue("stopFrame") scene.getGlobalVariableValue ("stopFrame")

if (curFrame >= startFrame and curFrame <= stopFrame): for splash in splashParticles: if (splash.getId() in tendrilIds): factor = 1.25 + velVariation[counter] else : factor = 0.75 + velVariation[counter]


84

CROWN SPLASHES

sPosH

= splash.getPosition()

velDir = sPosH - hPosH velDir.normalize() velVecX = velH * velDir.getX() * factor velVecY = velV * factor velVecZ = velH * velDir.getZ() * factor velVec = Vector.new(velVecX, velVecY, velVecZ) splash.setVelocity(velVec) counter += 1

IMPROVEMENTS

AND SUGGESTIONS

Possible additions are •

•

•

•

•

•

•

•

The GUI Randomize the tendril's angles. Create propagating tendril patterns. Translate “FramesPre” into a scripted daemon. Particles below the helper object should not be affected. Take the particles' vertical positions into account. Use spline control point positions or object vertices as tendril seeds. Add a time-dependent function for the velocity vector to start with very low values, and increase them over time.

You should now be able to implement the above suggestions and customize your crown splash script. For some features (propagating tendrils, tendrils from spline control points, and vertices) it is better to discard splashParticles, and to work with tendrilSeeds only. Otherwise you will get strange results.


85

CROWN SPLASHES

AXIS SETUPS So far, far, all scripts have been developed for a Y-based axis setup, but this can be considered a special case. If your scripts are for personal or internal use only then you do not have to care about this issue too much, because you just have to swap Y and Z in your vector definitions: verticalVelocity= verticalVelocity = 2.5 velocityVector = Vector.new(0, verticalVelocity verticalVelocity, , 0)

With a Z-based setup the vector is: velocityVector = Vector.new(0, 0, verticalVelocity verticalVelocity) )

RealFlow also provides a method for detecting the scene's axis setup as shown in this batch script: < py > verticalVelocity = verticalVelocity = 2.5 axisSetup = axisSetup = scene.getAxisSetup() if ( (axisSetup axisSetup == == AXIS_SETUP_ZXY): velocityVector = Vector.new(0.0, 0.0, verticalVelocity verticalVelocity) ) else: velocityVector = Vector.new(0.0, verticalVelocity verticalVelocity, , 0.0) scene.message(str(velocityVector))

If your axis setup is ZXY – with Z as the vertical axis – the result is: 0.000000 0.000000 2.500000

For Y-based setups (YXZ, YZX) it is: 0.000000 2.500000 0.000000


86

EXPORT MANAGER

EXPORT PATH MANAGER

EXPORT PATH MANAGER RealFlow's “Export Central” dialogue provides lots of features, but it is sometimes cumbersome to use. Especially the definition of export paths for storing different versions can be tedious, because the paths have to be entered and edited manually. This is not exactly a quick and smooth workflow. With the following batch script ( F10) it is possible to specify new export paths for a scene's standard particle emitters by choosing a directory. The chosen folder will then be transferred to the node's “Export Central” resources. One requirement is that the new path will only be applied to active resources, e.g. to BIN and RPC, while inactive formats should not be changed. Starting point for this helper is the Batch Simulation script, because we can find some useful concepts here like the creation of GUI input fields within loops, or the detection of empty field entries.

CREATING THE GUI The GUI is the place where we can choose directories and its only content is the scene's list of emitters. Therefore we have to collect all standard particle emitters first and loop through the resulting list: < py > emitterList = scene.get_PB_Emitters() guiForm = GUIFormDialog.new() for emitter in emitterList: guiForm.addDirectoryField(emitter.getName()+" guiForm.addDirectoryField(em itter.getName()+" export path")

The last line of code is the most interesting, but it should be familiar to you already, already, because it is what we call string concatenation. Here is a preview of the GUI with a few emitters:


88

EXPORT PATH MANAGER

EVALUATING

THE INPUT

All we have to do is to click on the appropriate folder icons (RealFlow 2015 only) and go to the desired directory. directory. Then, a loop is added where we will read out the GUIs individual fields: < py > if (guiForm.show() == GUI_DIALOG_ACCEPTED):

for i in range(0, len(emitterList)): emitter = emitterList[ emitterList[i i] emitterName = emitter.getName() fieldName = emitterName+" export path" exportPath = exportPath = guiForm.getFieldValue(fiel guiForm.getFieldValue(fieldName) dName)

The i variable is used as an index to access the list entries, but this is also a common concept now. Then, the fields' names are assembled, and finally read out and stored in exportPath. We are almost ready with this loop, but need to get an emitter's export resources:

By default, only “Particle cache (.bin)” is active, but maybe you also want to write RPC or ABC files. The script has to detect which formats are enabled, because only these will be changed. With this command we can check a node's export state – the result is printed below: exportResources = emitter.getAllExportResource emitter.getAllExportResourceValues() Values() (1, 'Particle cache (.bin)', True) (2, 'Particle proxy (.pxy)', False) (6, (3, (4, (5, (7,

'Krakatoa Particle File Format (.prt)', False) 'Particle sequence (.pd)', False) 'Particle sequence (.asc)', False) 'Particle sequence (.pdc)', False) 'Alembic sequence (.abc)', False)

(9, 'Arnold Scene Source (.ass)', False)


89

EXPORT PATH MANAGER

Each entry has its own index ranging from 0 to 2. The attribute of interest is number 2, because it tells us a whether a format is enabled (True) or nor (False). It is possible to directly access this field with its index. The first number is also important, because we can use it to address a specific export resource.

CHANGING THE EXPORT PATH Now we can check with the known != (“is not”) operator if a field is empty or not. Here is the complete script. The new parts are printed in blue: < py > emitterList = scene.get_PB_Emitters() guiForm = GUIFormDialog.new() for emitter in emitterList: guiForm.addDirectoryField(emitter.getName()+" guiForm.addDirectoryField(em itter.getName()+" export path") if (guiForm.show() == GUI_DIALOG_ACCEPTED):

for i in range(0, len(emitterList)): emitter = emitterList[ emitterList[i i] emitterName = emitter.getName() fieldName exportPath

= emitterName+" export path" = guiForm.getFieldValue(fie guiForm.getFieldValue(fieldName) ldName)

if ( (exportPath exportPath != != ""): exportResources = emitter.getAllExportResource emitter.getAllExportResourceValues() Values()

for entry in exportResources: if entry[ entry[2 2] == True: emitter.setExportResourcePath(entry[0], exportPath emitter.setExportResourcePath(entry[0 exportPath) )

Here we go through the entries of the node's export resources and address the relevant attributes – 0 and 2. Finally, the content from exportPath is inserted.


90

VELOCITIES FROM OCEAN STATISTICAL SPECTRUM WAVES


VELOCITIES FROM OCEAN STATISTICAL SPECTRUM WAVES Maybe you have already observed that ocean statistical spectrum (OSS) waves do not provide any velocity information. With RealWave, velocities can be visualized by activating the surface's “Particle layer” option. With deformers like “Fractal” or “Control Points” you can see RealFlow's typical blue and white patterns, but with “Ocean statistical spectrum” and “Gerstner” all colours remain the same during simulation. So, if you want to create meshes from the particle layer the velocity channel will remain empty and cannot be used for shading purposes. With the help of a simulation script it, on the other hand, possible to calculate the vertices' velocities.

DEFINITIONS

AND CONSIDERATIONS

Velocity is the distance s that is covered within a certain time t, and given in metres per second: velocity = s / t [m/s]

To be more precise, it is the change of position between two points in time. In physics, changes are represented with a D symbol: velocity = Ds / Dt

Our script has to calculate the differences in position between two frames (f0, f1) to get the distance, but we have to be careful with the order: Ds = positionf1 - positionf0

This also applies to time, but here it is much easier, because the time span between two frames is always the same – it is 1 frame. What we have to do is to convert this fixed time step to seconds. The length of the time span depends on the adjusted frame rate: Dt = 1.0 / FPS

Our complete formula is: velocity = (positionf1 – positionf0) / (1 / FPS)


92


INITIAL VELOCITIES The most obvious idea is to calculate the velocities and transfer them to the RealWave node's particle layer. layer. But, before we start we should take another look at this layer:

Zooming in reveals that the particles are not only located at the polygons' intersections, but also in the triangles' centres. This makes it difficult to transfer the calculated velocities to the particle layer, layer, because we do not have enough information from the vertices. It is possible to average velocities from a triangle's vertices and use the values for the centre particles, but this approach is too complex for our conceptual script. We therefore go a different route and •

•

•

introduce a “Container” node create particles at the vertices' positions add the calculated velocity to the particles.

This workflow can be seen as a particle swapping approach – something we have done already. already. Instead of particles from a different emitter we use vertices. It is important to unlink the “Container01” node from the “Relationship Editor's” default hub, and a nd set its particle type to “Dumb”. In order to speed up the simulation, go to RealFlow's SIMULATION OPTIONS > GENERAL and set both "MIN | MAX substeps" to 1. RealWave surfaces and dumb particles do not need more substeps. Now we have a clear list of tasks and can proceed with the first part of the script: initial velocities. The formula above tells us that we always need two frames, but the simulation starts at frame 0 and therefore the vertices' velocities are 0 as well. All we have to do is to apply our particle swapping algorithm in a slightly modified form. Add a new script to the “SimulationPre” branch of the “Simulation Flow” panel.


93


Here is the first part of our script: < py | simulationpre > rwSurface rwVertices emitter nullVec

= = = =

scene.getRealwave() rwSurface.getVertices() scene.get_PB_Emitter("Container01") scene.get_PB_Emitter("Contai ner01") Vector.new(0.0,0.0,0.0)

scene.enablePaint(False) emitter.removeAllParticles() for vertex in rwVertices: vPos = vertex.getPosition() emitter.addParticle(vPos, nullVec) scene.enablePaint(True)

The removeAllParticles() statement clears the emitter, because otherwise the number of particles will be increased with every start of the simulation. With scene.enablePaint(False) the creation of the particles will be very fast. Since we want to see the result during simulation, we have to reactivate RealFlow's paint function. In terms of scripting, the calculation of the changes in position is the most difficult part. The challenge is to store and keep the RealWave's vertex positions from the previous frame and use them in the current frame. A global variable is required for the positions: < py | simulationpre > # Add this line to the initial variable definitions vPositionsOld = vPositionsOld = [] # Append the blue lines to the exsiting code: for vertex in rwVertices: vPos = vertex.getPosition() emitter.addParticle(vPos, nullVec) vPositionsOld.append(vPos) scene.setGlobalVariableValue("vPositionsOld", vPositionsOld vPositionsOld) ) scene.enablePaint( True )


94


VELOCITY CALCULATIONS The global vPositionsOld can now be used in the “FramesPre” part of our script. We also need an empty list where the current positions will be stored, the time step 1.0 / FPS, and some other essentials: < py | framespre > vPositionsOld = vPositionsOld = vPositionsCur = emitter = rwSurface = rwVertices = dT

scene.getGlobalVariableValue("vPositionsOld") scene.getGlobalVariableValue("vPositionsOld") [] scene.get_PB_Emitter("Container01") scene.get_PB_Emitter("Con tainer01") scene.getRealwave() rwSurface.getVertices()

= 1.0 / scene.getFps()

emitter.removeAllParticles()

Then we start with another loop: < py | framespre > for vertex in rwVertices: vPos = vertex.getPosition()

In the next step we subtract the vertex's old position from its current position. This is again done by using the counter method from Crown Splashes.The counter is updated with every loop cycle and used as an index to extract the elements of vPositionsOld: < py | framespre > # Add this line to the initial variable definitions counter = 0 for vertex in rwVertices: vPos = vertex.getPosition() posDiff = vPos ... counter += 1

vPositionsOld[counter] vPositionsOld [counter]


95


It is time to apply our velocity formula. posDiff is a vector and therefore we have to treat its elements individually, individually, and assemble a new vector. All of the following processes happen inside the loop: < py | framespre > vPositionsOld = vPositionsOld = vPositionsCur = emitter = rwSurface = rwVertices = dT counter

scene.getGlobalVariableValue("vPositionsOld") scene.getGlobalVariableValue("vPositionsOld") [] scene.get_PB_Emitter("Container01") scene.get_PB_Emitter("Con tainer01") scene.getRealwave() rwSurface.getVertices()

= 1.0 / scene.getFps() = 0

emitter.removeAllParticles() for vertex in rwVertices: vPos = vertex.getPosition() posDiff = vPos - vPositionsOld vPositionsOld[counter] [counter] vel = Vector.new( Vector.new(posDiff posDiff.getX() .getX() / dT, posDiff posDiff.getY() .getY() / dT, posDiff posDiff.getZ() .getZ() / dT) particle = emitter.addParticle(vPos, vel)

particle.freeze() vPositionsCur.append(vPos) vPositionsCur .append(vPos) counter += 1

scene.setGlobalVariableValue("vPositionsOld scene.setGlobalVariableValue(" vPositionsOld", ", vPositionsCur vPositionsCur) )

The orange line does not only create a new particle, but stores it in a variable. You You know this notation from the Colour Blending script! In the next line, the particle's position is frozen, because we have applied a velocity and this means that the particle will be moving. Finally, Finally, we store the current position. The last line of the script uses a trick to save the current positions for the next frame, where they will be treated as the old positions: scene.setGlobalVariableValue("vPositionsOld scene.setGlobalVariableValue(" vPositionsOld", ", vPositionsCur vPositionsCur) )


96


We save the current positions and assign them as the old ones – the previous values will be overwritten and replaced. With the next frame, the global variable is read again, and so on. And here is the result of our script: a view of RealFlow's OSS waves with velocities. We can mesh these particles and include the velocity channel.

An interesting result can be achieved by disabling the emitter.removeAllParticles() statement. Then you will see the trajectories of the vertices and it is, of course, possible to mesh them as well. The result looks like an array a rray of complex knots.

IMPROVEMENTS

AND SUGGESTIONS

Here are a few more ideas for the last script: •

•

•

•

Use the velocity calculation for animated objects. Use the velocity vectors for triggering the emission of foam. Combine velocity with other attributes, e.g. height, and create complex thresholds. Write a version where the RealWave's particle layer is used for transferring the velocities. To get these particles you have to use the following statement: emitter = scene.get_PB_Emitter("RealWave01")


97

waterline magazine Scripting with RealFlow

© 2015 by Thomas Schlick | Next Limit Technologies Technologies Commercial distribution is prohibited. Translations only with permission.

Waterline Real Flow Scripting

Recommend Documents