| Earth Observation Mission CFI Software Pointing Software User Manual for JAVA |

Public 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.
void | close () throws CfiError
| Release all resources managed by this object.
native void | init (long mode, long model, String demFile) throws CfiError
| Initialise the DEM parameters.
native double | compute (final ModelId modelId, double lon, double lat) throws CfiError
| Compute altitude over the sea level for a point in the Earth.
native SatId | satId ()
| Get satellite id.
native DemConfFile | getData () throws CfiError
| Get DEM parameters.
native DemInfo | getInfo (final ModelId modelId, double lon, double lat) throws CfiError
| Get DEM source data.
native void | configure (final DemIdConfig config) throws CfiError
| Configure DEM cache.
native double | getCellValue (long row, long column) throws CfiError
| Get a DEM value for the given global row/column.
native GeoGeodCoord | getCellGeod (long row, long column) throws CfiError
| Get longitude/latitude corresponding to the the DEM point with the given global row/column.

## Detailed Description

Class for the DEM parameters.

## Constructor & Destructor Documentation

EECFI.DemId.DemId | ( |  | ) |

Empty Class constructor.

## Member Function Documentation

void EECFI.DemId.close | ( |  | ) | throws CfiError

Release all resources managed by this object.

IMPORTANT: The life time of the EOCFI Java objects must be explicitly managed by the program work flow. Failure to perform this release will lead to resource leakage and might have a significant impact in performance.

double EECFI.DemId::compute | ( | final ModelId | modelId,
|  | double | lon,
|  | double | lat |
| ) |  |  | throws 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.

native void EECFI.DemId.configure | ( | final DemIdConfig | config | ) | throws CfiError

Configure DEM cache.

GeoGeodCoord EECFI.DemId::getCellGeod | ( | long | row,
|  | long | column |
| ) |  |  | throws CfiError

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

Parameters:

  | row | The index of the row to be converted.
  | column | The index of the column to be converted.

Returns:
  Associated latitude and longitude according to DEM caracteristics.

double EECFI.DemId::getCellValue | ( | long | row,
|  | long | column |
| ) |  |  | throws CfiError

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

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.

DemConfFile EECFI.DemId::getData | ( |  | ) | throws CfiError

Get DEM parameters.

Returns:
  DEM data.

native DemInfo EECFI.DemId.getInfo | ( | final ModelId | modelId,
|  | double | lon,
|  | double | lat |
| ) |  |  | throws CfiError

Get DEM source data.

void EECFI.DemId::init | ( | long | mode,
|  | long | model,
|  | String | demFile |
| ) |  |  | throws CfiError

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.

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

Get satellite id.

Returns:
  Satellite id.