SetDrivenKeyEXCF (LScript version 2.5.1)
written by faulknermano, Lernie Ang

BRIEF

This is an offshoot from SetDrivenKeyCF. I've added the suffix EX to denote the difference. It is possible, in due time, that I might replace SetDrivenKeyCF completely with this variant if it turns out that it is totally superior in functionality, and thus keeping the original will have no practical purpose.

There is a big difference between SetDrivenKeyCF and the EX version. The difference lies in EX usage of a custom envelope called Relations Channel (explanation below). With Relations Channels, you can create, not only multiple keys (as opposed to SDKCF's single key), but control the keys' curves directly in the Graph Editor. While I have not benchmarked this script in terms of script performance, it may run faster than SDKCF simply because no longer does any computations. Rather, it directly reads information from the curves, letting the Graph Editor do all the computation for it.

To those not yet familiar with SDKCF, this script is essentially a channel converter. And instead of using a scaling factor to adjust how the two channels relate, the script works with the actual channel values and does the factoring calculations for you.

Just like SDKCF, EX comes with its SetDrivenKeyEXMasterMC global interface. Again, to those not familiar, this script allows you to manipulate multiple SDKEXCF instances from one interface. The useability of this script will be demonstrated in the SetDrivenKeyEXMasterMC documentation.

INTERFACE

The interface is resizable.

1.) Channels: this is where you select the channel you wish to track.

2.) Target: the string field located at the upper side shows the 'local' channel (e.g. the channel the script is applied to) enclosed in brackets, and it points to the currently targetted channel along with the Channel Group(s) it is attached to.

3.) Target Cap / Self Cap: Target and Self Cap are 'capping' features, to turn off SDKEXCF's influence if they exceed the range of the specified values. If you 'cap low' the Target (or T), then SDKEXCF will stop influencing the channel when the Target's (of Driver's) value of that particular channel goes below. If you chose 'cap high' then SDKEXCF will stop influencing if it reaches above the specified value. S stands for Self, and this is the same as Target, only that it looks at the value of the channel the script has been applied to, for reference. If you do wish to use 'capping' make sure the state buttons remain deactivated.

Note the input boxes will appropriately change depending on the type of channel (e.g. percentage, numerical, angle, distance). Obviously, the Self Limits will always be of the type of the channel that the script is attached to.

As you can see, the previous SDKCF had A and B values. In SDKEXCF, that's passé. :) More below.

4.) Start and End: these denote the frame range that the script will be active within. If the start frame inputted is higher or equal to the end frame then the script will assume that you do not want to specify a range, and will therefore keep the script active always. If you do specify a range and then go out of range, the script will not compute and the channel will snap to its keyframed position.

5.) Key: clicking on this button will establish a connection (I term it "relations") between the value of the Self Channel (Driven) and the value of the Target Channel (Driver). It will literally create a key in its Relations Channel.

6.) Setup Mode: you must have this turned on if you wish to key your relations properly. Failing to be in Setup Mode when you hit Key might have some insidious consequences. I say "might."

7.) Relations > GE / Self Channel > GE: these buttons send the channel in question to the Channel Bin. This is primarily used so that you can edit your curves more thoroughly.

RELATIONS CHANNELS

Okay, this is the 'big' thing, the thing that makes SDKEXCF very different. A word of thanks to Markus for reminding me how possible this is.

To put it succintly, Relations Channels are channels that EX uses to map the values it will apply to the Self Channel over the values of the Target Channel. The illustration shows a Relations Channel.

In ordinary channels, we map values over time (or frames). When we read this way, we look at the curve above and we say: "At frame 0.0, the value of the channel is at 0 degrees; at frame 2.758 , the value is at 20.48 degrees." But when we talk about Relations Channels, the time dimension is interpreted as an actual value. Let us suppose that our Self Channel is targetted to Camera.Position.X. We read Relations Channels this way: "At 2.758 meters (Position.X), the value that the Self Channel ought be at is 20.48 degrees." It may get confusing at first, but remember these two simple guidelines:

1.) The Self Channel, or the value that will be applied to the Self Channel is at the left of the graph.

2.) The Target Channel is at the bottom, where the frame timeline is. Here, the frames must be interpretted according to the Target's channel type:

a.) DISTANCE: read the frame number as meters: frame 1.0 is one meter, frame 0.45 is 45 centimeters.

b.) NUMBER: read it as is.

