Simulator scripting

General

Callback functions

Callback parameters

Function declaration

Simulation core and result access functions

Mel functions

Python functions


Utility script function

Mel functions

Python functions


Batch scripting

Option Vars

Simulator scripting

General


During the simulation process the user is allowed to access directly the simulator's content using some functions exported by the plugin. These functions can't be called at any point, they will work properly only when the simulator is in the appropriate internal state. The moments of time when the content can be manipulated properly are signaled by calling several callback functions, and the user is allowed to access the simulator's content only inside them. Every Phoenix simulator node has it's own script file. When the simulation starts the script is compiled and its callback function overrides the callback functions of any previous simulation. Python and Mel scripts are supported. Python was noted to be the faster of both. The Python module is build in the PhoenixFD plugin for Maya and is called phxfd.


Callback functions


There are four callback functions that must be named accordingly.


Function Description
OnSimulationBegin Called after all the initialization of the simulator is done and before first execution.
OnSimulationStep Called before each simulation step, after the interaction with the scene.
OnSimulationEnd Called after the end of the simulation just before destroying the simulation core.
OnNewFrame Called after each frame export.

 

Callback parameters


The following parameters are passed to each of the above callback functions in the same order:

 

Parameter Description
node <string> The simulator that calls the callback function
t <float> The simulator's internal time
dt <float> The simulator's internal step

 

Function declaration


Example Mel function declaration:


global proc OnSimulationBegin(string $node, float $t, float $dt)

Example Python function declaration:


def OnSimulationBegin(node, t, dt):

Simulation core and result access functions


Each of the simulation channels (temperature, velocity,smoke etc.) exists in two instances - in the simulation core and in the simulation result (i.e. cache). The functions in this section can access both the simulation core and result. If a node is passed to the access functions, the particular simulation result is accessed, otherwise the simulation core is accessed.

 

Warning! The simulation core exists only during the simulation and can be accessed only in the Callback functions.

 

 

Mel Functions

phxfdSystem [-q] [-node(-n) string] [system string]


Specify which coordinate system to be used when calling phxfdGet, phxfdInject and phxfdParticle.


-q

query the current coordinate system.

-node

determine manually the simulator node.

system

the coordinate system to set:

"object" - Object space

"world" - World space

"grid","core" - Grid space


Return value:

none

phxfdInject [-node(-n) string] -position(-pos) float float float -discharge(-d) float [-temperature(-t) float] [-smoke(-sm) float] [-fuel(-fl) float] [-velocity(-vel) float float float] [-uvw float float float]


Injects fluid in a given point. Using this function the user can create its own procedural sources. The result of the function CAN NOT be achieved by calling one or more phxfdSet functions, because they do not affect the quantity of the fluid, but only the parameters carried by the fluid. The injection of fluid in some point causes changes in the content only of the nearest 8 cells, but produces an outgoing flow in the entire grid. Nevertheless the function is not slower than the ordinary phfxSet function, because the outgoing flow appears later, when the simulation is executed. If phxfdGet function is executed immediately after phxfdInject in some near point, the velocity will be not changed.


-node

determine manually the simulator node.

-position

the position of the injection.

-discharge

the speed (not the quantity) of the discharged fluid.

-temperature

the temperature of the released fluid measured in K.

-smoke

the concentration of the "Smoke" channel.

-fuel

the concentration of the "Fuel" channel.

-velocity

the concentration of the "Velocity" channel.

-uvw

the concentration of the "UVW" channel.


Return value:

true if the operation was completed successfully, and false otherwise.

phxfdSet [-node(-n) string] -position(-pos) int int int [-temperature(-t) float] [-smoke(-sm) float] [-fuel(-fl) float] [-velocity(-vel) float float float] [-uvw float float float]


Directly set the content of a particular cell inside the grid. Note that this function works only in grid space and phxfdSystem do not have effect on it.


-node

determine manually the simulator node.

-position

the position of the cell.

-temperature

the temperature value in K.

-smoke

the value for the "Smoke" channel.

-fuel

the value for the "Fuel" channel.

-velocity

the value for the "Velocity" channel.

-uvw

the value for the "UVW" channel.


Return value:

true if the operation was completed successfully, and false otherwise.

phxfdGet [-node(-n) string] -position(-pos) float float float [-temperature(-t)] [-smoke(-sm)] [-fuel(-fl)] [-velocity(-vel)] [-uvw]


Get the content of the grid at a given point. Note that the point is in the coordinate system specified by phxfdSystem.


-node

determine manually the simulator node.

-position

the position of the content that must be accessed.

-temperature

get the temperature in K.

-smoke

get the value of the "Smoke" channel.

-fuel

get the value of the "Fuel" channel.

-velocity

get the value of the "Velocity" channel.

-uvw

get the value of the "UVW" channel.


Return value:

float[] An array of floats with the content of the grid at that point. The queued channels are return in a fixed order - temperature, smoke, fuel, velocity, uvw.

phxfFreeze -position(-pos) int int int [freeze bool] [source bool]


Freeze a cell during the simulation. The cell can be made optionally a source.


-position

the position of the cell to freeze.

freeze

if 1, the cell will be freeze, if 0 - unfreezed, default 1.

source

if 1, the cell will be marked as a source, if 0 - unmarked, default 0.


Return value:

true if the operation was completed successfully, and false otherwise.

phxfdParticle [-node(-n) string] -position(-pos) float float float -partgroup(-pg) string [-velocity(-vel) float float float] [-radius(-rad) float]


Creates particle in given position with given properties.


-node

determine manually the simulator node.

-position

the position of the new particle.

-partgroup

determine to which particle group to assign the new particle.

-velocity

set the initial velocity of the particle.

-radius

set the radius of the particle (only for foam and splashes).


Return value:

true if the operation was completed successfully, and false otherwise.

phxfdSaveCache filename string node string


Save the current content of the grid to a cache file.


filename

the cache file name.

node

the simulator node.


Return value:

true if the operation was completed successfully, and false otherwise.

 

Python Functions

setsystem system string [node string]


Specify which coordinate system to be used when calling get, inject and particle.


Return value:

true if the operation was completed successfully, and false otherwise.

getsystem [node string]


Return the current coordinate system.


Return value:

string The current coordinate system.

inject (x float, y float z float) disch float [temp float] [smoke float] [(vx float, vy float, vz float)] [(u float, v float, w float)]


Injects fluid in given point. Using this function the user can create its own procedural sources. The result of the function CAN NOT be achieved by calling one or more set functions, because they do not affect the quantity of the fluid, but only the parameters carried by the fluid. The injection of fluid in some point causes changes in the content only of the nearest 8 cells, but produces an outgoing flow in the entire grid. Nevertheless the function is not slower than the ordinary phfxSet function, because the outgoing flow appears later, when the simulation is executed. If get function is executed immediately after inject in some near point, the velocity will be not changed.


Return value:

true if the operation was completed successfully, and false otherwise.

set (cx int, cy int cz int) [temp float] [smoke float] [(vx float, vy float, vz float)] [(u float, v float, w float)] [node string]


Directly set the content of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

setT (cx int, cy int cz int) temp float [node string]


Directly set the temperature in K of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

setSm (cx int, cy int cz int) temp float [node string]


Directly set the value of the "Smoke" channel of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

setFl (cx int, cy int cz int) temp float [node string]


Directly set the value of the "Fuel" channel of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

setV (cx int, cy int cz int) temp float [node string]


Directly set the velocity of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

setUVW (cx int, cy int cz int) temp float [node string]


Directly set the value of the "UVW" channel of a particular cell inside the grid. Note that this function works only in grid space and setsystem do not have effect on it.


Return value:

true if the operation was completed successfully, and false otherwise.

get (x float, y float z float) [node string]


Get the content of the grid at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

[float float float tuple tuple] array with the content in this order - temperature, smoke, fuel, velocity, uvw.

getT (x float, y float z float) [node string]


Get the temperature in K of the grid at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

float the temperature in K.

getSm (x float, y float z float) [node string]


Get the value of the "Smoke" channel at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

float the smoke.

getFl (x float, y float z float) [node string]


Get the value of the "Fuel" channel at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

float the fuel.

getV (x float, y float z float) [node string]


Get the velocity of the grid at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

tuple the velocity.

getUVW (x float, y float z float) [node string]


Get the value of the "UVW" channel at a given point. Note that the point is in the coordinate system specified by setsystem


Return value:

tuple the uvw.

freeze (cx int, cy int cz int) [freeze bool] [source bool]


Freeze/Unfreeze the cell at a given point during the simulation, and optionally mark it as a source.


Return value:

true if the operation was completed successfully, and false otherwise.

particle group string (x float, y float z float) [(vx float, vy float, vz float)] [radius float] [node string]


Creates a particle in a given position with given properties.


Return value:

true if the operation was completed successfully, and false otherwise.

saveCache filename string [node string]


Save the current content of the grid to a cache file.


Return value:

true if the operation was completed successfully, and false otherwise.


Utility script function


These functions are not part of the simulation process, but can be used to script the functionality which is normally accessed via the GUI.


Mel Functions

phxfdSim [-q] [-node(-n) string] [-action string] [-flags(-f) int] [-fname(-fn) string] [-camera(-cam) string] [-clearbuffer(-cb) int] [-debug(-d) int]


This is the main command to control the simulator node.


-q

query a property:

no flags current state of the simulation. Can be one of the following: "none" - no simulation is running, "paused" - the simulation is paused, "running" - the simulation is running.

-node the node of the simulation that is currently running.

-debug the current debug flags

-node

determine manually the simulator node.

-action

the action to execute:

"start" - start the simulation of the specified node.

"stop" - start the current simulation.

"pause" - pause the current simulation.

"restore" - restore the simulation from the current time slider position. Use -fname to load he simulation from an arbitrary cache file.

"batch" - start the simulation in batch mode.

"batchr" - restore the simulation in batch mode.

"clearcache" - clear the output cache. Use -flags 1 to clear the resimulation cache.

"calclights" - calculate the additional lights.

"resetE" - reset the emission settings.

"resetD" - reset the diffuse settings.

"resetT" - reset the transparency settings.

"loadtempl" - load a preset. Use -fname to specify the preset file name.

"savetempl" - save a preset. Use -fname to specify the preset file name.

"savepreview" - save a GPU preview of the current frame.

-flags

specify flags, used by clearcache, loadtempl and savepreview actions.

-fname

specify a file name, used by restore, loadtempl, savetempl and savepreview actions.

-camera

specify the camera used with savepreview action.

-clearbuffer

when used with savepreview action, allows to specify if the frame buffer will be cleared before the new preview image is rendered. This can be used to draw multiple simulators to a single image.

-debug

Replace the smoke channel with debug information during the simulation:

0 - disabled, normal smoke channel

1 - frozen cells

2 - previous divergence

3, 4 - current divergence


Return value:

none

phxfdGetRoot


Return the PhoenixFD installation root path. If "." is returned, the PhoenixFD environment variable was not found. getPhoenixFDRoot will return also the fallback location.

phxfdSort camera string nodes string[]


Sort the nodes passed as the second argument based on a particular camera. This command can be used for example to determine the rendering order.


Return value:

string[] The sorted array of nodes.

phxfdSaveFramePreview nodes string[] merge int filename string cameras string[]


Saves a GPU preview for the current frame. The first argument specify a list of nodes to render. If merge is 1, the preview of all nodes will be merged to a single image, otherwise - each node will be rendered to a separate image. If filename is not empty, it allows overriding the default file name. An image will be rendered for each camera in the cameras list.

phxfdSaveAnimPreview nodes string[] startFrame int endFrame int merge int filename string cameras string[]


The same as phxfdSaveFramePreview, but allows you to specify a range of frames to render instead using the default one.

phxfdConnectRenderGizmo


With two nodes selected, this command will assign the shape node as render gizmo for the simulator/foam node.

phxfdConnectGlassGizmo


With two nodes selected, this command will assign the shape node as glass geometry for the foam node.

phxfdConnectLiqGeometry


With two nodes selected, this command will assign the shape node as liquid geometry for the foam node.

phxfdSetPreviewLights


Assign the selected lights to the preview lights of the selected simulator node.


Python Functions

start node string


Start the simulation of the specified node.

restore node string [filename string]


Restore the simulation from the current time slider position. A file can be specified to load the simulation state from.

batch node string


Start the simulation of the specified node in batch mode.

batchr node string frame int


Restore the simulation from a specified frame in batch mode.

pause


Pause the simulation.

stop


Stop the simulation.

clearcache node string [flag int]


Clear the output cache of the simulator node. If flag is 1, the resimulation cache will be cleared.

resetE


Reset the emission graph in render settings.

resetD


Reset the diffuse graph in render settings.

resetT


Reset the transparency graph in render settings.


Batch scripting

PhoenixFD can do simulation in batch mode. Like inside the GUI, only one simulation can be run at a time. The batch commands are blocking, i.e. they will return the execution to the script after finishing. This can be used to script more complicated setups, like one simulator depending on the result of another. These commands can also be run inside the GUI, but will effectively block it for interaction. Once started, they can't be stopped. However, the simulation can run slightly faster.


Batch Functions

phxfdBatchSim node string


Start simulating the specified node. The command will return when the simulation is over.

phxfdStartBatch node string startFrame int endFrame int


The same as phxfdBatchSim, but the second and third arguments override the default start/stop frame for the simulation.

phxfdBatchRestore node string startFrame int


Restore the simulation in batch mode. The second argument specify the frame from which the simulation must be restored. This is analogue to moving the time slider and clicking the "Restore" button.

phxfdBatchResim node string waiting bool


Start simulating in resimulation mode. If waiting is true, the Cache Waiting is turned on.

phxfdBatchResimRestore node string startFrame int waiting bool


Restore the resimulation in batch mode. The second argument specify the frame from which the simulation must be restored. This is analogue to moving the time slider and clicking the "Restore" button. If waiting is true, the Cache Waiting is turned on.


Example command line to launch Maya batch:


render -r vray -preRender "phxfdBatchSim(\"PhoenixFDSimulator1\")" -noRender phx_simple.ma

Option vars

Maya Option Vars

optionVar -sv "PhoenixFD_cachePath" string


Set the current cache path that will be used with the template path names.

optionVar -iv "PhoenixFD_safemode" number


Run Phoenix FD in safe mode. This will turn off the shading preview when loading new scenes to prevent display problems.