surface.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

#pragma once

#include <vlutil/vlConfig.h>
#include "geometry/geometryDefines.h"
#include "geometry/color.h"
#include <stdio.h>
#include <locale>
#include <string>
#include <vlutil/vlString.h>

class DtTerrainDatabase;
class DtMapSurfaceToRoughness;

// enumeration DtSoilType is used to specify the soiltype
// associated with a surface 
typedef enum
{
   SoftSoil,
   Swamp,
   Mud,
   Forest,
   Grass,
   CultivatedFields,
   Orchards,
   Rock,
   Boulder,
   Sand,
   DirtRoad,
   GravelRoad,
   PavedRoad,
   MuddyRoad,
   AsphaltOrOtherHardSurface,
   USRailRoad,
   EuroRailRoad,
   Flimsy,
   BodyOfWater,
   DryGround,
   UndefinedSoilType
} DtSoilType;

typedef enum
{
   Ocean,
   Lake,
   River, 
   Pond,
   Stream,
   Brook,
   UnspecifiedBodyOfWater   
} DtBodyOfWaterType;

typedef enum
{
   CfBuilding,
   CfTree,
   UnspecifiedCulturalFeature
} DtCulturalFeatureType;

// enumeration DtEnvState is used to specify the prevailing 
// environmental condition over a surface.
typedef enum
{
   Dry,
   Wet,
   Icy,
   Snow,
   UnspecifiedEnvState
} DtEnvState;

enum DtRoughnessSoilType
{
   DtPavedRoad = 0,
   DtHardPacked,
   DtRocks,
   DtSand,
   DtGravel,
   DtShallowWater,   
   DtMuck,
   DtDeepWater
};

class DtSurface;

// DtSurfaceCharacteristicStringMapper class can be installed in the DtSurface as a factory to map soil characteristics to strings
class DT_DLL_geometry DtSurfaceCharacteristicStringMapper
{
public:
   DtSurfaceCharacteristicStringMapper() {};
   virtual ~DtSurfaceCharacteristicStringMapper() {};

   virtual DtString surfaceCharacteristicsString(const DtSurface&) const = 0;
};

// class DtSurface:
//
// DtSurface has two member variables, a color specification and an
// unsigned 32-bit vector that specifies its characteristics - medium 
// the surface is in, soil type, environmental state, etc.
//
// The characteristics vector is laid out as follows (Note: we refer to the 
// most significant bit as bit-0 and the least significant bit as bit-31):
//
//  bit           interpretation when the bit is set
//  ---           ----------------------------------
//
//  medium specification. Initially, we only envision Ground and Water Surface
//  being used. 
//
// bit 0 -- surface is Ground (is equivalent to IsTerrainSkin in 
//                             earlier version)
//     1 -- surface is above ground
//     2 -- surface is under ground
//     3 -- top surface of a body of water
//     4 -- surface is above water
//     5 -- surface is under water
//   6,7 -- unused
// 
//  environment specification; the default is dry, unless otherwise specified.
//
//     8 -- surface is dry
//     9 -- surface is wet
//    10 -- surface is icy
//    11 -- surface is (covered with?) snow
//
//  12-15 -- unspecified
//
// soiltype specification
//    when medium is ground 
//    16 -- improved/unimproved
//    when medium is WaterSurface
//    16 -- deep/shallow
//    when medium is above ground
//     16 -- surface is / is not part of cultural feature 
//  17-23 -- currently unused
//    
//    bits 24-31 are laid out as follows 
//    0000 0000  -- unspecified soil type
//    0000 0001  -- softsoil  (ground/unimproved)
//    0000 0010  -- swamp     (ground/unimproved)
//    0000 0011  -- mud       (ground/unimproved) 
//    0000 0100  -- forest    (ground/unimproved)
//    0000 0101  -- grass                (ground)
//    0000 0110  -- Cultivated Fields    (ground)
//    0000 0111  -- Orchards             (ground)
//    0000 1000  -- Rock      (ground/unimproved)               
//    0000 1001  -- Boulder   (ground/unimproved)
//    0000 1010  -- Sand      (ground/unimproved)
//    0000 1011  -- Dirt Road   (ground/improved)
//    0000 1100  -- Gravel Road (ground/improved)
//    0000 1101  -- paved road  (ground/improved)
//    0000 1110  -- asphalt/other hard surface (ground/improved)
//    0000 1111  -- Railroad US (ground/improved)
//    0001 0000  -- RailRoad Euro (ground/improved)
//    0001 0001  -- flimsy (to map from ctdb soil types)
//    0001 0010  -- muddy road (ground/unimproved)
//    0001 0011  -- dry ground (ground/unimproved)
//
// body of water specification
//
//    bits 24-31 are laid out as follows 
//    0000 0001    -- ocean (water surface)
//    0000 0010    -- lake  (water surface)
//    0000 0011    -- river (water surface)
//    0000 0100    -- pond  (water surface)
//    0000 0101    -- stream(water surface)
//    0000 0110    -- brook (water surface)
//
// cultural feature specification
//
//    bits 24-31 are laid out as follows 
//    0000 0001    -- building (above ground)
//    0000 0010    -- tree     (above ground)

