Difference between revisions of "IC Python API:Loading PFX"

From Reallusion Wiki!
Jump to: navigation, search
m (Everything Put Together)
m (Necessary Modules)
 
(3 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 Popcorn FX 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.
+
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 Popcorn FX Method ==
+
== Load PopcornFX Method ==
  
Let's create a handy load function that can be reused multiple times.  This is useful if you are loading several Popcorn FX files in one go.  We do this by search the template and custom file directories for the Particle FX file by name.  Once it is found, we load the asset file into the scene and return the object that was instantiated.
+
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. They are optional arguments because we have provided the logical default values.
+
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 Particle FX file was found!
+
         '''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.''',
Line 69: 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 Popcorn FX assets.
+
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">

Latest revision as of 20: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

Ic python api loading pfx 01.png

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

Ic python api loading pfx 02.png

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.