Interface ISpatialReferenceResolution

Namespace
ESRI.ArcGIS.Geometry
Assembly
ESRI.Server.Geometry.dll

Provides access to members that control the resolution of a spatial reference.

[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
[Guid("833AC5B9-20E3-4896-8D55-770F4E90A2E4")]
public interface ISpatialReferenceResolution

Remarks

The ISpatialReferenceResolution interface is used to define default and custom grid origins, extents and resolutions for the XY, Z and M coordinate grids associated with a spatial reference. The terms resolution and precision are synonymous within the context of the spatial reference system and the former refers to the inverse of the scale factor. Methods on this interface can define coordinate grid resolutions and extent based on a known spatial reference horizon, or alter extents and resolutions in a controlled way (for example, enlarge the extent about its current center by specifying a larger (coarser) target resolution).

[C#]

//The following code shows how to use ISpatialReferenceResolution interface and methods

ISpatialReferenceFactory spatialReferenceFactory = new SpatialReferenceEnvironmentClass();
ISpatialReference spatialReference = spatialReferenceFactory.CreateESRISpatialReferenceFromPRJFile("C:\\Program Files\\ArcGIS\\Coordinate Systems\\Geographic Coordinate Systems\\World\\WGS 1984.prj");

IControlPrecision2 controlPrecision = spatialReference as IControlPrecision2;
//Flip this to false if low precision
controlPrecision.IsHighPrecision = true;

ISpatialReferenceResolution spatialReferenceResolution = spatialReference as ISpatialReferenceResolution;
//this is the KEY, Construct Horizon THEN
spatialReferenceResolution.ConstructFromHorizon();
//Set Default  
spatialReferenceResolution.SetDefaultXYResolution();
double xMin;
double xMax;
double yMin;
double yMax;
spatialReference.GetDomain(out xMin, out xMax, out yMin, out yMax);
System.Windows.Forms.MessageBox.Show("Domain : " + xMin + ", " + xMax + ", " + yMin + ", " + yMax);










[Visual Basic .NET]

'The following code shows how to use ISpatialReferenceResolution interface and methods

        Dim pSR As ISpatialReference2
        Dim pSRF As ISpatialReferenceFactory3
        Dim pSRResolution As ISpatialReferenceResolution
        Dim pControlPrecision2 As IControlPrecision2
        Dim XMin As Double
        Dim XMax As Double
        Dim YMin As Double
        Dim YMax As Double






        pSRF = New SpatialReferenceEnvironment
        pSR = pSRF.CreateESRISpatialReferenceFromPRJFile("D:\ArcGIS\Coordinate Systems\Geographic Coordinate Systems\World\WGS 1984.prj")

        pSRResolution = pSR
        pControlPrecision2 = pSR

        pControlPrecision2.IsHighPrecision = True   'Flip this to false if low precision

        pSRResolution.ConstructFromHorizon()     'this is the KEY, Construct Horizon THEN
        pSRResolution.SetDefaultXYResolution()   'Set Default

        pSR.GetDomain(XMin, XMax, YMin, YMax)

        Debug.Print("Domain : ", XMin, XMax, YMin, YMax)

 

Properties

MResolution

The M, or measure, resolution of this spatial reference.

double MResolution { get; set; }

Property Value

double

Remarks

MResolution resizes the existing grid about its center to accommodate the new resolution specified.  This property provides finer control for specifying the resolution than does ISpatialReferenceResolution::SetDefaultMResolution. The default MResolution is defined as 0.001 units for high and low precision spatial references.

The default value for MResolution is NaN for a new spatial reference.  If the MResolution is not well-defined (MResolution is NaN), calls to ISpatialReference::SetMDomain or ISpatialReference::SetMFalseOriginAndUnits will set the MResolution to the minimum allowable value (2.0/mUnits).  If the MResolution was already defined, these methods will not alter the MResolution.

 

XYResolution[bool]

The XY resolution (distance in SR units between distinguishable grid points) of this spatial reference. Reported in meters for PCS/UCS and degrees for GCS when bStandardUnits is true or in current units of SR when it is false.

double XYResolution[bool bStandardUnits] { get; set; }

Parameters

bStandardUnits bool

Property Value

double

Remarks

XYResolution determines the distinguishable distance between two points in horizontal (XY) space. It is the inverse of the scale factor.

XYResolution can be expressed in standard units or units defined by the spatial reference.  For ProjectedCoordinateSystems and UnknownCoordinateSystems the standard unit is expressed in meters; for GeographicCoordinateSystems the standard unit is expressed in degrees.

The default XYResolution for ProjectedCoordinateSystems and UnknownCoordinateSystems is either 1 mm (low-precision spatial reference) or 0.1 mm (high-precision spatial reference). For GeographicCoordinateSystems the default XYResolution is 1/500 arc-second (low-precision spatial reference) or 1/10000 arc-second (high-precision spatial reference).  The precision of a spatial reference is determined using IControlPrecision2::IsHighPrecision. At ArcGIS 9.2 all spatial references are created using high precision by default.

Altering this property preserves the current false origin of the spatial reference if it has already been defined. Otherwise, the ConstructFromHorizon method is used to define a false origin.

Use ISpatialReferenceResolution::XYResolution(False) to return or set the XYResolution in the units defined as part of the spatial reference.

The default value for XYResolution is NaN (not-a-number) for a new spatial reference.  If the XYResolution has not been set previously, calls to ISpatialReference::SetDomain or ISpatialReference::SetFalseOriginAndUnits will set the XYResolution to the minimum allowable value (2.0/XYunits).

ZResolution[bool]

The Z resolution (height/depth distance between distinguishable grid points) of this spatial reference. Reported in meters when bStandardUnits is true or in current units of SR when it is false.

double ZResolution[bool bStandardUnits] { get; set; }

Parameters

bStandardUnits bool

Property Value

double

Remarks

ZResolution resizes the existing grid about its center to achieve a target resolution of 1mm for low precision spatial references or 1/10 mm for high precision.  This property provides finer control for specifying the resolution than does ISpatialReferenceResolution::SetDefaultZResolution. The default ZResolution is defined in standard units as 0.1 mm for high and low precision spatial references, or 1 mm for low precision spatial references.  For ProjectedCoordinateSystems and GeographicCoordinateSystems, that default value is scaled to whatever units are associated with the spatial reference's VerticalCoordinateSystem property.

Use ISpatialReferenceResolution::ZResolution(False) to specify or retrieve the Z resolution in units defined by the vertical coordinate system. 

The default value for ZResolution is NaN for a new spatial reference.  If the ZResolution is not well-defined (ZResolution is NaN), calls to ISpatialReference::SetZDomain or ISpatialReference::SetZFalseOriginAndUnits will set the ZResolution to the minimum allowable value (2.0/zUnits).  If the ZResolution was already defined, these methods will not alter the ZResolution.

Methods

ConstructFromHorizon()

Defines the XY resolution and domain extent of this spatial reference based on the extent of its horizon. Low precision SRs will have minimum resolution of 1/10mm in current units.

void ConstructFromHorizon()

Remarks

ConstructFromHorizon defines a domain extent and resolution sufficient to cover the horizon of a given coordinate system for high precision spatial references.  For low-precision spatial references the domain extent is centered on the horizon center. It does not define an extent for the Z- or M-domains; for these use methods available on ISpatialReference.

 

Projected Coordinate Systems

For a high precision ProjectedCoordinateSystem (PCS), ConstructFromHorizon defines the domain extent to be a square completely covering, and slightly larger than, the horizon extent of the PCS (which is an arbitrary rectangle). The scale factor (1/precision) is chosen to fit this domain.

For a low precision PCS, the center of the domain extent is aligned with the center of the horizon extent and expanded to achieve a target resolution of 1mm.

The example below lists high and low precision extents for WGS 1984 UTM Zone 11N.

Name Low Precision ProjectedCoordinateSystem High Precision ProjectedCoordinateSystem
MinX -573,741.824 -5,120,900.0
MinY -1,073,741.824 -9,998,100.0
MaxX 1,573,741.823 14,875,300.0
MaxY 1,073,741.823 9,998,100.0
Resolution 0.001 2.2 x 10^-9

 

Geographic Coordinate Systems

For a high precision GeographicCoordinateSystem (GCS), ConstructFromHorizon produces the square domain (-400, -400, 400, 400) (expressed in the units of the SR).  

For a low precision GCS the upper right hand corner is adjusted to achieve a default resolution of 1/500 of an arc-second.

Name Low Precision GeographicCoordinateSystem High Precision GeographicCoordinateSystem
MinX -400 -400
MinY -400 -400
MaxX 793.046469444444 400
MaxY 793.046469444444 400
Resolution 5.55555555555556E-07 (1/500 arc-second) 8.8 x 10^-14

 

Unknown Coordinate Systems

For an UnknownCoordinateSystem (UCS), the "horizon" is defined to be a square that produces a resolution of 1 millimeter for a low precision UCS or 1/10 mm for a high precision UCS.

The example below lists high and low precision extents for an UnknownCoordinateSystem.

Name Low Precision UnknownCoordinateSystem High Precision UnknownCoordinateSystem
MinX -1,073,741.8245 -450,359,962,737.05
MinY -1,073,741.8245 -450,359,962,737.05
MaxX 1,073,741.8225 450,359,962,737.049
MaxY 1,073,741.8225 450,359,962,737.049
Resolution 0.001 0.0001

 

SetDefaultMResolution()

Sets the m coordinate grid resolution to 1 mm for a low precision spatial reference or 1/10 mm for a high precision spatial reference.

void SetDefaultMResolution()

Remarks

This method behaves analogously to the SetDefaultXYResolution method, but operates on the linear m coordinate grid. For a high-precision spatial reference the default MResolution is 0.0001 units; for a low-precision spatial reference the default MResolution is 0.001 units.

SetDefaultXYResolution()

defaults: PCS(hi): 1/10 mm; PCS(lo): 1 mm; GCS(hi): 1/10,000 arc-second; GCS(lo): 1/500 arc-second; UCS(hi): 1/10 mm (assumed); UCS(lo): 1 mm (assumed).

void SetDefaultXYResolution()

Remarks

SetDefaultXYResolution recalculates the maximum x and y coordinates for the domain of the spatial reference in order to achieve a target resolution of 1 millimeter for low precision ProjectedCoordinateSystems or 1/10 millimeter for high precision. For high precision GeographicCoordinateSystems, the target resolution is 1/10,000 of an arc-second and the low precision target resolution is 1/500 of an arc-second. For UnknownCoordinateSystems, the high precision target resolution is 1/10 millimeter and the low precision target resolution is 1 millimeter.  Resolutions are listed here in metric units but are converted to the units of the spatial reference by these methods.

Use the ISpatialReferenceResolution::XYResolution(False) property to specify the target resolution in units defined by the spatial reference.

 

SetDefaultZResolution()

Sets the z coordinate grid resolution to 1 mm for a low precision spatial reference or 1/10 mm for a high precision spatial reference.

void SetDefaultZResolution()

Remarks

This method behaves analogously to the SetDefaultXYResolution method, but operates on the linear z coordinate grid.  For a high-precision spatial reference the default ZResolution is 0.0001 meters (expressed in the units defined by the VCS if applicable); for a low-precision spatial reference the default ZResolution is 0.001 units.