ssEnvironment.h

Go to the documentation of this file.

// Copyright JRM Enterprises, Inc. 2004
// All rights reserved.
//
// This code is the intellectual property of JRM Enterprises, Inc.
// It may not be used or released as source or compiled binary form
// without the prior written consent of JRM Enterprises, Inc.
//
// Original Author:     Eric Olson     Date: May 2004

#ifndef _ssEnvironment_
#define _ssEnvironment_

#include "ssdllexport.h"

#include "ssSensor.h"
#include "ssAtmosphericTable.h"
#include "SSModRadStruct.h"


class SigSimRT;

// ssEnvironment
class SIGSIMRT_API ssEnvironment
{
public:

   enum ModtranAtmModel
   {
      Tropical = 1,
      MidLatitudeSummer = 2,
      MidLatitudeWinter = 3,
      SubArcticSummer = 4,
      SubArcticWinter = 5,
      USStandard = 6,
      UserDefinedAtm = 7,
   };

   enum ModtranHazeModel
   {
      NoAerosol = -1, // but might have clouds
      NoHaze = 0,    // no aerosol or clouds
      Rural_23km = 1,
      Rural_5km = 2,
      NavyMaritime = 3,
      Maritime_32km = 4,
      Urban_5km = 5,
      Tropospheric_50km = 6,
      UserDefine = 7,   // uses the atm state file for definition
      Fog_200m = 8,
      Fog_500m = 9,
      Desert = 10,
   };

   enum ModtranSeason
   {
      AutoSelect = 0,    // use summer for models 0,1,2,4,6,7
      Summer = 1,
      Winter = 2,
   };

   enum ModtranClouds
   {
      NoClouds = 0,
      Cumulus = 1,
      Altostratus = 2,
      Stratus = 3,
      Stratocumulus = 4,
      Nimbostratus = 5,
      Stratus_Drizzle = 6,
      Nimbostratus_Light = 7,
      Nimbostratus_Moderate = 8,
      Cumulus_Heavy = 9,
      Cumulus_Extreme = 10,
      Standard_Cirrus = 18,
      Subvisual_Cirrus = 19,
   };

   typedef struct
   {
      int numSensors;     
      int numRangeBins;   
      float* ranges;      
   } VisibilityRangeStruct;


   // ssEnvironment
   ssEnvironment();

   //ssEnvironment
   ~ssEnvironment();


   //setLUTSizeDefaults
   //
   void setLUTSizeDefaults();


   //updateAtmospherics
   bool updateAtmospherics(ssSensor* sensor, double sensorAltitude = 1.0, bool checkReload = true, bool setLUTSize = true);


   // ssEnvironment::getLightSourceData
   //
   // description: gets the maxRadiance-scaled environmental pseudoradiances (irradiance/PI/maxRadiance) for a particular sensor
   //
   // parameter: sensor - the sensor
   //          Nx - Wavelengths
   //          Ny - Object Altitudes
   //          Nc - Components  - fixed at 5 currently : {Ambient, Mie coef, Specular/Direct, Upwelling, Downwelling}
   //
   // Index as:   (y * Nx + x) * Nc + c
   //
   // return: float pointer to source irradiance data
   //
    float *getLightSourceData(ssSensor *sensor, unsigned int &Nx, unsigned int &Ny, unsigned int &Nc);

   // getSensorAtmosphericTablePointer
   ssAtmosphericTable* getSensorAtmosphericTablePointer(ssSensor* sensor);

   //*getSensorAtmosphericData
   float* getSensorAtmosphericData(ssSensor* sensor,
        unsigned int &Nx, unsigned int &Ny, unsigned int &Nz, 
        unsigned int &bins, unsigned int &comps);

   //getSunDiskRadiance
   float* getSunDiskRadiance(ssSensor* sensor, unsigned int& bins);

   //getMoonDiskRadiance
   float* getMoonDiskRadiance(ssSensor* sensor, unsigned int& bins);

   //getManMadeLightData
   float* getManMadeLightData(ssSensor* sensor,
      unsigned int& numLights, unsigned int& bins);

   //getManMadeLightData
   MANMADE_LIGHTSOURCE_TABLE* getManMadeLightProperties(unsigned int& numLights);

   //getNumberManMadeLights
   int getNumberManMadeLights();

   //getManMadeLightRadiance
   double getManMadeLightRadiance(ssSensor* sensor, int lightNum);


   //setDate
   void setDate(unsigned int day, unsigned int month, unsigned int year);

   //getDate
   void getDate(unsigned int& day, unsigned int& month, unsigned int& year);

   //setTimeOfDay
   void setTimeOfDay(double tod);

   //getTimeOfDay
   double getTimeOfDay();

   //getJRMTimeOfDay
   JRMTIME getJRMTimeOfDay();

   //setJRMTimeOfDay
   void setJRMTimeOfDay(JRMTIME time);

   //setSimulationTime
   void setSimulationTime(double simTime);

   //getSimulationTime
   double getSimulationTime(void);

   //getSensorAltitudeIndex
   int getSensorAltitudeIndex(double alt);

   //setAtmosphereStateFile
   void setAtmosphereStateFile(const char* name);

   //getAtmosphereStateFile
   char* getAtmosphereStateFile();

   //getAtmosphericTableChanged
   bool getAtmosphericTableChanged() const
   {
      return m_AtmTableChanged;
   }

   //setAtmosphericTableChanged
   void setAtmosphericTableChanged(bool state)
   {
      m_AtmTableChanged = state;
   }

   //setNightSkyTableFile
   void setNightSkyTableFile(char* name);

   //getNightSkyTableFile
   char* getNightSkyTableFile();

   //setBathymetryTableFile
   void setBathymetryTableFile(char* name);

   //getBathymetryTableFile
   char* getBathymetryTableFile();

   //setMMLSTableFile
   void setMMLSTableFile(char* name);

   //getMMLSTableFile
   char* getMMLSTableFile();

   //setAirGroundTempCalcMode
   void setAirGroundTempCalcMode(bool Calc_Ta_Tback);

   //getAirGroundTempCalcMode
   bool getAirGroundTempCalcMode();

   //setMaxDiurnalTemperature
   void setMaxDiurnalTemperature(double tempMax);

   //setMinDiurnalTemperature
   void setMinDiurnalTemperature(double tempMin);

   //getMaxDiurnalTemperature
   double getMaxDiurnalTemperature();

   //getMinDiurnalTemperature
   double getMinDiurnalTemperature();

   //setCurrentAirTemperature
   void setCurrentAirTemperature(double Ta);

   //getCurrentAirTemperature
   double getCurrentAirTemperature();

   //setAirModelOption
   void setAirModelOption(int air_model_option);

   //setUserDefinedAirTemperatures
   int   setUserDefinedAirTemperatures(int numberIntervals, double* airTemperature);

   //setUserDefinedAirTemperatures
   int   setUserDefinedAirTemperatures(int numberIntervals, double* airTemperature, double* timeOfDays);

   // isUserDefinedAirTemperature
   bool isUserDefinedAirTemperature();

   // disableUserDefinedAirTemperature
   void disableUserDefinedAirTemperature();

   //setModtranAtmModel
   void setModtranAtmModel(const ModtranAtmModel model);

   //getModtranAtmModel
   ModtranAtmModel getModtranAtmModel();

   //setModtranHazeModel
   void setModtranHazeModel(const ModtranHazeModel haze);

   //getModtranHazeModel
   ModtranHazeModel getModtranHazeModel();

   //setModtranAirMassCharacter
   void setModtranAirMassCharacter(int coastalinfluence);

   //getModtranAirMassCharacter
   int getModtranAirMassCharacter();

   //setModtranSeason
   void setModtranSeason(const ModtranSeason season);

   //getModtranSeason
   ModtranSeason getModtranSeason();

   //setModtranVisibility
   void setModtranVisibility(double vis);

   //getModtranVisibility
   double getModtranVisibility();

   //setWindVelocity
   void setWindVelocity(double windVelocity);

   //getWindVelocity
   double getWindVelocity();

   //setWindDirection
   void setWindDirection(double EofN);

   //getWindDirection
   double getWindDirection();

   //setRelativeHumidity
   void setRelativeHumidity(double relative_humidity);

   //getRelativeHumidity
   double getRelativeHumidity();

   //setGroundTemperature
   void setGroundTemperature(double Tbackground);

   //getGroundTemperature
   double getGroundTemperature();

   //setAtmosphericPressure
   void setAtmosphericPressure(double Pressure);

   //getAtmosphericPressure
   double getAtmosphericPressure();

   //setModtranClouds
   void setModtranClouds(const ModtranClouds clouds);

   //setCloudParameters
   void setCloudParameters(int numCloudLayers, float thickness, float baseAltitude, float extinctionScale, float waterDensity);

   //setCloudLayerParameters
   void setCloudLayerParameters(int layer, float altitude, float waterDensity, float iceDensity, float rainRate);
    //setCloudLayerParameters
   void setCloudLayerParameters(int layer, float altitude, float visibility);
   //getModtranClouds
   ModtranClouds getModtranClouds();

   //getCloudParameters
   void getCloudParameters(int& numCloudLayers, float& thickness, float& baseAltitude, float& extinctionScale, float& waterDensity);

   //getCloudLayerParameters
   void getCloudLayerParameters(int layer, float& altitude, float& waterDensity, float& iceDensity, float& rainRate);

   //setGeodeticOrigin
   void setGeodeticOrigin(double lat, double lon);

   //getGeodeticOrigin
   void getGeodeticOrigin(double& lat, double& lon);


   //setUpdateTime
   void setUpdateTime();


   //getUpdateTime
   JRMTIME getUpdateTime();

   //isDayTime 
   bool isDayTime();

   //setUseSun
   void setUseSun(bool flag);

   //isUsingSun
   bool isUsingSun();

   //setUseBothSunMoon
   void setUseBothSunMoon(bool flag);

   //getUseBothSunMoon
   bool getUseBothSunMoon();

   // getNightTimeConstant
   double getNightTimeConstant();

   // getSkyAngleFactor
   double getSkyAngleFactor();

   //getSunMaxPosition 
   void getSunMaxPosition(double& i, double& j, double& k);

   // getSunPlaneVectorENU
   void getSunPlaneVectorENU(double& i, double& j, double& k);

   //getSunPosition 
   void getSunPosition(double& i, double& j, double& k);

   //getMoonPosition 
   void getMoonPosition(double& i, double& j, double& k);

   //getSunMoonPosition 
   bool getSunMoonPosition(double& i, double& j, double& k);

   //getMoonPhase
   double getMoonPhase();

   //getStarPosition
   void getStarPosition(int starNum, double& i, double& j, double& k,
      double& temperature, double& attenuation);

   //getStarPositionRadiance
   void getStarPositionRadiance(ssSensor* sensor, int starNum, double& i, double& j, double& k, double& radiance);

   // initMaxStarParameters
   void initMaxStarParameters(ssSensor* sensor, double maxSize = 5.0, int starNum = -1);

   // ssEnvironment::getMaxStarRadiance
   double getMaxStarRadiance();

   // ssEnvironment::getStarPositionRadiance
   //
   void getStarPositionRadiance(ssSensor* sensor, int starNum, double& i, double& j, double& k, double& radiance, double& size);

   //ssEnvironment
   unsigned int getNumberStars();

   //getNumberWavelengths
   unsigned int getNumberWavelengths();

   //*getWavelengthsArray
   double* getWavelengthsArray();

   //getJulianDate
   long getJulianDate();

   //setUpdateBuffer
   void setUpdateBuffer(double hours);

   //getUpdateBuffer
   double getUpdateBuffer();

   //setSpectralMode
   void setSpectralMode(bool flag);

   //isAnySpectralMode
   bool isSpectralMode();

   //setAtmEnable
   void setAtmEnable(bool flag);

   //isAtmEnable
   bool isAtmEnable();

   //setScatterEnable
   void setScatterEnable(bool flag);

   //isScatterEnable
   bool isScatterEnable();

   //setMultiScatterEnable
   void setMultiScatterEnable(bool flag);

   //isMultiScatterEnable
   bool isMultiScatterEnable();

   //setRoundEarth
   void setRoundEarth(bool flag);

   //isRoundEarth
   bool isRoundEarth();

   //setUseODLimit
   void setUseODLimit(bool flag);

   //getUseODLimit
   bool getUseODLimit();

   //setAtmExtinctionScale
   void setAtmExtinctionScale(float scale);

   //getAtmExtinctionScale
   float getAtmExtinctionScale();

   //setAtmAmbientLightScale
   void setAtmAmbientLightScale(float scale);

   //getAtmAmbientLightScale
   float getAtmAmbientLightScale();

   //setAtmSkyScale
   void setAtmSkyScale(float scale);

   //getAtmSkyScale
   float getAtmSkyScale();

   //setNumberRanges
   void setNumberRanges(unsigned int ranges);

   //getNumberRanges
   unsigned int getNumberRanges();

   //setNumberObjectAltitudes
   void setNumberObjectAltitudes(unsigned int alts);

   //getNumberObjectAltitudes
   unsigned int getNumberObjectAltitudes();

   //getNumberObjectAngles
   unsigned getNumberObjectAngles();

   //setNumberObjectAngles
   void setNumberObjectAngles(unsigned int angles);


   //getNumberScatAngles
   unsigned int getNumberScatAngles();

   //setNumberScatAngles
   void setNumberScatAngles(unsigned int angles);

   //setNumberSensorAltitudes
   void setNumberSensorAltitudes(unsigned int alts);

   //getNumberSensorAltitudes
   unsigned int getNumberSensorAltitudes();

   //setMaxRange
   void setMaxRange(double range);

   //getMaxRange
   double getMaxRange();

   //setPowRange
   void setPowRange(double p);

   //getPowRange
   double getPowRange();

   //setPowDensity
   void setPowDensity(double p);

   //getPowDensity
   double getPowDensity();


   //setMaxAltitude
   void setMaxAltitude(double maximum);

   //getMaxAltitude
   double getMaxAltitude();

   //setPowAltitude
   void setPowAltitude(double p);

   //getPowAltitude
   double getPowAltitude();

   //getRangeScale
   double getRangeScale();

   //getObjectAltitudeScale
   double getObjectAltitudeScale();

   //getRainRate
   double getRainRate();

   //setRainRate
   void setRainRate(double rate);

   //getRainTemp
   double getRainTemp();

   //setRainTemp
   void setRainTemp(double temp);

   //getSensorAltitudeScale
   double getSensorAltitudeScale();

   //setUpdateInterval
   void setUpdateInterval(double deltaHours);

   //getUpdateInterval
   double getUpdateInterval();

   //setLUTPrecomputationRange
   void setLUTPrecomputationRange(bool lut_precomp_enable, double lut_tod_start, double lut_tod_end, double lut_tod_interval = 0.25);

   //getLUTPrecomputationRange
   void getLUTPrecomputationRange(bool& lut_precomp_enable, double& lut_tod_start, double& lut_tod_end, double& lut_tod_interval);


   /* -------------------------------------  BEGIN MODIFIED BRUNETON & NEYRET ATM LUT CODE ------------------------------ */

   // getSensorPolarATMLUTData
   // return: float pointers to sensor atmospheric data
   //
   void getSensorPolarATMLUTData(ssSensor* sensor, unsigned int& numSensAlts, unsigned int& numObjAngles, unsigned int& numScatAngles, unsigned int& numBins,
      float** xmitData, float** pradData, float** sradData, float** mradData);

   // getSensorMaxOptDepth
   void getSensorMaxOptDepth(ssSensor* sensor, unsigned int& numBins, float** maxOptDepth);

   // isMBNATM
   bool isMBNATM(ssSensor* sensor);

   //setMBNATM
   void setMBNATM(bool onoff);

   //getMBNATM
   bool getMBNATM();

   /* -------------------------------------  END MODIFIED BRUNETON & NEYRET ATM LUT CODE ------------------------------ */

   //setOriginalCode
   void setOriginalCode(bool onoff);

   //getOriginalCode
   bool getOriginalCode();

   //setModRad
   void setModRad(bool onoff);

   //getModRad
   bool getModRad();

#ifdef _LOS_Prop_

   //getTransmission
   void getTransmission(ssSensor* sensor,
      double sensorGeoC[3], double sensorOrient[3], double entityGeoC[3],
      double** transmission, double** pathRadiance, double** scatterRadiance);

   //getTransmission
   void getTransmission(ssSensor* sensor, double objectAlt, double objectRange,
      double** transmission, double** pathRadiance, double** scatterRadiance);

   //saveRangeTransCompare
   double saveRangeTransCompare(ssSensor* sensor, double objectAlt);
#endif // _LOS_Prop_

   // ssEnvironment::getAtmTableTransmission
   //
   // description: Gets the transmission properties of a LOS between a sensor and an object from the 
   //       sensor's atmospheric table.
   //
   // param: sensor - the sensor
   //      sensorAlt - altitude of the sensor [m]
   //        objectAlt - altitude of the object [m]
   //      objectRange - ground range [m] between sensor and object
   //
   // returns: transmission - passband transmission from sensor to object
   //      pathRadiance - passband path radiance from sensor to object
   //
   void getAtmTableTransmission(ssSensor* sensor, double sensorAlt, double objectAlt, double objectRange, double& transmission, double& pathRadiance);

   // getLightSourceTableIrradiances
   //
   void getLightSourceTableIrradiances(ssSensor* sensor, double objectAlt,
      double& ambientIrradiance, double& directIrradiance);

   //setGenerateFastDiurnalCache
   void setGenerateFastDiurnalCache(bool flag);

   //isGenerateFastDiurnalCache
   bool isGenerateFastDiurnalCache();

   //setWaterVaporPartialPressureScaleFactor
   void  setWaterVaporPartialPressureScaleFactor(double wvpp);

   //getWaterVaporPartialPressureForCurrentTimeOfDay
   double getWaterVaporPartialPressureForCurrentTimeOfDay();

   //findClosestDefaultWaterVaporPartialPressure
   double findClosestDefaultWaterVaporPartialPressure(char* sigsim_data_dir, double wvpp);


   //setSeasonBasedOnLocation
   void setSeasonBasedOnLocation();

   //useModcardParamsToGenerateCorrespondingATMState
   int useModcardParamsToGenerateCorrespondingATMState(char* sigsim_data_dir, char* sigsim_cache_dir, char* outfilebasename);


   // getEnvIrradianceRatios
   bool getEnvIrradianceRatios(double& EsundirRatio, double& EsundifRatio, double& EskyRatio, double& EearthRatio);

   // getEnvIrradianceAverageRatios
   bool getEnvIrradianceAverageRatios(double& EsundirAveRatio, double& EsundifAveRatio, double& EskyAveRatio, double& EearthAveRatio);

   //*getMetinPtr
   METIN* getMetinPtr();

   //isAtmosphereDirty
   bool isAtmosphereDirty();

   //setAtmosphereDirty
   void setAtmosphereDirty();

   //deferAtmosphericUpdates
   void deferAtmosphericUpdates(bool flag);

   //isAtmosphericUpdateDeferred
   bool isAtmosphericUpdateDeferred();

   //setUpdateAtmospherics
   void setUpdateAtmospherics(bool flag);

   //isAtmosphericsUpdated
   bool isAtmosphericsUpdated();

   //setConstEratio
   void setConstEratio(bool flag);

   //isConstEratio
   bool isConstEratio();

   //getRefractionProfile
   void getRefractionProfile(ssSensor* sensor, double& n0, double& h0, ellipsoid& E);

   // setVisibilityRangeEnable
   void setVisibilityRangeEnable(bool state);

    //initVisibilityRange
   void initVisibilityRange(SigSimRT* ss);

    //releaseVisibilityRange
   void releaseVisibilityRange();

   // getVisibilityRange
   bool getVisibilityRange(float visibleRange, ssSensor* sensor, float& sensorRange,
      float cloudCoverage, bool isGroundFog, float& visiblityEmissionFactor);

   // getCloudPropertiesProto
   void getCloudProperties(ssSensor* sensor, float& humidity, float& extinction, float& lightResponse,
      float& ambientLightResponse, float& secondaryLightResponse, float& density);

   //getMeanWaveHeight
   /* Translates wind speed into average wave height. */
   double getMeanWaveHeight();

   //computeSkyAngleExponent
   /*    // Returns the exponent n in the fitted function Lsky(theta) = Lsky(zenith) + (Lsky(horizon)-Lsky(zenith) * pow((Range(theta)/Range(horizon)), n). */
   double computeSkyAngleExponent();

   // sigsimUpdateEnvironment
   //
   // description: Direct call to SigSim's UpdateEnvironment routine.
   //
   // parameter: 
   //
   // return: SigSim UpdateEnvironment error codes.
   //
   int sigsimUpdateEnvironment(double alt_m);

   //queryIrradianceCache
   bool queryIrradianceCache(char* cacheDirectory);

   //saveIrradianceCache
   void saveIrradianceCache(char* cacheDirectory);

   //int TestRunModTranPath();   // TEMPORARY!

   //isAtmosphereLutForSensorDirty
   bool isAtmosphereLutForSensorDirty(ssSensor* sensor) const;

private:
   void interpolateFour(double fraction[2], double input1[4], double input2[4], double* output1, double* output2);
   void interpolateEight(double fraction[3], double input1[8], double input2[8], double* output1, double* output2);




   //setAutoLightLevel
   void setAutoLightLevel(ssSensor* sensor);

    //generateDiurnalCache
   bool generateDiurnalCache();

   //loadDefaults
   void loadDefaults();

   //insertSensorAtmosphericTable
   bool insertSensorAtmosphericTable(ssSensor* sensor);

   //setJulianDate
   void setJulianDate(long julian);

   //timeHasChangedSinceLastUpdate
   double timeHasChangedSinceLastUpdate();

    //clrAtmosphereDirty
   void clrAtmosphereDirty();


   //setAtmosphereLutsDirty
   void setAtmosphereLutsDirty();

   //checkSensorTimesChanged
   void checkSensorTimesChanged(bool explicitTimeChanged);


   unsigned int m_day;
   unsigned int m_month;
   unsigned int m_year;

   JRMTIME m_timeOfDay;

   JRMTIME m_lastUpdate;

   double m_simTime; // Simulation time (from start), currently independent of physical time.

   bool m_AtmTableChanged;

   double m_updateBuffer;

   char m_nightSkyTableFile[SIGSIM_STRING_SIZE];

   char m_mmlsTableFile[SIGSIM_STRING_SIZE];

   char m_bathymetryTableFile[SIGSIM_STRING_SIZE];

   char m_atmosphereStateFile[SIGSIM_STRING_SIZE];

   double m_maxAltitude;
   double m_powAltitude; // [1] 

   double m_maxRange;
   double m_powRange;     // [1] 

   double m_powDensity; // [1]

   // SigSim Structures

   METIN* m_metinPtr;

   bool m_useSun;
   bool m_useBothSunMoon;
   bool m_spectralMode;
   bool m_atmEnable;
   bool m_scatterEnable;
   bool m_multiScatterEnable;
   bool m_roundEarth;
   bool m_useODLimit;
   bool m_MBNATM;
   bool m_constEratio;

   bool m_OriginalCode; // Reproduces code as of Sept. 2012
   bool m_ModRad;       // Use Modtran/Radtran directly to fill ENV/ATM LUTs

   bool m_dirty;
   bool m_geodeticLocationDirty;

   bool m_generateFastDiurnalCache;

   bool m_lut_precomp_enable;
   double m_lut_tod_start, m_lut_tod_end, m_lut_tod_interval;

   unsigned int m_numberRanges;
   unsigned int m_numObjectAltitudes;
   unsigned int m_numObjectAngles;
   unsigned int m_numSensorAltitudes;
   unsigned int m_numScatAngles;
   float m_atmExtinctionScale;
   float m_atmAmbientLightScale;
   float m_atmSkyScale;

   bool m_isUserDefinedAirTemperature;

   //indicates whether to defer atmospheric updates, or the old way without deferring
   bool m_deferAtmosphericUpdates;
   //flag indicates when the atmospherics is updated.
   bool m_updateAtmospherics;

   friend class SigSimRT;
   friend class ssMaterialSet;

   bool m_visibilityRangeEnable;
   VisibilityRangeStruct m_visibilityRange;

   double m_maxStarRadiance;
   double m_maxStarSize;

   struct Implementation;
   Implementation* m_impl;

};
#endif // _ssEnvironment_