CS-MAP, Release 11.15

		Release 11.15 Changes
EPSG 6.11.2 Update

EPSG number mapping has been updated to EPSG release level 6.11.2. The flags return value from the mapping functions has been updated to indicate deprecation of an EPSG definition. Several new definitions, extracted from EPSG 6.11.2, have been added to the distribution dictionaries.

Well Known Text Update

Several improvements have been made to the Well Known Text (WKT) processing capability. This includes flavor updates and enhanced mapping of ESRI and Oracle names to CS-MAP definitions. The testing of WKT has been enhanced to include comparison of definitions generated by processing WKT definitions with the existing CS-MAP definitions to which they are mapped. This enhanced testing has located several discrepancies in the various sources of definitions. As a result, the traditional test program will almost always produce errors. Removing this error reporting to produce a clean test sequence was considered, but not implemented. Not only would this reduce the value of the test, but it also comforting to know that the testing procedure is active and actually locating some problems.

At this time, the name mapping update is limited to those definitions supported by EPSG 6.11.2. Definitions specific to various vendors using WKT have not been generated or tested. This remains a non-trivial task requiring much manual integration. Many hours have been expended with the goal of an process which would automatically and accurately map definitions from all known sources. Such efforts have not produced success; and we are convinced that such is not possible given the economic constraints.

This testing procedure indicates that none of the traditional sources of definitions was immune from a bust or two, including CS-MAP. The distribution dictionaries include several changes resulting from this analysis.

Three new functions have been added to support integration of WKT into applications:

	CS_wktCsDefFunc
	CS_wktDtDefFunc
	CS_wktElDefFunc

These functions are designed to be used with the dictionary hook function pointers:

	CS_usrCsDefPtr
	CS_usrDtDefPtr
	CS_usrElDefPtr

Executing code such as follows enables applications to pass WKT strings directly to the standard CS-MAP API in the same manner as providing a coordinate system, datum, or ellipsoid name:

	CS_usrCsDefPtr = CS_wktCsDefFunc;
	CS_usrDtDefPtr = CS_wktDtDefFunc;
	CS_usrElDefPtr = CS_wktElDefFunc;

Access to the standard WKT processing functions remains available.

It appears that the association of numbers with ESRI and Oracle datums is of little value, as they change as EPSG updates its database. Thus, the concept of ERSI and Oracle "ID Numbers" with regard to datums has been removed.

DHDN To ETRF89 Transformation

The grapevine has indicated that the German authorities will soon be publishing a grid shift data file for transforming DHDN to ETRF89 applicable to German geography. While such a file has not been published as yet, provisions for such have been added to CS-MAP. Since a data file was not available at the time of release of 11.15, this implementation has only been superficially tested. It is only hoped that once such a file is made public that no further code changes will be required to implement the new feature.

This implementation includes a new Geodetic Data Catalog file named DhdnToEtrf89.gdc. The official name may use the designation ETRS89 instead of ETRF89. We have used ETRF89 to remain consistent with similar transformations which apply to other geographic areas in Europe. Technically, we believe ETRF89 is the more "correct" name to use.

x64/Linux Compilation

This release of CS-MAP has been compiled and tested in the Microsoft VC++ 8.0 x64 environment. It has also been compiled and tested in the Linux environment using the gcc (version 3.3) compiler. A large number of source code modules were changed in order to enable a single set of source to be compiled for these different environments with minimal warnings.

For a handful of modules, the use of uppercase letters in the module file name was standardized to facilitate compilation in the Linux environment where file names are case sensitive.

Affine Post Processor for Lambert Conformal Conic

CS-MAP has supported the Transverse Mercator with Affine Post Processor for some years now. The Affine Post Processor feature has now been added to the Lambert Conformal Conic projection. Code name is "LMAF." The new variation accepts an additional six parameters which are the same as the Transverse Mercator equivalent.

Krovak Axis Changes

The "official" definition of the Krovak projection stipulates that the northing is the first coordinate and the easting is the second coordinate. This tended to produce maps which were rotated and largely unusable. While this behavior could be modified through the use of the quad projection parameter, suggestions by end-users has lead us to modify the projection code to produce the normal easting/northing coordinate order. Those requiring the original behavior can still achieve such through the use of the quad projection parameter.

It was also determined that the Krovak95 implementation was not in general use. To be compatible with the more widely used techniques for conversion of Czech coordinates to ETRF89 or equivalents, this projection system and related datum definitions has been deprecated. New datum definitions have been added to accomplish the desired datum shifts.

