ColorRampLegendItem Class
Represents a color ramp in a legend.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class ColorRampLegendItem : LegendItemRemarks
This class is used to explain a color ramp in a Legend.
 |
There are two common methods to generate a color ramp in a map:
a RasterVisualizer that visualizes a raster with numeric cell values (this would be used in an area-class map), or
a PolygonVisualizer that fills polygons with different colors depending on a numeric attribute (this would be used in an choropleth map).
Both of these methods can be handled by a ColorRampLegendItem: you just attach the RasterVisualizer or the PolygonVisualizer to its list of visualizers. The resulting image will then contain the color ramp, with numeric labels to the left.
For example, if the color ramp appears like this in Carmenta Studio:
 |
Then the generated legend item will look something like this:
 |
Image size
The Description in this example is just "Elevations (m)", while the image contains both the color ramp and the numeric labels. If the specified width and height for the image (either from Legend.ItemWidth and Legend.ItemHeight or from the legend item Width and Height) are too small to be useful, they will be ignored, and the resulting image will be high enough to contain all the labels, and wide enough to contain the labels and a ramp that is eight pixels wide.
Outline, background and borders
The OutlineColor and BackgroundColor are not applied to the entire image (as they are for other legend items), but only to the color ramp. So a black outline color would appear like this:
 |
If the color ramp in this example had come from a PolygonVisualizer instead, the image would have been created from a set of polygons instead of from a raster. The image would appear the same, but you would get an additional option: instead of using the OutlineColor of the legend item, you could have added a LineVisualizer to the list of visualizers. This should be the same line visualizer as you use for the polygon boundaries of the map. The resulting image would be something like this:
 |
The line visualizer creates lines also between the colors of the ramp, which you cannot get from the OutlineColor.
Labels
Note that in the example above, there was no label 5000 generated at the top of the ramp. This is because the example color table will cause the visualizer to use the light-gray color for any value greater than 4000, so there is really no sharp limit at 5000, and the unlabeled upper edge suggests a vague (or infinite) upper limit. However, if you would append a final entry to the color table, with the value 5000 and a fully transparent color like [0,0,0,0], then there will be a sharp limit at 5000 - since greater values will now appear transparent in the map - and you will get the label 5000 at the top of the ramp.
Note also that there is no label -500 at the bottom of the ramp. The reason is similar: the visualizer will use the dark-green color for any value less than -500 as well (that is the semantics of the first entry in a color table), so there is no sharp limit at -500. You can make such a label appear, if you prepend a new first entry to the color table, with a value less than -500 and a fully transparent color.
You can change the appearance of the numeric labels via LabelFont and LabelColor. The spacing between the labels is unspecified by default, but you will usually get one label for each color change. However, if there are many colors (more than 20), then the default mechanism will generate only two or three labels. In such cases, you may prefer to specify the LabelStep explicitly.
 |
Range of values
This legend item can automatically decide its range of displayed values, but you can override its choice via the properties BottomValue and TopValue. Note that these properties control the range of the displayed color ramp, not the range of the numeric labels, so you will not always get a numeric label for the TopValue and BottomValue.
Explicit values for TopValue and BottomValue can be used to display only a specific subinterval of the numeric range of values (although this is seldom what you want). Or, the top and bottom values that are automatically generated from the color ramp can be misleading, since they can be too large or too small compared to the possible extent of the numeric values. For example, you may know that ground elevations on Earth varies between -422 m and 8848 m, so it makes sense to use these heights as explicit BottomValue and TopValue.
If you use an explicit BottomValue or TopValue just to tweak the legend appearance slightly, then you get a maintenance problem: If the range of the color ramp is extended afterwards, you may forget to adjust the BottomValue or TopValue accordingly, so that the displayed range is unchanged.
Numbers growing downward
To get a color ramp whose numbers grow downward, let TopValue be less than BottomValue. This can be useful to show sea depths, if the depths are expressed as positive numbers. If you want to keep the automatic generation of the numeric range, you can just reverse the signs of the default values (that is, let TopValue be -1.7e308 and let BottomValue be 1.7e308).
 |
Blending a color ramp with gray
A special problem occurs when the map colors come from two visualizers that are blended. For example, a map configuration can have one layer with a color ramp for elevations, and another layer with gray-shaded relief (from ShadeOperator), where the grayscale is semi-transparent and drawn on top of the colored elevations. The semi-transparent shading will enhance the relief look, but the colors will be duller. Now, if the ColorRampLegendItem refers only to the raster visualizer for the color ramp, the legend item will get too bright colors, compared to the map:
 |
To make the legend colors more similar to the map colors, we need to add some grayness. The simplest way is to add another RasterVisualizer to the legend item, one with a single semi-transparent gray color, for example the color [180,180,180,75]:
 |
If the two layers had been drawn in the opposite order - a semi-transparent color map drawn on top of a gray-shaded relief - then a simpler solution would be to just use a gray BackgroundColor.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
LegendItem
ColorRampLegendItem
Platforms
Windows, Linux, Android
ColorRampLegendItem Members
The ColorRampLegendItem type has the following members.
Constructors
| Name | Description |
|---|---|
| ColorRampLegendItem | Initializes a new instance of the ColorRampLegendItem class. |
Properties
| Name | Description |
|---|---|
| Attributes | Gets the set of attributes for the feature of this ColorRampLegendItem. Inherited from LegendItem |
| BackgroundColor | Gets or sets a color used as background for the image. Inherited from LegendItem |
| BottomValue | Gets or sets the bottommost value in the color ramp. |
| Description | Gets or sets the description. Inherited from LegendItem |
| Height | Gets or sets the image height in pixels. Inherited from LegendItem |
| IsDisposed | Gets a value that tells whether the current ColorRampLegendItem has been disposed. Inherited from EngineObject |
| LabelColor | Gets or sets the color of the numeric labels. |
| LabelFont | Gets or sets the font for the numeric labels. |
| LabelStep | Gets or sets the spacing between the numeric labels. |
| Name | Gets or sets the name of the ColorRampLegendItem. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current ColorRampLegendItem represents. Inherited from EngineObject |
| OutlineColor | Gets or sets a color used for a rectangular outline for the image. Inherited from LegendItem |
| TopValue | Gets or sets the topmost value in the color ramp. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| Visualizers | Gets the list of visualizers used to generate the image. Inherited from LegendItem |
| Width | Gets or sets the image width in pixels. Inherited from LegendItem |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| GetImage | Overloaded. Saves the image to a memory buffer in PNG format. Inherited from LegendItem |
| GetLocalizedDescription | Gets a localized version of the legend item description in a specific language. Inherited from LegendItem |
| HasLocalizedDescription | Checks if a localized version of the legend item description is available in a specific language. Inherited from LegendItem |
| SetLocalizedDescription | Sets the legend item description in a specific language. Inherited from LegendItem |