terrainDatabase.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2003 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: terrainDb.h,v $ $Revision: 1.87 $ $State: Exp $
*******************************************************************************/
#ifndef terrainDatabase_H_
#define terrainDatabase_H_

//
// \file terrainDb.h
// \brief Contains the DtTerrainDatabase class declarationn, as well as the DtTerrainFileVersionNumber and other related declarations and definitions.
//

#include "gdb/gdbDefines.h"
#include "gdb/gdbNode.h"
#include "gdb/fileNode.h"
#include "tdbutil/serializable.h"
#include "terrainCS/coordSystem.h"
#include "gdb/terrainModifiedCallbackInfo.h"
#include "gdb/surfaceManager.h"
#include "gdb/specificationManager.h"
#include "gdb/vertexManager.h"
#include "geometry/homogeneousTransformMatrix.h"
#include "geometry/surface.h"
#include <vlutil/vlFilename.h>
#include <vlutil/vlConfig.h>
#include <vector>
#include <assert.h>

class DtList;
class DtPoint;
class DtExtent;
class DtChord;
class DtChordBundle;
class DtChordIntersectionRecord;
class DtChordIntersectRecordList;
class DtColor;
class DtMemoryManager;
class DtBaseCoordinateSystem;
class DtAllTypesPolygon;
class DtGroup;
class DtVectorNetworkRecord;
class DtVectorNetworkIntersectionRecord;
class DtTerrainInitializer;
class DtPolygonIndirect;
class DtTriangleIndirect;
class DtVectorNetwork;
class DtVectorNetworkTool;
class DtPlane;
class DtTerrainIntersector;
class DtTerrainIntersectorDescriptor;

enum DtMemoryUsageDetails
{
   ShowDetails = 1,
   ShowSizeOnly
};

enum DtVectorNetworkTransformFlag
{
   TransformYes = 1,
   TransformNo   
};

// Terrain database file version number:
// 100:  initial version
// 201:  DtFileNodes added
// 202:  Spatial indexes and optional data flags added
// 203:  Vector network added
// 204:  Reorganization of data - forced new format
// 205:  Refactored vector data format completely.
// 206:  Changed from using spatial index to using spatial subdivision.
// 207:  Added map datum to coordinate system node and scale factor to utm node
// 209:  Removed spatial subdivision. It now works with opcode. It only stores triangles.
// 210:  Added back in spatial subdivision and added new terrain intersection method integer
static const DtTerrainFileVersionNumber CURRENT_TDB_FILE_FORMAT_VERSION = TDB_210_VERSION;

// Optional data flags
// These are bitfield values (they must be a power of 2).  Only add new values
// on the end of the list, regardless of what order they are written in!
typedef enum
{
   OPT_FEATURES =             0x00000001,
   OPT_SPATIAL_SUBDIVISION =  0x00000002,
   OPT_EXPORTED_BY_3D_GUI  =  0x00000004
} DtTerrainFileOptionalData;

static const DtTerrainFileOptionalData CURRENT_TDB_MAX_OPTIONAL_DATA = OPT_EXPORTED_BY_3D_GUI;

// A mask of the currently defined optional data bitfield values
static const unsigned int OPT_FLAGS_MASK = (CURRENT_TDB_MAX_OPTIONAL_DATA*CURRENT_TDB_MAX_OPTIONAL_DATA)-1;

//
// These callback function types are defined so this library
// doesn't have to know about the GUI system but can still call
// GUI functions which update a ProgressMeterDialogBoxClass
//
// The calling GUI code does this:
//
// static ProgressMeterDialogBoxClass *p = 0;
// static wxFrame *me = 0;
// void prog_start_fcn(char *label, int range) { p = new ProgressMeterDialogBoxClass(me, "label", range); }
// void prog_incremental_fcn(int increment) { p->DidSomeMore(increment); }
// void prog_set_value_fcn(int value) { p->SetValue(value); }
// void prog_end_fcn(void) { delete(p); }
//
//
// The called, time-intensive tdb functions call these like:
//
// void load_db(progressCallbackStartFunction *prog_start_fcnp,
//        progressCallbackSetValueFunction *prog_set_value_fcnp,
//        progressCallbackIncrementalProgressFunction *prog_incremental_fcnp,
//        progressCallbackEndFunction *prog_end_fcnp)
// {
//    (*prog_start_fcnp)("Loading database", 10000);
//
//    for (int i=0; i<10000; i++)
//      {
//     (*prog_set_value_fcnp)(i); // This, or...
//        (*prog_incremental_fcnp)(1); // this. 
//      }
//    (*prog_end_fcnp)();
// }  
//
// Or, if you can live with the restrictions, inherit CanPopUpProgressMeter
// class.
//

typedef void progressCallbackStartFunction(const char* label, int range);
typedef void progressCallbackSetValueFunction(int value);
typedef void progressCallbackIncrementalProgressFunction(int increment);
typedef void progressCallbackEndFunction();
typedef void (*locationConversionFunction)(Coordinate_System* csFrom, Coordinate_System* csTo, DtPoint& in, DtPoint& out, const DtVector* offset);

// class DtTerrainDatabase:
//
// DtTerrainDatabase represents an entire database in GDB format.  It 
// represents the terrain skin, geometrical features over the skin and a 
// vector network.  The database can be written out to, and read from, a file.


//
// DtTerrainDatabase represents an entire database in GDB format.  It 
// represents the terrain skin, geometrical features over the skin and a 
// vector network.  The database can be written out to, and read from, a file.
class DT_DLL_gdb DtTerrainDatabase
{
public:
   // default constructor
   DtTerrainDatabase();

   // destructor
   virtual ~DtTerrainDatabase();

private:
   // copy constructor - unimplemented
   DtTerrainDatabase(const DtTerrainDatabase& orig);

   // assignment operator - unimplemented
   DtTerrainDatabase& operator=(const DtTerrainDatabase& orig);

public:
      
   // Initialization function - must be called before ANY other member 
   // function.
   // Override this to function to add new member data types in derived 
   // terrain databases.
   virtual bool init();

   // Sets the terrain intersector to be used for the terrain.  Pass a filled
   // out descriptor for the intersector that is desired.  If you want the intersector
   // to be used after making this call, make initIntersector call right after()
   virtual bool setIntersector(const DtTerrainIntersectorDescriptor* intersectorDescriptor);

   // Sets the terrain intersector directly.  Usually, you should use the 
   // setIntersector() call, and use the descriptor, but if you want to set
   // a custom intersector class, it can be done with this call.
   // \note DtTerrainDatabase takes ownership of this pointer, and will delete
   // the intersector when done with it.
   virtual bool setIntersectorManually(DtTerrainIntersector* intersector);

   // \return A pointer to a intersector descriptor that the DtTerrainDatabase
   // determines to be the best for the current terrain.
   // \note The caller is responsible for deleting this descriptor.
   // \note This does not this this intersector to the terrain.  Call setIntersector()
   // with the return value of this method to change the intersector.
   virtual DtTerrainIntersectorDescriptor* autoChooseIntersector() const;

   // Initializes the terrain polygon intersector.
   // This <b>must</b> be called after all the polygons are added to the
   // terrain and before the terrain is used for intersection calls.
   virtual bool initIntersector();

   // File name associated with database.
   virtual const DtFilename& fileName() const;
   virtual void setFileName(const DtFilename& arg);

   // \return the type of file this database was loaded from.
   // For example, if this terrainDatabase was loaded from a 
   // .gdb file, it will return "gdb".  If it was loaded from a 
   // shape file, it will return "shape".
   virtual DtString dataType() const;
   virtual void setDataType(const DtString& newDataType);

   // \return the version number of the file from which 
   // this database was loaded.  For example, if it was loaded
   // from a gdb file from version 203 it would return 203.  
   // Only non-zero if applicable.
   virtual unsigned int versionNumber() const;
   virtual void setVersionNumber(unsigned int versionNumber);


   //-------------------------------------------------------
   // Coordinate system
   //-------------------------------------------------------

   // Coordinate system type of the database.
   virtual CS_Type coordinateSystemType() const;

   // Coordinate system associated with the database.
   virtual Coordinate_System* coordinateSystem();
   virtual const Coordinate_System* coordinateSystem() const;

   // Sets both the coordinate system and coordinate system type
   // of the database.
   virtual void setCoordinateSystem(Coordinate_System* coordSys);

   // Change the coordinate system from the current coordinate system
   // to the one specified.  Will transform all appropriate elements
   // of the terrain database, including all geometry, into the new CS.
   // Requires that the terrainDatabase currently have a coordinate system.
   // and that the terrain be loaded.
   //
   // If allowReflect is true, allows the coordinate system to be translated to the
   // same coordinate system.  This can be used to project a database to a new location
   // If transformVectorNetwork is true, also attempts to transform vector network, if
   // possible (not all transformations are allowed).
   virtual bool transformCoordinateSystem(Coordinate_System* newCoordSys, bool allowReflect = false, 
      DtVectorNetworkTransformFlag transformVectorNetwork = TransformYes);

   // Applies the specified transform to the terrain database.
   // \return false if the transformation fails for any reason.
   // A side affect of performing the transformation is that all coordinate 
   // system nodes in the terrain will be applied to their children and 
   // removed.  May result in a much larger GDB as new vertices will be created
   // for previously shared vertices.
   virtual bool applyTransform(const DtHomogeneousTransformMatrix& matrix,
                               bool createNewVertices);

   //-------------------------------------------------------
   // Creating and accessing nodes and features
   //-------------------------------------------------------
   // \return a pointer to the group node that encompasses all of
   // the terrain skin.
   virtual DtGroup* terrain();
   virtual const DtGroup* terrain() const;
   virtual bool setTerrain(DtGroup* newTerrain);

   // \return a pointer to the group node that encompasses all of
   // the terrain features.
   virtual DtGroup* features();
   virtual const DtGroup* features() const;
   virtual bool setFeatures(DtGroup* newFeatures);

   // get the number of features in the terrain database.
   virtual int featureCount() const;

   virtual DtVertexManager* vertexManager();
   virtual const DtVertexManager* vertexManager() const;

   virtual DtSurfaceManager* surfaceManager();
   virtual const DtSurfaceManager* surfaceManager() const;

   virtual DtVectorNetwork* vectorNetwork();
   virtual const DtVectorNetwork* vectorNetwork() const;
   virtual void setVectorNetwork(DtVectorNetwork* newVectorNetwork);

   // Create nodes based on the type.  Types are defined in gdbNode.h.  The 
   // terrain database will allocate memory using its memory manager for 
   // efficiency.  
   // Use of this function is highly discouraged in favor of the direct node 
   // creation functions provided below.  
   virtual DtGdbNode* newNode(DtGdbNode::DtGdbNodeType type);

   // Create particular node types.

   // Asks the TerrainDatabase to create a new instance of a polygon node
   // with the specified vertices, surface and parent.  If the parent is 
   // not specified, then it adds the new polygon as a child to the root 
   // terrain group node.
   // If addToStart is specified, it adds the child to the start of
   // the parent (or terrain) node.
   virtual bool createPolygon(const std::vector<DtVertex>& vertices,
                                            DtSurface& surface,
                                            DtGroup* const parent = 0,
                                            bool addToStart = false);

   // Asks the TerrainDatabase to create a new instance of a polygon node
   // with the specified vertexIDs, surfaceID and parent.  If the parent is 
   // not specified, then it adds the new polygon as a child to the root 
   // terrain group node.
   // If addToStart is specified, it adds the child to the start of
   // the parent (or terrain) node.
   virtual bool createPolygon(const std::vector<DtVertexID>& vertexIDList,
                                            DtSurfaceID surfID,       
                                            DtGroup* const parent = 0,
                                            bool addToStart = false);

   // Asks the TerrainDatabase to create a new instance of a triangle node 
   // with the specified vertices, surface and parent.  If the parent is 
   // not specified, then it adds the new group as a child to the root 
   // terrain group node.
   // If addToStart is specified, it adds the child to the start of
   // the parent (or terrain) node.
   virtual DtTriangleIndirect* createTriangle(const DtPoint& vert1, 
                                              const DtPoint& vert2,
                                              const DtPoint& vert3,
                                              const DtSurface& surface,
                                              DtGroup* const parent = 0,
                                              bool addToStart = false);

   // Asks the TerrainDatabase to create a new instance of a triangle node 
   // with the specified vertex IDs, surface ID and parent.  If the parent is 
   // not specified, then it adds the new group as a child to the root
   // terrain group node.
   // If addToStart is specified, it adds the child to the start of
   // the parent (or terrain) node.
   virtual DtTriangleIndirect* createTriangle(const int vert0ID, 
                                              const int vert1ID, 
                                              const int vert2ID,
                                              const DtSurfaceID surfID,
                                              DtGroup* const parent = 0,
                                              bool addToStart = false);

   // If the parent is specified, then it adds the new group as a child to 
   // that parent group.  Otherwise, it just adds it to the top level terrain.
   virtual DtGroup* createGroup(DtGroup* parent = 0) const;

   // Add/remove nodes from a terrain database.  Note that the DtTerrainDatabase
   // will assume responsibility for deleting the memory associated with nodes
   // added to the database (regardless of whether or not the memory was allocated
   // in the client by calling new or by call DtTerrainDatabase::newNode()).
   virtual bool addNode(DtGdbNode *node, DtGroup *parent);
   virtual bool addNodeToStart(DtGdbNode *node, DtGroup *parent);

   virtual bool addTerrainNode(DtGdbNode *node, DtGroup *parent = 0);
   virtual bool addTerrainNodeToStart(DtGdbNode *node, DtGroup *parent = 0);
   virtual bool removeTerrainNode(DtGdbNode *node, DtGdbNode *parent = 0);
   
   virtual bool addFeatureNode(DtGdbNode *node, DtGroup *parent = 0);
   virtual bool addFeatureNodeToStart(DtGdbNode *node, DtGroup *parent = 0);
   virtual bool removeFeatureNode(DtGdbNode *node, DtGdbNode *parent = 0);

   //-------------------------------------------------------
   // Database extent
   //-------------------------------------------------------

