ISpatialReferenceFactory3 Interface

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

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

Members

	Name	Description
	ConstructHighPrecisionSpatialReference	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.
	ConstructLowPrecisionSpatialReference	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.
	CreateDatum	Creates a predefined datum.
	CreateESRISpatialReference	Creates a spatial reference system and defines it from the specified ESRISpatialReference buffer.
	CreateESRISpatialReferenceFromPRJ	Creates a spatial reference from a PRJ string.
	CreateESRISpatialReferenceFromPRJFile	Creates a spatial reference from a PRJ file.
	CreateESRISpatialReferenceInfo	Creates a spatial reference system and defines it from the specified ESRISpatialReference buffer.
	CreateESRISpatialReferenceInfoFromPRJ	Creates a spatial reference from a PRJ string.
	CreateESRISpatialReferenceInfoFromPRJFile	Creates a spatial reference from a PRJ file.
	CreateGeographicCoordinateSystem	Creates a predefined geographic coordinate system.
	CreateGeoTransformation	Creates a predefined transformation between geographic coordinate systems.
	CreateParameter	Creates a predefined parameter.
	CreatePredefinedAngularUnits	Creates a list of predefined angular units.
	CreatePredefinedDatums	Creates a list of a list of predefined datums.
	CreatePredefinedGeographicTransformations	Creates a list of predefined geographic transformations.
	CreatePredefinedLinearUnits	Creates a list of predefined linear units.
	CreatePredefinedPrimeMeridians	Creates a list of predefined prime meridians.
	CreatePredefinedProjections	Creates a list of predefined projections.
	CreatePredefinedSpheroids	Creates a list of predefined spheroids.
	CreatePredefinedVerticalCoordinateSystems	Creates a list of predefined vertical coordinate systems.
	CreatePredefinedVerticalDatums	Creates a list of predefined vertical datums.
	CreatePrimeMeridian	Creates a predefined prime meridian.
	CreateProjectedCoordinateSystem	Creates a predefined projected coordinate system.
	CreateProjection	Creates a predefined projection.
	CreateSpatialReference	Creates a predefined spatial reference from an srID.
	CreateSpheroid	Creates a predefined spheroid.
	CreateUnit	Creates a predefined unit of measure.
	CreateVerticalCoordinateSystem	Creates a predefined vertical coordinate system from an enumeration or ID code.
	CreateVerticalCoordinateSystemFromESRISpatialReference	Creates a vertical coordinate system from its string format.
	CreateVerticalDatum	Creates a predefined vertical datum from an enumeration or ID code.
	ExportESRISpatialReferenceInfoToPRJFile	Exports a spatial reference to a PRJ file.
	ExportESRISpatialReferenceToPRJFile	Exports a spatial reference to a PRJ file.
	GeoTransformationDefaults	Returns a list of default geographic transformations.
	GetPredefinedGeographicTransformations	Returns a list of predefined geographic transformations.

ISpatialReferenceFactory3.ConstructHighPrecisionSpatialReference Method

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.

Public Function ConstructHighPrecisionSpatialReference ( _
    ByVal inSR As ISpatialReference, _
    ByVal xyDoubler As Integer, _
    ByVal zDoubler As Integer, _
    ByVal mDoubler As Integer _
) As ISpatialReference

public ISpatialReference ConstructHighPrecisionSpatialReference (
    ISpatialReference inSR,
    int xyDoubler,
    int zDoubler,
    int mDoubler
);

Errors Returned

If a high precision spatial reference is passed in the operation returns E_Invalid_Arg.

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.

private void ConstructHighPrecisionSpatialReference()

    {

        // use activator class with SpatialReferenceEnvironment singleton

        Type factoryType = Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment");

        System.Object obj = Activator.CreateInstance(factoryType);

        ISpatialReferenceFactory3 spatialReferenceFactory = obj as ISpatialReferenceFactory3;

        ISpatialReference lowSpatialReference = spatialReferenceFactory.CreateSpatialReference(4326);

        IControlPrecision2 controlPrecision = lowSpatialReference as IControlPrecision2;

        //creates a low-precision SR

        controlPrecision.IsHighPrecision = false;

        ISpatialReferenceResolution spatialReferenceResolution = lowSpatialReference as ISpatialReferenceResolution;

        lowSpatialReference.SetFalseOriginAndUnits(-85, 120, 100000);

        //XYDoubler = -1 will result in highest legal resolution

        //M and Z doubler = 0 will result in output high precision SR matching resolution of input SR

        ISpatialReference highSpatialReference = spatialReferenceFactory.ConstructHighPrecisionSpatialReference(lowSpatialReference, -1, 0, 0);

    }