EPSG Number Added to Dictionary Definitions

Previously unused elements of the dictionary definition structures have now been allocated to carry the appropriate EPSG number associated with the definition. This is now populated for new definitions extracted from the EPSG database. Previously existing definitions will have a zero for epsgNbr until a future release. The dictionary compiler will now accept an EPSG: designation for all three primary definitions.

CS_getCurvatureAt Function

CS_getCurvatureAt is a new function which will return the Gaussian curvature for a coordinate system at a specified latitude. The function extracts the ellipsoid to be used from the coordinate system definition provided by the argument. The returned value is in meters and is useful for surveying programs which need to calculate the so-called "triple scale factor".


			Release 11.14 changes:

How the Mercator, Eckert IV, and Eckert VI  projections deal with the ±180 degree crack has been corrected.  These projections will now always cause the central meridian to appear in the center of the resulting map.

A new function has been added to enable applications deal with the new ESRI .wld files.  That is, another form of the .trf files, both referred to as world files.  The function prototype is:

int CS_wldCalc (double* AA, double* BB, double* CC, double* DD,
			    double from1 [2],
			    double to1 [2],
			    double from2 [2],
			    double to2 [2]);

The return values AA, BB, CC, DD are calculated so that the following code:

   to [0] = AA + CC * from[0] + DD * from[1];
   to [1] = BB - DD * from[0] + CC * from[1];

is valid for each of the provided two points.  AA and BB are translation values.  Read CC as being k*cos(theta) and DD as being k*sin(theta) where k is the uniform scale factor (same for X and Y axes) and theta is the rotation angle (in radians  of course).  Rotation is about the origin, scaling relative to the origin.

A new variation of the Nerth (i.e. MapInfo non-Earth equivalent) has been added which supports five additional parameters.  The key name of the projection is NERTH-SRT.  The additional parameters are:

Nerth Scale: Scale factor to be applied to the coordinates of all 		points, scale is applied relative to the rotation/scale origin defined by parameters three and four.

Nerth Rotation Angle: Rotation angle, in degrees, to be applied to the coordinates of all points.  Rotation is applied relative to the rotation/scale origin defined by parameters three and four.

Scale Rotation Origin X Value: X coordinate of the point in the coordinate system being defined about which data is to be rotated and scaled.

Scale Rotation Origin Y Value: Y coordinate of the point in the coordinate system being defined about which data is to be rotated and scaled.

It is intended that this new projection may be useful in dealing with local coordinate systems.

The Spanish transformation of ED50 to ETRF89 has been re-activated.  In a previous release this was deactivated (still present in the code but removed from the distribution definitions).  Deactivation was the result of numerous service calls about the definition while we were unable (despite an awful lot of searching) to find confirmation that: 1) this transformation was officially sanctioned, and 2) that it was permissible to distribute the datum shift file.

These issues have now been resolved.  We are permitted to distribute the datum shift file, and the transformation is indeed being promoted by Instituto Geográfico Nacional of Spain.  We have reactived this, but in the form of a new definition named �ED50-IGN.ES�.  It would be nice if other European governments adopt the Canandian NTv2 transformation technique for their own ED50 to ETRF89 transformations.  If this does happen, one only need to add the file name and location to the Ed50ToEtrf89.gdc file.

Several new coordinate systems have been added to the distribution definitions.

Release 11.13 changes:

Release 11.13 includes a diagnostic facility.
The global variable csDiagnostic is of type
FILE* and set to the null pointer by default.
Set this global variable to point to an
appropriate stream to obtain a diagnostic
data capture.

How the Miller projection handles the wrap-
around problem is now much more in line with
user expectations.

A new projection, Winkel-Tripel has been added;
it requires that the user define the standard
parallel; the normal valueis 50 degrees, 20
minutes.

A new formulation of the Transverse Mercator
has been added, the Kruger Formulation.  This
formulation provides higher accuracy at large
distances (ten degrees or more) from the
central meridian as is common in Sweden.

Several new datum and coordinate system definitions
have been added.

Release 11.12 changes:

    IMPORTANT  LICENSE  NOTICE

Please note that in your license agreement,
MSI indemnifies the LICENSEE from all damages
incurred by your use of the CS_MAP code.  In
this release Mentor supplies you with two new
modules, CS_esri,c and CS_oracle.c, only under the
condition that you waive these provisions of the
license agreement with regard to your use of either
of these two modules.

