# Package org.apache.sis.referencing.operation.projection

package org.apache.sis.referencing.operation.projection
Map projection implementations. This package is mostly for documentation purpose (each projection documents its name and parameters) and for implementers who want to extend a map projection. This package should usually not be used directly.

The best way to get a projection is to use the coordinate operation factory with the source and target CRS. That factory can bundle the projections defined in this package, together with any affine transform required for handling unit conversions and axis swapping, in a single (potentially concatenated) operation.

Users wanting to build their transforms directly should also avoid instantiating objects directly from this package and use a math transform factory instead. The `createParameterizedTransform(…)` method of that factory is subjects to the same rules than this package, namely input coordinates must be (longitude, latitude) in decimal degrees and output coordinates must be (easting, northing) in metres. More on this convention is explained below.

Users wanting to know more about the available projections and their parameters should look at the list of coordinate operation methods. Only users interested in the implementation of those projections should look at this package.

## Definition of terms

- Coordinate operation
  In the particular case of this package, the conversion of geographic coordinates in any axis order, geodesic orientation and angular units to projected coordinates in any axis order, horizontal orientation and linear units.
- Map projection (a.k.a. cartographic projection)
  The conversion of geographic coordinates from (longitude, latitude) in decimal degrees to projected coordinates (x, y) in metres.
- Normalized projection
  The conversion of geographic coordinates from (longitude, latitude) in radians to projected coordinates (x, y) on a sphere or ellipse having a semi-major axis length of 1. This definition may be slightly relaxed if some projection-specifics coefficients are concatenated with the conversions that take place between the above map projection and this normalized projection.

## Axis units and orientation

Many geographic coordinate reference systems use axis in (latitude, longitude) order, but not all. Axis order, orientation and units are CRS-dependent. For example some CRS use longitude values increasing toward East, while some others use longitude values increasing toward West. The axis order must be specified in all CRS, and any method working with them should take their axis order and units in account.

However, map projections defined in this package are transform steps, not the full transform to the final CRS. All projections defined in this package must comply with the OGC 01-009 specification. This specification says (quoting section 10.6 at page 34):

> Cartographic projection transforms are used by projected coordinate reference systems to map geographic coordinates (e.g. longitude and latitude) into (x, y) coordinates. These (x, y) coordinates can be imagined to lie on a plane, such as a paper map or a screen. All cartographic projection transforms will have the following properties:
> - Converts from (longitude, latitude) coordinates to (x,y).
> - All angles are assumed to be decimal degrees, and all distances are assumed to be metres.
> - The domain should be a subset of {[-180 … 180)×[-90 … 90]}°.
> Although all cartographic projection transforms must have the properties listed above, many projected coordinate reference systems have different properties. For example, in Europe some projected coordinate reference systems use grads instead of decimal degrees, and often the base geographic coordinate reference system is (latitude, longitude) instead of (longitude, latitude). This means that the cartographic projected transform is often used as a single step in a series of transforms, where the other steps change units and swap coordinates.

The Apache SIS implementation extends this rule to axis directions as well, i.e. (x, y) coordinates must be (East, North) oriented.

### Implications on South oriented projections

The above rule implies a non-intuitive behavior for the Transverse Mercator (South Orientated) projection, which still projects coordinates with y values increasing toward North. The real axis flip is performed outside this projection package, upon coordinate system axis inspection, as a concatenation of the North oriented cartographic projection with an affine transform. Such axis analysis and transforms concatenation can be performed automatically by the `createBaseToDerived(…)` method defined in the `MathTransformFactory` interface. The same rule applies to the Krovak projection as well (at the opposite of what ESRI does).

In order to reduce the risk of confusion, this package never defines south oriented map projection. This rule removes ambiguity when reading a transform in Well Known Text (WKT) format, since only the north-oriented variant is used and the affine transform coefficients tell exactly which axis flips are applied.

## Projection on unit ellipse

