CKey Manual

About

A CKey represents a key of an animation track. CKey objects are stored in a CCurve which in return is stored in a CTrack object.

CKey objects are an instance of CKbase.

// This code loops through all tracks and all keys of the given object.
CTrack* track = activeObject->GetFirstCTrack();
while (track != nullptr)
{
CCurve* const curve = track->GetCurve();
if (curve == nullptr)
continue;
const Int32 keyCount = curve->GetKeyCount();
for (Int32 i = 0; i < keyCount; ++i)
{
CKey* const key = curve->GetKey(i);
if (key)
{
// do something with the key
ApplicationOutput("Found a key!");
}
}
track = track->GetNext();
}
Py_ssize_t i
Definition: abstract.h:645
PyObject * key
Definition: abstract.h:289
CTrack * GetFirstCTrack()
Definition: c4d_baselist.h:2740
Definition: c4d_canimation.h:366
const CKey * GetKey(Int32 index) const
Definition: c4d_canimation.h:388
Int32 GetKeyCount() const
Definition: c4d_canimation.h:381
Represents a key in the CCurve of a track which represent the animation of a parameter.
Definition: c4d_canimation.h:58
Definition: c4d_canimation.h:671
CTrack * GetNext() const
Definition: c4d_canimation.h:716
CCurve * GetCurve(CCURVE type=CCURVE::CURVE, Bool bCreate=true)
Definition: c4d_canimation.h:835
maxon::Int32 Int32
Definition: ge_sys_math.h:60
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210

Access

CKey objects are accessed via the host CCurve:

See CCurve Manual.

// This example searches for a key left from the given time.
const BaseTime time = doc->GetTime();
CKey* const leftKey = curve->FindKey(time, nullptr, FINDANIM::LEFT);
if (leftKey)
{
// move this key to the current time
leftKey->SetTime(curve, time);
}
Definition: c4d_basetime.h:25
const CKey * FindKey(const BaseTime &time, Int32 *idx=nullptr, FINDANIM match=FINDANIM::EXACT) const
Definition: c4d_canimation.h:404
void SetTime(CCurve *seq, const BaseTime &t)
Definition: c4d_canimation.h:96
@ LEFT
Search left.
const char * doc
Definition: pyerrors.h:226

The host objects are accessed with:

Allocation/Deallocation

A CKey object can be created with the usual tools:

But typically keys are created using the host CCurve:

Keys can also be created using auto key functionality of the BaseDocument:

The default settings of a key are defined in the BaseDocument:

See also BaseDocument Animate.

Handle

CKey objects are manipulated with the host CCurve object.

