osgGIS Toolkit Overview



osgGIS builds OSG geometry from GIS feature data.

Some of the things you can do with osgGIS

  • Connect to feature data stores (like shapefiles) and read geometry and attributes
  • Assemble a custom pipeline for transforming feature data into OSG geometry
  • Build linear features like streets or political boundaries
  • Build extruded linear features like walls or fences
  • Build extruded structures like buildings, with facade and georeferenced rooftop textures
  • Substitute 3D models for point features
  • Clamp feature data to a terrain
  • Divide a huge layer into a grid and build cells in parallel
  • Embed custom Lua code in a build script to control the compilation process
  • Prepare overlay geometry for use with osgSim::OverlayNode?
  • Build layers offline or at runtime
  • Query feature attributes at runtime

What you can't do with osgGIS

Basic Workflow

In GIS terms, a feature is a fundamental unit of data comprised of some vector geometry and an associated set of attributes. osgGIS creates OSG scene graphs from GIS features. It does so using an "assembly line" process: features go in one end, the engine subjects them to a series of discrete processing steps, and a scene graph emerges from the other end. We call this process compilation.

More specifically, the compilation workflow looks like this:

  • Read features from a source location
  • Filter them to get only the features of interest
  • Feed them one at a time into the processing pipeline
  • Process and combine features into OSG drawables
  • Process and combine OSG drawables into OSG nodes
  • Combine the OSG nodes into a scene graph and return it to the user

That is the fundamental process. It is the selection and configuration of the processing units (called Filters) that determines how features turn into OSG geometry. osgGIS has several stock filters to choose from -- but it is fairly easy to write your own.

Fundamental Topics

Filters & Filter Graphs

osgGIS compiles a set of features by passing them though a FilterGraph. The FilterGraph is just a simple chain of !Filters. Each Filter performs some function against the incoming data and then passes the new data along to the next filter.

There are three data types that filters can input and output:

  • Feature : couples one or more vector shapes with an attribute set
  • Fragment : couples one or more osg::Drawable objects with an attribute set
  • Attributed Node : couple an osg::Node with an attribute set

There are many osgGIS filters, but they fall into four categories:

  • Feature Filters : accept features as input, and generate features as output
  • Fragment Filters : accept features or fragments as input, and generate fragments as output
  • Node Filters : accept features, fragments or nodes as input, and generate nodes as output
  • Collection Filters : accept any type of input, and generate the same type as output

It is only legal to chain filter together so that their inputs and outputs are compatible.

FeatureStores & FeatureLayers

Features are grouped together into some kind of backing store, like a file, web resource, or relational database table. In osgGIS, a FeatureStore is a connection to this backing store. A simple example would be an ESRI shapefile. A FeatureStore is responsible for reading data from that shapefile and return Feature objects. The interface lets you either a) read an individual features by unique ID, or b) iterate over all available features. osgGIS comes with a FeatureStore implementation that uses OGR to read common formats.

A FeatureLayer sits on top of a FeatureStore and adds application-level services like a spatial index. A spatial index lets you efficiently query for features that fall within a geographic area of interest. The FeatureLayer may also add layer-level attribution. In osgGIS, the typical workflow is to create a FeatureLayer using the Registry and to then compile data from that FeatureLayer using a layer compiler (described below).

Layer Compilers & Sessions

A layer compiler is a high-level utility for channeling features from one or more FeatureLayers through one or more FilterGraphs. It can then combine the outputs from the various filter graphs into a single final OSG scene graph. osgGIS has three built-in layer compilers:

  • Simple - compiles feature data into an in-memory, multi-LOD scene graph
  • Gridded - divides the data into a regular grid, and builds a paged, multi-LOD graph within each grid cell
  • Quadtree - compiles a paged, multi-LOD scene graph in which each LOD is a quadtree subdivision of the level above.

The gridded and quadtree compilers support incremental compilation and part-wise updating. Since there are no inter-dependencies among cells, they can compile them in parallel. This mechanism makes osgGIS very scalable since it can organize and compile datasets of arbitrary size using this technique.

Even though osgGIS can break a layer up into pieces and compile them independently, the entire layer compilation is tied together by a common Session. The session managed shared information like texture resources (a.k.a. skins) and external model references. It also tracks statistics associated with the layer compilation as a whole.


At the top of the heap are projects. A project contains all the configuration information necessary to compile an entire set of related GIS feature layers. For example, a project may define the rules for building a related set of roads, buildings, and trees that all sit atop a common terrain model.

Please refer to ProjectHowTos for more information on projects and how to use them.