Custom Palettes and Themes

Manifold has two systems to allow specification of custom formatting characteristics such as color in thematic formatting. One system, using custom palettes, is a legacy system that can be used to specify only colors. The more general method is to use custom themes, which can specify many different formatting characteristics such as rotation angles, color, and the size and style of labels, areas, lines or points.

Because custom palettes may not be supported at some time in the future, users should take care to employ only custom themes. The information in this topic on custom palettes is provided for backward compatibility with earlier versions of Manifold.

Note: in this topic, the word "theme" is used to mean a collection of formatting characteristics used with values for thematic formatting. It is a different use of the same word that is also used to mean a theme component.

In both cases, either custom palettes or themes used for thematic formatting of drawings and surfaces or terrains are loaded from .xml files found in the Config folder. Specifications for custom palettes or themes are enclosed within <palette> … </palette> tags for a custom palette or <theme> … </theme> tags to specify a custom theme.

If an .xml file specifying a custom theme occurs in the Config folder Manifold will automatically load it upon startup. If the .xml file specifying the custom theme neglects to provide a name for the theme, Manifold will name the theme Custom X, where X is a number that makes the name unique, for example, Custom 1, Custom 2 and so on.

Custom Palettes

Manifold palettes come in two forms: relative palettes in which colors only are specified, and fixed palettes that also specify values for the intervals to which colors apply. In relative palettes, only a list of colors need be specified. In fixed palettes, a list of colors as well as a corresponding list of values must be specified.

Users can add their own palettes (including those with fixed values) by creating .xml files in the following patterns:

For relative palettes:

<xml>

<name>My Relative Palette</name>

<color>#ffffff</color>

</colors>

</palette>

</xml>

For fixed palettes:

<xml>

<name>My Fixed Palette</name>

<color>#ffffff</color>

</colors>

</values>

</palette>

</xml>

Either fixed or relative palettes may also use decimal numbers to specify RGB color values as well as hex numbers:

<xml>

<name>Sample palette</name>

</colors>

</palette>

</xml>

The example above decimal numbers with the last color specified using hexadecimal. Decimal and hexadecimal color specifications may be used within the same palette.

Rules for Palettes

· There can be any number of <palette> … </palette> entries within a single XML file between the <xml> tag at the beginning of the file and the </xml> tag at the end of the file.

· The name string in the <name> attribute is mandatory and must be unique.

· Values of colors are specified in the <color> attribute in either hexadecimal form or decimal form.

· Hexadecimal colors are in "#rrggbb" form where rr, gg and bb are pairs of hexadecimal digits giving a hexadecimal number corresponding to the decimal number range from 0 to 255 for Red (rr), Green (gg) or Blue (bb). Leading zeros are significant, so that RGB values of 3, 5 and 6 are coded as 030506 in hexadecimal numbers. The examples above show a list of colors that are black, pure red, pure green, pure blue and white.

· Decimal colors may be in two forms: either r:g:b form where r, g and b are decimal integer numbers in the range from 0 to 255 or as a single decimal number that is the decimal equivalent of a #rrggbb hexadecimal number.

· There must be at least two colors listed in a palette.

· Fixed palettes must also include a list of values in the <values> attributes.

· Values in the <value> attributes are floating-point numbers. Negative numbers are prefixed with a - minus sign.

· Values must be listed in ascending order from lowest to highest value. Each value must be unique within the list for that palette. The number of values must be exactly the same as the number of colors in that palette.

Custom Themes

Users can add their own themes by creating .xml files in the following pattern:

<xml>

<theme>

<type>color</type>

<color>#cccccc</color>

<color>#ffffff</color>

</colors>

<colorMax>#ffffff</colorMax>

</values>

</theme>

</xml>

Themes use a more modern nomenclature than do palettes. Instead of referring to a "relative" or "fixed" palette, themes are called interval based (equivalent to relative palettes) or value based (equivalent to fixed palettes).

Rules

· The <theme> tag surrounds the definition of the theme. There can be any number of <theme> … </theme> entries within a single XML file between the <xml> tag at the beginning of the file and the </xml> tag at the end of the file.

· The <type> tag contains the type of the theme and can be equal to any of the following values: angle, color, areaSize, areaStyle, labelSize, labelStyle, lineSize, lineStyle, pointSize, or pointStyle.

· The <interval> tag determines whether the theme is interval-based (true) or value-based (false). Interval-based themes assign formatting to data falling within the specific intervals, and value-based themes assign formatting to data equal to specific values.

