Difference between revisions of "IC Python API:Uses and Capabilities"

Revision as of 04:04, 25 December 2019

The iClone Python API helps you to extend and customize iClone, and more easily integrate it into a Python-based pipeline. It provides a bridge between iClone and Python libraries and Python tools. The Python SDK is built on top of the iClone C++ SDK, and you can access a subset of the iClone API from Python scripts and execute them in iClone.

The iClone Python API can do the following:

	Std(G5, CC, etc.)	Non-Std	Non-Human	Prop	Camera	Light
	Character			Prop	Camera	Light
Transformation (RTS)	7.4	7.4	7.4	7.4	7.4	7.4
Facial Expression	7.4 Mo-cap Module	7.4 Mo-cap Module	-	-	-	-
Morph Animation	7.4 Experimental	7.4 Experimental	7.4 Experimental	7.4 Experimental		-
Material	7.4 Experimental	7.4 Experimental	7.4 Experimental	7.4 Experimental		7.4 Experimental
Parameters	-	-	-	-	7.4 Experimental	7.4 Experimental

Capabilities

As the iClone Python API continues to evolve, additional capabilities will be added over time. Below are lists of iClone Python API's current capabilities categorized by version number. The lists below are by no means exhaustive.

Version 0.7

[Expand]

iClone 7.4 Open Change Log

Version 0.7.1

[Expand]

iClone 7.41 Open Change Log: 01/17/2019 - 01/31/2019

LocalTransform & WorldTransform	Fixed incorrect transform rotations for RIObject, RIAvatar, RIProp, RILight, RICamera.
RINode::WorldTransform	New WorldTransform for RINode; No need for the user to write a function to retrieve it.
Rkey	New RKey can be used to carry additional data such as Time, TransitionType, and TransitionStrength.
Material Component	Fixed kTime > kKey for the MaterialComponent; Besides setting the frame time, one can also set the Transition Type and Strength.
LoadImageToTexture	Ability to load texture images to any channel within a material accessible via Mesh > Material Name.
RIHikEffectorComponent	Established framework for the RIHikEffoectorComponent API and test case is provided (not yet implemented).
Ignore API	Fixed RAudio:SetAudioPtr and RScene:SetScenePtr not being ignored (currently the online documentation also has this problem).
RApplication class	New RApplication class can retreive registry related data and API version number. Test case has been added.
RIObject::SetParent(RIObject/RINode)	All classes that derive from RIObject also inherit the SetParent member function.
RIObject::LinkTo(RIObject, RTime)	All classes that derive from RIObject also inherit the LinkTo member function.
RIObject::Unlink(RTime)	All classes that derive from RIObject also inherit the Unlink member function.
RIFaceComponent::GetKey(args)	Used to retrieve the current time's Facial Expression, Eye, and Head key values. Usage: RIFaceComponent::GetKey(RTime, Head, LeftEye, RightEye, Morph, Custom, Bone, Weight)
RIFaceComponent::AddClip(RTime)	Adds a default Facial clip at the designated point in time.
RIFaceComponent::AddEyeKey()	Create a EyeKey under the Facial Layer.
RIFaceComponent::AddHeadKey()	Create a HeadKey under the Facial Layer.
RIFaceComponent::AddExpressionKey()	Create a ExpressionKey under the Facial Layer.
RIFaceComponent::AddVisemeKey()	Create a LipsKey under the Viseme layer.
RIObject::SetName(std::wstring)	Used to change the name of an object.
RIObject::GetPivot()	All classes that derive from RIObject also inherit the GetPivot member function.
RIObject::SetPivot()	Provides a way to retrieve the pivot point of a prop.
RIObject::GetBounds()	All classes that derive from RIObject also inherit the GetBounds member function.

Version 0.7.2

[Expand]

iClone 7.41 Open Change Log: 02/15/2019 - 02/27/2019

Version 0.7.3

[Expand]

iClone 7.4x Open Change Log: 03/03/2019 - 04/29/2019

