Working with the analysis environment (ArcObjects .NET 10.5 SDK)

Summary

This topic provides a brief introduction on how to work with the analysis environment with spatial analysis operations.

About working with the analysis environment

The analysis environment controls the properties of the analysis performed by almost every Spatial Analyst operation. It contains the cell size, extent, and mask settings and provides a way to control the output spatial reference, and the output workspace into which temporary results are created.

The verify type environment setting is used when overwriting previous results, and the prefixes are used for the temporary output dataset name.

The session default analysis environment controls the analysis environment that is assigned to each operator object when it is created. The following are the initial default settings:

Cellsize—Maximum of input dataset cell sizes (MAXOF).
Extent—Intersection of input dataset extents (MINOF).
Mask—None.
Verify—Returns error message if output exists and terminates process.
DefaultOutputRasterPrefix—Raster.
DefaultOutputVectorPrefix—Shape.
OutSpatialReference—For more information, see Handling spatial reference.
OutWorkspace—Uses the %TEMP% system variable.

The session default analysis environment can be overridden so each new operator object begins with a different set of analysis environment properties. This can be useful if you are performing an analysis that requires use of multiple operator objects, and this analysis needs to use an analysis environment setting that is not the same as the default.

To change the session default analysis environment, create the RasterAnalysis object. Change the settings of the analysis environment to those you want to make the default, then call the SetAsNewDefaultEnvironment method. The SetAsNewDefaultEnvironment method will not change the analysis environment associated with any existing operator objects, but each new operator object created will contain the default settings.

You can change environment settings and call the SetAsNewDefaultEnvironment method as many times as you want. To restore the previous set of defaults, call RestoreToPreviousDefaultEnvironment. You can call this method as many times as you have called the SetAsNewDefaultEnvironment method. To reset the global analysis environment to the original defaults, call the Reset method.

The following code example shows how to change the default analysis environment settings that subsequent new operator objects will inherit:

