Class ReferencingUtilities

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.referencing.ReferencingUtilities

public final class ReferencingUtilities extends Static
A set of static methods working on GeoAPI referencing objects. Some of those methods may be useful, but not really rigorous. This is why they do not appear in the public packages.

Do not rely on this API! It may change in incompatible way in any future release.

Since:
0.5
Version:
1.1
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Do not allow instantiation of this class.
  • Method Summary

    Modifier and Type
    Method
    Description
    static org.opengis.referencing.operation.MathTransform
    createBaseToDerived(org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.parameter.ParameterValueGroup parameters, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
    Substitute for the deprecated createBaseToDerived(…) method.
    createTransformContext(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
    Creates a context with source and target ellipsoids and coordinate systems inferred from the given CRS.
    static int
    getDimension(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns the number of dimensions of the given CRS, or 0 if null.
    static org.opengis.referencing.datum.Ellipsoid
    getEllipsoid(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns the ellipsoid used by the given coordinate reference system, or null if none.
    static org.opengis.referencing.datum.Ellipsoid
    getEllipsoidOfGeographicCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns the ellipsoid used by the specified coordinate reference system, provided that the two first dimensions use an instance of GeographicCRS.
    static double
    getGreenwichLongitude(org.opengis.referencing.datum.PrimeMeridian primeMeridian, javax.measure.Unit<javax.measure.quantity.Angle> unit)
    Returns the longitude value relative to the Greenwich Meridian, expressed in the specified units.
    static <T extends org.opengis.referencing.IdentifiedObject>
    Class<? extends T>
    getInterface(Class<T> baseType, Class<? extends T> type)
    Returns the GeoAPI interface implemented by the given class, or the class itself if the interface is unknown.
    static <T extends org.opengis.referencing.IdentifiedObject>
    Class<? extends T>
    getInterface(Class<T> baseType, T object)
    Returns the GeoAPI interface implemented by the given object, or the implementation class if the interface is unknown.
    static Class<?>
    Returns the GeoAPI interface implemented by the given object, or the implementation class if the interface is unknown.
    static Map<String,?>
    getPropertiesForModifiedCRS(org.opengis.referencing.IdentifiedObject object)
    Returns the properties of the given object but potentially with a modified name.
    static String[]
    getShortAxisNames(Vocabulary resources, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns short names for all axes of the given CRS.
    static boolean
    getSingleComponents(Iterable<? extends org.opengis.referencing.crs.CoordinateReferenceSystem> source, Collection<? super org.opengis.referencing.crs.SingleCRS> addTo)
    Copies all SingleCRS components from the given source to the given collection.
    static javax.measure.Unit<?>
    getUnit(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns the unit used for all axes in the given coordinate reference system.
    static javax.measure.Unit<?>
    getUnit(org.opengis.referencing.cs.CoordinateSystem cs)
    Returns the unit used for all axes in the given coordinate system.
    identifierToName(org.opengis.parameter.ParameterDescriptorGroup parameters, org.opengis.metadata.citation.Citation authority)
    Returns the mapping between parameter identifiers and parameter names as defined by the given authority.
    static boolean
    isEllipsoidalHeight(org.opengis.referencing.datum.VerticalDatum datum)
    Returns true if the type of the given datum is ellipsoidal.
    static boolean
    startsWithNorthEast(org.opengis.referencing.cs.CoordinateSystem cs)
    Returns true if the given coordinate system has at least 2 dimensions and the 2 first axis have (North, East) directions.
    static org.opengis.referencing.crs.GeographicCRS
    toNormalizedGeographicCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs, boolean latlon, boolean allow3D)
    Derives a geographic CRS with (longitude, latitude) axis in the specified order and in decimal degrees.
    toPropertyName(Class<?> base, Class<?> type)
    Returns the XML property name of the given interface.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • ReferencingUtilities

      private ReferencingUtilities()
      Do not allow instantiation of this class.
  • Method Details

    • getGreenwichLongitude

      public static double getGreenwichLongitude(org.opengis.referencing.datum.PrimeMeridian primeMeridian, javax.measure.Unit<javax.measure.quantity.Angle> unit)
      Returns the longitude value relative to the Greenwich Meridian, expressed in the specified units. This method provides the same functionality than DefaultPrimeMeridian.getGreenwichLongitude(Unit), but on arbitrary implementation.
      Parameters:
      primeMeridian - the prime meridian from which to get the Greenwich longitude, or null.
      unit - the unit for the prime meridian to return.
      Returns:
      the prime meridian in the given units, or 0 if the given prime meridian was null.
      See Also:
    • getUnit

      public static javax.measure.Unit<?> getUnit(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns the unit used for all axes in the given coordinate system. If not all axes use the same unit, then this method returns null.

      This method is used either when the coordinate system is expected to contain exactly one axis, or for operations that support only one units for all axes, for example Well Know Text version 1 (WKT 1) formatting.

      Parameters:
      cs - the coordinate system for which to get the unit, or null.
      Returns:
      the unit for all axis in the given coordinate system, or null.
      See Also:
    • getUnit

      public static javax.measure.Unit<?> getUnit(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Returns the unit used for all axes in the given coordinate reference system. If not all axes use the same unit, then this method returns null.

      This method is used either when the CRS is expected to contain exactly one axis, or for operations that support only one units for all axes.

      Parameters:
      crs - the coordinate reference system for which to get the unit, or null.
      Returns:
      the unit for all axis in the given coordinate system, or null.
    • getDimension

      public static int getDimension(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Returns the number of dimensions of the given CRS, or 0 if null.
      Parameters:
      crs - the CRS from which to get the number of dimensions, or null.
      Returns:
      the number of dimensions, or 0 if the given CRS or its coordinate system is null.
    • getInterface

      public static Class<?> getInterface(Object object)
      Returns the GeoAPI interface implemented by the given object, or the implementation class if the interface is unknown. This method can be used when the base type (CRS, CS, Datum…) is unknown, for example when preparing an error message. If the base type is known, then the method expecting a baseType argument should be preferred.
      Parameters:
      object - the object for which to get the GeoAPI interface, or null.
      Returns:
      GeoAPI interface or implementation class of the given object, or null if the given object is null.
    • getInterface

      public static <T extends org.opengis.referencing.IdentifiedObject> Class<? extends T> getInterface(Class<T> baseType, T object)
      Returns the GeoAPI interface implemented by the given object, or the implementation class if the interface is unknown.
      Type Parameters:
      T - compile-time value of baseType.
      Parameters:
      baseType - parent interface of the desired type.
      object - the object for which to get the GeoAPI interface, or null.
      Returns:
      GeoAPI interface or implementation class of the given object, or null if the given object is null.
    • getInterface

      public static <T extends org.opengis.referencing.IdentifiedObject> Class<? extends T> getInterface(Class<T> baseType, Class<? extends T> type)
      Returns the GeoAPI interface implemented by the given class, or the class itself if the interface is unknown.
      Type Parameters:
      T - compile-time value of baseType.
      Parameters:
      baseType - parent interface of the desired type.
      type - type of object for which to get the GeoAPI interface, or null.
      Returns:
      GeoAPI interface or implementation class, or null if the given type is null.
    • getSingleComponents

      public static boolean getSingleComponents(Iterable<? extends org.opengis.referencing.crs.CoordinateReferenceSystem> source, Collection<? super org.opengis.referencing.crs.SingleCRS> addTo) throws ClassCastException
      Copies all SingleCRS components from the given source to the given collection. For each CompoundCRS element found in the iteration, this method replaces the CompoundCRS by its components, which may themselves have other CompoundCRS. Those replacements are performed recursively until we obtain a flat view of CRS components.
      Parameters:
      source - the collection of single or compound CRS.
      addTo - where to add the single CRS in order to obtain a flat view of source.
      Returns:
      true if this method found only single CRS in source, in which case addTo got the same content (assuming that addTo was empty prior this method call).
      Throws:
      ClassCastException - if a CRS is neither a SingleCRS or a CompoundCRS.
      See Also:
    • isEllipsoidalHeight

      public static boolean isEllipsoidalHeight(org.opengis.referencing.datum.VerticalDatum datum)
      Returns true if the type of the given datum is ellipsoidal. A vertical datum is not allowed to be ellipsoidal according ISO 19111, but Apache SIS relaxes this restriction in some limited cases, for example when parsing a string in the legacy WKT 1 format. Apache SIS should not expose those vertical heights as much as possible, and instead try to combine them with three-dimensional geographic or projected CRS as soon as it can.
      Parameters:
      datum - the datum to test, or null if none.
      Returns:
      true if the given datum is non null and of ellipsoidal type.
      See Also:
    • getEllipsoid

      public static org.opengis.referencing.datum.Ellipsoid getEllipsoid(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Returns the ellipsoid used by the given coordinate reference system, or null if none. More specifically:
      • If the given CRS is an instance of SingleCRS and its datum is a GeodeticDatum, then this method returns the datum ellipsoid.
      • Otherwise if the given CRS is an instance of CompoundCRS, then this method invokes itself recursively for each component until a geodetic datum is found.
      • Otherwise this method returns null.
      Note that this method does not check if there is more than one ellipsoid (it should never be the case).
      Parameters:
      crs - the coordinate reference system for which to get the ellipsoid.
      Returns:
      the ellipsoid, or null if none.
    • getEllipsoidOfGeographicCRS

      public static org.opengis.referencing.datum.Ellipsoid getEllipsoidOfGeographicCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Returns the ellipsoid used by the specified coordinate reference system, provided that the two first dimensions use an instance of GeographicCRS. Otherwise (i.e. if the two first dimensions are not geographic), returns null.

      This method excludes geocentric CRS on intent. Some callers needs this exclusion as a way to identify which CRS in a Geographic/Geocentric conversion is the geographic one. Another point of view is to said that if this method returns a non-null value, then the coordinates are expected to be either two-dimensional or three-dimensional with an ellipsoidal height.

      Parameters:
      crs - the coordinate reference system for which to get the ellipsoid.
      Returns:
      the ellipsoid in the given CRS, or null if none.
    • toNormalizedGeographicCRS

      public static org.opengis.referencing.crs.GeographicCRS toNormalizedGeographicCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs, boolean latlon, boolean allow3D)
      Derives a geographic CRS with (longitude, latitude) axis in the specified order and in decimal degrees. If no such CRS can be obtained or created, returns null.

      This method does not set the prime meridian to Greenwich. Meridian rotation, if needed, shall be performed by the caller.

      Parameters:
      crs - a source CRS, or null.
      latlon - true for (latitude, longitude) axis order, or false for (longitude, latitude).
      allow3D - whether this method is allowed to return three-dimensional CRS (with ellipsoidal height).
      Returns:
      a two-dimensional geographic CRS with standard axes, or null if none.
    • startsWithNorthEast

      public static boolean startsWithNorthEast(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns true if the given coordinate system has at least 2 dimensions and the 2 first axis have (North, East) directions. This method is used for assertions.
      Parameters:
      cs - the coordinate system to verify.
      Returns:
      whether the coordinate system starts with (North, East) direction.
    • getPropertiesForModifiedCRS

      public static Map<String,?> getPropertiesForModifiedCRS(org.opengis.referencing.IdentifiedObject object)
      Returns the properties of the given object but potentially with a modified name. Current implement truncates the name at the first non-white character which is not a valid Unicode identifier part, with the following exception:
      • If the character is '(' and the content until the closing ')' is a valid Unicode identifier, then that part is included. The intent is to keep the prime meridian name in names like "NTF (Paris)".
      Example:
      • "NTF (Paris)" is left unchanged.
      • "WGS 84 (3D)" is truncated as "WGS 84".
      • "Ellipsoidal 2D CS. Axes: latitude, longitude. Orientations: north, east. UoM: degree" is truncated as "Ellipsoidal 2D CS".
      Parameters:
      object - the identified object to view as a properties map.
      Returns:
      a view of the identified object properties.
      See Also:
    • toPropertyName

      public static StringBuilder toPropertyName(Class<?> base, Class<?> type)
      Returns the XML property name of the given interface. For CoordinateSystem base type, the returned value shall be one of affineCS, cartesianCS, cylindricalCS, ellipsoidalCS, linearCS, parametricCS, polarCS, sphericalCS, timeCS or verticalCS.
      Parameters:
      base - the abstract base interface.
      type - the interface or classes for which to get the XML property name.
      Returns:
      the XML property name for the given class or interface, or null if none.
      See Also:
    • createTransformContext

      public static DefaultMathTransformFactory.Context createTransformContext(org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS)
      Creates a context with source and target ellipsoids and coordinate systems inferred from the given CRS. The ellipsoids will be non-null only if the given CRS is geodetic (geographic or geocentric).
      Parameters:
      sourceCRS - the CRS from which to get the source coordinate system and ellipsoid, or null.
      targetCRS - the CRS from which to get the target coordinate system and ellipsoid, or null.
      Returns:
      the context to provides to math transform factory.
    • createBaseToDerived

      public static org.opengis.referencing.operation.MathTransform createBaseToDerived(org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.parameter.ParameterValueGroup parameters, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS) throws org.opengis.util.FactoryException
      Substitute for the deprecated createBaseToDerived(…) method. This substitute uses the full targetCRS instead of only the coordinate system of the target. This is needed for setting the "tgt_semi_minor" and "tgt_semi_major" parameters of Molodensky transformation for example.
      Parameters:
      factory - the factory to use for creating the transform.
      sourceCRS - the source (base) coordinate reference system.
      parameters - the parameter values for the transform.
      targetCRS - the target (derived) coordinate system.
      Returns:
      the parameterized transform from sourceCRS to targetCRS, including unit conversions and axis swapping.
      Throws:
      org.opengis.util.FactoryException - if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.
      See Also:
    • identifierToName

      public static Map<Integer,String> identifierToName(org.opengis.parameter.ParameterDescriptorGroup parameters, org.opengis.metadata.citation.Citation authority)
      Returns the mapping between parameter identifiers and parameter names as defined by the given authority. This method assumes that the identifiers of all parameters defined by that authority are numeric. Examples of authorities defining numeric parameters are EPSG and GeoTIFF.

      The map returned by this method is modifiable. Callers are free to add or remove entries.

      Parameters:
      parameters - the parameters for which to get a mapping from identifiers to names.
      authority - the authority defining the parameters.
      Returns:
      mapping from parameter identifiers to parameter names defined by the given authority.
      Throws:
      NumberFormatException - if a parameter identifier of the given authority is not numeric.
      IllegalArgumentException - if the same identifier is used for two or more parameters.
    • getShortAxisNames

      public static String[] getShortAxisNames(Vocabulary resources, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Returns short names for all axes of the given CRS. This method uses short names like "Latitude" or "Height", even if the full ISO 19111 names are "Geodetic latitude" or "Ellipsoidal height". This is suitable as header for columns in a table. This method does not include abbreviation or units in the returned names.
      Parameters:
      resources - the resources from which to get "latitude" and "longitude" localized labels.
      crs - the coordinate reference system from which to get axis names.
      Returns:
      axis names, localized if possible.