This document is archived and information here might be outdated.  Recommended version.


Using the SpatialReferenceEnvironment (ArcObjects .NET 10.5 SDK)

Using the SpatialReferenceEnvironment


Summary
This topic shows how to use the SpatialReferenceEnvironment singleton object. The SpatialReferenceFactory interfaces, factory codes, and several methods for creating a coordinate system are also discussed.

In this topic


About using the spatial reference environment

ArcObjects includes a vast array of predefined spatial reference systems and building blocks for spatial reference systems. Each predefined object is identified by a factory code. Factory codes are defined enumeration sets that begin with esriSR. Use the enumeration macro rather than the integer value it represents.
Occasionally, the code value an enumeration stands for might change. This is because many of the values are from the European Petroleum Survey Group (EPSG) Geodetic Parameter Dataset, which is becoming an industry standard.

Supported functions

The ISpatialReferenceFactory interface provides methods that use the FactoryCode to generate predefined factory spatial reference objects. The following are the three types of functions on this interface:
  • Those that return single objects
  • Those that return a set of objects of the same type
  • Those that are used to import and export SpatialReference objects to and from a .prj file or a .prj string representation
For example, the CreateGeographicCoordinateSystem function takes as its only parameter an integer that represents the FactoryCode of a predefined geographic coordinate system (GCS). The function returns a fully instantiated GCS object that can then be queried for its properties and classes.
The next type of function on the ISpatialReferenceFactory interface returns a complete set of objects. For example, the CreatePredefinedProjections function returns a set that contains all the available projection objects. These type of functions are useful for developers who want to populate a drop-down selection list of available SpatialReference objects. See the following code example:
[C#]
private void PrintPreDefinedProjections()
{

    // Set up the SpatialReferenceEnvironment.
    // SpatialReferenceEnvironment is a singleton object and needs to use the Activator class.

    Type factoryType=Type.GetTypeFromProgID(
        "esriGeometry.SpatialReferenceEnvironment");
    System.Object obj=Activator.CreateInstance(factoryType);
    ISpatialReferenceFactory spatialReferenceFactory=obj as
        ISpatialReferenceFactory;

    ISet projectionSet=spatialReferenceFactory.CreatePredefinedProjections();

    System.Windows.Forms.MessageBox.Show("Number of predefined Projections=" +
        projectionSet.Count);

    projectionSet.Reset();

    for (int i=0; i < projectionSet.Count; i++)
    {
        IProjection projection=projectionSet.Next()as IProjection;
        Console.WriteLine("PCS Name: {0} (Code: {1})", projection.Name,
            projection.FactoryCode);
    }

}
[VB.NET]
Private Sub PrintPreDefinedProjections()
    
    ' Set up the SpatialReferenceEnvironment.
    ' SpatialReferenceEnvironment is a singleton object and needs to use the Activator class.
    
    Dim factoryType As Type=Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment")
    Dim spatialReferenceFactory As ISpatialReferenceFactory3=CType(Activator.CreateInstance(factoryType), ISpatialReferenceFactory3)
    
    Dim projectionSet As ISet=spatialReferenceFactory.CreatePredefinedProjections()
    
    System.Windows.Forms.MessageBox.Show("Number of predefined Projections=" & projectionSet.Count)
    projectionSet.Reset()
    
    For i As Integer=0 To projectionSet.Count - 1
        Dim projection As IProjection=CType(projectionSet.Next(), IProjection)
        Console.WriteLine("PCS Name: {0} (Code: {1})", projection.Name, projection.FactoryCode)
    Next i
    
End Sub
The third type of function supported by ISpatialReferenceFactory deals with .prj files and strings. CreateESRISpatialReferenceFromPRJFile takes an old- or new-style .prj file and creates either a geographic or projected coordinate system from it, depending on the file contents. The old-style .prj file is used with coverages, triangulated irregular networks (TINs), and grids.
CreateESRISpatialReferenceFromPRJ is used to create a SpatialReference based on the string buffer of an old-style .prj file. While CreateESRISpatialReference is similar, the string buffer must be in the format of a new .prj file. The following code example shows how to create a SpatialReference coordinate system directly from a .prj file (both old- and new-style files are supported):
[C#]
private IProjectedCoordinateSystem LoadProjectedCoordinateSystem()
{

    // Set up the SpatialReferenceEnvironment.
    // SpatialReferenceEnvironment is a singleton object and needs to use the Activator class.

    Type factoryType=Type.GetTypeFromProgID(
        "esriGeometry.SpatialReferenceEnvironment");
    System.Object obj=Activator.CreateInstance(factoryType);
    ISpatialReferenceFactory spatialReferenceFactory=obj as
        ISpatialReferenceFactory;

    IProjectedCoordinateSystem projectedCoordinateSystem =
        spatialReferenceFactory.CreateESRISpatialReferenceFromPRJFile(
        "C:\\Program Files\\ArcGIS\\Desktop10.0\\Coordinate Systems\\Projected Coordinate Systems\\World\\Mollweide (world).prj")as IProjectedCoordinateSystem;
    return projectedCoordinateSystem;

}
[VB.NET]
Private Function LoadProjectedCoordinateSystem() As IProjectedCoordinateSystem
    
    ' Set up the SpatialReferenceEnvironment.
    ' SpatialReferenceEnvironment is a singleton object and needs to use the Activator class.
    
    Dim factoryType As Type=Type.GetTypeFromProgID("esriGeometry.SpatialReferenceEnvironment")
    Dim spatialReferenceFactory As ISpatialReferenceFactory3=CType(Activator.CreateInstance(factoryType), ISpatialReferenceFactory3)
    
    Dim projectedCoordinateSystem As IProjectedCoordinateSystem=CType(spatialReferenceFactory.CreateESRISpatialReferenceFromPRJFile _
                                                                  ("C:\Program Files\ArcGIS\Desktop10.0\Coordinate Systems\Projected Coordinate Systems\World\Mollweide (world).prj"), IProjectedCoordinateSystem)
    
    Return projectedCoordinateSystem
    
End Function
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 ensures that coordinate values fit exactly into the new, denser grid mesh. Each intersection of the original grid is an intersection of the new grid.
ConstructLowPrecisionSpatialReference creates a low-precision spatial reference from an existing high-precision one. You can require that the new resolution value be maintained, possibly at the expense of the x,y-domain extent.
In addition, ISpatialReferenceFactory3 provides access to predefined vertical coordinate systems and datums via the CreateVerticalCoordinateSystem and CreateVerticalDatum methods. The predefined vertical datums and coordinate systems are listed in the esriSRVerticalDatumType and esriSRVerticalCSType enumerations.


See Also:

Constructing a high- or low-precision spatial reference




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

Development licensing Deployment licensing
ArcGIS Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced
Engine Developer Kit Engine