Scripting Parametric Motion

Parametric motion control is especially useful in these situations:

• To animate complex assemblies, which is very difficult with keyframing alone.

• When the equations of motion are known.

It is possible to script parametric motion for an actor that will take place while the actor is moving along a path. Motion along a path is scripted with the Define Actor Path tool.

To make it easier to define equations of motion, MicroStation provides a set of Built-in variables and functions. Additionally, you can define custom parameters based on the built-in variables or any variable that has previously been defined (see Defining custom parameters).

To script parametric motion

1. Use the Create Actor tool to create an actor with which to associate the motion and to specify the allowable types of motion.
   The actor must be created with a unique name.

   Create Actor settings window



2. Use the Script Actor tool to script the motion.

   Script Actor dialog box. Options not available for the identified actor are dimmed.

   
   Key in equations only for the values that are to change; leave others blank. For motion to occur, these parameter equations should be dependent on time. This can be handled by referencing the built-in variable for time (tSeconds) or frame number (frame) directly, or by defining custom parameters that are dependent on time.


3. (Optional) To script additional motion for the same actor, repeat step 2.
   or
   (Optional) To script motion for a different actor, repeat steps 1-2.



If a new script entry for a particular actor conflicts with an existing entry for the actor, the Script Actor tool displays an alert box, in which you are prompted to use, reject, or recreate the entry.

Built-in variables and functions

The following built-in variables are available for defining actor motion equations or custom parameters with the Script Actor tool .

Variable	Description
frame	frame number
pi	the mathematical value, Pi, which is equal to the angle covered by one-half of a circle
tSeconds	elapsed time from beginning of sequence (frame 0) in seconds
beginFrame	beginning frame of the section currently being recorded
endFrame	end frame of the section currently being recorded
minFrame	first frame number at which action is defined (frame 0); also first frame of a preview
maxFrame	last frame number at which action is defined; also last frame of a preview
beginSequence	frame number of the start of the current script
endSequence	last frame number of the current script
sequenceLength	length of the current script in frames
tSecondsSequence	elapsed time (in seconds) from beginning of the current script

The elapsed time tSeconds is derived as follows:

tSeconds = frames/frames per second

For example, if you set frames per second to 30, tSeconds equals 1 second at frame 30, 2 seconds at frame 60 and so on.

You set the number of frames per second in the General Settings box, which is opened by selecting Settings > General in the Animation Producer's dialog box.

The following built-in functions are available for defining actor motion equations or custom parameters with the Script Actor tool. These functions are identical to those in the standard C math library, except that all angular values are expected and returned in degrees rather than radians.

Function	Description
radiansFromDegrees(d)	radians from degrees
degreesFromRadians(r)	degrees from radians
secondsFromFrame(f)	seconds from frame number
cos(angle)	trigonometric cosine of angle
acos(value)	arc cosine of value
sin(angle)	sine of angle
asin(value)	arc sine of value
atan(value)	arc tangent of value
atan2(valueY, valueX)	arc tangent of valueY/valueX
tan(angle)	tangent of angle
cosh(value)	hyperbolic cosine of value
sinh(value)	hyperbolic sine of value
tanh(value)	hyperbolic tangent of value
exp(value)	exponential of x
log(value)	natural logarithm of value
log10(value)	base 10 logarithm of value
pow(x,y)	x to y power
sqrt (value)	square root of value
fabs (value)	absolute value of
ceil(value)	smallest integer not less than value
floor(value)	largest integer not greater than value
fmod (value)	modulus of value
rand ()	pseudo random number
srand(x)	set random seed

Defining custom parameters

Often the same parameters are used in multiple equations of motion in different designs. You can save time by using built-in variables and functions to define custom parameters. Once you define a custom parameter, you can refer to it by name when scripting actors.

For example, consider a custom parameter, named revolution, defined as follows:

360/maxFrame*frame

An actor whose motion is scripted as revolution rotates one full rotation during the course of the animation sequence, no matter how many frames are used. This is determined as follows: dividing 360 (degrees) by the total number of frames (maxFrame) gives the rotation per frame. This, in turn, is multiplied by the current frame number (frame).

Mathematical operators can be applied to custom parameters in the same manner as to built-in variables. Continuing with the example:

2*revolution — rotates the actor 720°

revolution/2 — rotates the actor 180°

Each newly defined custom parameter is stored in the open script along with the script entries themselves. To make your parameters more easily reusable with other designs, it is advisable to save the parameters in a separate script file. You can then include this script in other scripts (see Including scripts ).

To define a custom parameter

1. From the Animation Producer dialog box's Settings menu, choose Parameters.
   The Animation Parameters dialog box opens.


2. Click the Create button.
   The Create Parameter dialog box opens.


3. In the Name field, key in the name for the parameter.


4. In the Value field, key in the value (see Built-in variables and functions ).


5. (Optional) In the Description field, key in a description of the parameter.


6. Click the OK button.
   The Create Parameter dialog box closes, and the parameter is added to the list in the Animation Parameters dialog box.

Choosing Clear Script from the Animation Producer dialog box's File menu removes any custom parameters from the open script. This is further reason to store custom parameters in a separate script file.

The Animation Parameters dialog box is also used to edit and delete existing parameters.