Executables

This section describes the use and function of the three executable modules which are a part of the CS- MAP distribution. Note that the executables modules themselves are not provided. Source code which can be used to create the executable modules on your platform are included.

CS_COMP—Coordinate System COMPiler

CS_COMP [/c] [/b] [/s] [/t] [/w] source_file_dir output_dir

CS_COMP creates binary dictionary files from the ASCII source files provided with the CS-MAP distribution. This feature has been added to

eliminate problems with the byte order of binary data on platforms other than Intel and
provide a means by which coordinate system definitions can be committed to source control procedures. Release 6 (and later) of CS-MAP precludes, to a large extent, the first need described above. See Byte Ordering below.

On UNIX systems, you will need to use the UNIX option character (i.e. the dash) when specifying options.

Source code to CS_COMP and its components is provided to all licensees, and has been tested as a console application under Windows XP and Linux 3.2.2. As CS-MAP is intended for use in a large variety of systems, and for compilation and linking by users who may not have access to lex and yacc, the user interface and source file formats are very simple and basic.

By compiling all four source files at the same time, CS_COMP can now perform consistency checks between all four files. To simplify use, the actual file names are hard coded into the program. Thus, the source files are required to be named Coordsys.asc, Datums.asc, Elipsoid.asc, and Mreg.asc for the Coordinate System, Datum, Ellipsoid, and Multiple Regression Transformation data files respectively. CS_COMP expects these files to reside in the directory specified as the first positional argument on the command line.

Similarly, the names of the output files are fixed by the program, being the names specified in the CSdata module. These are the same names that the library in general searches for. The directory in which these files are written is specified as the second positional parameter on the command line.

Since CS_COMP performs a consistency check between all files, it expects to compile all four files. It is not possible to compile the files individually.

CS_COMP is coded for possible compilation as a Windows XP console application. Therefore, it requires an acknowledgment before it exits, enabling the operator to verify successful completion before the window disappears. For use in make files and/or batch files, you may wish to use the /b option to suppress the requirement for acknowledgment before exit.

CS_COMP normally produces encrypted output files. Use the /c option to cause unencrypted versions of the dictionaries to be produced for testing and/or debugging purposes.

Presence of the /t option instructs CS_COMP to include coordinates systems, datums, and ellipsoids in the Test group. Normally, these are neither compiled or distributed with your application.

Use the /w option to instruct CS_COMP to report any inconsistency in the data which may only be suspicious.

In the UNIX environment, the dash must be used as the option character.

Use the /s option to instruct CS_COMP to produce dictionary files in big endian byte order regardless of the system on which the program has been compiled. This forces a byte swap before output on little endian processors (e.g. Intel) and omits the byte swap on big endian processors (e.g. Sun).

Byte Ordering

CS_COMP calls CS_bswap immediately prior to writing any data to the dictionary file in order to effect, as necessary, a byte order switch to little endian (i.e. Intel/DOS) byte order. This is the same byte order expected by the CS-MAP library on all platforms. It is also the byte order which the data file from other sources, such as the NADCON LAS/LOS files, are distributed. Use of the /s options reverses this effect, causing big endian data files to be produced, regardless of the processor in use.

Source File Formats

Coordsys.asc

