1. Caching
    1. Seeding the Cache
    2. Types of Caches
      1. TMS (default)
      2. Sqlite3
      3. Tile Cache

Caching

osgEarth can cache tiles in order to increase performance. One an image or heightfield has been created once, it is generally much faster to access a local cache for that tile rather than create the tile or download it from the web again.

All layers in the map share a single cache object defined at the map level.

There are multiple types of caches that can be used in osgEarth, but all caches are specified with the following format: 

 <cache type="cache_type">
   <property1>value</property2>
   <property2>value</property2>
   ...
 </cache>

The type parameters tells osgEarth which type of cache to create. All properties and their corresponding values will be passed to the cache to configure it.

General Notes

  • All disk based caches use the image and heightfield name to create the folder to cache to. Please make sure that your layer names are unique per each cache path.
  • osgEarth uses OpenSceneGraph?'s existing plugins to read and write data. Make sure that the format you specify for the caches has good support for reading and writing. For example, the tiff plugin in OpenSceneGraph? 2.6.1 has a problem writing 16 and 32 bit datasets, so it is inappropriate to use when caching heightfields. The DDS plugin does support writing both 16 and 32 bit datasets to disk. The tiff plugin is the recommended plugin to use for OSG 2.8 and above.
  • It is possible to run osgEarth completely off of a cache by setting the OSGEARTH_CACHE_ONLY environment variable or using the <cache_only> attribute.
  • It is possible to override the cache format and disable caching for a particular layer by using the <cache_enabled> and <cache_format> elements

Seeding the Cache

Sometimes it is useful to pre-seed your cache for a particular area of interest. osgEarth provides a utility application, osgearth_seed to accomplish this task. osgearth_seed will take an Earth file and populate your cache.

osgearth_seed Usage 

Command:

       osgearth_seed [options] filename

Options:
       --bounds minx miny maxx, maxy         The geospatial extents to seed.
       --min-level level                     The minimum level to seed down to.
       --max-level level                     The maximum level to seed down to.
       -b                                    Shorthand for --bounds.
       --cache-path                          Use a different cache path than the one defined in the earth file
       --cache-type                          Override the cache type if you override the cache path (tms or disk).

Types of Caches

TMS (default)

If the cache type is tms then osgEarth caches files to disk using a format compatible with the  TMS specification.

The tms style cache has the following properties:

  • path - The path on disk to cache tiles to
  • format - The format to cache to (png, jpg, dds, etc). If no format is specified, the preferred format of the image or heightfield source will be used. If there is no preferred format for the source, the default will be png.
  • tms_type - If the value of tms_type is google then the y tile index will be inverted so that 0,0 is the top left tile rather than the bottom left tile. 
<map name="My Map" type="geocentric">

  <!--Specify a map level "tms" cache for all images and heightfields--> 
  <cache type="tms">
     <path>c:/osgearth_cache</path>
  </cache>

  <image name="bluemarble" driver="tms">
     <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/</url>       
  </image>

  <image name="inset" driver="gdal">
     <url>c:/data/inset.tiff</url>
  </image> 

</map>

Sqlite3

Set the cache type to sqlite3 to store your cache in a  sqlite database file. This is nice because the entire cache is in a single file, making it easy to transport if necessary.

The sqlite3 cache has the following properties:

  • path - path to the database file.

Example: 

<map type="globe">

  <cache type="sqlite3">
     <path>c:/osgearth_cache.db</path>
     <max_size>300</max_size> <!-- MB -->
  </cache>

  <image name="bluemarble" driver="tms">
     <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/</url>       
  </image>

Tile Cache

If the cache type is tilecache then osgEarth caches files to disk using a format that is compatible with Metacarta's  TileCache "Disk" style caching. This means that the resulting osgEarth cache can be used by any client that can consume publicly accessible TileCache? disk caches such as  OpenLayers or osgEarth. This is very useful because as you are browsing and caching tiles, you are actually creating a map that can be browsed by other clients. If no cache type is specified, then a TileCache? style cache will be used.

The tilecache style cache has the following properties:

  • path - The path on disk to cache tiles to
  • format - The format to cache to (png, jpg, dds, etc). If no format is specified, the preferred format of the image or heightfield source will be used. If there is no preferred format for the source, the default will be png. 
<map name="My Map" type="geocentric">
  <!--Specify a map level "tilecache" cache for all images and heightfields--> 
  <cache type="tilecache">
    <!--All tiles will be cached to c:/osgearth_cache-->
    <path>c:/osgearth_cache</path>
    <!--All tiles will be cached to png format.  If we did not specify the format, tiles would be cached to the preferred format of the tile source-->
    <format>png</format>
  </cache>

  <image name="TMS" driver="tms">
    <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite/</url>       
  </image>

  <image name="inset" driver="gdal">
     <url>c:/data/inset.tiff</url>
   </image> 

</map>

Back to Documentation