Spatial
Allows you to create and modify spatial references with custom tolerance and resolution values. 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.
Create the SpatialReferenceBuilder by WKID, WKT string, or from an existing SpatialReference.
Change SpatialReferenceBuilder.tolerance and/or SpatialReferenceBuilder.resolution as required.
Use SpatialReferenceBuilder.isValid after changing properties to check the new values are valid and consistent with each other - for example, SpatialReferenceBuilder.tolerance must be at least twice SpatialReferenceBuilder.resolution.
Call SpatialReferenceBuilder.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 SpatialReferenceBuilder.verticalTolerance and/or SpatialReferenceBuilder.verticalResolution values.
Since
200.8.0
See also
Constructors
Creates a spatial reference builder with the specified spatial reference (including any customizations) as the starting point for further modifications. This method creates a spatial reference builder with property values that match the given SpatialReference, including any custom precision values (SpatialReferenceBuilder.resolution, SpatialReferenceBuilder.tolerance, SpatialReferenceBuilder.verticalResolution, and SpatialReferenceBuilder.verticalTolerance).
Creates a spatial reference builder based on well-known text. 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 (SpatialReferenceBuilder.resolution, SpatialReferenceBuilder.tolerance, SpatialReferenceBuilder.verticalResolution, and SpatialReferenceBuilder.verticalTolerance).
Creates a spatial reference builder based on the given horizontal and vertical coordinate systems. 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 (SpatialReferenceBuilder.resolution, SpatialReferenceBuilder.tolerance, SpatialReferenceBuilder.verticalResolution, and SpatialReferenceBuilder.verticalTolerance). If verticalWKID is null, the builder will not have a vertical coordinate system associated with it.
Properties
True if a SpatialReference can be produced from the current builder properties, false otherwise. A spatial reference builder is only considered valid if:
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 SpatialReferenceBuilder.resolution are the units of the horizontal coordinate system (SpatialReferenceBuilder.unit) defined when this builder was created.
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 SpatialReferenceBuilder.tolerance are the units of the horizontal coordinate system (SpatialReferenceBuilder.unit) defined when this builder was created.
The unit of measure for the horizontal coordinate system of this spatial reference. Also the unit of measure for SpatialReferenceBuilder.tolerance and SpatialReferenceBuilder.resolution.
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 SpatialReferenceBuilder.verticalResolution are the units of the vertical coordinate system (SpatialReference.verticalUnit) defined when this builder was created, if one was set.
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.simplifyOrNull and when the input is a z-aware Polyline; it is not used in other methods. The units of SpatialReferenceBuilder.verticalTolerance are the units of the vertical coordinate system (SpatialReferenceBuilder.verticalUnit) defined when this builder was created, if one was set.
The unit of measure for the vertical coordinate system of this spatial reference, or null if no vertical coordinate system is set for this builder. Also the unit of measure for SpatialReferenceBuilder.verticalTolerance and SpatialReferenceBuilder.verticalResolution.
The well-known ID for the vertical coordinate system (VCS), or null if this builder has no VCS or has a custom VCS.
Functions
Sets the minimum distance that separates unique x,y coordinate values when stored in an ArcGISFeatureTable.
Sets the minimum distance that determines if two x,y coordinates are considered to be at the same location for relational and topological GeometryEngine operations.
Returns a new SpatialReference based on the current values of this builder. Use SpatialReferenceBuilder.isValid after changing precision properties on this builder to check all the values are valid and consistent with each other - for example, SpatialReferenceBuilder.tolerance must be at least twice SpatialReferenceBuilder.resolution for this method to return a SpatialReference.
Sets the minimum distance that separates unique z-values when stored in an ArcGISFeatureTable.
Sets the minimum distance that determines if two z-values are considered to be at the same location for GeometryEngine operations that compare z-values.