Feature Symbology
osgEarth can read vector feature data and display it on the map. Exactly how it displays that data is up to you - and this page explains how to control that.
The basic unit of vector data is the Feature. A Feature consists of geometry (one or more shapes) and an associated list of attributes (name/value pairs). osgEarth's symbology system lets you use the geometry and the attributes in various ways in order to control exactly how the features will look in your scene.
osgEarth provides a set of symbols that you use to define the rendering. The symbology exists separately from the content; thus, symbology can be re-usable and applied to different feature data sets. These symbols, taken together, form styles and these styles are applied to feature data by the geometry engine. A collection of styles is called a stylesheet. If all this sounds familiar, that's because the concept draws directly from the work of web design, where HTML rendering it controlled by CSS styles.
Styles
In a .earth file, you may see a <styles> block that looks like this:
<styles>
<style type="text/css">
buildings {
altitude-clamping: terrain;
extrusion-height: 15;
extrusion-flatten: true;
fill: #ff7f2f;
}
</style>
</styles>
That is a stylesheet block. You will find this inside a <model> layer that is rendering feature data, paired with a <features> block. (The <features> block defines the source of the actual content.)
In this case, the <style> element holds CSS-formatted data. A CSS style block can hold multiple styles, each of which has a name. In this case we only have one style: "buildings". This style tells the geometry engine to do the following:
- Clamp the feature geometry to the terrain elevation data;
- Extrude shapes to a height of 15m above the terrain;
- Flatten the top of the extruded shape; and
- Color the shape orange.
By the way, this example comes from the "feature_extrude.earth" sample found in the repo's "tests" folder. Give it a try.
Symbols
Now we will go over all the available symbols. Each one has a corresponding class in the osgEarth::Symbology API. Here we'll describe the symbols in terms of their CSS properties.
Note that some of the properties are documented as being "expressions". That means you can express the value in terms of simple inline calculations and feature attribute values. More on that later.
Point Symbol
The Point Symbol tells osgEarth to render the geometry as a set of graphical points, and describes how they should look.
mystyle {
point-size: 3; - render points with a GL size of 3 pixels
fill: #ff0000; - color the points red
}
Line Symbol
The Line Symbol tells osgEarth to render the geometry as graphical lines.
mystyle {
stroke: #ffff00; - render yellow lines
stroke-opacity: 0.5; - half transparent (you could also say stroke: #ffff007f)
stroke-width: 2; - lines should be 2 pixels wide
}
Polygon Symbol
The Polygon Symbol tells osgEarth to render the geometry as filled graphical polygons.
mystyle {
fill: #00ff00; - render green filled polys
fill-opacity: 1.0; - fully opaque
}
Altitude Symbol
The Altitude Symbol controls how the geometry interacts with the map's terrain elevation. Here are some examples.
mystyle {
altitude-clamping: terrain; - set the Z coordinate of each geometry point to that of the terrain (see below)
altitude-offset: 10; - add this value to the Z coordinate of the geometry (expression)
altitude-scale: 2; - scale the Z coordinate by this value (expression)
}
Options for "altitude-clamping" are:
- terrain - Clamp the geometry to the terrain skin. osgEarth samples the elevation grid under each point and applies the height value to the feature. If the geometry already had Z values, they are overwritten by the terrain height values.
- relative - This clamps the geometry to the terrain, just like "terrain", but instead of discarding a pre-existing Z value in the geometry, it adds that value to the terrain height.
- absolute - Use this if you plan to use the Extrusion symbol, and your feature data has a height attribute that is expressed relative to MSL or to the ellipsoid. This tells the extruder that it need to extrude "down" from a roof height, rather than "up" from the terrain.
- none - The default value. Use this if you don't want any terrain clamping, but you still want to use "altitude-offset" or "altitude-scale".
Note: if you use both "altitude-scale" and "altitude-offset" together, the scale is applied first.
Extrusion Symbol
The Extrusion Symbol tells osgEarth to extrude geometry upwards, creating walls and (in the case of extruding polygons) a roof. For example, you can use this symbol to create 3D buildings out of 2D footprint features.
Example:
mystyle {
extrusion-height: [hgt]; - distance (in meters) to extrude the geometry upwards (expression)
extrusion-flatten: true; - whether to extrude all points to the same absolute height
extrusion-wall-style: wall; - name of another style in this stylesheet describing how to draw the extruded walls
extrusion-roof-style: roof; - name of another style in this stylesheet describing how to draw the roof polygon
}
Flattening: Some features, like buildings, typically have a flat roof even if you base geometry is not flat (e.g. on the side of a hill). Set extrusion-flatten to true to flatten to roof. Other features (e.g. a fence) may require the default, non-flattened top that follows the terrain's contours.
Marker Symbol
The Marker Symbol tells osgEarth that instead of drawing the actual geometry, it should use a marker in its place. A marker is a 3D model or an image/icon placed in the scene. For example, you may have a feature set of points, each of which represents the location of a tree. You could use a Marker symbol to tell osgEarth to place a 3D model of a tree at the location of each point.
This example places a tree model at each vertex in the feature geometry:
mystyle {
marker: "tree.ive"; - URI of the data to render in place of geometry (expression)
marker-placement: vertex; - rule describing how to place marker instances (see below)
marker-scale: 2; - scale factor to apply to each marker instance
}
This example randomly scatters tree models within the feature geometry. For example, say your feature set consists of city park boundaries. Use this to scatter trees in those parks:
marker: "tree.ive"; - URI of the data to render in place of geometry (expression)
marker-placement: random; - random scattering placement
marker-density: 100; - place 100 instances per square kilometer
marker-random-seed: 4; - seed value to affect deterministic scattering (0 = disable)
"marker" is the URI of the resource to use. It can be an image or a model.
"marker-placement" options are:
- vertex - place one instance at each point along the geometry
- random - randomly scatter instances within the geometry
- interval - place instances at regular gridded intervals within the geometry
Skin Symbol
The Skin Symbol controls texture mapping. A Skin in osgEarth is an image coupled with a set of parameters that describe its size and its suitability for use at a symbol. Skins, and how to define them, are described in more detail in the discussion on 'Resource Libraries'?.
The Skin Symbol can operate in two different ways. The first is by pointing directly at a skin to use:
house {
skin-library: mylib; - name of the resource library containing the skin
skin: "house42"; - name of the skin.
}
The second way to use the Skin Symbol is to provide "suitability" criteria. A resource library will hold a collection of skins; the Skin Symbol will then provide a set of parameters used to randomly select a suitable texture from the library:
office_buildings {
skin-library: mylib; - name of the resource library to load textures from
skin-tags: building commercial; - list of tag strings (space-separated) used to narrow down the skin selection
skin-tiled: false; - only consider non-tiled skins
skin-object-height: 42; - height of the object that will be skinned (see below)
skin-random-seed: 2; - seeds the PRNG to affect deterministic texture selection (optional; 0 = disable)
}
NOTE: When used with the Extrusion Symbol, the extruded height of the object is added to the Skin Symbol automatically - you do NOT need to specify the "skin-object-height" manually.
Text Symbol
The Text Symbol tells osgEarth to turn features into text labels.
mystyle{
text-content: [name]; - Actual text of the label (expression)
text-font: "arial.ttf"; - font name to use
text-size: 16; - font size
text-halo: #000000; - color of the halo around the text
text-remove-duplicate-labels: true; - don't label more than one feature with the same content
text-priority: [population]; - priority, for resolving screen-space conflicts (expression)
}
Expressions
Some symbol properties support expressions. An expression is a simple in-line calculation that uses feature attribute values to calculate a property dynamically.
In an expression, you access a feature attribute value by enclosing its name in square brackets, like this: [name]
Examples:
mystyle {
extrusion-height: [hgt]*0.3048; - read the "hgt" attribute, and convert it from feet to meters
altitude-offset: max([base_offset], 1); - use the greater of the "base_offset" attribute, and 1.0
text-content: "Name: [name]"; - sets the text label to the concatenation of a literal and an attribute value
}
The numeric expression evaluator supports basic arithmetic (+, -, *, / %), some utility functions (min, max), and grouping with parentheses.
It also works for string values. There are no operators, but you can still embed attributes.
FUTURE: Look for osgEarth to support custom scripting so you can go beyond the power of simple expressions.
