DEIMOS
Earth Observation Mission CFI Software
Pointing Software User Manual		 ESA
Public Member Functions | Protected Member Functions

EECFI::DemId Class Reference

Class for the DEM parameters. More...

Inheritance diagram for EECFI::DemId:
EECFI::CfiId EECFI::CfiClass

List of all members.

Public Member Functions

 DemId ()
 Default constructor.
 DemId (const DemId &other)
virtual ~DemId () EXCEPT
 Class destructor.
void init (long mode, long model, const std::string &demFile)
 Initialise the DEM parameters.
double compute (const ModelId &modelId, double lon, double lat) const
 Compute altitude over the sea level for a point in the Earth.
SatId satId () const
 Get satellite id.
DemConfFile getData () const
 Get DEM parameters.
DemInfo getInfo (const ModelId &modelId, double lon, double lat) const
 Get DEM source data.
void configure (const DemIdConfig &config)
 Configure DEM cache.
double getCellValue (long row, long column) const
 Get a DEM value for the given global row/column.
void getCellGeod (long row, long column, double &lat, double &lon) const
 Get longitude/latitude corresponding to the the DEM point with the given global row/column.
DemId & operator= (const DemId &other)

Protected Member Functions

void eraseObject ()
 Erase object and free memory.

Detailed Description

Class for the DEM parameters.

Constructor & Destructor Documentation

EECFI::DemId::DemId (  ) 

Default constructor.

EECFI::DemId::DemId ( const DemId &  other  ) 

Copy constructor.

Parameters:
other The DemId to copy from
EECFI::DemId::~DemId (  )  [virtual]

Class destructor.

References eraseObject().

Member Function Documentation

double EECFI::DemId::compute ( const ModelId &  modelId,
double  lon,
double  lat 
) const

Compute altitude over the sea level for a point in the Earth.

Parameters:
modelId Model id.
lon Longitude.
lat Latitude.
Returns:
Altitude corresponding to lon and lat.

References EECFI::CfiClass::throwWarn.

void EECFI::DemId::configure ( const DemIdConfig &  config  ) 

Configure DEM cache.

Parameters:
config DEM ID configuration. The "command" parameter in the "config" object has to be compatible with the DEM cache type in the DemId object: XPCFI_PRELOAD_CACHE cannot be used with the command XPCFI_SET_MAX_SIZE and XPCFI_FIFO_CACHE cannot be used with the command XPCFI_LOAD_TILE_SET.

References EECFI::DemIdConfig::area, EECFI::DemIdConfig::command, EECFI::LatLonArea::latMax, EECFI::LatLonArea::latMin, EECFI::LatLonArea::lonMax, EECFI::LatLonArea::lonMin, EECFI::DemIdConfig::maxCacheSize, and EECFI::CfiClass::throwWarn.

void EECFI::DemId::eraseObject (  )  [protected]

Erase object and free memory.

References EECFI::CfiId::status(), EECFI::CfiId::subtractInstance(), and EECFI::CfiClass::throwWarn.

Referenced by operator=(), and ~DemId().

void EECFI::DemId::getCellGeod ( long  row,
long  column,
double &  lat,
double &  lon 
) const

Get longitude/latitude corresponding to the the DEM point with the given global row/column.

The DemId::getCellGeod method converts row and column indexes to associated latitude and longitude according to DEM caracteristics.

Parameters:
row The index of the row to be converted.
column The index of the column to be converted.
lon Longitude [deg].
lat Latitude [deg].

References EECFI::CfiClass::throwWarn.

double EECFI::DemId::getCellValue ( long  row,
long  column 
) const

Get a DEM value for the given global row/column.

The DemId::getCellValue method directly retrieves the value of a DEM cell.

Parameters:
row The index of the row to be retrieved.
column The index of the column to be retrieved.
Returns:
Altitude corresponding to row and column.

References EECFI::CfiClass::throwWarn.

DemConfFile EECFI::DemId::getData (  )  const

Get DEM parameters.

Returns:
DEM data.

