Tools

osgEarth comes with many tools that help you work with earth files and geospatial data.

osgearth_viewer

osgearth_viewer can load and display a map from and command line. The osgEarth EarthManipulator is used to control the camera and is optimized for viewing geospatial data.

Sample Usage

osgearth_viewer earthfile.earth [options]
Option Description
--sky Installs a SkyNode (sun, moon, stars and atmosphere..globe only)
--kml [file.kml] Loads a KML or KMZ file
--kmlui Displays a limited UI for toggling KML placemarks and folders
--coords Displays map coords under mouse
--dms Displays map coords as degrees/mins/seconds
--dd Displays map coords as decimal degrees
--mgrs Displays map coords as MGRS
--ortho Installs an orthographic camera projection
--images [path] Finds images in [path] and loads them as image layers
--image-extensions [*] With --images, only considers the listed extensions
--out-earth [out.earth] With --images, writes out an earth file
--logdepth Activates the logarithmic depth buffer in high-speed mode.
--logdepth2 Activates the logarithmic depth buffer in high-precision mode.
--uniform [name] [min] [max] Installs a uniform and displays an on-screen slider to control its value. Helpful for debugging.
--ico Activates OSG’s IncrementalCompileOperation, which will compile paged objects over a series of frames (reducing frame breaks). This is actually an OpenSceneGraph option, but useful for osgEarth

osgearth_version

osgearth_version displays the current version of osgEarth.

Argument Description
--caps Print out system capabilities
--major-number Print out major version number only
--minor-number Print out minor version number only
--patch-number Print out patch version number only
--so-number Print out shared object version number only
--version-number Print out version number only

osgearth_cache

osgearth_cache can be used to manage osgEarth’s cache. See Caching for more information on caching. The most common usage of osgearth_cache is to populate a cache in a non-interactive manner using the --seed argument.

Sample Usage