c.) PERCENTAGE: read it as if it was scaling factor. Frame 1.0 is 100%, frame 3.45 is 345%.

d.) ANGLE: read it as is. Frame 45.4 is 45.5 degrees.

Relations Channels are arranged into a channel group called RelationsChannels in the Graph Editor. Furthermore, they are identified uniquely by an "RC." prefix to the actual channel they have been assigned to. In the above illustration, I've applied an SDKEXCF instance to my hands_L.pinky02.Rotation.P channel.

Remember that each applied SDKEXCF instance will have its own unique Relations Channels; you cannot share Relations Channels. If you wish for one channel to share Relations Channels, however, do not apply an EX instance on that channel. Instead, just simply use Channel Follower on the channel that uses the Relations Channel you want. Do not apply a Channel Follower instance on a Relations Channel, or do not refer to a Relations Channel in Channel Follower.

Because Relations Channels are indeed actual channels, you can use the power of the Graph Editor to manipulate those curves as you see fit. In the previous SDKCF there was a Pre-, Post-Behavior feature. This has been removed from EX because the curves will handle all that. If you want, in SDKCF parlance, to 'overshoot' select the Offset Repeat behavior.

A QUICK RUN-DOWN ON USAGE

This is the simplest, most direct form of usage of SDKEXCF.

1.) Clear your scene and select your Camera.

2.) Open up your Graph Editor and press Shift+G to bring the selected Layout item's channels to the Channel Bin.

3.) Select the channel Camera.Position.X.

4.) From the Modifiers Tab and Add Modifiers popup, select SetDrivenEXCF from the list.

5.) Open up the interface.

6.) In the Target Channels list box, select Light.Rotation.H.

7.) Click on the Key button. This will record the Target Channel's values (Rotation.H: 45 degrees) and relate that to the Self Channel's value (Position.X: 0 meters).

8.) Select your Camera and move anywhere along the X-axis.

9.) Then select your Light and rotate its heading at any value.

10.) Click Key again. This will, once again, relate the current value of the Target Channels to the current value of the Self Channels.

11.) Test the connection by disabling Setup Mode and creating keys for the Light's heading.

SETTING UP SDKEXCF FOR JOINT MORPHING

This seems to be one of the most popular application. So I'll quickly demonstrate how to do it. It's rather simple and straightforward. I will be assuming that you are using Morph Mixer for deformations.

1.) Locate the morph channel that you wish the drive, and put it in the Channel Bin.

2.) Apply an SDKEXCF instance on the morph channel.

3.) Open up the interface. Make sure the Setup Mode is turned on.

4.) On the Target Channels list, search for and select the driver channel (e.g. the bone's channel).

5.) You will see the interface update according to the Target's channel type.

6.) Put the joint in neutral pose. Then adjust your morph value that corresponds to the bone's neutral pose ( by either using the Morph Mixer panel or the Graph Editor).

7.) Click Key. This records the relation between the Self Channel and the Target Channel values.

8.) Now put the joint in a bent position and your morph value to the corresponding value.

9.) Click Key.

10.) Put your joint in an extreme position and your morph the same.

11.) Click Key once more.

12.) Test the relations by turning off the Setup Mode and create keyframes for the joint bone, and rotating it. Note that the script works with IK, too.

JOINT MORPHING WITH MULTIPLE MORPH MAPS

If you look at the Joint Morphing example usage, you notice that it only uses one morph channel, and thus one morph map only to drive it. There will be times, out of penury of precision, when you will want to have more morph maps to be driven by the bone. Whether or not this is easier to achieve in SDKCF, I do not know. However the way to go about in EX is to use the capping feature. You can tell EX to stop calculating when the Target (or T) value exceeds or goes below a certain value. But you will need, like SDKCF, to attach another instance of EX to pick up the other instance when it stops calculating. In this instance, you must make the capping values match with the other one. It's not hard to figure out, though it does take a bit of time to set it all up.

BUGS & LIMITATIONS

There are no known bugs in EX as of yet.

Same limitations of SDKCF apply to EX: this LScript uses string names to locate the channel that it was previously assigned to. This means that you must take care not to name two Channel Groups identically. This can happen if you have named two items of different types the same; for example, having a camera named "Camera" but renaming the distant light to "Camera" (now, why would you do that?) Furthermore, if you rename an object that is the target of an instance of SetDrivenKeyCF, you may have to reassign it, especially if you wish to save the scene, and load thereafter.