ISpatialReferenceFactory3.ConstructLowPrecisionSpatialReference Method

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.

Public Function ConstructLowPrecisionSpatialReference ( _
    ByVal bMatchPrecision As Boolean, _
    ByVal inSR As ISpatialReference, _
    ByVal dataExtent As IEnvelope _
) As ISpatialReference

public ISpatialReference ConstructLowPrecisionSpatialReference (
    bool bMatchPrecision,
    ISpatialReference inSR,
    IEnvelope dataExtent
);

Errors Returned

EINVALID_ARG - This error is returned if a low precision spatial reference is passed into _InSR.

-2147220986 FDO_E_IMPLEMENTATION

If maintainPrecision = True and the data extent cannot be covered with a low precision spatial reference the following error is returned: a low precision spatial reference cannot cover the specified extent at the input precision. To successfully create a low precision spatial reference you must either reduce the data extent or set maintainPrecision = False.

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.

ISpatialReferenceFactory3.CreateESRISpatialReferenceInfo Method

Creates a spatial reference system and defines it from the specified ESRISpatialReference buffer.

Public Sub CreateESRISpatialReferenceInfo ( _
    ByVal spatRefInfo As String, _
    ByRef SpatialReference As ISpatialReferenceInfo, _
    ByRef cBytesRead As Integer _
)

public void CreateESRISpatialReferenceInfo (
    string spatRefInfo,
    ref ISpatialReferenceInfo SpatialReference,
    ref int cBytesRead
);

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]]

ISpatialReferenceFactory3.CreateESRISpatialReferenceInfoFromPRJ Method

Creates a spatial reference from a PRJ string.

Public Function CreateESRISpatialReferenceInfoFromPRJ ( _
    ByVal prj As String _
) As ISpatialReferenceInfo

public ISpatialReferenceInfo CreateESRISpatialReferenceInfoFromPRJ (
    string prj
);

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.

ISpatialReferenceFactory3.CreateESRISpatialReferenceInfoFromPRJFile Method

Creates a spatial reference from a PRJ file.

Public Function CreateESRISpatialReferenceInfoFromPRJFile ( _
    ByVal prjFile As String _
) As ISpatialReferenceInfo

public ISpatialReferenceInfo CreateESRISpatialReferenceInfoFromPRJFile (
    string prjFile
);

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]]

ISpatialReferenceFactory3.CreatePredefinedVerticalCoordinateSystems Method

Creates a list of predefined vertical coordinate systems.

Public Function CreatePredefinedVerticalCoordinateSystems ( _
) As ISet

public ISet CreatePredefinedVerticalCoordinateSystems (
);

Description

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

ISpatialReferenceFactory3.CreatePredefinedVerticalDatums Method

Creates a list of predefined vertical datums.

Public Function CreatePredefinedVerticalDatums ( _
) As ISet

public ISet CreatePredefinedVerticalDatums (
);

Description

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

ISpatialReferenceFactory3.CreateVerticalCoordinateSystem Method

Creates a predefined vertical coordinate system from an enumeration or ID code.

Public Function CreateVerticalCoordinateSystem ( _
    ByVal vcsID As Integer _
) As IVerticalCoordinateSystem

public IVerticalCoordinateSystem CreateVerticalCoordinateSystem (
    int vcsID
);

Description

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

