vtool.maya_lib.rigs_util¶

Class Summary

`Control`(name[, tag])	Convenience for creating controls
`ControlGroup`(control_group)
`StoreControlData`([node])
`StretchyChain`()	rigs
`StretchyElbowLock`(three_joints, three_controls)	Create an elbow lock stretchy on the three joints
`SoftIk`(joints)
`RiggedLine`(top_transform, btm_transform, name)	rigs
`RigSwitch`(switch_joint)	Create a switch between different rigs on a buffer joint.
`MirrorControlKeyframes`(node)
`TwistRibbon`(joint[, end_transform])	Takes a joint.
`IkFkSwitch`(fk_controls, ik_controls)	Not implemented, but would be nice to have the ik/fk switch behavior on any set.

Function Summary

`rename_control`(old_name, new_name)
`rename_message_groups`(search_name, replace_name)
`create_joint_buffer`(joint[, connect_inverse])
`create_distance_reader`(xform1, xform2[, ...])	Create a distance reader between 2 transforms.
`create_distance_scale`(xform1, xform2[, ...])	Create a stretch effect on a transform by changing the scale when the distance changes between xform1 and xform2.
`create_sparse_joints_on_curve`(curve, ...)	Create joints on a curve that are evenly spaced and not in hierarchy.
`create_joints_on_curve`(curve, joint_count, ...)	Create joints on curve that do not aim at child.
`create_spline_ik_stretch`(curve, joints[, ...])	Makes the joints stretch on the curve.
`create_simple_spline_ik_stretch`(curve, joints)	Stretch joints on curve.
`create_bulge_chain`(joints, control[, ...])	Adds scaling to a joint chain that mimics a cartoony water bulge moving along a tube.
`create_distance_falloff`(source_transform[, ...])	Under development.
`create_attribute_lag`(source, attribute, targets)	Add lag to the targets based on a source attribute.
`create_attribute_spread`(control, transforms)	Given a list of transforms, create a spread attribute which will cause them to rotate apart.
`create_attribute_spread_translate`(control, ...)	Given a list of transforms, create a spread attribute which will cause them to translate apart.
`create_offset_sequence`(attribute, ...)	Create an offset where target_transforms lag behind the attribute.
`is_control`(transform)
`get_controls`([namespace])	Get the controls in a scene.
`select_controls`([namespace])
`key_controls`([namespace])
`zero_out_controls`([namespace])
`mirror_control`(control)	Find the right side control of a left side control, and mirror the control cvs.
`mirror_controls`()	Mirror cv positions of all controls in the scene.
`mirror_mesh_to_matching_mesh`(left_mesh, ...)	given 2 meshes under different transforms using the positions from left mesh, calculate the right position and set the verts on the right mesh.
`mirror_curve`([prefix])	Mirror curves in a scene if the end in _L and _R
`process_joint_weight_to_parent`(mesh)	Sometimes joints have a sub joint added to help hold weighting and help with heat weighting.
`joint_axis_visibility`(bool_value)	Show/hide the axis orientation of each joint.
`hook_ik_fk`(control, joint[, groups, attribute])	Convenience for hooking up ik fk.
`fix_fade`(target_curve, follow_fade_multiplies)	This fixes multiplyDivides so that they will multiply by a value that has them match the curve when they move.
`scale_controls`(value)
`fix_sub_controls`([controls])
`set_control_space`(x, y, z, control[, ...])
`mesh_border_to_control_shape`(mesh, control)
`edge_loop_to_control_shape`(edge, control[, ...])
`is_control_group`(control_group)
`get_control_groups`()
`get_important_info`(control_group)	Returns a dictionary with ud attributes and values
`get_control_group_info`(control_group)	Returns a class with ud attributes and values
`has_switch`(control)
`get_control_group_with_switch`(control)
`match_to_joints`(control_group[, info_dict, ...])
`match_switch_rigs`(control_group[, auto_key])
`match_switch_rigs_over_time`(control_group, ...)	this will switch to the control group supplied if the control_group is rig1 than the switch will be set to rig2 before the match happens.
`get_rigs_from_control_group`(control_group)
`get_rigs_from_control`(control)
`match_switch_rigs_from_control`(control[, ...])
`set_switch_parent`(controls, parent_switch)	param parent_switch The name of a control group that has a switch (the control group has a switch when its 1
`setup_zip_fade`(left_zip_attr, ...[, description])	This may be removed in the future. This attempts to add zip attribute. Zip needs to be setup with constraint with
`create_joint_sharpen`(joint[, rotate_axis, ...])	Creates a joint section
`get_controls_not_in_control_set`(top_group[, ...])
`get_potential_top_control`(top_group)
`get_potential_controls`(top_group[, namespace])
`is_control_shape_good`(control)
`create_matejczyk_compression_hinge`(...[, ...])	If you were connecting this setup to a rig, using the example of an arm rig two_rig joints would be the arm and the elbow joints.
`create_compression_joint`(joint, end_parent, ...)	joint need to be a joint with a child joint.

class Control(name, tag=True)¶

Convenience for creating controls

Parameters: name (str) – The name of a control that exists or that should be created.

set_curve_type(type_name)¶

Set the curve type. The type of shape the curve should have.

Parameters: type_name (str) – e.g. ‘circle’, ‘square’, ‘cube’, ‘pin_round’

set_curve_as_text(text)¶

set_to_joint(joint=None, scale_compensate=False)¶

Set the control to have a joint as its main transform type.

Parameters

joint (str) – The name of a joint to use. If none joint will be created automatically.
scale_compensate (bool) – Whether to connect scale of parent to inverseScale of joint.
look. (This causes the group above the joint to be able to change scale value without affecting the control's) –

translate_shape(x, y, z)¶

Translate the shape curve cvs in object space.

Parameters

x (float) –
y (float) –
z (float) –

rotate_shape(x, y, z)¶

Rotate the shape curve cvs in object space

Parameters

x (float) –
y (float) –
z (float) –

scale_shape(x, y, z, use_pivot=True)¶

Scale the shape curve cvs relative to the current scale.

Parameters

x (float) –
y (float) –
z (float) –
use_pivot (bool) –

color(value)¶

Set the color of the curve.

Parameters: value (int) – This corresponds to Maya’s color override value.

color_rgb(r=0, g=0, b=0)¶: Maya 2015 and above. Set to zero by default. Max value is 1.0.

get_color()¶

set_color_hue(value)¶

set_color_saturation(value)¶

set_color_value(value)¶

show_rotate_attributes()¶: Unlock and set keyable the control’s rotate attributes.

show_scale_attributes()¶: Unlock and set keyable the control’s scale attributes.

hide_attributes(attributes=None)¶

Lock and hide the given attributes on the control. If no attributes given, hide translate, rotate, scale and visibility.

Parameters: attributes (list) – List of attributes, e.g. [‘translateX’, ‘translateY’]

hide_translate_attributes()¶: Lock and hide the translation attributes on the control.

hide_rotate_attributes()¶: Lock and hide the rotate attributes on the control.

hide_scale_attributes()¶: Lock and hide the scale attributes on the control.

hide_visibility_attribute()¶: Lock and hide the visibility attribute on the control.

hide_scale_and_visibility_attributes()¶: Lock and hide the visibility and scale attributes on the control.

hide_keyable_attributes()¶: Lock and hide all keyable attributes on the control.

rotate_order(xyz_order)¶: Set the rotate order on a control.

color_respect_side(sub=False, center_tolerance=0.001, offset=0)¶

Look at the position of a control, and color it according to its side on left, right or center.

Parameters

sub (bool) – Whether to set the color to sub colors.
center_tolerance (float) – The distance the control can be from the center before its considered left or right.
offset (int) – TODO: Fill description.

Returns

The side the control is on in a letter. Can be ‘L’,’R’ or ‘C’

Return type

str

get()¶

Returns: The name of the control.
Return type: str

get_uuid()¶

get_xform_group(name='xform')¶

This returns a xform group above the control.

Parameters: name (str) – The prefix name supplied when creating the xform group. Usually xform or driver.

create_xform(prefix='xform')¶

Create a xform above the control.

Returns: The name of the xform group.
Return type: str

rename(new_name)¶

Give the control a new name.

Parameters: new_name (str) – The new name.

delete_shapes()¶: Delete the shapes beneath the control.

copy_shapes(transform)¶

fix_sub_control_shapes()¶

class ControlGroup(control_group)¶

load_data(attr_dict)¶

class StoreControlData(node=None)¶

remove_data(control)¶

remove_pose_control_data()¶

set_data(data=None)¶

set_pose_manager(pose_manager_instance)¶: sets a pose manager in order to get default pose. This is used when working with a joint chain.

set_namesapce(namespace)¶

set_control_data_attribute(control, data=None)¶

set_controls(controls)¶

set_side_replace(replace_string, pattern_string, position_string)¶

eval_data(return_only=False)¶

eval_mirror_data(side='L')¶

eval_multi_transform_data(data_list)¶

get_data()¶

set_node(node)¶

class StretchyChain¶

rigs

set_joints(joints)¶

set_node_for_attributes(node_name)¶

set_scale_axis(axis_letter)¶

set_distance_offset(attribute)¶

set_vector_instead_of_matrix(bool_value)¶

set_add_dampen(bool_value, damp_name=None)¶

set_add_damp(bool_value, damp_name=None)¶

set_simple(bool_value)¶

set_description(string_value)¶

set_per_joint_stretch(bool_value)¶

set_scale_attribute_offset(value)¶

set_extra_joint(joint)¶

set_attribute_name(attribute_name)¶

set_default_value(value)¶

set_create_title(bool_value)¶

create()¶

class StretchyElbowLock(three_joints, three_controls)¶

Create an elbow lock stretchy on the three joints

Parameters

three_joints (list) – For example the arm, elbow and wrist joint. Can be any 3 joints though
three_controls (list) – For example the top arm control, the pole vector control and the btm control. Controls should transform that correspond to an ik setup.

set_stretch_axis(axis_letter)¶

set_lock_attribute_control(name_of_a_control)¶

set_attribute_control(name_of_a_control)¶

set_description(description)¶

set_use_translate_for_stretch(bool_value)¶

set_use_this_overall_distance_node(distance_node)¶

set_default_value(value)¶

set_top_aim_transform(transform)¶

set_parent(transform)¶

set_create_soft_ik(bool_value)¶

create()¶

class SoftIk(joints)¶

set_attribute_control(control_name, attribute_name=None)¶

set_control_distance_attribute(control_distance_attribute)¶

set_default_distance_attribute(default_distance_attribute)¶

set_top_aim_transform(transform)¶

set_ik_locator_parent(transform)¶

set_btm_control(control_name)¶

set_description(description)¶

create()¶

class RiggedLine(top_transform, btm_transform, name)¶

rigs

set_local(bool_value)¶

create()¶

class RigSwitch(switch_joint)¶

Create a switch between different rigs on a buffer joint.

Parameters: switch_joint (str) – The name of a buffer joint with switch attribute.

get_weight_count()¶

add_groups_to_index(index, groups)¶

A switch joint is meant to switch visibility between rigs. By adding groups you define what their visibility is when the switch attribute changes. An index of 0 means the groups will be visible when the switch is at 0, but invisible when the switch is at 1.

Parameters

index (int) – The index on the switch. Needs to be an integer value even though switch is a float.
groups (list) – The list of groups that should have visibility attached to the index.

set_attribute_control(transform)¶

Set where the switch attribute should live.

Parameters: transform (str) – The name of a transform

set_attribute_name(attribute_name)¶

Set the name of the switch attribute on the attribute_control.

Parameters: attribute_name (str) – The name for the attribute.

create()¶

class MirrorControlKeyframes(node)¶

set_skip_translate(bool_value)¶

set_fix_axis(axis_letters='XYZ')¶

set_right_side_control(control_name)¶

mirror_outputs(fix_translates=False)¶

class TwistRibbon(joint, end_transform=None)¶

Takes a joint. If no end_transform given, the code will take the first child of the joint as the end of the ribbon.

set_description(description)¶

set_joint_count(int_value)¶

set_joints(joint_list)¶

set_ribbon_offset_axis(axis_letter)¶

set_attach_directly(bool_value)¶

set_top_parent(transform)¶

set_btm_parent(transform)¶

set_top_constraint(transform, constraint_type='parentConstraint')¶

set_btm_constraint(transform, constraint_type='parentConstraint')¶

set_top_twist_fix(bool_value)¶

set_btm_twist_fix(bool_value)¶

set_dual_quaternion(bool_value, turn_twist_fix_on=True)¶

set_ribbon_offset(value)¶

set_rounded(bool_value)¶

create()¶

class IkFkSwitch(fk_controls, ik_controls)¶

Not implemented, but would be nice to have the ik/fk switch behavior on any set. This class would help add it.

set_fk(fk_controls, fk_joints)¶

set_ik(ik_controls, ik_joints)¶

create()¶

rename_control(old_name, new_name)¶

rename_message_groups(search_name, replace_name)¶

create_joint_buffer(joint, connect_inverse=True)¶

create_distance_reader(xform1, xform2, on_distance=1, off_distance=- 1, negative_value=False)¶

Create a distance reader between 2 transforms. The command will create an attribute from 0 to one. 0 when the distance is greater than off_distance. 1 when the distance is less than on_distance. -1 off distance uses the current distance between xform1 and xform2 as the off_distance. where on distance tells when to activate based on distance, the negative_value activates at -1 when the value goes the other way.

Returns: distance node name
Return type: str

create_distance_scale(xform1, xform2, axis='X', offset=1)¶

Create a stretch effect on a transform by changing the scale when the distance changes between xform1 and xform2.

Parameters

xform1 (str) – The name of a transform.
xform2 (str) – The name of a transform.
axis (str) – “X”, “Y”, “Z” The axis to attach the stretch effect to.
offset (float) – Add an offset to the value.

Returns

(locator1, locator2) The names of the two locators used to calculate distance.

Return type

tuple

create_sparse_joints_on_curve(curve, joint_count, description)¶: Create joints on a curve that are evenly spaced and not in hierarchy.

create_joints_on_curve(curve, joint_count, description, attach=True, create_controls=False)¶

Create joints on curve that do not aim at child.

Parameters

curve (str) – The name of a curve.
joint_count (int) – The number of joints to create.
description (str) – The description to give the joints.
attach (bool) – Whether to attach the joints to the curve.
create_controls (bool) – Whether to create controls on the joints.

Returns

[ joints, group, control_group ] joints is a list of joints, group is the main group for the joints,: control_group is the main group above the controls.

If create_controls = False then control_group = None

Return type

list

create_spline_ik_stretch(curve, joints, node_for_attribute=None, create_stretch_on_off=False, create_bulge=True, scale_axis='X')¶

Makes the joints stretch on the curve. Joints must be on a spline ik that is attached to the curve.

Parameters

curve (str) – The name of the curve that joints are attached to via spline ik.
joints (list) – List of joints attached to spline ik.
node_for_attribute (str) – The name of the node to create the attributes on.
create_stretch_on_off (bool) – Whether to create extra attributes to slide the stretch value on/off.
create_bulge (bool) – Whether to add bulging to the other axis that are not the scale axis.
scale_axis (str) – ‘X’, ‘Y’, or ‘Z’, the axis that the joints stretch on.

create_simple_spline_ik_stretch(curve, joints, stretch_axis='Y')¶

Stretch joints on curve. Joints must be attached to a spline ik. This is a much simpler setup than create_spline_ik_stretch.

Parameters

curve (str) – The name of the curve that joints are attached to via spline ik.
joints (list) – List of joints attached to spline ik.
stretch_axis (str) – TODO: Fill description.

create_bulge_chain(joints, control, max_value=15, description='bulge')¶

Adds scaling to a joint chain that mimics a cartoony water bulge moving along a tube.

Parameters

joints (list) – List of joints that the bulge effect should move along.
control (str) – Name of the control to put the bulge slider on.
max_value (float) – The maximum value of the slider.

create_distance_falloff(source_transform, source_local_vector=None, target_world_vector=None, description='falloff')¶: Under development.

create_attribute_lag(source, attribute, targets)¶

Add lag to the targets based on a source attribute. A lag attribute will also be added to source to turn the effect on and off. If you are animating the rotation of a control inputs are as follows:

create_attribute_lag( ‘CNT_FIN_1_L’, ‘rotateY’, [‘driver_CNT_FIN_2_L, ‘driver_CNT_FIN_3_L’, ‘driver_CNT_FIN_4_L’] )

Parameters

source (str) – The node where the attribute lives. Also, a lag attribute will be created here.
attribute (str) – The attribute to lag. Sometimes can be rotateX, rotateY or rotateZ.
targets (list) – A list of targets to connect the lag into. The attribute arg will be used as the attribute to connect into on each target.

create_attribute_spread(control, transforms, name='spread', axis='Y', invert=False, create_driver=False)¶

Given a list of transforms, create a spread attribute which will cause them to rotate apart.

Parameters

control (str) – The name of a control where the spread attribute should be created.
transforms (list) – A list of transforms that should spread apart by rotation.
name (str) – The name of the attribute to create.
axis (str) – Can be ‘X’,’Y’,’Z’
invert (bool) – Whether to invert the spread behavior, so it can mirror.
create_driver (bool) – Whether to create a driver group above the transform.

create_attribute_spread_translate(control, transforms, name='spread', axis='Z', invert=False)¶

Given a list of transforms, create a spread attribute which will cause them to translate apart. This is good for fingers that are rigged with ik handles.

Parameters

control (str) – The name of a control where the spread attribute should be created.
transforms (list) – A list of transforms that should spread apart by translation.
name (str) – The name of the attribute to create.
axis (str) – Can be ‘X’,’Y’,’Z’
invert (bool) – Whether to invert the spread behavior, so it can mirror.

create_offset_sequence(attribute, target_transforms, target_attributes)¶: Create an offset where target_transforms lag behind the attribute.

is_control(transform)¶

get_controls(namespace='')¶

Get the controls in a scene.

It follows these rules

First check if a transform starts with “CNT_” Second check if a transform has an attribute named control. Third check if a transform has an attribute named tag and is a nurbsCurve, and that tag has a value. Fourth check if a transform has an attribute called curveType.

If it matches any of these conditions it is considered a control.

Returns: List of control names.
Return type: list

select_controls(namespace='')¶

key_controls(namespace='')¶

zero_out_controls(namespace='')¶

mirror_control(control)¶

Find the right side control of a left side control, and mirror the control cvs.

It follows these rules: It will only match if the corresponding right side name exists.

Replace _L with _R at the end of a control name. Replace L_ with R_ at the start of a control name. Replace lf with rt inside the control name

mirror_controls()¶: Mirror cv positions of all controls in the scene. See get_controls() and mirror_control() for rules.

mirror_mesh_to_matching_mesh(left_mesh, right_mesh)¶: given 2 meshes under different transforms using the positions from left mesh, calculate the right position and set the verts on the right mesh.

mirror_curve(prefix=None)¶: Mirror curves in a scene if the end in _L and _R

process_joint_weight_to_parent(mesh)¶

Sometimes joints have a sub joint added to help hold weighting and help with heat weighting. This will do it for all joints with name matching process_ at the beginning on the mesh arg that is skinned.

Parameters: mesh (str) – A mesh skinned to process joints.

joint_axis_visibility(bool_value)¶: Show/hide the axis orientation of each joint.

hook_ik_fk(control, joint, groups=None, attribute='ikFk')¶

Convenience for hooking up ik fk.

Parameters

control (str) – The name of the control where the attribute arg should be created.
joint (str) – The joint with the switch attribute. When adding multiple rigs to one joint chain, the first joint will have a switch attribute added.
groups (list) – The ik control group name and the fk control group name.
attribute (str) – The name to give the attribute on the control. Usually ‘ikFk’

fix_fade(target_curve, follow_fade_multiplies)¶

This fixes multiplyDivides so that they will multiply by a value that has them match the curve when they move.

For example if eye_lid_locator is multiplyDivided in translate to move with CNT_EYELID. Pass its multiplyDivide node to this function with a curve that matches the btm eyelid. The function will find the amount the multiplyDivide.input2X needs to move, so that when CNT_EYELID moves on Y it will match the curvature of target_curve.

Parameters

target_curve (str) – The name of the curve to match to.
follow_fade_multiplies (str) – A list of a multiplyDivides.

scale_controls(value)¶

fix_sub_controls(controls=None)¶

set_control_space(x, y, z, control, compensate_cvs=True)¶

mesh_border_to_control_shape(mesh, control, offset=0.1)¶

edge_loop_to_control_shape(edge, control, offset=0.1)¶

is_control_group(control_group)¶

get_control_groups()¶

get_important_info(control_group)¶: Returns a dictionary with ud attributes and values

get_control_group_info(control_group)¶: Returns a class with ud attributes and values

has_switch(control)¶

get_control_group_with_switch(control)¶

match_to_joints(control_group, info_dict=None, auto_key=False)¶

match_switch_rigs(control_group, auto_key=False)¶

match_switch_rigs_over_time(control_group, start_frame, end_frame)¶: this will switch to the control group supplied if the control_group is rig1 than the switch will be set to rig2 before the match happens.

get_rigs_from_control_group(control_group)¶

get_rigs_from_control(control)¶

match_switch_rigs_from_control(control, auto_key=False)¶

set_switch_parent(controls, parent_switch)¶

Parameters: parent_switch (str) – The name of a control group that has a switch (the control group has a switch when its 1 of 2 rigs are on 1 joint chain)

setup_zip_fade(left_zip_attr, right_zip_attr, fade_attributes, description='zip')¶

This may be removed in the future. This attempts to add zip attribute. Zip needs to be setup with constraint with: weight between source and midpoint.

create_joint_sharpen(joint, rotate_axis='Z', scale_axis='X', offset_axis='Y', offset_amount=1, invert=False, name=None)¶: Creates a joint section

get_controls_not_in_control_set(top_group, control_set=None)¶

get_potential_top_control(top_group)¶

get_potential_controls(top_group, namespace=None)¶

is_control_shape_good(control)¶

create_matejczyk_compression_hinge(two_rig_joints, three_guide_joints, description, translate_limit=10)¶: If you were connecting this setup to a rig, using the example of an arm rig two_rig joints would be the arm and the elbow joints. three_guide joints would be a guide for the arm, elbow and wrist. These would be offset from the rig joints but arm and wrist guides would be close to the elbow. The guide joints need to aim at each other.

create_compression_joint(joint, end_parent, description, point_constraint=False)¶: joint need to be a joint with a child joint. Child joint is automatically found.