org.apache.sis.storage.gdal

## Class Proj4Factory

- Object
- - AbstractFactory
  - - GeodeticAuthorityFactory
    - - Proj4Factory

- All Implemented Interfaces:
    AuthorityFactory, CRSAuthorityFactory, Factory

      public class Proj4Factory
      extends GeodeticAuthorityFactory
      implements CRSAuthorityFactory

  A factory for Coordinate Reference Systems created from Proj.4 definitions. This authority factory recognizes codes in the `"Proj4"` name space. The main methods in this class are:
  - `getAuthority()`
  - `createCoordinateReferenceSystem(String)`
  - `createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, boolean)`
  - `createParameterizedTransform(ParameterValueGroup)`
  Other methods delegate to one of above-cited methods if possible, or throw a `FactoryException` otherwise.
  Since:
    0.8

  Defined in the `sis-gdal` module

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Proj4Factory()` Creates a default factory.
    `Proj4Factory(Map<String,?> properties)` Creates a new Proj.4 factory.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CoordinateReferenceSystem` | `createCoordinateReferenceSystem(String code)` Creates a new CRS from the given Proj.4 definition.
    `IdentifiedObject` | `createObject(String code)` Creates a new geodetic object from the given Proj.4 definition.
    `CoordinateOperation` | `createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, boolean force)` Creates an operation for conversion or transformation between two coordinate reference systems.
    `MathTransform` | `createParameterizedTransform(ParameterValueGroup parameters)` Creates a transform from a group of parameters.
    `Citation` | `getAuthority()` Returns the project that defines the codes recognized by this factory.
    `Set<String>` | `getAuthorityCodes(Class<? extends IdentifiedObject> type)` Returns the set of authority codes for objects of the given type.
    `Set<OperationMethod>` | `getAvailableMethods(Class<? extends SingleOperation> type)` Returns some map projection methods supported by Proj.4.
    `Set<String>` | `getCodeSpaces()` Returns the code space of the authority.
    `ParameterValueGroup` | `getDefaultParameters(String method)` Returns the default parameter values for a math transform using the given operation method.
    `OperationMethod` | `getOperationMethod(String name)` Returns the operation method of the given name.

    - ### Methods inherited from class GeodeticAuthorityFactory

      `createCartesianCS, createCompoundCRS, createCoordinateOperation, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createDatum, createDerivedCRS, createEllipsoid, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createExtent, createFromCoordinateReferenceSystemCodes, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createOperationMethod, createParameterDescriptor, createParametricCRS, createParametricCS, createParametricDatum, createPolarCS, createPrimeMeridian, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createUnit, createVerticalCRS, createVerticalCS, createVerticalDatum, getDescriptionText, newIdentifiedObjectFinder, toString, trimNamespace`

    - ### Methods inherited from class AbstractFactory

      `getVendor`

    - ### Methods inherited from class Object

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

    - ### Methods inherited from interface CRSAuthorityFactory

      `createCompoundCRS, createDerivedCRS, createEngineeringCRS, createGeocentricCRS, createGeographicCRS, createImageCRS, createProjectedCRS, createTemporalCRS, createVerticalCRS`

    - ### Methods inherited from interface AuthorityFactory

      `getDescriptionText`

    - ### Methods inherited from interface Factory

      `getVendor`

