Difference between revisions of "IC7 Python API"

From Reallusion Wiki!
Jump to: navigation, search
m (See Also)
m (Sample Code Snippets)
(44 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
Scripting can be  powerful tool in your arsenal for dealing with 3D art production.  Whether you are looking for a way to automate some parts of your workflow or develop more advanced tool-kits and plugins, scripting can offer something for everyone.  With the iClone Python API, one has access to the powerful low level implementations hidden within iClone, while abstracting its complexity to a manageable level.
 
Scripting can be  powerful tool in your arsenal for dealing with 3D art production.  Whether you are looking for a way to automate some parts of your workflow or develop more advanced tool-kits and plugins, scripting can offer something for everyone.  With the iClone Python API, one has access to the powerful low level implementations hidden within iClone, while abstracting its complexity to a manageable level.
 
=== Disclaimer ===
 
  
 
{{Notice|Reallusion cannot be held responsible for any damages to your code or project-schedule as a result of your study and use of this documentation or correspondence with our SDK support team. Reallusion is not obliged to make any changes to the SDK at your request. When using this reference or inquiring for support, you do so at your own risk.
 
{{Notice|Reallusion cannot be held responsible for any damages to your code or project-schedule as a result of your study and use of this documentation or correspondence with our SDK support team. Reallusion is not obliged to make any changes to the SDK at your request. When using this reference or inquiring for support, you do so at your own risk.
 
}}
 
}}
  
== Why Python? ==
+
=== Why Python? ===
  
 
Python is a general-purpose language, which means it can be used to build just about anything - a process made easy with the right tools and code libraries. Professionally, Python is great for backend web development, data analysis, artificial intelligence, and scientific computing. Many developers have also used Python to build productivity tools, games, and desktop apps, so there are plenty of resources to help you learn how to create those as well.
 
Python is a general-purpose language, which means it can be used to build just about anything - a process made easy with the right tools and code libraries. Professionally, Python is great for backend web development, data analysis, artificial intelligence, and scientific computing. Many developers have also used Python to build productivity tools, games, and desktop apps, so there are plenty of resources to help you learn how to create those as well.
  
 
Python is easy to pick up for experienced programmers coming from other languages and easy to learn for beginners and novices.  Which can also explain its wide-spread support with 3D software with the likes of Autodesk 3dsMax, Autodesk Maya, Maxon Cinema4d, Blender, etc.
 
Python is easy to pick up for experienced programmers coming from other languages and easy to learn for beginners and novices.  Which can also explain its wide-spread support with 3D software with the likes of Autodesk 3dsMax, Autodesk Maya, Maxon Cinema4d, Blender, etc.
 +
 +
== Module & Class Documentation ==
 +
 +
{| class = "wikitable"
 +
!Resource
 +
!Article
 +
|-
 +
|Categorized Python reference manual.
 +
|[[iC_Python_API:RL_Python_Modules | Reallusion Python Modules]]
 +
|-
 +
|Python Modules in alphabetical order.
 +
|[[IC_Python_API:RL_Python_Modules_Ordered_List | Python Modules Ordered List]]
 +
|-
 +
|Class members listed in alphabetical order.
 +
|[[iC_Python_API:RL_Python_Class_Members | Reallusion Python Class Members]]
 +
|-
 +
|Existing enumerations in the RLPy namespace.
 +
|[[IC_Python_API:Enums | Reallusion Python Enumerations]]
 +
|}
  
 
== Getting Started ==
 
== Getting Started ==
Line 30: Line 47:
  
 
{| class = "wikitable"
 
{| class = "wikitable"
!Topic
+
!width=200|Topic
 
!Purpose
 
!Purpose
 
|-
 
|-
|[[iC_Python_API:Capabilities_And_Limitations|Capabilities and Limitations]]
+
|[[iC_Python_API:Uses_and_Capabilities|Uses and Capabilities]]
|Understand what you can or can't do in iClone with the current Python API set.
+
|Understand what you can do in iClone with the current Python API set.
 
|-
 
|-
 
|[[iC_Python_API:Your_First_iClone_Python_Plugin|Your First iClone Python Plugin]]
 
|[[iC_Python_API:Your_First_iClone_Python_Plugin|Your First iClone Python Plugin]]
 
|Learn to prepare your IDE (Integrated Development Environment) for Python and produce your first "Hello World" program for iClone.
 
|Learn to prepare your IDE (Integrated Development Environment) for Python and produce your first "Hello World" program for iClone.
 
|-
 
|-
|[[iC_Python_API:Using_Pyside2_For_Creating_User_Interface|Using Pyside 2 for Creating User Interface]]
+
|[[iC_Python_API:Using_Pyside2_For_Creating_User_Interface|Using Pyside 2 for Creating U.I.]]
 
|Learn to create a simple dialog window with PySide 2.0 module for Python 3.6.2.
 
|Learn to create a simple dialog window with PySide 2.0 module for Python 3.6.2.
 
|-
 
|-
Line 53: Line 70:
 
|[[iC_Python_API:Python_Extension_Libraries|Python Extension Libraries]]
 
|[[iC_Python_API:Python_Extension_Libraries|Python Extension Libraries]]
 
|Get informed about Python package manager and recommended modules.
 
|Get informed about Python package manager and recommended modules.
 +
|}
 +
 +
== Python Samples ==
 +
 +
The following samples demonstrate the use of the iClone Python API for creating simple and useful tools, including the implementation of major APIs exposed in iClone. If you are new to Python scripting or the iClone scripting environment, we recommend that you start off with the novice and fundamental level lessons.
 +
 +
=== Python of the Month ===
 +
 +
Python of the Month are monthly to bi-monthly lessons on various topics with the sole purpose of getting you up to speed on the various features of the iClone Python API.  Each lesson comes with a plugin script as well as five fundamental lessons that are based on the content within the plugin script.
 +
 +
{| class = "wikitable"
 +
!Release Date
 +
!Plugin Script
 +
!Fundamentals I
 +
!Fundamentals II
 +
!Fundamentals III
 +
!Fundamentals IV
 +
!Fundamentals V
 
|-
 
|-
|[[iC_Python_API:Novice_Level_Examples|Novice Level Examples]]
+
! scope="row"| June, 2019
|rowspan="3"|Samples to the left demonstrate the use of the iClone Python API for creating simple and useful tools, including the implementation of major APIs exposed in iClone. If you are new to Python scripting or the iClone scripting environment, we recommend that you start off with the basic level lessons.  Each section includes a couple of lessons suitable for the difficulty level, a video summary of the operational workflow, and a link to the GitHUB page where you can gather the source code and example files to get started.
+
|[[ iC_Python_API:Smooth_Camera_Follow|Smooth Camera Follow]]
 +
|[[ iC_Python_API:List_All_Props | List All Props ]]
 +
|[[ iC_Python_API:3D_Look_At | 3D Look At ]]
 +
|[[ iC_Python_API:Transformation_Key | Transformation Key ]]
 +
|[[ iC_Python_API:Linear_Interpolation| Linear Interpolation ]]
 +
|[[ iC_Python_API:Float_Slider| Float Slider ]]
 
|-
 
|-
|[[iC_Python_API:Intermediate_Level_Examples|Intermediate Level Examples]]
+
! scope="row"| July, 2019
 +
|[[ iC_Python_API:Audio_Driven|Audio Driven]]
 +
|[[ iC_Python_API:Progress_Bar | Progress Bar ]]
 +
|[[ iC_Python_API:Animated_Material | Animated Material ]]
 +
|[[ iC_Python_API:Audio_Visualizer | Audio Visualizer ]]
 +
|[[ iC_Python_API:File_Path | File Path ]]
 +
|[[ iC_Python_API:Color_Picker | Color Picker ]]
 
|-
 
|-
|[[iC_Python_API:Advanced_Level_Examples|Advanced Level Examples]]
+
! scope="row"| August, 2019
 +
|[[ iC_Python_API:Camera_Auto-Focus|Camera Auto-Focus]]
 +
|[[ iC_Python_API:Stopwatch | Stopwatch ]]
 +
|[[ iC_Python_API:Bounding_Info | Bounding Info ]]
 +
|[[ iC_Python_API:Linked_Controls | Linked Controls ]]
 +
|[[ iC_Python_API:Blurry_Vision | Blurry Vision ]]
 +
|[[ iC_Python_API:Align_to_Camera | Align to Camera ]]
 +
|-
 +
! scope="row"| November, 2019
 +
|[[ iC_Python_API:Camera_Dolly_Zoom|Camera Dolly Zoom]]
 +
|[[ iC_Python_API:Object_Type | Object Type ]]
 +
|[[ iC_Python_API:Message_Box | Message Box ]]
 +
|[[ iC_Python_API:Item_Lister | Item Lister ]]
 +
|[[ iC_Python_API:Dialog_Callbacks | Dialog Callbacks ]]
 +
|[[ iC_Python_API:Local_Move | Local Move ]]
 +
|-
 +
! scope="row"| December, 2019
 +
|[[ iC_Python_API:PopcornFX_Sequencer | PopcornFX Sequencer ]]
 +
|[[ iC_Python_API:Table_View | Table View ]]
 +
|[[ iC_Python_API:Tree_View | Tree View ]]
 +
|[[ iC_Python_API:Plugin_Window | Plugin Window ]]
 +
|bgcolor="lightyellow"|[[ iC_Python_API:Loading_PFX | Loading PFX ]]
 +
|bgcolor="lightyellow"|[[ iC_Python_API:Loading_JSON | Loading JSON ]]
 +
|-
 +
! scope="row"| February, 2020
 +
|[[ iC_Python_API:Spring_Joints | Spring Joints ]]
 +
|[[ iC_Python_API:Transform_Math | Transform Math ]]
 +
|[[ iC_Python_API:Rotation_Math | Rotation Math ]]
 +
|[[ iC_Python_API:Error_Handling | Error Handling ]]
 +
|[[ iC_Python_API:Handling_Time | Handling Time ]]
 +
|[[ iC_Python_API:Basic_Math | Basic Math ]]
 +
|-
 +
! scope="row"| March, 2020
 +
|[[ iC_Python_API:Pose_Manager | Pose Manager ]]
 +
|[[ iC_Python_API:List_View | List View]]
 +
|[[ iC_Python_API:Icons_and_Images | Icons and Images ]]
 +
|[[ iC_Python_API:Serialize_Pose | Serialize Pose]]
 +
|[[ iC_Python_API:Screenshotting | Screenshotting]]
 +
|[[ iC_Python_API:Saving_JSON | Saving JSON ]]
 
|}
 
|}
 +
 +
<span style="background-color:lightyellow">Cells in light yellow</span> are lessons derived from full-fledged paid versions, but they are still useful on their own.  For a better understanding on how they integrate into the bigger picture, you might be interested in purchasing the fully-featured scripts from the [https://marketplace.reallusion.com/iclone/plug-in Reallusion Marketplace]. For more information see the '''Python of Month''' script article for the corresponding month.
 +
 +
=== Various Lessons ===
 +
 +
These lessons come in the form of free plugins.  They are classified into different difficulty levels:
 +
 +
*'''Novice''': Recommended for those who may be new to scripting and are not familiar with the iClone API library.
 +
*'''Intermediate''': Recommended for those have made an effort of understanding the iClone API and are getting comfortable with Python.
 +
*'''Advanced''': Recommended for those who have deep knowledge of the iClone API and are proficient with Python.
 +
 +
{| class = "wikitable"
 +
!Difficulty Level
 +
!Script
 +
!Description
 +
|-
 +
!scope="row"|Novice
 +
|[[iC_Python_API:Batch_Render_Folder|Batch Render Folder]]
 +
| Takes multiple iClone projects within a directory and renders each one to a separate video.
 +
|-
 +
!scope="row"|Novice
 +
|[[iC_Python_API:Joint_Driven_Morph|Joint Driven Morph]]
 +
| Drive morph targets via real-time rotation of bone joints.
 +
|-
 +
!scope="row"|Intermediate
 +
|[[iC_Python_API:Group_Manager|Group Manager]]
 +
| A utility that creates layer controls for iClone.
 +
|-
 +
!scope="row"|Intermediate
 +
|[[iC_Python_API:Musical_Keyboard|Musical Keyboard]]
 +
| Creates key-press events that can respond in real-time.
 +
|-
 +
!scope="row"|Advanced
 +
|[[iC_Python_API:Light_Remote_Control|Light Remote Control]]
 +
| Implements Internet of Things to drive functions within the iClone application itself.
 +
|-
 +
!scope="row"|Advanced
 +
|[[iC_Python_API:Hand_Gestures_Puppeteering|Hand Gestures Puppeteering]]
 +
| Provides an intuitive graphical user interface to drive the hand gestures of a character.
 +
|}
 +
 +
=== Sample Code Snippets ===
 +
 +
These samples are recommended for those who may have working knowledge of the iClone API but would like to digest certain ways of accomplishing specific tasks in piecemeal.
 +
 +
*[[ iC_Python_API:Basic_Animation| Basic Animation]]
 +
*[[ iC_Python_API:Managing_Time | Managing Time ]]
 +
*[[ iC_Python_API:Loading_All_Props | Loading All Props ]]
 +
*[[ iC_Python_API:Using_Temp_Data | Using Temp Data ]]
 +
*[[ iC_Python_API:Embedding_QML | Embedding QML ]]
 +
*[[ iC_Python_API:Merge_All_Clips | Merge All Clips]]
 +
 +
=== External Resources ===
 +
 +
*[https://www.python.org/ Python.org]
 +
*[https://wiki.qt.io/Qt_for_Python Qt for Python (PySide2)]
 +
*[https://github.com/reallusion/iclone Reallusion GitHub]
  
 
== Release Cycles ==
 
== Release Cycles ==

Revision as of 19:03, 18 November 2020

Main article: Main Page.

Scripting can be powerful tool in your arsenal for dealing with 3D art production. Whether you are looking for a way to automate some parts of your workflow or develop more advanced tool-kits and plugins, scripting can offer something for everyone. With the iClone Python API, one has access to the powerful low level implementations hidden within iClone, while abstracting its complexity to a manageable level.

⚠ Reallusion cannot be held responsible for any damages to your code or project-schedule as a result of your study and use of this documentation or correspondence with our SDK support team. Reallusion is not obliged to make any changes to the SDK at your request. When using this reference or inquiring for support, you do so at your own risk.

Why Python?

Python is a general-purpose language, which means it can be used to build just about anything - a process made easy with the right tools and code libraries. Professionally, Python is great for backend web development, data analysis, artificial intelligence, and scientific computing. Many developers have also used Python to build productivity tools, games, and desktop apps, so there are plenty of resources to help you learn how to create those as well.

Python is easy to pick up for experienced programmers coming from other languages and easy to learn for beginners and novices. Which can also explain its wide-spread support with 3D software with the likes of Autodesk 3dsMax, Autodesk Maya, Maxon Cinema4d, Blender, etc.

Module & Class Documentation

Resource Article
Categorized Python reference manual. Reallusion Python Modules
Python Modules in alphabetical order. Python Modules Ordered List
Class members listed in alphabetical order. Reallusion Python Class Members
Existing enumerations in the RLPy namespace. Reallusion Python Enumerations

Getting Started

iClone Conventions

Keep the following conventions in mind when dealing with the iClone environment:

See Also

Topic Purpose
Uses and Capabilities Understand what you can do in iClone with the current Python API set.
Your First iClone Python Plugin Learn to prepare your IDE (Integrated Development Environment) for Python and produce your first "Hello World" program for iClone.
Using Pyside 2 for Creating U.I. Learn to create a simple dialog window with PySide 2.0 module for Python 3.6.2.
Controlling a Simple Prop Information on loading a file, adding a transform key, changing material parameters and rendering to video.
Animating a Character Introduction to controlling character animation via Python script.
iClone Events System Learn to use iClone events to trigger callback functions.
Python Extension Libraries Get informed about Python package manager and recommended modules.

Python Samples

The following samples demonstrate the use of the iClone Python API for creating simple and useful tools, including the implementation of major APIs exposed in iClone. If you are new to Python scripting or the iClone scripting environment, we recommend that you start off with the novice and fundamental level lessons.

Python of the Month

Python of the Month are monthly to bi-monthly lessons on various topics with the sole purpose of getting you up to speed on the various features of the iClone Python API. Each lesson comes with a plugin script as well as five fundamental lessons that are based on the content within the plugin script.

Release Date Plugin Script Fundamentals I Fundamentals II Fundamentals III Fundamentals IV Fundamentals V
June, 2019 Smooth Camera Follow List All Props 3D Look At Transformation Key Linear Interpolation Float Slider
July, 2019 Audio Driven Progress Bar Animated Material Audio Visualizer File Path Color Picker
August, 2019 Camera Auto-Focus Stopwatch Bounding Info Linked Controls Blurry Vision Align to Camera
November, 2019 Camera Dolly Zoom Object Type Message Box Item Lister Dialog Callbacks Local Move
December, 2019 PopcornFX Sequencer Table View Tree View Plugin Window Loading PFX Loading JSON
February, 2020 Spring Joints Transform Math Rotation Math Error Handling Handling Time Basic Math
March, 2020 Pose Manager List View Icons and Images Serialize Pose Screenshotting Saving JSON

Cells in light yellow are lessons derived from full-fledged paid versions, but they are still useful on their own. For a better understanding on how they integrate into the bigger picture, you might be interested in purchasing the fully-featured scripts from the Reallusion Marketplace. For more information see the Python of Month script article for the corresponding month.

Various Lessons

These lessons come in the form of free plugins. They are classified into different difficulty levels:

Difficulty Level Script Description
Novice Batch Render Folder Takes multiple iClone projects within a directory and renders each one to a separate video.
Novice Joint Driven Morph Drive morph targets via real-time rotation of bone joints.
Intermediate Group Manager A utility that creates layer controls for iClone.
Intermediate Musical Keyboard Creates key-press events that can respond in real-time.
Advanced Light Remote Control Implements Internet of Things to drive functions within the iClone application itself.
Advanced Hand Gestures Puppeteering Provides an intuitive graphical user interface to drive the hand gestures of a character.

Sample Code Snippets

These samples are recommended for those who may have working knowledge of the iClone API but would like to digest certain ways of accomplishing specific tasks in piecemeal.

External Resources

Release Cycles

We are constantly working on improving the coverage of our Python APIs, so we want to move to shorter release cycles. Rather than releasing major versions over longer periods of time, we will aim to build, test, and release updates more frequently.

With continuous delivery, we can exercise the option to include early access and experimental features in each release that are in early to intermediate stages of development. This strategy allows us get feedback for a feature while it is being worked on it, in turn we learn more about what you want in the final product. There will be two main types of feature releases:

Retrieved from "https://wiki.reallusion.com/index.php?title=IC7_Python_API&oldid=4832"