Allows you to create and modify spatial references with custom tolerance and resolution values. More...
| Header | #include <Spatial |
| Since | Esri |
| Inherits | Esri |
Public Functions
| bool | is |
| double | resolution() const |
| void | set |
| void | set |
| void | set |
| void | set |
| Esri | to |
| double | tolerance() const |
| Esri | unit() const |
| double | vertical |
| double | vertical |
| Esri | vertical |
| int | vertical |
| Q | wk |
| int | wkid() const |
Static Public Members
| Esri | create(const Esri |
| Esri | create(const Q |
| Esri | create(int wkid, Q |
| Esri | create(int wkid, int vertical |
Detailed Description
Spatial references have default precision properties when created using SpatialReference constructors from well-known ID (WKID) numbers or a well-known text (WKT) string. Esri strongly recommends using the default precision values in most cases because they have proved to perform quite well for most situations. Learn more about the properties of a spatial reference.
Users with high-accuracy data capture and storage workflows may require non-default precision values. The SpatialReferenceBuilder allows you to create SpatialReference objects and customize the precision properties SpatialReference::tolerance and SpatialReference::resolution, using the following workflow.
1. Create the SpatialReferenceBuilder by WKID, WKT string, or from an existing SpatialReference. 1. Change tolerance and/or resolution as required. 1. Use isValid after changing properties to check the new values are valid and consistent with each other - for example, tolerance must be at least twice resolution. 1. Call toSpatialReference to produce a SpatialReference.
You can now use the new custom precision SpatialReference as required. For example:
- When creating a new geodatabase table, setting TableDescription::spatialReference with a custom SpatialReference::resolution determines the precision with which the coordinate values are stored. Note that shapefiles and also non-Esri data sources do not support storing coordinate values with resolution, and therefore any resolution set will be ignored in such cases.
- Perform relational or topological GeometryEngine operations with a custom tolerance, by creating a Geometry with your customized SpatialReference::tolerance, and passing the geometry to the relational or topological operation - see GeometryEngine for more information.
If you are working with z-values (Geometry::hasZ, FeatureTable::hasZ), you may wish to also consider setting verticalTolerance and/or verticalResolution values.
See also Unit and GeometryEngine.
Member Function Documentation
[static] Esri::ArcGISRuntime::SpatialReferenceBuilder *SpatialReferenceBuilder::create(const Esri::ArcGISRuntime::SpatialReference &spatialReference , QObject *parent = nullptr)
Creates a spatial reference builder with the specified spatial reference (including any customizations) as the starting point for further modifications.
- spatialReference - The spatial reference to use as a starting point for further modifications.
- parent - The optional parent QObject.
This method creates a spatial reference builder with property values that match the given SpatialReference, including any custom precision values (resolution, tolerance, verticalResolution, and verticalTolerance).
[static] Esri::ArcGISRuntime::SpatialReferenceBuilder *SpatialReferenceBuilder::create(const QString &wkText , QObject *parent = nullptr)
Creates a spatial reference builder based on well-known text.
- wkText - A supported well-known text definition of a coordinate system.
- parent - The optional parent QObject.
This method creates a spatial reference build based on the given well-known text definition of a coordinate system, and so can be used to define a builder with a customized coordinate system. The builder will have default precision values (resolution, tolerance, verticalResolution, and verticalTolerance).
[static] Esri::ArcGISRuntime::SpatialReferenceBuilder *SpatialReferenceBuilder::create(int wkid, QObject *parent = nullptr)
Creates a spatial reference builder based on the given horizontal coordinate system.
- wkid - The well-known ID of the horizontal coordinate system. Must be a positive value (greater than zero).
- parent - The optional parent QObject.
This method creates a spatial reference builder based on the given horizontal coordinate system WKID, and will have not have a vertical coordinate system associated with it. It will have default precision values (resolution, tolerance, verticalResolution, and verticalTolerance).
[static] Esri::ArcGISRuntime::SpatialReferenceBuilder *SpatialReferenceBuilder::create(int wkid, int verticalWkid , QObject *parent = nullptr)
Creates a spatial reference builder based on the given horizontal and vertical coordinate systems.
- wkid - The well-known ID of the horizontal coordinate system. Must be a positive value (greater than zero).
- verticalWkid - The well-known ID of the vertical coordinate system. Must be a non negative value.
- parent - The optional parent QObject.
This method creates a spatial reference builder based on the given horizontal coordinate system WKID and vertical coordinate system verticalWKID. It will have default precision values (resolution, tolerance, verticalResolution, and verticalTolerance). If verticalWKID is 0, this is equivalent to calling SpatialReferenceBuilder, and the builder will have not have a vertical coordinate system associated with it.
bool SpatialReferenceBuilder::isValid () const
Returns true if a SpatialReference can be produced from the current builder properties, false otherwise.
A spatial reference builder is only considered valid if:
- resolution and verticalResolution are greater than zero.
- tolerance and verticalTolerance are greater than zero.
- tolerance is at least twice the resolution.
- verticalTolerance is at least twice the verticalResolution.
See also toSpatialReference.
double SpatialReferenceBuilder::resolution() const
Returns the minimum distance that separates unique x,y coordinate values when stored in an ArcGISFeatureTable.
The resolution represents the detail in which a feature class records the location and shape of features, defining the number of decimal places or significant digits stored. It is the minimum distance that separates x,y coordinate values in the Geometry of an ArcGISFeature. Any coordinates that differ by less than the resolution will still be stored as the same coordinate value. The units of resolution are the units of the horizontal coordinate system (unit) defined when this builder was created.
resolution must be greater than zero for isValid to be true and toSpatialReference to produce a SpatialReference. tolerance must also be at least twice resolution.
A separate resolution, verticalResolution, is defined for the distance between z-values.
See also setResolution(), unit, and tolerance.
void SpatialReferenceBuilder::setResolution (double resolution)
Sets the resolution to resolution.
See also resolution.
void SpatialReferenceBuilder::setTolerance (double tolerance)
Sets the tolerance to tolerance.
See also tolerance.
void SpatialReferenceBuilder::setVerticalResolution (double verticalResolution )
Sets the verticalResolution to verticalResolution.
See also verticalResolution.
void SpatialReferenceBuilder::setVerticalTolerance (double verticalTolerance )
Sets the verticalTolerance to verticalTolerance.
See also verticalTolerance.
Esri::ArcGISRuntime::SpatialReference SpatialReferenceBuilder::toSpatialReference () const
Returns a new SpatialReference based on the current values of this builder.
Use isValid after changing precision properties on this builder to check all the values are valid and consistent with each other - for example, tolerance must be at least twice resolution for this method to return a SpatialReference.
See also isValid.
double SpatialReferenceBuilder::tolerance() const
Returns the minimum distance that determines if two x,y coordinates are considered to be at the same location for relational and topological GeometryEngine operations.
This value is used in relational and topological GeometryEngine operations when determining whether two points are close enough, in the horizontal plane, to be considered as the same coordinate value when calculating the result. The units of tolerance are the units of the horizontal coordinate system (unit) defined when this builder was created.
tolerance must be greater than zero and at least twice resolution for isValid to be true and toSpatialReference to produce a SpatialReference.
A separate tolerance, verticalTolerance, is defined for the difference between z-values.
See also setTolerance(), unit, and resolution.
Esri::ArcGISRuntime::Unit SpatialReferenceBuilder::unit() const
Returns the unit of measure for the horizontal coordinate system of this spatial reference.
Also the unit of measure for tolerance and resolution.
See also verticalUnit.
double SpatialReferenceBuilder::verticalResolution () const
Returns the minimum distance that separates unique z-values when stored in an ArcGISFeatureTable.
The vertical resolution represents the detail in which a feature class records the location and shape of features, defining the number of decimal places or significant digits stored. It is the minimum distance that separates z-values in the Geometry of an ArcGISFeature. Any z-values that differ by less than the vertical resolution will still be stored as the same z-value. The units of verticalResolution are the units of the vertical coordinate system (SpatialReference::verticalUnit) defined when this builder was created, if one was set.
verticalResolution must be greater than zero for isValid to be true and toSpatialReference to produce a SpatialReference. verticalTolerance must also be at least twice verticalResolution.
A separate resolution, resolution, is defined for the distance between x,y coordinates.
See also setVerticalResolution(), verticalUnit, and verticalTolerance.
double SpatialReferenceBuilder::verticalTolerance () const
Returns the minimum distance that determines if two z-values are considered to be at the same location for GeometryEngine operations that compare z-values.
This value is used in relational and topological GeometryEngine operations when determining whether two z-values are close enough to be considered as the same value when calculating the result. This is currently only used by GeometryEngine::simplify(const Esri::ArcGISRuntime::Geometry&) and when the input is a z-aware Polyline; it is not used in other methods. The units of verticalTolerance are the units of the vertical coordinate system (verticalUnit) defined when this builder was created, if one was set.
verticalTolerance must be greater than zero and at least twice verticalResolution for isValid to be true and toSpatialReference to produce a SpatialReference.
A separate tolerance, tolerance, is defined for the distance between x,y coordinates.
See also setVerticalTolerance(), verticalUnit, and verticalResolution.
Esri::ArcGISRuntime::LinearUnit SpatialReferenceBuilder::verticalUnit () const
Returns the unit of measure for the vertical coordinate system of this spatial reference, or empty if no vertical coordinate system is set for this builder.
Also the unit of measure for verticalTolerance and verticalResolution.
See also unit.
int SpatialReferenceBuilder::verticalWkid () const
Returns the well-known ID for the vertical coordinate system (VCS), or 0 if this builder has no VCS or has a custom VCS.
See also wkid and SpatialReference::verticalWkid.
QString SpatialReferenceBuilder::wkText () const
Returns the well-known text definition of the horizontal and vertical coordinate systems of this builder.
If this coordinate system can only be represented in WKT2 format this property returns an empty string.
See also SpatialReference::wkText.
int SpatialReferenceBuilder::wkid() const
Returns the well-known ID for the horizontal coordinate system, or 0 if this builder has a custom horizontal coordinate system.
See also verticalWkid.