osgearth_cache --seed file.earth
Argument Description
--list Lists info about the cache in a .earth file
--seed Seeds the cache in a .earth file
--estimate Print out an estimation of the number of tiles, disk space and time it will take to perform this seed operation
--mp Use multiprocessing to process the tiles. Useful for GDAL sources as this avoids the global GDAL lock
--mt Use multithreading to process the tiles.
--concurrency The number of threads or processes to use if –mp or –mt are provided
--min-level level Lowest LOD level to seed (default=0)
--max-level level Highest LOD level to seed (default=highest available)
--bounds xmin ymin xmax ymax Geospatial bounding box to seed (in map coordinates; default=entire map
--index shapefile Loads a shapefile (.shp) and uses the feature extents to set the cache seeding bounding box(es). For each feature in the shapefile, adds a bounding box (similar to --bounds) to constrain the region you wish to cache.
--cache-path path Overrides the cache path in the .earth file
--cache-type type Overrides the cache type in the .earth file
--purge Purges a layer cache in a .earth file

osgearth_package

osgearth_package creates a redistributable TMS based package from an earth file.

Sample Usage

osgearth_package --tms file.earth --out package
Argument Description
--tms make a TMS repo
--out path root output folder of the TMS repo (required)
--bounds xmin ymin xmax ymax bounds to package (in map coordinates; default=entire map) You can provide multiple bounds
--max-level level max LOD level for tiles (all layers; default=5). Note: you can set this to a large number to get all available data (e.g., 99). This works fine for files (like a GeoTIFF). But some data sources do not report (or have) a maximum data level, so it’s better to specify a specific maximum.
--out-earth earthfile export an earth file referencing the new repo
--ext extension overrides the image file extension (e.g. jpg)
--overwrite overwrite existing tiles
--keep-empties writes out fully transparent image tiles (normally discarded)
--continue-single-color continues to subdivide single color tiles, subdivision typicall stops on single color images
--db-options db options string to pass to the image writer in quotes (e.g., “JPEG_QUALITY 60”)
--mp Use multiprocessing to process the tiles. Useful for GDAL sources as this avoids the global GDAL lock
--mt Use multithreading to process the tiles.
--concurrency The number of threads or processes to use if –mp or –mt are provided
--alpha-mask Mask out imagery that isn’t in the provided extents.
--verbose Displays progress of the operation

osgearth_conv

osgearth_conv copies the contents of one TileSource to another. All arguments are Config name/value pairs, so you need to look in the header file for each driver’s Options structure for options. Of course, the output driver must support writing (by implementing the ReadWriteTileSource interface). The “in” properties come from the GDALOptions getConfig method. The “out” properties come from the MBTilesOptions getConfig method.

Sample Usage

osgearth_conv --in driver gdal --in url world.tif --out driver mbtiles --out filename world.db
Argument Description
--elevation convert as elevation data (instead of image data)
--profile [profile] reproject to the target profile, e.g. “wgs84”
--min-level [int] min level of detail to copy
--max-level [int] max level of detail to copy
--threads [n] threads to use (Careful, may crash. Doesn’t help with GDAL inputs)
--extents [minLat] [minLong] [maxLat] [maxLong] Lat/Long extends to copy

osgearth_tfs

osgearth_tfs generates a TFS dataset from a feature source such as a shapefile. By pre-processing your features into the gridded structure provided by TFS you can significantly increase performance of large datasets. In addition, the TFS package generated can be served by any standard web server, web enabling your dataset.

Sample Usage

osgearth_tfs filename
Argument Description
filename Shapefile (or other feature source data file )
--first-level level The first level where features will be added to the quadtree
--max-level level The maximum level of the feature quadtree
--max-features The maximum number of features per tile
--grid Generate a single level grid with the specified resolution. Default units are meters. (ex. 50, 100km, 200mi)
--out The destination directory
--layer The name of the layer to be written to the metadata document
--description The abstract/description of the layer to be written to the metadata document
--expression The expression to run on the feature source, specific to the feature source
--order-by Sort the features, if not already included in the expression. Append DESC for descending order!
--crop Crops features instead of doing a centroid check. Features can be added to multiple tiles when cropping is enabled
--dest-srs The destination SRS string in any format osgEarth can understand (wkt, proj4, epsg). If none is specific the source data SRS will be used.

osgearth_backfill

osgearth_backfill is a specialty tool that is used to post-process TMS datasets. Some web mapping services use different completely different datasets at different zoom levels. For example, they may use NASA BlueMarble imagery until they reach level 4, then abruptly switch to LANDSAT data. This is fine for 2D slippy map visualization but can be visually distracting when viewed in 3D because neighboring tiles at different LODs look completely different.

osgearth_backfill lets you generate a TMS dataset like you normally would (using osgearth_package or another tool) and then “backfill” lower levels of detail from a specified higher level of detail. For example, you can specify a max level of 10 and lods 0-9 will be regenerated based on the data found in level 10.

Sample Usage

osgearth_backfill tms.xml
Argument Description
--bounds xmin ymin xmax ymax bounds to backfill (in map coordinates; default=entire map
--min-level level The minimum level to stop backfilling to. (default=0)
--max-level level The level to start backfilling from(default=inf)
--db-options db options string to pass to the image writer in quotes (e.g., “JPEG_QUALITY 60”)

osgearth_boundarygen

osgearth_boundarygen generates boundary geometry that you can use with an osgEarth <mask> layer in order to stich an external model into the terrain.

Sample Usage

osgearth_boundarygen model_file [options]
Argument Description
--out file_name output file for boundary geometry (default is boundary.txt)
--no-geocentric Skip geocentric reprojection (for flat databases)
--convex-hull calculate a convex hull instead of a full boundary
--verbose print progress to console
--view show result in 3D window
--tolerance N vertices less than this distance apart will be coalesced (0.005)
--precision N output coordinates will have this many significant digits (12)

osgearth_overlayviewer

osgearth_overlayviewer is a utility for debugging the overlay decorator capability in osgEarth. It shows two windows, one with the normal view of the map and another that shows the bounding frustums that are used for the overlay computations.