References EECFI::CfiError::addMsg(), EECFI::DemConfFile::cacheMaxSize, EECFI::DemConfFile::cacheType, EECFI::DemConfFile::dataSize, EECFI::DemConfFile::dataType, EECFI::DemConfFile::dir, EECFI::DemMiniTiles::fileName, EECFI::DemConfFile::geoidComputation, EECFI::DemConfFile::geoidNumHarmonics, EECFI::DemMiniTiles::latSize, EECFI::DemMiniTiles::lonSize, EECFI::DemConfFile::metadataModel, EECFI::DemConfFile::miniTiles, EECFI::DemConfFile::model, EECFI::DemConfFile::northAlt, EECFI::DemConfFile::offsetX, EECFI::DemConfFile::offsetY, EECFI::DemConfFile::resUnit, EECFI::DemConfFile::resX, EECFI::DemConfFile::resY, EECFI::DemConfFile::southAlt, EECFI::CfiClass::throwWarn, EECFI::DemConfFile::userDirectory, EECFI::DemConfFile::XNumPoints, EECFI::DemConfFile::xRange, EECFI::DemConfFile::YNumPoints, and EECFI::DemConfFile::yRange.

DemInfo EECFI::DemId::getInfo ( const ModelId &  modelId,
double  lon,
double  lat 
) const

Get DEM source data.

Parameters:
modelId Model id.
lon Longitude.
lat Latitude.
Returns:
DEM source data corresponding to lon and lat

References EECFI::DemInfo::dataSource, EECFI::DemInfo::demModel, and EECFI::CfiClass::throwWarn.

void EECFI::DemId::init ( long  mode,
long  model,
const std::string &  demFile 
)

Initialise the DEM parameters.

The altitude is calculated from the altitudes read from a digital elevation model (DEM).

Location of DEM dataset

The DEM files are looked for in the directory specified in the field Directory in the DEM configuration file (see [D_H_SUM]). If this field is empty, the DEM files are looked for in the directory where the DEM configuration file is placed.

Access to DEM dataset

Depending on the Cache_Type field in the DEM configuration file (see [D_H_SUM]), one of the following methods is used to access the DEM dataset:
  • FIFO_CACHE (default): memory is reserved for holding DEM data. As soon as an altitude value is requested and is not yet available in memory, the corresponding data file is loaded in memory. When the maximum size of reserved memory (configurable with the field Cache_Max_Size) is exceeded, memory is made available with a First In - First Out policy, that is memory correspondent to the file loaded earliest is made available for the file to be loaded.
  • PRELOAD_CACHE: memory is reserved for holding DEM data. The user shall load in memory the needed files in advance via the function xp_dem_id_configure (see section 7.65). Request of a value not available in memory would result in an error.
  • NO_CACHE: no memory is reserved for holding DEM data. The dataset is accessed via a single direct I/O access to the file storing the requested value.
Choice of the method that best fits user's needs depends on many aspects including HW/SW setup and the type of user application:
  • The FIFO_CACHE is recommended for user applications able to request to the operating system a large amount of physical memory and that require making a large numbers of DEM computations per DEM area i.e. when several DEM computations are done reading the same file or small set of files covering the same region.
  • The PRELOAD_CACHE is recommended for multithreading applications. Note that memory holding DEM data can be shared amongst several threads. In the FIFO_CACHE, as memory content can change at runtime, mutual exclusion mechanisms are implemented in order to avoid threads to access inconsistent data. Such mechanisms are not needed in the PRELOAD_CACHE methods and therefore multithreading applications may run more efficiently. However the user is requested to estimate the area (in terms of the longitude/latitude boundaries) that will be requested during computations.
  • The above methods using memory to hold DEM data do not improve performance (or make even performance worse) of applications running with low amount of physical memory available or when DEM request is sporadic per DEM area. In all these cases, the user is recommended to set Cache_Type to NO_CACHE. For example, applications making sporadic accesses and in different DEM areas will not benefit of the caching methods, as the advantage of having a fast access to data is lost by the disadvantage of continuously load new files correspondent to different areas.
The default configuration is (i.e. when fields are not provided in the file):
  • Cache_Type = FIFO_CACHE
  • Cache_Max_Size = 2 GigaBytes
Values of Cache_Type and Cache_Max_Size can be changed at runtime under certain conditions using the method DemId::configure.
Memory is allocated using the malloc() C library function. Therefore performance of DEM access using caching strictly depends on the implementation of such library and on memory management from the Operating System. Performance of access to memory depends on many factors that can be tuned by the user. For the sake of example, if, as it normally happens in Linux systems, the memory request is larger than a given threshold size, the memory will be allocated in the virtual memory space and this may result in several page faults at runtime, leading to inefficiencies in the execution. The user can improve this by tuning the threshold size (i.e. using the mallopt() C library, if available). In order to get the best advantages from the caching methods, the user is therefore recommended to evaluate and tackle platform specific issues to memory allocation and management.

DEM maximum altitude algorithm

If the mini tile configuration is provided (MiniTile_Configuration tag) in the DEM configuration file (see [D_H_SUM]), the maximum altitude algoritm is used to compute DEM intersection. This algorithm consists in the following:
  • The tiles are divided in sub-sections (mini-tiles), according to the configuration provided in DEM configuration file: Lon_Size and Lat_Size tags. For example, if the tile is 15 degrees long in longitude and 15 degrees long in latitude, and Lon_Size and Lat_Size are 5 degrees and 5 degrees respectively, the tile would have 9 mini-tiles equal in size between them.
  • In the DEM configuration of mini-tiles, also the tag Filename is provided, which corresponds to the name (or path) of the binary file which contains the maximum altitude corresponding to each mini-tile. This file can be generated with function PointingFunc::genMaxAltitudeFile. If no path is provided, the binary file in looked for in current directory and the DEM directory.
  • Internally, the algorithm checks if the altitude of the rays when crossing above each mini-tile is higher or lower than maximum altitude contained in the mini-tile. If the altitude is lower, the mini-tile is computed to look for an intersection; if not, the mini-tile is skipped and the following mini-tile is checked.
Note: the algorithm is not executed if the difference in latitude/longitude of start and end points in ray search is less than mini-tile size.

DEM Geoid computation

The DEM ACE2 files provide the altitude with respect to its reference geoid. In the internal DEM computations, the altitude is transformed to altitude over the reference ellipsoid. To perform this operation, a number of harmonics must be used, which can be configured with the following DEM configuration user tags (see [D_H_SUM]):
  • Geoid_Computation tag: this field can take the values:
    • Enabled: geoid computation is performed.
    • Disabled: geoid computation is not performed.
  • Geoid_Nof_Harmonics tag: the number of harmonics to be used in geoid computation.
If this fields are not provided, the default values are:
  • Geoid_Computation: Enabled
  • Geoid_Nof_Harmonics: 30
The computation precision increases with the number of harmonics (maximum is 360 harmonics) but the runtime gets worse. The computation of the geoid at runtime can be avoided by generating offline a DEM dataset storing altitudes w.r.t. ellipsoid using PointingFunc::genDemAltitudesFromEllipsoid. In this case, when the DEM is used, the geoid computation shall be disabled in the DEM configuration file.
Parameters:
mode Digital elevation model initialisation mode (DemModelPointingEnum). This parameter has no effect in current implementation (the DEM type is taken from configuration file), but a warning will be raised if the value does not coincide with the one in configuration file.
model Digital elevation model initialisation model (dummy in current implementation).
demFile File used for DEM initialisation.

References EECFI::CfiId::addInstance(), and EECFI::CfiClass::throwWarn.

DemId & EECFI::DemId::operator= ( const DemId &  other  ) 

Copy assignment operator.

Parameters:
other The DemId to copy/assign from

References EECFI::CfiId::addInstance(), and eraseObject().

SatId EECFI::DemId::satId (  )  const

Get satellite id.

Returns:
Satellite id.
Generated on Mon Dec 11 2023 13:28:30 for by doxygen 1.7.1