Working with MAXKey Values

Value > MAXKey Values > Working with MAXKey Values

Values and Collections - Quick Navigation

Changing the .time property of a key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly.

The class of a key's value property is determined by the controller it is in, for example, a linear_float key has a float .value , a tcb_rotation key has a quaternion .value , etc. The properties are all settable and support the math-assignment operators and nested-property access.

HERE ARE SOME EXAMPLES:

$foo.pos.keys[2].time += 20f -- change time of single key
$foo.pos.keys.time += 20f -- change time of all keys
$box1.uvw_map.center.keys[2].value.x += 20
for k in $baz.bend.angle.keys do k.value *= 1.1

In some cases, the actual value stored in a key is not the value shown in the command panels, shown in Track View, the value returned by the .value property of the key, or the value returned when accessing the property to which the key’s controller is assigned. Instead, a scaling factor is applied to the key’s value before the value is made "visible". For example, percentages are normally displayed with a range of 0-100, rotation angles are in degrees, colors are [0-255,0-255,0-255]. The unscaled key values for percentages are normally in a range of 0-1, rotation angles in radians, and colors are [0-1,0-1,0-1].

In the description of properties for each class, the scaling factor, if any, is identified for each property. Take the following properties for the PArray class

FOR EXAMPLE:

<PArray>.X_Spin_Vector Float default: 1.0 -- animatable
<PArray>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage
<PArray>.Spin_Phase Float default: 0.0 -- animatable, angle
<PArray>.viewPercent Float default: 10.0 -- percentage

The .X_Spin_Vector property does not apply any scaling to its controller keys. The .Spin_Time_Variation property applies percentage scaling to its controller keys (displayed as percentage, stored as fraction). The .Spin_Phase property applies angle scaling to its controller keys (displayed as degrees, stored as radians). The .viewPercent property is stored internally with a percentage scaling factor, but since this property is not animatable, this scaling it invisible to MAXScript.

Normally this scaling is not of concern when programming in MAXScript, but there are two cases where it must be taken into account. The first is when using script controllers, and is described in Script Controllers.

The second case is when one controller is applied as the controller for two or more properties. The scaling is an attribute of the animatable property, not the controller, so in (the admittedly rare) situations in which a controller is shared by several animatables that have different scaling, unexpected results will occur if you do not take into account the scaling factor. An example of this is shown in the following script, where the same controller is shared between three differently scaled properties.

FOREXAMPLE:

obj=PArray()
cont=bezier_float()
obj.X_Spin_Vector.controller=cont
obj.Spin_Time_Variation.controller=cont
obj.Spin_Phase.controller=cont
obj.X_Spin_Vector=1
obj.X_Spin_Vector -- no scaling
obj.Spin_Time_Variation -- percentage
obj.Spin_Phase -- angle

OUTPUT:

$PArray:PArray03 @ [0,0,0] -- result line 1
Controller:Bezier_Float -- result line 2
Controller:Bezier_Float -- result line 3
Controller:Bezier_Float -- result line 4
Controller:Bezier_Float -- result line 5
1 -- result line 6
1.0 -- result line 7, unscaled
100.0 -- result line 8, percentage scaled, 1 = 100%
57.2958 -- result line 9, angle scaled, 
1 radian = 57.2958 degrees

If you do assign the same controller to properties with different scaling factors, you should take care to access the .value property through the correct animatable property - this provides a scaling context for the access operation.