RO::EHikEffector	Provide the same number as the core Hik enumeration that is aligned with RLHumanIK \ RLHikDef.h (the old version was aligned to ICInterfaceEnumDef.h). This fix is applied to both LeftHandThumb and RightFootExtraFinger enums.
RO::EHikEffectorType enum(Translate/Rotate)	Provide settings for HIK effector translate / rotate.
RMatrix4 RINode::WorldToLocal( RMatrix4 kWorld )	Used to convert the input world space matrix into a local space matrix relative to this node.
RMatrix4 RINode::LocalToWorld( RMatrix4 kWorld )	Used to convert the input local space matrix into a matrix in actual wolrd space.
Modified RISkeletonComponent::GetSkinBones	Fixed the problem of not returning all the skin bones. The original method will only have 54 Bone (CC), but it should be more than this.
Modified RIProp::WorldTransform()	Fixed the faulty rotation problem. The original Rotation did not do Degree to Radian, which caused the calculated Quaterion to be wrong.
CHikEffectorComponent::SetActive( RO::EHikEffector eEffector, RO::EHikEffectorType eType, bool bActive )	Used to set HIK effector active state.
CHikEffectorComponent::GetActive( RO::EHikEffector eEffector, RO::EHikEffectorType eType )	Used to get the current HIK effector active state.
std::map< std::wstring, RL::CMatrix4f > CHikEffectorComponent::Solve( args... )	Mocap solution for HIK. Usage: RL::CMatrix4f > CHikEffectorComponent::Solve( RO::EHikEffector eEffector, const RL::CMatrix4f& kMatrix )
CHikEffectorComponent::SetLock( args... )	Used to set IK effector Lock. CHikEffectorComponent::SetLock( RO::EHikEffector eEffector, RO::EHikEffectorType eType, bool bLock ).
CHikEffectorComponent::GetLock( args... )	Used to get the current IK effector Lock status. Usage: CHikEffectorComponent::GetLock( RO::EHikEffector eEffector, RO::EHikEffectorType eType ).
CHikEffectorComponent::SetPosition( args... )	Used to set IK effector Position coordinates. Usage: CHikEffectorComponent::SetPosition( RO::EHikEffector eEffector, const RL::CVector3f& vPosition ).
CHikEffectorComponent::SetPosition( args... )	Used to set multiple IK effector Position coordinates. Usage: CHikEffectorComponent::SetPosition( const std::vector< RO::EHikEffector >& kEffectorIds, const std::vector< RL::CMatrix4f >& kEffectorWorld, const std::vector< bool >& kRotateActive, const std::vector< bool >& kTranslateActive)
CHikEffectorComponent::SetBodyWeight( const float fWeight )	It is used to set the weight ratio of whole body ik when IK effector moves (0-1).
CVisemeComponent::TextToSpeech( args... )	Used to turn text into sound and set Viseme lips at the same time. Usage: CVisemeComponent::TextToSpeech( std::wstring strContent, RO::ELanguage eLanguage, float fVolume, float fPitch, float fSpeed ).
CVisemeComponent::TextToVisemeData( args... )	Used to convert input text into Visme lip data (English TTS system). Usage: CVisemeComponent::TextToVisemeData( std::wstring strContent, float fVolume, float fPitch, float fSpeed )
Modify std::vector< RTime > GetVisemeKeyTimes()	Fixed the key time conversion problem. Originally did not convert Frequency and changed GetVisemeKeys to GetVisemeKeyTimes.
Modify CVisemeComponent::ProcessTTS( args... )	private function Modify the language system to determine the system according to RO :: ELanguage. Usage: CVisemeComponent::ProcessTTS( std::wstring strContent, RO::ELanguage eLanguage, float fVolume, float fPitch, float fSpeed, std::wstring& wsWaveFilePath, RL::CArrayList< std::pair< unsigned short, unsigned int > >& kPhonemeDatas )
RAudio.Load	Fixed issues with wave files crashing twice.
RFileIO::ExportFbxFile	Used for exporting FBX files.
API Versioning	Changed API version to 0.7.3 from 0.7.2.
RISkeletonComponent::GetRootPositionRetargetingRatio	Provides how to convert from Position of SkinRoot to Position of MotionRoot.
Modify ICCameraObject - preview camera	You can get preview camera through find camera object
CFaceComponent::GetWeight( args... )	Get the clip and layer overlay result of the current facial expression. Usage: CFaceComponent::GetWeight(RO::RTime kTime,std::vector< float >& kHead,std::vector< float >& kLeftEye,std::vector< float >& kRightEye,std::vector< float >& kMorph,std::vector< float >& kBone,std::vector< float >& kCustom,float& fStrength)
RIAvatar::GetGeneration()	Provides CC roles belonging to CC_G1 or CC_G3
eunm EAvatarGeneration{ CC_G1_Avatar, CC_G3_Avatar }	Provide CC role type
Modify RISpotLight::SetSpotLightBeam( args... )	Fixed the original misused fFalloffPower parameter, and the angle / falloff / attenuation is currently corresponding to GetSpotLightBeam. RISpotLight::SetSpotLightBeam( RTime kTime, float fAngle, float fFalloff, float fAttenuation ).
Modify RISpotLight::GetSpotLightBeam( args... )	Modify the attenuation parameter value of the spotlight. Usage: RISpotLight::GetSpotLightBeam( int& nAngle, int& nFalloff, int& nAttenuation )