class DT_DLL_geometry DtSurface
{
public:

   // enumeration DtMedium is used to specify where a surface 
   // is situated.
   typedef enum
   {
      Ground,
      AboveGround,
      UnderGround,
      WaterSurface,
      AboveWater,
      UnderWater,
      UnspecifiedMedium
   } DtMedium;

   typedef unsigned int DtCharacteristics;

public:

   // default constructor
   DtSurface();

   // destructor
   virtual ~DtSurface();

   // copy constructor
   DtSurface(const DtSurface& orig);

   // assignment operator
   DtSurface& operator=(const DtSurface& orig);

   // comparison operators
   bool operator==(const DtSurface& orig) const;
   bool operator!=(const DtSurface& orig) const;

   // accessor / mutator functions
   virtual const DtColor& color() const;
   virtual void setColor(const DtColor& c);

   // Set/Get the surface characteristics field.
   virtual void setSurfaceCharacteristics(DtCharacteristics surfChar);
   virtual DtCharacteristics characteristics() const;

   // \return A string that describes the surface characteristic.
   DtString surfaceCharacteristicsString() const;

   // functions to return medium, environmental 
   // state, soil type, body of water type, and cultural feature type. 
   virtual DtMedium whereSurface() const;
   virtual DtEnvState envState() const;
   virtual DtSoilType soilType() const;
   virtual DtBodyOfWaterType bodyOfWaterType() const;
   virtual DtCulturalFeatureType culturalFeatureType() const;

   // functions to return medium, environmental 
   // state, soil type, body of water type, and 
   // cultural feature type as a string. 
   virtual DtString mediumString() const;
   virtual DtString envStateString() const;
   virtual DtString soilTypeString() const;
   virtual DtString bodyOfWaterTypeString() const;
   virtual DtString culturalFeatureTypeString() const;

   virtual DtRoughnessSoilType roughnessSoilType() const;
   virtual DtString roughnessSoilTypeString() const;

   // Set/Get whether the surface is ground.
   virtual void setIsGround(bool onOff); 
   virtual bool isGround() const;


   // Set/Get whether the surface is above ground.
   virtual void setAboveGround(bool onOff); 
   virtual bool aboveGround() const;

   // Set/Get whether the surface is under ground.
   virtual void setUnderGround(bool onOff); 
   virtual bool underGround() const;

   // Set/Get whether the surface is water.
   virtual void setIsWaterSurface(bool onOff); 
   virtual bool isWaterSurface() const;

   // Set/Get whether the surface is above water.
   virtual void setAboveWater(bool onOff); 
   virtual bool aboveWater() const;

   // Set/Get whether the surface is under water.
   virtual void setUnderWater(bool onOff); 
   virtual bool underWater() const;


   // Set/Get whether the surface is dry.
   virtual void setIsDry(bool onOff); 
   virtual bool isDry() const;

   // Set/Get whether the surface is wet.
   virtual void setIsWet(bool onOff); 
   virtual bool isWet() const;

   // Set/Get whether the surface is icy.
   virtual void setIsIcy(bool onOff); 
   virtual bool isIcy() const;
   
   // Set/Get whether the surface is covered by snow.
   virtual void setIsCoveredBySnow(bool onOff); 
   virtual bool isCoveredBySnow() const;

   
   // Set/Get whether the surface is improved. 
   // The medium is required to be Ground.
   virtual void setIsImproved(bool onOff); 
   virtual bool isImproved() const;
   virtual bool isUnimproved() const;

  // Set/Get whether the surface is a body of water
  // and is deep.
   virtual void setIsDeep(bool onOff); 
   virtual bool isDeep() const;
   virtual bool isShallow() const;

  // Set/Get whether the surface is a part of a cultural
  // feature. The medium is required to be AboveGround.
   virtual void setIsCulturalFeature(bool onOff); 
   virtual bool isCulturalFeature() const;
   
   // Accessor/Mutator functions for soil type

   // Set/Get whether the surface is soft soil.
   virtual void setIsSoftSoil(bool onOff); 
   virtual bool isSoftSoil() const;

   // Set/Get whether the surface is swamp.
   virtual void setIsSwamp(bool onOff); 
   virtual bool isSwamp() const;

   // Set/Get whether the surface is mud.
   virtual void setIsMud(bool onOff); 
   virtual bool isMud() const;

   // Set/Get whether the surface is forest.
   virtual void setIsForest(bool onOff); 
   virtual bool isForest() const;

   // Set/Get whether the surface is grass.
   virtual void setIsGrass(bool onOff); 
   virtual bool isGrass() const; 

   // Set/Get whether the surface is grass.
   virtual void setIsCultivatedField(bool onOff); 
   virtual bool isCultivatedField() const; 

   // Set/Get whether the surface is grass.
   virtual void setIsOrchard(bool onOff); 
   virtual bool isOrchard() const; 

   // Set/Get whether the surface is rock.
   virtual void setIsRock(bool onOff); 
   virtual bool isRock() const;

   // Set/Get whether the surface is boulder.
   virtual void setIsBoulder(bool onOff); 
   virtual bool isBoulder() const;

   // Set/Get whether the surface is sand.
   virtual void setIsSand(bool onOff); 
   virtual bool isSand() const;

   // Set/Get whether the surface is dirt road.
   virtual void setIsDirtRoad(bool onOff); 
   virtual bool isDirtRoad() const;

   // Set/Get whether the surface is dry ground.
   virtual void setIsDryGround(bool onOff);
   virtual bool isDryGround() const;

   // Set/Get whether the surface is gravel road.
   virtual void setIsGravelRoad(bool onOff); 
   virtual bool isGravelRoad() const;

   // Set/Get whether the surface is paved road.
   virtual void setIsPavedRoad(bool onOff); 
   virtual bool isPavedRoad() const;

  // Set/Get whether the surface is Muddy road.
   virtual void setIsMuddyRoad(bool onOff); 
   virtual bool isMuddyRoad() const;

   // Set/Get whether the surface is asphalt or other hard
   // surface.
   virtual void setIsHardSurface(bool onOff); 
   virtual bool isHardSurface() const;

   // Set/Get whether the surface is US rail road.
   virtual void setIsUSRailRoad(bool onOff); 
   virtual bool isUSRailRoad() const;

   // Set/Get whether the surface is Euro rail road.
   virtual void setIsEuroRailRoad(bool onOff); 
   virtual bool isEuroRailRoad() const;

   // Set/Get whether the surface is flimsy.
   virtual void setIsFlimsy(bool onOff); 
   virtual bool isFlimsy() const;

  // Set/Get whether the soiltype is undefined.
   virtual void setIsUndefinedSoilType(bool onOff);
   virtual bool isUndefinedSoilType() const;

   // \deprecated Use standard version above.
   // \see setIsUndefinedSoilType
   // \see undefinedSoilType
   virtual void setUndefinedSoilType(bool onOff);
   virtual bool undefinedSoilType() const;

   // Accessor/Mutator functions for body of water type.
 
   // Set/Get whether the surface is ocean.
   virtual void setIsOcean(bool onOff); 
   virtual bool isOcean() const;

   // Set/Get whether the surface is lake.
   virtual void setIsLake(bool onOff); 
   virtual bool isLake() const;

   // Set/Get whether the surface is river.
   virtual void setIsRiver(bool onOff); 
   virtual bool isRiver() const;

   // Set/Get whether the surface is pond.
   virtual void setIsPond(bool onOff); 
   virtual bool isPond() const;

   // Set/Get whether the surface is stream.
   virtual void setIsStream(bool onOff); 
   virtual bool isStream() const;

   // Set/Get whether the surface is brook.
   virtual void setIsBrook(bool onOff); 
   virtual bool isBrook() const;

   // Set/Get whether the surface is part of a tree.
   virtual void setIsTree(bool onOff); 
   virtual bool isTree() const;

   // Set/Get whether the surface is part of a Building.
   virtual void setIsBuilding(bool onOff); 
   virtual bool isBuilding() const;


   // Set characteristics based on an exact match with a string.
   virtual bool characteristicsFromString(std::string characteristicsString, bool warn = true);

   // Set characteristics based on any match with a substring of the specified 
   // characteristics string.  
   // \note This may cause the incorrect surface characteristics to be set, if 
   // the specified string contains more than one of the substrings searched for.
   virtual bool characteristicsFromSubString(std::string characteristicsString, bool warn = true);

   // debugging aid
   virtual void dump() const;

   // \return The maximum color of the surface
   virtual void maxColor(DtColor& theColor);

   // \return The default color associated with the surface type
   DtColor colorForSurfaceType() const;

   // input/output functions
   virtual bool readFrom(FILE* fp);
  // virtual bool readFromOldFormat(FILE* fp, DtTerrainDatabase* ptdb);
   virtual bool writeTo(FILE* fp);

   static DtString soilTypeToString(DtRoughnessSoilType type);
   static DtRoughnessSoilType stringToSoilType(const DtString& string);

public:

   static DtSurface& nullSurface();

   static void setSurfaceToRoughnessMapper(DtMapSurfaceToRoughness&
      surfaceToRoughnessMapper);

   static DtSurfaceCharacteristicStringMapper* surfaceCharacteristicStringMapper();
   static DtSurfaceCharacteristicStringMapper* setSurfaceCharacteristicStringMapper(DtSurfaceCharacteristicStringMapper* mapper);

public:

   static const DtColor theSoftSoilColor;
   static const DtColor theSwampColor;
   static const DtColor theMudColor;
   static const DtColor theForestColor;
   static const DtColor theGrassColor;
   static const DtColor theCultivatedFieldColor;
   static const DtColor theOrchardColor;
   static const DtColor theRockColor;
   static const DtColor theBoulderColor;
   static const DtColor theSandColor;
   static const DtColor theDirtRoadColor;
   static const DtColor theGravelRoadColor;
   static const DtColor thePavedRoadColor;
   static const DtColor theMuddyRoadColor;
   static const DtColor theHardSurfaceColor;
   static const DtColor theRailRoadColor;
   static const DtColor theFlimsySoilColor;
   static const DtColor theDryGroundColor;
   static const DtColor theOceanColor;
   static const DtColor theLakeColor;
   static const DtColor theRiverColor;
   static const DtColor thePondColor;

   static const DtColor theIceColor;
   static const DtColor theTreeColor;
   static const DtColor theBuildingColor;

   //Dted colors
   static const DtColor theDtedGroundCellColor;
   static const DtColor theDtedWaterCellColor;

   static const char DtSoilPavedRoad[];
   static const char DtSoilHardPacked[];
   static const char DtSoilRocks[];
   static const char DtSoilSand[];
   static const char DtSoilGravel[];
   static const char DtSoilShallowWater[];
   static const char DtSoilMuck[];
   static const char DtSoilDeepWater[];

protected:

   static const DtCharacteristics theSoftSoilBitMask;
   static const DtCharacteristics theSoftSoilComparator;

   static const DtCharacteristics theSwampBitMask;
   static const DtCharacteristics theSwampComparator;

   static const DtCharacteristics theMudBitMask;
   static const DtCharacteristics theMudComparator;

   static const DtCharacteristics theForestBitMask;
   static const DtCharacteristics theForestComparator;

   static const DtCharacteristics theGrassBitMask;
   static const DtCharacteristics theGrassComparator;

   static const DtCharacteristics theCultivatedFieldBitMask;
   static const DtCharacteristics theCultivatedFieldComparator;

   static const DtCharacteristics theOrchardBitMask;
   static const DtCharacteristics theOrchardComparator;

   static const DtCharacteristics theRockBitMask;
   static const DtCharacteristics theRockComparator;

   static const DtCharacteristics theBoulderBitMask;
   static const DtCharacteristics theBoulderComparator;

   static const DtCharacteristics theSandBitMask;
   static const DtCharacteristics theSandComparator;

   static const DtCharacteristics theDirtRoadBitMask;
   static const DtCharacteristics theDirtRoadComparator;

   static const DtCharacteristics theGravelRoadBitMask;
   static const DtCharacteristics theGravelRoadComparator;

   static const DtCharacteristics thePavedRoadBitMask;
   static const DtCharacteristics thePavedRoadComparator;

   static const DtCharacteristics theDryGroundBitMask;
   static const DtCharacteristics theDryGroundComparator;

   static const DtCharacteristics theMuddyRoadBitMask;
   static const DtCharacteristics theMuddyRoadComparator;

   static const DtCharacteristics theHardSurfaceBitMask;
   static const DtCharacteristics theHardSurfaceComparator;

   static const DtCharacteristics theUSRailRoadBitMask;
   static const DtCharacteristics theUSRailRoadComparator;

   static const DtCharacteristics theEuroRailRoadBitMask;
   static const DtCharacteristics theEuroRailRoadComparator;

   static const DtCharacteristics theFlimsySoilBitMask;
   static const DtCharacteristics theFlimsySoilComparator;

   static const DtCharacteristics theOceanBitMask;
   static const DtCharacteristics theOceanComparator;

   static const DtCharacteristics theLakeBitMask;
   static const DtCharacteristics theLakeComparator;

   static const DtCharacteristics theRiverBitMask;
   static const DtCharacteristics theRiverComparator;

   static const DtCharacteristics thePondBitMask;
   static const DtCharacteristics thePondComparator;

   static const DtCharacteristics theStreamBitMask;
   static const DtCharacteristics theStreamComparator;
 
   static const DtCharacteristics theBrookBitMask;
   static const DtCharacteristics theBrookComparator;

   static const DtCharacteristics theDeepWaterBitMask;
   static const DtCharacteristics theDeepWaterComparator;

   static const DtCharacteristics theBuildingBitMask;
   static const DtCharacteristics theBuildingComparator;

   static const DtCharacteristics theTreeBitMask;
   static const DtCharacteristics theTreeComparator;

protected:
   // Custom function to lower the case of a string.  Necessary since the tolower
   // function (from locale) needs to have a locale specified.  Defaults to using 
   // the classic C locale, which is for ASCII.
   std::string customToLower(const std::string& stringToConvert, const std::locale loc = std::locale::classic()) const;

   // Removes any white spaces on the right side of the string
   std::string trimString(const std::string& strToTrim);

   virtual void setRoughnessSoilType();

   DtCharacteristics myCharacteristics;
   DtColor                  myColor;
   DtRoughnessSoilType      myRoughness;
   static DtMapSurfaceToRoughness* theMapSurfaceToRoughness;   
};

inline const DtColor& DtSurface::color() const
{
   return myColor;
}

inline void DtSurface::setColor(const DtColor& c)
{
   myColor = c;
}

inline DtSurface::DtCharacteristics DtSurface::characteristics() const
{
   return myCharacteristics;
}

inline void DtSurface::setSurfaceCharacteristics(DtSurface::DtCharacteristics surfChar)
{
   myCharacteristics = surfChar;
   setRoughnessSoilType();
}