com.esri.arcgis.geometry
Interface ISpatialReference

All Superinterfaces:
ISpatialReferenceInfo, Serializable
All Known Subinterfaces:
IGeographicCoordinateSystem, IGeographicCoordinateSystem2, IProjectedCoordinateSystem, IProjectedCoordinateSystem2, IProjectedCoordinateSystem3, IProjectedCoordinateSystem4, IProjectedCoordinateSystem5, ISpatialReference2, ISpatialReference3, IUnknownCoordinateSystem
All Known Implementing Classes:
GeographicCoordinateSystem, ProjectedCoordinateSystem, UnknownCoordinateSystem

public interface ISpatialReference
extends ISpatialReferenceInfo, Serializable

Provides access to members that control a SpatialReference.

Superseded By

ISpatialReference3

Description

The spatial reference is not defined when creating a new instance of a geometry. It is the developer's responsibility to define a spatial reference that makes sense for the geometry and for the operation. To achieve precise and predictable results using the geometry library, it is essential that the spatial reference of geometries within a workflow is well defined. When performing a spatial operation using two or more geometries, for example an intersection, the coordinate systems of the two geometries must be equal. If the coordinate systems of the geometries are different or undefined, the operation could produce unexpected results.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


Method Summary
 void changed()
          Notify this object that some of its parts have changed (parameter values, z unit, etc.).
 void getDomain(double[] xMin, double[] xMax, double[] yMin, double[] yMax)
          The XY domain extent.
 void getFalseOriginAndUnits(double[] falseX, double[] falseY, double[] xyUnits)
          Get the false origin and units.
 void getMDomain(double[] outMMin, double[] outMMax)
          The measure domain extent.
 void getMFalseOriginAndUnits(double[] falseM, double[] mUnits)
          Get the measure false origin and units.
 ILinearUnit getZCoordinateUnit()
          The unit for the Z coordinate.
 void getZDomain(double[] outZMin, double[] outZMax)
          The Z domain extent.
 void getZFalseOriginAndUnits(double[] falseZ, double[] zUnits)
          Get the Z false origin and units.
 boolean hasMPrecision()
          Returns true when m-value precision information has been defined.
 boolean hasXYPrecision()
          Returns true when (x,y) precision information has been defined.
 boolean hasZPrecision()
          Returns true when z-value precision information has been defined.
 void isPrecisionEqual(ISpatialReference otherSR, boolean[] isPrecisionEqual)
          Returns TRUE when the precision information for the two spatial references is the same.
 void setDomain(double xMin, double xMax, double yMin, double yMax)
          The XY domain extent.
 void setFalseOriginAndUnits(double falseX, double falseY, double xyUnits)
          Set the false origin and units.
 void setMDomain(double inMMin, double inMMax)
          The measure domain extent.
 void setMFalseOriginAndUnits(double falseM, double mUnits)
          Set the measure false origin and units.
 void setZCoordinateUnit(ILinearUnit zunit)
          The unit for the Z coordinate.
 void setZDomain(double inZMin, double inZMax)
          The Z domain extent.
 void setZFalseOriginAndUnits(double falseZ, double zUnits)
          Set the Z false origin and units.
 
Methods inherited from interface com.esri.arcgis.geometry.ISpatialReferenceInfo
getAbbreviation, getAlias, getFactoryCode, getName, getRemarks
 

Method Detail

hasXYPrecision

boolean hasXYPrecision()
                       throws IOException,
                              AutomationException
Returns true when (x,y) precision information has been defined.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The hasXYPrecision
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

hasZPrecision

boolean hasZPrecision()
                      throws IOException,
                             AutomationException
Returns true when z-value precision information has been defined.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The hasZPrecision
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

hasMPrecision

boolean hasMPrecision()
                      throws IOException,
                             AutomationException
Returns true when m-value precision information has been defined.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The hasMPrecision
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isPrecisionEqual

void isPrecisionEqual(ISpatialReference otherSR,
                      boolean[] isPrecisionEqual)
                      throws IOException,
                             AutomationException
Returns TRUE when the precision information for the two spatial references is the same.

Remarks

