How to make different types of colors and color ramps

About making different types of colors and color ramps

The properties available on the IColor interface define the common functionality of all color objects. Representations of colors are held internally as CIELAB colors, described in the Display assembly overview topic. The CIELAB color model is device independent, providing a frame of reference to allow authentic translation of colors between one color model and another.
You can use the GetCIELAB and SetCIELAB methods of the IColor interface to interact directly with a color object using the CIELAB model. Although colors are held internally as CIELAB colors, you do not need to deal directly with the CIELAB color model—you can use the IColor interface to read and define colors. For example, the RGB property can be used to read or write a Long integer representing the red, green, and blue (RGB) values for any color object.
When reading the RGB property, the UseWindowsDithering property should generally be set to true. If UseWindowsDithering is false, the RGB property returns a number with a high byte of two, which indicates the use of a system color, and the RGB property returns a value outside of the range you expected. If you write to the RGB property, the UseWindowsDithering property will be set to true for you. For more information on converting individual byte values to long integer representation, look for topics on color models and hexadecimal numbering in your development environment's Help system.
The IColor interface also provides access to colors through another color model—cyan, magenta, yellow, and black (CMYK). The CMYK property can be used in a similar way as RGB to read or write a Long integer representing the CMYK components of a particular color—the difference being that the CMYK color model requires four values to define a color. The RGBToLong function can be adapted as shown.
Setting the NullColor property to true results in the set color being nullified. Items with color set to null will not appear on the display. This only applies to the specific color objects—not all items with the same apparent color; therefore, you can have different null colors in one Map or PageLayout.
IColor also has two methods to convert colors to and from specific CIELAB colors, using the parameters of the CIELAB color model. You can set a color object to a specific CIELAB color by using SetCIELab, or read CIELAB parameters from an existing color by using GetCIELab. For more information, see the CieLabConversion class.
The feature renderers do not use color transparency; instead, a display filter is used. Setting the transparency on a color has no effect, unless the objects using the color honor this setting. The Color class is an abstract class. When dealing with a color object, you always interact with one of the color classes, which are described in the following section. RGBColor, CMYKColor, HSVColor, and HLSColor are all creatable classes, allowing new colors to be created programmatically according to the most appropriate color model.

Making different types of colors

This section discusses some of the different types of color models supported in ArcObjects. A brief explanation of each color model is given along with sample code for using each model.

RGB color model

RGB is based on the primary colors of light, that is, red, green, and blue.
  • When red, green, and blue rays of light coincide, white light is created. The RGB color model is therefore termed "additive", as adding the components together creates light.
  • An equal triad of fully saturated colors (255,255,255) illuminate white; and, conversely, 0 values illuminate nothing or black.
  • Equal triads between 0 and 100 produce pure gray shades.
The following code example shows a function that creates an RGB-based color in ArcObjects:
[VB.NET] 
Public Shared Function MakeRGBColor(ByVal R As Byte, ByVal G As Byte, ByVal B As Byte) As ESRI.ArcGIS.Display.IRgbColor
Dim RgbClr As ESRI.ArcGIS.Display.RgbColor = New ESRI.ArcGIS.Display.RgbColorClass
With RgbClr
    .Red = R
    .Green = G
    .Blue = B