Records in the COORDSYS.ASC source file consist of a line of text. Blank lines are generally ignored. All characters following an un-escaped pound sign character ('#') are ignored. The pound sign character can be escaped by the backslash ('\') or pound sign ('#') characters. Note that this is required to get a pound sign character into a coordinate system description as these descriptions are not quoted. Leading and trailing whitespace on all records is also ignored. Records to be processed must start with one of the 39 keywords described below. The colon separator character is considered to be part of the keyword. The value of the keyword must follow the keyword on the same line of text, white space may be used to separate the keyword from its value.

Each occurrence of the CS_NAME: keyword indicates the beginning of a new coordinate system definition and the end of any previous coordinate system definition. Otherwise, the order of the specifications is not important. However, to maintain your source in a comprehensible format, it is strongly recommended that each coordinate system definition begin with the CS_NAME: keyword and be terminated by one or more blank lines. No blank lines should appear within the definition itself. Further, while CS_COMP will sort the resulting binary Coordinate System Dictionary file, maintaining the coordinate system source file in sorted order makes it (relatively) easy to locate a definition should review or editing be required.

For projection specific information, refer to the projection descriptions of this guide. Note that rarely will any projection require the use of all 39 keyword specifications.

The 25 keywords and their values are:

CS_NAME: - Used to specify the key name of the coordinate system which is to be defined, 23 characters max. See CS_nampp for conventions concerning key names.
DESC_NM: - Used to specify the 63 character descriptive name of the coordinate system being defined.
DT_NAME: - Used to specify the datum key name to which a geodetically referenced coordinate system is to be referenced to. The ellipsoid used is a part of this datum definition. Presence of a valid datum key name here indicates that the coordinate system is geodetically referenced. Either a DT_NAME: specification, or an EL_NAME: specification must be provided for each coordinate system definition. If both DT_NAME: and EL_NAME: specifications are provided, the EL_NAME: specification is ignored by CS-MAP.
EL_NAME: - Used to specify the ellipsoid key name for a cartographically referenced coordinate system. A coordinate system is cartographically referenced to the ellipsoid named by this specification if, and only if, the datum key name specification is omitted. If both DT_NAME: and EL_NAME: specifications are provided, the EL_NAME: specification is ignored by CS-MAP.
ORG_LAT: - Used to specify the origin latitude of the coordinate system. This value may be in any form acceptable to CS_atof, but is always in degrees relative to the equator. Use positive numbers for north latitude, negative numbers for south latitude.
ORG_LNG: - Used to specify the origin longitude of the coordinate system. This value may in any form acceptable to CS_atof, but always in degrees and is always relative to the Greenwich prime meridian. Use positive numbers for east longitude, negative numbers for west longitude.
SCL_RED: - Used to specify the scale reduction which may apply to a coordinate system. This value is ignored by the many projections which do not support this feature. The value may be specified as a decimal number, e.g. 0.9996, or as a ratio, e.g. 1:2500. A value of 1.0 or greater is unusual, but is accepted.
ZERO_X: - Used to specify the minimum X value which is to be considered non-zero. X coordinate values whose absolute value is less than the value specified here will be converted to hard zeros. This is used to suppress coordinate output such as 4.3472E-07 which can be of value in certain applications. A value of 0.0 is assumed if no specification is made.
ZERO_Y: - Used to specify the minimum Y value which is to be considered non-zero. Y coordinate values whose absolute value is less than the value specified here will be converted to hard zeros. This is used to suppress coordinate output such as 4.3472E-07 which can be of value in certain applications. A value of 0.0 is assumed if no specification is made.
PARM1: thru PARM24: - Used to specify the value of as many as 24 parameters which are specific to the particular projection in use. The use of these items varies from one projection to another. The value is always a real number. Where a longitude is specified, it must be given in degrees, relative to Greenwich, where west longitude is negative. Where a latitude is expected, it must be given in degrees relative to the equator where north latitude is positive and south latitude is negative. When an azimuth is specified, it must be given in degrees east of north (i.e. west of north would be negative). In all cases, the values are processed by CS_atof, and any form acceptable to that function may be used.
X_OFF: - Used to specify the value of the false easting of the coordinate system. A value of 0.0 is assumed if no specification is made. Any form acceptable to CS_atof may be used, including the use of the comma as a thousands separator.
Y_OFF: - Used to specify the value of the false northing of the coordinate system. A value of 0.0 is assumed if no specification is made. Any form acceptable to CS_atof may be used, including the use of the comma as a thousands separator.
PROJ: - Used to specify the code name of the projection upon which the coordinate system is based. This code value must be the value assigned to the desired projection in the CSdataPJ module, i.e. the projection table. This value is a character string of two to eight characters. Since projections can now have several variations, this code value is not the same as the five character code used to generate function and structure tag names. You will need to refer to the CSdataPJ module to determine the code name for a specific projection type.
UNIT: - Used to specify the name of the system unit for the coordinate system being defined. In the case of a normal cartesian coordinate system, this must be one of the supported unit of length names as defined in the CSdataU module. In the case of the Unity projection, i.e. the coordinate system being defined is latitude and longitude or a variation thereof, the unit name must be one of those names defined as a unit of angular measure in the CSdataU module.
GROUP: - Used to classify coordinate systems into groups to make selection of a coordinate system from the 5,000+ provided a bit easier. The supported group codes are defined in the CSdata module.
SOURCE: - Used to specify the source of the information used to define this coordinate system, 63 characters maximum. The term Authority is often used to describe this information.
QUAD: - Used to indicate the quadrant of the cartesian coordinates produced by the coordinate system. Zero or 1 indicate the normal right handed cartesian system where X increases to the east, and Y increases to the north. Quadrants are numbered counterclockwise, therefore a value of 2 specifies a cartesian system where X increases to the west, while Y increases north. A value of 3 indicates that X increases to the west and Y increases to the south. A value of 4 indicates that X increases to the east and Y increases to the south. A negative value will cause the axes to be swapped after the appropriate quadrant is applied. A value of 1 is assumed if this specification is absent.
MIN_LNG: - This parameter is optional and can be used to specify the minimum longitude of the useful range of the coordinate system. The value is given in degrees relative to Greenwich in any form acceptable to CS_atof. Positive values indicate east longitude, while negative values indicate west longitude. Its value should be normalized between -360 and +360 and when used must be algebraically less than the MAX_LNG: parameter.
MAX_LNG: - This parameter is optional and can be used to specify the maximum longitude of the useful range of the coordinate system. The value is given in degrees relative to Greenwich in any form acceptable to CS_atof. Positive values indicate east longitude, while negative values indicate west longitude. Its value should be normalized between -360 and +360 and when used must be algebraically greater than the MIN_LNG: parameter.
MIN_LAT: - This parameter is optional and can be used to specify the minimum latitude of the useful range of the coordinate system. The value is given in degrees relative to the equator in nay form acceptable to CS_atof. Positive values indicate north latitude while negative values indicate south latitude. Its value should be normalized between -90 and +90 and when used must be algebraically less than the MAX_LAT: parameter.
MAX_LAT: - This parameter is optional and can be used to specify the maximum latitude of the useful range of the coordinate system. The value is given in degrees relative to the equator in nay form acceptable to CS_atof. Positive values indicate north latitude while negative values indicate south latitude. Its value should be normalized between -90 and +90 and when used must be algebraically greater than the MIN_LAT: parameter.
MIN_XX: - This parameter is optional and can be used to specify the minimum X coordinate value of the useful range of the coordinate system. The value is given in system units and may be provided in any form acceptable to CS_atof. Its value must be algebraically less than the MAX_XX: parameter.
MAX_XX: - This parameter is optional and can be used to specify the maximum X coordinate value of the useful range of the coordinate system. The value is given in system units and may be provided in any form acceptable to CS_atof. Its value must be algebraically greater than the MIN_XX: parameter.
MIN_YY: - This parameter is optional and can be used to specify the minimum Y coordinate value of the useful range of the coordinate system. The value is given in system units and may be provided in any form acceptable to CS_atof. Its value must be algebraically less than the MAX_YY: parameter.
MAX_YY: - This parameter is optional and can be used to specify the maximum Y coordinate value of the useful range of the coordinate system. The value is given in system units and may be provided in any form acceptable to CS_atof. Its value must be algebraically greater than the MIN_YY: parameter.

Other key words have been coded into the CS_COMP module but are reserved for future use by OSGeo contributors. They should not be used until their exact usage is defined in a future release.

Datums.asc

Records in the DATUMS.ASC source file consist of a line of text. Blank lines are ignored. All characters following an un-escaped pound sign character ('#') are ignored. The pound sign character can be escaped by the backslash ('\') or pound sign ('#') characters. Note that this is required to get a pound sign character into a datum description as these descriptions are not quoted. Leading and trailing whitespace on all records is also ignored. Records to be processed must start with one of the twelve keywords described below. The colon separator character is considered to be part of the keyword. The value of the keyword must follow the keyword on the same line of text, white space may be used to separate the keyword from its value.

Each occurrence of the DT_NAME: keyword indicates the beginning of a new datum definition and the end of any previous datum definition. Otherwise, the order of the specifications is not important. However, to maintain your source in a comprehensible format, it is strongly recommended that each coordinate system definition begin with the DT_NAME: keyword and be terminated by one or more blank lines. No blank lines should appear within the definition itself. Further, while CS_COMP will sort the resulting binary Datum Dictionary file, maintaining the datums source file in sorted order makes it (relatively) easy to locate a definition should review or editing be required.

Also note, that CS-MAP uses the Datum Key name as the base portion of a file name to access the Multiple Regression Transformation file. Therefore, a datum key name of more than 8 characters on a DOS based system may not work as expected.

The twelve keywords and their required values are:

DT_NAME: - Used to specify the key name of the datum which is to be defined, 23 characters max. Refer to CS_nampp for conventions concerning key names. Since datum key names are used to link to the Multiple Regression Transformation files, datum key names longer than 8 characters may present problems on systems using the DOS FAT-16 file system (i.e. file name limited to 8 characters).
DESC_NM: - Used to specify the 63 character descriptive name of the datum being defined. ELLIPSOID: - Used to specify the key name of the ellipsoid definition upon which this datum is based. This name must be the key name of an entry in the Ellipsoid Dictionary.
USE: — This parameter is required and is used to specify the datum conversion technique to convert coordinates based on the datum being defined to WGS84 coordinates. There are, currently, ten valid values. They are:
1. MOLODENSKY - Use the Molodensky transformation to convert to WGS84.
2. GEOCENTRIC - Use the geocentric translation method to convert to WGS84.
3. BURSA - Use the Bursa/Wolfe Seven Parameter Transformation to convert to WGS84.
4. 7PARAMETER - Use the Seven Parameter Transformation to convert to WGS84, default to Molodensky if the necessary parameters are not present.
5. MULREG - Use the Multiple Regression Transformation formulas. If such a definition is not available, default to the Bursa/Wolfe Seven Parameter Transformation.
6. NAD27 - Use the NADCON or Canadian National Transformation emulation as appropriateto convert to NAD83, and consider the result to be WGS84 coordinates.
7. `NAD83 - Consider the coordinates to be WGS84 coordinates already, no shift is to be performed.
8. WGS84 - The coordinates are WGS84 coordinates already, no datum shift is required.
9. WGS72 - Use an internal formula to convert to WGS84.
10. HPGN - Use the NADCON algorithm, but use the HPGN data files, to shift the coordinates to NAD83, then consider the result to be WGS84 coordinates without any further datum shift.
DELTA_X: - The X component of the vector from the geocenter of this datum to the geocenter of the WGS-84 datum in meters.
DELTA_Y: - The Y component of the vector from the geocenter of this datum to the geocenter of the WGS-84 datum in meters.
`DELTA_Z : - The Z component of the vector from the geocenter of this datum to the geocenter of the WGS-84 datum in meters.
BWSCALE: - The scale of the Bursa/Wolfe or Seven Parameter Transformation, given as parts per million as is ordinarily the case for this transformation. This value can be positive or negative. The actual resulting scale factor used in the transformation is 1.0 + (BWSCALE * 1.0E-06).
ROT_X: - The rotation about the X axis, given in seconds of arc. Positive values indicate clockwise rotation of the right handed Helmert coordinate system.
ROT_Y: - The rotation about the Y axis given in seconds of arc. Positive values indicate clockwise rotation of the right handed Helmert coordinate system.
ROT_Z: - The rotation about the Z axis given in seconds of arc. Positive values indicate clockwise rotation of the right handed Helmert coordinate system.
SOURCE: - The source of information from which this definition was developed.

Support of other keywords has been coded into the CS_COMP module; but use of these is reserved by OSGeo contributors for future use.

Elipsoid.asc

Records in the ELIPSOID.ASC source file consist of a line of text. Blank lines of text are ignored. All characters following an un-escaped pound sign character ('#') are ignored. The pound sign character can be escaped by the backslash ('\') or pound sign ('#') characters. Note that this is required to get a pound sign character into an ellipsoid description as these descriptions are not quoted. Leading and trailing white space on all records is also ignored. Records to be processed must start with one of the five keywords described below. The colon separator character is considered to be part of the keyword. The value of the keyword must follow the keyword on the same line of text, white space may be used to separate the keyword from its value.

Each occurrence of the EL_NAME: keyword indicates the beginning of a new ellipsoid definition and the end of any previous ellipsoid definition. Otherwise, the order of the specifications is not important. However, to maintain your source in a comprehensible format, it is strongly recommended that each ellipsoid definition begin with the EL_NAME: keyword and be terminated by one or more blank lines. No blank lines should appear within the definition itself. Further, while CS_COMP will sort the resulting binary Ellipsoid Dictionary file, maintaining the ellipsoid definition source file in sorted order makes it (relatively) easy to locate a definition should review or editing be required.

The six keywords and their required values are:

EL_NAME: - Used to specify the key name of the ellipsoid which is to be defined, 23 characters max.
DESC_NM: - Used to specify the 63 character descriptive name of the ellipsoid being defined.
E_RAD: - Used to specify the equatorial radius of the ellipsoid being defined. This radius must be specified in meters.
P_RAD: - Used to specify the polar radius of the ellipsoid being defined. This radius must be specified in meters. Use the same value given for E_RAD: to define a spherical ellipsoid.
SOURCE: - The source of the information used to make this definition.
GROUP: - This keyword is used to mark ellipsoid definitions as being for testing only. Additional groups may be established in the future.

CS_COMP will calculate the eccentricity and flattening from the provided radii.

MReg.asc

Records in a MREG.ASC source file consist of a line of text. Blank lines are ignored. All characters following an un-escaped pound sign character ('#') are ignored. The pound sign character can be escaped by the backslash ('\') or pound sign ('#') characters. Note that this is required to get a pound sign character into a datum description as these descriptions are not quoted. Leading and trailing white space on all records is also ignored. Records to be processed must start with one of the 12 keywords described below. The colon separator character is considered to be part of the keyword. The value of the keyword must follow the keyword on the same line of text, white space may be used to separate the keyword from its value. In certain cases, the actual keyword contains numeric qualifiers which indicate the specific power series term the keyword applies to.

Each occurrence of the DATUM_NAME: keyword indicates the beginning of a new multiple regression definition and the end of any previous multiple regression definition. The order of the specifications is not important. However, to maintain your source in a comprehensible format, it is strongly recommended that each multiple regression definition begin with the DATUM_NAME: keyword and be terminated by one or more blank lines. No blank lines should appear within the definition itself. Maintaining the multiple regression source file in sorted order makes it (relatively) easy to locate a definition should review or editing be required.

Please note that a test case is required for each datum. A binary multiple regression coefficient data file will not be written unless the provided coefficients satisfy the provided test case. In the terminology used in this module, LAMBDA refers to longitude, and PHI refers to latitude. In preparation for future enhancements to CS-MAP, the HEIGHT coefficients are also required. If such are not currently available, simply use values which will produce a zero change in height to get around the required coefficient check.

Values for the various keywords are given in a manner which is somewhat inconsistent with CS-MAP. However, the manner in which these values are specified is consistent with the conventions used in the source for most of this type of information: DMA TR-8350.2B.

The 12 keywords and their required values are:

DATUM_NAME: - Used to specify the 23 character name of the datum for which the following coefficients represent the multiple regression coefficients. This is the name, with the .MRT extension appended, which is given to the coefficient data file. The association of a datum in the Datum Dictionary and the multiple regression data file is established by this name.
TEST_LAMBDA: - This keyword must be followed by the longitude of the test point. This longitude must be given in degrees, minutes, and seconds form, where west longitudes are given as values greater than 180. This entry is processed by a "%d %d %lf" sscanf format specification.
TEST_PHI: - This keyword must be followed by the latitude of the test point. This latitude must be given in degrees, minutes, and seconds form. Use a negative value to indicate south latitude. This entry is processed by a "%d %d %lf" sscanf format specification.
DELTA_LAMBDA: - This keyword must be followed by a single real value which represents the amount of longitude shift, in seconds of arc, which is expected at the provided test point.
DELTA_PHI: - This keyword must be followed by a single real value which represents the amount of latitude shift, in seconds of arc, which is expected at the provided test point.
DELTA_HEIGHT: - This keyword must be followed by a single real value which represents the amount of elevation shift, in meters, which is expected at the provided test point.
LAMBDA_OFF: - This keyword must be followed by the longitude offset used to normalize the coefficient formula. This value must be given in decimal degrees, use negative values for west longitude.
PHI_OFF: - This keyword must be followed by the latitude offset used to normalize the coefficient formula. This value must be given in decimal degrees, use negative values for west longitude.
KK - This keyword must be followed by the scale factor which is used to normalize the regression formula. This value is unitless.
LAMBDA - This keyword is used to identify a longitude formula coefficient. The keyword itself must be followed by a Un and a Vn sequence which indicates which coefficient follows. For example, LAMBDA U1 V2: 1.23456 indicates that 1.23456 is the coefficient for the longitude times latitude squared term in the regression formula. CS-MAP does not support terms with powers higher than 9.
PHI - This keyword is used to identify a latitude formula coefficient. The keyword itself must be followed by a Un and a z sequence which indicates which coefficient follows. For example, PHI U2 V1: 1.23456 indicates that 1.23456 is the coefficient for the longitude squared times latitude term in the regression formula. CS-MAP does not support terms with powers higher than 9.
HEIGHT - This keyword is used to identify an elevation formula coefficient. The keyword itself must be followed by a Un and a z sequence which indicates which coefficient follows. For example, HEIGHT U0 V0: 1.23456 indicates that 1.23456 is the constant term in the regression formula. CS-MAP does not support terms with powers higher than 9.

TEST -- TEST program

TEST [/t12345...] [/dmap_dir] [/pnn] [/s] [/v] [/b] [test_data_file_name]

TEST will exercise most (but not all) of the functions included in the Coordinate System Mapping Package library. It can be used to verify the correct operation of the library in different environments, especially useful after compiling the library with a new or different C compiler or on a different platform.

Since TEST relies on the test coordinate systems, datums, and ellipsoids, CS_COMP should be run with the /t option prior to using the TEST program.

The program requires no arguments and normally expects the Ellipsoid Dictionary, the Datum Dictionary, the Coordinate System Dictionary, all Multiple Regression Transformation files, and Geodetic Data Catalogs to reside in their default locations and the file TEST.DAT to reside in the current working directory when executed. As a convenience, however, if a file named COORDSYS exists in the same directory from which TEST was executed, TEST will look to that directory for all supporting data files (except the TEST.DAT file). Alternatively, you may use the /d option to specify the directory you want TEST to look to for all supporting data files.

TEST will write all diagnostic messages to the console screen. On Windows 95/98/NT systems, you will need to use the MS-DOS option character (i.e. the forward slash) when specifying options.

The provided test file, TEST.DAT, includes tests for the NAD27 to NAD83 datum conversion software. Therefore, the NADCON CONUS database file system must exist in the default data directory (see CSdata(5CS)) if these tests are to be successful. TEST.DAT also includes tests for the Canadian National Transformation. However, since OSGeo cannot distribute the data files associated with the Canadian National Transformation, these tests have been commented out. Canadian users may wish to uncomment these tests before using TEST.

The command line options can be used to modify the operation of the test procedure. There are, currently, 19 separate tests performed by TEST, and each is designated with a number or a letter. Normally, TEST performs each of the first fifteen tests twice; first in forward numeric order, and then in reverse numeric order. Use the /t option to specify the specific test(s) you would like performed, and the order in which they are to be performed; one test per character (120 maximum).

Individual Tests

The nature of the 16 tests are:

Test 1 - This test manipulates the Ellipsoid Dictionary using CS_eldef, CS_elupd, and CS_eldel.
Test 2 - This test manipulates the Datums Dictionary using CS_dtdef, CS_dtupd, and CS_dtdel.
Test 3 - This test manipulates the Coordinate System Dictionary using CS_csdef, CS_csupd, and CS_csdel.
Test 4 - This test reads the file named TEST.DAT in the current directory and performs all of the conversions indicated, comparing the calculated results with the expected results recorded in the file. Of course, all discrepancies are reported to the user. You may specify an alternate file name (and directory) on the command line as the only positional argument. Each supported projection (except the Equidistant Cylindrical) has at least one test from a source other than CS-MAP in TEST.DAT. TEST.DAT also includes tests of datum conversions.
Test 5 - Test 5 is a performance test. Normally, it records the amount of wall clock time necessary to make 300,000 conversions from "UTM27-13" to "CO83-C" using the High Performance Interface. Each conversion, therefore, includes an inverse Transverse Mercator, a NAD27 to NAD83 datum shift, and a forward Lambert Conformal Conic conversion. The test cycles through a list of 10 different coordinate pairs to add some reality to the test without distorting the numeric results with I/O time and/or system overhead. The elapsed time and the effective conversion rate are reported to the user. The /p option can be used to change the number of conversions in the test. For example, /p45 would instruct TEST to perform 450,000 conversions whenever it performs test number 5.
Test 6 - This test exercises the sorting and binary search functions of CS-MAP well beyond what would be experienced in normal use. This is accomplished by sorting the Coordinate System Dictionary into reverse order, binary searching the result, and resorting back into normal order. Finally, the order of the result is verified to be correct.
Test 7 - This test exercises the CS_csgrp function and its supporting data.
Test 8 - For each coordinate system in the Coordinate System Dictionary, this test will cause a coordinate to be converted in both the forward and inverse direction, as well as calculate the grid scale factor and the convergence angle. This test does not verify the accuracy of the results, but simply assures that every calculation function is exercised at least once. This test is somewhat superfluous now that Test C is available.
Test 9 - This test exercises the functions which are used to calculate the power series solutions to the elliptical integrals used quite frequently in CS-MAP. It verifies the results against an outside source, and then compares forward and inverse calculations with each other. Please note that the external source for the correct values is limited in precision. Therefore the RMS discrepancy values may be alarmingly high. This is not the case, however, as indicated by the RMS discrepancies between forward and reverse calculations.
Test A - This test is identical to test 4 in every way except it uses the High Level Interface function CS_cnvrt function for all conversions, thus testing the caching system for coordinate systems and datum conversions.
Test B - Test B tests the grid scale and convergence angle functions of all non-azimuthal projections. It uses an empirical technique to determine the grid scale and convergence angle of several random points within the useful range of each coordinate system. Azimuthal projections are skipped as the grid scale functions in these cases usually return scale factors along and normal to radials from the origin. An empirical means of calculating these scale factors eludes us at the current time.
Test C - This test tries very hard to produce a floating point exception. Very regular and randomly generated coordinate values, both geographic and cartesian, are generated and passed to all functions for each coordinate system in the coordinate system dictionary. The coordinates are, in most cases, completely outlandish numbers. Reporting floating point exceptions is very difficult, however, varying from compiler to compiler, system to system. However, CS-MAP has passed this test many times, on four different compilers.
Test D - This test tests the forward and inverse functions of each projection against each other. That is, random geographic coordinates within the useful range of each coordinate system are converted to cartesian form using the forward function, and then back to geographic using the inverse function. The results are then compared.
Test E - This test performs all the functions of Test D; but in this case the useful range of each of the projections is reduced by about one half, and thus enabling the error tolerance to be substantially reduced.
Test F - Test F tests the CS_atof and CS_ftoa functions in two phases. First, the standard system function sprintf is used to check the operation of the CS_atof function. In the second phase, CS_atof is used to test the CS_ftoa function. Neither phase, currently, tests the operation of the degree, minute. and/or second processing.
Test G - Test G is the coordinate creep test. Creep is defined as the number of millimeters a coordinate moves after repeated conversions from cartesian to geographic and back. Test G starts with a specific cartesian coordinate well within the useful range of a projection (but certainly not the natural origin) and converts the coordinate to geographic and back to cartesian 1,000 times. The distance between the original coordinate and the final result is calculated in millimeters to arrive at the creep value. A creep value greater than 10 is considered a failure. As of release 8.01, only the four most used projections are tested.
Test S - This is not really a test, per se, but a request that the test program switch its mode with regard to byte ordering. Thus, on an little endian processor such as Intel, the initial S in a test sequence will cause all binary data files to be swapped to big endian byte ordering and the CS_bswap module adjusted to cause the necessary byte swaps for the program to function. Thus, all byte swapping mechanisms can be tested on a single processor. Since the byte swap algorithm is its own inverse, a second occurrence of Test S reverses the effect of a previous execution. Note, including an odd number of S specifications in the test specification will leave all dictionary files in a swapped condition.
Test V - This is not a test. Occurrence of a V in the test string simply toggles the verbose flag. Thus, the verbose flag can be turned off , or on, for specific tests individually.
Test Z - This is not a test. When TEST encounters this character in the test sequence, it simply starts the test sequence again from the beginning. Thus, an infinite loop can be established. Typically, a CONTROL-C is used to terminate the program at some point.

Test Data

The TEST.DAT file specifies the actual coordinates which are to be converted and the expected results. TEST ignores empty lines in the file and lines which begin with the pound sign (#) character. Other records are expected to contain 8 fields separated by commas. The eight fields are expected to contain:

Key name of the coordinate system of the coordinates specified in fields 2 and 3 of this line. That is, the name of the source coordinate system of the test conversion to be performed.
& 3. The X and then Y coordinates to be converted. These are expected in decimal form and are converted to binary using the CS_atof function of the CS-MAP library. Thus a variety of forms can be used.
Key name of the coordinate system to which the coordinates given in fields 2 & 3 are to be converted.
& 6. The expected X and Y coordinates of the conversion. Again, any form acceptable to CS_atof can be used.
& 8. The X and Y tolerance within which the converted values must agree with the expected values. If the converted values do not match the expected values within the specified tolerance, a diagnostic message is printed.

Most conversion examples provided in TEST.DAT were obtained from reputable sources other than CS_MAP itself. Comments in the TEST.DAT file itself will indicate those specific tests which have not been verified with sources outside other than CS-MAP. The tolerance values given in the provided TEST.DAT file should not be considered as an indication of the accuracy or precision of the CS-MAP library. Rather, these values usually indicate the accuracy and precision of the source data from which the examples were obtained. Occasionally, the tolerance values do indicate the accuracy of the CS- MAP library; comments in the TEST.DAT file indicate when this is the case.

Other Command Line Options

Finally, the /v option can be used to cause TEST to operate in verbose mode. In this mode, TEST will report its progress through each test. In order to enable use of TEST as a Windows NT console application, TEST normally requires an acknowledgment when all tests are complete. The /b option can be used to suppress this feature. The /s option can be used to instruct TEST to start out in big endian mode; useful when testing the automatic byte swapping feature. Use the /d option to provide TEST with the full path to the directory containing the binary dictionary files it is to use. In the absence of this option, TEST uses the directory encoded into the CSdata module; except that if a valid COORDSYS file exists in the directory from which TEST was executed, that directory is used (MS-DOS only). Use the /p option to indicate the length of the performance test (i.e. Test 5). The value provided is multiplied by 10,000 to obtain the number of conversions which are performed and timed in order to produce the conversion rate.

BUGS

Test C, the floating point exception test, does not exercise the datum conversion functions as yet.

mfcTEST -- MFC Dialog TEST

mfcTEST

mfcTest is designed to test the MFC based GUI interactive dialogs provided with CS-MAP. The program is a simple dialog box MFC program which contains a menu. The single menu entry provides a selection for each of the primary dialogs provided. Note also, that the Test dialog can be very convenient for testing projection and datum shift calculations in an interactive environment (assuming you're using Windows, of course).

This test program requires no arguments. All testing must be done in an interactive manner. Note, that each of the dialogs has a help button, and expects to find the help file in the same directory as the primary mapping data files. The help buttons are grayed out if the help file does not exist in this location.

Dictionary Differences Program

The source to Dictionary Difference program, DictDiff, is conveyed in a file named CS_DictDiff.c; the distribution places this file in the Dictionary directory. The main module calls functions named CS_csDiff, CS_dtDiff, and CS_elDiff which are defined in a module named CSdictDiff.c which the distribution deposits in the Source directory. These three functions are a part of the normal library build.

Messages which report differences refer to "was" and "is". That is, messages report the previous value and the new value for all detected changes.

DictDiff is a command line program and can used in virtually any environment that supports a C compiler. It compares the binary forms of dictionary files and reports all differences detected. It requires exactly two positional arguments. The first command line argument is the directory containing the "was" or previous dictionary files. The second argument is the directory of the "is" or current dictionary files. All messages are reported to stdout, i.e. the terminal.

In producing the differences, some tolerance numbers had to be chosen to delineate what a change consists of. You should examine the source code in file named CSdiffDict.c to verify that you are comfortable with the tolerance values that were chosen. The tolerance values are manipulated throughout the program, but the variable name okValue is consistent.