diff options
Diffstat (limited to 'jniwrap/README.md')
| -rw-r--r-- | jniwrap/README.md | 146 |
1 files changed, 0 insertions, 146 deletions
diff --git a/jniwrap/README.md b/jniwrap/README.md deleted file mode 100644 index 9cc97dac..00000000 --- a/jniwrap/README.md +++ /dev/null @@ -1,146 +0,0 @@ -# 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 - -* Andrea Antonello (andrea.antonello@hydrologis.com) -* Martin Desruisseaux (martin.desruisseaux@geomatys.com) - - - -## 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. |
