Changes between Initial Version and Version 1 of ossimPlanetAPI

Timestamp:

Feb 4, 2008, 10:09:52 AM (16 years ago)

Author:

mlucas17

Comment:

--

ossimPlanetAPI

@@ +1 @@
+= ossimPlanet API =
+
+ossimPlanet is an advanced 3D global visualization system that builds upon the remote sensing and GIS capabilities in OSSIM and the advanced 3D visualization capabilities of OpenSceneGraph.  The core libraries are written in C++ and provide the ability to display and manipulate large geospatial files, 3D models, OGC WMS sites, WorldWind data servers, KML/KMZ files, and Predator motion video. The system also includes a powerful action/router communication system that allows peer to peer or server to client synchronization of navigation, data sets, and internal functions between multiple instances of ossimPlanet. 
+
+[[Image:OssimPlanetAPI.jpg]]
+
+The design goals of the system emphasize:
+
+* High performance 3D visualization
+* Photogrammetric accuracy
+* Native File access (files don't need to be staged, or "pre-cooked"
+* Advanced Collaboration (Data and Navigation synchronization)
+* Leveraging existing OpenSceneGraph and OSSIM capabilities
+
+== Goals ==
+The objective of the ossimPlanet Applications Programming Interface (API) is to make it easy to integrate ossimPlanet capabilities into other programs, solutions, technologies and computer languages.  A properly implemented API will minimize the learning curve and provide a simplified interface to integrate a 3D planet into a new application.  The ossimPlanet API will be implemented in C in an ossimPlanetAPI.c and ossimPlanetAPI.h header file.  That interface will be wrapped to provide bindings to other languages (Java, Python, Cocoa, etc) to provide native interfaces for the project.  There will initially be three modes, depending on application requirements, for use of the API:
+
+# The application owns and controls its own OpenGL Context and embeds planet as another drawable (SCOPES)
+# The application owns and controls its own OpenSceneGraph,  planet is just a node in that scene graph
+# The application gets all OpenSceneGraph and viewing capabilites from ossimPlanet, it creates the context and the rendering window
+
+The API should simplify the initialization and viewing of a fully capable planet with a minimum number of program calls.  The API implementation strategy will take advantage of the existing router/action communications infrastructure that is already established in ossimPlanet.  Once the planet is up and running, virtually all other functions can be controlled by sending messages to ossimPlanet.  These messages and their corresponding actions will be defined in a separate section of this API.  Java and other languages have simple mechanisms to transmit messages with standard communications protocols.  These requests can be sent generically at run time to trigger desired behavior in local or remote planets.
+
+This document will take a top down approach to the API and implement some quick start guides to show the developer how to quickly implement an application that incorporates ossimPlanet capabilities.  The ultimate reference for the API will be ossimPlanet/include/ossimPlanet/ossimPlanetApi.h and ossimPlanet/src/ossimPlanet/ossimPlanetApi.cpp in the svn ossim repository.  To check out the ossim repository, type in the following from a terminal:
+ svn co https://svn.osgeo.org/ossim/trunk .
+ For non developers use the technique that does not go through a secure socket:
+ svn co http://svn.osgeo.org/ossim/trunk .
+ (note the trailing . )
+
+== Quickstart Guide ==
+
+There are three potential paths to integrating ossimPlanet into your application:
+
+#  The application owns and controls its own OpenGL Context and embeds planet as another drawable (SCOPES)
+#  The application owns and controls its own OpenSceneGraph,  planet is just a node in that scene graph
+#  The application gets all OpenSceneGraph and viewing capabilites from ossimPlanet, it creates the context and the rendering window
+
+The initialization will begin with setting up a state pointer to ossimPlanet passing the appropriate mode from the list above.  This will initialize all needed resources for your application.
+
+== Case 1 The application owns and controls its own OpenGL Context ==
+and embeds planet as another drawable
+
+[[Image:Case1ossimPlanetAPI.jpg]]
+
+Use this case if your application already creates and maintains its own OpenGL context.  Within that context, ossimPlanet is just another drawable.  Behind the scenes ossimPlanet will provide the globe which is managed by an OpenSceneGraph within the library.
+
+== Case 2 The application owns and controls its own OpenSceneGraph ==
+planet is just a node in that scene graph
+
+[[Image:Case2ossimPlanetAPI.jpg]]
+
+This case is for applications that create and maintain their own OpenSceneGraph.  In this case the planet and it subtree of objects is just added as a node in the Application's tree.
+
+== Case 3 The application gets all OpenSceneGraph and viewing capabilites from ossimPlanet ==
+it creates the context and the rendering window.
+
+[[Image:Case3ossimPlanetAPI.jpg]]
+
+OssimPlanet with create and provide the view, the tree, and the planet objects to the application.  For new applications and simulations this approach requires the least amount of programming.
+
+== C API Reference ==
+=== Type Definitions ===
+ossimPlanet_StatePtr is the main pointer.  All API calls will manpulate this state pointer.  
+It will hold the planet layers, views, manipulators, ... etc. ossimPlanet_PlanetPtr is the native pointer
+to a Planet Object.  The ossimPlanet_LayerPtr is the native pointer to a Planet layer.   
+
+   typedef void*        ossimPlanet_StatePtr;
+   typedef void*        ossimPlanet_PlanetPtr;
+   typedef void*        ossimPlanet_LayerPtr;
+   typedef ossim_int64   ossimPlanet_IndexType;
+   typedef ossim_uint64 ossimPlanet_SizeType;
+   typedef const char*  ossimPlanet_ConstStringType;
+   typedef char*        ossimPlanet_StringType;
+   
+The context type determines how much you want the API to manage and handle.  There are 3 ways you probably would like to use the library.  
+
+*CASE 1 -  ossimPlanet_NOVIEWER_CONTEXT option is used to embed  the scenegraph and bridge view parameters. There are 2 situations when you want to do this and both require that you create your own GL context and manage it. The first situation is if Planet is the drawable and you are in a GUI environment that creates a Gl context for you.  You just make it current and then draw the planet and use the API to bridge view parameters and manipulate layers.  The second situation is if you have a full GL application that you wrote and all you want to do is embed the planet as a drawable.  This requires some additional gl state saving when invoking the drawing of the planet.
+* CASE 2 - ossimPlanet_PLANET_ONLY_CONTEXT option is used when you are wanting to use the API only to interface into the manipulation of the planet layers.  Typically this is done if you have your own OpenSceneGraph and your own View and gl context.  We will give you native access to the root planet class.
+* CASE 3 - ossimPlanet_VIEWER_CONTEXT option is typical of a full command line application that all you are concerned about is scripting and running a full screen or windowed planet.  This will interface into osg::Viewer and will create a render window for you.
+
+ typedef enum ossimPlanet_ContextType
+ {
+      ossimPlanet_NOVIEWER_CONTEXT    = 0,
+      ossimPlanet_PLANET_ONLY_CONTEXT = 1,
+      ossimPlanet_VIEWER_CONTEXT      = 2
+ };
+
+Standard boolean enumeration
+
+   typedef enum ossimPlanet_BOOL
+   {
+      ossimPlanet_FALSE = 0,
+      ossimPlanet_TRUE  = 1
+   };
+
+=== Setup and Initialization ===
+This section is reserved for setup and initialization.  There are a number of setup interfaces that can be used to set internal variables and search paths before the init is called.
+
+'''ossimPlanet_addOpenSceneGraphLibraryPath''' Will add the passed in path to OpenSceneGraph's Library path.  This will be used mainly for finding OpenSceneGraph plugins.  If this needs to be setup it should be done before you call ossimPlanet_init and start adding layers to planet.
+   
+  /**
+    * @param path Path to add to the Library search path.
+    * @param insertFrontFlag Inserts the path to the front of the search path list if its ossimPlanet_TRUE and
+    *                        appends to the end otherwise.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_addOpenSceneGraphLibraryPath(ossimPlanet_ConstStringType path,
+                                                                 ossimPlanet_BOOL insertFrontFlag);
+
+
+'''ossimPlanet_addOpenSceneGraphDataPath''' Adds the passed in path to OpenSceeGraph's data path.  This allows one to give relative path naming to data that is loaded.  For example:  if you have a font called arial.ttf and it's located in /fonts then you can add /fonts to the search path and you can load a font by just the name "arial.ttf".  The /fonts will be prepended.  If this needs to be setup it should be done before you call ossimPlanet_init and start adding layers to planet.
+
+  /**
+    * @param path Path to add to the Data search path.
+    * @param insertFrontFlag Inserts the path to the front of the search path list if its ossimPlanet_TRUE and
+    *                        appends to the end otherwise.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_addOpenSceneGraphDataPath(ossimPlanet_ConstStringType path,
+                                                              ossimPlanet_BOOL insertFrontFlag);
+   
+'''ossimPlanet_loadOssimPreferenceFile''' exposes the OSSIM core engines preference loading from a file.
+
+   /**
+    * @param preferenceFile The preference file to load.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_loadOssimPreferenceFile(ossimPlanet_ConstStringType preferenceFile);
+
+'''ossimPlanet_setOssimPreferenceNameValue''' Allows you access to the OSSIM core engine's preference variables and you can set them.
+   /**
+    * @param name The name of the preference variable.
+    * @param value The value of the preference variable.
+    */ 
+   OSSIMPLANET_DLL void ossimPlanet_setOssimPreferenceNameValue(ossimPlanet_ConstStringType name,
+                                                                ossimPlanet_ConstStringType value);
+
+'''ossimPlanet_addOssimPlugin'''     Adds an ossim core plugin.  If this is a directory then all files in the directoy that are plugins are added
+   /**
+    * @param path Path to add to the OSSIM Plugin search path.
+    * @param insertFrontFlag Inserts the path to the front of the list if its ossimPlanet_TRUE and
+    *                        appends to the end otherwise.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_addOssimPlugin(ossimPlanet_ConstStringType path,
+                                                   ossimPlanet_BOOL insertFrontFlag);
+
+'''ossimPlanet_addOssimElevation''' Add elevation to the OSSIM core system.
+   /**
+    * @param path Path to add to the Elevation.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_addOssimElevation(ossimPlanet_ConstStringType path);
+
+
+
+'''ossimPlanet_addGeoid''' Elevation data is typically relative to mean sea level.  The geoid grids will be used to shift the Mean Sea Level to ellipsoidal heights. 
+
+   /**
+    * @param path Path to add to the Geoid search path.
+    * @param byteOrder.  Most of the goid grids don't have Endian indication.  You can download little endian or big endian type geoid grids
+    *        The basic 96 grid that comes with OSSIM egm96.grd is a big endian byte order.  You can downlod from 
+    * @param insertFrontFlag Inserts the path to the front of the search path list if its ossimPlanet_TRUE and
+    *                        appends to the end otherwise.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_addGeoid(ossimPlanet_ConstStringType path,
+                                             ossimByteOrder byteOrder,
+                                            ossimPlanet_BOOL insertFrontFlag);
+
+'''ossimPlanet_init''' Used to initialize the system.  This is typically called one time.  It initializes internal registries.
+
+ void ossimPlanet_init();
+
+'''ossimPlanet_initWithArgs''' Allows one to init by passing command line arguments.  This is typically used by command line applications.
+
+   /**
+    * @param argc A pointer to an integer.
+    * @param argv Pointer to the argv.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_initWithArgs(int* argc, char** argv[]);
+
+'''ossimPlanet_setTracePattern''' Allows you to set the trace on and off for various classes in the system.  If you want to trace all ossim classes then do ossimPlanet_setTracePattern("ossim.*");
+
+'''ossimPlanet_setTracePattern''' Allows you to set the trace on and off for various classes in the system.  This is in the format of a regular expression.  Some of the special characters found in the regular expression are:
+   /**
+    * ^        Matches at beginning of a line
+    * $        Matches at end of a line
+    * .        Matches any single character
+    * [ ]      Matches any character(s) inside the brackets
+    * [^ ]     Matches any character(s) not inside the brackets
+    * -        Matches any character in range on either side of a dash
+    * *        Matches preceding pattern zero or more times
+    * +        Matches preceding pattern one or more times
+    * ?        Matches preceding pattern zero or once only
+    *
+    * ()       Saves a matched expression and uses it in a  later match
+    *
+    * If you want to trace all
+    * ossim classes then do :
+    * 
+    * ossimPlanet_setTracePattern("ossim.*");
+    *
+    * @param pattern A regular expression pattern to describe what to trace.  
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setTracePattern(ossimPlanet_ConstStringType pattern);
+
+'''ossimPlanet_finalize''' Allows for cleanup.  It will cleanup wen the last finalize is called. So if multiple calls to init occur then the same number of finalizes need to occur.
+
+ void ossimPlanet_finalize();
+
+'''ossimPlanet_microSecondSleep''' Gives access to a microsecond sleep.
+   /**
+    * @param microSeconds Specify how many microseconds to sleep.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_microSecondSleep(ossimPlanet_SizeType microSeconds);
+   
+
+'''ossimPlanet_milliSecondSleep''' Gives access to a millisecond sleep.
+   /**
+    * @param milliSeconds Specify how many microseconds to sleep.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_milliSecondSleep(ossimPlanet_SizeType milliSeconds);
+
+
+'''ossimPlanet_secondSleep''' Gives access to a seconds sleep.
+
+   /**
+    * @param seconds Specify how many microseconds to sleep.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_secondSleep(ossimPlanet_SizeType seconds);
+
+=== State Interface ===
+
+Cases 1,2, & 3
+
+'''ossimPlanet_newState'''  will return an internal class that contains all the needed state information.  It will basically create a self contained manager for view, layers, manipulator, ... etc.  This Will be the main pointer that all API calls operate on.  Note: Currently there can be only 1 view assigned per state.
+
+    /**
+    * @param contextType This specifies the type of context you would like to create.  @see ossimPlanet_contextType.
+    *
+    * @return State pointer;
+    */
+   OSSIMPLANET_DLL ossimPlanet_StatePtr ossimPlanet_newState(ossimPlanet_ContextType type);
+   
+   
+'''ossimPlanet_deleteState''' will delete the passed in state and set the pointer back to 0.
+
+ /**
+ * @param state This is the state to delete.
+ */
+ OSSIMPLANET_DLL void ossimPlanet_deleteState(ossimPlanet_StatePtr state);
+
+=== View Interface ===
+
+Cases 1 and 3
+
+The view interface portion of the API applies only to the ossimPlanet_VIEWER_CONTEXT and ossimPlanet_NOVIEWER_CONTEXT.  The API will define ways to manipulate the view, setup projection and View Matrices, define viewport settings, ... etc.
+
+'''ossimPlanet_setSceneDataToView''' is used to set the Planet layers to the view once you finish setting it up.  Typically, you initialize the layers to default values and then call this API to tie it to the view.
+
+   /**
+    * @param state The state to modify.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setSceneDataToView(ossimPlanet_StatePtr state);
+
+'''setViewportToCurrentGlSettings''' will assume that a Gl context is created and that the Viewport is set.  It will use GL calls to get the current Viewport values and set to the internal structures associated with the passed in state.  This is used when you are manipulating the Viewport through GL calls.  If this is the case then you can call this before rendering the planet.
+
+'''ossimPlanet_setViewManipulator''' Allows one to set a manipulator for the view.  For now, we only support manipulator type ossimPlanetManipulator.
+
+   /**
+    * @param state The state to modify.
+    * @param typeName The type of Manipulator to create.  The current one is ossimPlanetManipulator.
+    * @param receverPathName The recever path name given to this object.  We can pass setup commands to it.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewManipulator(ossimPlanet_StatePtr state,
+                                                       ossimPlanet_ConstStringType typeName,
+                                                       ossimPlanet_ConstStringType receiverPathName);
+
+   /**
+    * @param state State to modify.
+    */
+   OSSIMPLANET_DLL void setViewportToCurrentGlSettings(ossimPlanet_StatePtr state);
+
+'''ossimPlanet_setViewManipulator''' will set your current state view manipulator.
+   /**
+    *  Only support ossimPlanetManipulator type for now.
+    *
+    * @param state The state to modify.
+    * @param typeName The type of Manipulator to create.  The current one is ossimPlanetManipulator.
+    * @param receverPathName The recever path name given to this object.  We can pass setup commands to it.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewManipulator(ossimPlanet_StatePtr state,
+                                                       ossimPlanet_ConstStringType typeName,
+                                                       ossimPlanet_ConstStringType receiverPathName);
+
+   /**
+    * @param state State to modify.
+    */
+   OSSIMPLANET_DLL void setViewportToCurrentGlSettings(ossimPlanet_StatePtr state);
+   
+'''setProjectionMatrixToCurrentGlSettings''' This will assume that a Gl context is created and that the Projection Matrix is set.  It will use GL calls to get the current Projection Matrix values and set to the internal structures associated with the passed in state.  This is used when you are manipulating the Projection Matrix through  GL calls.  If this is the case then you can call this before rendering the planet.
+
+   /**
+    * @param state State to modify.
+    */
+   OSSIMPLANET_DLL void setProjectionMatrixToCurrentGlSettings(ossimPlanet_StatePtr state);
+   
+'''setModelViewMatrixToCurrentGlSettings''' This will assume that a Gl context is created and that the ModelView Matrix is set.  It will use GL calls to get the current ModelView Matrix values and set to the internal structures associated with the passed in state.  This is used when you are manipulating the ModelView Matrix through GL calls.  If this is the case then you can call this before rendering the planet.
+
+   /**
+    * @param state State to modify.
+    */
+   OSSIMPLANET_DLL void setModelViewMatrixToCurrentGlSettings(ossimPlanet_StatePtr state);
+
+'''ossimPlanet_setProjectionMatrixAsPerspective''' will allow one to set the perspective.
+
+   /**
+    * @param state The state to modify.
+    * @param fov Field of view in degrees.
+    * @param aspectRatio The aspect ratio of the view.
+    * @param near The near plane distance.
+    * @param far The far plane distance.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrixAsPerspective(ossimPlanet_StatePtr state,
+                                                                     double fov,
+                                                                     double aspectRatio,
+                                                                     double near, 
+                                                                     double far);
+
+'''ossimPlanet_setProjectionMatrixAsFrustum''' is identical to using the  glFrustum call.
+
+   /**
+    * @param state The state to modify.
+    * @param left Left value.
+    * @param right Right value.
+    * @param bottom Bottom value.
+    * @param top Top value.
+    * @param zNear zNear value.
+    * @param zFar zFar value.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrixAsFrustum(ossimPlanet_StatePtr state,
+                                                                 double left, double right,
+                                                                 double bottom, double top,
+                                                                 double zNear, double zFar);
+
+'''ossimPlanet_setProjectionMatrixAsOrtho''' is identical to the glOrtho call and creates and orthographic projection.
+   
+   /**
+    * @param state The state to modify.
+    * @param left Left value.
+    * @param right Right value.
+    * @param bottom Bottom value.
+    * @param top Top value.
+    * @param zNear zNear value.
+    * @param zFar zFar value.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrixAsOrtho(ossimPlanet_StatePtr state,
+                                                               double left, double right,
+                                                               double bottom, double top,
+                                                               double zNear, double zFar);
+   
+'''ossimPlanet_setProjectionMatrixAsOrtho2D''' will set to a 2D orthographic projection. See OpenGL glOrtho2D documentation for further details.
+   /** 
+    * @param state The state to modify.
+    * @param left Left value.
+    * @param right Right value.
+    * @param bottom Bottom value.
+    * @param top Top value.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrixAsOrtho2D(ossimPlanet_StatePtr state,
+                                                                 double left, double right,
+                                                                 double bottom, double top);
+
+'''ossimPlanet_setProjectionMatrixAsRowOrderedArray'''  assumes a 4x4 array or 16 consecutive values.  The values are stored row ordered.  This means that the first 4 values are for the first row and the second four values are for the second row, ... etc.
+
+   /**
+    * @param state The state to modify.
+    * @param m The array of 16 values
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrixAsRowOrderedArray(ossimPlanet_StatePtr state,
+                                                                         double* m);
+   
+'''ossimPlanet_setProjectionMatrix''' will set the projection matrix to the passed in values.  Note m00 - m03 identifies the first row of the matrix, then the next is the second row, ... etc.
+
+   /**
+    * @param state The state to modify the view orientation matrix.
+    * @param m00 row 0 col 0
+    * @param m01 row 0 col 1
+    * @param m02 row 0 col 2
+    * @param m03 row 0 col 3
+    * @param m10 row 1 col 0
+    * @param m11 row 1 col 1
+    * @param m12 row 1 col 2
+    * @param m13 row 1 col 3
+    * @param m20 row 2 col 0
+    * @param m21 row 2 col 1
+    * @param m22 row 2 col 2
+    * @param m23 row 2 col 3
+    * @param m30 row 3 col 0
+    * @param m31 row 3 col 1
+    * @param m32 row 3 col 2
+    * @param m33 row 3 col 3
+    *
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setProjectionMatrix(ossimPlanet_StatePtr state,
+                                                        double m00, double m01, double m02, double m03,
+                                                        double m10, double m11, double m12, double m13,
+                                                        double m20, double m21, double m22, double m23,
+                                                        double m30, double m31, double m32, double m33);
+
+
+'''ossimPlanet_setViewMatrixAsLlhHprRelativeTangent''' will allow one to pass in the lat, lon height and the euler angles to define the view matrix.  The Euler angles are relative to the tangent plane at the given lat lon position.  Note: this is for the camera and the Z-Axis is the plumb/Nadir axis.  This means that a heading, pitch and roll of all zero degrees will have the eye looking straight down.  Note: all lat lon values are assumed to be relative to the WGS84 ellipsoid.  
+
+  /**
+    * @param state The state to modify.
+    * @param lat The latitude of the view camera in degrees.
+    * @param lon The longitude of the view camera in degrees.
+    * @param height The height of the view camera in meters relative to the WGS84 ellipsoid.
+    * @param heading The heading of the view camera in degrees.
+    * @param pitch  The pitch of the view camera in degrees.
+    * @param roll  The roll of the view camera in degrees.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewMatrixAsLlhHprRelativeTangent(ossimPlanet_StatePtr state,
+                                                                         double lat,
+                                                                         double lon,
+                                                                         double height,
+                                                                         double heading,
+                                                                         double pitch,
+                                                                         double roll);
+   
+'''ossimPlanet_setViewMatrixAsLlhHprAbsolute'''    will allow one to pass in the lat, lon height and the euler angles to define the view matrix.  The Euler angles are not relative to the tangent plane at the given lat lon position but instead the unit axis is used as the base for the camera and the Z-Axis is the plumb/Nadir axis.  Note: all lat lon values are assumed to be relative to the WGS84 ellipsoid.  
+
+
+   /**
+    * @param state The state to modify.
+    * @param lat The latitude of the view camera in degrees.
+    * @param lon The longitude of the view camera in degrees.
+    * @param height The height of the view camera in meters relative to the WGS84 ellipsoid.
+    * @param heading The heading of the view camera in degrees.
+    * @param pitch  The pitch of the view camera in degrees.
+    * @param roll  The roll of the view camera in degrees.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewMatrixAsLlhHprAbsolute(ossimPlanet_StatePtr state,
+                                                                  double lat,
+                                                                  double lon,
+                                                                  double height,
+                                                                  double heading,
+                                                                  double pitch,
+                                                                  double roll);
+   
+'''ossimPlanet_setViewMatrixAsRowOrderedArray''' will set the matrix to the passed in row ordered array.
+
+   /**
+    * @param state The state to modify the view orientation matrix.
+    * @param m Row ordered view matrix.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewMatrixAsRowOrderedArray(ossimPlanet_StatePtr state,
+                                                                   const double *m);
+   
+
+'''ossimPlanet_setViewMatrix'''    will set the matrix to the passed in values.  Note m00 - m03 identifies the first row of the matrix, then the next is the second row, ... etc.
+
+   /**
+    *
+    * @param state The state to modify the view orientation matrix.
+    * @param m00 row 0 col 0
+    * @param m01 row 0 col 1
+    * @param m02 row 0 col 2
+    * @param m03 row 0 col 3
+    * @param m10 row 1 col 0
+    * @param m11 row 1 col 1
+    * @param m12 row 1 col 2
+    * @param m13 row 1 col 3
+    * @param m20 row 2 col 0
+    * @param m21 row 2 col 1
+    * @param m22 row 2 col 2
+    * @param m23 row 2 col 3
+    * @param m30 row 3 col 0
+    * @param m31 row 3 col 1
+    * @param m32 row 3 col 2
+    * @param m33 row 3 col 3
+    *
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewMatrix(ossimPlanet_StatePtr state,
+                                                  double m00, double m01, double m02, double m03,
+                                                  double m10, double m11, double m12, double m13,
+                                                  double m20, double m21, double m22, double m23,
+                                                  double m30, double m31, double m32, double m33);
+
+'''ossimPlanet_setViewport''' will allow you to set the viewport dimensions.
+
+   /**
+    * @param state  The state to modify the viewport definitions.
+    * @param x The x location in pixels of the viewport.  Typically 0
+    * @param y The y location in pixels of the viewport.  Typically 0
+    * @param w The width in pixels of the viewport.
+    * @param h The height in pixels of the viewport.
+    *
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewport(ossimPlanet_StatePtr state,
+                                                int x, 
+                                                int y, 
+                                                int w, 
+                                                int h);
+
+'''ossimPlanet_setViewportClearColor''' will clear the viewport with the passed in color.
+
+   /**
+    * @param state  The state information to modify the clear color.
+    * @param red The red component of the clear color.
+    * @param green The green component of the clear color.
+    * @param blue The blue component of the clear color.
+    * @param alpha The alpha component of the clear color.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setViewportClearColor(ossimPlanet_StatePtr state,
+                                                  float red,
+                                                  float green,
+                                                  float blue,
+                                                  float alpha);
+
+=== Rendering Interface ===
+Cases 2 and 3
+
+This will hold the basic rendering interface definitions.  We should supply a way to query if the graph needs rendering or not and a way to render the graph.
+
+
+'''ossimPlanet_renderFrame'''  is the main rendering step.  This will render 1 frame.
+
+   /**
+     * @param state The state to modify.
+     * @return Returns ossimPlanet_TRUE if the render frame can continue again or
+     *                 ossimPlanet_FALSE if it was canceled.  
+     */
+   OSSIMPLANET_DLL ossimPlanet_BOOL ossimPlanet_renderFrame(ossimPlanet_StatePtr state);
+
+'''ossimPlanet_renderFramePreserveState'''  is the main rendering step.  This will render 1 frame and preserve the state.  This will call osismPlanet_pushState before rendering and ossimPlanet_popState after rendering and will preserve gl attributes, View, Projection and Texture matrices.
+
+   /**
+    * @param state The state to modify.
+    * @return Returns ossimPlanet_TRUE if the render frame can continue again or
+    *                 ossimPlanet_FALSE if it was canceled.  
+    */
+   OSSIMPLANET_DLL ossimPlanet_BOOL ossimPlanet_renderFramePreserveState(ossimPlanet_StatePtr state);
+
+
+'''ossimPlanet_needsRendering''' is used determine if another frame is required to be rendered.  Call this to determine if you need to call ossimPlanet_renderFrame.   
+
+   /**
+    * Example use:
+    *
+    *    if(ossimPlanet_needsRendering(state))
+    *    {
+    *        ossimPlanet_frame(state);
+    *    }
+    *
+    * @param state The state to modify.
+    * @return ossimPlanet_TRUE if needs to continue rendering or ossimPlanet_FALSE if
+    *         no more rendering is required.
+    */
+   OSSIMPLANET_DLL ossimPlanet_BOOL ossimPlanet_needsRendering(ossimPlanet_StatePtr state);
+
+=== Layer interface ===
+This section allows for generic Planet layer manipulation.
+
+'''ossimPlanet_addLayer''' adds a layer to planet. the layer type is used in the ossimPlanetLayerRegistry to construct a layer of the passed layerType.  The receiverName is used to set the receiver name of the layer created so action messages can be routed to it.
+
+   /**
+    * @param state The state to modify.
+    * @param layerType Layer type name to add.  This is used by the layer registry to construct a layer
+    *                  specified by the layerType.
+    * @param name This is the name you wish to give the layer.
+    * @param id This is the id for the layer.
+    * @param description This is the description for the layer.
+    * @param receiverPathName Allows one to create a receiver name for the layer.  This is the target name for
+    *                         Action messages(@see ossimPlanet_routeAction).
+    *
+    * @return The natve pointer to the layer added.
+    */
+   OSSIMPLANET_DLL ossimPlanet_LayerPtr ossimPlanet_addLayer(ossimPlanet_StatePtr state,
+                                                             ossimPlanet_ConstStringType layerType,
+                                                             ossimPlanet_ConstStringType name,
+                                                             ossimPlanet_ConstStringType id,
+                                                             ossimPlanet_ConstStringType description,
+                                                             ossimPlanet_ConstStringType receiverPathName);
+
+'''ossimPlanet_getNumberOfLayers''' Allows one access to the number of layers currently defined for your state.
+
+   /**
+    * @param state The state to use.
+    *
+    * @return Returns the number of layers defined in planet for the give state.
+    */
+   OSSIMPLANET_DLL ossimPlanet_SizeType ossimPlanet_getNumberOfLayers(ossimPlanet_StatePtr state);
+
+
+'''ossimPlanet_getIndexOfLayerGivenPtr''' Allows one to get the layer index of the passed in layer. 
+
+   /**
+    * @param state The state to use.
+    * @param layerPtr The layer pointer to use.
+    *
+    * @return Returns the index of the layer given it's pointer.
+    */
+   OSSIMPLANET_DLL ossimPlanet_IndexType ossimPlanet_getIndexOfLayerGivenPtr(ossimPlanet_StatePtr state,
+                                                                             ossimPlanet_LayerPtr layerPtr);
+ 
+'''ossimPlanet_getLayerGivenIndex''' Allows one to get the layer pointer from the passed in index.  
+   /**
+    * @param state The state to use.
+    * @param idx The index number of the layer to return.
+    *
+    * @return Returns the layer pointer given an index.  NULL or 0 is returned if idx is out of range.
+    */
+   OSSIMPLANET_DLL ossimPlanet_LayerPtr ossimPlanet_getLayerGivenIndex(ossimPlanet_StatePtr state,
+                                                                       ossimPlanet_IndexType idx);
+
+'''ossimPlanet_getLayerGivenId''' Will return the native layer pointer given the id   
+   /**
+    * @param state The state to use.
+    * @param idThe id of the layer to search.
+    *
+    * @return Returns the layer pointer identified by id.
+    */
+   OSSIMPLANET_DLL ossimPlanet_LayerPtr ossimPlanet_getLayerGivenId(ossimPlanet_StatePtr state,
+                                                                    ossimPlanet_ConstStringType id);
+
+'''ossimPlanet_getLayerName''' returns the layer name.
+
+   /**
+    * @param state The state to use.
+    * @param idx The index of the layer to access.
+    *
+    * @return The layer name for the layer at the specified index.
+    */
+   OSSIMPLANET_DLL ossimPlanet_ConstStringType ossimPlanet_getLayerName(ossimPlanet_LayerPtr layer);
+
+'''ossimPlanet_setLayerName''' allows one to set the layer name.
+   
+   /**
+    * @param layer The layer to set.
+    * @param name The name to set the layer to.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setLayerName(ossimPlanet_LayerPtr layer,
+                                                 ossimPlanet_ConstStringType name);   
+
+'''ossimPlanet_getLayerId''' returns the layer id.
+   
+   /**
+    * @param state The state to use.
+    * @param idx The index of the layer to access.
+    *
+    * @return The layer name for the layer at the specified index.
+    */
+   OSSIMPLANET_DLL ossimPlanet_ConstStringType ossimPlanet_getLayerId(ossimPlanet_LayerPtr layer);
+      
+'''ossimPlanet_setLayerId''' Allows one to set the layer id.
+
+   /**
+    * @param layer The layer to set.
+    * @param id The id to set the layer to.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setLayerId(ossimPlanet_LayerPtr layer,
+                                               ossimPlanet_ConstStringType id);
+
+'''ossimPlanet_getLayerDescription''' returns the layer description.
+
+   /**
+    * @param state The state to use.
+    * @param idx The index of the layer to access.
+    *
+    * @return The layer description for the layer at the specified index.
+    */
+   OSSIMPLANET_DLL ossimPlanet_ConstStringType ossimPlanet_getLayerDescription(ossimPlanet_LayerPtr layer);
+
+'''ossimPlanet_setLayerDescription''' Allows one to set the layer description.
+
+   /**
+    * @param layer The layer to set.
+    * @param description The description to set the layer to.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setLayerDescription(ossimPlanet_LayerPtr layer,
+                                                        ossimPlanet_ConstStringType description);
+
+'''ossimPlanet_getLayerReceverPathName''' Returns the layer's receiver path name
+
+   /**
+    * @param state The state to use.
+    * @param idx The index of the layer to access.
+    *
+    * @return The recever path name for the layer at the specified index.
+    */
+   OSSIMPLANET_DLL ossimPlanet_ConstStringType ossimPlanet_getLayerReceverPathName(ossimPlanet_LayerPtr layer);
+
+'''ossimPlanet_setLayerReceiverPathName''' Allows one to change/set the layer receiver path name.     
+   /**
+    * @param layer The layer to set.
+    * @param receiverName The description to set the layer to.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_setLayerReceiverPathName(ossimPlanet_LayerPtr layer,
+                                                             ossimPlanet_ConstStringType receiverPathName);
+
+== Action / Router and Receiver Command Reference ==
+We will define the API used to send messages to different layers in the system.  followed by documentation on layers that have receiver commands. 
+
+
+'''ossimPlanet_routeActionForm1''' This will use ossimPlanet's Action router to route the message to the destination.  For example: lets say we have a receiver name as foo and we have an action called bar and it takes a single string as an argument then call ossimPlanet_routeActionForm1(":foo bar MySingleString"). This will route a action "bar" to the receiver "foo" and has 1 argument MySingleString.
+
+    /**
+      * @param action
+      */
+   OSSIMPLANET_DLL void ossimPlanet_routeActionForm1(ossimPlanet_ConstStringType completeAction);
+
+
+'''ossimPlanet_routeActionForm2'''  Is a utility call that is the same as ossimPlanet_routeActionForm1 but will do the concatenation of the target, action, and arg parameters into a single composite action.  ossimPlanet_routeActionForm2(":foo", "bar", "MySingleString") will perform the same action as Form1 above.
+   /**
+    * @param action
+    */
+   OSSIMPLANET_DLL void ossimPlanet_routeActionForm2(ossimPlanet_ConstStringType target,
+                                                     ossimPlanet_ConstStringType action,
+                                                     ossimPlanet_ConstStringType arg);
+
+'''ossimPlanet_postActionForm1'''  will use ossimPlanet's Action router to route the message to the destination.  The post call will instead add the action to a thread queue and route in the background without the caller having to wait for completion.  This is equivalent to ossimPlanet_routeActionForm1 above but will instead just add to thread queue for later processing.
+ 
+   /**
+    * @param action
+    */
+   OSSIMPLANET_DLL void ossimPlanet_postActionForm1(ossimPlanet_ConstStringType completeAction);
+   
+'''ossimPlanet_postActionForm2''' will use ossimPlanet's Action router to route the message to the destination.  The post call will instead add the action to a thread queue and route in the background without the caller having to wait for completion.  This is equivalent to ossimPlanet_routeActionForm2 above but will instead just add to thread queue for later processing.
+
+   /**
+    * @param target The target receiver path name.
+    * @param action The action to execute
+    * @param arg the arguments for the action.
+    */
+   OSSIMPLANET_DLL void ossimPlanet_postActionForm2(ossimPlanet_ConstStringType target,
+                                                     ossimPlanet_ConstStringType action,
+                                                     ossimPlanet_ConstStringType arg);
+=== ossimPlanetLand Receiver Commands ===
+
+'''add''' takes any number of arguments and can be of the form:
+
+* {Image {Parent {Name <name>} {Id <id>}} {Name <name>} {Id <id>} {Description <description>} {Filename <file>}}
+This is the Image object definition and supplies all parameters for initialization.  For the {Image ..} you can give it a name, Id and a description.  The accessor in this example is a Filename type. Future accessor types will be given such as Wms.  The {Parent ...} object is used to identify the Parent you wish to add the layer to If this is not specified then the root Layer of the reference set is used as the parent.  You must call add {ImageGroup {...}} to create a group before adding to it any children  This basically allows you to group Image types into a common group.  Note, the name id and description are optional but if you want to later do a remove you might want to specify at least one or both name and id for the image being added.
+* {ImageGroup {Parent {Name <name>} {Id <id>}} {Name <name>} {Id <id>} {Description <description>} } 
+Allows one to create a group and give it a name id and description.<br>
+<br>
+'''remove'''  takes any number of arguments and can be of the form:
+*{Image {Name <name>} {Id <id>}}
+This form is used to also delete layers of type ImageGroup.  For image groups you still use {Image and not {ImageGroup for the removal.
+
+'''Examples:'''<br> 
+Add a filename accessor to the root texture reference layer called /data/ccf_utm/foo.ccf and give it and id, description and name.  We add it as a child to a previosly created group with name MyRootLayer. 
+ ossimPlanet_routeActionForm1(":land add {Image  {Name MyName} {Id MyId} {Description my big description} {Filename /data/ccf_utm/foo.ccf} }"
+
+Add a filename accessor as a child of a layer with id MyRootIdan give it an id, description and name with a filename /data/ccf_utm/foo.ccf.  
+ ossimPlanet_routeActionForm1(":land add {Image {Parent {Id MyRootId} {Name MyRootLayer} } {Name MyName} {Id MyId} {Description my big description} {Filename /data/ccf_utm/foo.ccf} }"
+
+Remove a layer
+
+   ossimPlanet_routeActionForm1(":land remove {Image {Name MyName} {Id MyId}}"
+
+Notice the Image object is eclosed by { } brackets.  You can have any number of them on one line {Image {.....}} {Image {...}} .... etc.
+