Skip to content

Commit

Permalink
Merge 1c1dc40 into 5bbeb0c
Browse files Browse the repository at this point in the history
  • Loading branch information
@desruisseaux
desruisseaux committed Apr 27, 2018
2 parents 5bbeb0c + 1c1dc40 commit c4eb35e
Show file tree
Hide file tree
Showing 9 changed files with 165 additions and 1,930 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Expand Up @@ -94,4 +94,7 @@ README
/src/gie
/src/geodtest

# Java bridge
jniwrap/out

/docs/build
2 changes: 1 addition & 1 deletion jniwrap/Makefile.am
View file
@@ -1,4 +1,4 @@
EXTRA_DIST = build.xml doxygen.cfg README
EXTRA_DIST = build.xml README.md

SUBDIRS = org

Expand Down
128 changes: 0 additions & 128 deletions jniwrap/README
View file

This file was deleted.

116 changes: 116 additions & 0 deletions jniwrap/README.md
View file
@@ -0,0 +1,116 @@
# 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.



## 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`.



### 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.9.8+, to run the build.
* For execution:
* If a Java version less than the current version on the local machine is desired,
add an `release` attribute in the `javac` task of `build.xml`.



### 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 -classpath <path to the jar library>/proj.jar Main.java

and execute the created test case with:

java -cp .:<path to the jar library>/proj.jar -Djava.library.path=<path to the libproj, if needed> Main

That's it, enjoy!
115 changes: 39 additions & 76 deletions jniwrap/build.xml
View file
@@ -1,88 +1,51 @@
<?xml version="1.0"?>
<project name="jproj" default="compile" basedir=".">

<!-- ******************************************* -->
<!-- Set the variables -->
<!-- ******************************************* -->
<property name="src" value="org/proj4"/>
<property name="srcProj" value="../src"/>
<property name="build" value="classes"/>
<property name="libs" value="libs"/>

<!-- ******************************************* -->
<!-- Start everything (default target) -->
<!-- ******************************************* -->
<target name="compile" depends="start, do_javac, jar_it">
<echo>Compilation finished...</echo>
</target>

<!-- ******************************************* -->
<!-- Create some begin stuff -->
<!-- ******************************************* -->
<target name="start">
<echo>Creating folder structure...</echo>
<mkdir dir="${build}"/>
<mkdir dir="${libs}"/>
</target>

<!-- ******************************************* -->
<!-- Execute javac compilation -->
<!-- ******************************************* -->
<target name="do_javac" depends="start">
<echo>Compiling the java code...</echo>
<javac srcdir="${src}" destdir="${build}" encoding="UTF-8" source="1.5" target="1.5" includeAntRuntime="false"/>
</target>

<!-- ******************************************* -->
<!-- Execute javah for JNI headers -->
<!-- ******************************************* -->
<!-- Needed if new native methods are added. -->
<!-- Header file is created only if the old -->
<!-- proj/src/org_proj4_PJ.h file is deleted -->
<!-- before to run this task. -->
<!-- ******************************************* -->
<target name="do_javah" depends="do_javac">
<echo>Creating jni headers...</echo>
<javah classpath="${build}" class="org.proj4.PJ" destdir="${srcProj}"/>
</target>

<!-- ******************************************* -->
<!-- Do the C part compilation through make -->
<!-- ******************************************* -->
<target name="do_make" depends="do_javah">
<echo>Compiling libraries...</echo>
<exec dir=".." executable="make"/>
</target>

<!-- ******************************************* -->
<!-- Create binary package distribution -->
<!-- ******************************************* -->
<target name="jar_it">
<jar destfile="${libs}/jproj.jar" basedir="${build}/">
<project name="Proj bridge to Java" default="compile" basedir=".">

<!-- *******************************************
Set directory paths and versions.
******************************************* -->
<property name="src-java" value="."/>
<property name="src-C" value="../src"/>
<property name="out" value="out"/>
<property name="classes" value="${out}/classes"/>
<property name="javadoc" value="${out}/apidocs"/>
<property name="version" value="5.1"/>

<!-- *******************************************
Compile (default target).
Include generation of JNI header.
******************************************* -->
<target name="compile">
<mkdir dir="${out}"/>
<mkdir dir="${classes}"/>
<javac srcdir="${src-java}" destdir="${classes}" encoding="UTF-8" nativeheaderdir="${src-C}"
createMissingPackageInfoClass = "false"
includeAntRuntime = "false"
includes = "org/**/*.java"/>

<jar destfile="${out}/proj.jar" basedir="${classes}" level="9" strict="fail">
<manifest>
<attribute name="Built-By" value="Proj.4"/>
<attribute name="Implementation-Title" value="Proj bridge to Java"/>
<attribute name="Implementation-Version" value="${version}"/>
<attribute name="Implementation-Vendor" value="Proj.4 project"/>
<attribute name="Implementation-URL" value="http://proj4.org/"/>
</manifest>
</jar>
</target>

<!-- ****************************************************** -->
<!-- Execute doxygen help file and source file creation -->
<!-- ****************************************************** -->
<target name="do_make_help" depends="start">
<echo>Creating help files...</echo>
<exec dir="." executable="doxygen">
<arg line="doxygen.cfg"/>
</exec>
<!-- **********************************************************
Build and create documentation.
********************************************************** -->
<target name="javadoc" depends="compile">
<javadoc sourcepath="${src-java}" classpath="${classes}" destdir="${javadoc}" encoding="UTF-8"
noqualifier="all" windowtitle="Proj bridge to Java" author="false"/>
</target>

<!-- ******************************************* -->
<!-- Clean up everything -->
<!-- ******************************************* -->
<!-- *******************************************
Clean up everything.
******************************************* -->
<target name="clean">
<echo>Cleaning up...</echo>
<delete dir="${build}"/>
<delete dir="${libs}"/>
<delete dir="docs"/>
<delete dir="${out}"/>
</target>

</project>

0 comments on commit c4eb35e

Please sign in to comment.