About

Along with the ColorSwatchData and ColorSwatchGroup types these utility functions were introduced to handle colors. The functions are defined in the lib_colorchooser.h header file.

String Conversion

These functions convert a given RGB color value to a formatted String:

ColorRGBToString(): Returns a String presenting the color in RGB format.
ColorHSVToString(): Returns a String presenting the color in HSV format.

  // This example reads the color parameter of the given material
  // and prints the value as RGB and HSV.
 
  // access MATERIAL_COLOR_COLOR parameter
  GeData data;
  if (!material->GetParameter(MATERIAL_COLOR_COLOR, data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const Vector color = data.GetVector();
 
  const String rgbString = ColorRGBToString(color);
  const String hsvString = ColorHSVToString(color);
  ApplicationOutput("Material Color: RGB " + rgbString + ", HSV " + hsvString);

Color Format Conversion

The following functions allow easy conversion of colors stored in different formats.

These functions convert float colors (0.0 ... 1.0) to 8-bit colors (0 .. 255):

ColorComponentFloatTo8Bit(): Converts a float component to 8 bit.
ColorComponent8BitToFloat(): Converts a 8 bit component to float.
ColorFloatTo8Bit(): Converts a float color to an 8 bit color.
Color8BitToFloat(): Converts a 8 bit color to a float color.

These functions convert float colors (0.0 ... 1.0) to 16-bit colors (0 .. 65536):

ColorComponentFloatTo16Bit(): Converts a float component to 16 bit.
ColorComponent16BitToFloat(): Converts a 16 bit component to Float.
ColorFloatTo16Bit(): Converts a float color to a 16 bit color.
Color16BitToFloat(): Converts a 16 bit color to a float color.

Also, a Kelvin color temperature can be converted:

ColorKelvinTemperatureToRGB(): Converts the given Kelvin temperature to a RGB float value.

  // This example calculates a RGB value from a light temperature
  // and applies it to the given "Light" object.
 
  const Float  kelvin = 2600.0; // light bulb
  const Vector rgb = ColorKelvinTemperatureToRGB(kelvin);
 
  light->SetParameter(LIGHT_COLOR, rgb, DESCFLAGS_SET::NONE);

Color Harmony

These functions are used to calculate color palettes based on the given input color.

ColorHarmonyGetComplementary(): Generates the complementary color.
ColorHarmonyGetSplitComplementary(): Generates the split complementary color.
ColorHarmonyGetTetradic(): Generates the tetradic color harmony palette.
ColorHarmonyGetAnalogous(): Generates the analogous color harmony palette.
ColorHarmonyGetEquiangular(): Generates the equiangular color harmony palette.
ColorHarmonyRotateColor(): Generates a palette composed by a defined amount of colors whose hue is separated by a defined angle in HSV color space.
ColorHarmonyInterpolateColors(): Generates a palette composed by a defined amount of colors interpolated between the given colors.

Note: The output maxon::BaseArray contains also the original color.

  // This example reads the color value from the given material.
  // The complementary color is calculated and applied to a new material.
 
  // access MATERIAL_COLOR_COLOR parameter
  GeData data;
  if (!material->GetParameter(MATERIAL_COLOR_COLOR, data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // the original color
  const Vector color = data.GetVector();
 
  maxon::BaseArray<Vector> results;
 
  // calculate the complementary color
  if (!ColorHarmonyGetComplementary(color, false, results))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // check if the result contains both the original and complementary color
  if (results.GetCount() != 2)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get the result color
  const Vector complementaryColor = results[1];
 
  // create new material with complementary color
  BaseMaterial* const newMaterial = BaseMaterial::Alloc(Mmaterial);
  if (newMaterial == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  newMaterial->SetParameter(MATERIAL_COLOR_COLOR, complementaryColor, DESCFLAGS_SET::NONE);
  doc->InsertMaterial(newMaterial);

Table of Contents

About

String Conversion

Color Format Conversion

Color Harmony

Further Reading