· The <values> and <value> tags contain interval breaks or unique values depending on whether the theme is interval-based or value-based. The theme must contain at least one value.

· Tags specifying specific characteristics consist of a tag using the plural name of the given type followed by singular name tags for each specific case. The <colors> and <color> tags contain formatting data for colors as seen in the prototype XML above. A theme for for line styles would use <lineStyles> and <lineStyle> tags, a theme for point styles would use <pointStyles> and <pointStyle> tags and so on. The number of <color> tags (or other singular tags) and <value> tags must be the same.

· The <colorMin> and <colorMax> tags are used with interval-based themes to format color and contain formatting data for values that are less than the lowest break, or greater than the highest break. An interval-based theme used to format line styles would use <lineStyleMin> and <lineStyleMax> tags and so on.

· The <colorDef> tag is used with value-based themes and contains formatting data to use for values that are different from any of defined unique values. A theme for line styles would use the <lineStyleDef> tag and so on.

· Values of colors are specified in the <color> attribute in either hexadecimal form or decimal form.

· There must be at least two colors listed in a theme.

· Fixed themes must also include a list of values in the <values> attributes.

· Values in the <value> attributes are floating-point numbers. Negative numbers are prefixed with a - minus sign.

· Values must be listed in ascending order from lowest to highest value. Each value must be unique within the list for that theme. The number of values must be exactly the same as the number of colors in that theme.

Theme Examples

To create an example of a theme, use the Thematic Formatting dialog to create a format and then press the Save to File button to save it as an .xml file. Open the .xml file with Notepad to see how the .xml implements the above rules.

Using Palettes or Themes

To utilize newly created or modified palettes or themes place the new or modified .xml file containing the palettes into the Config folder for Manifold (normally C:\Program Files\Manifold System\Config) and restart Manifold. To quickly check what palettes are currently available, see the Tools - Options, Color Palettes dialog.

When Manifold launches, the system will scan all .xml files in the Config folder. Any <palette> or <theme> entries found in any of those .xml files will be loaded into the system as available palettes.

Color Specification in Hex or Decimal

Most classic graphics programming is done specifying colors using hex numbers in the #rrggbb pattern. However, most Windows programs used in graphics editing report RGB colors using triplets of decimal numbers. Manifold can accept both numeric representation styles.

The hex specifications:

…define exactly the same colors as the decimal specifications:

The third style, of reporting concatenated hex values (#rrggbb) as their equivalent decimal number value is rarely used except as a shorthand way of specifying black color. The following pairs of values are equivalent:

<color>#ffffff</color>

Example

We've created a file in the Config folder called mypalettes.xml that contains:

<xml>

<name>Atlas Colors in Meters</name>

<color>#bfdbe3</color>

<color>#ffffff</color>

</colors>

</values>

</palette>

<name>Atlas Colors in Feet</name>

<color>#bfdbe3</color>

<color>#ffffff</color>

</colors>

</values>

</palette>

<name>Atlas Colors</name>

<color>#bfdbe3</color>

<color>#ffffff</color>

</colors>

</palette>

</xml>

When Manifold launches it will see the mypalettes.xml file in the Config folder and will read it to see what it contains. It will find three palettes in the file and will load them for use. Two of the palettes are fixed palettes while the third file is a relative palette. Note that negative numbers may be used as values for fixed palettes.

All three palettes use the same colors. The two fixed palettes have different values, which we can see upon examination are the same numbers that would be used for elevations either in feet or in meters. This is a fairly typical arrangement when creating a new palette intended for use with surfaces. Surfaces usually originate in either meter-based data sets, where the elevation values are given in meters, or in foot-based elevation values such as US SDTS DEMs where the elevations are in feet. It is convenient to have the same fixed palette available with both meter-based as well as foot-based palettes so that the color scheme can be used for the same elevation above or below sea level regardless of whether the numbers in the surface represent meters or feet.

It is also convenient to have a version of a fixed palette available as a relative palette. This is allows a quick look at how the full range of palette colors appears in use. We can use whatever data set we want and even if it only ranges between -100 and 1000 we will still see the full set of colors.

Tech Tip

Manifold cannot use any customizations if the .xml files do not contain XML that is exactly correct. A useful test before launching Manifold is to open any newly created or modified .xml file in Internet Explorer. Internet Explorer will show a correct .xml file in a simple text format. If Internet Explorer cannot parse the .xml file, Manifold won't be able to either.