Module org.opengis.geoapi

Package org.opengis.referencing.crs

Interface CRSFactory

All Superinterfaces:

Factory, ObjectFactory

@UML(identifier="CS_CoordinateSystemFactory",
     specification=OGC_01009)
public interface CRSFactory
extends ObjectFactory

Builds up complex Coordinate Reference Systems from simpler objects or values. CRSFactory allows applications to make Coordinate Reference Systems (CRS) that cannot be created by a CRSAuthorityFactory. This factory is very flexible, whereas the authority factory is easier to use. So CRSAuthorityFactory can be used to make "standard" coordinate reference systems, and CRSFactory can be used to make "special" coordinate reference systems.

For example, the EPSG authority has codes for USA state plane coordinate systems using the NAD83 datum, but these coordinate systems always use meters. EPSG does not have codes for NAD83 state plane coordinate systems that use feet units. This factory lets an application create such a hybrid coordinate system.

Default methods

All create(…) methods in this interface are optional. Unless otherwise specified in the documentation, methods that are not overridden by the implementer will throw an UnimplementedServiceException by default.

Since:

1.0

See Also:

• CSFactory
• DatumFactory

Method Summary

Modifier and Type	Method	Description
default CompoundCRS	createCompoundCRS(Map<String,?> properties, CoordinateReferenceSystem... components)	Creates a compound CRS from an ordered sequence of components.
default DerivedCRS	createDerivedCRS(Map<String,?> properties, CoordinateReferenceSystem baseCRS, Conversion conversionFromBase, CoordinateSystem derivedCS)	Creates a derived CRS.
default EngineeringCRS	createEngineeringCRS(Map<String,?> properties, EngineeringDatum datum, CoordinateSystem cs)	Creates a engineering CRS from a datum.
default EngineeringCRS	createEngineeringCRS(Map<String,?> properties, EngineeringDatum datum, DatumEnsemble<EngineeringDatum> datumEnsemble, CoordinateSystem cs)	Creates a engineering CRS from a datum or datum ensemble.
default CoordinateReferenceSystem	createFromWKT(String wkt)	Creates a CRS object from a Well-Known Text.
default CoordinateReferenceSystem	createFromXML(String xml)	Creates a CRS object from a GML string.
default GeocentricCRS	createGeocentricCRS(Map<String,?> properties, GeodeticDatum datum, CartesianCS cs)	Deprecated. The GeocentricCRS type has been removed since ISO 19111:2007.
default GeocentricCRS	createGeocentricCRS(Map<String,?> properties, GeodeticDatum datum, SphericalCS cs)	Deprecated. The GeocentricCRS type has been removed since ISO 19111:2007.
default GeodeticCRS	createGeodeticCRS(Map<String,?> properties, GeodeticDatum datum, DatumEnsemble<GeodeticDatum> datumEnsemble, CartesianCS cs)	Creates a geocentric CRS from a Cartesian coordinate system.
default GeodeticCRS	createGeodeticCRS(Map<String,?> properties, GeodeticDatum datum, DatumEnsemble<GeodeticDatum> datumEnsemble, SphericalCS cs)	Creates a geocentric CRS from a spherical coordinate system.
default GeographicCRS	createGeographicCRS(Map<String,?> properties, GeodeticDatum datum, EllipsoidalCS cs)	Creates a geographic CRS from a reference frame.
default GeographicCRS	createGeographicCRS(Map<String,?> properties, GeodeticDatum datum, DatumEnsemble<GeodeticDatum> datumEnsemble, EllipsoidalCS cs)	Creates a geographic CRS from a reference frame or datum ensemble.
default ImageCRS	createImageCRS(Map<String,?> properties, ImageDatum datum, AffineCS cs)	Deprecated. ImageCRS is replaced by EngineeringCRS as of ISO 19111:2019.
default ParametricCRS	createParametricCRS(Map<String,?> properties, ParametricDatum datum, DatumEnsemble<ParametricDatum> datumEnsemble, ParametricCS cs)	Creates a parametric CRS from a datum or datum ensemble.
default ProjectedCRS	createProjectedCRS(Map<String,?> properties, GeographicCRS baseCRS, Conversion conversionFromBase, CartesianCS derivedCS)	Creates a projected CRS from a defining conversion.
default TemporalCRS	createTemporalCRS(Map<String,?> properties, TemporalDatum datum, TimeCS cs)	Creates a temporal CRS from a datum.
default TemporalCRS	createTemporalCRS(Map<String,?> properties, TemporalDatum datum, DatumEnsemble<TemporalDatum> datumEnsemble, TimeCS cs)	Creates a temporal CRS from a datum or datum ensemble.
default VerticalCRS	createVerticalCRS(Map<String,?> properties, VerticalDatum datum, VerticalCS cs)	Creates a vertical CRS from a reference frame.
default VerticalCRS	createVerticalCRS(Map<String,?> properties, VerticalDatum datum, DatumEnsemble<VerticalDatum> datumEnsemble, VerticalCS cs)	Creates a vertical CRS from a reference frame or datum ensemble.