   // Forces the entire terrain database to recompute extents.  This includes all
   // child nodes (groups, etc).
   virtual void recomputeExtent() const;

   // \return the extent of the database.
   virtual void getExtent(DtExtent& extent) const;


   //-------------------------------------------------------
   // VectorNetwork Operations
   //-------------------------------------------------------
   virtual bool planarizeVectorNetwork(DtReal tolerance, unsigned int excessiveEdgeCount);

   // Clips the vector network to the specified extent.
   virtual bool clipVectorNetwork(const DtPoint& southWestPoint,
                                  const DtPoint& northEastPoint);

   // Clips the vector network to the correct extent of the terrain data
   virtual bool clipVectorNetwork();

   // Get and set the vector network tool.
   // Allows the user to create their own derived vectorNetworkTool
   // and have the TerrainDatabase use it.
   // @note Deletes any existing vector network tool.
   virtual const DtVectorNetworkTool* vectorNetworkTool() const;
   virtual DtVectorNetworkTool* vectorNetworkTool();
   virtual void setVectorNetworkTool(DtVectorNetworkTool* vectorNetworkTool);


   //-------------------------------------------------------
   // Intersection routines
   //-------------------------------------------------------

   // Functions for finding the height of the terrain at a specified location.
   // Takes a location, in either local (DB) coordinates
   // or a latitude and longitude, and the returns the altitude of the 
   // terrain at the specified location if possible. If no intersection 
   // with terrain was found at the specified location, 0 is returned.
   // 
   // \note
   // 1 - These functions *only* intersect terrain polygons - no 
   //     feature data.  
   //
   // 2 - The intersection is defined to be the topmost intersection with 
   //     the terrain.  Thus if there are multiple levels of terrain polygons,
   //     the highest intersection will be returned as the height. 
   virtual double terrainHeight(const DtPoint& localLocation) const;
   virtual double terrainHeight(const DtVector& localLocation) const;
   virtual double terrainHeight(double lat, double lon) const;

   // Similar to above functions, but return a boolean signifying whether or
   // not an intersection with the terrain was found or not.  If not,
   // the height is set to 0 and false is returned.  If so, true is returned
   // and the height parameter is set to the height of the terrain.
   virtual bool terrainHeight(const DtPoint& localLocation, double& height) const;
   virtual bool terrainHeight(const DtVector& localLocation, double& height) const;
   virtual bool terrainHeight(double lat, double lon, double& height) const;

   // Functions for determining the height of the terrain at a specified location, 
   // AND the soil type of the terrain polygon intersected at that location.
   // 
   // Return Values:
   // These functions return true if an intersection occurred, If so, they also set the
   // height to be the height of the intersection point and the soilType to be the 
   // soilType associated with the intersected polygon.
   //
   // They return false if no intersection occurred.  If so, they also set the height 
   // to 0 and the soilType to "DtSurface::undefinedSoilType"
   //
   // \note
   // 1 - These functions to NOT intersect vector or geometric feature data - they are
   //     intended for finding the "ground" height.
   // 2 - These functions determine the *topmost* intersection with the terrain.  Thus
   //     if there are multiple levels of terrain, the highest intersection point will
   //     be returned as the height. 
   //     In order to get the closest intersection points with terrain (and possibly features
   //     data, use the closestIntersection() functions below.
   virtual bool terrainHeightAndSoilType(const DtVector& localLocation, double& height, DtSoilType& soilType) const;
   virtual bool terrainHeightAndSoilType(double lat, double lon, double& height, DtSoilType& soilType) const;

   // Functions for determining the height of the terrain at a specified location, 
   // AND additional data from the intersection with terrain polygon intersected at that location.
   // 
   // Return Values:
   // These functions return true if an intersection occurred, If so, they also set the
   // height to be the height of the intersection point and the intersection record
   // to the data returned from the intersection with the terrain at that point.
   //
   // They return false if no intersection occurred.  If so, they also set the height 
   // to 0 and the soilType to "DtSurface::undefinedSoilType"
   //
   // @note
   // 1 - These functions to NOT intersect vector or geometric feature data - they are
   //     intended for finding the "ground" height.
   // 2 - These functions determine the *topmost* intersection with the terrain.  Thus
   //     if there are multiple levels of terrain, the highest intersection point will
   //     be returned as the height. 
   //     In order to get the closest intersection points with terrain (and possibly features
   //     data, use the closestIntersection() functions below.
   // 3 - The amount of data returned in the intersection record will be determined by the
   //     Intersection Record Type flag that is passed into the call.
   virtual bool terrainHeightAndIntersection(const DtVector& localLocation, double& height,
      DtChordIntersectionRecord& record,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN) const;

