October 29th, 2008

Retime, insert, and clean up keyframes, and other useful keyframe stuff.


Move both included scripts (abKeyWrangler.mel and abKWBuildMarkingMenu.mel) into your Maya scripts directory and restart Maya (or rehash).  Run the following script from the mel command line to bring up the script interface:

source abKeyWrangler.mel;abKeyWrangler;

How to Use It

To retime an animation you first have to select a range of keyframes in the Graph Editor.  You can then use the quick retime buttons at the top of the UI to add or subtract a set number of frames to the selected range or you can set your new desired range by entering values in the New Start and Endframe fields.

To insert frames you can select an object (or objects) or you can select animation curves in the Graph Editor.  Frames are inserted (or deleted) before or after the current time based on the value of the "Insert/Delete After Current Time" checkbox.

The "Curve Color" menu allows you to color the translate, rotate and scale animation curves of selected objects (usually control curves) from dark to light in the order selected.  This can be especially useful when you're working on a hierarchy of several control curves at the same time (like a spine or FK limb) and want to identify which animation curve goes with which control curve at a glance.  It makes sense when you see it.

"Filter Curves By ChannelBox Selection" under the "Options" menu, when enabled, will limit the animation curves displayed in the Graph Editor to those that match the attributes selected in the ChannelBox.

Convert Curves

As of version 1.3, the script has the ability to quickly convert curves from stepped to spline.  When you click the  "Convert" tab you'll see this interface.  It allows you to specify different types of tangents (and whether those tangents are broken or free weighted) for each of four different keyframe situations.

Peaks (or valleys) are keyframes with neighbors that are both either above or below them.  Ledges are keys with one neighbor at the same value and the other above or below it.  Plateaus are found between ledges; they're the keys with both neighbors at the same value.  And slopes are exactly what they sound like: keys with one neighbor above them and the other below.

Version 2.1 adds valleys to the mix as well.  It also includes a quick select conversion profile pop up menu, accessible by right clicking on the "Convert Selected Curves" button.

The Marking Menu

Version 2.1 of the script now includes its own marking menu.  It incorporates the features of my sonorously named tangentMarkingMenuMod script (among other things) without the hassle of having to replace files in the Maya install directory.

To activate it click "Enable Custom Marking Menu" under the "Options" menu of the script UI.  Once enabled, it will add "Lock Tangents" and "Free Tangents" options to your shift+s Middle Mouse Button (MMB) marking menu and create an entirely new menu mapped to your shift+s Right Mouse Button (RMB).  Here's a quick description of the new menu items and their functions:

  • Prev Key: Select the keys immediately preceding any selected keyframes in the GE.  If no keys are selected it will move to the previous keyframe in the timeline.
  • Next Key: Select the keys immediately following any selected keyframes in the GE.  If no keys are selected it will move to the next keyframe in the timeline.
  • Set To Prev: Will set a keyframe on (in order of precedence) any selected keys, any selected curves (at the current time), or any selected objects (at the current time) with the same value as the previous key.
  • Set To Next: Will set a keyframe on (in order of precedence) any selected keys, any selected curves (at the current time), or any selected objects (at the current time) with the same value as the next key.
  • Blend Prev/Next: A sub menu that allows you to set new keys as above by blending the influence of the previous and next keys.
  • ChannelBox Filter: If enabled, curves displayed in the GE will be filtered by highlighted channels in the channelBox.  For example you could select all of the spine curves on a character, enable the channel filter, and select the x rotation channel in the channelBox to display only those curves for each spine control (note: this is where the "Curve Color" feature comes in very useful).
  • Zero Selected: Will set the values of all selected keys to zero.
  • Copy/Paste SubMenu: Copy and paste individual key values (further detail below).
  • Move Time: If enabled, will update the current time to an average (if more than one key is selected) of the newly selected keyframes.
  • Extrapolate Curves: Will set a new key at the current time that maintains the slope of the selected animCurve(s).  Intended to be used before the first or after the last key on a curve.
  • Average Selected Keys: Set the selected keys on each curve to their average value.
  • Straighten Selected Keys: Set the key values such that they form a straight line between the preceeding and following unselected keys
  • Subdivide Curves: Insert a frame every n (chosen in the sub menu) number of frames on the selected curves between selected keyframes.
  • Convert Curves: Convert selected curves using one of several conversion profiles.
  • Clean Selected Curves: Run "Clean Selected Curves" on the selected curves.
  • Snap Selected Keys: Run "Clean Up Fractional Keys" on the selected keyframes, averaging overlapping keys.
  • Default Key Tangents: Select a mode to set the global in and out key tangents.

Copy (Copy/Paste SubMenu)

Copy animCurve values based on the current selection.  When copying with:

  • No Curve Selection: All keyable attributes on the current object selection will be copied at the current time.
  • Curve Selection (multiple keys selected on at least one highlighted curve): Values for the selected curves will be copied at the current time.
  • Key Selection (no more than one key selected on each highlighted curve): Values for the selected keys will be copied.

Paste (Copy/Paste SubMenu)

Paste animCurve values based on the current selection.  When pasting with:

  • No Curve Selection: The entire save buffer will be pasted at the current time.
  • Curve Selection (multiple keys selected on at least one highlighted curve): Values from the save buffer will be pasted at the current time only on selected curves (which may yield no result if none of the selected curves are in the save buffer).
  • Key Selection (no more than one key selected on each highlighted curve): Values from the save buffer will be pasted to the selected keys.

A Few Notes

If you find that the custom marking menu has disappeared during your Maya session, you can reactivate it by calling the script again ("source abKeyWrangler.mel;abKeyRangler;").  Once the marking menu is back you can close the UI.

If you have issues with the Translate Tool marking menu showing up when you don't want it to while using the shift+s RMB marking menu, click "Disable Translate Tool MM In Graph Editor" in the "Options" menu.  The marking menu will be disabled only while the mouse is above the Graph Editor.

If you want the custom marking menu installed by default when you start Maya, add the following to your userSetup.mel file (in your scripts directory):

source abKeyWrangler.mel;abKWStartStopCustomMM(true);

That's it.  Enjoy!


