Library Description
IML exposes many namespaces and classes. Here is a rundown of each and its purpose.
CameraUtilities — this class allows for the addition, motion, setting management, and render priority of cameras in the scene. The following functions are available in this class:
– AddCamera(name=”New Camera). This adds a camera to the world named “New Camera” and returns a camera object.
– MoveTo(camera, location=(0,0,0)). This moves camera objects to a specific location in world space.
– RotateTo(camera, rotation=(0,0,0)). This rotates the camera in world space in degrees around X, then Y, then Z.
– SetRenderCamera(camera). This marks the specific camera as the active camera for multi-camera actions.
CharacterUtilities — this is a namespace with different classes which creates a concept of a character. A character can be any mesh that uses bones to change pose positions. Vectors represent the range of motion of a bone, or set of bones. There are two kinds of Characters — human and non-human. Human characters have standard bones for movable parts of a human, such as eyes, arms, legs, lips, or the torso. Non-human characters do not have standard representations, and require a full description of the character’s rig. The following classes and functions are available
– StandardVector. This class defines control motions for humanoid characters. It is not complete, so currently only the following controls are supported:
— torso. This control allows a humanoid to rotate around the hips or bend left and right.
— arms. This control collects the left and right arm, and allows inverse kinematic motions of the arm in a hemisphere around the shoulder.
— head. This control motion of items on the head of a humanoid, including eyes, ears, and mouth.
– Character. This class defines non-human characters, and allows the manipulation of non-human controls.
— GetSavedRig(). This returns the rig object as a path from the character instance.
— GetAndSavePathOfRigFromCollection(collection). This searches a collection for an armature, and returns the world reference to that armature.
— Import(characterFile, collection). This takes a rigged character file and imports the character into a collection.
– ControlBone. This class defines a single bone in the rig as a control. Similar to Blender’s concept of a pose bone. All control bones have named degrees of freedom and a motion amount that is between -1.0 and 1.0. These named degrees of freedom are created by callback functions of the character. This is hard to explain abstractly, so an example is warranted. If there exists a human character with an upper arm bone, this bone has 2 degrees of freedom — up and down being one, with left and right being the other. A control bone can be created, and a named degree of freedom called “MoveUpDown” can be created, then a callback function to move the bone appropriate to the character can be created. This way, the character can move the control bone in a standard manner.
— Clamp(value, min, max). This is a math helper — if the value is outside the bounds, it returns the nearest value inside the -1..1 bound.
— AddCallBack(callBackName, callBackFunc). Control bones maintain a dictionary of named functions to call to perform a move. The most common names can either be “MoveLeftRight” or “MoveUpDown”. The callback will be called with the input value given to the move command. This allows motions to link together.
— AddChildOfConstraint(targetBoneName). Any control bone can be a child of any other bone. This allows rows of bones to move together if a parent bone has moved. A control bone can be a child of exactly one other bone.
— RemoveChildOfConstraint(). Remove the child constraint for the bone.
— _Move(motionChoice, amount). This internal helper function actually moves the bone. motionChoice is the name of the motion, and amount is a number between -1.0 and 1.0.
— MoveLeftRight(amount). This is a shortcut for _Move(“MoveLeftRight”, amount).
— MoveUpDown(amount). This is a shortcut for _Move(“MoveUpDown”, amount).
— GetWorldPosition(). This returns the world cooridinates of the bone. Bones have local positions in an armature, and this maps to world space.
— GetWorldRotation(). Bones have relative rotation to a parent. This returns world rotation as euler rotations.
— SetWorldPosition(position). This moves the bone to a position in world space.
— _GetBoneByName(name). Finds the named bone in an armature and returns the raw bone. In Blender, this returns a pose bone.
— GetControl(). This converts the controlbone to a control type that contains one bone.
– Control. Control is a class to animate arrays of both controls and control bones. It is self-referential — that is, a control can contain controls. All controls must expose a MoveLeftRight and a MoveUpDown callback. All controls must eventually base to control bones. A control will hold an array of controls and an array of control bones. The idea being that eventually, controls contain only control bones. The bones are then called to move by an amount, with the amount scaled in each call. The scaling factor is decided when a control is created.
— AddControl(controls, controlOrder). Adds a control to move in a specific order in the list of controls. It will replace controls given the same order slot.
— AddControlBone(controlBone, leftRightScale, upDownScale, forwardBackwardScale, leftRightRotateScale, upDownRotateScale, forwardBackwardRotateScale). Adds a control bone and sets up scale factors for the amount. When a Control is called with a motion request, the motion functions are given an amount. This then calls the control bones in the order specified, with the scale factors specified. This as the ability to dampen or amplify a motion in the call chain.
— There are various Move functions that all have similar signatures and do similar actions, as specified by the function names. Each takes an amount of motion to pass to all children controls. These are MoveLeftRight(amount), MoveUpDown(amount), and RotateLeftRight(amount). These iterate the controls, then the control bones, calling into each objects _Move function with the named motion and the scaled amount.
– Humanoid is a class that derives from character, and defines a hierarchy of classes in Python. The hierarchy is: Humanoid –> Head | Torso | Arms | Legs –> Eyes | Ears | Mouth. So, it is possible to perform an action like human.Head.Eyes.MoveUpDown(1.0). For items that are paired in humans, such as eyes or arms, a left/right is available. So, human.Head.Eyes.left.MoveUpDown(1.0) would move only the left eye to look up. Items with a left/right have a GetChirality() function that return is this is the left or right item of the type. Special functions exist for moving elbows, as these are forward kinematic controls, while hands are inverse. To move a hand, you specify the motion in world space, and the IK solver will move the other bones. To move an elbow, a special ElbowMoveUpDown(amount) exists that performs forward kinematics. Special functions on the humanoid class can be used to get the length of the arm as well as the displacement of a hand in the current pose. This allows determining how much of the range of motion is left prior to executing a move. Notable functions include:
— LoadFromStandardLibrary(characterName). This loads a fully rigged character from a pre-supplied library of characters. It returns a type of Humanoid.
— GetAllUsedControls(). This returns all controls that have been modified since the character loaded, or None if the character has never changed poses.
— GetPoseByName(self, poseName). This creates a standard vector for the hierarchy of controls that defines a human, all set to specific values. Available pose names are “Neutral”, which is arms down looking straight ahead with feet together, “T-Pose” which is arms spread wide, “TorsoStraight”, which is a relaxed version of Neutral with slight outward swing of the arms.
— RecordPoseByName(poseName, frame). This uses a named pose to record that pose to a specific frame in the animation keyframes.
CollectionHelpers — this class helps manage the scene/world by putting objects into groups called collections. You can create a collection with a name, move objects between collections, or get a list of all collections.
– CreateCollectionWithName(name). Create a named collection to contain objects.
– MoveObjectsBetweenCollections(objects, oldCollection, newCollection). Move objects between the old and new collections.
– GetMasterCollection(). All scenes contain a root collection known as the master collection. All objects initially load to this collection, and then are moved to new named collections.
Importers — this class helps managing importing/exporting assets from standard formats such as blender, fbx, or glTF. USD is not currently supported because USD is not available in the version of Rhino used for development/testing, but hopefully will come at a later date.
– ImportGLTF(filePath, fileName). This loads the GLTF files into the master collection.
– ImportOrLinkFromBlendFile(blendFile, objectType, objectName, action). If the action is “Import”, the named object in the blendfile is appended, else it is linked. Use blender’s types ( scene, mesh, etc) and the specific names of the objects being imported.
– ImportHDRorEXRIntoWorld(exrFile, position). Load the exr or HDR file into the world, setting the center of volume to the specified position.
LightUtilities — this class helps manage light. You can add lights, set the color to an HTML hex code, change the shape of the light, or change the intensity of a light.
– AddLight(lightType, name). Lights can be Blender’s standard types of POINT, SUN, SPOT, AREA, HEMI, and Volume.
– ColorLightByHexCode(light, hexCode). Set the color of the light to the specified CSS hex code.
MeshPrimitives — this class creates specific platonic solids. It defines both 2d items like circles or 3d items like spheres. It has the ability to construct circles, cubes, cylinders, empties (aka objects that don’t have real geometry), spheres (both Ico and UV), and planes.
– Circle(radius, location). A circle with specified radius and location on the XY plane.
– Cube(size=[]). A cuboid with specified length, width, and height.
– Cylinder(r, h). A cylinder with radius r and height h.
– Empty(location=()). A blender empty object with location (x, y, z).
– IcoSphere(radius, location). A sphere with radius, and location specified. This mesh has vertices equally spaced thoughout the sphere.
– Plane(size=i). A square plane on the XY plane with the specified dimension
– UVSphere(radius, location). A UV sphere with the radius and location specified. The sphere has layered polar rectangles.
MeshUtilities — this class manages boolean operations, mesh density operations, and distortion operations for meshes.
-IncreaseVertexDensity(mesh, level, render_level). Increase the density of vertices by levels.
– MeshBoolean(main_object, other_object, operator). Perform a boolean operation between two meshes, putting the result back into the main object and deleting the other object. valid operators are “DIFFERENCE”, “UNION”, and “INTERSECT”.
RigUtilities — this class manages rigs apart from movements. It allows the creation of bones, rigs, controls, and snaps.
SkeletonUtilities — this class manages collections of bones that are linked together, head to tail. It allows adding more bones, segmenting bones, selecting a single bone in a list, or deleting entire groups of bones.
StableDiffusion — this class wraps up stable diffusion to use for texturing objects on the fly.
TextureUtilities — this class manages shaders and textures. It allows unwrapping meshes and assigning UVs, creating and managing shaders, and creating and managing textures.
TimeKeys — this class manages time and keyframes. It manages the frame rate, the total length of animation time, adding and subtracting keyframes, and saving specifc bones to the keyframe.
WorldUtilites — this is by far the largest class. It manages what objects are active or selected, adding or removing objects from the scene, enumerating objects in a scene, getting location in world space of objects, getting the parent/children of objects, getting OS filesystem locations for standard assets, manages HDRs, moves objects around, renders images and videos, names objects, changes modes for applications like blender, changes visiblity, moves the skybox, or does basic translate, scale, rotation of objects.