[C#]

public IRasterAnalysisEnvironment SetNewDefaultEnvironment(IEnvelope envelope_Extent,
    double nCellSize, IGeoDataset geoDataset_Mask, IWorkspace workspace,
    ISpatialReference spatialReference)
{
    // Creates a new RasterAnalysis object and sets it as a new default setting.
    // Create a RasterAnalysis object.
    IRasterAnalysisEnvironment rasterAnalysisEnvironment=new RasterAnalysisClass();
    try
    {
        // Set the new default extent.
        if (envelope_Extent != null)
        {
            object extentProvider=(object)envelope_Extent;
            object snapRasterData=Type.Missing;
            rasterAnalysisEnvironment.SetExtent
                (esriRasterEnvSettingEnum.esriRasterEnvValue, ref extentProvider,
                ref snapRasterData);
        }
        // Set the new default cell size.
        if (nCellSize > 0)
        {
            object cellSizeProvider=(object)nCellSize;
            rasterAnalysisEnvironment.SetCellSize
                (esriRasterEnvSettingEnum.esriRasterEnvValue, ref cellSizeProvider);
        }
        // Set the new default mask for analysis.
        if (geoDataset_Mask != null)
        {
            rasterAnalysisEnvironment.Mask=geoDataset_Mask;
        }
        // Set the new default output workspace.
        if (workspace != null)
        {
            rasterAnalysisEnvironment.OutWorkspace=workspace;
        }
        // Set the new default output spatial reference.
        if (spatialReference != null)
        {
            rasterAnalysisEnvironment.OutSpatialReference=spatialReference;
        }
        // Set it as the default settings.
        rasterAnalysisEnvironment.SetAsNewDefaultEnvironment();
    }
    catch (Exception ex)
    {
        rasterAnalysisEnvironment=null;
    }
    return rasterAnalysisEnvironment;
}

[VB.NET]

Public Function SetNewDefaultEnvironment(ByVal envelope_Extent As IEnvelope, ByVal nCellSize As Double, ByVal geoDataset_Mask As IGeoDataset, ByVal workspace As IWorkspace, ByVal spatialReference As ISpatialReference) As IRasterAnalysisEnvironment
    ' Creates a new RasterAnalysis object and sets it as a new default setting.
    Try
    ' Create a RasterAnalysis object.
    Dim rasterAnalysisEnvironment As IRasterAnalysisEnvironment=New RasterAnalysisClass
    ' Set the new default extent.
    If Not envelope_Extent Is Nothing Then
        Dim extentProvider As Object=CType(envelope_Extent, Object)
        rasterAnalysisEnvironment.SetExtent(esriRasterEnvSettingEnum.esriRasterEnvValue, extentProvider)
    End If
    ' Set the new default cell size.
    If nCellSize > 0 Then
        Dim cellSizeProvider As Object=CType(nCellSize, Object)
        rasterAnalysisEnvironment.SetCellSize(esriRasterEnvSettingEnum.esriRasterEnvValue, cellSizeProvider)
    End If
    ' Set the new default mask for analysis.
    If Not geoDataset_Mask Is Nothing Then
        rasterAnalysisEnvironment.Mask=geoDataset_Mask
    End If
    ' Set the new default output workspace.
    If Not workspace Is Nothing Then
        rasterAnalysisEnvironment.OutWorkspace=workspace
    End If
    ' Set the new default output spatial reference.
    If Not spatialReference Is Nothing Then
        rasterAnalysisEnvironment.OutSpatialReference=spatialReference
    End If
    ' Set it as the default settings.
    rasterAnalysisEnvironment.SetAsNewDefaultEnvironment()
    ' Return reference to the default environment setting.
    SetNewDefaultEnvironment=rasterAnalysisEnvironment
    Exit Function
    Catch ex As Exception
    SetNewDefaultEnvironment=Nothing
    End Try
End Function

Each operator object can have its own analysis environment. This environment can be accessed through the IRasterAnalysisEnvironment interface. The methods on this interface allow direct control of the analysis environment on that object. When an operator object is created, the initial analysis environment properties are taken from the session's default analysis environment.

The following code example sets the necessary analysis environment properties for a new operator object. The code example defines an explicit workspace path, cell size, extent for RasterMakerOp, and uses the MakeConstant method:

[C#]

public void SetOpEnvironment()
{
    // Set tool level analysis environment.
    // Create an Op (RasterMaker operator).
    IRasterMakerOp rasterMakerOp=new RasterMakerOpClass();
    // Query Op for IRasterAnalysisEnvironment.
    IRasterAnalysisEnvironment rasterAnalysisEnvironment=
        (IRasterAnalysisEnvironment)rasterMakerOp;
    // Set output workspace for the Op.
    IWorkspaceFactory workspaceFactory=new RasterWorkspaceFactoryClass();
    IWorkspace workspace=workspaceFactory.OpenFromFile("c:\\temp", 0);
    rasterAnalysisEnvironment.OutWorkspace=workspace;
    // Set cell size for the Op.
    object object_cellSize=(System.Object)30;
    rasterAnalysisEnvironment.SetCellSize
        (esriRasterEnvSettingEnum.esriRasterEnvValue, ref object_cellSize);
    // Set output extent for the Op.
    IEnvelope envelope=new EnvelopeClass();
    envelope.XMin=0;
    envelope.YMin=0;
    envelope.XMax=3000;
    envelope.YMax=3000;
    object extentProvider=(System.Object)envelope;
    object object_Missing=System.Type.Missing;
    rasterAnalysisEnvironment.SetExtent(esriRasterEnvSettingEnum.esriRasterEnvValue,
        ref extentProvider, ref object_Missing);
    // Perform spatial operation.
    IRaster outRas=null;
    outRas=(IRaster)(rasterMakerOp.MakeConstant(10, true));
}

[VB.NET]

Public Sub SetOpEnvironment()
    ' Create an Op (RasterMaker operator).
    Dim rasterMakerOp As IRasterMakerOp=New RasterMakerOpClass
    ' Query Op for IRasterAnalysisEnvironment.
    Dim rasterAnalysisEnvironment As IRasterAnalysisEnvironment=CType(rasterMakerOp, IRasterAnalysisEnvironment)
    ' Set output workspace for the Op.
    Dim workspaceFactory As IWorkspaceFactory=New RasterWorkspaceFactoryClass
    Dim workspace As IWorkspace=workspaceFactory.OpenFromFile("c:\temp", 0)
    rasterAnalysisEnvironment.OutWorkspace=workspace
    ' Set cell size for the Op.
    rasterAnalysisEnvironment.SetCellSize(esriRasterEnvSettingEnum.esriRasterEnvValue, 30)
    ' Set output extent for the Op.
    Dim envelope As IEnvelope=New EnvelopeClass
    envelope.XMin=0
    envelope.YMin=0
    envelope.XMax=3000
    envelope.YMax=3000
    Dim extentProvider As System.Object=CType(envelope, System.Object)
    rasterAnalysisEnvironment.SetExtent(esriRasterEnvSettingEnum.esriRasterEnvValue, extentProvider)
    ' Perform spatial operation.
    Dim outRas As IRaster
    outRas=CType(rasterMakerOp.MakeConstant(10, True), IRaster)
End Sub

Development licensing	Deployment licensing
ArcGIS Desktop Basic	ArcGIS Desktop Basic
ArcGIS Desktop Standard	ArcGIS Desktop Standard
ArcGIS Desktop Advanced	ArcGIS Desktop Advanced