
Windsway Company is releasing some Geodesy oriented software as open souce
code. This is not a complete application but rather a set of routines that
you can use to build your own applications. The release consists of four
open source files:

  Mapstuff.bas       version 0.96
  Geodesy.cls        version 0.93
  WICUtilities.bas   version 0.90
  
The first two files must be included in your Visual Basic project.
WICUtilities.bas must be included if you want to use the Mapstuff.bas
function ParseLatLong() or the MaskEdit string builder and parser.

Geodesy Class file:

The class file (.cls) contains the physical definitions of the supported
datums and methods for retrieving the desired datum. Normally you need not
use these methods at all as the functions that need the datum dimentions
contain the necessary code to do this. However there is a function you can
call to get the data.

Mapstuff:

Mapstuff is the file that contains all the action. There are routines for
converting Latitude/Longitude to UTM coordinates and UTM Coordinates to 
Latitude/Longitude. There are implementations of T. Vincenty's Direct
and Inverse Solution of Geodesics on the Ellipsoid. There are standard 
VB data structures called Types that are used throughout Mapstuff.These
Types add order to the calling sequences of most of the routines. All 
Types and Routines are public. All the main functions return an error code
of type Integer to flag success or failure. The error codes are constants
in the definition section of the code. The code names all begin with 
WIC (for Windsway Instrument Company) and are ALWAYS Capitalized. A fuction
returning WICNOERROR has completed successfully (this does not necessarily
mean that the information returned is meaningful). any other error code
means something went wrong during the function call. The return codes for
each function are documented in a comment block at the beginning of the 
function.


Mapstuff.bas contains the following routine for your use:

 Antipod
 IsAntipodal
 
 The function Antipod returns the antipod of a point. The antipod is the
 point on the earth's surface that is diametrically opposite of a given 
 point.
 
 The function ISAntipodal determines if any given point is antipodal to any
 other given point. The function returns True of it is otherwise it returns
 False.
 
 ArcCos
 ArcSin
 ArcTan
 ATan2:
 
 These four routine simply implement the trigonometric function in a 
 way that is standard to my way of doing software. 
 
 
 ComputeZone:
 
 This function compute the zone data for any UTM zone. It expects a Type
 ZoneStruct and populates it with information concerning the UTM zone of
 interest. As with all the main functions in Mapstuff.bas, the function
 returns an error code of type Integer that signals success or failure. 
 
 Given the latitude and longitude of a place, ComputeZone will return
 the UTM central longitude of the place along with the zone number and
 zone letter of the place.
 
 Converge
 
 This function computes the convergence of meridians between two parallels
 of Latitude. The function returns the convergence in meters in the 
 GeoStruct component Distance (i.e. gs.Distance). DO NOT confuse this 
 function with the computation of the Grid North (convergence) in LL2UTM
 or UTM2ll.

 DegToRad
 RadToDeg:
 
 DegToRad converts an angle in decimal degrees to radians and RadToDeg
 converts an angle in radians to decimal degrees.
 
 
 DMSToD            
 DToDMS:
 
 DtoDMS converts an angle in decimal degrees to it constituant parts; 
 degrees, minutes and seconds. These components are returned a a DMS
 structure (byref). DMSToD converts an angle from degrees/minutes/seconds
 to decimal degrees.
 
 Sex2Deg:
 
 Sex2Deg converts an angle expressed in sexigesimal format:
  dd.mmsssss
 where dd is degrees, mm is minutes and sssss represents ss.ssss seconds
 into decimal degrees:
  dd.ddddd
 The function assumes that minutes are expressed as two digits and the
 first two digits of ss are the whole seconds and the balance of ssssss 
 are the decimal portion. The decimal portion of ssssss can be expressed
 to any reasonable number of places. Therefore dd.mmssssss expresses an
 angle of dd degrees mm minutes and ss.ssss seconds
 
 FmtDMS:
 
 FmtDMS converts decimal degrees dd.ddddd into a string dd mm ss.ssss
 or time expressed as hh.hhhhh into a string hh mm ss.ssss with the 
 appropriate symbols i.e. 23 34' 45.5678" or 23h 34m 45.5678s. User 
 specifies degrees or time and the number of decimal places for seconds.
 Decimal range from 0 to 5. If more than 5 places is specified, places
 is set to 5. FmtDMS is intended for printing or display purposes.

 FmtDMS1
 
 this Function formats angular and time quantities.
 Input:  x decimal value - function restricts number
                             of decimals to 5
         n number of digits to right of decimal
         l format of output string
             1 = decimal degrees
                 i.e. ddd.dddd (for n=4)
             2 = degrees and decimal minutes
                 i.e. ddd mm.mmmm (for n=4)
             3 = degrees, minutes and decimal seconds
                 i.e. ddd mm ss.ssss (for n=4)
         m = 1 formatting to degrees
         m = 2 formatting to hours
         
 FmtDMS1 is intended for printing or display purposes.
 
 NOTE: FmtDMS1 rounds at the last decimal place
 
 GetEllipseStuff:
 
 This function extracts the ellipse data for the requested datum from
 the arrays in the class file Geodesy.cls. It returns the ellipse's 
 major and minor axes as well as the ellipsoid name in an EllipseStruct. 
 
 
 GetDatumStuff
 
 This function extracts the datum data for the requested datum from the
 arrays in the class file Geodesy.cls. It returns the datum information in
 a DatumStruct. The intent of the inclusion of the datum data is to allow 
 the user of an application to get to the ellipsoid information through
 datum name which is commonly used in GPS receivers. The datumNumber is
 geoid number for the ellipsoid associated with the named datum. 
 
 Suggested use:
 
 Read the datumNames into a list box in your application and allow the
 user to select one and use its ListIndex+1 as the index for GetDatumStuff.
 Then use the datumNumber as the geoid number to get to the underlying 
 ellipse data eMajor, eMinor and eName using GetEllipseStuff
 
 GetFlattening:
 This function extracts the value if the ellipsoid flattening of the 
 requested datum and returns the inverse flattening (1/f). The values in
 the class module array rflat are the actual flattening values (f) and can
 be obtained by calling the get procedure eflat directly. The function
 returns WICNOERROR if successful else it returns WICBADGEOID
 
 LL2UTM
 UTM2LL:
 
 These functions are implementations of the algorithms presented in the 
 USGS Professional Paper 1395 "Map Projections - a Working Manual" by John
 P. Snyder.
 
 LL2UTM converts a position defined by a latitude/longitude pair to it's
 correspond UTM coordinates using a datum of the user's choice. The
 function returns the requested information in a UTMStructure and returns
 the error code WICNOERROR if no errors encountered in the conversion.
 
 UTM2LL converts a position described by a UTM Easting/Northing and zone
 to it's corresponding latitude/longitude. The requested information is 
 returned in a UTMStructure and the function returns WICNOERROR if 
 successful.

 ModAzimuth
 ModLatitude
 ModLongitude
 Modulus:
 
 These functions attempt to constrain their arguments to specific ranges.
 
 ModAzimuth constrains an angle (in radians) to the range of 0 <= angle
 <= 2*PI (0 to 360 deg). It is used for azimuths.
 
 ModLatitude constrains an angle (in radians) to the range -PI/2 <= angle
 >= +PI/2 (-90 deg to +90 deg). It is used for latitudes
 
 ModLongitude constrains an angle (in radians) to the range -PI <= angle
 >= PI (-180 deg to +180 deg). It is used for longitudes
 
 Modulus is my implementation of the Mod function for floating point
 numbers. It returns the remainder of the division of x/y as a double.
 
 ParseLatLong
 
 This function parses a string containing an angle and extracts the degrees
 minutes and seconds. The string must be in the format dd:mm:ss.ss or 
 dd:mm.mm or dd.ddd The string delimiters can be a colon (:) or a 
 semicolon (;) or a comma (,). The angle is returned as decimal degrees. 
 This function is useful for use with data entry into a text box. I use 
 the textbox KeyPress event to restrict input of degrees to digits, 
 delimiters and tab and backspace keys along with the valid delimiters
 so that ParseLatLong() will return the value of an angle passed to it 
 from TextBox.Text.

 Reciprocal:
 
 This function returns the reciprocal of an azimuth. Azimuth is in decimal
 degrees.
  
 Square:
 
 This function returns the square of a value, i.e. Square(x) = x * x
 
 
 VDirect
 VInverse
 
 These funcitions are the implementation of Vincenty's algorithms.
 
 Given the latitude and longitude of a point and the azimuth and distance
 to a second point, VDirect returns the latitude and longitude of the
 second point and the azimuth of the first point from the second. The 
 computed data is returned in a GeoStructure. The distance is returned
 in meters and the azimuth is the angle measured from true north.The 
 function returns the standard WICNOERROR if successful.
 
 Given the latitude and longitude of two points, VInverse returns the
 distance between the two points in meters and the azimuth of each point
 from the other. These azimuths are NOT reciprocals. The functions returns
 the standard WICNOERROR if successful.

