Upgrading from an older version of osgEarth

Here are some tips for upgrading from an older version to a newer version.

---

From 2.1 to 2.2

Caching

Caching is completely reworked for 2.2.

The old "tms-style" cache is gone. Any existing cache folder you have are no longer valid.

The new disk-based cache is called "filesystem". It's use is similar to the old TMS cache:

   <cache type="filesystem">
       <path>path_to_cache_folder</path>
   </cache>

You can also set up a filesystem cache with an environment variable:

    set OSGEARTH_CACHE_PATH=absolute_path_to_cache_folder

Other useful environment variables control the default cache policy:

• OSGEARTH_CACHE_ONLY : Set this to ONLY read data from the cache, and never the source.
• OSGEARTH_NO_CACHE : Set this to ONLY read from the source, and never from the cache.

Finally, there is a new cache_policy tag in the earth file:

    <cache_policy usage="cache_only"/>

You can use this at the map options level or at the layer level.

Annotation

There's a new osgEarthAnnotation library. Everything from 2.1's osgEarth::Util::Annotation namespace is now here.

The osgEarth::Util::Viewpoint class has relocated to osgEarth core.

PlaceNode replaces the old PlacemarkNode.

There's a new decluttering engine for annotation objects. It prevents on-screen overlap of LabelNode's and PlaceNode's. You can activate it simply by setting the nodes' render bin like so:

    node->getOrCreateStateSet()->setRenderBinDetails(binNumber, OSGEARTH_DECLUTTER_BIN);

You can set binNumber to INT_MAX or another value of your choosing. See the osgearth_annotation program for an example.

Scripting

There is a new JavaScript scripting engine in 2.2 that you can use in a StyleSheet. In addition to using the built-in expression evaluator, you can call custom JavaScript methods in your earth file.

Here's a quick example.

    ...
    <styles>
        <script language="javascript">
            function getHeight()
            {
                return 3.5 * Math.max(feature.attributes["stories"], 1);
            }
        </script>
 
        <style type="text/css">
            buildings {
                extrusion-height: getHeight();
            }
        </style>
    </styles>
    ...

To use scripting, you have to compile in the otherwise-optional Google V8 library.

Also note: the expression classes (NumericExpression and StringExpression) both natively support scripts.

Miscellany

The Config class underwent come changes:

• There are no more "attributes" in Config. We removed them to simplify the implementation.
• You can now easily serialize a Config object to JSON and back.

The URI object:

• Most I/O happens through the URI object. Use this to load data from a path or URL. It automatically takes care of caching and cache policies.
• The HTTPClient object will no longer load data from local files; it is HTTP only (as it should be).
• URI and Config take care of relative path resolution now. The user of reference URIs is deprecated and in most cases removed.

---

From 1.4 to 2.0

Classes that were removed or renamed:

EarthFile	Used to do .earth file serialization; the same functionality is now in the .earth plugin (by way of osgDB::readNodeFile/writeNodeFile).
MapEngineProperties	We replaced this with two classes: MapOptions (for Map config) and MapNodeOptions (for MapNode config).
MapLayer	This class used to represent both image and elevation layers. We replaced it with ImageLayer and ElevationLayer respectively.
FadeLayerNode	No longer needed, just can just omit it from your scene graph. The functionality it provided is now automatically supported. For layer opacity, just call ImageLayer::setOpacity now. For range-based fading, you can use the new min_range and max_range properties (see <image>).

Header files that are obsolete; you can can simply remove them from your source:

• osgEarth/EarthFile
• osgEarthUtil/FadeLayerNode

Methods:

• Map::addMapLayer: replace with addImageLayer or addElevationLayer as appropriate.
• LoadingPolicy::numThreadsPerCore: replace with numLoadingThreads or numLoadingThreadsPerCore.
• LoadingPolicy::numTileGeneratorThreads: replace with numCompileThreads or numCompileThreadsPerCore.

Example:

You used to set terrain options like this:

  Config conf;
  conf.add("min_tile_range_factor", "6.0");
  MapEngineProperties props;
  props.fromConfig(conf);
  m_pMapNode = new MapNode(earthMap, props); 

The equivalent with 2.0 is:

  TerrainOptions t_opt;
  t_opt.minTileRangeFactor() = 6.0;
  MapNodeOptions mn_opt(t_opt);
  m_pMapNode = new MapNode(earthMap, mn_opt);

(Note that the direct usage of Config objects is deprecated.)