Easily convert between latitude/longitude, Universal Transverse Mercator (UTM) and Ordnance Survey (OSGB) references with Java using the Jcoord package.
Stable version: 1.0 (11th February 2006)
Development version: 1.1-b (3rd April 2006)
Features | Download | Documentation | Examples | Development | Version History | Licensing
Conversion between latitude/longitude and grid references is not as simple as one would expect. Indeed, the maths involved is rather complex and not really for the faint-hearted! I have created a Java package which provides a simple API to allow conversion between OSGB (Ordnance Survey of Great Britain) grid references, UTM (Universal Transverse Mercator) references and latitude/longitude. OSGB Grid references can be returned as a standard six-figure grid reference using the 100km grid square letters (e.g. SK619847).
The Jcoord script also contains a method to allow the calculation of the surface distance between two points of latitude/longitude.
Looking for the same thing but with JavaScript or PHP? Translations of this package with the same functionality are available for JavaScript (see JScoord) and PHP (see PHPcoord).
Information on converting between UTM and latitude/longitude is available at www.posc.org.
The Ordnance Survey have published a concise guide on converting between OSGB and latitude/longitude which is available at www.gps.gov.uk.
Bear in mind that Jcoord is still in development, so check back often for updates. To contact me about Jcoord, send an e-mail to jcoord@jstott.me.uk.
Features
Jcoord contains the following features:
- Calculate distance between a pair of latitudes and longitudes.
- Convert between an OSGB grid reference and latitude and longitude using either the OSGB36 or WGS84 data.
- Create objects representing OSGB grid references from a six-figure reference string (e.g. "TG514131").
- Convert between UTM reference and latitude and longitude.
- Compatible with Java 1.4 and above.
Download
jar files contain both the source code and compiled bytecode.
Current Version
- v1.0 - 11th February 2006
- jcoord-1.0.jar (23kB)
- jcoord-doc-1.0.zip (51kB) - View Online
- jcoord-doc-1.0.tar.gz (14kB) - View Online
Documentation
Jcoord API documentation is available online for the following versions:
Examples
The Jcoord download contains a uk.me.jstott.jcoord.Test class which shows how to use the various classes and method provided in the Jcoord package.
Development Version
I am currently working on version 1.1 of Jcoord which will be released in the near future. A complete jar file including all the source code and documentation is available for testing purposes.
- Download: v1.1-b - 3rd April 2006
Version 1.1 will be a significant update, including the ability to covert co-ordinates between various datums as well as adding the ability to convert easily between any one of six different co-ordinate systems. Here's a list of supported co-ordinate systems:
- Latitude/longitude
- Universal Transverse Mercator (UTM)
- Ordnance Survey Grid Reference (OSGB)
- Military Grid Reference System (MGRS) - New in v1.1
- Earth-centred, Earth-fixed (ECEF) - New in v1.1
- Irish National Grid Reference (ING) - New in v1.1
It is possible to convert between a co-ordinate in any system simply by first converting the co-ordinate to a latitude/longitude and then converting that to the other system. Here's an example to show how easy it is to convert between an Irish National Grid Reference and a UTM reference:
IrishRef i = new IrishRef("G099361"); LatLng ll = i.toLatLng(); ll.toDatum(WGS84Datum.getInstance()); UTMRef u = new UTMRef(ll);
Here's a comprehensive list of new features and fixes being added to the current development version:
- Added Junit unit test suite in the uk.me.jstott.jcoord.junit package.
- Added NotDefinedOnUTMGridException which is thrown whenever an attempt is made to convert a LatLng object to a UTMRef object where the latitude falls outside the defined UTM grid.
- Can format a latitude/longitude into a String in degrees-minutes-seconds format.
- Added a class for Military Grid Reference System (MGRS) to allow for conversrions between MGRS and UTM and latitude/longitude.
- Documentation (javadoc) improvements.
- LatLng.getLat() has been deprecated. Use LatLng.getLatitude() instead.
- LatLng.getLng() has been deprecated. Use LatLng.getLongitude() instead.
- LatLng constructor now validates parameters and throws an IllegalArgumentException if either the latitude or longitude are invalid.
- UTMRef(double,double,char,int) constructor has been deprecated and replaced with UTMRef(int,char,double,double). This is to make the order of the parameters more sensible.
- Fixed slight error with values for converting between WGS84 and OSGB36.
- New method: LatLng.distanceMiles(LatLng) to calculate the distance between two points of latitude/longitude in miles.
- New constructors in LatLng to allow for specifying a datum and/or the latitude and longitude as degrees/minutes/seconds.
- Added IrishRef class to allow conversion between latitude and longitude and Irish National Grid References.
- Added new uk.me.jstott.jcoord.datum package with a number of data that all extend uk.me.jstott.jcoord.datum.Datum.
- Added new uk.me.jstott.jcoord.ellipsoid package with a number of definitions of reference ellipsoids that all extend uk.me.jstott.jcoord.ellipsoid.Ellipsoid.
- Fixed slight errors in OSRef to LatLng conversions.
- Added ECEFRef class to represent co-ordinates in the Earth-centred, Earth-fixed co-ordinate system and to allow them to be converted to/from latitude and longitude.
If you have any suggestions for future enhancements or find a problem with the current development version, let me know by e-mail at jcoord@jstott.me.uk.
Version History
- 1.0 - 11th February 2006
- Initial Version created from PHPcoord v2.2.
Licensing
This software product is available under the GNU General Public License (GPL) which permits the use of this product subject to a number of conditions as described in the license. A commercial license is also available for this product which provides the added benefits of royalty-free use and distribution in proprietary applications as well as prioritised technical support by e-mail. Contact me for more information about commercial licenses for this product.
If you do not require a commercial license but still want to contribute, perhaps you would like to consider making a donation:
- Donation - any amount
Commercial licenses for this product are available at the following prices:
- Single user - £15 (approximately $30)
- 2-10 users - £40 (approximately $80)
- 11-100 users - £150 (approximately $300)
- Unlimited users - £600 (approximately $1200)
Note that you will be billed in Pounds Sterling, so the relevant exchange rate from your currency will apply at the time of purchase. A copy of the license will be forwarded to the address provided at the time of purchase.
© 2000-08, Jonathan Stott.
18 Jan 2008 12:14:20 GMT