com.esri.arcgis.geometry
Interface ISpatialReferenceFactory3

All Superinterfaces:
ISpatialReferenceFactory, ISpatialReferenceFactory2, Serializable
All Known Subinterfaces:
ISpatialReferenceFactory4
All Known Implementing Classes:
SpatialReferenceEnvironment

public interface ISpatialReferenceFactory3
extends ISpatialReferenceFactory2, Serializable

Provides access to members that create vertical datums or coordinate systems.

Remarks

The ISpatialReferenceFactory3 interface has two methods that are useful when working with low and high precision spatial references. ConstructHighPrecisionSpatialReference creates a high precision spatial reference from a low precision spatial reference. Using this method will ensure that coordinate values will fit exactly into the new, denser grid mesh. Each intersection of the original grid is an intersection of the new grid. ConstructLowPrecisionSpatialReference will create a low precision spatial reference from an existing high precision one. You can require that the new resolution value be maintained, usually at the expense of the XY domain extent.

When To Use

ISpatialReferenceFactory3 provides methods for vertical coordinate system support and convert existing low precision spatial references to a high precision spatial reference (or vice-versa).

Product Availability

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


Method Summary
 ISpatialReference constructHighPrecisionSpatialReference(ISpatialReference inSR, int xyDoubler, int zDoubler, int mDoubler)
          Constructs a high precision spatial reference based on an existing spatial reference.
 ISpatialReference constructLowPrecisionSpatialReference(boolean bMatchPrecision, ISpatialReference inSR, IEnvelope dataExtent)
          Construct a low precision spatial reference with the same scale factor as the high precision input, but with a different domain extent.
 void createESRISpatialReferenceInfo(String spatRefInfo, ISpatialReferenceInfo[] spatialReference, int[] cBytesRead)
          Creates a spatial reference system and defines it from the specified ESRISpatialReference buffer.
 ISpatialReferenceInfo createESRISpatialReferenceInfoFromPRJ(String prj)
          Creates a spatial reference from a PRJ string.
 ISpatialReferenceInfo createESRISpatialReferenceInfoFromPRJFile(String prjFile)
          Creates a spatial reference from a PRJ file.
 ISet createPredefinedVerticalCoordinateSystems()
          Creates a list of predefined vertical coordinate systems.
 ISet createPredefinedVerticalDatums()
          Creates a list of predefined vertical datums.
 IVerticalCoordinateSystem createVerticalCoordinateSystem(int vcsID)
          Creates a predefined vertical coordinate system from an enumeration or ID code.
 IVerticalCoordinateSystem createVerticalCoordinateSystemFromESRISpatialReference(String srInfo)
          Creates a vertical coordinate system from its string format.
 IVerticalDatum createVerticalDatum(int vdID)
          Creates a predefined vertical datum from an enumeration or ID code.
 void exportESRISpatialReferenceInfoToPRJFile(String prjFile, ISpatialReferenceInfo spatialReference)
          Exports a spatial reference to a PRJ file.
 
Methods inherited from interface com.esri.arcgis.geometry.ISpatialReferenceFactory2
createPredefinedGeographicTransformations, createSpatialReference, getGeoTransformationDefaults, getPredefinedGeographicTransformations
 
Methods inherited from interface com.esri.arcgis.geometry.ISpatialReferenceFactory
createDatum, createESRISpatialReference, createESRISpatialReferenceFromPRJ, createESRISpatialReferenceFromPRJFile, createGeographicCoordinateSystem, createGeoTransformation, createParameter, createPredefinedAngularUnits, createPredefinedDatums, createPredefinedLinearUnits, createPredefinedPrimeMeridians, createPredefinedProjections, createPredefinedSpheroids, createPrimeMeridian, createProjectedCoordinateSystem, createProjection, createSpheroid, createUnit, exportESRISpatialReferenceToPRJFile
 

Method Detail

createVerticalCoordinateSystem

IVerticalCoordinateSystem createVerticalCoordinateSystem(int vcsID)
                                                         throws IOException,
                                                                AutomationException