   // Similar to the terrainHeight functions above.
   // Function to determine the closest intersection to a specified location, 
   // either in local (DB) coordinates or in lat/lon.  The closest intersection 
   // is defined as the closest intersection in the down or up direction from
   // location.  Thus if there are multiple terrain levels, it will not necessarily
   // return an intersection with the topmost as the terrainHeight functions do.
   // 
   // \note  Unlike the terrainHeight functions, if the vectorNetworkRecord and 
   // vectorNetworkIntersectionRecord are non-NULL, it will computes an 
   // intersection with the vector network and return the best intersection as 
   // defined by the metrics in the vectorNetworkRecord.
   //
   // Return Values:
   // True if any intersection, vector data or terrain, is found.  
   // If a vector data intersection is found,  then the vecNetworkIntersectionRecord
   // is set appropriately.  
   // If at least one terrain intersection is found, the intersectionPoint 
   // parameter is set to the *closest* intersection point.  
   //
   // \return A boolean indication whether or not an intersection has been found.
   // 
   virtual bool closestIntersection(const DtVector& localLocation, 
                                    DtPoint& intersectionPoint,
                                    DtVectorNetworkRecord* vectorNetworkRecord = 0, 
                                    DtVectorNetworkIntersectionRecord* vecNetworkIntersectionRecord = 0) const;

   // Same as above function, but accepts location in lat/lon.
   virtual bool closestIntersection(double lat, 
                                    double lon, 
                                    DtPoint& intersectionPoint,
                                    DtVectorNetworkRecord* vectorNetworkRecord = 0, 
                                    DtVectorNetworkIntersectionRecord* vecNetworkIntersectionRecord = 0) const;

   // Same as above function, but returns the entire intersection record, 
   // and not just the intersection point.
   virtual bool closestIntersection(const DtVector& localLocation, 
                                    DtChordIntersectionRecord& record,
                                    DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
                                    DtVectorNetworkRecord* vectorDatarecord = 0, 
                                    DtVectorNetworkIntersectionRecord* vectorIntersectionRecord = 0) const;

   // Same as above function, but accepts location in lat/lon.
   virtual bool closestIntersection(double lat, 
                                    double lon, 
                                    DtChordIntersectionRecord& record,
                                    DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
                                    DtVectorNetworkRecord* vectorDatarecord = 0, 
                                    DtVectorNetworkIntersectionRecord* vectorIntersectionRecord = 0) const;

   virtual bool closestIntersection(const DtList& localLocationList, 
                                    DtList& recordList,
                                    int& numIntersections,
                                    DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,      
                                    DtVectorNetworkRecord *vectorDatarecord = 0, 
                                    DtList *vectorList = 0) const;

   // Calculates the first terrain intersection point along a chord given in
   // Database Coordinates.
   virtual bool intersect(
      const DtChord& chord, 
      DtPoint& intersectionPoint, 
      double& intersectionTime,
      DtVectorNetworkRecord *record = 0, 
      DtVectorNetworkIntersectionRecord *intersectionRecord = 0) const;
    
   // Returns complete intersection information about the first terrain
   // intersection point along a chord given in Database Coordinates.
   // The irtFlag value specifies which data should be calculated and returned
   // for each intersection point.
   virtual bool intersect(
      const DtChord& chord, 
      DtChordIntersectionRecord& record,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
      DtVectorNetworkRecord *vectorDatarecord = 0, 
      DtVectorNetworkIntersectionRecord *vectorIntersectionRecord = 0) const;

   // \return True if the specified sphere intersects with any terrain polygons.
   // If irtFlag is IRT_IPOLYGON or higher, a list of all the intersected 
   // polygons is returned inside the record.
   virtual bool intersect(const DtSphere& sphere,
      DtSphereIntersectionRecord& record,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN) const;

   // Computes the list of all intersections of a chord (in Database
   // Coordinates) with the terrain database. Returns a list of
   // DtChordIntersectionRecords. Returns false if no intersections exist.
   // The irtFlag value specifies which data should be calculated and returned
   // for each intersection point.
   // Note that passing an irtFlag value of IRT_NO_DATA will probably never
   // return more than one intersection.
   virtual bool allIntersectsAlongChord(
      const DtChord& chord,
      DtChordIntersectRecordList& intList,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
      DtVectorNetworkRecord *vectorDatarecord = 0, 
      DtList *vectorList = 0) const;
    
   // Returns complete intersection information about the first terrain
   // intersection points along each of a list of DtChords given in Database
   // Coordinates.  The returned record list is a DtList of
   // DtChordIntersectionRecords (one for each chord) each of which must be
   // created and deleted by the caller.  The irtFlag value specifies which
   // data should be calculated and returned for each intersection point.  
   //
   // numTerrainIntersections and numVectorNetworkIntersections are set to the
   // numbers of chords that intersected each respectively.
   // 
   // Returns true if any chord intersected the terrain (or vector network if specified).
   // Returns false otherwise.
   // 
   virtual bool intersectList(
      const DtList& chordList, 
      DtList& recordList,
      int& numTerrainIntersections,
      int& numVectorNetworkIntersections,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
      DtVectorNetworkRecord *vectorDatarecord = 0, 
      DtList *vectorList = 0) const;