// This example creates a new key and sets the default values.
CKey* const newKey = curve->AddKey(time, &index);
if (newKey == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
track->FillKey(doc, obj, newKey);
void SetKeyDefault(BaseDocument *doc, Int32 kidx)
CKey * AddKey(const BaseTime &time, Int32 *nidx=nullptr, Bool bUndo=false, Bool SynchronizeKeys=false)
Definition: c4d_canimation.h:423
Bool FillKey(BaseDocument *doc, BaseList2D *bl, CKey *key)
Definition: c4d_canimation.h:821
PyObject * obj
Definition: complexobject.h:60
Py_ssize_t * index
Definition: abstract.h:374
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67

Properties

Parameters

The parameters of a key can be edited as usual with C4DAtom::SetParameter() and C4DAtom::GetParameter(). The parameter IDs are defined in ckvalue.h.

// This example sets the "Break Tangents" parameter of the first key.
CKey* key = curve->GetKey(0);
if (key)
{
}
@ ID_CKEY_BREAK
Definition: ckvalue.h:20
#define ConstDescID(...)
Definition: lib_description.h:594
Represents a level within a DescID.
Definition: lib_description.h:298
Note
The boolean parameters of a key are stored internally as bits, see Bits.

Selection

In Cinema 4D there can be up to four Timeline windows. A key can be selected in one or multiple of these windows. The selection state is stored as a bit:

// This example selects the first key in the first timeline window.
CKey* key = curve->GetKey(0);
if (key)
{
}
@ SET
Set bit.
@ TL1_SELECT
Selection bit for Timeline 1.

Time

An animation key is defined by its position in time:

// This example moves the current key one frame along the timeline.
BaseTime time = key->GetTime();
time = time + BaseTime(1, doc->GetFps());
key->SetTime(curve, time);

See also BaseTime Manual.

Value

An animation key defines a certain value at a certain time:

Note
Data of special tracks can be read and set using C4DAtom::GetParameter() and C4DAtom::SetParameter().
To set the keyframe for a Vector parameter one must define tracks and keyframes for each vector component.
// This example handles the key value depending on the track category.
// check if the track is "value" track (float)
{
Float value = key->GetValue();
value = value + 1.0;
key->SetValue(curve, value);
}
// check if the track is "data" track
else if (track->GetTrackCategory() == CTRACK_CATEGORY_DATA)
{
GeData data = key->GetGeData();
// handle GeData
key->SetGeData(curve, data);
}
PyObject * value
Definition: abstract.h:715
Int32 GetTrackCategory() const
Definition: c4d_canimation.h:851
Definition: c4d_gedata.h:83
maxon::Float Float
Definition: ge_sys_math.h:66
#define CTRACK_CATEGORY_VALUE
Value track.
Definition: c4d_canimation.h:633
#define CTRACK_CATEGORY_DATA
Data track.
Definition: c4d_canimation.h:634

See also CTrack Read-Only Properties and CCurve Animation.

Tangents

A key also defines the local tangents. These tangents influence the interpolation between the keys.

The modes are:

The left and right tangents are defined by two points. These two points are defined by time and value.

The time property of the tangents can be accessed with:

The value property of the tangents can be accessed with:

The left and right tangent can be adjusted with:

// This example shortens the left tangent by one frame
// while preserving the angle by adapting the value.
BaseTime time = key->GetTimeLeft();
time = time + BaseTime(1, doc->GetFps());
key->SetTimeLeftAdjustValue(curve, time);

Interpolation

There are different ways to interpolate between the values of the animation keys. The interpolation from one key to the next is defined per key:

Interpolation modes are:

// This example sets the interpolation of the given key to linear.
key->SetInterpolation(curve, CINTERPOLATION::LINEAR);
@ LINEAR
Linear.

Quaternion Interpolation

Quaternion interpolation can be used on the rotation of a BaseObject. The kind of interpolation can be refined per key.

See also BaseObject Quaternion Rotation Mode.

Preset

Several presets exist to manage the clamp, slope and overshoot behaviour of a key.

The preset modes are:

// This example checks the preset used by the given key.
// If certain preset is used, a different preset is set.
const CKEYPRESET preset = key->GetKeyPreset();
if (preset == CKEYPRESET::AUTO_CLAMP)
{
// change preset
key->SetKeyPreset(curve, CKEYPRESET::AUTO_OVERSHOOT);
}
CKEYPRESET
Definition: ge_prepass.h:4195
@ AUTO_OVERSHOOT
Auto, Auto Angle, remove Overshooting.
@ AUTO_CLAMP
Auto, Auto Angle, Clamp.

Copy

A new CKey can be created by copying an existing one.

// This example creates a clone of the given key
// and places it one second "later" in the timeline.
CKey* const clone = key->GetClone(nullptr);
if (clone == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const BaseTime time = key->GetTime() + BaseTime(1.0);
clone->SetTime(curve, time);
curve->InsertKey(clone);
Bool InsertKey(CKey *ckey, Bool bUndo=false, Bool SynchronizeKeys=false)
Definition: c4d_canimation.h:442

Functionality

The data stored in a key can easily be flushed.

Bits

The boolean parameters of a key are stored internally as bits. These bits can be edited directly.

See also Parameters.

Further Reading