OpenSceneGraph Ephemeris Model

osgEphemeris Documentation

Table of Contents

Introduction

From dictionary.com:
e·phem·er·is    ( P )     (-fmr-s)
n. pl. eph·e·mer·i·des (f-mr-dz)
A table giving the coordinates of a celestial body at a number of specific times during a given period.

[Late Latin ephmeris, from Greek, diary, from ephmeros, daily. See ephemeral.]

osgEphemeris provides the virtual environment for the sky, sun, moon, planets and stars to be used with visualization applications using OpenSceneGraph. When using osgEphemeris, the user provides the software with Latitude, Longitude, Date and Time, and the software will provide a ground (or near-ground) view of the sky with the sun, moon, planets, and stars all positioned with reasonable accuracy.

Note that osgEphemeris is intended for ground based visualization and does not extend to space flight or accurate representation of heavenly body positioning other than for a view that is on or near the ground. Near means within 40,000 feet of the ground, or so. Altitudes are taken into consideration and distance above horizon for heavenly bodies, but loose accuracy the higher the vantage point.

The software is provided for use in two methods: as a C++ API, or as a .osg file format, using OpenSceneGraph Node Kit methodology. This document will demonstrate how to use the osgEphemeris software, how to integrate it into your application and how to control its parameters.

Familiarity with OpenSceneGraph C++ API and OpenSceneGraph utility programs, such as osgviewer are assumed.

Downloading and Building osgEphemeris

The current build is tested solely on Linux. As most osg components, osgEphemeris should port easily to Windows and other platforms with little effort. Contributions are welcome.

Downloading osgEphemeris

Current access to osgEphemeris is through cvs on openscenegraph.org:


cvs -d :pserver:cvsguest@openscenegraph.org:/cvs/osg co osgEphemeris

Building osgEphemeris on Linux

Prerequisite: DWMake

A prerequisite for building osgEphemeris is DWMake. DWMake is a simple set of GNU makefile definitions and rules for a set of common targets. Instructions for getting and installing DWmake follow

DWMake is also available through CVS:


cvs -d :pserver:cvsguest@openscenegraph.org:/cvs/DWMake co DWMake

To build all projects using DWMake a global environmental variable DWMAKE needs to be defined, which points to the top level directory where DWMake is installed. If you've just run the cvs command above, then the following applies:

For CSH:

% cd DWMake
% setenv DWMAKE `pwd`

For SH or BASH:

$ cd DWMake
$ export DWMAKE=`pwd`

You may want to add these to your .profile, .bashrc, or .cshrc, whichever is appropriate.

Building osgEphemeris

Once you have DWMake installed and the DWMAKE environmental variable defined, it is just a matter of typing make in the osgEphemeris directory:


% cd osgEphemeris
% make

Installing osgEphemeris

By default osgEphemeris installes in /usr/local. You may install in other locations by using the directive INST_LOCATION:


% make install
OR
% make INST_LOCATION=/usr install

Simple usage

The simples way to start using osgEphemeris is to save the following into a file named ephemeris.osg and use it on the command line with osgviewer. (We'll assume that you will use this file with a piece of terrain, named terrain.osg, which can be confined within a skydome of radius 100000): 

    osgEphemerisModel::EphemerisModel {
        Latitude 38.4765
        Longitude -122.493
        SkyDomeRadius 100000
    }

Like this: 
        osgviewer --clear-color 0,0,0,1 ephemeris.osg terrain.osg

Note, that it is recommended to use the argument --clear-color 0,0,0,1 which provides a black background as opposed to the OSG bluish default clear color.

Also note that the terrain will be distant and centered from the viewpoint, and probably not visible. The skydome will remain fixed at the eyepoint and will likely obscure the terrain in Trackball mode. Simply pull the terrain database toward the view with the right mouse button, or center the view by typing '3' (to enter 'DriveManipulator mode') followed by the <space> bar.

This example uses three directives in the .osg file: Latitude, Longitude, and SkyDomeRadius. Latitude and Longitude are the position of the viewer on planet earth, given in degrees. Negative values represent South and Western hemispheres respectively. The values given in the example correspond to San Francisco, California.

SkyDomeRadius refers to the size of the skydome's radius. By default, the skydome has a radius of the distance between the earth and the moon, or 384403.0 kilometers. Most terrain databases will become dwarfed by this large sky dome and will probably not even be visible. Set this value to something that is large enough to encompass the terrain you will be viewing, but not so large that it will cause visual anomalies.

For example, if the terrain is a block 25 Km by 25 Km, then set the radius to about 25000 (25 Km - assuming meters as units).

.OSG File Directives

As discussed above, a simple file containing the entry 

    osgEphemerisModel::EphemerisModel {
        Latitude 38.4765
        Longitude -122.493
        SkyDomeRadius 100000
    }
is sufficient to have a simple ephemeris model. A complete list of directives, which can be specified between the { and } brackets in the osgEphemeris::EphemerisModel definition, follows. Directives whose access value is set to D are dynamically changable at run-time. Directives whose access value is set to S are settable at initialization only.

Directive Description Type Units Range Default
Value		 Access
Latitude The global latitude of the earthbound view position. double degrees -180.0 - 180.0 0.0 D
Longitude The global longitude of the earthbound view position. double degrees -90.0 - 90.0 0.0 D
DateTime The argument for the DateTime directive is a string of the form YYYYMMDDhhmmss where
  • YYYY indicates the year (e.g. 2006)
  • MM indicates the month (e.g. 09 for September)
  • DD indicates the day of the month,
  • hh indicates the hour (range 00 to 23)
  • mm indicates the minutes (range 00 to 59)
  • ss indicates seconds (range 00 to 59).

For example, the string

20060224162800
represents the 24th of February, 2006, at 2:28 PM. hh, mm, and ss are optional and will be set to 00 if omitted. 		string now D
SkyDomeRadius The SkyDome is a sphere that encompasses the scene, providing the color of the sky, horizon and a surface to which the sun texture is projected. double <database> -180.0 - 180.0 0.0 S
AutoDateTime Direct osgEphemeris to update the date and time to the current date and time as set on the computer. Setting this to False will allow the application to dynamically change the date and time. Setting it to True will cause dynamic changes to be ignored and the current date and time will be used. boolean True/False True D
MoveWithEyePoint Direct osgEphemeris to move the skydome and all ephemeris components to be centered at the eyepoint at all times when set to True. If set to False, the ephemeris components will be centered around 0,0,0 and will not translate spatially. This is useful for debugging situations. boolean True/False True S
UpdateCallback Provide osgEphemeris a callback compiled as a dynamically shared object, specified by <shared object>::<class name>. For example:
TimePasses::TimePassesCallback
where TimePasses is the dynamically shared object and TimePassesCallback is the class name of the callback.

This callback is derived from osgEphemeris::EphemerisUpdateCallback and provides a functor to which a pointer to EphemerisData is passed. The callback may then modify the EphemerisData, updating latitude, longitude, date and time.

See example below

Callback NULL S