A map projection in this package is actually the concatenation of the following transforms, in that order (ignoring axis order changes and conversions from/to units other then degrees and metres, which are not the purpose of this package):

- A normalization affine transform
- A `NormalizedProjection` subclass
- A denormalization affine transform

The first step ("normalization") converts longitude and latitude values from degrees to radians and removes the central meridian from the longitude. The last step ("denormalization") multiplies the result of the middle step by the global scale factor (typically the product of the scale factor with the semi-major axis length), then adds the false easting and false northing. This means that the middle step ("normalized projection") is performed on an ellipse (or sphere) having a semi-major axis of 1.

In other words, the transform method of the middle step works typically on longitude and latitude values in radians relative to the central meridian (not necessarily Greenwich). Its results are typically (x, y) coordinates having (East, North) axis orientation. However in some cases the actual input and output coordinates may be different than the above by some scale factor, translation or rotation, if the projection implementation choose to combine some linear coefficients with the above-cited normalization and denormalization affine transforms.

Note: In Proj.4, the same standardization is handled by `pj_fwd​.c` and `pj_inv​.c`. This normalization makes the equations closer to the ones published in Snyder's book, where the false easting, false northing and scale factor are usually not given.

## References

- IOGP. Coordinate Conversions and Transformations including Formulas.
  Geomatics Guidance Note Number 7, part 2, Version 49.
- Snyder, John P. Map Projections - A Working Manual.
  U.S. Geological Survey Professional Paper 1395, 1987.

Since:
  0.6
See Also:
  - Map projections on MathWorld

Defined in the `sis-referencing` module

- Related Packages
  Package
  Description
  org.apache.sis.referencing.operation
  Relationship between any two Coordinate Reference Systems (CRS).
  org.apache.sis.referencing.operation.builder
  Helper classes for creating Math Transforms from a set of points.
  org.apache.sis.referencing.operation.matrix
  Matrix implementations for spatiotemporal referencing.
  org.apache.sis.referencing.operation.transform
  Conversions or transformations of multi-dimensional coordinate points.
- Class
  Description
  AlbersEqualArea
  Albers Equal Area projection (EPSG code 9822).
  AzimuthalEquidistant
  Azimuthal Equidistant (Spherical) projection.
  CassiniSoldner
  Cassini-Soldner projection (EPSG codes 9806 and 9833).
  CylindricalEqualArea
  Cylindrical Equal Area projection (EPSG codes 9834, 9835).
  LambertConicConformal
  Lambert Conic Conformal projection (EPSG codes 9801, 9802, 9803, 9826, 1051).
  Mercator
  Mercator Cylindrical projection (EPSG codes 9804, 9805, 1026, 1024, 1044, 9841).
  ModifiedAzimuthalEquidistant
  Modified Azimuthal Equidistant projection (EPSG:9832).
  Mollweide
  Mollweide projection.
  NormalizedProjection
  Base class for conversion services between ellipsoidal and cartographic projections.
  NormalizedProjection.ParameterRole
  Maps the parameters to be used for initializing `NormalizedProjection` and its normalization / denormalization matrices.
  ObliqueMercator
  Oblique Mercator projection (EPSG codes 9812, 9815).
  ObliqueStereographic
  Oblique Stereographic projection (EPSG code 9809).
  Orthographic
  Orthographic projection (EPSG:9840).
  PolarStereographic
  Polar Stereographic projection (EPSG codes 9810, 9829, 9830).
  Polyconic
  American Polyconic projection (EPSG codes 9818).
  ProjectionException
  Thrown by `NormalizedProjection` when a map projection failed.
  SatelliteTracking
  Satellite-Tracking projection.
  Sinusoidal
  Sinusoidal equal-area projection, also known as "Sanson-Flamsteed".
  TransverseMercator
  Transverse Mercator projection (EPSG codes 9807).
  ZonedGridSystem
  Transverse Mercator Zoned Grid System projection (EPSG codes 9824).