End With
Return RgbClr
End Function
[C#] 
public static ESRI.ArcGIS.Display.IRgbColor MakeRGBColor(byte R, byte G, byte B)
{
    ESRI.ArcGIS.Display.RgbColor RgbClr = new ESRI.ArcGIS.Display.RgbColorClass();
    RgbClr.Red = R;
    RgbClr.Green = G;
    RgbClr.Blue = B;
    return RgbClr;
}

CMYK color model

CMYK is a color model based on the four color components of cyan, magenta, yellow, and black. The CMYK model, unlike RGB, is termed "subtractive", as adding all the components together creates an absence of light (black).
  • CMYK is the industry standard color model for electronic publishing processes including offset-printing with color plates.
  • During the printing process, the ink coverage is controlled by the size of the dot or halftone screen percentage that is specified for each of the four process colors.
The following code example shows a function that creates a CMYK-based color in ArcObjects:
[VB.NET] 
Public Shared Function MakeCmykColor(ByVal C As Byte, ByVal M As Byte, ByVal Y As Byte, ByVal k As Byte) As ESRI.ArcGIS.Display.ICmykColor
Dim CmykClr As ESRI.ArcGIS.Display.CmykColor = New ESRI.ArcGIS.Display.CmykColorClass
With CmykClr
    .Cyan = C
    .Magenta = M
    .Yellow = Y
    .Black = k
End With
Return CmykClr
End Function
[C#] 
public static ESRI.ArcGIS.Display.ICmykColor MakeCmykColor(byte C, byte M, byte Y,
    byte k)
{
    ESRI.ArcGIS.Display.CmykColor CmykClr = new ESRI.ArcGIS.Display.CmykColorClass();
    CmykClr.Cyan = C;
    CmykClr.Magenta = M;
    CmykClr.Yellow = Y;
    CmykClr.Black = k;
    return CmykClr;
}

HSV color model

HSV is a model calculated by the hue, saturation, and value color coordinate system in which the color space is represented by a single cone.
  • When the saturation is 100, the color is fully saturated.
  • When the saturation is 0, the color is a pure gray shade of the value specified.
  • When the value is 100 and any saturation is specified, a color tint is produced.
  • When the value is less than 100 and a saturation is specified, a shade is produced.
  • When the value is 0, the color is black.
The following code example shows a function that creates an HSV-based color in ArcObjects:
[VB.NET] 
Public Shared Function MakeHSVColor(ByVal H As Byte, ByVal S As Byte, ByVal V As Byte) As ESRI.ArcGIS.Display.IHsvColor
Dim HsvClr As ESRI.ArcGIS.Display.HsvColor = New ESRI.ArcGIS.Display.HsvColorClass
With HsvClr
    .Hue = H
    .Saturation = S
    .Value = V
End With
Return HsvClr
End Function
[C#] 
public static ESRI.ArcGIS.Display.IHsvColor MakeHSVColor(byte H, byte S, byte V)
{
    ESRI.ArcGIS.Display.HsvColor HsvClr = new ESRI.ArcGIS.Display.HsvColorClass();
    HsvClr.Hue = H;
    HsvClr.Saturation = S;
    HsvClr.Value = V;
    return HsvClr;
}

HLS color model

HLS is a model calculated by the hue, lightness, and saturation color coordinate system in which the color space is represented by a double-ended cone.
  • When lightness is 0, the color is black.
  • When lightness is 100, the color is white.
  • When lightness is greater than 50, a color tint is produced.
  • When lightness is less than 50, a color shade is produced.
  • When saturation is 100, the color is fully saturated. 
  • When saturation is 0, the color is a pure gray shade of the specified lightness.
The following code example shows a function that creates an HLS-based color in ArcObjects:
[VB.NET] 
Public Shared Function MakeHLSColor(ByVal H As Byte, ByVal L As Byte, ByVal S As Byte) As ESRI.ArcGIS.Display.IHlsColor
Dim HlsClr As ESRI.ArcGIS.Display.HlsColor = New ESRI.ArcGIS.Display.HlsColorClass
With HlsClr
    .Hue = H
    .Lightness = L
    .Saturation = S
End With
Return HlsClr
End Function
[C#] 
public static ESRI.ArcGIS.Display.IHlsColor MakeHLSColor(byte H, byte L, byte S)
{
    ESRI.ArcGIS.Display.HlsColor HlsClr = new ESRI.ArcGIS.Display.HlsColorClass();
    HlsClr.Hue = H;
    HlsClr.Lightness = L;
    HlsClr.Saturation = S;
    return HlsClr;
}

Color ramps

The objects supporting the IColorRamp interface offer a simple way to define a series of colors for use elsewhere in ArcObjects. For example, you can set a color ramp directly onto the ColorRamp property of the IGradientFillSymbol interface of a FillSymbol, or you can create a color ramp to define the colors used in a ClassBreaksRenderer.
The individual ColorRamp objects offer different ways of defining the criteria that determine which colors comprise the ColorRamp. Random colors can be created using the RandomColorRamp, and sequential colors can be created using the AlgorithmicColorRamp. The PresetColorRamp Class contains 13 colors, allowing the creation of ramps mimicking ArcView GIS 3.x color ramps. In addition, the MultiPartColorRamp allows you to create a single color ramp that concatenates other color ramps, providing unlimited color ramp capabilities.
ColorRamps are used in the following ways in ArcObjects:
  • By accessing the individual colors in a ramp
  • By using the ramp object directly as a property or in a method of another object
First, a color ramp can be set up and its individual colors accessed. For example, when a UniqueValueRenderer is created, each symbol in its symbol array should be set individually, perhaps using colors from a color ramp. See the following steps:
  1. To retrieve individual colors from a color ramp, set the Size property according to the number of Color objects you want to retrieve from the ramp.
  2. Call the CreateRamp method, which populates the Color and the Colors properties. The Color property holds a read-only, zero-based array of Color objects, returned by index.
The following code example shows the creation of a RandomColorRamp and the generation of 10 color objects from that ramp. The Boolean parameter used in the CreateRamp method is checked after the method is called to ensure the colors were generated correctly.
[VB.NET] 
Dim colorRamp As IRandomColorRamp = New RandomColorRampClass()
colorRamp.Size = 10
Dim bOK As Boolean
colorRamp.CreateRamp( bOK)
If (bOK) Then
    ' Access the Color array here, for example, set colors
    ' for an array of symbols, or map layers, and so on.
    For i As Integer = 0 To colorRamp.Size - 1 Step i + 1
    Next
End If
[C#] 
IRandomColorRamp colorRamp = new RandomColorRampClass();
colorRamp.Size = 10;
bool bOK;
colorRamp.CreateRamp(out bOK);
if ((bOK))
{
    // Access the Color array here, for example, set colors
    // for an array of symbols, or map layers, and so on.
    for (int i = 0; i <= colorRamp.Size - 1; i++){}
}
The Colors property returns an enumeration of colors and is useful as a lightweight object to pass between procedures.
Second, a color ramp object can be used directly, for example, the ColorRamp property of the IGradientFillSymbol can be set to a specific color ramp object. The MultiPartColorRamp also uses color ramp objects directly by passing the object as a parameter in the AddRamp method.
The following code example shows a GradientFillSymbol object being created with an AlgorithmicColorRamp as its fill. The IntervalCount is set, which decides the amount of colors in the gradient fill.
[VB.NET] 
Dim algoRamp As IAlgorithmicColorRamp = New AlgorithmicColorRampClass()
algoRamp.FromColor = myFromColorObject
algoRamp.ToColor = myToColorObject
Dim gradFill As IGradientFillSymbol = New GradientFillSymbolClass()
gradFill.ColorRamp = TryCast(algoRamp, IGradientFillSymbol)
gradFill.IntervalCount = 5
[C#] 
IAlgorithmicColorRamp algoRamp = new AlgorithmicColorRampClass();
algoRamp.FromColor = myFromColorObject;
algoRamp.ToColor = myToColorObject;
IGradientFillSymbol gradFill = new GradientFillSymbolClass();
gradFill.ColorRamp = (IGradientFillSymbol)algoRamp;
gradFill.IntervalCount = 5;
If the ramp is used directly, as previously shown, it is not necessary to set the Size property or to call the CreateRamp method. In these cases, the parent object uses the information contained in the color ramp object to generate the number of colors it requires. The Size property is ignored. The name property stores a string, which you can use to keep track of your color ramps. ArcObjects does not use it internally.


See Also:

How to make a character marker symbol
How to make a gradient fill symbol
How to make a line callout
How to make a line fill symbol
How to make a picture marker symbol
Creating custom symbols
Creating other kinds of custom symbols
How to make a cartographic line symbol
Working with symbols and colors



Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine