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

Revision as of 01:08, 26 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.

v0.7

[Expand]

iC 7.4x

v0.7.1

[Expand]

iC 7.4x ( 01/17/2019 - 01/31/2019 )

LocalTransform WorldTransform	Fixed LocalTransform/WorldTransform( RIObject, RIAvatar, RIProp,RILight, RICamera ): Incorrect transform rotations for RIObject, RIAvatar, RIProp, RILight, RICamera.
RINode	New 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.
MaterialComponent	Fixed MaterialComponent( AddAmbientKey, AddDiffuseKey, AddSpecularKey, AddGlossinessKey, AddSpecularKey, AddSelfIlluminationKey, AddOpacityKey, AddTextureWeightKey, AddUvDataKey, RemoveUvDataKey, LoadVideoToTexture, AddVideoVolumeKey): 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	New RIObject::SetParent(RIObject/RINode): All classes that derive from RIObject also inherit the SetParent member function.
RIObject	New RIObject::LinkTo(RIObject, RTime): All classes that derive from RIObject also inherit the LinkTo member function.
RIObject	New RIObject::Unlink(RTime): All classes that derive from RIObject also inherit the Unlink member function.
RIFaceComponent	New RIFaceComponent::GetKey(RTime, Head, LeftEye, RightEye, Morph, Custom, Bone, Weight): Used to retrieve the current time's Facial Expression, Eye, and Head key values.
RIFaceComponent	New RIFaceComponent::AddClip(RTime): Adds a default Facial clip at the designated point in time.
RIFaceComponent	New RIFaceComponent::AddEyeKey(): Create a EyeKey under the Facial Layer.
RIFaceComponent	New RIFaceComponent::AddHeadKey(): Create a HeadKey under the Facial Layer.
RIFaceComponent	New RIFaceComponent::AddExpressionKey(): Create a ExpressionKey under the Facial Layer.
RIFaceComponent	New RIFaceComponent::AddVisemeKey(): Create a LipsKey under the Viseme layer.
RIObject	New RIObject::SetName(std::wstring): Used to change the name of an object.
RIObject	New RIObject::GetPivot(): All classes that derive from RIObject also inherit the GetPivot member function.
RIObject	New RIObject::SetPivot(): Provides a way to retrieve the pivot point of a prop.
RIObject	New RIObject::GetBounds(): All classes that derive from RIObject also inherit the GetBounds member function.

v0.7.2

[Expand]

iC 7.4x ( 02/15/2019 - 02/27/2019 )

v0.7.4

[Expand]

iC 7.5 ( 04/08/2019 - 07/01/2019 )

CCameraObject	New <RO::RCameraDofData> CCameraObject::GetDOFData(): Get camera Dof data.
RScene	New <RO::RICameraPtr> RScene::GetCurrentCamera(): Get the camera currently used in the current scene.
RGlobal	New <RO::RStatus> RGlobal::GetScreenSize( int& nWidth, int& nHeight ): Get Export Render size.
RIObject	Fixed RIObject::SetName: SetName will now be recorded into undo/redo history.
RScene	<RO::RStatus> RScene::ClearSelectObjects(): Added the state of deselecting objects in the scene.
CCameraObject	<float> CCameraObject::GetAngleOfView( RO::RTime kTime ) const: Get Iclone camera FOV.
CCameraObject	<RO::RStatus> CCameraObject::GetAperture( float& fWidth, float& fHeight ): Get Filmback width and height.
RIVisemeComponent	Modified RIVisemeComponent::AddVisemeKey( RVisemeKey ): Pass in RVisemeKey instead.
RIVisemeComponent	Modified RIVisemeComponent::RemoveVisemesKey( RVisemeKey ): Pass in RVisemeKey instead.
RIVisemeComponent	Modified RIVisemeComponent::GetVisemeKey( RTime kTime, RVisemeKey& kKey ): Pass in RVisemeKey and Reference to retrieve data.
RIVisemeComponent	Modified RIVisemeComponent::GetVisemeKeys(): Directly return std :: vector <RVisemeKey>.
RIAvatar	Modified RIAvatar::GetGeneration: Added two types CC_Game_Base_One & CC_Game_Base_Multi.
RFileIO	Modified RFileIO::ExportFbxFile: Take one more parameter std :: wstring strIncludeMotionPath to output together with Object.
RGlobal	New <bool> RGlobal::IsTrialContentMode(): detect whether the current AP is loaded with trial content (for internal API).
RISkeletonComponent	New RISkeletonComponent::ConvertBoneAxisAndParent(kAxisMaps, kReParentMaps): Calculate the current RTS according to the incoming axial map & change the parent's map.
CCameraObject	New <RO::ECameraFitResolution> CCameraObject::GetFitRenderRegionType(): Get Camera fit render region type (Horizontal / Vertical).
CCameraObject	New <RO::ECameraFitResolution> CCameraObject::GetFitFovType(): Get Camera fit fov type (Horizontal / Vertical).
REventCallback	New REventCallback::OnObjectDataChangedWithType( int nObjectChangeDataType ): Added the type corresponding to the event when the AP triggers the ObjectDataChanged event.
OnHierarchyChanged	New REventCallback::OnHierarchyChanged(): AP to trigger HierarchyChanged event, currently occurs in reach effector.
RIAvatar	New RIAvatar::GetAvatarType(): Which Type is used to get the current character (Standard, NonStd, StandardSearize).
RFileIO	New <bool> RFileIO::CheckExportFbxHasLicense( RO::RIObjectPtr spObject ): Added judging whether the output Fbx comes with a sell / export license (for internal API).
RFileIO	Modified RFileIO::ExportFbxFile: When exporting Fbx, judge whether it has a sell / export license
RISkeletonComponent	New RISkeletonComponent::ConvertToOriginalBoneAxis(): Turn the current Pose into the axis of the original skeleton (NonStd characters only).
RICCamera	Modify RICCamera::GetFocalLength(): Correction If it is judged that the control (CameraFovClipControl / CCameraFovKeyControl) is wrong, the focal length is calculated based on the FrustumFov in the current camera.
RGlobal	New RGlobal.TrialVersionRemainingTimes( const std::wstring& strBinPath, unsigned int uProductID, const std::wstring& strProductFold,const std::wstring& strRegRoot,unsigned int uTimeNo ): Can check the remaining number of trails (some Trial will be useful, ex 3DX).