Limitations

As the iClone Python API continues to evolve, limitations may expand or contract over time. Below are lists of iClone Python API's currently known limitations. This list is not exhaustive.

Inoperable Assets

The following items can not be manipulated and acted upon with Python scripting:

Particle FX (iClone & PopcornFX)
SpeedTrees
Substance Materials
Textures Images
Constraints: Path, Spring, LookAt, Link, Physics, etc.
Physics (Soft & Rigid)
IK end-effectors (control attached props instead to drive IK reach)
Mesh level components: vertices, edges, faces, etc.
Preview camera

Unsupported Operations

The following operations are not available via Python scripting:

Saving iClone formats: iProjects, iAvatars, iProps, etc.
Pixel operations: multiply, add, overlay, etc.
Image processing: Brightness, Hue, Saturation, Sharpen, Soften, Blend, etc.
Render parameter settings (Project settings can not be changed)
Facial lip-sync keying
Preference settings
Attach/Detach: changing object parent-child relation
Align motion/character root alignment
Modeling operations: manipulation of mesh components

@@ Line 227: / Line 227: @@
 !scope="row"|RlVisemeComponent::GetVisemeKey( args... )
 |Used to get the VisemeID and Weight of Viseme at a specified point in time. Usage: RlVisemeComponent::GetVisemeKey( RO::RTime kTime, RO::EVisemeID& eVisemeID, float& fWeight )
