Module org.osgeo.proj
Package org.osgeo.proj

Class Proj

Object
Proj
public final class Proj extends Object
Static methods for coordinate reference systems and operations. The methods provided in this class are specific to PROJ implementation, but the objects returned by those methods can be used in an implementation independent way. Some entry points are: Alternatively the getAuthorityFactory(String) and getOperationFactory(CoordinateOperationContext) methods provide similar functionality in a more implementation neutral way, at the cost of one indirection level (need to fetch the factory before invoking methods on it).
Since:
1.0

  • Method Details

    • version

      public static Optional<String> version()
      Returns the version number of the PROJ library. If the PROJ library is not installed on the current system, then this method logs an error message and returns an empty value. This method can be used as a way to check if the library is present.
      Returns:
      the PROJ release string, or an empty value if the native library is not found.

    • getAuthorityFactory

      public static CRSAuthorityFactory getAuthorityFactory(String authority)
      Returns a factory for creating coordinate reference systems from codes allocated by the given authority. The authority is typically "EPSG", but not necessarily; other authorities like "IAU" are also allowed. Typical values are:
      • "EPSG" — de facto standard for coordinate reference systems on Earth.
      • "IAU" — extraterrestrial coordinate reference systems.
      • "" (empty string) — PROJ default set of authorities.
      After a factory has been obtained, its createCoordinateReferenceSystem(…) method can be invoked to create a CRS from an authority code. For example the code below creates the "WGS 84" coordinate reference system for the "EPSG::4326" code. In that example, only the first line is PROJ-specific; the remaining lines can be executed with any GeoAPI implementation: 
       CRSAuthorityFactory factory = Proj.getAuthorityFactory("EPSG");
 CoordinateReferenceSystem crs = factory.createCoordinateReferenceSystem("4326");
 System.out.println(crs.toWKT());
      The factory returned by this method is safe for concurrent use in multi-threads environment. The object returned by this method also implements the CSAuthorityFactory, DatumAuthorityFactory and CoordinateOperationAuthorityFactory interfaces (so it can be cast to any of those interfaces), but typically only the CRSAuthorityFactory interface is used.
      Parameters:
      authority - authority name of the factory (e.g. "EPSG").
      Returns:
      the CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory and CoordinateOperationAuthorityFactory for the given authority.
      Throws:
      NullPointerException - if authority is null.

    • getOperationFactory

      public static CoordinateOperationFactory getOperationFactory(CoordinateOperationContext context)
      Creates a new operation factory for the given context. The context is an optional argument which allows specifying the area of interest and desired accuracy. The returned factory can be used for creating CoordinateOperations for given pairs of CoordinateReferenceSystems. Example: 
       CoordinateReferenceSystem  sourceCRS = ...;
 CoordinateReferenceSystem  targetCRS = ...;
 CoordinateOperationFactory opFactory = Proj.getOperationFactory(null);
 CoordinateOperation        operation = opFactory.createOperation(sourceCRS, targetCRS);
 System.out.println(operation.toWKT());
      Parameters:
      context - in which coordinate operations are to be used, or null for the default setting.
      Returns:
      a factory for creating coordinate operations in the given context.

    • getFactory

      public static <F extends Factory> F getFactory(Class<F> type)
      Returns a factory of the given type. This method recognizes three groups of factories:
      Type Parameters:
      F - compile-time value of type argument.
      Parameters:
      type - type of factory desired.
      Returns:
      factory of the given type.
      Throws:
      IllegalArgumentException - if the specified type is not one of the above-listed types.

    • createFromUserInput

      public static IdentifiedObject createFromUserInput(String text) throws FactoryException
      Instantiate a geodetic object from a user specified text. The returned object will typically by a subtype of CoordinateReferenceSystem. The text can be a:
      • WKT string.
      • PROJ string.
      • database code, prefixed by its authority. Example: “EPSG:4326”.
      • OGC URN. Examples: “urn:ogc:def:crs:EPSG::4326”, “urn:ogc:def:coordinateOperation:EPSG::1671”, “urn:ogc:def:ellipsoid:EPSG::7001” or “urn:ogc:def:datum:EPSG::6326”.
      • OGC URN combining references for compound coordinate reference systems. Examples: “urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717”. We also accept a custom abbreviated syntax “EPSG:2393+5717”.
      • OGC URN combining references for references for projected or derived CRSs. Example for Projected 3D CRS “UTM zone 31N / WGS 84 (3D)”: “urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031”.
      • OGC URN combining references for concatenated operations. Example: “urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618”.
      • An Object name. Example: “WGS 84”, “WGS 84 / UTM zone 31N”. In that case as uniqueness is not guaranteed, the function may apply heuristics to determine the appropriate best match.
      • PROJJSON string.
      Parameters:
      text - one of the above mentioned text format.
      Returns:
      a coordinate reference system or other kind of object created from the given text.
      Throws:
      FactoryException - if the given text can not be parsed.
      See Also:

    • createCoordinateOperation

      public static CoordinateOperation createCoordinateOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws FactoryException
      Returns an operation for conversion or transformation between two coordinate reference systems, taking in account the given context. If more than one operation exists, the preferred one is returned. If no operation exists, then an exception is thrown.

      The context is an optional argument which specifying the area of interest and desired accuracy. If this argument is null, then the default setting is:

      • Coordinate operations from any authority will be searched, with the restrictions set in the "authority_to_authority_preference" database table.
      • Area of interest is unknown.
      • Desired accuracy is best accuracy available.
      • Source and target CRS extents use is SourceTargetCRSExtentUse.SMALLEST.
      • Criterion for comparing areas of validity is SpatialCriterion.STRICT_CONTAINMENT.
      • Grid availability use is USE_FOR_SORTING.
      • Use of intermediate pivot CRS is allowed.
      Parameters:
      sourceCRS - input coordinate reference system.
      targetCRS - output coordinate reference system.
      context - context in which the coordinate operation is to be used.
      Returns:
      coordinate operations from sourceCRS to targetCRS.
      Throws:
      NullPointerException - if sourceCRS or targetCRS is null.
      UnsupportedImplementationException - if a CRS is not a PROJ-JNI implementation.
      FactoryException - if the operation creation failed.
      See Also:

    • createCoordinateOperations

      public static List<CoordinateOperation> createCoordinateOperations(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateOperationContext context) throws FactoryException
      Returns operations for conversion or transformation between two coordinate reference systems, taking in account the given context. If no coordinate operation is found, then this method returns an empty list.

      The context is an optional argument which allows specifying the area of interest and desired accuracy. If this argument is null, then the default values are documented here.

      Parameters:
      sourceCRS - input coordinate reference system.
      targetCRS - output coordinate reference system.
      context - context in which the coordinate operation is to be used.
      Returns:
      coordinate operations from sourceCRS to targetCRS.
      Throws:
      NullPointerException - if sourceCRS or targetCRS is null.
      UnsupportedImplementationException - if a CRS is not a PROJ-JNI implementation.
      FactoryException - if the operation creation failed.

    • createPosition

      public static DirectPosition createPosition(CoordinateReferenceSystem crs, double... coordinates)
      Creates a position with the given coordinate values and an optional CRS.

      At least one of crs and coordinates arguments must be non-null. If both arguments are non-null, then the number of dimensions of the given CRS must match the number of coordinate values.

      A DirectPosition instance can be transformed to another CRS by a call to factory.createOperation(position.getCoordinateReferenceSystem()) for fetching the coordinate operation, then operation.getMathTransform().transform(position, null) for executing that operation. However those steps are costly and should be applied for only a small number of points. For large number of points, consider using coordinate tuples in float[] or double[] arrays instead.

      Serialization

      The DirectPosition returned by this method is serializable, but the CRS is lost in the serialization process because we do not serialize native PROJ objects.
      Parameters:
      crs - the coordinate reference system, or null is unspecified.
      coordinates - the coordinate values, or null for initializing the position to zero.
      Returns:
      a direct position for the given coordinate values and optional CRS.
      Throws:
      NullPointerException - if both crs and coordinates are null.
      UnsupportedImplementationException - if the given CRS is not a PROJ-JNI implementation.
      MismatchedDimensionException - if the given CRS is non-null but its number of dimensions is not equal to the length of the coordinates array.
      See Also:

    • normalizeForVisualization

      public static CoordinateOperation normalizeForVisualization(CoordinateOperation operation)
      Returns a coordinate operation with axis order such as the east direction is first and the north direction is second, if possible.
      Parameters:
      operation - the operation for which to adjust axis order.
      Returns:
      an operation with axis order convenient for visualization.

    • areEquivalent

      public static boolean areEquivalent(Object obj1, Object obj2, ComparisonCriterion criterion)
      Returns true if the given objects are equivalent according the given criterion. If the two given objects are null, this method returns true. If one object is null and the other object is non-null, this method returns false.
      Parameters:
      obj1 - first object to compare, or null.
      obj2 - second object to compare, or null.
      criterion - the comparison criterion, which can be strict or relaxed.
      Returns:
      whether the given objects are equivalent according the given criterion.