# Package org.apache.sis.storage.gdal

Extensions to referencing services as wrapper around the C/C++ Proj.4 library.

See: Description

- Class Summary
  Class | Description
  --- | ---
  Proj4 | Bindings to the Proj.4 library as static convenience methods.
  Proj4Factory | A factory for Coordinate Reference Systems created from Proj.4 definitions.

## Package org.apache.sis.storage.gdal Description

Extensions to referencing services as wrapper around the C/C++ Proj.4 library. Current version wraps only referencing services, but future versions are expected to wrap more GDAL functionalities. Unless otherwise specified, this optional module requires the native (C/C++) Proj.4 library to be installed on the local machine. This package allows 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.

Note that Apache SIS provides its own map projection engine in pure Java, so this module is usually not needed. This module is useful when a map projection is not yet available in Apache SIS, or when an application needs to reproduce the exact same numerical results than Proj.4. But some Apache SIS features like transform derivatives are not available through the Proj.4 wrappers.

When this optional module is available, the `CRS​.forCode(String)` method accepts Proj.4 definition strings prefixed by `"Proj4::"`. Example:

    CoordinateReferenceSystem crs = CRS.forCode("Proj4::+init=epsg:3395");

Calls to `CRS​.findOperation(…)` will delegate the coordinate transformation to Proj.4 if `sourceCRS` and `targetCRS` were both obtained from a code in `"Proj4"` namespace or by a method in this package. Otherwise, Apache SIS will use its own referencing engine. The backing referencing engine can be seen by printing the `MathTransform`: a transform backed by Proj.4 have a Well Known Text 1 representation like below:

    PARAM_MT["pj_transform",
      PARAMETER["srcdefn", "+proj=…"],
      PARAMETER["dstdefn", "+proj=…"]]

Note on Proj.4 definition strings
Proj.4 unconditionally requires 3 letters for the `"+axis="` parameter — for example `"neu"` for North, East and Up respectively — regardless the number of dimensions in the CRS to create. Apache SIS makes the vertical direction optional in order to specify whether the CRS to create shall contain a vertical axis or not:

- If the vertical direction is present (as in `"neu"`), a three-dimensional CRS is created.
- If the vertical direction is absent (as in `"ne"`), a two-dimensional CRS is created.

Examples:

- `"+init=epsg:4326"` (not equivalent to the standard EPSG::4326 definition)
- `"+proj=latlong +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0"` (default to two-dimensional CRS)
- `"+proj=latlon +a=6378137.0 +b=6356752.314245179 +pm=0.0 +axis=ne"` (explicitely two-dimensional)
- `"+proj=latlon +a=6378137.0 +b=6356752.314245179 +pm=0.0 +axis=neu"` (three-dimensional)

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.
Installation
The Proj.4 library needs to be reachable on a platform-dependent library path. For example the operating system may search in `/usr/lib`, `/opt/local/lib` and other directories. One of those directories shall contain the `proj` or `libproj` file with platform-specific suffix (e.g. `.so`, `.dylib` or `.dll`). An easy way to install the library in appropriate directory is to use the package manager provided by the platform.

Since:
  0.8

Defined in the `sis-gdal` module

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