Methods inherited from interface org.opengis.util.Factory

getVendor

Method Details

createGeographicCRS

@UML(identifier="createGeographicCoordinateSystem",
     specification=OGC_01009)
default GeographicCRS createGeographicCRS(Map<String,?> properties,
 GeodeticDatum datum,
 EllipsoidalCS cs)
                                   throws FactoryException

Creates a geographic CRS from a reference frame. This is a shortcut for the more generic method without datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame to use in created CRS.

cs - the ellipsoidal coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createGeographicCRS

default GeographicCRS createGeographicCRS(Map<String,?> properties,
 GeodeticDatum datum,
 DatumEnsemble<GeodeticDatum> datumEnsemble,
 EllipsoidalCS cs)
                                   throws FactoryException

Creates a geographic CRS from a reference frame or datum ensemble. It could be (latitude, longitude) or (longitude, latitude). The CRS can optionally be three-dimensional with an ellipsoidal height.

At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of reference frames which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the ellipsoidal coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createGeocentricCRS

@Deprecated(since="3.1")
default GeocentricCRS createGeocentricCRS(Map<String,?> properties,
 GeodeticDatum datum,
 SphericalCS cs)
                                   throws FactoryException

Deprecated.

The GeocentricCRS type has been removed since ISO 19111:2007. Use createGeodeticCRS(Map, GeodeticDatum, DatumEnsembe, SphericalCS) instead.

Creates a geocentric CRS from a spherical coordinate system. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame.

cs - the spherical coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createGeodeticCRS

default GeodeticCRS createGeodeticCRS(Map<String,?> properties,
 GeodeticDatum datum,
 DatumEnsemble<GeodeticDatum> datumEnsemble,
 SphericalCS cs)
                               throws FactoryException

Creates a geocentric CRS from a spherical coordinate system. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of reference frames which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the spherical coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createGeocentricCRS

@Deprecated(since="3.1")
default GeocentricCRS createGeocentricCRS(Map<String,?> properties,
 GeodeticDatum datum,
 CartesianCS cs)
                                   throws FactoryException

Deprecated.

The GeocentricCRS type has been removed since ISO 19111:2007. Use createGeodeticCRS(Map, GeodeticDatum, DatumEnsemble, CartesianCS) instead.

Creates a geocentric CRS from a Cartesian coordinate system. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame.

cs - the Cartesian coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createGeodeticCRS

default GeodeticCRS createGeodeticCRS(Map<String,?> properties,
 GeodeticDatum datum,
 DatumEnsemble<GeodeticDatum> datumEnsemble,
 CartesianCS cs)
                               throws FactoryException

Creates a geocentric CRS from a Cartesian coordinate system. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - geodetic reference frame, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of reference frames which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the Cartesian coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createVerticalCRS

