Provides access to members that specify the spatial and M tolerances of a spatial reference.
When To Use
Use the ISpatialReferenceTolerance interface to define default and user-specified XYTolerance and ZTolerance parameters utilized by the topology engine when performing geometric and relational operations on geometries associated with this spatial reference. This interface also provides access to define the MTolerance used by the geometric and relational operations associated with this spatial reference.
Members
| Name | Description | |
|---|---|---|
 |
IsMToleranceEqual | Returns true if the measure tolerances of the two spatial references are the same. |
|
IsXYToleranceEqual | Returns true if the XY tolerances of the two spatial references are the same. |
|
IsZToleranceEqual | Returns true if the Z tolerances of the two spatial references are the same. |
 |
MTolerance | The tolerance used to determine equality of M values. |
 |
MToleranceValid | Returns true if the M tolerance is well defined (not NaN) and >= the minimum M tolerance. |
|
SetDefaultMTolerance | Sets the default tolerance used to determine equality of M values (2.0 * m resolution). |
|
SetDefaultXYTolerance | Sets the default cluster tolerance used to control point coalescing in the X and Y dimensions (the equivalent of 1 mm in the current spatial reference units). |
|
SetDefaultZTolerance | Sets the default value for the Z cluster tolerance used to control point coalescing strictly along the Z axis (the equivalent of 1 mm in the current vertical coordinate system units). |
|
SetMinimumMTolerance | Sets the minimum tolerance (i.e., pre 9.2) used to determine equality of M values (2.0 * m resolution). |
|
SetMinimumXYTolerance | Sets the xy cluster tolerance to be 2.0 * resolution. Use this value for compatibility with pre-9.2 topological and relational operators. |
|
SetMinimumZTolerance | Sets the minimum value for the Z cluster tolerance (i.e., pre 9.2) used to control point coalescing strictly along the Z axis (the equivalent of 1 mm in the current vertical coordinate system units). |
|
XYTolerance | The xy tolerance used to control point coalescing in the X and Y dimensions. |
|
XYToleranceValid | Returns esriSRToleranceOK if the XY tolerance is well defined (not NaN) and >= the minimum XY tolerance. |
|
ZTolerance | The tolerance used to control point coalescing strictly along the Z axis. |
|
ZToleranceValid | Returns true if the Z tolerance is well defined (not NaN) and >= the minimum Z tolerance. |
ISpatialReferenceTolerance.IsMToleranceEqual Method
Returns true if the measure tolerances of the two spatial references are the same.
Public Function IsMToleranceEqual ( _
ByVal otherSR As ISpatialReference _
) As Boolean
public bool IsMToleranceEqual (
ISpatialReference otherSR
);
Remarks
IsMToleranceEqual will return True if both Spatial Reference MTolerances are undefined (NaN) or if they are both defined and numerically equal.
Note that the IClone::IsEqual method on spatial referencesdoes not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) of the spatial reference.
ISpatialReferenceTolerance.IsXYToleranceEqual Method
Returns true if the XY tolerances of the two spatial references are the same.
Public Function IsXYToleranceEqual ( _
ByVal otherSR As ISpatialReference _
) As Boolean
public bool IsXYToleranceEqual (
ISpatialReference otherSR
);
Remarks
IsXYToleranceEqual will return True if both Spatial Reference XYTolerances are undefined (NaN) or if they are both defined and numerically equal.
Note that the IClone::IsEqual method on spatial referencesdoes not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) part of the spatial reference.
ISpatialReferenceTolerance.IsZToleranceEqual Method
Returns true if the Z tolerances of the two spatial references are the same.
Public Function IsZToleranceEqual ( _
ByVal otherSR As ISpatialReference _
) As Boolean
public bool IsZToleranceEqual (
ISpatialReference otherSR
);
Remarks
IsZToleranceEqual will return True if both Spatial Reference Z Tolerances are undefined (NaN)or if they are both defined and numerically equal.
Note that the IClone::IsEqual method on spatial referencesdoes not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) part of the spatial reference.
ISpatialReferenceTolerance.MTolerance Property
The tolerance used to determine equality of M values.
Public Property MTolerance As Double
public double MTolerance {get; set;}
Remarks
The MTolerance method establishes or retrieves the value for the MTolerance of the spatial reference. Setting the MTolerance using this property provides finer control than SetDefaultMToleranceor SetMinimumMTolerance.
The minimum allowable MTolerance is 2.0 * MResolution. To ensure that the MTolerance specified is valid, use MToleranceValid after setting the MTolerance using this property.
The MTolerance is undefined (NaN) by default.
ISpatialReferenceTolerance.MToleranceValid Property
Returns true if the M tolerance is well defined (not NaN) and >= the minimum M tolerance.
Public ReadOnly Property MToleranceValid As esriSRToleranceEnum
public esriSRToleranceEnum MToleranceValid {get;}
Remarks
The MToleranceValid property determines if the current M tolerance associated with the spatial reference is valid. A M Tolerance is considered valid when it is well-defined (not NaN) and the M tolerance is greater than or equal to the minimum M tolerance. The minimum allowable MTolerance is 2.0 * MResolution.
To ensure that the MTolerance specified is valid, call MToleranceValid after calling ISpatialReferenceTolerance::MTolerance.
ISpatialReferenceTolerance.SetDefaultMTolerance Method
Sets the default tolerance used to determine equality of M values (2.0 * m resolution).
Public Sub SetDefaultMTolerance ( _
)
public void SetDefaultMTolerance (
);
Remarks
The SetDefaultMTolerance method establishes the default value for the M tolerance. The default value is 0.001 units.
The minimum allowable MTolerance is 2.0 * MResolution.
If the value specified by SetDefaultMTolerance is not greater than or equal to 2.0 * MResolution, the MTolerance will be set at 2.0 * MResolution.
The following code snippet illustrates the required steps to set the default M tolerance for a new SpatialReference.
ISpatialReferenceFactory3 spatialReferenceFactory =
new SpatialReferenceEnvironmentClass() as ISpatialReferenceFactory3;
ISpatialReference spatialRef = spatialReferenceFactory.CreateSpatialReference(23033);
if (spatialRef == null)
return;
ISpatialReferenceResolution spatialRefResolution = spatialRef as ISpatialReferenceResolution;
// Set the domain extent to a default range based on the target resolution
spatialRefResolution.SetDefaultMResolution();
ISpatialReferenceTolerance spatialRefTolerance = spatialRefResolution as ISpatialReferenceTolerance;
spatialRefTolerance.SetDefaultMTolerance();
ISpatialReferenceTolerance.SetDefaultXYTolerance Method
Sets the default cluster tolerance used to control point coalescing in the X and Y dimensions (the equivalent of 1 mm in the current spatial reference units).
Public Sub SetDefaultXYTolerance ( _
)
public void SetDefaultXYTolerance (
);
Remarks
SetDefaultXYTolerance establishes the default value for the XY tolerance, taking into account the current units of the spatial reference. Any established tolerance will not be changed automatically if the units of the spatial reference are changed. For a ProjectedCoordinateSystem or an UnknownCoordinateSystem, the default tolerance is 1 mm (expressed in the units of the spatial reference) or 2.0 * XYResolution, whichever is larger. For a GeographicCoordinateSystem, it is the angle subtending 1 mm at the equator, or 2.0 * XYResolution, whichever is larger.
The minimum allowable XYTolerance is 2.0 * XYResolution.
If the value specified by SetDefaultXYTolerance is not greater than or equal to 2.0 * XYResolution, the XYTolerance will be set at 2.0 * XYResolution.
A file-based data source, such as shapefiles, CAD and SDC, that has an UnknownCoordinateSystem and that has an X coordinate data extent that falls between +/-400, will use a tolerance in degrees corresponding to 1mm along the equator (8.98315284119522E-09degrees).
public void SetDefaultXYToleranceExample()
{
//The following code example creates a new projected coordinate system,
//defines the domainextent and default resolution, and sets the default XYTolerance.
// use activator class with SpatialReferenceEnvironment singleton
Type factoryType = Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment");
System.Object obj = Activator.CreateInstance(factoryType);
ISpatialReferenceFactory3 spatialReferenceFactory = obj as ISpatialReferenceFactory3;
ISpatialReference spatialRef = spatialReferenceFactory.CreateSpatialReference(32610);
ISpatialReference projectedCoordinateSystem = spatialReferenceFactory.CreateProjectedCoordinateSystem(32610);
IControlPrecision2 controlPrecision = projectedCoordinateSystem as IControlPrecision2;
controlPrecision.IsHighPrecision = true;
ISpatialReferenceResolution spatialReferenceResolution = projectedCoordinateSystem as ISpatialReferenceResolution;
spatialReferenceResolution.ConstructFromHorizon();
ISpatialReferenceTolerance spatialReferenceTolerance = projectedCoordinateSystem as ISpatialReferenceTolerance;
spatialReferenceTolerance.SetDefaultXYTolerance();
}
'The following code example creates a new projected coordinate system,
'defines the domain extent and default resolution, and sets the default XYTolerance.
Dim pSpatialReferenceFactory As ISpatialReferenceFactory3
pSpatialReferenceFactory = New SpatialReferenceEnvironment
Dim pSpatialReference As ISpatialReference
pSpatialReference = pSpatialReferenceFactory.CreateProjectedCoordinateSystem(32610)
Dim pControlPrecision As IControlPrecision2
pControlPrecision = pSpatialReference
pControlPrecision.IsHighPrecision = True
Dim pSRRes As ISpatialReferenceResolution
pSRRes = pSpatialReference
pSRRes.ConstructFromHorizon()
Dim pSRTolerance As ISpatialReferenceTolerance
pSRTolerance = pSpatialReference
pSRTolerance.SetDefaultXYTolerance()
ISpatialReferenceTolerance.SetDefaultZTolerance Method
Sets the default value for the Z cluster tolerance used to control point coalescing strictly along the Z axis (the equivalent of 1 mm in the current vertical coordinate system units).
Public Sub SetDefaultZTolerance ( _
)
public void SetDefaultZTolerance (
);
Remarks
The SetDefaultZTolerance method establishes the default value for the ZTolerance. Any established tolerance will not automatically be changed by changing the units of the spatial reference. The default value is 1mm (scaled to whatever units are associated with the spatial reference's vertical coordinate system).
The minimum allowable ZTolerance is 2.0 * ZResolution.
The following code snippet illustrates the required steps to set the default Z tolerance for a new SpatialReference.
ISpatialReferenceFactory3 spatialReferenceFactory =
new SpatialReferenceEnvironmentClass() as ISpatialReferenceFactory3;
ISpatialReference spatialRef = spatialReferenceFactory.CreateSpatialReference(23033);
if (spatialRef == null)
return;
ISpatialReferenceResolution spatialRefResolution = spatialRef as ISpatialReferenceResolution;
// Set the domain extent to a default range based on the target resolution
spatialRefResolution.SetDefaultZResolution();
ISpatialReferenceTolerance spatialRefTolerance = spatialRefResolution as ISpatialReferenceTolerance;
spatialRefTolerance.SetDefaultZTolerance();
ISpatialReferenceTolerance.SetMinimumMTolerance Method
Sets the minimum tolerance (i.e., pre 9.2) used to determine equality of M values (2.0 * m resolution).
Public Sub SetMinimumMTolerance ( _
)
public void SetMinimumMTolerance (
);
Errors Returned
2147220990 - FDO_E_INDEX_OUT_OF_RANGE
The spatial reference object's M-resolution is undefined (NaN). Use one of the methods on ISpatialReferenceResolution to define a resolution value before calling SetMinimumMTolerance.
Remarks
The SetMinimumMTolerance method sets the tolerance to the value of the spatial reference's grid resolution (or 2.0 * M resolution). Setting the MTolerance using this method provides a mechanism to maintain backward compatibility with ArcGIS 9.1 geometric and relational operators. At 9.1 and before, this is the only tolerance value used by measure or linear referencing aware operations in the geometry system.
The following code snippet illustrates the required steps to set the minimum M tolerance for a new SpatialReference.
ISpatialReferenceFactory3 spatialReferenceFactory =
new SpatialReferenceEnvironmentClass() as ISpatialReferenceFactory3;
ISpatialReference spatialRef = spatialReferenceFactory.CreateSpatialReference(23033);
if (spatialRef == null)
return;
ISpatialReferenceResolution spatialRefResolution = spatialRef as ISpatialReferenceResolution;
// Set the domain extent to a default range based on the target resolution
spatialRefResolution.SetDefaultMResolution();
ISpatialReferenceTolerance spatialRefTolerance = spatialRefResolution as ISpatialReferenceTolerance;
spatialRefTolerance.SetMinimumMTolerance();
ISpatialReferenceTolerance.SetMinimumXYTolerance Method
Sets the xy cluster tolerance to be 2.0 * resolution. Use this value for compatibility with pre-9.2 topological and relational operators.
Public Sub SetMinimumXYTolerance ( _
)
public void SetMinimumXYTolerance (
);
Errors Returned
2147220990 - FDO_E_INDEX_OUT_OF_RANGE
The spatial reference object's resolution is undefined (NaN). Use one of the methods on ISpatialReferenceResolution to define a resolution value before calling SetMinimumXYTolerance.
Remarks
The SetMinimumXYTolerance method sets the tolerance to the value of the spatial reference's grid resolution (or 2.0 * XYResolution). Setting the XYTolerance using this method provides a mechanism to maintain backward compatibility with ArcGIS 9.1 geometric and relational operators. At version 9.1 and before, this is the only tolerance value used by geometric and relational operators.
private void SetMinimumXYTolerance()
{
// use activator class with SpatialReferenceEnvironment singleton
Type factoryType = Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment");
System.Object obj = Activator.CreateInstance(factoryType);
ISpatialReferenceFactory3 spatialReferenceFactory = obj as ISpatialReferenceFactory3;
ISpatialReference spatialReference = spatialReferenceFactory.CreateSpatialReference(32610);
if (spatialReference == null)
return;
ISpatialReferenceResolution spatialRefResolution = spatialReference as ISpatialReferenceResolution;
try
{
// 9.3 releases and earlier did not set the domain, resolution or
// Set the domain extent based on the SpatialReference horizon.
spatialRefResolution.ConstructFromHorizon();
spatialRefResolution.SetDefaultXYResolution();
}
catch (Exception ex)
{
throw new NullReferenceException(ex.Message);
}
ISpatialReferenceTolerance spatialRefTolerance =
spatialRefResolution as ISpatialReferenceTolerance;
spatialRefTolerance.SetMinimumXYTolerance();
}
ISpatialReferenceTolerance.SetMinimumZTolerance Method
Sets the minimum value for the Z cluster tolerance (i.e., pre 9.2) used to control point coalescing strictly along the Z axis (the equivalent of 1 mm in the current vertical coordinate system units).
Public Sub SetMinimumZTolerance ( _
)
public void SetMinimumZTolerance (
);
Errors Returned
2147220990 - FDO_E_INDEX_OUT_OF_RANGE
The spatial reference object's Z-resolution is undefined (NaN). Use one of the methods on ISpatialReferenceResolution to define a resolution value before calling SetMinimumZTolerance.
Remarks
The SetMinimumZTolerance method sets the ZTolerance to 2.0 * z resolution. Setting the ZTolerance using this method provides a mechanism to maintain backward compatibility with ArcGIS 9.1 geometric and relational operators. At 9.1 and before, this is the only tolerance value used by the geometric and relational operators.
The ZResolution should be defined before calling SetMinimumZTolerance.
The following code snippet illustrates the required steps to set the default Z tolerance for a new SpatialReference.
ISpatialReferenceFactory3 spatialReferenceFactory =
new SpatialReferenceEnvironmentClass() as ISpatialReferenceFactory3;
ISpatialReference spatialRef = spatialReferenceFactory.CreateSpatialReference(23033);
if (spatialRef == null)
return;
ISpatialReferenceResolution spatialRefResolution = spatialRef as ISpatialReferenceResolution;
// Set the domain extent to a default range based on the target resolution
spatialRefResolution.SetDefaultZResolution();
ISpatialReferenceTolerance spatialRefTolerance = spatialRefResolution as ISpatialReferenceTolerance;
spatialRefTolerance.SetMinimumZTolerance();
ISpatialReferenceTolerance.XYTolerance Property
The xy tolerance used to control point coalescing in the X and Y dimensions.
Public Property XYTolerance As Double
public double XYTolerance {get; set;}
Remarks
The XYTolerance property is the planar cluster tolerance associated with a spatial referencethat will be used by geometric and relational operators. It has the same meaning as the cluster tolerance parameter presented in other parts of ArcGIS, including topology and Geoprocessing. The default value is 1mm (scaled to whatever units are associated with the spatial reference) for ProjectedCoordinateSystems and UnknownCoordinateSystems, and the angle corresponding to 1mm along the equator for geographic coordinate systems.
Setting the XYTolerance using this property provides finer control than SetDefaultXYToleranceor SetMinimumXYTolerance.
The minimum allowable XYTolerance is 2.0 * XYResolution. XYTolerance is undefined (NaN) by after creating a spatial reference. Operations on the spatial reference that define its coordinate grid will set the tolerance to its minimum value if its currently NaN. The tolerance is not modified if the grid resolution changes. To ensure that the XYTolerance specified is valid, use XYToleranceValid.
ISpatialReferenceTolerance.XYToleranceValid Property
Returns esriSRToleranceOK if the XY tolerance is well defined (not NaN) and >= the minimum XY tolerance.
Public ReadOnly Property XYToleranceValid As esriSRToleranceEnum
public esriSRToleranceEnum XYToleranceValid {get;}
Errors Returned
The XYToleranceValid property determines if the current XY tolerance associated with the spatial reference is valid. A XY Tolerance is considered valid when it is well defined (not NaN) and the XY tolerance is greater than or equal to the minimum XY tolerance. The minimum allowable XYTolerance is 2.0/xyUnits.
To ensure that the XTolerance specified is valid, call XYToleranceValid after calling ISpatialReferenceTolerance::XYTolerance.
Remarks
The xy grid resolution of a spatial referencecan be altered independantly of the XYTolerance. Use this method to ensure that the current XYTolerance is defined and not less than the minimum legal value (2.0 * XYResolution).
ISpatialReferenceTolerance.ZTolerance Property
The tolerance used to control point coalescing strictly along the Z axis.
Public Property ZTolerance As Double
public double ZTolerance {get; set;}
Remarks
The ZTolerance property controls clustering of the z-values of coordinates. It currently is used only in the context of the topology validation operation. It is expressed in the spatial reference's vertical coordinate system units. Setting the ZTolerance using this property provides finer control than SetDefaultZToleranceor SetMinimumZTolerance.
The minimum allowable ZTolerance is 2 * ZResolution (defined by ISpatialReferenceResolution::ZResolution). To ensure that the ZTolerance specified is valid, use ZToleranceValid after setting the ZTolerance using this property.
The ZTolerance is undefined (NaN) by default. Methods that define the z coordinate grid will set the z tolerance to the minimum value if it isn't currently defined
ISpatialReferenceTolerance.ZToleranceValid Property
Returns true if the Z tolerance is well defined (not NaN) and >= the minimum Z tolerance.
Public ReadOnly Property ZToleranceValid As esriSRToleranceEnum
public esriSRToleranceEnum ZToleranceValid {get;}
Remarks
ZToleranceValid determines if the current ZTolerance associated with the spatial reference is valid. A ZTolerance is considered valid when it is well defined (not NaN) and the Z tolerance is greater than or equal to the minimum ZTolerance. The minimum allowable ZTolerance is 2.0 * ZResolution.
To ensure that the ZTolerance specified is valid, call ZToleranceValid after calling ISpatialReferenceTolerance::ZTolerance.
Classes that implement ISpatialReferenceTolerance
| Classes | Description |
|---|---|
| GeographicCoordinateSystem | Creates a geographic coordinate system. |
| ProjectedCoordinateSystem | Creates a projected coordinate system. |
| UnknownCoordinateSystem | Creates an unknown coordinate system. |
Remarks
The tolerance values for a spatial reference remain_**_NaN until they are either set explicitly using one of the methods or properties available on this interface or as a result of calling a method which defines the resolution of the spatial reference, including ISpatialReference::SetDomain, ISpatialReference::SetZDomain, ISpatialReference::SetMDomain, ISpatialReference::SetFalseOriginAndUnits, ISpatialReference::SetZFalseOriginAndUnits and ISpatialReference::SetMFalseOriginAndUnits**. These methods will set the corresponding tolerance to its minimum value if it is currently undefined (NaN).
It is generally good practice to check the validity of the tolerance after setting it using any of the available methods.