+|}
+</div></div>
+=== Version 0.7.3 ===
+<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
+<div style="font-weight:bold;line-height:1.6;">iClone 7.4x Open Change Log: 03/03/2019 - 04/29/2019 </div>
+<div class="mw-collapsible-content">
+{|class= "wikitable"
+!scope="row"|RO::EHikEffector
+|Provide the same number as the core Hik enumeration that is aligned with RLHumanIK \ RLHikDef.h (the old version was aligned to ICInterfaceEnumDef.h).  This fix is applied to both LeftHandThumb and RightFootExtraFinger enums.
+|-
+!scope="row"|RO::EHikEffectorType enum(Translate/Rotate)
+|Provide settings for HIK effector translate / rotate.
+|-
+!scope="row"|RMatrix4 RINode::WorldToLocal( RMatrix4 kWorld )
+|Used to convert the input world space matrix into a local space matrix relative to this node.
+|-
+!scope="row"|RMatrix4 RINode::LocalToWorld( RMatrix4 kWorld )
+|Used to convert the input local space matrix into a matrix in actual wolrd space.
+|-
+!scope="row"|Modified RISkeletonComponent::GetSkinBones
+|Fixed the problem of not returning all the skin bones.  The original method will only have 54 Bone (CC), but it should be more than this.
+|-
+!scope="row"|Modified RIProp::WorldTransform()
+|Fixed the faulty rotation problem.  The original Rotation did not do Degree to Radian, which caused the calculated Quaterion to be wrong.
+|-
+!scope="row"|CHikEffectorComponent::SetActive( RO::EHikEffector eEffector, RO::EHikEffectorType eType, bool bActive )
+|Used to set HIK effector active state.
+|-
+!scope="row"|CHikEffectorComponent::GetActive( RO::EHikEffector eEffector, RO::EHikEffectorType eType )
+|Used to get the current HIK effector active state.
+|-
+!scope="row"|std::map< std::wstring, RL::CMatrix4f > CHikEffectorComponent::Solve( args... )
+|Mocap solution for HIK.  Usage: RL::CMatrix4f > CHikEffectorComponent::Solve( RO::EHikEffector eEffector, const RL::CMatrix4f& kMatrix )
+|-
+!scope="row"|CHikEffectorComponent::SetLock( args... )
+|Used to set IK effector Lock. CHikEffectorComponent::SetLock( RO::EHikEffector eEffector, RO::EHikEffectorType eType, bool bLock ).
+|-
+!scope="row"|CHikEffectorComponent::GetLock( args... )
+|Used to get the current IK effector Lock status.  Usage: CHikEffectorComponent::GetLock( RO::EHikEffector eEffector, RO::EHikEffectorType eType ).
+|-
+!scope="row"|CHikEffectorComponent::SetPosition( args... )
+|Used to set IK effector Position coordinates. Usage: CHikEffectorComponent::SetPosition( RO::EHikEffector eEffector, const RL::CVector3f& vPosition ).
+|-
+!scope="row"|CHikEffectorComponent::SetPosition( args... )
+|Used to set multiple IK effector Position coordinates. Usage: CHikEffectorComponent::SetPosition( const std::vector< RO::EHikEffector >& kEffectorIds, const std::vector< RL::CMatrix4f >& kEffectorWorld, const std::vector< bool >& kRotateActive, const std::vector< bool >& kTranslateActive)
+|-
+!scope="row"|CHikEffectorComponent::SetBodyWeight( const float fWeight )
+|It is used to set the weight ratio of whole body ik when IK effector moves (0-1).
+|-
+!scope="row"|CVisemeComponent::TextToSpeech( args... )
+|Used to turn text into sound and set Viseme lips at the same time.  Usage: CVisemeComponent::TextToSpeech( std::wstring strContent, RO::ELanguage eLanguage, float fVolume, float fPitch, float fSpeed ).
+|-
+!scope="row"|CVisemeComponent::TextToVisemeData( args... )
+|Used to convert input text into Visme lip data (English TTS system).  Usage: CVisemeComponent::TextToVisemeData( std::wstring strContent, float fVolume, float fPitch, float fSpeed )
+|-
+!scope="row"|Modify std::vector< RTime > GetVisemeKeyTimes()
+|Fixed the key time conversion problem.  Originally did not convert Frequency and changed GetVisemeKeys to GetVisemeKeyTimes.
+|-
+!scope="row"|Modify CVisemeComponent::ProcessTTS( args... )
+|private function Modify the language system to determine the system according to RO :: ELanguage.  Usage: CVisemeComponent::ProcessTTS( std::wstring strContent, RO::ELanguage eLanguage, float fVolume, float fPitch, float fSpeed, std::wstring& wsWaveFilePath, RL::CArrayList< std::pair< unsigned short, unsigned int > >& kPhonemeDatas )
+|-
+!scope="row"|RAudio.Load
+|Fixed issues with wave files crashing twice.
+|-
+!scope="row"|RFileIO::ExportFbxFile
+|Used for exporting FBX files.
+|-
+!scope="row"|API Versioning
+|Changed API version to 0.7.3 from 0.7.2.
+|-
+!scope="row"|RISkeletonComponent::GetRootPositionRetargetingRatio
+|Provides how to convert from Position of SkinRoot to Position of MotionRoot.
+|-
+!scope="row"|Modify ICCameraObject  - preview camera
+|You can get preview camera through find camera object
+|-
+!scope="row"|CFaceComponent::GetWeight( args... )
+|Get the clip and layer overlay result of the current facial expression.  Usage: CFaceComponent::GetWeight(RO::RTime kTime,std::vector< float >& kHead,std::vector< float >& kLeftEye,std::vector< float >& kRightEye,std::vector< float >& kMorph,std::vector< float >& kBone,std::vector< float >& kCustom,float& fStrength)
+|-
+!scope="row"|RIAvatar::GetGeneration()
+|Provides CC roles belonging to CC_G1 or CC_G3
+|-
+!scope="row"|eunm EAvatarGeneration{ CC_G1_Avatar, CC_G3_Avatar }
+|Provide CC role type
+|-
+!scope="row"|Modify RISpotLight::SetSpotLightBeam( args... )
+|Fixed the original misused fFalloffPower parameter, and the angle / falloff / attenuation is currently corresponding to GetSpotLightBeam. RISpotLight::SetSpotLightBeam( RTime kTime, float fAngle, float fFalloff, float fAttenuation ).
+|-
+!scope="row"|Modify RISpotLight::GetSpotLightBeam( args... )
+|Modify the attenuation parameter value of the spotlight.  Usage: RISpotLight::GetSpotLightBeam( int& nAngle, int& nFalloff, int& nAttenuation )
 |}
 </div></div>

