pasteKey command

Go to: Return value. Related commands. Flags. Examples.

Synopsis

pasteKey [flags] [objects]

The pasteKey command pastes curve segment hierarchies from the clipboard onto other objects or curves. If the object hierarchy from which the curve segments were copied or cut does not match the object hierarchy being pasted to, pasteKey will paste as much as it can match in the hierarchy. If animation from only one object is on the clipboard, it will be pasted to each of the target objects. If animation from more than one object is on the clipboard, selection list order determines what animation is pasted to which object.

Valid operations include:

One attribute to one or more attributes (Clipboard animation is pasted onto all target attributes.
One attribute to one or more objects (Clipboard animation pasted onto target object, when attribute names match.)
Many attributes to one or more objects
Clipboard animation pasted onto targets when attribute names match.

This command operates on a keyset. A keyset is defined as a group of keys within a specified time range on one or more animation curves.

The animation curves comprising a keyset depend on the value of the "-animation" flag:

keysOrObjects:
1. Any active keys, when no target objects or -attribute flags appear on the command line, or
2. All animation curves connected to all keyframable attributes of objects specified as the command line's targetList, when there are no active keys.
keys: Only act on active keys or tangents. If there are no active keys or tangents, don't do anything.
objects: Only act on specified objects. If there are no objects specified, don't do anything.

Note that the "-animation" flag can be used to override the curves uniquely identified by the multi-use "-attribute" flag, which takes an argument of the form attributeName, such as "translateX".

Keys on animation curves are identified by either their time values or their indices. Times and indices can be given individually or as part of a list or range.

-time 10pal means the key at frame 10 (PAL format).
-time 1.0sec -time 15ntsc -time 20 means the keys at time 1.0 second, frame 15 (in NTSC format), and time 20 (in the currently defined global time unit).
-time "10:20" means all keys in the range from 10 to 20, inclusive, in the current time unit.

Omitting one end of a range means "go to infinity", as in the following examples:

-time "10:" means all keys from time 10 (in the current time unit) onwards.
-time ":10" means all keys up to (and including) time 10 (in the current time unit).
-time ":" is a short form to specify all keys.

-index 0 means the first key of each animation curve. (Indices are 0-based.)
-index 2 -index 5 -index 7 means the 3rd, 6th, and 8th keys.
-index "1:5" means the 2nd, 3rd, 4th, 5th, and 6th keys of each animation curve.

The way the keyset clipboard will be pasted to the specified object's attributes depends on the paste "-option" specified. Each of these options below will be explained using an example. For all the explanations, let us assume that there is a curve segment with 20 frames of animation on the keyset clipboard (you can put curve segments onto the clipboard using the cutKey or copyKey commands). We will call the animation curve that we are pasting to the target curve:

pasteKey -time 5 -option insert
1. Shift all keyframes on the target curve after time 5 to the right by 20 frames (to make room for the 20-frame clipboard segment).
2. Paste the 20-frame clipboard segment starting at time 5.
pasteKey -time "5:25" -option replace
1. Remove all keys on the target curve from 5 to 25.
2. Paste the 20-frame clipboard curve at time 5.
pasteKey -option replaceCompletely
1. Remove all keys on the target curve.
2. Paste the 20-frame clipboard curve, preserving the clipboard curve's original keyframe times.
pasteKey -time 5 -option merge
1.The clipboard curve segment will be pasted starting at time 5 for its full 20-frame range until frame 25.
2. If a keyframe on the target curve has the same time as a keyframe on the clipboard curve, it is overwritten. Otherwise, any keys that existed in the 5:25 range before the paste, will remain untouched
pasteKey -time "3:10" -option scaleInsert
1. Shift all keyframes on the target curve after time 3 to the right by 7 frames (to clear the range 3:10 to paste in)
2. The clipboard curve segment will be scaled to fit the specified time range (i.e. the 20 frames on the clipboard will be scaled to fit into 7 frames), and then pasted into the range 3:10.
pasteKey -time "3:10" -option scaleReplace
1. Any existing keyframes in the target curve in the range 3:10 are removed.
2. The clipboard curve segment will be scaled to fit the specified time range (i.e. the 20 frames on the clipboard will be scaled to fit into 7 frames), and then pasted into the range 3:10.
pasteKey -time "3:10" -option scaleMerge
1. The clipboard curve segment will be scaled to fit the specified time range (i.e. the 20 frames on the clipboard will be scaled to fit into 7 frames).
2. If there are keys on the target curve at the same time as keys on the clipboard curve, they are overwritten. Otherwise, keyframes on the target curve that existed in the 3:10 range before the paste, will remain untouched.
pasteKey -time "3:10" -option fitInsert
1. Shift all the keyframes on the target curve after time 3 to the right by 7 frames (to clear the range 3:10 to paste in)
2. The first 7 frames of the clipboard curve segment will be pasted into the range 3:10.
pasteKey -time "3:10" -option fitReplace
1. Any existing frames in the target curve in the range 3:10 are removed.
2. The first 7 frames of the clipboard curve segment will be pasted into the range 3:10.
pasteKey -time "3:10" -option fitMerge
1. The first 7 frames of the clipboard curve segment will be pasted into the range 3:10.
2. If there are keys on the target curve at the same time as keys on the clipboard curve, they are overwritten. Otherwise, keyframes on the target curve that existed in the 3:10 range before the paste, will remain untouched.

Return value

int The number of curves pasted

Related commands

copyKey, cutKey, snapKey, keyframe, keyframeStats, keyframeOutliner, scaleKey, setInfinity, keyTangent, findKeyframe

Flags

animation, attribute, clipboard, connect, controlPoints, copies, float, floatOffset, hierarchy, includeUpperBound, index, option, shape, time, timeOffset, valueOffset

Long name (short name) [argument types] Properties

-option (-o) string

Valid values are "insert", "replace", "replaceCompletely", "merge", "scaleInsert," "scaleReplace", "scaleMerge", "fitInsert", "fitReplace", and "fitMerge". The default paste option is: "insert".

-clipboard (-cb) string

Specifies the clipboard from which animation is pasted. Valid clipboards are "api" and "anim". The default clipboard is: anim

-connect (-c) boolean

When true, connect the source curve with the destination curve's value at the paste time. (This has the effect of shifting the clipboard curve in value to connect with the destination curve.) False preserves the source curve's original keyframe values. Default is false.

-copies (-cp) int

The number of times to paste the source curve.

-timeOffset (-to) time

How much to offset the pasted keys in time (for time-input animation curves).

-floatOffset (-fo) float

How much to offset the pasted keys in time (for non-time-input animation curves).

-valueOffset (-vo) float

How much to offset the pasted keys in value.

-attribute (-at) string

List of attributes to select

-hierarchy (-hi) string

Hierarchy expansion options. Valid values are "above," "below," "both," and "none." (Not valid for "pasteKey" cmd.)

-shape (-s) boolean

Consider attributes of shapes below transforms as well, except "controlPoints". Default: true. (Not valid for "pasteKey" cmd.)

-controlPoints (-cp) boolean

This flag explicitly specifies whether or not to include the control points of a shape (see "-s" flag) in the list of attributes. Default: false. (Not valid for "pasteKey" cmd.)

-index (-in) TuInt32

index of a key on an animCurve

-time (-t) timeRange

time uniquely representing a key (or key range) on a time-based animCurve. Valid timeRanges include single values (-t 10) or a string with a lower and upper bound, separated by a colon (-t "10:20")

-float (-f) floatRange

value uniquely representing a non-time-based key (or key range) on a time-based animCurve. Valid floatRange include single values (-f 10) or a string with a lower and upper bound, separated by a colon (-f "10:20")

-includeUpperBound (-iub) boolean

When the -t/time or -f/float flags represent a range of keys, this flag determines whether the keys at the upper bound of the range are included in the keyset. Default value: true. This flag is only valid when the argument to the -t/time flag is a time range with a lower and upper bound. (When used with the "pasteKey" command, this flag refers only to the time range of the target curve that is replaced, when using options such as "replace," "fitReplace," or "scaleReplace." This flag has no effect on the curve pasted from the clipboard.)

-animation (-an) string

Where this command should get the animation to act on. Valid values are "objects," "keys," and "keysOrObjects" Default: "keysOrObjects." (See Description for details.)

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can be used more than once in a command

Examples

	// Paste keyframes onto nurbsSphere1's translateX attribute at time 10
	//
	pasteKey -time 10 -attribute translateX nurbsSphere1;
	
	// Paste to all active objects, preserving the timing from the clipboard.
	//
	pasteKey;