A ColorSwatchData object can manage multiple color groups. These color groups can be loaded globally from Cinema 4D, a BaseDocument or a preset and saved back to these sources. Local color groups and global color groups are stored separately. The class is defined in the lib_colorchooser.h header file.

// This example loops through all colors of all color groups of the given BaseDocument.
// For each selected color a new material is created.
// load document color swatches
ColorSwatchData* const colorSwatchData = ColorSwatchData::Alloc(doc, false);
if (colorSwatchData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// AutoFree takes ownership
// loop through groups
const Int groupCount = colorSwatchData->GetGroupCount();
for (Int i = 0; i < groupCount; ++i)
ColorSwatchGroup* group = colorSwatchData->GetGroupAtIndex(i);
if (group)
// loop through colors
const Int colorCount = group->GetColorCount();
for (Int c = 0; c < colorCount; ++c)
Bool selected = false;
// get color and check if it is selected
if (group->GetColor(c, color, &selected) && selected)
// create new material
Material* const mat = Material::Alloc();
if (mat == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// use color
const Vector rgb { color.r, color.g, color.b };
Definition: ge_autoptr.h:152
void Assign(TYPE *p)
Definition: ge_autoptr.h:225
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Definition: lib_colorchooser.h:406
ColorSwatchGroup * GetGroupAtIndex(Int index, SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT)
static ColorSwatchData * Alloc(BaseDocument *doc=nullptr, Bool global=false)
Definition: lib_colorchooser.h:218
Bool GetColor(Int index, maxon::ColorA &color, Bool *selected=nullptr) const
Int GetColorCount() const
Definition: c4d_basematerial.h:241
static Material * Alloc()
maxon::Bool Bool
Definition: ge_sys_math.h:55
maxon::Int Int
Definition: ge_sys_math.h:64
Definition: memoryallocationbase.h:67
Definition: mmaterial.h:56
A color consisting of three components R, G, B and an alpha.
Definition: col4.h:16
T r
Definition: col4.h:33
T g
Definition: col4.h:34
T b
Definition: col4.h:35


ColorSwatchData instances are created with the usual tools:

// This example allocates a new ColorSwatchData object.
// During allocation the color groups of the given BaseDocument are automatically loaded.
if (data == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int groupCount = data->GetGroupCount();
ApplicationOutput("The document contains " + String::IntToString(groupCount) + " color groups");
static void Free(ColorSwatchData *&p)
static String IntToString(Int32 v)
Definition: c4d_string.h:495
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210

Document Colors

Color groups can be stored in a BaseDocument:

// This example loads a Cinema 4D scene file.
// The color swatches of this file are loaded into the given ColorSwatchData object.
// The merged colors are saved back to the original document.
// load colors of the original
if (!colorSwatchData->Load(doc))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// select the scene file
Filename sceneFile;
// open a dialog to select a file
if (!sceneFile.FileSelect(FILESELECTTYPE::SCENES, FILESELECT::LOAD, "Select File"_s))
return maxon::OK;
// load the scene file
BaseDocument* loadedDoc = LoadDocument(sceneFile, SCENEFILTER::NONE, nullptr);
if (loadedDoc == nullptr)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(sceneFile, MAXONCONVERTMODE::NONE), "Could not load document."_s);
// merge the scene file colors
colorSwatchData->Load(loadedDoc, true);
// store merged colors back into the BaseDocument
BaseDocument * LoadDocument(const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr, const ProgressDelegate &progressDelegate=ProgressDelegate())
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
No check if file exists under case-sensitive drives.
Definition: c4d_basedocument.h:498
static void Free(BaseDocument *&bl)
Bool Save(BaseDocument *doc, Bool saveGlobalColors=false)
Bool Load(BaseDocument *doc, Bool merge=false, Bool loadGlobalColors=false)
Manages file and path names.
Definition: c4d_file.h:94
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
return OK
Definition: apibase.h:2620
Load dialog.
3D scene files.


Color swatches can also be stored in the preset library:

To make work with presets easier these utility functions exist:

// // This example checks if a color swatches preset with the given name already exists.
// // If not, the preset is created.
// const String presetName("myColorPreset");
// // check if preset already exists
// if (!ColorSwatchData::PresetExists(presetName))
// {
// // construct url
// SDKBrowserURL presetUrl = ColorSwatchData::GetPresetDirectory();
// presetUrl += presetName;
// // save preset
// if (!colorSwatchData->SavePreset(presetUrl, "User", "This is my preset"))
// return maxon::UnknownError(MAXON_SOURCE_LOCATION);
// }

Color Groups

The color swatches stored in a ColorSwatchData are stored in groups. These groups can either be stored with the document (SWATCH_CATEGORY::DOCUMENT) or with Cinema 4D itself (SWATCH_CATEGORY::GLOBAL).

// This example adds a new group to the given ColorSwatchData.
// Then the name of each group is printed.
colorSwatchData->AddGroup(SWATCH_CATEGORY::DOCUMENT, "New Group");
const Int groupCount = colorSwatchData->GetGroupCount(SWATCH_CATEGORY::DOCUMENT);
for (Int i = 0; i < groupCount; ++i)
const ColorSwatchGroup* const group = colorSwatchData->GetGroupAtIndex(i, SWATCH_CATEGORY::DOCUMENT);
if (group != nullptr)
ApplicationOutput("Group Name: " + group->GetName());
ColorSwatchGroup * AddGroup(SWATCH_CATEGORY category=SWATCH_CATEGORY::DOCUMENT, const String &name=String(), Bool selected=false, Int insertAt=-1, const ColorAlphaArray &colors=ColorAlphaArray())
String GetName() const

Further utility functions are:

Further Reading