com.esri.arcgis.geometry
Interface ISpatialReferenceTolerance

All Superinterfaces:

Serializable

All Known Implementing Classes:

GeographicCoordinateSystem, ProjectedCoordinateSystem, UnknownCoordinateSystem

public interface ISpatialReferenceTolerance
extends Serializable

Provides access to members that specify the spatial and M tolerances of a spatial reference.

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.

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Method Summary

double	getMTolerance() The tolerance used to determine equality of M values.
int	getMToleranceValid() Returns true if the M tolerance is well defined (not NaN) and >= the minimum M tolerance.
double	getXYTolerance() The xy tolerance used to control point coalescing in the X and Y dimensions.
int	getXYToleranceValid() Returns esriSRToleranceOK if the XY tolerance is well defined (not NaN) and >= the minimum XY tolerance.
double	getZTolerance() The tolerance used to control point coalescing strictly along the Z axis.
int	getZToleranceValid() Returns true if the Z tolerance is well defined (not NaN) and >= the minimum Z tolerance.
boolean	isMToleranceEqual(ISpatialReference otherSR) Returns true if the measure tolerances of the two spatial references are the same.
boolean	isXYToleranceEqual(ISpatialReference otherSR) Returns true if the XY tolerances of the two spatial references are the same.
boolean	isZToleranceEqual(ISpatialReference otherSR) Returns true if the Z tolerances of the two spatial references are the same.
void	setDefaultMTolerance() Sets the default tolerance used to determine equality of M values (2.0 * m resolution).
void	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).
void	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).
void	setMinimumMTolerance() Sets the minimum tolerance (i.e., pre 9.2) used to determine equality of M values (2.0 * m resolution).
void	setMinimumXYTolerance() Sets the xy cluster tolerance to be 2.0 * resolution.
void	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).
void	setMTolerance(double mTolerance) The tolerance used to determine equality of M values.
void	setXYTolerance(double xYTolerance) The xy tolerance used to control point coalescing in the X and Y dimensions.
void	setZTolerance(double zTolerance) The tolerance used to control point coalescing strictly along the Z axis.

Method Detail

setDefaultXYTolerance

void setDefaultXYTolerance()
                           throws IOException,
                                  AutomationException

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).

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-09 degrees).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMinimumXYTolerance

void setMinimumXYTolerance()
                           throws IOException,
                                  AutomationException

Sets the xy cluster tolerance to be 2.0 * resolution. Use this value for compatibility with pre-9.2 topological and relational operators.

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getXYTolerance

double getXYTolerance()
                      throws IOException,
                             AutomationException

The xy tolerance used to control point coalescing in the X and Y dimensions.

Remarks

The XYTolerance property is the planar cluster tolerance associated with a spatial reference that 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 SetDefaultXYTolerance or 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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The xYTolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setXYTolerance

void setXYTolerance(double xYTolerance)
                    throws IOException,
                           AutomationException

The xy tolerance used to control point coalescing in the X and Y dimensions.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

xYTolerance - The xYTolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDefaultZTolerance

void setDefaultZTolerance()
                          throws IOException,
                                 AutomationException

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).

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMinimumZTolerance

void setMinimumZTolerance()
                          throws IOException,
                                 AutomationException

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).

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZTolerance

double getZTolerance()
                     throws IOException,
                            AutomationException

The tolerance used to control point coalescing strictly along the Z axis.

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 SetDefaultZTolerance or 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

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The zTolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setZTolerance

void setZTolerance(double zTolerance)
                   throws IOException,
                          AutomationException

The tolerance used to control point coalescing strictly along the Z axis.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

zTolerance - The zTolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDefaultMTolerance

void setDefaultMTolerance()
                          throws IOException,
                                 AutomationException

Sets the default tolerance used to determine equality of M values (2.0 * m resolution).

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMinimumMTolerance

void setMinimumMTolerance()
                          throws IOException,
                                 AutomationException

Sets the minimum tolerance (i.e., pre 9.2) used to determine equality of M values (2.0 * m resolution).

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMTolerance

double getMTolerance()
                     throws IOException,
                            AutomationException

The tolerance used to determine equality of M values.

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 SetDefaultMTolerance or 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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The mTolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMTolerance

void setMTolerance(double mTolerance)
                   throws IOException,
                          AutomationException

The tolerance used to determine equality of M values.

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 SetDefaultMTolerance or 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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

mTolerance - The mTolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getXYToleranceValid

int getXYToleranceValid()
                        throws IOException,
                               AutomationException

Returns esriSRToleranceOK if the XY tolerance is well defined (not NaN) and >= the minimum XY tolerance.

Remarks

The xy grid resolution of a spatial reference can 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).

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A com.esri.arcgis.geometry.esriSRToleranceEnum constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getZToleranceValid

int getZToleranceValid()
                       throws IOException,
                              AutomationException

Returns true if the Z tolerance is well defined (not NaN) and >= the minimum Z tolerance.

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A com.esri.arcgis.geometry.esriSRToleranceEnum constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getMToleranceValid

int getMToleranceValid()
                       throws IOException,
                              AutomationException

Returns true if the M tolerance is well defined (not NaN) and >= the minimum M tolerance.

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.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

A com.esri.arcgis.geometry.esriSRToleranceEnum constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isXYToleranceEqual

boolean isXYToleranceEqual(ISpatialReference otherSR)
                           throws IOException,
                                  AutomationException

Returns true if the XY tolerances of the two spatial references are the same.

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 references does not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) part of the spatial reference.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

otherSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Returns:

The isXYToleranceEqual

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isMToleranceEqual

boolean isMToleranceEqual(ISpatialReference otherSR)
                          throws IOException,
                                 AutomationException

Returns true if the measure tolerances of the two spatial references are the same.

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 references does not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) of the spatial reference.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

otherSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Returns:

The isMToleranceEqual

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isZToleranceEqual

boolean isZToleranceEqual(ISpatialReference otherSR)
                          throws IOException,
                                 AutomationException

Returns true if the Z tolerances of the two spatial references are the same.

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 references does not consider coordinate grid or tolerance properties. It only looks at the coordinate system part (i.e. projection information) part of the spatial reference.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

otherSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Returns:

The isZToleranceEqual

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.