Creates a predefined vertical coordinate system from an enumeration or ID code.

Description

Use an element from the esriSRVerticalCSType enumeration as the VerticalCSType to create a particular predefined vertical coordinate system.

Product Availability

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

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

createVerticalDatum

IVerticalDatum createVerticalDatum(int vdID)
                                   throws IOException,
                                          AutomationException
Creates a predefined vertical datum from an enumeration or ID code.

Description

Use an element from the esriSRVerticalDatumType enumeration as the vdID to create a particular predefined vertical datum.

Product Availability

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

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

createPredefinedVerticalDatums

ISet createPredefinedVerticalDatums()
                                    throws IOException,
                                           AutomationException
Creates a list of predefined vertical datums.

Description

Returns a list of all predefined vertical datums. The list has two columns: the factory code and the name.

Product Availability

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

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

createPredefinedVerticalCoordinateSystems

ISet createPredefinedVerticalCoordinateSystems()
                                               throws IOException,
                                                      AutomationException
Creates a list of predefined vertical coordinate systems.

Description

Returns a list of all predefined vertical coordinate systems. The list has two columns: the factory code and the name.

Product Availability

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

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

createVerticalCoordinateSystemFromESRISpatialReference

IVerticalCoordinateSystem createVerticalCoordinateSystemFromESRISpatialReference(String srInfo)
                                                                                 throws IOException,
                                                                                        AutomationException
Creates a vertical coordinate system from its string format.

Description

Creates a vertical coordinate system object from the well-known text (WKT) version of a spatial reference. An example of a WKT string that contains geographic and vertical coordinate systems is below. The string is broken into several lines to make it easier to read.

GEOGCS["GCS_North_American_1927",DATUM["D_North_American_1927",
SPHEROID["Clarke_1866",6378206.4,294.9786982]],
PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],
VERTCS["NAVD_1988",VDATUM["North_American_Vertical_Datum_1988"],
PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],
UNIT["Meter",1.0]]
 

Product Availability

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

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

createESRISpatialReferenceInfo

void createESRISpatialReferenceInfo(String spatRefInfo,
                                    ISpatialReferenceInfo[] spatialReference,
                                    int[] cBytesRead)
                                    throws IOException,
                                           AutomationException
Creates a spatial reference system and defines it from the specified ESRISpatialReference buffer.

Description

CreateESRISpatialReferenceInfo creates a spatial reference from the well-known text (WKT) version. Below is an example of a WKT string, broken into several lines to make it easier to read.

GEOGCS["GCS_North_American_1927",DATUM["D_North_American_1927",

  SPHEROID["Clarke_1866",6378206.4,294.9786982]],

  PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],

VERTCS["NAVD_1988",VDATUM["North_American_Vertical_Datum_1988"],

  PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],

  UNIT["Meter",1.0]]

Product Availability

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

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

createESRISpatialReferenceInfoFromPRJ

ISpatialReferenceInfo createESRISpatialReferenceInfoFromPRJ(String prj)
                                                            throws IOException,
                                                                   AutomationException
Creates a spatial reference from a PRJ string.

Description

CreateESRISpatialReferenceInfoFromPRJ creates a spatial reference from an ArcGIS for Desktop Advanced workstation version of a coordinate system definition. This type of definition is used for coverages, TINs, and GRIDs. If you pass in a Projection Engine-style string instead, "the input is not a workstation prj file" error message is returned. The Projection Engine format is used by shapefiles, geodatabases, and raster formats other than GRIDs.

An ArcGIS for Desktop Advanced workstation file might look like:

Projection GEOGRAPHIC

Units DEGREES

Datum WGS84

Spheroid WGS84

Parameters

Use CreateESRISpatialReferenceInfoFromPRJFile if you want to create a spatial reference from a Projection Engine-style string.

Product Availability

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

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

createESRISpatialReferenceInfoFromPRJFile

ISpatialReferenceInfo createESRISpatialReferenceInfoFromPRJFile(String prjFile)
                                                                throws IOException,
                                                                       AutomationException
Creates a spatial reference from a PRJ file.