private void CreateVerticalReferenceSystem()

     {

         // use activator class with SpatialReferenceEnvironment singleton

         Type factoryType = Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment");

          System.Object obj = Activator.CreateInstance(factoryType);

         ISpatialReferenceFactory3 spatialReferenceFactory = obj as ISpatialReferenceFactory3;

        // Dimension a vertical datum and vertical coordinate system

         // Use the enumerations to create instances of the predefined objects

         IVerticalDatum verticalDatum = spatialReferenceFactory.CreateVerticalDatum((int)esriSRVerticalDatumType.esriSRVertDatum_Alicante);

          IVerticalCoordinateSystem verticalCoordinateSystem = spatialReferenceFactory.CreateVerticalCoordinateSystem((int)esriSRVerticalCSType.esriSRVertCS_Alicante);

      }

Dim pSRF As ISpatialReferenceFactory3

         pSRF = New SpatialReferenceEnvironment

        Dim pVCS As IVerticalCoordinateSystem

         Dim pGCS As IGeographicCoordinateSystem2

         Dim pSpatialReference3 As ISpatialReference3

        pGCS = pSRF.CreateGeographicCoordinateSystem(esriSRGeoCSType.esriSRGeoCS_NAD1927)

          pSpatialReference3 = pGCS

         pVCS = pSRF.CreateVerticalCoordinateSystem(esriSRVerticalCSType.esriSRVertCS_NAVD1988)

          pSpatialReference3.VerticalCoordinateSystem = pVCS

        Dim pVCS2 As IVerticalCoordinateSystem

         pVCS2 = pSpatialReference3.VerticalCoordinateSystem

ISpatialReferenceFactory3.CreateVerticalCoordinateSystemFromESRISpatialReference Method

Creates a vertical coordinate system from its string format.

Public Function CreateVerticalCoordinateSystemFromESRISpatialReference ( _
    ByVal srInfo As String _
) As IVerticalCoordinateSystem

public IVerticalCoordinateSystem CreateVerticalCoordinateSystemFromESRISpatialReference (
    string srInfo
);

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]]

ISpatialReferenceFactory3.CreateVerticalDatum Method

Creates a predefined vertical datum from an enumeration or ID code.

Public Function CreateVerticalDatum ( _
    ByVal vdID As Integer _
) As IVerticalDatum

public IVerticalDatum CreateVerticalDatum (
    int vdID
);

Description

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

private void CreateVerticalReferenceSystem()

    {

        // use activator class with SpatialReferenceEnvironment singleton

        Type factoryType = Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment");

        System.Object obj = Activator.CreateInstance(factoryType);

        ISpatialReferenceFactory3 spatialReferenceFactory = obj as ISpatialReferenceFactory3;

        // Dimension a vertical datum and vertical coordinate system

        // Use the enumerations to create instances of the predefined objects

        IVerticalDatum verticalDatum = spatialReferenceFactory.CreateVerticalDatum((int)esriSRVerticalDatumType.esriSRVertDatum_Alicante);

        IVerticalCoordinateSystem verticalCoordinateSystem = spatialReferenceFactory.CreateVerticalCoordinateSystem((int)esriSRVerticalCSType.esriSRVertCS_Alicante);

    }

ISpatialReferenceFactory3.ExportESRISpatialReferenceInfoToPRJFile Method

Exports a spatial reference to a PRJ file.

Public Sub ExportESRISpatialReferenceInfoToPRJFile ( _
    ByVal prjFile As String, _
    ByVal SpatialReference As ISpatialReferenceInfo _
)

public void ExportESRISpatialReferenceInfoToPRJFile (
    string prjFile,
    ISpatialReferenceInfo SpatialReference
);

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]]

Inherited Interfaces

Interfaces	Description
ISpatialReferenceFactory2	Provides access to members that create different kinds of spatial reference components.
ISpatialReferenceFactory	Provides access to members that create different kinds of spatial reference components.

Classes that implement ISpatialReferenceFactory3

Classes	Description
SpatialReferenceEnvironment	Creates various spatial reference objects.

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 using this interface in a console application, you must mark the routine as single-threaded.  A class can be marked as single-threaded by adding the [STAThread] attribute immediately preceding your routine's declaration.

Example:

    [STAThread]

     static void Main(string[] args)

     {

     }

When using this interface in a console application, you must mark the routine as single-threaded.  A class can be marked as single-threaded by adding the [STAThread] attribute immediately preceding your routine's declaration.

 

  <STAThread()> _

    Shared Sub Main(ByVal args As String()) 

 

    End Sub