Class GeodeticObjectBuilder

java.lang.Object
org.apache.sis.referencing.Builder<GeodeticObjectBuilder>
org.apache.sis.internal.referencing.GeodeticObjectBuilder

public class GeodeticObjectBuilder extends Builder<GeodeticObjectBuilder>
Helper methods for building Coordinate Reference Systems and related objects. In current version, each builder instance should be used for creating only one CRS. Reusing the same builder for creating many CRS has unspecified behavior.

For now, this class is defined in the internal package because this API needs more experimentation. However, this class may move in a public package later if we feel confident that its API is mature enough.

Since:
0.6
Version:
1.3
  • Field Details

    • datum

      private org.opengis.referencing.datum.GeodeticDatum datum
      The geodetic datum, or null if none.
    • conversionName

      private String conversionName
      The name of the conversion to use for creating a ProjectedCRS or DerivedCRS. This name is for information purpose; its value does not impact the numerical results of coordinate operations.
      See Also:
    • method

      private org.opengis.referencing.operation.OperationMethod method
      The conversion method used by ProjectedCRS or DerivedCRS, or null if unspecified.
      See Also:
    • parameters

      private org.opengis.parameter.ParameterValueGroup parameters
      The projection parameters, or null if not applicable.
    • factories

      private final ReferencingFactoryContainer factories
      Group of factories used by this builder.
    • locale

      private final Locale locale
      The locale for error messages, or null for default locale.
    • normalizedAxisOrder

      private boolean normalizedAxisOrder
      Whether to use the axis order defined by AxesConvention.NORMALIZED.
      See Also:
  • Constructor Details

    • GeodeticObjectBuilder

      public GeodeticObjectBuilder()
      Creates a new builder with default locale and set of factories.
    • GeodeticObjectBuilder

      public GeodeticObjectBuilder(ReferencingFactoryContainer factories, Locale locale)
      Creates a new builder using the given factories and locale.
      Parameters:
      factories - the factories to use for geodetic objects creation, or null for default.
      locale - the locale for error message in exceptions, or null for default.
  • Method Details

    • name

      private static Map<String,Object> name(org.opengis.referencing.IdentifiedObject template)
      Creates a map of properties containing only the name of the given object.
    • setNormalizedAxisOrder

      public GeodeticObjectBuilder setNormalizedAxisOrder(boolean normalized)
      Sets whether axes should be in (longitude, latitude) order instead of (latitude, longitude). This flag applies to geographic CRS created by this builder.
      Parameters:
      normalized - whether axes should be in (longitude, latitude) order instead of (latitude, longitude).
      Returns:
      this, for method call chaining.
      See Also:
    • setDomainOfValidity

      public GeodeticObjectBuilder setDomainOfValidity(CharSequence description, double westBoundLongitude, double eastBoundLongitude, double southBoundLatitude, double northBoundLatitude)
      Sets the domain of validity as a geographic bounding box set to the specified values. The bounding box crosses the anti-meridian if eastBoundLongitude < westBoundLongitude. If this method has already been invoked previously, the new value overwrites the previous one.
      Parameters:
      description - a textual description of the domain of validity, or null if none.
      westBoundLongitude - the minimal λ value.
      eastBoundLongitude - the maximal λ value.
      southBoundLatitude - the minimal φ value.
      northBoundLatitude - the maximal φ value.
      Returns:
      this, for method call chaining.
      Throws:
      IllegalArgumentException - if (south bound > north bound). Note that NaN values are allowed.
    • setFlattenedSphere

      public GeodeticObjectBuilder setFlattenedSphere(String name, double semiMajorAxis, double inverseFlattening, javax.measure.Unit<javax.measure.quantity.Length> units) throws org.opengis.util.FactoryException
      Creates a geodetic datum with an ellipsoid of the given shape.
      Parameters:
      name - ellipsoid and datum name.
      semiMajorAxis - equatorial radius in supplied linear units.
      inverseFlattening - eccentricity of ellipsoid. An infinite value creates a sphere.
      units - linear units of major axis.
      Returns:
      this, for method call chaining.
      Throws:
      org.opengis.util.FactoryException - if the datum cannot be created.
    • setConversionMethod

      public GeodeticObjectBuilder setConversionMethod(String name) throws org.opengis.util.FactoryException
      Sets the conversion method to use for creating a ProjectedCRS or DerivedCRS. The method is typically a map projection method. Examples:
      • Lambert Conic Conformal (1SP)
      • Lambert Conic Conformal (2SP)
      • Mercator (variant A)
      • Mercator (variant B)
      • Mercator (variant C)
      • Popular Visualisation Pseudo Mercator
      This method can be invoked only once.
      Parameters:
      name - name of the conversion method.
      Returns:
      this, for method call chaining.
      Throws:
      org.opengis.util.FactoryException - if the operation method of the given name cannot be obtained.
    • setConversionName

      public GeodeticObjectBuilder setConversionName(String name)
      Sets the name of the conversion to use for creating a ProjectedCRS or DerivedCRS. This name is for information purpose; its value does not impact the numerical results of coordinate operations.
      Parameters:
      name - the name to give to the conversion.
      Returns:
      this, for method calls chaining.
    • setConversion

      public GeodeticObjectBuilder setConversion(org.opengis.parameter.ParameterValueGroup parameters) throws org.opengis.util.FactoryException
      Sets the conversion method together with all parameters. This method does not set the conversion name. If a name different than the default is desired, setConversionName(String) should be invoked.
      Parameters:
      parameters - the map projection parameter values.
      Returns:
      this, for method calls chaining.
      Throws:
      org.opengis.util.FactoryException - if the operation method cannot be obtained.
    • ensureConversionMethodSet

      private void ensureConversionMethodSet()
      Ensures that setConversionMethod(String) has been invoked.
    • setParameter

      public GeodeticObjectBuilder setParameter(String name, double value, javax.measure.Unit<?> unit) throws IllegalStateException, org.opengis.parameter.ParameterNotFoundException, org.opengis.parameter.InvalidParameterValueException
      Sets the value of a numeric parameter. The setConversionMethod(String) method must have been invoked exactly once before this method. Calls to this setParameter(…) can be repeated as many times as needed.
      Parameters:
      name - the parameter name.
      value - the value to give to the parameter.
      unit - unit of measurement for the given value.
      Returns:
      this, for method calls chaining.
      Throws:
      IllegalStateException - if setConversionMethod(String) has not been invoked before this method.
      org.opengis.parameter.ParameterNotFoundException - if there is no parameter of the given name.
      org.opengis.parameter.InvalidParameterValueException - if the parameter does not accept the given value.
    • changeConversion

      public GeodeticObjectBuilder changeConversion(String newMethod, BiConsumer<org.opengis.parameter.ParameterValue<?>,Parameters> mapper) throws org.opengis.util.FactoryException
      Replaces the current operation method by a new one with parameter values derived form the old method. This method can be invoked for replacing a projection by another one with a similar set of parameters.

      If non-null, the given mapper is used for copying parameter values from the old projection. The accept(ParameterValue<?> source, Parameters target) method is invoked where source is a parameter value of the old projection and target is the group of parameters where to set the values for new projection. If mapper is null, then the default implementation is as below:

      Parameters:
      newMethod - name of the new operation method, or null if no change.
      mapper - mapper from old parameters to new parameters, or null for verbatim copy.
      Returns:
      this, for method calls chaining.
      Throws:
      IllegalStateException - if setConversionMethod(String) has not been invoked before this method.
      org.opengis.util.FactoryException - if the operation method of the given name cannot be obtained.
      ClassCastException - if a parameter value of the old projection is not an instance of ParameterValue (this restriction may change in a future version).
    • copyParameterValue

      private static void copyParameterValue(org.opengis.parameter.ParameterValue<?> source, Parameters target)
      The default mapper of changeConversion(String, BiConsumer).
      Parameters:
      source - parameter value of the old projection.
      target - group of parameters of the new projection where to copy source parameter value.
    • apply

      public GeodeticObjectBuilder apply(org.opengis.referencing.crs.ProjectedCRS crs)
      Sets the operation method, parameters, conversion name and datum for the same projection than the given CRS. Metadata such as domain of validity are inherited, except identifiers.
      Parameters:
      crs - the projected CRS from which to inherit the properties.
      Returns:
      this, for method call chaining.
    • applyTransverseMercator

      public GeodeticObjectBuilder applyTransverseMercator(TransverseMercator.Zoner zoner, double latitude, double longitude) throws org.opengis.util.FactoryException
      Sets the operation method, parameters and conversion name for a Transverse Mercator projection. This convenience method delegates to the following methods:
      Transverse Mercator parameters
      Parameter name Parameter value
      Latitude of natural origin Given latitude, snapped to 0° in the UTM case
      Longitude of natural origin Given longitude, optionally snapped to a UTM zone
      Scale factor at natural origin 0.9996 in UTM case
      False easting 500000 metres in UTM case
      False northing 0 (North hemisphere) or 10000000 (South hemisphere) metres
      Note that calculation of UTM zone contains special cases for Norway and Svalbard. If not desired, those exceptions can be avoided by making sure that the given latitude is below 56°N.

      If the given zoner is ANY, then this method will use the given latitude and longitude verbatim (without snapping them to a zone) but will still use the UTM scale factor, false easting and false northing.

      Parameters:
      zoner - whether to use UTM or MTM zones, or ANY for using arbitrary central meridian.
      latitude - the latitude in the center of the desired projection.
      longitude - the longitude in the center of the desired projection.
      Returns:
      this, for method calls chaining.
      Throws:
      org.opengis.util.FactoryException - if the operation method for the Transverse Mercator projection cannot be obtained.
      See Also:
    • applyPolarStereographic

      public GeodeticObjectBuilder applyPolarStereographic(boolean north) throws org.opengis.util.FactoryException
      Sets the operation method, parameters and conversion name for a Polar Stereographic projection. This convenience method delegates to the following methods:
      Universal Polar Stereographic parameters
      Parameter name Parameter value
      Latitude of natural origin 90°N or 90°S
      Longitude of natural origin
      Scale factor at natural origin 0.994
      False easting 2000000 metres
      False northing 2000000 metres
      Parameters:
      north - true for North pole, or false for South pole.
      Returns:
      this, for method calls chaining.
      Throws:
      org.opengis.util.FactoryException - if the operation method for the Polar Stereographic (variant A) projection cannot be obtained.
    • createProjectedCRS

      public org.opengis.referencing.crs.ProjectedCRS createProjectedCRS(org.opengis.referencing.crs.GeographicCRS baseCRS, org.opengis.referencing.cs.CartesianCS derivedCS) throws org.opengis.util.FactoryException
      Creates a projected CRS using a conversion built from the values given by the setParameter(…) calls.
      Example: The following example creates a projected CRS for the "NTF (Paris) / Lambert zone II" projection, from a base CRS which is presumed to already exists in this example.
      Parameters:
      baseCRS - coordinate reference system to base the derived CRS on.
      derivedCS - the coordinate system for the derived CRS, or null for the default.
      Returns:
      the projected CRS.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while building the projected CRS.
    • createProjectedCRS

      public org.opengis.referencing.crs.ProjectedCRS createProjectedCRS() throws org.opengis.util.FactoryException
      Creates a projected CRS with base CRS on the datum previously specified to this builder and with default axes. The base CRS uses the ellipsoid specified by setFlattenedSphere(String, double, double, Unit).
      Returns:
      the projected CRS.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while building the projected CRS.
    • getBaseCRS

      private org.opengis.referencing.crs.GeographicCRS getBaseCRS()
      Returns the CRS to use as the base of a projected CRS.
    • createGeographicCRS

      public org.opengis.referencing.crs.GeographicCRS createGeographicCRS() throws org.opengis.util.FactoryException
      Creates a geographic CRS.
      Returns:
      the geographic coordinate reference system.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while building the geographic CRS.
    • createTemporalCRS

      public org.opengis.referencing.crs.TemporalCRS createTemporalCRS(Date origin, javax.measure.Unit<javax.measure.quantity.Time> unit) throws org.opengis.util.FactoryException
      Creates a temporal CRS from the given origin and temporal unit. For this method, the CRS name is optional: if no addName(…) method has been invoked, then a default name will be used.
      Parameters:
      origin - the epoch in milliseconds since January 1st, 1970 at midnight UTC.
      unit - the unit of measurement.
      Returns:
      a temporal CRS using the given origin and units.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while building the temporal CRS.
    • createCompoundCRS

      public org.opengis.referencing.crs.CoordinateReferenceSystem createCompoundCRS(org.opengis.referencing.crs.CoordinateReferenceSystem... components) throws org.opengis.util.FactoryException
      Creates a compound CRS, but we special processing for (two-dimensional Geographic + ellipsoidal heights) tuples. If any such tuple is found, a three-dimensional geographic CRS is created instead of the compound CRS.
      Parameters:
      components - ordered array of CoordinateReferenceSystem objects.
      Returns:
      the coordinate reference system for the given properties.
      Throws:
      org.opengis.util.FactoryException - if the object creation failed.
    • replaceComponent

      public org.opengis.referencing.crs.CoordinateReferenceSystem replaceComponent(org.opengis.referencing.crs.CoordinateReferenceSystem source, int firstDimension, org.opengis.referencing.crs.CoordinateReferenceSystem replacement) throws org.opengis.util.FactoryException
      Replaces the component starting at given index by the given component. This method can be used for replacing e.g. the horizontal component of a CRS, or the vertical component, etc.. If a new compound CRS needs to be created and a name has been specified, that name will be used.

      Limitations

      Current implementation can replace exactly one component of CompoundCRS. If the given replacement spans more than one component, then this method will fail.
      Parameters:
      source - the coordinate reference system in which to replace a component.
      firstDimension - index of the first dimension to replace.
      replacement - the component to insert in place of the CRS component at given index.
      Returns:
      a CRS with the component replaced.
      Throws:
      org.opengis.util.FactoryException - if the object creation failed.
      See Also: