This page provides information on how scripting can be used with Chaos Phoenix.
Overview
During the simulation process you can directly access the simulator's content using some functions exported by the plugin. These functions can't be called at any arbitrary 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 you can access the simulator's content only inside them.
Every Phoenix Simulator node has its 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 has been noted to be the faster of the two. The Python module is built into the Phoenix plugin for Maya, and is called phxfd.
Callback Functions
There are four callback functions that must be named accordingly.
Function | Description |
| OnSimulationBegin(node, t, dt) | Called after all the initialization of the simulator is done and before first execution. |
| OnSimulationStep(node, t, dt) | Called before each simulation step, after the interaction with the scene. |
| OnSimulationEnd(node, t, dt) | Called after the end of the simulation. The simulation core would be already destroyed during this callback so it should not be accessed. |
OnNewFrame(node, t, dt) | 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 - returns a string containing the name of the simulator node. |
| t <float> | The simulator's internal time - the returned value is equal to the current frame / frames per second. |
| dt <float> | The simulator's internal step - the returned value is equal to the current time / (frames per second * steps per frame). |
Script File Example
The following example will print the name of the simulator (node) , the current time (t) and the current time step (dt). The if() statement is used to stop the simulation if the current frame is 2.
You can save the script below to a test.py file for Python or test.mel file for MEL and load it from Phoenix Simulator → Simulation → Scripting → Script File.
PYTHON 3 (used for Maya 2022 and newer):
import maya.cmds as cmds
import phxfd
def OnNewFrame(node, t, dt):
print (node)
print (t)
print (dt)
if( cmds.currentTime(query = True) == 2 ):
phxfd.stop()
PYTHON 2 (used for Maya 2020 and older):
import maya.cmds as cmds
import phxfd
def OnNewFrame(node, t, dt):
print node
print t
print dt
if( cmds.currentTime(query = True) == 2 ):
phxfd.stop()
MEL:
global proc OnNewFrame(string $node, float $t, float $dt) {
print $node;
print $t;
print $dt;
$now = `currentTime -q`;
if($now == 2){
phxfdSim -n $node -a "stop";
}
}
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.
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.
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] Inject fluid in a given point. Using this function you can create your 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.
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.
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.
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. | ||||||||||||||||
phxfdFreeze -position(-pos) int int int [ freeze bool] [ source bool] Freeze a cell during the simulation. The cell can be made optionally a source.
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] Create particle in given position with given properties.
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 an AUR or VDB cache file.
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)] [(ufloat, v float, w float)] Inject fluid in given point. Using this function you can create your 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, wfloat)] [ 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] Create 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 Functions
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(-a) string] [-flags(-f) int] [-fname(-fn) string] [-debug(-d) int] This is the main command to control the simulator node.
Return value: none | ||||||||||||
phxfdGetRoot Return the Phoenix installation root path. If "." is returned, the Phoenix 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[] Save a GPU preview for the current frame. The first argument specifies 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. | ||||||||||||
phxQuickSetup -preset(-p) int Set up a Quick Simulation with the selected object. The available options are as follows: 0 - fire 9 - tap water | ||||||||||||
phxfdAbout Returns a string with the exact Phoenix version installed. | ||||||||||||
phxfdCopyrights Returns a string with all credits and copyrights for Phoenix and all 3rd party software used. |
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
Phoenix 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 specifies the frame from which the simulation must be restored. This is analogue to moving the time slider and clicking the "Restore" button. |
phxfdBatchRestoreStop node string startFrame int endFrame int Restore the simulation in batch mode. The second argument specifies the frame from which the simulation must be restored. The third argument specifies the end frame of the Restore. |
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 specifies 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
Example command line calls to initialize Maya Batch and start a Phoenix simulation:
cd "C:\Program Files\Autodesk\Maya2017\bin"
mayabatch.exe -file "D:\PHOENIX_QA\batchSimScene.ma" -command "phxfdBatchSim(\"PhoenixFDSimulator1\")"
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 in safe mode. This will turn off the shading preview when loading new scenes to prevent display problems. |