Version 1.1
October 30th, 2008 Added "Options Menu" with option to "Filter Curve By ChannelBox Selection".  Added "Curve Color" menu.  It allows you to color the translate, rotate and scale curves of selected objects from dark to light.  This comes in handy when you're working on animating a hierarchy (like a spine or FK arm) and have several curves selected at once in the Graph Editor.  Improved script handling of namespaces.
Version 1.2
November 6th, 2008 Added "Select Menu" to quickly select animation curves in your scene from characterSets, lights and cameras.
Version 1.3
December 2nd, 2008 Added "Convert" tab to give lots of control in converting stepped curves to splines.  Added "Reset Globals To Defaults" to "Options" menu.  Also added the ability to switch the default global key tangent mode under the "Options" menu.  Improved curve cleaning to work better with stepped curves and just be faster in general.
Version 1.4
December 3rd, 2008 Fixed a few issues with convert keys.  Step conversion now works correctly, and end keys are converted as expected.  The interface now remembers the last tab selected.
Version 1.5
December 23rd, 2008 Gradient Color Curves wasn't always finding the selected objects' animCurves.  It should now.  Tolerance on animCurve conversion is now relative to each curve's value range.
Version 1.6
March 16th, 2009 Added "All Curves" under Select menu, which should select all of the user anim curves (camera, light, nurbs curve, transform, motionPath -- stuff you've set set keyframes on).  Also added the "Snap Selected Keys" checkBox to the retiming tab.
Version 1.7
July 30th, 2009 Added "Previous Key" and "Next Key" under "Select" menu (requires a selection of keys in the Graph Editor).
Version 1.8
August 4th, 2009 Added "Clean Up Fractional Keys" button to the "CleanUp" tab.  It's my version of snap keys.  It's also now used when "Snap Selected Keys" is enabled in the "Retime" tab.
Version 2.1
September 21st, 2009 Added custom marking menu with lots of new features (shift+S RMB in the Graph Editor).  Added Valley tangents in convert curves box.  Added "Color" tab to color key ticks.  Select keys in the Graph Editor or ticks in the timeline to color keyframes for selected or displayed curves.    Added quick select convert profiles to the "Convert Selected Curves" button.
Version 2.2
November 13th, 2009 Added "Copy Keys" and "Paste Keys" to marking menu: select individual keys to copy (one per curve), curves or objects.  Added "Objects From Selected AnimCurves" in "Select" menu.  Replaced "Current Time To Sel" (south position in the custom marking menu) with "Zero Selected": select some keys in the GE, run this and they'll be zeroed.  Added "Extrapolate Curves": select one or more curves, move the current time to a frame before the first or after the last key, run this and a new key that maintains the slope of the curve will be created.
Version 2.3
December 9th, 2009 Can now paste a key value to multiple selected keys (so long as not all the keys on the animCurve are selected).  Added "Average Selected Keys", "Straighten Selected Keys", "Subdivide Curves", "Convert Curves", and "Default Key Tangents" to the marking menu.  Improved the way fractional keys are snapped (especially with keys on a slope).  Results should end up closer to the original curve than previously (added a few more checkbox options).
Version 2.5
January 4th, 2010 Added "Scale" tab and moved color tab options to "Color" menu.
Version 2.51
March 16th, 2010 Convert Keys now respects key selection (unselected keys won't be converted); fixed a major issue with curve cleaning (curves should maintain their shape now).
Version 2.7
May 25th, 2011 Added previous/next blend slider under Blend Prev/Next sub menu.  Fixed a bunch of marking menu issues.  Adjusted UI and improved popup menu behaviour for 2011 and up.  Added support for auto tangents in 2012 and beyond.  Fixed bug in curve cleaning.
Version 2.91
October 18th, 2011 Added "Apply Default Tangents To New Keys" in the Insert tab "Blend Previous/Next" Section.  New keys created as the result of a blend are now added to the selection, so consecutive blend adjustments should work more intuitively.  Added option to auto assign special tick color to newly inserted keys when blending between previous/next keys.  Added "Auto Assign Prev/Next Key Tangents On Blend".  Added "Linear Mode" to keying modes.  Added the ability to limit the curves adjusted using the blend prev/next tool (in either the marking menu "Blend Prev/Next", or the "Insert" tab of the script UI) to those channels selected in the channelBox.  Removed Filter Keys for Maya 2012 and up since it's now built in (mostly) and replaced it on marking menu with "Show UI" command.
Typo Correction
January 18th, 2012 Fix a typo in the instructions that gave the incorrect command to run the script.  It should have read "source abKeyWrangler;abKeyWrangler;".

"abKeyWrangler" was posted on October 29th, 2008 under Mel Scripts.  It was created using Maya.  It is tagged with Animation, Keys and Tween.

This entry was last updated on January 18th, 2012.

Subscribe to the Comments Feed or Updates Feed for this entry.

Share |


August 5th, 2009 said:

Love this script, use it every time I animate anything.

October 3rd, 2009 said:

Hey! it looks great man, I'd love to try it, but i'm a "newbie"  using scripts in maya and I donīt know exactly what I have to do for actually see the GUI... :-0

October 6th, 2009 said:

Hey Claude,

Sorry about that.  I've added the instructions to the top of this page.

October 7th, 2009 said:

Thanks a lot  man...u Rock!

November 8th, 2009 said:

Hey there Crumbly- First off i want to say that this seems like an incredible Mel script and i'm dieing to use it..but i'm rather having a difficult time installing it.. Whenever i try to run  -  source abKeyWrangler.mel;abKeyRangler;- it says that it cannot find procedure abKeyRangler.... not sure how to go about fixing that and i tried to figure it out for an hour haha... Sorry if it's something simple, I'm rather new to the whole dowloading MEL script thing

November 8th, 2009 said:

Hey MontyQ,

Oops, it looks like I misspelled the name of the procedure in the instructions.  It should be "abKeyWrangler" instead of "abKeyRangler".  I hope that hasn't tripped up too many people.

November 8th, 2009 said:

It works!!!  :D Thankyou so much Crumbly! This will def. be my tool for life haha

December 10th, 2009 said:

First off, AWESOME script!  I have a quick question though...  Is there an option to disable the marking menu in the viewport?  I'm so used to Shift + LMB selecting multiple controls, but once I open the UI I can no longer shift select.  Or is there a way to assign the marking menu to something other than Shift + LMB?  Sorry if this is something simple that I'm overlooking.

December 10th, 2009 said:

Hey adam,

So when you press Shift+LMB in a model view the keyWrangler marking menu pops up?

That's weird.

I'm not sure how it could be happening.  My marking menu just piggy backs onto an existing Maya menu that's assigned by default to both Shift+s+LMB and Shift+s+MMB.  abKeyWrangler just modifies the Shift+s+MMB menu and adds a new menu to Shift+s+RMB.  It's only called when the Graph Editor is the active pane, though, so I'm not sure how it's interfering with your shift select (it works for me on 2008 x64).

I'll try and figure out what might be going on, but in the meantime you can put this version of the marking menu into your prefs\markingMenus directory and assign it to a hotkey in the hotkey editor.

December 11th, 2009 said:

I did notice that if I bring up the menu with Shift + s + LMB once the UI is up, the Shift + LMB goes back to normal and all is good.  But if I close the UI and open it again, it's back to Shift + LMB bringing up the menu.  It's not a HUGE deal.  Once I open the UI, I leave it open.  So it's just a matter of doing this once, each time I open Maya.

just say it


Related Posts