@UML(identifier="createVerticalCoordinateSystem",
     specification=OGC_01009)
default VerticalCRS createVerticalCRS(Map<String,?> properties,
 VerticalDatum datum,
 VerticalCS cs)
                               throws FactoryException

Creates a vertical CRS from a reference frame. This is a shortcut for the more generic method without datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - vertical datum to use in created CRS.

cs - the vertical coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createVerticalCRS

default VerticalCRS createVerticalCRS(Map<String,?> properties,
 VerticalDatum datum,
 DatumEnsemble<VerticalDatum> datumEnsemble,
 VerticalCS cs)
                               throws FactoryException

Creates a vertical CRS from a reference frame or datum ensemble. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - vertical reference frame, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of reference frames which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the vertical coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createTemporalCRS

default TemporalCRS createTemporalCRS(Map<String,?> properties,
 TemporalDatum datum,
 TimeCS cs)
                               throws FactoryException

Creates a temporal CRS from a datum. This is a shortcut for the more generic method without datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - temporal datum to use in created CRS.

cs - the temporal coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createTemporalCRS

default TemporalCRS createTemporalCRS(Map<String,?> properties,
 TemporalDatum datum,
 DatumEnsemble<TemporalDatum> datumEnsemble,
 TimeCS cs)
                               throws FactoryException

Creates a temporal CRS from a datum or datum ensemble. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - temporal datum, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of datum which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the temporal coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createParametricCRS

default ParametricCRS createParametricCRS(Map<String,?> properties,
 ParametricDatum datum,
 DatumEnsemble<ParametricDatum> datumEnsemble,
 ParametricCS cs)
                                   throws FactoryException

Creates a parametric CRS from a datum or datum ensemble. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - parametric datum, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of datum which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the parametric coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createEngineeringCRS

@UML(identifier="createLocalCoordinateSystem",
     specification=OGC_01009)
default EngineeringCRS createEngineeringCRS(Map<String,?> properties,
 EngineeringDatum datum,
 CoordinateSystem cs)
                                     throws FactoryException

Creates a engineering CRS from a datum. This is a shortcut for the more generic method without datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - engineering datum to use in created CRS.

cs - the coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createEngineeringCRS

@UML(identifier="createLocalCoordinateSystem",
     specification=OGC_01009)
default EngineeringCRS createEngineeringCRS(Map<String,?> properties,
 EngineeringDatum datum,
 DatumEnsemble<EngineeringDatum> datumEnsemble,
 CoordinateSystem cs)
                                     throws FactoryException

Creates a engineering CRS from a datum or datum ensemble. At least one of the datum and datumEnsemble arguments shall be non-null. If both are non-null, then datum shall be a member of the datum ensemble.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - engineering datum, or null if the CRS is associated only to a datum ensemble.

datumEnsemble - collection of datum which for low accuracy requirements may be considered to be insignificantly different from each other, or null if there is no such ensemble.

cs - the coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

createImageCRS

@Deprecated(since="3.1")
default ImageCRS createImageCRS(Map<String,?> properties,
 ImageDatum datum,
 AffineCS cs)
                         throws FactoryException

Deprecated.

ImageCRS is replaced by EngineeringCRS as of ISO 19111:2019.

Creates an image coordinate reference system.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

datum - image datum to use in created CRS.

cs - the Cartesian or Oblique Cartesian coordinate system for the created CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createCompoundCRS

@UML(identifier="createCompoundCoordinateSystem",
     specification=OGC_01009)
default CompoundCRS createCompoundCRS(Map<String,?> properties,
 CoordinateReferenceSystem... components)
                               throws FactoryException

Creates a compound CRS from an ordered sequence of components.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

components - the sequence of coordinate reference systems making the compound CRS.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

createDerivedCRS

@UML(identifier="createFittedCoordinateSystem",
     specification=OGC_01009)
default DerivedCRS createDerivedCRS(Map<String,?> properties,
 CoordinateReferenceSystem baseCRS,
 Conversion conversionFromBase,
 CoordinateSystem derivedCS)
                             throws FactoryException

