/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Extensions to referencing services as wrapper around the C/C++ {@literal 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++) <a href="http://proj.osgeo.org/">Proj.4</a>
 * library to be installed on the local machine. This package allows to:
 * <ul>
 *   <li>{@linkplain org.apache.sis.storage.gdal.Proj4#createCRS Create a Coordinate Reference System instance from a Proj.4 definition string}.</li>
 *   <li>Conversely, {@linkplain org.apache.sis.storage.gdal.Proj4#definition get a Proj.4 definition string from a Coordinate Reference System}.</li>
 *   <li>{@linkplain org.apache.sis.storage.gdal.Proj4#createOperation Create a coordinate operation backed by Proj.4 between two arbitrary CRS}.</li>
 * </ul>
 *
 * 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
 * {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform#derivative transform derivatives}
 * are not available through the Proj.4 wrappers.
 *
 * <p>When this optional module is available, the {@link org.apache.sis.referencing.CRS#forCode CRS.forCode(String)}
 * method accepts Proj.4 definition strings prefixed by {@code "Proj4::"}. Example:</p>
 *
 * {@preformat java
 *     CoordinateReferenceSystem crs = CRS.forCode("Proj4::+init=epsg:3395");
 * }
 *
 * Calls to {@link org.apache.sis.referencing.CRS#findOperation CRS.findOperation(…)} will delegate the coordinate
 * transformation to Proj.4 if {@code sourceCRS} and {@code targetCRS} were both obtained from a code in {@code "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 {@code MathTransform}:
 * a transform backed by Proj.4 have a <cite>Well Known Text 1</cite> representation like below:
 *
 * {@preformat wkt
 *   PARAM_MT["pj_transform",
 *     PARAMETER["srcdefn", "+proj=…"],
 *     PARAMETER["dstdefn", "+proj=…"]]
 * }
 *
 * <h2>Note on Proj.4 definition strings</h2>
 * Proj.4 unconditionally requires 3 letters for the {@code "+axis="} parameter — for example {@code "neu"} for
 * <cite>North</cite>, <cite>East</cite> and <cite>Up</cite> 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:
 *
 * <ul>
 *   <li>If the vertical direction is present (as in {@code "neu"}), a three-dimensional CRS is created.</li>
 *   <li>If the vertical direction is absent (as in {@code "ne"}), a two-dimensional CRS is created.</li>
 * </ul>
 *
 * <div class="note"><b>Examples:</b>
 * <ul>
 *   <li>{@code "+init=epsg:4326"} (<strong>not</strong> equivalent to the standard EPSG::4326 definition)</li>
 *   <li>{@code "+proj=latlong +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0"} (default to two-dimensional CRS)</li>
 *   <li>{@code "+proj=latlon +a=6378137.0 +b=6356752.314245179 +pm=0.0 +axis=ne"} (explicitly two-dimensional)</li>
 *   <li>{@code "+proj=latlon +a=6378137.0 +b=6356752.314245179 +pm=0.0 +axis=neu"} (three-dimensional)</li>
 * </ul>
 * </div>
 *
 * <b>Warning:</b> despite the {@code "epsg"} word, coordinate reference systems created by {@code "+init=epsg:"}
 * syntax are not necessarily compliant with EPSG definitions. In particular, the axis order is often different.
 * Units of measurement may also differ.
 *
 * <h2>Installation</h2>
 * The Proj.4 library needs to be reachable on a platform-dependent library path.
 * For example the operating system may search in {@code /usr/lib}, {@code /opt/local/lib} and other directories.
 * One of those directories shall contain the {@code proj} or {@code libproj} file with platform-specific suffix
 * (e.g. {@code .so}, {@code .dylib} or {@code .dll}).
 * An easy way to install the library in appropriate directory is to use the package manager provided by the platform.
 *
 * @author  Martin Desruisseaux (Geomatys)
 * @version 0.8
 * @since   0.8
 * @module
 */
package org.apache.sis.storage.gdal;