***BUGS APPENDANT (09.22.02)***

There is a bug, not related to the script itself, that concerns copying a channel. Copying a channel (by using the RMB context menu) with an SDKEXCF instance applied will corrupt that instance. This is probably a bug in LScript and the way it loads script instances, or a bug in LightWave in general.

Proceed to the SetDrivenKeyMasterEXMC documentation.

***APPENDANT (09.21.02)***

Thanks to Mascio for reporting this bug: SDKEXCF did not save properly, discarding all the Relations Channels information when the script exited (e.g. scene was reloaded). This has been fixed.

***APPENDANT (09.22.02)***

More fixes and more thanks to Mascio for report this particular bug: SDKEXCF instances that were applied to bones were not being properly referenced upon load time. This resulted in the Relations Channel, that the instance owned, not being recreated on load time, and effectively cancelled out its connection to its driver.

Furthermore, I've observed another irrepairable (at this time) bug concerning channels in the Channel Bin. Please look at the appendant to the BUGS & LIMITATIONS section.

***APPENDANT (09.25.02) --- IK READERS ---***

Taking for granted the functionality I offered in MorphDriverCF for being able to read IK computations, I totally forgot that the methods I use for SDKEXCF were very different. Needless to say there is no inherent ability of SDKEXCF to read IK-driven channels (this functionality is not available to LScript itself, yet). So as a workaround for this I've included a subset of scripts that can work, though not limited for use with SDKEXCF. Before I continue, note: this is obviously a workaround, and while it works very nicely, it is not workflow-friendly.Be prepared to wince.

The concept of IK Readers is to create channels that contain, instead of keyframe information, inverse kinematics computations. The only current avenue available to LScript-writers to access IK information is through the Item Animation module or architecture. Thus, IK Readers have two parts: one Channel Filter script, and one Item Animation script. Are you quivering yet? There's more.

Because of the current restrictions for inter-plugin communications it is not possible to 'spawn' multiple instances of these two scripts on-demand. Thus, I've included ten (10) scripts for each (twenty in all). The best part is (and I mean that sarcastically), if you want to refer to more IK-driven channels than just ten, you're going to have to create new scripts based on the scripts provided. I've included a spawner that will ease this part considerably - see below.

But really, this workaround works great and there's little hit on speed. Let me go through what it involves:

1.) The first step is to 'tag' the items that have IK in them. You tag them by applying IKReaderIA_## as a Motion Modifier (or Item Animation modifier). Click open the interface and select one of the three possible rotational channels.

2.) The second step is to create a custom channel (using the Master Channel plug-in - you can find that in the Master Class Plug-ins panel). Set the channel type to ANGLE then press OK.

3.) Third step: go to the Graph Editor and load up the channel. It should be located under the MC channel group. Once you locate it, put it up the Channel Bin and apply the IKReaderCF_## script on it.

4.) The important thing to remember is that the scripts correspond with their numbers. IKReaderCF_04 will try to locate and read IKReaderIA_04. If it cant see it, it will inform you.

5.) Once you have the two scripts connected, the channel itself wont look anything special. In fact, it will look like nothing is happening (unlike other Channel Filter scripts and plug-ins which trace the their effect influence by a dotted curve or line). The reason is that the CF script is calling the IA on demand, so it cannot 'predict' the values farther on.

6.) So now you have a channel that contains IK. Now what? Well, suppose you want to connect a certain morph to that IK channel: apply SDKEXCF to the morph map channel and have it point to the IK channel. Then it's just a simple matter of keying them: key the morph at 0% when the angle of the bone determines no morph effect. Then, move your goal item so that it reaches the angle where the morph should be maximum, adjust the morph channel to 100% and then click Key again. Remember to switch Setup Mode off.

Last important notes on spawning the LScripts: if you wish for more LScripts (thus more IK channels), please do not mail me to ask for it. I've gone through some pains to write IKReaderSpawner that will spawn both IA and CF IKReaders. The spawner is 'smart' and will detect the difference between IA and CF. All you have to do is select either IKReaderIA_## or IKReaderCF_## and it will prompt you for the range (thus the number) of spawns. You may not, due to 'security reasons' specify a start spawn of less than 11. In other words, the provided 20 scripts must remain untouched as much as possible.

Contact me at: faulknermano1@yahoo.com