   // Computes the list of all intersections of each of a list of chords (in
   // Database Coordinates) with the terrain database. Returns data in a
   // DtList of DtChordIntersectionRecordLists, which the caller is
   // responsible for creating and deleting.  
   // 
   // Parameters: 
   // numTerrainIntersections and numVectorNetworkIntersections are set to the
   // numbers of chords that intersected each respectively.
   // irtFlag  - specifies which data should be calculated and returned 
   //            for each intersection point.  
   //
   // \note  passing an irtFlag value of IRT_NO_DATA will probably never return
   // more than one intersection per chord.
   // 
   // Returns true if any chord intersected the terrain (or vector network if specified).
   // Returns false otherwise.
   virtual bool allIntersectsAlongChordList(
      const DtList& chordList,
      DtList& intListList,         
      int& numTerrainIntersections,
      int& numVectorNetworkIntersections,
      DtGdbNode::DtIntersectRecordType irtFlag = DtGdbNode::IRT_ALL_DATA_TERRAIN,
      DtVectorNetworkRecord *vectorDatarecord = 0, 
      DtList *vectorListList = 0) const;


   // Vector Network Intersection Functions
   // 
   // The following functions all intersect a chord, location,
   // or list thereof with the vector network.  
   // The functions all:
   // Return true if intersection(s) occurred.  
   // Return false otherwise, including when no vector data exists
   // or if input parameters are 0
   // 
   // 
   // Common parameters:
   // irtFlag - All of these functions specify a flag that determines what 
   //           data is requested by the intersection call.  This flag specifies
   //           the type and amount of data returned.
   // vectorRecord - the vectorRecord specifies such things as the metric(s) 
   //                to use and the interest range in searching the vector data.
   // vectorIntersectionRecord - either a single record or list of records, 
   //                            these hold the returned vector intersection records.
   //                            When more than one is returned, they are sorted in
   //                            relevance/closeness order.  
   // For example:  a bridge is more relevant than a river under it.
   // 
   // \note  The user is responsible for allocating and deallocating the 
   // vectorNetworkRecord and vector intersection records.
   // \note  The vectorIntersectionRecords (or lists thereof) must be 
   //          initialized properly if they are going to be reused.
   virtual bool intersectVectorNetwork(
      const DtChord& chord,
      DtGdbNode::DtIntersectRecordType irtFlag,
      DtVectorNetworkRecord* vectorRecord, 
      DtVectorNetworkIntersectionRecord* vectorIntersectionRecord) const;

   // Parameters:
   // vectorList - DtList of the DtVectorNetworkIntersectionRecords
   //              for the chord.
   // \note  The user is responsible for deleting the DtList and
   // all associated items.
   virtual bool intersectVectorNetwork(
      const DtChord& chord,
      DtGdbNode::DtIntersectRecordType irtFlag,
      DtVectorNetworkRecord* vectorRecord, 
      DtList* vectorList) const;

   // 
   // \param vectorList DtList of the best (as defined above) 
   //                   DtVectorNetworkIntersectionRecord
   //                   for each chord in the list.
   // \note  The user is responsible for deleting the DtList and
   // all associated items.
   virtual bool intersectChordsWithVectorNetwork(
      const DtList& chordList,
      DtGdbNode::DtIntersectRecordType irtFlag,
      DtVectorNetworkRecord* vectorRecord, 
      DtList* vectorList) const;

   // Intersections a list of local (DB) locations with the vector network.
   // The single best intersections, not a list, per location are put in the
   // list of vector network intersection records.  
   //
   // \note  The user is responsible for deleting the list of 
   // DtVectorNetworkIntersectionRecords (and the records too).
   virtual bool intersectLocationsOnVectorNetwork(
      const DtList& localLocationList,
      DtGdbNode::DtIntersectRecordType irtFlag,
      DtVectorNetworkRecord* vectorRecord, 
      DtList* vectorList) const;

   // Intersects a list of chords with the vector network.
   // Parameters:  
   // vectorListList - list of DtVectorNetworkIntersectionRecordLists which
   //                  will contain all the DtVectorNetworkIntersectionRecordLists
   //                  associated with each chord.  If the actual recordList is
   //                  empty, then that chord intersected nothing.
   // \note  The user is responsible for allocating and deallocating the list of
   //        DtVectorNetworkIntersectionRecordsLists.
   virtual bool allIntersectionsWithVectorNetworkAlongChordList(
      const DtList& chordList,
      DtGdbNode::DtIntersectRecordType irtFlag,
      DtVectorNetworkRecord* record, 
      DtList* vectorListList) const;


