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.

• bMatchPrecision indicates whether the output low precision spatial reference should have the same resolution as the input high precision spatial reference. If not, then pExtent is used to help determine the output resolution.
• pInSR is the existing high precision spatial reference. Passing in a low precision spatial reference will return an error.
• pExtent is used to determine the output resolution when matching the input resolultion is not desired. ConstructLowPrecisionSpatialReference delegates to the existing method IGeometryEnvironment::ConstructDomainExtent in that case, which attempts to enlarge the extent by a factor of 1.5 (clipped against the horizon extent). If an empty envelope is passed in and bMatchPrecision is FALSE, then the low precision version of ISpatialReferenceResolution::ConstructFromHorizon is used for GeographicCoordinateSystems or ProjectedCoordinateSystems. If bMatchPrecision is true, then an attempt is made to use the domain extent as the new domain extent; the precision is not matched in this case.
  

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.