v0.7.5

[Expand]

iC 7.6 (07/05/2019 - 07/29/2019)

v0.7.6

[Expand]

iC 7.7 ( 08/08/2019 - 11/05/2019 )

v0.7.7

[Expand]

iC 7.7 ( 12/05/2019 - 12/18/2019 )

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 407: / Line 407: @@
 !scope="row"|RIFileIO
 |Fixed RLPy.RIFileIO.LoadObject(): Now supports iPkfx file format.
+|}
+</div></div>
+=== v0.7.7 ===
+<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
+<div style="font-weight:bold;line-height:1.6;">iC 7.7 ( 12/05/2019 - 12/18/2019 ) </div>
+<div class="mw-collapsible-content">
+{|class= "wikitable"
+!scope="row"|RFileIO
+|Modified RLPy.RFileIO.LoadObject(): New Parameter(bRecordStep) to decide whether to record this operation into Undo/Redo list
+|-
+!scope="row"|RFileIO
+|Modified RLPy.RFileIO.LoadFile(): New Parameter(bRecordStep) to decide whether to record this operation into Undo/Redo list.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetAttributeCount(): Get the number of PopcornFX attributes.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetAttributeName(index): Get the attribute name of a given index.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetAttributeValue(index): Get the attribute value of given index.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::AddAttributeKey(Time, str, list(4)): Add the attribute key by time and name.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetSamplerList(EPopcornFxSamplerType): Get the name of all samplers.
+|-
+!scope="row"|EPopcornFxSamplerType
+|New EPopcornFxSamplerType(): Get the sampler object.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetMeshSamplerTarget(str): Set the sampler object.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::GetMeshSamplerTarget(str, RIObject):
+|-
+!scope="row"|EObjectModifiedType
+|New EObjectModifiedType(): Provides the type of the object that was modified.
+|-
+!scope="row"|RIGlobal
+|New RIGlobal::ObjectModified(RIObject): This command can detect changes made to an object which is useful for refreshing a custom user interface or informing a plugin of the changes.
+|-
+!scope="row"|RIPopcornFXObject
+|New RIPopcornFXObject::ClearMeshSamplerTarget(str): Removes the Mesh Sampler target object.
 |}
 </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.

CICFileIO	<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	RlVisemeComponent::AddVisemesClip( RO::RTime kTime, const std::wstring& nClipName, RO::RTime kTimeLength ): Used to create Viseme Clip.
RIProp	RIProp::SetDummy( bIsDummy): Used to set whether Prop is Dummy.
RIProp	<bool> RIProp::IsDummy(): Used to check if Prop is Dummy.
RIMorphComponent	std::vector< std::wstring > RIMorphComponent::GetMorphNames(): Get all morph names for the specified mesh.
RIObject	RIObject::Clone(): Used to copy the object.
RIObject	RIObject::IsSelected(): Confirm whether the object is selected in the scene.
RemoveVisemesClip	RemoveVisemesClip( RO::RTime kTime ): Remove a viseme Clip at the specified time.
RlVisemeComponent	RlVisemeComponent::RemoveVisemesKey( RO::RTime kTime ): Remove a viseme key at the specified point in time.
RlVisemeComponent	RlVisemeComponent::GetVisemeMorphWeights(): Used to get the weight of each Morph of viseme.
RlVisemeComponent	RlVisemeComponent::GetVisemeBones(): Used to get the Bone used by Viseme.
RlVisemeComponent	RlVisemeComponent::GetVisemeKeys(): Used to get the time of all Viseme keys, and return RTime as an array.
RlVisemeComponent	RlVisemeComponent::GetVisemeKey( RO::RTime kTime, RO::EVisemeID& eVisemeID, float& fWeight ): Used to get the VisemeID and Weight of Viseme at a specified point in time.

