Printed on 20 March, 2009
User's Guide
CS-MAP User's Guide
Copyright (c) 2008, Autodesk, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided
that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the
following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Autodesk, Inc. nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written permission.
THIS DOCUMENTATION AND THE SOFTWARE IT DOCUMENTS IS PROVIDED BY Autodesk, Inc. ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL Autodesk, Inc. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
i
Contents
Chapter 1 Chapter 1 -- Distribution/Release Notes 9
Current Manual Status................................................................................................................................10
The Distribution..........................................................................................................................................12
Include Directory.............................................................................................................................13
Library Source Code........................................................................................................................13
Dictionary Source Code and Data ...................................................................................................14
Test Source Code and Data .............................................................................................................15
Documentation Directory ................................................................................................................16
Data Directory.................................................................................................................................16
Make Procedure...............................................................................................................................16
Release Notes for CS-MAP 12 ...................................................................................................................20
Chapter 2 Chapter 2 -- Descriptions and Discussion 21
Overview ....................................................................................................................................................21
Initialization.....................................................................................................................................22
High Level Interface........................................................................................................................22
Coordinate System Dictionary.........................................................................................................23
Other Interfaces...............................................................................................................................24
Other Dictionaries ...........................................................................................................................24
Cartographic vs. Geodetic Referencing of Coordinate Systems......................................................25
Latitudes and Longitudes.................................................................................................................26
Coordinate Arrays ...........................................................................................................................27
Selected Source Code......................................................................................................................28
Naming Conventions..................................................................................................................................28
Name Collisions ..............................................................................................................................28
Projection Code Names...................................................................................................................30
High Level Interface...................................................................................................................................32
Basic Coordinate Conversion -- CS_cnvrt.......................................................................................33
Grid Scale Factor -- CS_scale .........................................................................................................34
Convergence Angle -- CS_cnvrg.....................................................................................................34
Data Directory -- CS_altdr ..............................................................................................................35
Recover System Resources -- CS_recvr..........................................................................................35
Get Error Message Text -- CS_errmsg ............................................................................................35
Compute Azimuth and Distance -- CS_llazdd.................................................................................35
Unit Lookup -- CS_unitlu................................................................................................................35
Coordinate System Name Verification – CS_csIsValid..................................................................36
Datum Name Verification – CS_dtIsValid......................................................................................36
Ellipsoid Name Verification – CS_elIsValid...................................................................................36
Low Level Functions..................................................................................................................................36
Cartographic Projections .................................................................................................................36
Geodetic Datum Shift Functions .....................................................................................................42
General Utility Functions ................................................................................................................43
Error Handling............................................................................................................................................47
Data Structures............................................................................................................................................48
Ellipsoid Definition Structure..........................................................................................................48
Datum Definition Structure .............................................................................................................48
ii Contents
Datum Composite Structure ............................................................................................................49
Coordinate System Definition Structure..........................................................................................49
Preprocessed Projection Structures..................................................................................................49
Coordinate System Parameter Structure..........................................................................................50
Projection Name Table Structure.....................................................................................................50
Datum Shift Definition Structure.....................................................................................................51
The Data Dictionaries.................................................................................................................................51
The Coordinate System Dictionary .................................................................................................52
The Datum Dictionary.....................................................................................................................52
The Ellipsoid Dictionary .................................................................................................................53
Dictionary Encryption .....................................................................................................................53
Dictionary Definition Protection .....................................................................................................54
Byte Ordering..................................................................................................................................55
Dictionary Compiler........................................................................................................................55
Multiple Regression Datum Transformation Files ..........................................................................55
Default Datums, Ellipsoids, and Units ............................................................................................56
High Performance Interface........................................................................................................................57
The Functions..................................................................................................................................57
Coordinate System to Coordinate System.......................................................................................60
The LL Coordinate System..............................................................................................................61
Multiple Conversions ......................................................................................................................61
Adding Datum Conversions to the Interface ...................................................................................62
Geodetically Referenced Coordinate Systems.................................................................................63
Cartographically Referenced Coordinate Systems ..........................................................................63
Cartographic Projections .................................................................................................................64
Program Environments ..............................................................................................................................64
Multi-Threaded Programming.........................................................................................................65
GUI Considerations.........................................................................................................................66
Customization.............................................................................................................................................66
Tuning the Protection System..........................................................................................................66
Turning of Unique Names...............................................................................................................67
Eliminating a Projection..................................................................................................................67
Data Dictionary Directory ...............................................................................................................67
Dictionary File Names.....................................................................................................................67
Adding Units ...................................................................................................................................67
Language Translation ......................................................................................................................68
Chapter 3 Chapter 3 -- Executables 69
CS_COMP—Coordinate System COMPiler ..............................................................................................69
Byte Ordering..................................................................................................................................70
Source File Formats.........................................................................................................................70
TEST -- TEST program..............................................................................................................................78
Individual Tests...............................................................................................................................78
Test Data..........................................................................................................................................81
Other Command Line Options ........................................................................................................81
BUGS ..............................................................................................................................................82
mfcTEST -- MFC Dialog TEST .................................................................................................................82
Dictionary Differences Program.................................................................................................................82
Chatper 4 -- Library Functions 83
High Level Interface Functions ..................................................................................................................83
CS_altdr ALTernate DiRectory.......................................................................................................83
Contents iii
CS_atof Ascii TO Floating point.....................................................................................................84
CS_azddll LatLong Azimuth Distance calculator ...........................................................................86
CS_azsphr AZimuth on a SPHeRe..................................................................................................87
CS_cnvrg CoNVeRGence function.................................................................................................87
CS_cnvrt generalized CoNVeRT function......................................................................................88
CS_cnvrt3D 3D generalized CoNVeRT function............................................................................88
CS_csEnum Coordinate System ENUMerator................................................................................88
CS_csIsValid Coordinate System key name Is Valid......................................................................89
CS_csRangeEnum Coordinate System Useful Range Enumerator ................................................90
CS_csRangeEnumSetup Coordinate System Range Enumeration Setup.......................................90
CS_dtEnum DaTum ENUMerator ..................................................................................................91
CS_dtIsValid DaTum key name Is Valid........................................................................................92
CS_elEnum ELlipsoid ENUMerator...............................................................................................92
CS_elIsValid ELlipsoid key name Is Valid.....................................................................................93
CS_errmsg ERRor MeSsaGe...........................................................................................................93
CS_erpt Error RePorT.....................................................................................................................94
CS_fast FAST mode........................................................................................................................94
CS_ftoa Floating point TO Ascii.....................................................................................................94
CS_geoctrSetUp GEOCenTRic setup ............................................................................................96
CS_geoctrGetXyz GEOCenTRic GET XYZ .................................................................................97
CS_geoctrGetLlh GEOCenTRic GET LatLongHgt.......................................................................97
CS_getCountyFips Get County Federal Information Processing Standard code............................97
CS_getDataDirectory GET DATA DIRECTORY..........................................................................98
CS_getDatumOf Get Datum of a Coordinate System ....................................................................98
CS_getDescriptionOf Get Description of a Coordinate System.....................................................98
CS_getEllipsoidOf Get Ellipsoid Of a Coordinate System ............................................................99
CS_getReferenceOf Get Reference Of a Coordinate System.........................................................99
CS_getSourceOf Get Source Of Coordinate System......................................................................99
CS_getUnitsOf Get Units of a Coordinate System.......................................................................100
CS_getElValues Get Ellipsoid Values..........................................................................................100
CS_getCurvatureAt get CURVATURE AT specified latitude.....................................................100
CS_isgeo IS GEOgraphic..............................................................................................................101
CS_llazdd Lat/Long to AZimuth and Distance calculator.............................................................101
CS_llFromMgrs calculate Lat/Long FROM MGRS......................................................................102
CS_mgrsFromLl calculate MGRS FROM Lat/Long.....................................................................102
CS_mgrsSetUp MGRS SETUP.....................................................................................................102
CS_recvr RECoVeR resources......................................................................................................103
CS_scale grid SCALE factor function...........................................................................................103
CS_scalh grid SCALE factor(H) function.....................................................................................103
CS_scalk grid SCALE factor(K) function.....................................................................................104
CS_setHelpPath SET HELP PATH..............................................................................................104
CS_spZoneNbrMap State Plane ZONE NumBeR MAPper..........................................................104
CS_unEnum UNits ENUMerator..................................................................................................105
CS_unitlu UNIT Look Up.............................................................................................................105
High Performance Interface......................................................................................................................106
CS_audflt Angular Unit DeFauLT ................................................................................................106
CS_cs2ll Coordinate System TO Latitude/Longitude ...................................................................107
CS_cscnv Coordinate System CoNVergence................................................................................107
CS_csdef Coordinate System DEFinition locator..........................................................................107
CS_csdel Coordinate System definition DELete...........................................................................108
CS_csEnumByGroup Coordinate System ENUMerator By Group ..............................................109
CS_csGrpEnum Coordinate System GRouP ENUMerator...........................................................110
CS_csloc Coordinate System LOCate and initialize .....................................................................110
CS_cssch Coordinate System SCale H, along a meridian.............................................................112
CS_cssck Coordinate System SCale K, along a parallel ...............................................................112
