IC Python API:Merge All Clips

From Reallusion Wiki!
Jump to: navigation, search

Main article: Sample Code Snippets.

This article will talk about using iClone 7.83's new powerful clip functionalities; specifically the Skeleton Component's MergeClips function. We will rely on this function to merge all animation clips within the timeline for a selected character.

Required Modules

This script will only need to rely on the Reallusion Python module.

import RLPy

Merging All Clips

First and foremost, we'll need a function to merge all timeline animation clips for a given avatar:

def merge_all_clips(avatar):
    skel_comp = avatar.GetSkeletonComponent()

    if skel_comp is None:
        return

    clip1 = skel_comp.GetClip(0)
    clip2 = skel_comp.GetClip(1)

    if clip1 is not None and clip2 is not None:
        result = skel_comp.MergeClips(clip1, clip2)
        if result == RLPy.RStatus.Failure:  # If clip merge fails, display an error message
            RLPy.RUi.ShowMessageBox(
                "Merge All Clips: Error",
                "\nUnknown error occured while merging clips!\nMerge operation was aborted part way.",
                RLPy.EMsgButton_Ok)
            return
        merge_all_clips(avatar)  # Recursive loop
    else:
        RLPy.RGlobal.ObjectModified(avatar, RLPy.EObjectType_Avatar)  # Force timeline update

Notice that this function recursively loops in order to continuously merge neighboring clips until there is only one left.

Running the Script

Next, let's run the above function on a selected avatar and perform the relevant checks to make sure that the selection conforms with some prerequisites. Specifically, we would only allow one avatar selected and reject empty or multiple selections, and objects of the wrong type.

def run_script():

    selected_objects = RLPy.RScene.GetSelectedObjects()

    if len(selected_objects) == 0:
        RLPy.RUi.ShowMessageBox(
            "Merge All Clips: Error",
            "\nNothing was selected!\n\nPlease select a single animated character.",
            RLPy.EMsgButton_Ok)
        return

    if selected_objects[0].GetType() != RLPy.EObjectType_Avatar:
        RLPy.RUi.ShowMessageBox(
            "Merge All Clips: Error",
            "\nNo character was selected!\n\nPlease select a single animated character.",
            RLPy.EMsgButton_Ok)
        return

    RLPy.RGlobal.BeginAction('Merge All Clips')  # Start recording an UNDO action
    merge_all_clips(selected_objects[0])
    RLPy.RGlobal.EndAction()  # Stop recording UNDO action and register as an event

Notice that we record an undo action for the merge_all_clips function. This is so that when the function is complete, the user can undo the whole process with Ctrl+Z or Edit > Undo; Essentially returning the multiple motion clips before the merging procedure.

Everything Put Together

An example of the multiple motion clips of a selected avatar.
After running the this script, the multiple motion clips combine into one.

You can copy and paste the following code into a PY file and load it into iClone via Script > Load Python. However, in order to properly load this script make sure to:

  1. Create or load a scene with one or more animated avatars.
  2. Select a single avatar with multiple animation clips in the timeline.
  3. Open the timeline track to view the multiple motion clips.
  4. Execute the script from Script > Load Python menu.

When the script is ran, the multiple motion clips should merge into one with the original animations intact.

import RLPy


def merge_all_clips(avatar):
    skel_comp = avatar.GetSkeletonComponent()

    if skel_comp is None:
        return

    clip1 = skel_comp.GetClip(0)
    clip2 = skel_comp.GetClip(1)

    if clip1 is not None and clip2 is not None:
        result = skel_comp.MergeClips(clip1, clip2)
        if result == RLPy.RStatus.Failure:  # If clip merge fails, display an error message
            RLPy.RUi.ShowMessageBox(
                "Merge All Clips: Error",
                "\nUnknown error occured while merging clips!\nMerge operation was aborted part way.",
                RLPy.EMsgButton_Ok)
            return
        merge_all_clips(avatar)  # Recursive loop
    else:
        RLPy.RGlobal.ObjectModified(avatar, RLPy.EObjectType_Avatar)  # Force timeline update


def run_script():

    selected_objects = RLPy.RScene.GetSelectedObjects()

    if len(selected_objects) == 0:
        RLPy.RUi.ShowMessageBox(
            "Merge All Clips: Error",
            "\nNothing was selected!\n\nPlease select a single animated character.",
            RLPy.EMsgButton_Ok)
        return

    if selected_objects[0].GetType() != RLPy.EObjectType_Avatar:
        RLPy.RUi.ShowMessageBox(
            "Merge All Clips: Error",
            "\nNo character was selected!\n\nPlease select a single animated character.",
            RLPy.EMsgButton_Ok)
        return

    RLPy.RGlobal.BeginAction('Merge All Clips')  # Start recording an UNDO action
    merge_all_clips(selected_objects[0])
    RLPy.RGlobal.EndAction()  # Stop recording UNDO action and register as an event

APIs Used

You can research the following references for the APIs deployed in this code.