RCameraDofData	Modified RLPy.RCameraDofData: Set Function can now be used. Originally all SetEnable, SetFocus, etc. were hidden functions.
RICamera	New <RStatus> AddDofKey( RKey, RCameraDofData ): The key used to download the Camera Dof, the Preview Camera cannot be downloaded (not Pause).
RICamera	New <int> GetNearClippingPlane(): Get the near clipping plane of the camera
RICamera	New <RStatus> SetNearClippingPlane( int nNearPlane ): Set the near clipping plane of the camera to nNearPlane
RICamera	New <int> GetFarClippingPlane(): Get the far clipping plane of the camera
RICamera	New <RStatus> SetFarClippingPlane( int nFarPlane ): Set the far clipping plane of the camera to nFarPlane
RIObject	Update(): RTS & Geronetry to update all Child bone & Mesh of this object
RINode	Update(): Transform to update all Childe Nodes
ELinkObjectAlignType	AlignType referenced when adding Link objects
RIObject	Modified RIObject::LinkTo( std::shared_ptr< RIObject > spTargetObject, RO::ELinkObjectAlignType eAlignType, RTime kTime ): Link objects often pass AlignType to determine the Position / Rotation of the Target object.
RIClip	Fixed RLPy.RIClip.SetLength(): that now even the props from the Prop SetParent group can correctly modify the Clip Length of each Child Prop
RScene	Modified GetProps(): Restricted to get only the outermost Props on the scene (excluding the meaning of Props children)
RScene	Modified FindObjects( RO::EObjectType eType ): Restricted to get only the outermost Props on the scene (excluding the meaning of Props children)

RICamera.GetFocalLength	Fixed RICamera.GetFocalLength: retrieves faulty value when the query is not of the current time.
RIObject	RIObject: RLPy.RIObject.SetVisible: Effects the visibility of the entire object hierarchy rather than just the object itself.
RIProp	Modified RIProp: Added ConvertBoneAxisAndParent in RISkeletonCompoment
RIPopcornObject	New RIPopcornObject: Added New RIPopcornObject to control PopcornFX object
RScene	Modified RScene: RLPy.RScene.FindObject now supports PopcornFX object types.
RICamera	New RLPy.RICamera.RemoveDofKey( RKey ): Deletes DOF key at specified times
RICamera	New RICamera.RemoveDofKeys(): Deletes all the DOF keys for a given camera.
RICamera	New RLPy.RICamera.GetDofKeyCount(): Gets the total count of all DOF keys for a specified camera.
RICamera	New RLPy.RICamera.IsLookAtMode( RTime ): Get the status of camera at a specified time.
Console	Fixed Console: Fixed log support for UTF-8 strings.
RIObject	New RLPy.RIObject.GetLinkedObject( RTime ): Get the linked object at a specified time.
RIObject	Fixed RLPy.RIObject.Clone(): Not returning the right object type (such as RIAvatar, RIProp etc)
RIFileIO	Fixed RLPy.RIFileIO.LoadFile(): Now supports iPkfx file format.
RIFileIO	Fixed RLPy.RIFileIO.LoadObject(): Now supports iPkfx file format.

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

Revision as of 01:08, 26 December 2019

Contents

Capabilities

v0.7

v0.7.1

v0.7.2

v0.7.4

v0.7.5

v0.7.6

v0.7.7

Limitations

Inoperable Assets

Unsupported Operations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools

RFileIO	Modified RLPy.RFileIO.LoadObject(): New Parameter(bRecordStep) to decide whether to record this operation into Undo/Redo list
RFileIO	Modified RLPy.RFileIO.LoadFile(): New Parameter(bRecordStep) to decide whether to record this operation into Undo/Redo list.
RIPopcornFXObject	New RIPopcornFXObject::GetAttributeCount(): Get the number of PopcornFX attributes.
RIPopcornFXObject	New RIPopcornFXObject::GetAttributeName(index): Get the attribute name of a given index.
RIPopcornFXObject	New RIPopcornFXObject::GetAttributeValue(index): Get the attribute value of given index.
RIPopcornFXObject	New RIPopcornFXObject::AddAttributeKey(Time, str, list(4)): Add the attribute key by time and name.
RIPopcornFXObject	New RIPopcornFXObject::GetSamplerList(EPopcornFxSamplerType): Get the name of all samplers.
EPopcornFxSamplerType	New EPopcornFxSamplerType(): Get the sampler object.
RIPopcornFXObject	New RIPopcornFXObject::GetMeshSamplerTarget(str): Set the sampler object.
RIPopcornFXObject	New RIPopcornFXObject::GetMeshSamplerTarget(str, RIObject):
EObjectModifiedType	New EObjectModifiedType(): Provides the type of the object that was modified.
RIGlobal	New RIGlobal::ObjectModified(RIObject): This command can detect changes made to an object which is useful for refreshing a custom user interface or informing a plugin of the changes.
RIPopcornFXObject	New RIPopcornFXObject::ClearMeshSamplerTarget(str): Removes the Mesh Sampler target object.