| Earth Observation Mission CFI Software Pointing Software User Manual |

Public Member Functions | Protected Member Functions

# EECFI::DemId Class Reference

Class for the DEM parameters. More...

Inheritance diagram for EECFI::DemId:

List of all members.

## Public Member Functions
| DemId ()
| Empty Class constructor.
| ~DemId () throw (CfiError)
| Class destructor.
void | init (long mode, long model, const string demFile) throw (CfiError)
| Initialise the DEM parameters.
double | compute (const ModelId &modelId, double lon, double lat) const throw (CfiError)
| Compute altitude over the sea level for a point in the Earth.
SatId | satId () const
| Get satellite id.
DemConfFile | getData () const throw (CfiError)
| Get DEM parameters.
DemInfo | getInfo (const ModelId &modelId, double lon, double lat) const throw (CfiError)
| Get DEM source data.
void | configure (DemIdConfig &config) throw (CfiError)
| Configure DEM cache.
## Protected Member Functions
GenericId * | getId ()
| Get the id.

## Detailed Description

Class for the DEM parameters.

## Constructor & Destructor Documentation

EECFI::DemId::DemId | ( |  | ) |

Empty Class constructor.

EECFI::DemId::~DemId | ( |  | ) | throw (CfiError)

Class destructor.

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

## Member Function Documentation

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

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.

void EECFI::DemId::configure | ( | DemIdConfig & | config | ) | throw (CfiError)

Configure DEM cache.

Parameters:

  | config | DEM ID configuration.

DemConfFile EECFI::DemId::getData | ( |  | ) | const throw (CfiError)

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::DemConfFile::metadataModel, 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.

GenericId * EECFI::DemId::getId | ( |  | ) | `[protected]`

Get the id.

Returns:
  Pointer to xp_dem_id.

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

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, and EECFI::DemInfo::demModel.

void EECFI::DemId::init | ( | long | mode,
|  | long | model,
|  | const string | demFile |
| ) |  |  | throw (CfiError)

Initialise the DEM parameters.

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

# 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.

Parameters:

  | mode | Digital elevation model initialisation mode (DemModelPointingEnum).
  | model | Digital elevation model initialisation model (dummy in current implementation).
  | demFile | File used for DEM initialisation.

SatId EECFI::DemId::satId | ( |  | ) | const

Get satellite id.

Returns:
  Satellite id.