Distribution/Release Notes

Due to distribution permission issues, it was determined that the polynomial coefficients for the System 34 coordinate conversions could not be open sourced. Thus, to properly incorporate Syatem 34 capabilities into your application, you will need to obtain a copy of these coefficients for yourself. Refer to the source module named CSsys34KMS.c for details.

CSV File Support

Implemented as a C++ object, there now exists rather substantial support for reading and writing data file in the CSV (comma separated value) format.

EPSG Support

Still a work inprogress, there now exists substantial support for accessing data provided by the EPSG Parameter Dataset. As this dataset is traditionally distributed in Microsoft Access format, this facility relies on the conversion of all EPSG data tables to .CSV format, and uses the new CSV FIle SUpport object to access them.

WKT Flavor Support

Using the new Name Mapper facility, CS-MAP's ability to handle various flavors of WKT has been imporved. There is lots yet to be done, but a non-trivial improvement in the accuracy and number of flavors supported.

So, there remains much to do to bring this document up to the standard desired by the CS-MAP contributor team. For now, it's important to provide potential users with the basic information necessary to get started using CS-MAP.

The Distribution

Detailed instructions on how to obtain the distribution are available at http://trac.osgeo.org/csmap/wiki/HowToGetTheSourceCode

The distribution includes many somewhat voluminous grid data files known to OSGeo as being in the public domain. There are several such grid data files which are not in the public domain and which must be obtained from the source on an individual user basis. Simple registration is all that is required in many cases, license fees are rarely required. Mostly, the issuing authority just wants to keep track of who is using the data in order to adhere to ISO quality control standards.

The Canadian National Transformation data file is, perhaps, the most widely used example of a grid data file which OSGeo is not permitted to distribute. You and your clients will need to obtain this file from the Canadian government. A license fee is no longer required, but Geomatics Canada still needs to know who is using the data file. Contact: www.geod.nrcan.gc.ca

Since the distribution cannot include a copy of the Canadian National Transformation file, the test cases for this transformation are commented out in the provided TEST.DAT file. After obtaining the Canadian National Transformation file, you will probably want to uncomment these test cases from the test file.

Typically, a README.txt file is placed in the folder in which an undistributable grid data files would normally reside. THis text file will usually provide information as to how to obtain a copy of the data file. When a CS-MAP error message which indicates that a file is missing is encountered, check to see if there is not a README.txt file in the folder in which CS-MAP was looking for the file and examine its contents.

Source Layout

Include Directory

You don't need to be a genius to figure out that all header files are installed into this sub-directory. What might surprise you is that there is only one real header file: cs_map.h. While this file is quite large, the precompiled header feature of most modern compilers make this approach most convenient.

Also, you never have to guess in which header file a specific item is defined in. They're all defined in cs_map.h. Neither do you have to wonder which files must be included into your application; cs_map.h is the one. There are other include files, but are those required by the rather strange environment used for MFC development.

The cs_map.h header file will specifically include two files. The files, and exactly where they are included, are described below. These provide a means by which users can incorporate their own features without having to modify cs_map.h after each new release.

Library Source Code

The directory named Source will contain all source code to the library proper. The source code components of CS-MAP are normally compiled and the resulting objects used to construct an object module library. Source code to dictionary compilers and test programs are provided elsewhere. Make files for building the library are provided in this folder.

Each of the make files includes a list of all the modules that belong in the library. This list represents most of the drudgery of creating a make file. Adjust the actual rules as necessary for your platform/compiler. Notice that leaving the manifest constant __MFC__ undefined will cause all MFC related code to be skipped during the compilation process. Obviously, if compiling in an environment other than Windows 32/64, be sure to leave the __MFC__ constant undefined.

Dictionary Source Code and Data

The directory named Dictionaries will contain the source code to the dictionary compiler, and the data files which this compiler compiles to produce the binary form of the Category Dictionary, the Coordinate System Dictionary, the Datum Dictionary, the Ellipsoid Dictionary, and the Multiple Regression Transformation data files. Be sure to compile these dictionaries with the /t option if you intend to run the CS-MAP test program.

Make files for building the compiler are provided in this folder.

The distribution also uses this directory to convey sample Geodetic Data Catalogs which you will definitely want to inspect and perhaps modify. Geodetic data files which OSGeo believes to be in the public domain are deposited in sub-folders of this folder in a specific hierarchy. This hierarchy is consistent with the provided Geodetic Data Catalog (.gdc) files. There is no specific requirement for the location of the geodetic data files other than their location must be consistent with the specifications int he Geodetic Data Catalog files.

Also please note that the OSTN97.TXT and OSTN02.TXT data files must also reside in the primary data directory. Again, by design, there is only one file for each of these transformations, and the implementation of a Geodetic Data Catalog file was skipped. Also, due to the rather strange nature of these files, most of the features of a Geodetic Data Catalog file do not apply anyway.

Test Source Code and Data

The directory named Test will contain the source code to the CS-MAP test program and the supporting data file, TEST.DAT. Compilation and linking of this program will obviously require the inclusion of the header file and library. Make files for building the test program are provided in this folder.

In order to execute the entire test sequence, you will need to have compiled the dictionaries with the /t option. This causes the retention of the test coordinate systems (not normally distributed with an application) in the dictionary files. The test program will also expect to have access to the NADCON and HPGN data files provided in the sub-directories of the Dictionaries directory. When executing the test program, use the /d option to indicate the location of the directory in which the dictionaries, NADCON, and HPGN data files reside; e.g. /d..\Dictionaries.

This program performs a fairly substantial test of most all features and capabilities of CS-MAP. This program should be used each time CS-MAP is used in a new configuration or compiled with a different compiler.

Note that a large number of the tests encoded in the TEST.DAT file are commented out as they rely on the existence of specific geodetic data files which OSGeo cannot distribute. For example, since OSGeo cannot distribute the Canadian National Transformation, all test dependent upon that data file are commented out. Upon obtaining geodetic data files which Mentor Software cannot distribute, you should consider un-commenting the tests related to such files.

Documentation Directory

The directory named Documentation is where you will find a copy of this documentation. Depending upon the format, it may consist of a single file, or a directory containing multiple files. A printable version may also be present.

Additionally, this directory will contain the source code to the help file which is provided for use with the MFC based components of CS-MAP. The source code files include an .rtf file, a contents file (.cnt), and several screen shots in .bmp format. Again, a make file compatible with Visual C++ Version 6 (or later) nmake is provided; it is named help.nmk. (As the help file is not generally usable in the Linux environment, no Linux compatible make file is provided.) Note, that the CS-MAP MFC based functions expect to find the help file in the same directory as the mapping data files. Of course, a function exists which enables application programmers to override this default location (CS_setHelpPath). If for any reason, the MFC based functions cannot locate the help file, the help button on all dialogs will be grayed out.

Please note that the help file is designed for distribution with your application. It does not mention OSGeo, CS-MAP, or the original developers of CS-MAP. It uses a rather generic term "coordinate conversion system" to refer to that which it is describing.

Data Directory

Several data files used in the construction of CS-MAP's Name Mapper facility are included in the Data directory. It is envisioned that these files will be replaced by a more convenient and controllable means in the near future.