org.apache.sis.storage.gdal

## Class Proj4

- Object
- - Static
  - - Proj4

-     public final class Proj4
      extends Static

  Bindings to the Proj.4 library as static convenience methods. The methods in this class allow to:
  - Create a Coordinate Reference System instance from a Proj.4 definition string.
  - Conversely, get a Proj.4 definition string from a Coordinate Reference System.
  - Create a coordinate operation backed by Proj.4 between two arbitrary CRS.
  Most methods in this class delegate to `Proj4Factory`.
  Since:
    0.8

  Defined in the `sis-gdal` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static CoordinateReferenceSystem` | `createCRS(String definition, int dimension)` Creates a new CRS from the given Proj.4 definition string.
    `static CoordinateOperation` | `createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, boolean force)` Creates an operation for conversion or transformation between two coordinate reference systems.
    `static String` | `definition(CoordinateReferenceSystem crs)` Infers a Proj.4 definition from the given projected, geographic or geocentric coordinate reference system.
    `static String` | `version()` Returns the version number of the Proj.4 library.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### version

          public static String version()

      Returns the version number of the Proj.4 library. Returns `null` if Proj.4 is not installed on the current system.
      Example: Rel. 4.9.3, 15 August 2016
      Returns:
        the Proj.4 release string, or `null` if the native library has been found.

    - #### definition

          public static String definition(CoordinateReferenceSystem crs)
                                   throws FactoryException

      Infers a Proj.4 definition from the given projected, geographic or geocentric coordinate reference system. This method does not need the Proj.4 native library; it can be used in a pure Java application. However the returned definition string may differ depending on whether the Proj.4 library is available or not.
      Parameters:
        `crs` - the coordinate reference system for which to create a Proj.4 definition.
      Returns:
        the definition of the given CRS in a Proj.4 format.
      Throws:
        `FactoryException` - if the Proj.4 definition string can not be created from the given CRS.

    - #### createCRS

          public static CoordinateReferenceSystem createCRS(String definition,
                                                            int dimension)
                                                     throws FactoryException

      Creates a new CRS from the given Proj.4 definition string. Some examples of definition strings are:
      - `"+init=epsg:3395 +over"` (see warning below)
      - `"+proj=latlong +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0"`
      - `"+proj=merc +lon_0=0 +k=1 +x_0=0 +y_0=0 +datum=WGS84 +units=m +ellps=WGS84 +towgs84=0,0,0"`
      Warning: despite the `"epsg"` word, coordinate reference systems created by `"+init=epsg:"` syntax are not necessarily compliant with EPSG definitions. In particular, the axis order is often different. Units of measurement may also differ.
      Parameters:
        `definition` - the Proj.4 definition string.
        `dimension` - the number of dimension of the CRS to create (2 or 3).
      Returns:
        a CRS created from the given definition string and number of dimensions.
      Throws:
        `NullPointerException` - if the definition string is `null`.
        `IllegalArgumentException` - if the definition string is empty or the dimension argument is out of range.
        `UnavailableFactoryException` - if the Proj.4 native library is not available.
        `FactoryException` - if the CRS creation failed for another reason.
      See Also:
        `Proj4Factory​.createCoordinateReferenceSystem(String)`

    - #### createOperation

          public static CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS,
                                                            CoordinateReferenceSystem targetCRS,
                                                            boolean force)
                                                     throws FactoryException

      Creates an operation for conversion or transformation between two coordinate reference systems. The given CRSs should be instances created by this package. If not, then there is a choice:
      - If `force` is `false`, then this method returns `null`.
      - Otherwise this method always uses Proj.4 for performing the coordinate operations, regardless if the given CRS were created from Proj.4 definition strings or not. This method fails if it can not map the given CRS to Proj.4 data structures.

      Recommended alternative

      Provided that an EPSG database is available, Apache SIS `CRS​.findOperation(…)` method produces results that are closer to the authoritative definitions of coordinate operations (technically, Apache SIS referencing engine is a late-binding implementation while Proj.4 is an early-binding implementation — see EPSG guidance notes for a definition of late versus early-binding approaches). Apache SIS also attaches metadata about coordinate operation accuracy and domain of validity, have extended support of multi-dimensional CRS and provides transform derivatives. This `Proj4​.createOperation(…)` method should be reserved to situations where an application needs to reproduce the same numerical results than Proj.4.
      Parameters:
        `sourceCRS` - the source coordinate reference system.
        `targetCRS` - the target coordinate reference system.
        `force` - whether to force the creation of a Proj.4 transform even if the given CRS are not wrappers around Proj.4 data structures.
      Returns:
        a coordinate operation for transforming coordinates from the given source CRS to the given target CRS, or `null` if the given CRS are not wrappers around Proj.4 data structures and `force` is false.
      Throws:
        `UnavailableFactoryException` - if `force` is `true` and the Proj.4 native library is not available.
        `FactoryException` - if `force` is `true` and this method can not create Proj.4 transform for the given pair of coordinate reference systems for another reason.
      See Also:
        `Proj4Factory​.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, boolean)`, `CRS​.findOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, GeographicBoundingBox)`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.