Release 11.12 includes the ability to read WKT
of the Oracle flavor and the ability to convert
ESRI and Oracle definitions and code numbers
to EPSG code numbers and vice-versa.  A WKT
memory leak was plugged.

I did indeed intend to update the documentation
which accompanies this release.  However, due to
an instance of DLL Hell, my documentation program,
AuthoriIT, is currently inoperative on the system
I use to maintain CS-MAP.  Rather than delay this
long awaited (by at least one client anyway)
release I simply use this ReadMe.txt file to
indicate what the the changes are, and where you
can find the information you need.

The basic changes are as follows:

1> There is now a new WKT flavor, 'wktFlvrOracle'.

2> There is now a CS_esri.c module.  It contains
data tables and functions which can be used to map
ESRI definition names and/or code numbers to EPSG
code numbers.  (EPSG code numbers can then be
mapped to MSI names.)  Additionally, an ESRI datum
name can be mapped to either an EPSG code number or
an MSI (Mentor Software, Inc.) name.  This latter
feature is helpful as there are several ESRI datum
names for which there is no EPSG equivalent, but
for which there is an MSI equivalent.  Please
examine the source code for this module for current
documentation.  This is very very basic stuff, not
much high tech here.  The value is in the effort
required to produce the data tables.

3> Similar to the above, there is now a CS_oracle.c
module.  This module provides the data and functions
necessary to convert Oracle definition names and/or
code numbers to EPSG code numbers, and in the case of
datums, EPSG code numbers or MSI names.

Please note that in both of the above cases, a fetch
by index function is available.  Using these
functions, it is possible to populate, for exampel,
a Combo Box with ESRI or Oracle names or numbers and
let the user choose from the list.

Release 11.11 changes:

Some time ago, we were provided with a data file
which indicated that the Spanish government had
adopted the Canadian file format and instituted
an official conversion from ED50 to ETRF89 using
same.  We incorporated this enthusiastically
thinking we would be ahead of the game for once.
Since that time, we have been unable to verify
that this conversion is officially adopted.

Therefore, in this release, we remove the
Ed50ToEtrf89.gdc file, and modify the ED50
datum definition to use the Seven Parameter
transformation technique.  This removes
references to the sped2et.gsb data file
which we have a copy of, but do not have
permission to distribute.

Release 11.10 includes:

