Class GeodeticObjectBuilder
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 Summary
FieldsModifier and TypeFieldDescriptionprivate String
The name of the conversion to use for creating aProjectedCRS
orDerivedCRS
.private org.opengis.referencing.datum.GeodeticDatum
The geodetic datum, ornull
if none.private final ReferencingFactoryContainer
Group of factories used by this builder.private final Locale
The locale for error messages, ornull
for default locale.private org.opengis.referencing.operation.OperationMethod
The conversion method used byProjectedCRS
orDerivedCRS
, ornull
if unspecified.private boolean
Whether to use the axis order defined byAxesConvention.NORMALIZED
.private org.opengis.parameter.ParameterValueGroup
The projection parameters, ornull
if not applicable.Fields inherited from class org.apache.sis.referencing.Builder
properties
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new builder with default locale and set of factories.GeodeticObjectBuilder
(ReferencingFactoryContainer factories, Locale locale) Creates a new builder using the given factories and locale. -
Method Summary
Modifier and TypeMethodDescriptionapply
(org.opengis.referencing.crs.ProjectedCRS crs) Sets the operation method, parameters, conversion name and datum for the same projection than the given CRS.applyPolarStereographic
(boolean north) Sets the operation method, parameters and conversion name for a Polar Stereographic projection.applyTransverseMercator
(TransverseMercator.Zoner zoner, double latitude, double longitude) Sets the operation method, parameters and conversion name for a Transverse Mercator projection.changeConversion
(String newMethod, BiConsumer<org.opengis.parameter.ParameterValue<?>, Parameters> mapper) Replaces the current operation method by a new one with parameter values derived form the old method.private static void
copyParameterValue
(org.opengis.parameter.ParameterValue<?> source, Parameters target) The defaultmapper
ofchangeConversion(String, BiConsumer)
.org.opengis.referencing.crs.CoordinateReferenceSystem
createCompoundCRS
(org.opengis.referencing.crs.CoordinateReferenceSystem... components) Creates a compound CRS, but we special processing for (two-dimensional Geographic + ellipsoidal heights) tuples.org.opengis.referencing.crs.GeographicCRS
Creates a geographic CRS.org.opengis.referencing.crs.ProjectedCRS
Creates a projected CRS with base CRS on the datum previously specified to this builder and with default axes.org.opengis.referencing.crs.ProjectedCRS
createProjectedCRS
(org.opengis.referencing.crs.GeographicCRS baseCRS, org.opengis.referencing.cs.CartesianCS derivedCS) Creates a projected CRS using a conversion built from the values given by thesetParameter(…)
calls.org.opengis.referencing.crs.TemporalCRS
createTemporalCRS
(Date origin, javax.measure.Unit<javax.measure.quantity.Time> unit) Creates a temporal CRS from the given origin and temporal unit.private void
Ensures thatsetConversionMethod(String)
has been invoked.private org.opengis.referencing.crs.GeographicCRS
Returns the CRS to use as the base of a projected CRS.name
(org.opengis.referencing.IdentifiedObject template) Creates a map of properties containing only the name of the given object.org.opengis.referencing.crs.CoordinateReferenceSystem
replaceComponent
(org.opengis.referencing.crs.CoordinateReferenceSystem source, int firstDimension, org.opengis.referencing.crs.CoordinateReferenceSystem replacement) Replaces the component starting at given index by the given component.setConversion
(org.opengis.parameter.ParameterValueGroup parameters) Sets the conversion method together with all parameters.setConversionMethod
(String name) Sets the conversion method to use for creating aProjectedCRS
orDerivedCRS
.setConversionName
(String name) Sets the name of the conversion to use for creating aProjectedCRS
orDerivedCRS
.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.setFlattenedSphere
(String name, double semiMajorAxis, double inverseFlattening, javax.measure.Unit<javax.measure.quantity.Length> units) Creates a geodetic datum with an ellipsoid of the given shape.setNormalizedAxisOrder
(boolean normalized) Sets whether axes should be in (longitude, latitude) order instead of (latitude, longitude).setParameter
(String name, double value, javax.measure.Unit<?> unit) Sets the value of a numeric parameter.Methods inherited from class org.apache.sis.referencing.Builder
addIdentifier, addIdentifier, addIdentifier, addName, addName, addName, addName, addNameAndIdentifier, addNamesAndIdentifiers, onCreate, reidentify, rename, setCodeSpace, setDeprecated, setDescription, setRemarks, setVersion
-
Field Details
-
datum
private org.opengis.referencing.datum.GeodeticDatum datumThe geodetic datum, ornull
if none. -
conversionName
The name of the conversion to use for creating aProjectedCRS
orDerivedCRS
. 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 methodThe conversion method used byProjectedCRS
orDerivedCRS
, ornull
if unspecified.- See Also:
-
parameters
private org.opengis.parameter.ParameterValueGroup parametersThe projection parameters, ornull
if not applicable. -
factories
Group of factories used by this builder. -
locale
The locale for error messages, ornull
for default locale. -
normalizedAxisOrder
private boolean normalizedAxisOrderWhether to use the axis order defined byAxesConvention.NORMALIZED
.- See Also:
-
-
Constructor Details
-
GeodeticObjectBuilder
public GeodeticObjectBuilder()Creates a new builder with default locale and set of factories. -
GeodeticObjectBuilder
Creates a new builder using the given factories and locale.- Parameters:
factories
- the factories to use for geodetic objects creation, ornull
for default.locale
- the locale for error message in exceptions, ornull
for default.
-
-
Method Details
-
name
Creates a map of properties containing only the name of the given object. -
setNormalizedAxisOrder
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 ifeastBoundLongitude
<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, ornull
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 aProjectedCRS
orDerivedCRS
. 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
- 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
Sets the name of the conversion to use for creating aProjectedCRS
orDerivedCRS
. 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 thatsetConversionMethod(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. ThesetConversionMethod(String)
method must have been invoked exactly once before this method. Calls to thissetParameter(…)
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
- ifsetConversionMethod(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.FactoryExceptionReplaces 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. Theaccept(ParameterValue<?> source, Parameters target)
method is invoked wheresource
is a parameter value of the old projection andtarget
is the group of parameters where to set the values for new projection. Ifmapper
is null, then the default implementation is as below:- Parameters:
newMethod
- name of the new operation method, ornull
if no change.mapper
- mapper from old parameters to new parameters, ornull
for verbatim copy.- Returns:
this
, for method calls chaining.- Throws:
IllegalStateException
- ifsetConversionMethod(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 ofParameterValue
(this restriction may change in a future version).
-
copyParameterValue
private static void copyParameterValue(org.opengis.parameter.ParameterValue<?> source, Parameters target) The defaultmapper
ofchangeConversion(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
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:setConversionName(String)
with a name like "Transverse Mercator" or "UTM zone 10N", depending on the arguments given to this method.setConversionMethod(String)
with the name of the Transverse Mercator projection method.setParameter(String, double, Unit)
for each of the parameters enumerated below:
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.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 If the given
zoner
isANY
, 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, orANY
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:setConversionName(String)
with a name like "Universal Polar Stereographic North", depending on the argument given to this method.setConversionMethod(String)
with the name of the Polar Stereographic (variant A) projection method.setParameter(String, double, Unit)
for each of the parameters enumerated below:
Universal Polar Stereographic parameters Parameter name Parameter value Latitude of natural origin 90°N or 90°S Longitude of natural origin 0° Scale factor at natural origin 0.994 False easting 2000000 metres False northing 2000000 metres - Parameters:
north
-true
for North pole, orfalse
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 thesetParameter(…)
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, ornull
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.FactoryExceptionCreates 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 bysetFlattenedSphere(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.FactoryExceptionCreates 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 noaddName(…)
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 ofCoordinateReferenceSystem
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 ofCompoundCRS
. 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:
-