Proj.4 bindings

This module is a "proof of concept" implementation of GeoAPI referencing interfaces using JNI bindings to the C/C++ Proj4 library. This module contains two packages:

  • The org.proj4 package contains a slightly modified copy of the classes provided in the jniwrap directory of the Proj.4 project. The slight modifications are binary-compatible.
  • The org.opengis.wrapper.proj4 package contains implementations of GeoAPI interfaces on top of the org.proj4 package.

This module requires the Proj.4 native library version 4.8 or above. The Proj.4 library is used for performing map projection calculations. The GeoAPI wrappers extend the Proj.4 services by providing the following additional functionalities:

  • Coordinate Reference Systems created from EPSG code honor axis order as defined by EPSG. This reordering can be disabled if the usual (λ,φ) order is desired.
  • Coordinate Operations and Math Transforms can be created from EPSG and OGC parameter names, in addition of Proj.4 parameter names.

Licensing

All files provided in this module are hereby placed into the Public Domain. This means anyone is free to do whatever they wish with those files. The Proj.4 wrappers are provided as code examples, in the hope to facilitate GeoAPI implementations backed by other libraries. Implementors can take this source code and use it for any purpose, commercial or non-commercial, copyrighted or open-source, with no legal obligation to acknowledge the borrowing/copying in any way.

Note that the GeoAPI interfaces are not in the public domain; they are copyrighted by OGC and distributed under a permissive, BSD-like license. Only the example codes - including this Proj.4 wrappers module - are in the public domain.

Download

The Proj.4 bindings can be used in a Maven project using the following pom.xml configuration. Note that the Proj.4 native library needs to be installed manually; this is not done by Maven.

<repositories>
  <repository>
    <id>geotoolkit</id>
    <name>Geotoolkit.org project</name>
    <url>http://maven.geotoolkit.org</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>org.opengis.wrapper</groupId>
    <artifactId>geoapi-proj4</artifactId>
    <version>3.1-SNAPSHOT</version>
  </dependency>
</dependencies>

Usage example

Proj.4 functionality can be used directly (without GeoAPI interfaces) by the PJ class as below:

package org.myproject;

import org.proj4.*;
import java.util.Arrays;


/**
 * Converts coordinates from EPSG:32632 (WGS 84 / UTM zone 32N) to WGS84,
 * then prints the result to the standard output stream.
 */
public class MyApp {
    public static void main(String[] args) throws PJException {
        PJ sourcePJ = new PJ("+init=epsg:32632");           // (x,y) axis order
        PJ targetPJ = new PJ("+proj=latlong +datum=WGS84"); // (λ,φ) axis order
        double[] coordinates = {
            500000,       0,   // First coordinate
            400000,  100000,   // Second coordinate
            600000, -100000    // Third coordinate
        };
        sourcePJ.transform(targetPJ, 2, coordinates, 0, 3);
        System.out.println(Arrays.toString(coordinates));
    }
}

The above example - especially the CRS definitions given to the PJ constructors - was specific to the Proj.4 library. The same functionality can be achieved through the implementation-neutral GeoAPI interfaces as below:

package org.myproject;

import org.opengis.referencing.crs.CRSAuthorityFactory;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.CoordinateOperation;
import org.opengis.referencing.operation.CoordinateOperationFactory;
import org.opengis.referencing.operation.TransformException;
import org.opengis.util.FactoryException;
import org.opengis.wrapper.proj4.PJFactory;
import java.util.Arrays;


/**
 * Converts coordinates from EPSG:32632 (WGS 84 / UTM zone 32N) to WGS84,
 * then prints the result to the standard output stream.
 */
public class MyApp {
    public static void main(String[] args) throws FactoryException, TransformException {
        // The following lines instantiate directly the factories for the Proj.4 bindings
        // for simplicity reasons, but a real application would be encouraged to use some
        // kind of Service Registry instead.
        CRSAuthorityFactory       crsFactory = new PJFactory.EPSG();
        CoordinateOperationFactory opFactory = new PJFactory.Operation();

        // From this point, use only the GeoAPI interfaces.
        CoordinateReferenceSystem sourceCRS = crsFactory.createCoordinateReferenceSystem("32632");
        CoordinateReferenceSystem targetCRS = crsFactory.createCoordinateReferenceSystem("4326");
        CoordinateOperation operation = opFactory.createOperation(sourceCRS, targetCRS);
        double[] coordinates = {
            500000,       0,   // First coordinate
            400000,  100000,   // Second coordinate
            600000, -100000    // Third coordinate
        };
        operation.getMathTransform().transform(coordinates, 0, coordinates, 0, 3);
        System.out.println(Arrays.toString(coordinates));
    }
}