Unzip the contents of Geodesy.Zip into a folder where you wish to run
the sample stuff. I have the VB project in a folder Geodesy on the VB 
path. This will create a sample project for you to use to test the
code. Read Geodesy.txt (actually this file - you are reading it now)
to understand the software and then run the samples that are created 
in your folder

I have included some simple code to illustrate how these routines might
be used in a VB program. Cut and paste the Command1.Click and 
Command2.click code (files Testxxx.txt) into the Geodesy project's 
(Geodesy.vbp) GeoTest.frm module in place of the ones that is currently 
there and run the program from the IDE. 

For the future:

I am currently working on a NMEA sentence tokenizer module that will 
extract the fields from GPS (or any NMEA device) NMEA data streams. The
code is designed so that the user can easily add their own favorite
sentences to the tokenizer. Some tests have shown that the code can 
easily parse standard sentences such as GPRMC or GPGGA. This code 
will not be ready for release until the November 2002 time frame.


In conclusion:
If you have questions I will try to field them, but I can't guarantee 
instant response nor will I write complete projects for you. I would like
to hear about any additions you make to my code. Send the source
code please! 

Remember this is an open source project and you are obligated
by the license to share the code and any improvements with anyone who 
would like a copy. Please read the licensing agreement at the site 
documented in the code.

The latest version of the Visual Basic source code can be downloaded from
http://www.windreader.com/geodesy

Contacting me:
My e-mail address is documented on the windreader website  Feel free to 
contact me with any questions, bug reports or requests for help. I will try
to give you fast response, but occasionly I am traveling and cannot respond
until I return, so be patient! When you e-mail, PLEASE put the word GEODESY - VB
as part of the subject along with the real subject (i.e. GEODESY - VB my subject).
This helps me sort out good email from the load of spam that finds it's way to
me on a daily basis.

Vic Fraenckel
September 6, 2002
