Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
org.osgeo.proj
Makefile.am
README.md
build.xml

README.md

PROJ bridge to Java

This is the third release of JNI wrappers for the main PROJ functions. The first release of JNI wrappers were created by http://www.hydrologis.com. The second release of JNI wrappers were created by http://www.geoapi.org. This release is compatible with any PROJ versions from 4.8 to 5 provided that PROJ has been compiled as described below.

What is "PROJ bridge to Java"

PROJ bridge to Java is a small library of Java classes that wrap a few PROJ functions by using the Java Native Interface (JNI). The main Java class is org.proj4.PJ. A Java code example is given in the Usage & a fast example section below.

Versions

The PROJ bridge to Java does not follow the same version numbers than the main PROJ library since the same JAR file can be compatible with a range of PROJ versions. Version compatibility is given below:

Java bridge Compatible with PROJ library
2.0 and 3.0 4.8 to 5+
1.0 4.4.9 to 4.8 inclusive

Compilation

To compile the native part, configure has to be run in the PROJ directory like this:

CFLAGS=-Iinclude2 ./configure --with-jni=include1

where

  • include1 = folder in which the header file jni.h resides (usually $JAVA_HOME/include)
  • include2 = folder in which the header file jni_md.h resides (usually $JAVA_HOME/include/linux or whatever)

On MacOS, those two folders are /Library/Java/JavaVirtualMachines/.../Contents/Home/include/.

The java part is compiled by running Ant inside the jniwrap folder. This will compile the classes and archive them in a JAR file. It applies to Linux, MacOS and Windows (and virtually to every system supporting java).

Requirements

Beyond the ones already put by PROJ, you need:

  • For compilation:
    • Java 9+, the Java standard development kit version 9 or above
    • Ant 1.10+, to run the build.
  • For execution:
    • If a Java version less than the current version on the local machine is desired, add a release attribute in the javac task of build.xml before to compile.
    • Proj version 4.8 or more recent compiled with the --with-jni option.

Documentation

The documentation is held inside the code and can be retrieved by running ant javadoc inside the folder jniwrap. This will create the HTML format documentation inside of jniwrap/out/apidocs

License

GPL for the first release. Proj.4 license for the second release.

Authors

Usage & a fast example:

The proj.jar is all is needed to implement PROJ support in java applications. The whole job is done by the PROJ library, so there are just a couple of functions that be used.

The best way is to see everything through an example. In the following example we create two Coordinate Reference System and transform 3 points. The Coordinate Reference Systems and the points are hard-coded for simplicity. Of course, real applications would read them from a file or other data source.

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 Main {
    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));
    }
}

Compile the Main code

We assume that PROJ was compiled with the right flag to support the bridge to Java. Therefore we have a library called proj.jar. Thus we compile the Main.java with the command:

javac --class-path <path to the jar library>/proj.jar Main.java

and execute the created test case with (replace : by ; on the Windows platform):

java --class-path <path to the jar library>/proj.jar:. Main

Troubleshooting

If an java.lang.UnsatisfiedLinkError is thrown at execution time, add the following line in the Java code:

System.out.println(System.getProperty("java.library.path"));

Then verify that the libproj.so (Linux), libproj.dylib (MacOS) or libproj.dll (Windows) file is located in one of the directories listed by above code. If this is not the case, then try configuring the LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (MacOS) or PATH (Windows) environment variable. Alternatively, a -Djava.library.path=<path to the libproj> option can be added to above java command. If the problem persist, adding the -verbose:jni option to the java command may help more advanced diagnostics.

You can’t perform that action at this time.