Description

Creates a spatial reference from a file that contains the well-known text version. Below is an example of a WKT version that contains both geographic and vertical coordinate systems. WKT is always a single line, but the sample is broken into several lines to make it easier to read.

GEOGCS["GCS_North_American_1927",DATUM["D_North_American_1927",
SPHEROID["Clarke_1866",6378206.4,294.9786982]],
PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],
VERTCS["NAVD_1988",VDATUM["North_American_Vertical_Datum_1988"],
PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],
UNIT["Meter",1.0]]

Product Availability

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

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

exportESRISpatialReferenceInfoToPRJFile

void exportESRISpatialReferenceInfoToPRJFile(String prjFile,
                                             ISpatialReferenceInfo spatialReference)
                                             throws IOException,
                                                    AutomationException
Exports a spatial reference to a PRJ file.

Description

Creates a well-known text version of a spatial reference and writes the information to a file. Below is an example of a WKT version that contains both geographic and vertical coordinate systems. WKT is always a single line, but the sample is broken into several lines to make it easier to read.

GEOGCS["GCS_North_American_1927",DATUM["D_North_American_1927",
SPHEROID["Clarke_1866",6378206.4,294.9786982]],
PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],
VERTCS["NAVD_1988",VDATUM["North_American_Vertical_Datum_1988"],
PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],
UNIT["Meter",1.0]]

Product Availability

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

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

constructHighPrecisionSpatialReference

ISpatialReference constructHighPrecisionSpatialReference(ISpatialReference inSR,
                                                         int xyDoubler,
                                                         int zDoubler,
                                                         int mDoubler)
                                                         throws IOException,
                                                                AutomationException
Constructs a high precision spatial reference based on an existing spatial reference. xy/z/mDoubler is the number of times the respective precision is to be doubled. A value of zero will find the maximum doubling for that precision.

Remarks

ConstructHighPrecisionSpatialReference creates a high precision copy of an existing low precision spatial reference. It is used when the new high precision spatial reference grid must “mesh” with the existing low precision grid. Each point of the old grid is also a point of the new grid.

The doubler parameters are exponents of powers of 2. For example, if the xyDoubler = 2, then the XY grid resolution of the output spatial reference is 4 times the input grid resolution (16 new grid cells cover 1 old grid cell). The grid also is translated so it remains centered about its current location. If a doubler parameter is -1, then the closest legal resolution to the default that covers the input XY domain and the coordinate system's horizon is chosen. If the doubler parameter is -2, the smallest possible legal resolution that covers the input XY domain and the coordinate system's horizon is chosen. In these cases, the highest exponent is chosen that will produce an output grid that both contains all the grid points defined by the input grid and covers the horizon of the input spatial reference. A doubler value of zero will maintain the existing resolution of the low precision spatial reference. It is an error to specify a doubler parameter that will result in a grid smaller than the corresponding input grid.

For ProjectedCoordinateSystems or GeographicCoordinateSystems the minimum values of the domain extent are defined just outside the envelope defined by the coordinate system's horizon.

Product Availability

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

Parameters:
inSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
xyDoubler - The xyDoubler (in)
zDoubler - The zDoubler (in)
mDoubler - The mDoubler (in)
Returns:
A reference to a com.esri.arcgis.geometry.ISpatialReference
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

constructLowPrecisionSpatialReference

ISpatialReference constructLowPrecisionSpatialReference(boolean bMatchPrecision,
                                                        ISpatialReference inSR,
                                                        IEnvelope dataExtent)
                                                        throws IOException,
                                                               AutomationException
Construct a low precision spatial reference with the same scale factor as the high precision input, but with a different domain extent. If the calculated domain extent cannot cover the specified data extent, an error is returned.

Remarks

ConstructLowPrecisionSpatialReference creates a low precision copy of an existing high precision spatial reference.

Product Availability

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

Parameters:
bMatchPrecision - The bMatchPrecision (in)
inSR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
dataExtent - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Returns:
A reference to a com.esri.arcgis.geometry.ISpatialReference
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.