1. Two new functions have been added to provide
conversion between Mentor Software, Inc. coordinate
system names and EPSG code numbers.  The functions
are: CS_msi2epsg and CS_epsg2msi.
2. Two new functions have been added which support
the conversion of Well Known Text (WKT) to Mentor
Software definitions and vice versa.  The function
names are: CS_wkt2msi and CS_msi2wkt.
3. The four new functions have been added in such a
manner that they can be exported in a DLL (like
Mentor's own .DLL products).
4. The EPSG:???? type names applied to EPSG definition
conversions have been replaced with "real" names, and
the duplicate definitions have been removed.
5. Functions exist now exist to convert between Mentor
key names and EPSG code numbers for ellipsoids and
datums, in addition to coordinate systems.
6. An error in the WKT to CS-MAP conversion was
corrected.  Previous to 11.10, the origin longitude
was not always converted correctly.
7. The association of a base coordinate system with
its referenced datum is now performed by a function
which is 100% reliant on the dictionaries; the mapping
table has been eliminated.
8. A deferred close mode has been implemented for each
of the dictionaries.  CS-MAP's heritage includes the
days when the number of files which a process could
have open simultaneously was severely limited.  Thus,
CS-MAP opened and closed the dictionary files for
each access.  On newer systems, which virus checkers
and such, the constant opening and closing can become
very burdensome.  You may now set a flag to activate
a "leave the dictionary open" mode for each dictionary.

Release 11.09 includes:

1> Several additional functions for reading and
writing coordinate system, datum, and ellipsoid
definitions in the Well Known Text (WKT) format.

2> Release 11.09 uses the new revision (1999)
of the C++ STL standard, and compiles with
Version 7 of Micros??t's Visual C++ Version 7.
Also links with MFC Version 7 libraries.

3> Release 11.09 supports geoid99 type data
files in big endian byte order.  The NGS's
geoid 2003 data files are in big endian order.

4> Release 11.09 dictionaries include definitons
converted from version 6.03 of the EPSG
database.

Release 11.08 was never actually released.

Release 11.07 includes:

1. Several new functions for reading and writing
coordinate system, datum, and ellipsoid definitions
in the Well Known Text (WKT) format.  The following
lists the new functions, check the documentation
file for details on these functions:

Function Name	Brief Functional Description
CS_wktToCs	Converts a WKT string to cs_Csdef_
CS_wktToDt	Converts a GEOGTRAN WKT object to cs_Dtdef_
CScs2Wkt	Converts a cs_Csdef_ to WKT format
CSdt2Wkt	Converts a cs_Csdef_ to WKT format
Csel2Wkt	Converts a cs_Eldef_ to WKT format

The WKT implementation includes a C++ object named
TrcWktElement which may be useful to the application
developer.  See rcWellKnownText.hpp for the
declaration of this object.  Much of this WKT code
is written in C++ and is available only if you compile
with C++ active.  You will also need to define __CPP__
in order to have the WKT features compiled.

2. Modifications have been made to CS-MAP such that
it is compatible with the following:
   * Visual C++ Version 7.0 (this is .NET 2002).
   * MFC Version 7.0
   * Compliant with the STL portions of the ANSI/ISO Standard C++ (ISO/IEC 14882)

Release 11.06 was never actually released.

Release 11.05 includes:

1> Correction for a problem in converting
between NAD27 and NAD83 at the western
extremes of Alaska (i.e. Alutetian Islands).

2> Fixed an error which placed Pulaski County,
Arkansas, in the wrong state plane zone.
Pulaski COunty is now correctly coded as being
in the South zone.

3> Added the Useful Range Enumeration feature.
See CS_csRangeEnum in the help file.

4> This distribution includes the new Australian
datum grid shift files; one file for each datum
that covers the entire continent.  No more
overlapping files.  This change did not require
any programming changes.  However, the .gdc
files for Australian have changed, and the
Test.dat (i.e. validation suite) file has
changed as the numbers produced by the new files
are not identical (very close, but not identical)
to the results produced by the old files.
 
Release 11.04 includes:

Updated dictionary definitions for Malaysia.

New feature kludged into Nad27ToCsrs to
properly handle Maritime Provinces of
Canada.  Note that this feature requires
placing a reference to a .gdc file within
another .gdc file.  Wierd, but it works
and is only necessary for the Maritime
Provinces of Canada.

Some changes to improve portablility of
code to Unix platforms.

Release 11.03 includes:

1> A new variation to the Oblique Mercator.
This variation accepts the Skew Azimuth at the
Rectified Origin.  Currently, our version of
the RSO accepts only the Azimuth of the
Central Geodesic at the Projection Center.
This is useful in Malaysia.

2> A defect in the coordinate system update
function was correct.  The problem would be
evident only when updating a user defintion
prior to user protection being activated.

3> A confirmation is now requried before
deleting a dictinary definition using the
MFC dialogs.

	CS-MAP, Release 11.02

Release 11.01 did not survive testing and was
never released.  The first official release in
the major release 11 is 11.02.
   

Norm has a new e-mail address.  The old one had
been around so long, that the spam and viruses
were intolerable.  New e-mail address is:

    norm@rockware.com

While Mentor and Rockware are particiapting in a
joint venture, Mentor and Rockware are separate
entities.  As part of the joint venture, Mentor
gets office space, accounting and financial
services, marketing services, and Internet
presence.  RockWare has an exclusive license
to market Mentor's retail products and earns
a commission on all retail sales.

Regardless, Rockware and Mentor remain two
independent entities as far as CS-MAP is concerned.

Release 11.01 is an official release which is compilable
under many additional platforms without modification.
Platforms specifically supported now are:

A> Windows 32
B> Windows CE
C> Sun Solaris
D> HP UX
E> IBM AIX
F> Apple MS X DOS

Please note, we have to rely on client input to keep
C thru F maintained.   Your input is greatly
appreciated.

It turns out that I have been lying for many years now.
I have been claiming that CS-MAP was ANSI compliant.
Well, I don't think it used to be; but I think it is
now.  It is difficult to tell as what one compiler
considers ANSI standard is considered non-standard by
other compilers.  In any case, we're a lot closer now
than we have been in the past.  There are some ANSI
standard violations, but these are all dealt with in
the source module named CS_ansi.c

Release 11 includes an MFC based dialog which can be
used to edit the new .GDC files.  Of course, this
release also includes all of the following features
which were made available in various minor releases of
Release 10:

1> Add support for the NAD27 to CSRS direct datum
   conversion.

2> Add support for the Spanish ED50 to ETREF89 datum
   conversion via grid shift file.

3> Add support for the direct conversion from NAD27 to
   ATS77 using the TRANSFORM algorithm.

4> Add support for the 13th order of the Danish System 34
   conversion.  This is referred to as Sys34-99.

5> Add support for the 2002 version of the Ordnance
   Survey datum conversion.  (Geoid height 2002 is not
   supported as yet.)

6> Add capabaility to convert direct from ATS77<->CSRS.
   This replaces the former:
   ATS77<->CSRS<->NAD83<->WGS84<->NAD83<->CSRS

7> Add support for run-time (non-persistent) additions
   to the internal unit table.  Unit table modifications
   include addition of a "plural unit names".

8> Fixed the "NewBrunswick" coordinate system; the false
   easting and false northing have been erroneously swapped
   for some time now.

9> A variation of the Azimuthal Equidistant projection
   wherein parameter 2 is the average elevation.  This
   value can be used to essentially elevate the system
   to account for the average elevation.

10> Support for the French datum shift which we will
    call RGF93.  I don't know any French, so I won't
    suggest what any of that means.

11> Support for the new Irish ITM and the multiple
    regression datum technique for converting
    Irish 1975 to ETRF89.

12> Corrected a circular list problem in the VERTCON
    code.

13> Multiple file/datum Australian GDA94 capability.

14> support for the Canadian ATS77 datum.

15> support for the Canadian CSRS datum.

16> support for the Military Grid Reference System
    (MGRS).

17> support for the Transverse Mercator with Affine
    Post-Processor.

18> support for Danish System 34/45.

19> support for OSTN97.

20> support for OSGM91.

21> support for GEOID99.

22> support for Hungarian EOV.

23> support for Japanese Geodetic Datum of 2000.

24> support for Canadian geoid height data files
   (.byn files).

25> provisions have been included to enable clients
    to manage system dependencies without having
    to modify CS-MAP distribution code.  Look at new
    distribution files named: cs_clientBeg.h,
    cs_clientEnd.h, and CS_system.c.

* * * N O T E * * * N O T E * * * N O T E * * *
The source file CS_geoid.c has been removed from
the distribution.  This is legacy code, and is no
longer used.  Should you need a copy, contact
Mentor.

Two modules which typically need not be part of
any distribution executable have been removed from
the make files.  These modules:

      CS_gdcGenerator.c
      CS_rlsUpdt.c

were typically used in an update module, should no
longer be necessary, and are not actually used in
the coordinate conversion code.  Thus, efforts to
port these modules are usually for naught.  This
will be the last release that these source modules
will be included in the distribution.

Many of the .gdc files in the distribution will have
all meaningful contents commented out.  We are not
permitted to distribute several of the files, so we
comment their reference out of the .gdc file to
prevent error reporting during the testing process.
Before distributing your product, please be sure the
distribution .gdc files jive with the rest of your
distribution.

CS-MAP distributions are now on CD and include those
datum shift and geoid height data files which are in
the public domain.  Mentor Software is not licensed to
distribute the data files for Version 2 of the Canadian
National Transform, the ATS77 to CSRS data file for
New Brunswick and related geography, or the OSTN97.txt
grid shift data file, or the OSGM91.txt data file.
If we were, we would have to charge a license fee for
its use anyway.  You will need to obtain a license to
use any of these data files.  Have your credit card
ready, there is a license fee.

Users of your application will also need to obtain
their own license to use this file if they desire/need
to convert Canadian geography from NAD27 to NAD83 or
or ATS77 to CSRS and vice-versa.

Should you have any questions, or discover a bug (or
what appears to be a bug) please call Norm at
1-888-ASK-NORM (1-888-275-6676).  Better yet, you
can email: norm@rockware.com.

Thanks for licensing CS-MAP.

Norm Olsen
Vice President, Engineering
Mentor Software, Inc.

2221 East Street, Suite 203
Golden, CO  80401
   -or-
P. O. Box 147
Golden, CO  80402

303-277-9967	[direct voice line]
303-278-4099 FAX  [RockWare's Fax]
888-275-6676  [Toll Free Tech Support]
norm@rockware.com