Creates a derived CRS. The conversionFromBase argument shall contain the parameter values required for the conversion. It may or may not contain the corresponding “base to derived” transform, at user's choice. If a math transform is provided, this method may or may not use it at implementation choice. Otherwise this method shall create a math transform from the parameters.

If the transform is an affine map performing a rotation, then any mixed axes must have identical units. For example, a (latitude (°), longitude (°), height (m)) system can be rotated in the (latitude, longitude) plane, since both affected axes are in degrees. But the transform should not rotate this coordinate system in any other plane.

It is the user's responsibility to ensure that the conversion performs all required steps, including unit conversions and change of axis order, if needed. Note that this behavior is different than createProjectedCRS(…) because transforms other than cartographic projections are not standardized.

Upcoming API change — specialization
According ISO 19111, the baseCRS type should be SingleCRS. This change may be applied in GeoAPI 4.0.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

baseCRS - coordinate reference system to base the projection on. The number of axes must matches the number of source dimensions of the conversion from base.

conversionFromBase - the defining conversion.

derivedCS - the coordinate system for the derived CRS. The number of axes must matches the number of target dimensions} of the conversion from base.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

See Also:

• CoordinateOperationFactory.createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
• MathTransformFactory.createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)

createProjectedCRS

@UML(identifier="createProjectedCoordinateSystem",
     specification=OGC_01009)
default ProjectedCRS createProjectedCRS(Map<String,?> properties,
 GeographicCRS baseCRS,
 Conversion conversionFromBase,
 CartesianCS derivedCS)
                                 throws FactoryException

Creates a projected CRS from a defining conversion. The conversionFromBase argument shall contain the parameter values required for the projection. It may or may not contain the corresponding “base to derived” transform, at user's choice. If a math transform is provided, this method may or may not use it at implementation choice. Otherwise this method shall create a math transform from the parameters.

The supplied conversion should not includes the operation steps for performing axis unit conversions and change of axis order; those operations shall be inferred by this constructor by some code equivalent to:

MathTransform baseToDerived = MathTransformFactory.createBaseToDerived(baseCRS, parameters, derivedCS)

This behavior is different than createDerivedCRS(…) because parameterized transforms are standardized for projections. See the note on cartographic projections.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

baseCRS - geographic coordinate reference system to base the projection on. The number of axes must matches the number of source dimensions of the conversion from base.

conversionFromBase - the defining conversion.

derivedCS - the coordinate system for the projected CRS. The number of axes must matches the number of target dimensions of the conversion from base.

Returns:

the coordinate reference system for the given properties.

Throws:

FactoryException - if the object creation failed.

See Also:

• CoordinateOperationFactory.createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
• MathTransformFactory.createBaseToDerived(CoordinateReferenceSystem, ParameterValueGroup, CoordinateSystem)

createFromXML

@UML(identifier="createFromXML",
     specification=OGC_01009)
default CoordinateReferenceSystem createFromXML(String xml)
                                         throws FactoryException

Creates a CRS object from a GML string.

Parameters:

xml - coordinate reference system encoded in GML format.

Returns:

the coordinate reference system for the given GML.

Throws:

FactoryException - if the object creation failed.

createFromWKT

@UML(identifier="createFromWKT",
     specification=OGC_01009)
default CoordinateReferenceSystem createFromWKT(String wkt)
                                         throws FactoryException

Creates a CRS object from a Well-Known Text. Well-Known texts (WKT) may come in two formats:

• The current standard, WKT 2, is defined by ISO 19162.
• The legacy format, WKT 1, was defined by OGC 01-009.

Implementations are encouraged, but not required, to recognize both versions.

Parameters:

wkt - coordinate system encoded in Well-Known Text format.

Returns:

the coordinate reference system for the given WKT.

Throws:

FactoryException - if the object creation failed.

See Also:

• IdentifiedObject.toWKT()