Load iClone Formats	This includes .iProjects, .iAvatars, *.iProps, and any number of supported file formats readable and writable by iClone.
Animate Props	RTS (Rotate, Translate, Scale) prop transformations, including playing their animation clips.
Animate Characters	Play motion clips and rotate joints of a character in FK mode (Forward Kinetic).
Morph Animation	Drive morph sliders and key morph slider values in the timeline.
Add audio to objects	Add or remove audio tracks to props and characters that can playback in real-time.
Adjust Materials	Adjust strength contributions per texture channel, UV settings, diffuse color, ambient color, opacity values, etc.
Camera Controls	Adjust focal length, angle of view, near and far clipping planes, etc. on any camera in the scene.
Light Controls	Control settings for direction, spot and point lights. Such as range, angle, falloff, attenuation, etc.
Device Input	Drive animations and object parameters with the keyboard, mice, joystick, etc.
TCP/IP	Drive animations and object parameters remotely with IOT (Internet of Things) from other computers, cell-phones, etc. Or, have iClone drive IOT with smart network connectivity for lights, doors, etc.
Get Events	Setup callbacks for iClone run-time events such as on load, on selection, on parameter value change, on set timer, etc. Useful for tasks that need to trigger following an event like adding newly created items into a list tree, deploying automatic settings on load, or driving corrective morph targets when certain combinations of morphs are activated.
Render Project	Write batch render scripts and specify target directories for output.
Custom UI Design	Use iClone's native UI classes, or extend beyond it with QT's Pyside2 to create buttons, forms, dropdowns, modal windows, etc.
Animation Keys	Set timeline keys for various motion clips. Animate props, characters, lights, etc. via scripting.

RIObjectPtr CICFileIO::LoadObject( strPath )	Function that can load objects, and directly get the loaded objects, currently only the types that inherit RIObject can use this API
RlVisemeComponent::AddVisemesClip( args... )	Used to create Viseme Clip. Usage: RlVisemeComponent::AddVisemesClip( RO::RTime kTime, const std::wstring& nClipName, RO::RTime kTimeLength )
RIProp::SetDummy( bIsDummy)	Used to set whether Prop is Dummy.
bool RIProp::IsDummy()	Used to check if Prop is Dummy.
std::vector< std::wstring > RIMorphComponent::GetMorphNames()	Used to get all MorphName in the specified mesh.
RIObject::Clone()	Used to copy the object.
RIObject::IsSelected()	Used to confirm whether the object is selected in the scene.
RemoveVisemesClip( RO::RTime kTime )	Used to remove the Viseme Clip at the specified time.
RlVisemeComponent::RemoveVisemesKey( RO::RTime kTime )	Used to remove the Viseme key at the specified point in time..
RlVisemeComponent::GetVisemeMorphWeights()	Used to get the weight of each Morph of Viseme.
RlVisemeComponent::GetVisemeBones()	Used to get the Bone used by Viseme.
RlVisemeComponent::GetVisemeKeys()	Used to get the time of all Viseme keys, and return RTime as an array.
RlVisemeComponent::GetVisemeKey( args... )	Used to get the VisemeID and Weight of Viseme at a specified point in time. Usage: RlVisemeComponent::GetVisemeKey( RO::RTime kTime, RO::EVisemeID& eVisemeID, float& fWeight )

Difference between revisions of "IC Python API:Uses and Capabilities"

Revision as of 04:04, 25 December 2019

Contents

Capabilities

Version 0.7

Version 0.7.1

Version 0.7.2

Version 0.7.3

Limitations

Inoperable Assets

Unsupported Operations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools