Prototype and description of the function getelevation03()

(Function of the unlock requiring group "Elevation calculations")

 

getelevation03()
Elevation from the 3 sec. elevation model CGIAR for a point.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getelevation03(
     double nGeoLon,
     double nGeoLat,
     unsigned long lInterpol,
     short *nElevation);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getelevation03(;
     nGeoLon AS REAL8,;                     // 8 Byte
     nGeoLat AS REAL8,;                     // 8 Byte
     lInterpol AS LOGIC,;                   // 4 Byte
     nElevation REF SHORTINT);              // 4 Byte
as logic pascal:geodll32.getelevation03     // 4 Byte


The function determines the ground level elevation from the 3 seconds
elevation model (90 m raster) CGIAR at a point defined by geographical
coordinates.

The 3 seconds elevation model of the NASA Shuttle Radar Topographic Mission
"SRTM 90m Digital Elevation Data" is free available for non commercial
purposes and can be acquired for commercial use economically priced from
the CGIAR. With a license for the GeoDLL function group "Elevation
calculations" you only acquired the right to use the functions to compute
the elevation data. The elevation data are subject to the copyright of the
"CGIAR Consortium for Spatial Information". This organization revised and
supplemented the original data of the NASA. Please consider the terms of
use and the copyright conditions of the CGIAR.

The 3 seconds elevation model consists of altogether 1728 files with
elevation data between the 60. northern latitude and the 60. southern
latitude. Each file covers a range of 5 lines of longitude and 5 lines of
latitude. The ground elevations are put down in a 3 seconds raster grid.
That corresponds to a resolution of maximal 90 x 90 meters in equator
proximity. In direction to the poles the grid consolidates with increasing
resolution over the geographical latitude. The elevation data are
horizontal georeferenced with geographic coordinates in the reference
system WGS84. Vertical the ground elevation is georeferenced as the "Mean
Sea Level" in integral meters. Further information you find on the Internet
site of the CGIAR.

You can download the data of the 3 seconds elevation model from the Internet
site of the "CGIAR Consortium for Spatial information". The current Internet
address is "http://srtm.csi.cgiar.org/". Click in the navigation column on
the link "SRTM Data Search and Download". Activate the radio buttons
"Multiple Selection" and "ArcInfo ASCII". Click inside the world raster map
on the segments, from which you need elevation data. Confirm your
selection with the Button "Search". In a new window the segments you
selected are arranged for the download. Click on one of the links "Data
Download (FTP)" or to "Data Download (HTTP)" for each data segment you need
to copy the data to your computer.

After unpacking the ZIP compressed data they are present as ASCII data
files. To be able to use the data with GeoDLL functions, first the data
path to the elevation data must be make known to GeoDLL by calling the
function setelev03datapath(). With the first access of a GeoDLL function to
an ASCII formatted file this is automatically converted to the substantially
more efficient and more compact binary data format. The conversion can take
a long time up to a half minute. To go on working while the conversion is in
process, the event-processing can be switched on (see below). Future
accesses directly use the new produced binary formatted file. The ASCII file
then can be deleted. The conversion to the binary format can be done
alternatively with the function convelev03ascii2bin().

Since the function due to the extensive calculations is time-consuming,
the event handling during the calculation by interrupting the processing loop
can be are allowed bei calling the function seteventloop().

ASCCI files of the CGIAR versions 2 through 4 are supported. This fle
formats are possible:
Example of a file name in CGIAR V2 syntax:        Z_38_2.ASC.
Example of a file name in CGIAR V3/V4 syntax: SRTM_38_02.ASC.
The file names are not upper or lower case sensitive.

You can order CD-ROMs, DVDs or an external hard disk with already to the
binary data format converted elevation data directly from KilletSoft.
Internet address: http://www.killetsoft.de/p_gdlfhb_e.htm.
Thereby the elevation data are passed free of charge. They are subject to
the copyright of the "CGIAR Consortium for Spatial information". Only a
small copying fee and the costs of the data medium must be paid.

Differences between the elevation models GLOBE and CGIAR:
Elevation model:             GLOBE             CGIAR
GeoDLL function              getelevation30()  getelevation03()
Range longitude [degrees]    -180 to 180       -180 to 180
Range latitude [degrees]     -90 to 90         -60 to 60
Resolution [sec]             30 x 30           3 x 3
Resolution [m]               925 x ‹= 925      90 x ‹= 90
Horizontal reference         WGS84             WGS84
Vertical reference           Mean Sea Level    Mean Sea Level
Horizontal deviation [m]     ‹ 6               ‹ 6
Vertical deviation [m]       ‹ 10              ‹ 7
Number of files              16                1728
File size [MB]               101/126           70
Range per file [degrees]     90 x 40/50        5 x 5


The parameters are passed and/or returned as follows:
nGeoLon     Geographic longitude of the point to get the ground elevation
            from in [degrees] notation vggg.ggg in the Reference System
            WGS84.

nGeoLat     Geographic latitude of the point to get the ground elevation
            from in [degrees] notation vgg.ggg in the Reference System
            WGS84.

lInterPol   TRUE: The ground elevation is interpolated from the 4 corner
            points of the 3 x 3 seconds raster field containing the
            coordinate. The computation is exact, but relative slow.
            FALSE: The ground elevation corresponds to the value of the
            3 x 3 seconds raster field containing the coordinate. The
            computation is less exact, but relative fast.

nElevation  Ground elevation over the Mean Sea Level in meters as result of
(ref)       the computation. In the presence of a water cover the value 0
            is returned. If an error occurs the function returns the value
            9999.

returnVal   In case of an error the function returns FALSE, otherwise TRUE.


For geographic coordinates in [degrees] notation applies:
v           Optional sign for longitudes west of Greenwich and latitudes
            south of the equator.
g           degrees and decimal fraction of a degree.


Unlocking
This function is a component of the unlock requiring function group
"Elevation calculations". It is unlocked for unrestricted use together with
the other functions of the group by passing the unlock parameters, acquired
from the software distribution company, trough the function setunlockcode().
Without unlocking only a few function calls for test purposes (shareware
principle) are possible.