Themes

Themes are used to describe the visual appearance of geometries. These are TypeScript or JSON files describing a set of styles for geometries. There are different types of geometries and corresponding styles which can customize the appearance of these geometries.

To understand the basic principles of styling geometries, let us take a look at a simple theme used by the SpeedLimitsDataSource sample. It is located in the src/datasources/speedLimitsDataSource/theme/speedLimitTheme.ts file of the @here/olp-examples package.

This file exports a SpeedLimitTheme object with a string name of theme and styles array. It defines styles for lines of different color and one style for an invisible line.

Each style object must have two string properties - when and technique, some optional properties, and a set of additional properties in attr which are specific to each style.

• when: An expression describing when this style should be applied. This expression is used by StyleSetEvaluator to retrieve the required technique. You can examine the SpeedLimitsTile.createSpeedLimitsMaterial method for an example of its usage.
• technique: A property specifying the style's geometry type and must be one of "line", "fill", "solid-line", "dashed-line", "extruded-line", "extruded-polygon", "text", "landmark", "line", "segments", or "none".
• attr: Attributes that are specific for each technique and describe the visual appearance of a geometry.
• description: Optional, a human readable description.
• renderOrder: Optional, a geometry's render order.
• transparent: Optional, set to true if a line should appear transparent. Rendering transparent lines may come with a slight performance impact.
• opacity: Optional, for transparent lines, set a value between 0.0 for fully transparent and to 1.0 for fully opaque.

First, let us examine the styles of solid lines used to visualize speed limits. There are three of them so common attributes are placed in the lineAttributes object which is reused for all the lines.

Solid lines have styles with the solid-line technique and represent a solid line geometry. Its appearance can be customized by specifying the following attributes:

• lineWidth: Line width in meters. It is an array of widths for different zoom levels that can have a single element with only value in it if there is no need to apply different widths on different zoom levels, or can have multiple elements with minLevel, maxLevel, and value to specify zoom level ranges with certain line widths.
• color: Line color in hexadecimal or CSS-style notation, for example: "#e4e9ec", "#fff", "rgb(255, 0, 0)", or "hsl(35, 11%, 88%)".
• clipping: If set to true or omitted, a line will be clipped by tile bounds. If set to false, the line will be rendered even outside of the tile.

There is a special style with the segments technique. This technique is used to create line geometries of one-pixel width, however, in this case, it has an attribute visible set to false. This is done to improve performance. This style is applied to invisible lines which are used only for detecting intersections of the mouse pointer with geometries. It is preferable to use visible: false instead of opacity: 0 because rendering will not perform actual draw calls for geometry with visible set to false, thus improving performance.

The speed limits theme:

// Common styles for speed limit line.
const lineAttributes = {
    lineWidth: 4,
    metricUnit: "Pixel",
    clipping: false // Line will not be clipped by tile bounds
};

/** Theme for visualization of speed limits geometries. */
export const SpeedLimitTheme = {
    name: "speedlimits", // Theme name.
    styles: [
        {
            description: "Style for visualizing low speed limits.",
            when: "type == 'speedlimit-line-low'",
            technique: "solid-line",
            renderOrder: 1010,
            attr: { color: "rgb(191,33,47)", ...lineAttributes }
        },
        {
            description: "Style for visualizing medium speed limits.",
            when: "type == 'speedlimit-line-medium'",
            technique: "solid-line",
            renderOrder: 1009,
            attr: { color: "rgb(249,167,62)", ...lineAttributes }
        },
        {
            description: "Style for visualizing high speed limits.",
            when: "type == 'speedlimit-line-high'",
            technique: "solid-line",
            renderOrder: 1008,
            attr: { color: "rgb(39,179,118)", ...lineAttributes }
        }
    ]
};

There are other techniques used to visualize various types of geometries, you can find them in Technique API.