Difference between revisions of "IC Python API:Loading PFX"
From Reallusion Wiki!
Chuck (RL) (Talk | contribs) m (→File Not Found Messaging) |
Chuck (RL) (Talk | contribs) m (→Necessary Modules) |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
{{Parent|IC_Python_API:RL_Python_Samples|RL Python Samples}} | {{Parent|IC_Python_API:RL_Python_Samples|RL Python Samples}} | ||
| − | This article will show you how to load | + | This article will show you how to load PopcornFX assets into the scene from the template and custom library paths. This lesson is applicable for other asset types such as Avatars, Props, Terrains, and more; as long as you know where the asset file directories are located. |
== Necessary Modules == | == Necessary Modules == | ||
| − | Besides the rudimentary Reallusion Python module, we'll also need the '''os'' module to read from the windows file system. | + | Besides the rudimentary Reallusion Python module, we'll also need the '''os''' module to read from the windows file system. |
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
| Line 13: | Line 13: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == Load | + | == Load PopcornFX Method == |
| − | Let's create a handy load function that can be reused multiple times. This is useful if you are loading several | + | Let's create a handy load function that can be reused multiple times. This is useful if you are loading several PopcornFX files in one go. We do this by search the template and custom file directories for the PopcornFX file by name. Once it is found, we load the asset file into the scene and return the object that was instantiated. |
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
| Line 45: | Line 45: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | Notice that some useful arguments have been included to assist in the search. | + | Notice that some useful arguments have been included to assist in the search. They are optional arguments because we have provided the logical default values. |
== File Not Found Messaging == | == File Not Found Messaging == | ||
| Line 57: | Line 57: | ||
RLPy.RUi.ShowMessageBox( | RLPy.RUi.ShowMessageBox( | ||
"PFX File Not Found", | "PFX File Not Found", | ||
| − | '''No matching Popcorn | + | '''No matching Popcorn ParticleFX file was found! |
Please check the file name for errors | Please check the file name for errors | ||
and capitalization for case-sensitive search.''', | and capitalization for case-sensitive search.''', | ||
RLPy.EMsgButton_Ok) | RLPy.EMsgButton_Ok) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| + | |||
| + | This segment of code is final part of the '''LoadPopcornFX''' method. | ||
== Example Usage == | == Example Usage == | ||
| Line 67: | Line 69: | ||
[[File:Ic_python_api_loading_pfx_02.png|frame]] | [[File:Ic_python_api_loading_pfx_02.png|frame]] | ||
| − | Now that we have a handy reusable method, we can call it multiple times to load various | + | Now that we have a handy reusable method, we can call it multiple times to load various PopcornFX assets. After loading the PFX files, you should playback to view the particles effects in action. |
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
| Line 74: | Line 76: | ||
text_fx_01 = LoadPopcornFX("LED Text") | text_fx_01 = LoadPopcornFX("LED Text") | ||
text_fx_02 = LoadPopcornFX("LED Text") | text_fx_02 = LoadPopcornFX("LED Text") | ||
| + | error_fx = LoadPopcornFX("Non-existing PFX") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Notice that assigning a loaded asset does not need to be assigned to a variable -the returned value is simply discarded. Also the same particle file can be called multiple times for multiple instantiations. | Notice that assigning a loaded asset does not need to be assigned to a variable -the returned value is simply discarded. Also the same particle file can be called multiple times for multiple instantiations. | ||
| + | |||
| + | == Everything Put Together == | ||
| + | |||
| + | You can copy and paste the following code into a PY file and load it into iClone via '''Script > Load Python'''. | ||
| + | |||
| + | <syntaxhighlight lang="python"> | ||
| + | import RLPy | ||
| + | import os | ||
| + | |||
| + | |||
| + | def LoadPopcornFX(name, case_sensitive=True, template_first=True): | ||
| + | ''' | ||
| + | Load a PopcornFX file by it's name (without the extension). | ||
| + | |||
| + | Args: | ||
| + | name (String): The name of the PFX file without the extension. | ||
| + | case_sensitive (Bool): Whether or not to use case sensitive search. | ||
| + | template_first (Bool): Changes the search priority between Template and Custom paths | ||
| + | |||
| + | Returns: | ||
| + | RIObject: A reference to the PFX object loaded into the scene. | ||
| + | ''' | ||
| + | template_data_path = RLPy.RApplication.GetTemplateDataPath() | ||
| + | template_data_path += '\\iClone Template\\Particle\\' | ||
| + | |||
| + | custom_data_path = RLPy.RApplication.GetCustomDataPath() | ||
| + | custom_data_path += '\\Particle\\' | ||
| + | |||
| + | for directory in [template_data_path, custom_data_path] if template_first else [custom_data_path, template_data_path]: | ||
| + | for root, dirs, files in os.walk(directory): | ||
| + | for f in files: | ||
| + | if f == name+".iPkfx" if case_sensitive else f.lower() == name.lower()+".ipkfx": | ||
| + | popcornfx_file_path = os.path.join(root, f) | ||
| + | load_object = RLPy.RFileIO.LoadObject(popcornfx_file_path) | ||
| + | return load_object | ||
| + | |||
| + | # No matching file was found -notify the user | ||
| + | RLPy.RUi.ShowMessageBox( | ||
| + | "PFX File Not Found", | ||
| + | '''No matching Popcorn Particle FX file was found! | ||
| + | Please check the file name for errors | ||
| + | and capitalization for case-sensitive search.''', | ||
| + | RLPy.EMsgButton_Ok) | ||
| + | |||
| + | |||
| + | LoadPopcornFX("DOF Kidneys") | ||
| + | explosion_fx = LoadPopcornFX("Explosion") | ||
| + | text_fx_01 = LoadPopcornFX("LED Text") | ||
| + | text_fx_02 = LoadPopcornFX("LED Text") | ||
| + | error_fx = LoadPopcornFX("Non-existing PFX") | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | == APIs Used == | ||
| + | |||
| + | You can research the following references for the APIs deployed in this code. | ||
| + | |||
| + | <div style="column-count:4; -moz-column-count:4; -webkit-column-count:4"> | ||
| + | * [[ IC_Python_API:RLPy_RApplication#GetTemplateDataPath | RLPy.RApplication.GetTemplateDataPath() ]] | ||
| + | * [[ IC_Python_API:RLPy_RApplication#GetCustomDataPath | RLPy.RApplication.GetCustomDataPath() ]] | ||
| + | * [[ IC_Python_API:RLPy_RFileIO#LoadObject | RLPy.RFileIO.LoadObject() ]] | ||
| + | * [[ IC_Python_API:RLPy_RUi#ShowMessageBox | RLPy.RUi.ShowMessageBox() ]] | ||
| + | </div> | ||
Latest revision as of 19:29, 19 December 2019
- Main article: RL Python Samples.
This article will show you how to load PopcornFX assets into the scene from the template and custom library paths. This lesson is applicable for other asset types such as Avatars, Props, Terrains, and more; as long as you know where the asset file directories are located.
Necessary Modules
Besides the rudimentary Reallusion Python module, we'll also need the os module to read from the windows file system.
import RLPy
import os
Load PopcornFX Method
Let's create a handy load function that can be reused multiple times. This is useful if you are loading several PopcornFX files in one go. We do this by search the template and custom file directories for the PopcornFX file by name. Once it is found, we load the asset file into the scene and return the object that was instantiated.
def LoadPopcornFX(name, case_sensitive=True, template_first=True):
'''
Load a PopcornFX file by it's name (without the extension).
Args:
name (String): The name of the PFX file without the extension.
case_sensitive (Bool): Whether or not to use case sensitive search.
template_first (Bool): Changes the search priority between Template and Custom paths
Returns:
RIObject: A reference to the PFX object loaded into the scene.
'''
template_data_path = RLPy.RApplication.GetTemplateDataPath()
template_data_path += '\\iClone Template\\Particle\\'
custom_data_path = RLPy.RApplication.GetCustomDataPath()
custom_data_path += '\\Particle\\'
for directory in [template_data_path, custom_data_path] if template_first else [custom_data_path, template_data_path]:
for root, dirs, files in os.walk(directory):
for f in files:
if f == name+".iPkfx" if case_sensitive else f.lower() == name.lower()+".ipkfx":
popcornfx_file_path = os.path.join(root, f)
load_object = RLPy.RFileIO.LoadObject(popcornfx_file_path)
return load_object
Notice that some useful arguments have been included to assist in the search. They are optional arguments because we have provided the logical default values.
File Not Found Messaging
Next, we should tell the user if the file has not been found. This is done with a simple modal message window.
# No matching file was found -notify the user
RLPy.RUi.ShowMessageBox(
"PFX File Not Found",
'''No matching Popcorn ParticleFX file was found!
Please check the file name for errors
and capitalization for case-sensitive search.''',
RLPy.EMsgButton_Ok)
This segment of code is final part of the LoadPopcornFX method.
Example Usage
Now that we have a handy reusable method, we can call it multiple times to load various PopcornFX assets. After loading the PFX files, you should playback to view the particles effects in action.
LoadPopcornFX("DOF Kidneys")
explosion_fx = LoadPopcornFX("Explosion")
text_fx_01 = LoadPopcornFX("LED Text")
text_fx_02 = LoadPopcornFX("LED Text")
error_fx = LoadPopcornFX("Non-existing PFX")
Notice that assigning a loaded asset does not need to be assigned to a variable -the returned value is simply discarded. Also the same particle file can be called multiple times for multiple instantiations.
Everything Put Together
You can copy and paste the following code into a PY file and load it into iClone via Script > Load Python.
import RLPy
import os
def LoadPopcornFX(name, case_sensitive=True, template_first=True):
'''
Load a PopcornFX file by it's name (without the extension).
Args:
name (String): The name of the PFX file without the extension.
case_sensitive (Bool): Whether or not to use case sensitive search.
template_first (Bool): Changes the search priority between Template and Custom paths
Returns:
RIObject: A reference to the PFX object loaded into the scene.
'''
template_data_path = RLPy.RApplication.GetTemplateDataPath()
template_data_path += '\\iClone Template\\Particle\\'
custom_data_path = RLPy.RApplication.GetCustomDataPath()
custom_data_path += '\\Particle\\'
for directory in [template_data_path, custom_data_path] if template_first else [custom_data_path, template_data_path]:
for root, dirs, files in os.walk(directory):
for f in files:
if f == name+".iPkfx" if case_sensitive else f.lower() == name.lower()+".ipkfx":
popcornfx_file_path = os.path.join(root, f)
load_object = RLPy.RFileIO.LoadObject(popcornfx_file_path)
return load_object
# No matching file was found -notify the user
RLPy.RUi.ShowMessageBox(
"PFX File Not Found",
'''No matching Popcorn Particle FX file was found!
Please check the file name for errors
and capitalization for case-sensitive search.''',
RLPy.EMsgButton_Ok)
LoadPopcornFX("DOF Kidneys")
explosion_fx = LoadPopcornFX("Explosion")
text_fx_01 = LoadPopcornFX("LED Text")
text_fx_02 = LoadPopcornFX("LED Text")
error_fx = LoadPopcornFX("Non-existing PFX")
APIs Used
You can research the following references for the APIs deployed in this code.