- - ### Constructor Detail

    - #### Proj4Factory

          public Proj4Factory()

      Creates a default factory.

    - #### Proj4Factory

          public Proj4Factory(Map<String,?> properties)

      Creates a new Proj.4 factory. The `properties` argument is an optional map for specifying common properties shared by the objects to create. Some available properties are listed there. Unknown properties, or properties that do not apply, or properties for which `Proj4Factory` supplies itself a value, are ignored.
      Parameters:
        `properties` - common properties for the objects to create, or `null` if none.

  - ### Method Detail

    - #### getAuthority

          public Citation getAuthority()

      Returns the project that defines the codes recognized by this factory. The authority determines the code space.
      Specified by:
        `getAuthority` in interface `AuthorityFactory`
      Specified by:
        `getAuthority` in class `GeodeticAuthorityFactory`
      Returns:
        `Citations​.PROJ4`.
      See Also:
        `AbstractFactory​.getVendor()`

    - #### getCodeSpaces

          public Set<String> getCodeSpaces()

      Returns the code space of the authority. The code space is the prefix that may appear before codes. It allows to differentiate Proj.4 definitions from EPSG codes or other authorities. The code space is removed by `createCoordinateReferenceSystem(String)` before the definition string is passed to Proj.4
      Example a complete identifier can be `"Proj4:+init=epsg:4326"`. Note that this is not equivalent to the standard `"EPSG:4326"` definition since the axis order is not the same. The `"Proj4:"` prefix specifies that the remaining part of the string is a Proj.4 definition; the presence of an `"epsg"` word in the definition does not change that fact.
      Overrides:
        `getCodeSpaces` in class `GeodeticAuthorityFactory`
      Returns:
        `"Proj4"`.

    - #### getAuthorityCodes

          public Set<String> getAuthorityCodes(Class<? extends IdentifiedObject> type)
                                        throws FactoryException

      Returns the set of authority codes for objects of the given type. Current implementation can not return complete Proj.4 definition strings. Instead, this method currently returns only fragments (e.g. `"+proj=lcc"`).
      Specified by:
        `getAuthorityCodes` in interface `AuthorityFactory`
      Parameters:
        `type` - the spatial reference objects type.
      Returns:
        fragments of definition strings for spatial reference objects of the given type.
      Throws:
        `FactoryException` - if access to the underlying database failed.

    - #### getAvailableMethods

          public Set<OperationMethod> getAvailableMethods(Class<? extends SingleOperation> type)

      Returns some map projection methods supported by Proj.4. Current implementation can not return the complete list of Proj.4 method, but returns the main ones. For each operation method in the returned set, the Proj.4 projection name can be obtained as below:

          String proj = IdentifiedObjects.getName(method, Citations.PROJ4);

      The `proj` names obtained as above can be given in argument to the `getOperationMethod(String)` and `getDefaultParameters(String)` methods.
      Parameters:
        `type` - `SingleOperation.class` for fetching all operation methods, or `Projection.class` for fetching only map projection methods.
      Returns:
        methods available in this factory for coordinate operations of the given type.
      See Also:
        `DefaultMathTransformFactory​.getAvailableMethods(Class)`

    - #### getOperationMethod

          public OperationMethod getOperationMethod(String name)
                                             throws FactoryException

      Returns the operation method of the given name. The given argument can be a Proj.4 projection name, but other authorities (OGC, EPSG…) are also accepted. A partial list of supported projection names can be obtained by `getAvailableMethods(Class)`. Some examples of Proj.4 projection names are given below (not all of them are supported by this Proj.4 wrapper).

      Some Proj.4 projection names
      Name | Meaning
      --- | ---
      `aea` | Albers Equal-Area Conic
      `aeqd` | Azimuthal Equidistant
      `cass` | Cassini-Soldner
      `cea` | Cylindrical Equal Area
      `eck4` | Eckert IV
      `eck6` | Eckert VI
      `eqdc` | Equidistant Conic
      `gall` | Gall Stereograpic
      `geos` | Geostationary Satellite View
      `gnom` | Gnomonic
      `krovak` | Krovak Oblique Conic Conformal
      `laea` | Lambert Azimuthal Equal Area
      `lcc` | Lambert Conic Conformal
      `merc` | Mercator
      `mill` | Miller Cylindrical
      `moll` | Mollweide
      `nzmg` | New Zealand Map Grid
      `omerc` | Oblique Mercator
      `ortho` | Orthographic
      `sterea` | Oblique Stereographic
      `stere` | Stereographic
      `robin` | Robinson
      `sinu` | Sinusoidal
      `tmerc` | Transverse Mercator
      `vandg` | VanDerGrinten

      The default implementation delegates to a `DefaultCoordinateOperationFactory` instance. It works because the Apache SIS operation methods declare the Proj.4 projection names as aliases.
      Parameters:
        `name` - the name of the operation method to fetch.
      Returns:
        the operation method of the given name.
      Throws:
        `FactoryException` - if the requested operation method can not be fetched.
      See Also:
        `DefaultCoordinateOperationFactory​.getOperationMethod(String)`

    - #### getDefaultParameters

          public ParameterValueGroup getDefaultParameters(String method)
                                                   throws NoSuchIdentifierException

      Returns the default parameter values for a math transform using the given operation method. The given argument can be a Proj.4 projection name, but other authorities (OGC, EPSG…) are also accepted. A partial list of supported projection names can be obtained by `getAvailableMethods(Class)`. The returned parameters can be given to `createParameterizedTransform(ParameterValueGroup)`.
      Parameters:
        `method` - the case insensitive name of the coordinate operation method to search for.
      Returns:
        a new group of parameter values for the `OperationMethod` identified by the given name.
      Throws:
        `NoSuchIdentifierException` - if there is no method registered for the given name or identifier.

    - #### createParameterizedTransform

          public MathTransform createParameterizedTransform(ParameterValueGroup parameters)
                                                     throws FactoryException

      Creates a transform from a group of parameters. The `OperationMethod` name is inferred from the parameter group name. Each parameter value is formatted as a Proj.4 parameter in a definition string.
      Example:

          ParameterValueGroup p = factory.getDefaultParameters("Mercator");
          p.parameter("semi_major").setValue(6378137.000);
          p.parameter("semi_minor").setValue(6356752.314);
          MathTransform mt = factory.createParameterizedTransform(p);

      The corresponding Proj.4 definition string is:

          +proj=merc +a=6378137.0 +b=6356752.314

      Parameters:
        `parameters` - the parameter values.
      Returns:
        the parameterized transform.
      Throws:
        `FactoryException` - if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.
      See Also:
        `getDefaultParameters(String)`, `getAvailableMethods(Class)`

    - #### createObject

          public IdentifiedObject createObject(String code)
                                        throws FactoryException

      Creates a new geodetic object from the given Proj.4 definition. The default implementation delegates to `createCoordinateReferenceSystem(String)`.
      Specified by:
        `createObject` in interface `AuthorityFactory`
      Specified by:
        `createObject` in class `GeodeticAuthorityFactory`
      Parameters:
        `code` - the Proj.4 definition of the geodetic object to create.
      Returns:
        a geodetic created from the given definition.
      Throws:
        `FactoryException` - if the geodetic object can not be created for the given definition.
      See Also:
        `AbstractIdentifiedObject`

    - #### createCoordinateReferenceSystem

          public CoordinateReferenceSystem createCoordinateReferenceSystem(String code)
                                                                    throws FactoryException

      Creates a new CRS from the given Proj.4 definition. The `"Proj4:"` prefix (ignoring case), if present, is ignored.
      Apache SIS extension
      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:
      - 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)
      Specified by:
        `createCoordinateReferenceSystem` in interface `CRSAuthorityFactory`
      Overrides:
        `createCoordinateReferenceSystem` in class `GeodeticAuthorityFactory`
      Parameters:
        `code` - the Proj.4 definition of the CRS object to create.
      Returns:
        a CRS created from the given definition.
      Throws:
        `FactoryException` - if the CRS object can not be created for the given definition.
      See Also:
        `Proj4​.createCRS(String, int)`

    - #### createOperation

          public 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 factory. 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.
      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:
        `FactoryException` - if `force` is `true` and this method can not create Proj.4 transform for the given pair of coordinate reference systems.
      See Also:
        `Proj4​.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, boolean)`, `DefaultCoordinateOperationFactory​.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem)`

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