Module org.osgeo.proj

Package org.osgeo.proj

package org.osgeo.proj
Java Native Interface for the PROJ C/C++ library.

Usage example

Coordinate operations can be performed as below (a more complete example is available here). In this example, only the calls to Proj static methods are specific to this implementation. All other lines should work in the same way with any GeoAPI implementation. Note that geographic coordinates are in latitude, longitude order, as specified in the EPSG database and in agreement with centuries of practice.

 CRSAuthorityFactory        factory   = Proj.getAuthorityFactory("EPSG");
 CoordinateOperationFactory regops    = Proj.getOperationFactory(null);
 CoordinateReferenceSystem  sourceCRS = factory.createCoordinateReferenceSystem("4326");   // WGS 84
 CoordinateReferenceSystem  targetCRS = factory.createCoordinateReferenceSystem("3395");   // WGS 84 / World Mercator
 CoordinateOperation        operation = regops.createOperation(sourceCRS, targetCRS);
 double[] coordinates = {
     45.500,  -73.567,                    // Montreal
     49.250, -123.100,                    // Vancouver
     35.653,  139.839,                    // Tokyo
     48.865,    2.349                     // Paris
 };
 operation.getMathTransform().transform(
         coordinates, 0,                  // Source coordinates.
         coordinates, 0,                  // Target coordinates (in this case, overwrite sources).
         4);                              // Number of points to transform.

 System.out.printf("Montreal:  %11.1f %11.1f%n", coordinates[0], coordinates[1]);
 System.out.printf("Vancouver: %11.1f %11.1f%n", coordinates[2], coordinates[3]);
 System.out.printf("Tokyo:     %11.1f %11.1f%n", coordinates[4], coordinates[5]);
 System.out.printf("Paris:     %11.1f %11.1f%n", coordinates[6], coordinates[7]);

Performance considerations

Calls to createCoordinateOperation(…) methods may be costly. Developers should get a CoordinateOperation instance only once for a given pair of CoordinateReferenceSystems and keep that reference as long as they may need it.

Calls to MathTransform.transform(…) methods may also be costly. Developers should avoid invoking those methods repeatedly for each point to transform. For example it is much more efficient to invoke transform(double[], …) only once for an array of 4 points than to invoke that method 4 times (once for each point). Above example shows the recommended way to use a transform.

Multi-threading

Unless otherwise noted in Javadoc, all classes are safe for use in multi-thread environment. However there is a limit in the number of concurrent threads which can use efficiently the same MathTransform instance. This limit can be controlled by assigning an integer to the "org.osgeo.proj.maxThreadsPerInstance" system property at startup time. A low value does not necessarily block more threads from using a MathTransform concurrently, but the extra threads may observe a performance degradation. Conversely a too high value may retain more resources than necessary. The current default value is 4.

Note that there is no limit on Java side in the amount of threads that can use different MathTransform instances concurrently.

String representation

Referencing objects such as CRS, datum, etc. implement the IdentifiedObject.toWKT() method, which can be used for getting a string representation in Well Known Text (WKT) version 2 format. The Object.toString() method can also be used for getting a similar string representation, but in a slightly simplified version. Note that those string representations do not perform database access, and consequently may be less complete than the formatting done by ReferencingFormat.

Referencing objects also implement the Formattable interface. The "%s" flag formats the object name, while the alternative form "%#s" formats the authority (typically EPSG) code.

Unsupported features

The following method calls will cause an exception to be thrown:

Since:
1.0