Introduction

The Java projection library is a partial port to Java of the popular PROJ.4 map projection library. Most of the common projections are implemented and the aim is to eventually support all the PROJ projections. This is a pure Java port and is not to be confused with the JNI bindings for PROJ.

This is a very preliminary release of a work in progress. You have been warned.

License

The downloadable source code on this page is released under the Apache License. Basically, this means that you are free to do whatever you like with this code, including commercial use, but it's not my fault if your satellite/nuclear power station/missile system fails as a result.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this code except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Projections

PROJ is a procedural library and the Java port is not a straight procedural port. It tries to be a bit more object-oriented. Each projection is implemented as a Java class, based on a common superclass called Projection. To use the library, you need to create a projection, either directly by calling its constructor or via one of the factory methods. There are factory methods for creating projections based on the commonly-used PROJ.4 command-line parameters, and in the future there may be methods for other methods, such as EPSG and GeoTIFF codes.

Once you have a Projection, you can use it to convert between latitude/longitude and projected map units (by default, metres) by calling the transform and transformInverse methods. There are various forms of these methods which support converting single or multiple points.

Supported Projections

The following projections are supported:

In addition, there are over 6000 named coordinate systems based on these projections.

The PROJ.4 Interface

For people used to PROJ.4, a class called ProjectionFactory is provided. This has a factory method which takes an array of strings in PROJ.4 format and returns an appropriate projection. For example:

    Projection projection = ProjectionFactory.fromPROJ4Specification(
        new String[] {
            "+proj=tmerc",
            "+lon_0=-123",
            "+lat_0=0",
            "+ellps=WGS84",
        }
    );

The +init= option is provided for creating named projections. The library includes over 6000 coordinate systems including all the State Plane systems (NAD27 and NAD83), many World coordinate systems and ESRI and EPSG codes.

What's Missing?

Some of the nastier projections have not been implemented yet, but all the common ones are there.

There's no way to set some of the projection parameters via the PROJ.4 interface. This applies to parameters which are specific to certain projections, such as the Oblique Mercator projection

Coordinate system and geodetic datum conversion is missing.

Download

The projections library is now, after a lot of kind work by Bernhard Jenny, a SourceForge project and can be found here: Java Map Projection Library. Please use this link to get the source code.

The original code is still available here for reference, but is now obsolete: Download Version 1.0.9

The archive contains source and a built Jar file. An Ant build file is included so you can build the source yourself.

Please let me know of any bugs you find.

The Globe Applet

Below is an applet which you can use to see what these projections look like. It displays several layers: the Sea, the World coastline, a graticule and a Tissot indicatrix. This last is an aid to visualizing the distortion of the projections. To change the centre of projection, click and drag. To zoom in and out, hold down the Alt (Option) key while dragging. To move the map, hold down the Shift key. Note that moving the centre of projection out of the valid range may cause certain projections to behave badly. Some of the drawing code in this applet is a bit buggy, but I'm working on it.

Change History

  • 30 Apr 2010: Version 1.0.9: Added "longlat" as an alias for the "latlong" projection.
  • 21 Apr 2010: Version 1.0.8: Fixed a bug in AlbersProjection. Fixes kindly provided by Brad Morgan.
  • 18 Apr 2010: Version 1.0.7: Fixed a bug in the inverse AlbersProjection.
  • 9 May 2009: Version 1.0.6: Fixed some units bugs. Fixes kindly provided by Jørn Svendsen and Brian Ferris.
  • 24 May 2008: Version 1.0.5: Fixed a bug in preventing trueScaleLatitude working in azimuthal projections.
  • 16 Aug 2007: Version 1.0.4: Fixed another bug in inverse tmerc projection.
  • 11 Aug 2007: Version 1.0.3: Fixed a bug in inverse tmerc projection and added radian versions of projection methods.
  • 17 Jul 2007: Version 1.0.2: Fixed a bug in using +init causing standard parallels to become zero.
  • 16 Jun 2007: Version 1.0.1: Fixed Lambert Conformal Projection to use two standard parallels properly.
  • 3 Apr 2007: Made ProjectionFactory methods public and fixed false easting in UTM projection.