   //-------------------------------------------------------
   // Post-processing
   //-------------------------------------------------------
   virtual void reduce();

   // Eliminates duplicate vertices in all polygons and triangles in the 
   // terrain database.
   // This should save memory if many vertices are shared among polygons
   // and/or triangles, but may take a while to process.
   virtual void eliminateDuplicateVertices(const double tol);

   // Eliminates duplicate surfaces in the terrain database.
   virtual void eliminateDuplicateSurfaces(void);

   // Converts all three-sided polygons nodes to triangle nodes
   // 
   // \note  Does NOT triangulate polygons with more than 3 sides.
   virtual void polygonNodesToTriangleNodes();

   // Attempts to balance the terrain node (tree structure of DtGdbNodes)
   // according to the branching and leafing parameters specified.
   // 
   // \note  Balancing the tree is an extremely computationally expensive
   // operation for all but the simplest terrains.  Use with caution.
   //  
   // KNOWN ISSUE:  balancing the terrain *will* reorder the nodes in the 
   // tree, thus potentially causing drawing issues.  
   virtual void balanceTerrain(unsigned int branching,
                               unsigned int bushiness);
  
   // Returns the type of intersection model being used.  Calls down to intersection model pointer
   // to return type
   virtual int terrainIntersectorType() const;

   //-------------------------------------------------------
   // Miscellaneous
   //-------------------------------------------------------

   // Try to figure out what most common terrain skin poly color is so we
   // can clear to it.
   virtual DtColor mostCommonTerrainSkinColorWithin(const DtExtent& e) const;


   // Creates two terrain triangles formed from the specified extent.  The 
   // altitude of the vertices is determined by the altitude of the left, back, 
   // bottom vertex and the right, front, upper vertex.  These are used as the 
   // SW and NE vertices respectively.  The altitude of the SE vertex matches 
   // the altitude of the SW vertex and the altitude of the NW vertex equals the
   // altitude of the NE vertex.
   // 
   // (NW) *----------* (NE)
   //      |\         |
   //      | \        |
   //      |  \       |
   //      |   \      |
   //      |    \     |
   //      |     \    |
   //      |      \   |
   //      |       \  |
   //      |        \ |
   //      |         \|
   // (SW) *----------* (SE)
   //
   virtual bool setFromExtent(const DtExtent& e);

   virtual bool groundClamp(DtPoint& databaseCoord, float const offset = 0) const;

   // Terrain Modified callback registration.
   virtual void addTerrainModifiedCallback(
      DtTerrainModifiedCallbackFunction cb, void* userData);

   // Terrain Modified callback cancellation.
   virtual void removeTerrainModifiedCallback(
      DtTerrainModifiedCallbackFunction cb, void* userData);

   // Notify the terrain object (and any registered callbacks) that the
   // terrain database has just changed somewhere.
   virtual void terrainWasModified(const DtExtent& changedVolume);

   // \return a pointer to a memory manager class that handles
   // allocations of a group of objects (polygons, groups, grids, 
   // features, etc.)
   virtual DtMemoryManager* memoryMgr() const;

   // transforms to all nodes under them.
   virtual bool collapseNodeTree();

   // Prints in the output console/log file (as verbose) the amount
   // of memory being used by this object
   virtual void printMemoryUsage(DtMemoryUsageDetails details=ShowDetails) const;

   virtual int sizeInBytes() const;

   virtual DtVertex highestPoint();

   virtual DtVertex lowestPoint();

   virtual int totalOfPolygons() const;

   virtual int loadExternalReferences(int level=1);

   DtTerrainIntersector* terrainIntersector() const;

   DtTerrainIntersector* terrainIntersector();

   void setOptionalDataFlag(DtTerrainFileOptionalData, bool onOff);
   int optionalDataFlags() const;

   // While reading a GDB file, reports whether this database will contain
   // optional data
   bool fileHasOptionalData(DtTerrainFileOptionalData optData) const;

public:

   // \return a newly created instance of a DtTerrainDatabase.
   static DtTerrainDatabase* create();

protected:

   bool calculateExtremePoints();  

   bool testInvariant() const;

   // Process the modified callbacks
   virtual void processTerrainModifiedCallbacks(const DtExtent& changedVolume); 

   // Remaps the vertex and surface IDs for all nodes below the current node.
   // Assumes that both parameters are non-null and valid.
   virtual bool remapVertexIDs(DtGdbNode* currentNode, DtVertexID* oldIDToNewIDMap);
   virtual bool remapSurfaceIDs(DtGdbNode* currentNode, DtSurfaceID* oldIDToNewIDMap);

   // Transform all appropriate parts of the terrain database from/to the
   // specified coordinate system.  
   // Requires that the coordinate system be set as specified
   // in the function title.
   virtual bool xformCoordinateSystemTo(Coordinate_System* coordSys, DtVectorNetworkTransformFlag transformVectorNetwork);

   // Should only be used when re-projecting withing the same database to a different zone
   virtual bool xformUTMtoUTM(Coordinate_System* coordSys, DtVectorNetworkTransformFlag transformVectorNetwork);
   
   virtual void xformVectorNetwork(Coordinate_System* newCoordSys, locationConversionFunction conversionFcn, const DtVector* offset=0);
   virtual void xformVertexManager(Coordinate_System* newCoordSys, locationConversionFunction conversionFcn, const DtVector* offset=0);
   virtual void xformTreeNodes(Coordinate_System* newCoordSys, locationConversionFunction conversionFcn, const DtVector* offset=0);

protected:
   DtFilename              myFileName;

   // a group node encompassing all of the nodes that
   // constitute the terrain skin.
   DtGroup*                myTerrain;
   DtTerrainIntersector*   myTerrainIntersector;

   DtVertexManager*        myVertexManager;
   DtSurfaceManager*       mySurfaceManager;

   // holds number of features in terrain database.
   int                     myFeatureCount;
   DtGroup*                myFeatures;
   DtVectorNetwork*        myVectorNetwork;
   DtVectorNetworkTool*    myVectorNetworkTool;

   DtString                myDataType;
   unsigned int            myVersionNumberFromFile;
   unsigned int            myOptionalDataFlagFromFile;

   mutable DtMemoryManager* myMemoryMgr;

   Coordinate_System*      myCoordinateSystem;

   progressCallbackIncrementalProgressFunction* myProgSetValueFcnp;
   DtIntrusiveList myTerrainModifiedCallbacks;

   // Lowest and highest points in the terrain
   DtVertex                myLowestPoint;
   DtVertex                myHighestPoint;
   bool                    myExtremePointsCalculated;

   // Total of polygons in the terrain
   int                     myTotalOfTriangles;
};

inline int DtTerrainDatabase::totalOfPolygons() const
{
   return myTotalOfTriangles;
}

inline DtVertex DtTerrainDatabase::highestPoint() 
{
   if (!myExtremePointsCalculated)
   {
      calculateExtremePoints();
   }
   return myHighestPoint;
}

inline DtVertex DtTerrainDatabase::lowestPoint() 
{
   if (!myExtremePointsCalculated)
   {
      calculateExtremePoints();
   }
   return myLowestPoint;
}

inline DtMemoryManager* DtTerrainDatabase::memoryMgr() const
{
   return myMemoryMgr;
}

inline DtGroup* DtTerrainDatabase::terrain()
{
   return myTerrain; 
}

inline const DtGroup* DtTerrainDatabase::terrain() const
{
   return myTerrain; 
}


inline DtGroup* DtTerrainDatabase::features()
{
   return myFeatures;
}

inline const DtGroup* DtTerrainDatabase::features() const
{
   return myFeatures;
}

inline DtVectorNetwork* DtTerrainDatabase::vectorNetwork()
{
   return myVectorNetwork;
}
inline const DtVectorNetwork* DtTerrainDatabase::vectorNetwork() const
{
   return myVectorNetwork;
}

inline CS_Type DtTerrainDatabase::coordinateSystemType() const
{
   if (myCoordinateSystem)
   {
      return myCoordinateSystem->getCS_Type();
   }
   else
   {
      return CS_NONE;
   }
}

inline Coordinate_System* DtTerrainDatabase::coordinateSystem() 
{
   return myCoordinateSystem;
}
inline const Coordinate_System* DtTerrainDatabase::coordinateSystem() const
{
   return myCoordinateSystem;
}

inline void DtTerrainDatabase::setCoordinateSystem(Coordinate_System* coordSys)
{
   myCoordinateSystem = coordSys;
}

inline int DtTerrainDatabase::featureCount() const
{
   return myFeatureCount;
}

inline void DtTerrainDatabase::setOptionalDataFlag(DtTerrainFileOptionalData flag, bool onOff)
{
   if (onOff)
   {
      myOptionalDataFlagFromFile |= flag;
   }
   else
   {
      myOptionalDataFlagFromFile &= ~flag;
   }
}

// While reading a GDB file, reports whether this database will contain
// optional data
inline bool DtTerrainDatabase::fileHasOptionalData(DtTerrainFileOptionalData optData) const
{
   bool retVal = false;

   if (myOptionalDataFlagFromFile & optData)
   {
      return true;
   }

   return retVal;
}

inline int DtTerrainDatabase::optionalDataFlags() const
{
   return myOptionalDataFlagFromFile;
}

inline DtTerrainIntersector* DtTerrainDatabase::terrainIntersector()
{
   return myTerrainIntersector;
}

inline DtTerrainIntersector* DtTerrainDatabase::terrainIntersector() const
{
   return myTerrainIntersector;
}

#endif