The IClone::IsEqual method implementation for spatial references only compares the coordinate system (projection information) portion of the spatial reference. If, in addition, you need to verify that the coordinate grid portions of the spatial references are equal, apply this method after IsEqual. The XY, Z, or M domain and resolution (precision) values, as well as the XY, Z and M cluster tolerances are compared.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
otherSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
isPrecisionEqual - The isPrecisionEqual (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setFalseOriginAndUnits

void setFalseOriginAndUnits(double falseX,
                            double falseY,
                            double xyUnits)
                            throws IOException,
                                   AutomationException
Set the false origin and units.

Description

An alternative to the SetDomain method. The falseX and falseY values correspond to the minimum X and minimum Y values of the XY domain. The xyUnits, also referred to as the scale factor, is the is the inverse of the resolution (which is also referred to as the precision).

Sample values if data is based on a geographic coordinate system are:

falseX = -180

falseY = -90

xyUnits = 1000000

Sample values if data is based on a projected coordinate system are:

 
falseX = 200000
falseY = 4000000
xyUnits = 100
 

Remarks

When creating a new spatial reference with a projected or geographic coordinate system, the recommended method for defining the XY Domain is ISpatialReferenceResolution::ConstructFromHorizon.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseX - The falseX (in)
falseY - The falseY (in)
xyUnits - The xyUnits (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setZFalseOriginAndUnits

void setZFalseOriginAndUnits(double falseZ,
                             double zUnits)
                             throws IOException,
                                    AutomationException
Set the Z false origin and units.

Description

An alternative method to the SetZDomain method. The falseZ value corresponds to the minimum Z value of the Z domain. The zUnits is the same as the precision or scale value. The inverse of zUnits is the resolution of the z data.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseZ - The falseZ (in)
zUnits - The zUnits (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMFalseOriginAndUnits

void setMFalseOriginAndUnits(double falseM,
                             double mUnits)
                             throws IOException,
                                    AutomationException
Set the measure false origin and units.

Description

An alternative method to the SetMDomain method. The falseM value corresponds to the minimum measure value of the measure domain. The mUnits is the same as the precision or scale value. The inverse of mUnits is the resolution of the measure data.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseM - The falseM (in)
mUnits - The mUnits (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFalseOriginAndUnits

void getFalseOriginAndUnits(double[] falseX,
                            double[] falseY,
                            double[] xyUnits)
                            throws IOException,
                                   AutomationException
Get the false origin and units.

Description

An alternative method to the GetDomain method. The falseX and falseY values correspond to the minimum X and minimum Y values of the XY domain. The xyUnits is the same as the precision or scale value. The inverse of the xyUnits defines the resolution of the data stored in the geodatabase. The resolution is used to snap data when it is stored in the geodatabase.

The falseX, falseY, and xyUnits use the same unit of measure as the coordinate system.

Sample values if data is based on a geographic coordinate system are:

falseX = -180

falseY = -90

xyUnits = 1000000

Sample values if data is based on a projected coordinate system are:

 
falseX = 200000
falseY = 4000000
xyUnits = 100

In the first example, the data is using a geographic coordinate system so the falseX and falseY values are in degrees. The inverse of the xyUnits is 0.000001 degrees.

In the second example, the data is using a projected coordinate system. Let us assume that the unit of measure is meters. The smallest coordinates values that a feature can have is x = 200000 meters and Y = 4000000 meters. The inverse of the xyUnits is 0.01 (meters) which means data will be snapped to the closest centimeter when it is stored.

Remarks

Use this function to retrieve the following information about the spatial reference of the geometry:

falseX: XMin of the domain.

falseY: YMin of the domain.

XYUnits: Precision of the domain.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseX - The falseX (out: use single element array)
falseY - The falseY (out: use single element array)
xyUnits - The xyUnits (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getZFalseOriginAndUnits

void getZFalseOriginAndUnits(double[] falseZ,
                             double[] zUnits)
                             throws IOException,
                                    AutomationException
Get the Z false origin and units.

Description

An alternative method to the GetZDomain method. The falseZ value corresponds to the minimum Z value of the Z domain. The zUnits is the same as the precision or scale value. The inverse of the zUnits defines the resolution of the z data stored in the geodatabase. The resolution is used to snap data when it is stored in the geodatabase.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseZ - The falseZ (out: use single element array)
zUnits - The zUnits (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMFalseOriginAndUnits

void getMFalseOriginAndUnits(double[] falseM,
                             double[] mUnits)
                             throws IOException,
                                    AutomationException
Get the measure false origin and units.

Description

An alternative method to the GetMDomain method. The falseM value corresponds to the minimum measure value of the measure domain. The mUnits is the same as the precision or scale value. The inverse of the mUnits defines the resolution of the measure data stored in the geodatabase. The resolution is used to snap data when it is stored in the geodatabase.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
falseM - The falseM (out: use single element array)
mUnits - The mUnits (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDomain

void getDomain(double[] xMin,
               double[] xMax,
               double[] yMin,
               double[] yMax)
               throws IOException,
                      AutomationException
The XY domain extent.

Description

An alternative method to the GetFalseOriginAndUnits method. Returns the minimum and maximum allowed X and Y values for a spatial reference. Use GetFalseOriginAndUnits to obtain the allowed precision (1/resolution) value.

Remarks

The GetDomain and SetDomain methods are used to set and get the square domain extent of a coordinate system. The domain extent is different than the valid area of a coordinate system. The domain extent is an arbitrary square used to delimit valid coordinates for a spatial reference system and determine their resolution. It is possible that the domain extent is larger than the usable area of a coordinate system (a UTM zone, for example). A small domain extent gives you finer resolution coordinates over a smaller area. A larger domain extent lets you represent features over a larger geographic area but with coarser resolution.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
xMin - The xMin (out: use single element array)
xMax - The xMax (out: use single element array)
yMin - The yMin (out: use single element array)
yMax - The yMax (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setDomain

void setDomain(double xMin,
               double xMax,
               double yMin,
               double yMax)
               throws IOException,
                      AutomationException
The XY domain extent.

Description

An alternative method to the SetFalseOriginAndUnits method. Sets the minimum and maximum allowed X and Y values for a spatial reference . A resolution is then calculated from these extremes. Use SetFalseOriginAndUnits to set explicitly the desired scale factor (1.0/resolution) value.

Remarks

The xy domain must be square. If you set a wider X or Y extent, it will take precedence. For example, let's say you set these values:

XMin = -180

XMax = 180

YMin = -90

YMax = 90

If you then query the values with GetDomain, you will see that the YMax value is 270. That is because the X extent is 360, so the Y extent must also be 360. The minimum x and y values are always maintained.

When creating a new spatial reference with a projected or geographic coordinate system, the recommended method for defining the XY Domain is ISpatialReferenceResolution::ConstructFromHorizon. This method produces a valid domain that covers the valid coordinate range for the coordinate system.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
xMin - The xMin (in)
xMax - The xMax (in)
yMin - The yMin (in)
yMax - The yMax (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getZDomain

void getZDomain(double[] outZMin,
                double[] outZMax)
                throws IOException,
                       AutomationException
The Z domain extent.

Description

An alternative method to the GetZFalseOriginAndUnits method. Returns the minimum and maximum allowed Z values for a spatial reference. Use GetZFalseOriginAndUnits to obtain the Z precision (1/resolution) value.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
outZMin - The outZMin (out: use single element array)
outZMax - The outZMax (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setZDomain

void setZDomain(double inZMin,
                double inZMax)
                throws IOException,
                       AutomationException
The Z domain extent.

Description

An alternative method to the SetZFalseOriginAndUnits method. Sets the minimum and maximum allowed Z values for a spatial reference. Use SetZFalseOriginAndUnits to set explicitly the allowed Z precision value. The zUnits value is the inverse of the resolution of the Z data.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
inZMin - The inZMin (in)
inZMax - The inZMax (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMDomain

void getMDomain(double[] outMMin,
                double[] outMMax)
                throws IOException,
                       AutomationException
The measure domain extent.

Description

An alternative method to the GetMFalseOriginAndUnits method. Returns the minimum and maximum allowed measure values for a spatial reference. Use GetMFalseOriginAndUnits to obtain the M precision (1/resolution) value.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
outMMin - The outMMin (out: use single element array)
outMMax - The outMMax (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMDomain

void setMDomain(double inMMin,
                double inMMax)
                throws IOException,
                       AutomationException
The measure domain extent.

Description

An alternative method to the SetMFalseOriginAndUnits method. Sets the minimum and maximum allowed measure values for a spatial reference. Use SetMFalseOriginAndUnits to set explicitly the allowed measure precision value. The mUnits value is the inverse of the resolution of the measure data.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
inMMin - The inMMin (in)
inMMax - The inMMax (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getZCoordinateUnit

ILinearUnit getZCoordinateUnit()
                               throws IOException,
                                      AutomationException
The unit for the Z coordinate.

Remarks

ISpatialReference::ZCoordinateUnit should no longer be used in favor of ISpatialReference3::VerticalCoordinateSystem

There is now an entire Vertical Coordinate System available for your convenience. Using ISpatialReference3::VerticalCoordinateSystem has several benefits including allowing the user to choose a datum, positive or negative direction for the values of Z, and a vertical shift to the Z values.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.ILinearUnit
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setZCoordinateUnit

void setZCoordinateUnit(ILinearUnit zunit)
                        throws IOException,
                               AutomationException
The unit for the Z coordinate.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
zunit - A reference to a com.esri.arcgis.geometry.ILinearUnit (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

changed

void changed()
             throws IOException,
                    AutomationException
Notify this object that some of its parts have changed (parameter values, z unit, etc.).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.