Add raster data | ArcGIS Maps SDK for .NET

You can add raster data A raster is a matrix of cells (or pixels) organized into rows and columns (or a grid) where each cell contains a value representing information, such as temperature. Rasters include digital aerial photographs, imagery from satellites, digital pictures, and scanned maps. Learn more stored on your device or raster data from an image service by performing one of the following tasks:

Adding a raster to a map or scene using a raster layer if you want to display the raster
Adding a raster to a map or scene for use with a raster function

Raster data provides a unique way to analyze and visualize geographic phenomena. Rasters A raster is a matrix of cells (or pixels) organized into rows and columns (or a grid) where each cell contains a value representing information, such as temperature. Rasters include digital aerial photographs, imagery from satellites, digital pictures, and scanned maps. Learn more consist of a matrix of cells, with each cell containing a value. Rasters can have multiple dimensions or bands, for example, the red, green, and blue channels in an aerial photo. Rasters are different from vectors, which use points, lines, and polygons to represent features. For more information on raster data, including advantages and disadvantages of using it, see ArcGIS Pro help topic Introduction to image and raster data.

Raster data is represented by the Raster class. Your app can work with many sources of raster data, including raster files A raster file is georeferenced bitmap data. It can be a single, standalone file or a collection of files that work together. Raster files are typically used in offline applications. Learn more , mosaic datasets, raster data shared through image services, or the results of raster functions. A raster function can take any of these rasters as input for analysis.

The Raster object implements the loadable pattern described in Loading resources asynchronously and asynchronously accesses raster data from remote services or datasets.

Raster data supports the identify operation to obtain RasterCell values when a user clicks on a pixel in a RasterLayer in a MapView or SceneView.

Attention

For some rasters, additional files are needed in order to resolve the spatial reference described in the raster metadata. The spatial reference is needed in order to correctly georeference the raster data on a map, or to reproject the raster data when being used in a RasterLayer or used in analysis. If the raster data has an unknown spatial reference or it’s spatial reference is invalid, it cannot be reprojected on-the-fly which might cause unexpected results. A raster layer with an unknown spatial reference can only be displayed if it is added to a map that does not have a defined spatial reference; in that case, it is displayed at the origin of the map (0,0).

It is highly recommended to download these files, which are included in the Projection Engine data download, if you work with raster data in your app. Learn more about these files in the GDAL support files topic.

Create a raster from a raster file

To add raster files stored on your desktop or device to your app, create a Raster object using the path of the raster file.

// create a raster from a path to a supported raster format
Raster myRaster = new Raster(pathToRaster);

// create a RasterLayer using the Raster
RasterLayer newRasterLayer = new RasterLayer(myRaster);

Load a raster from a GeoPackage

A GeoPackage A geopackage is an OGC spatial data storage format that can contain multiple datasets of geographic features, non-spatial tabular data, and raster data. Learn more is an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. It is a platform-independent SQLite database file that contains data and metadata tables. For details, refer to the OGC GeoPackage specification. You can read a local GeoPackage and load the feature tables and rasters that it contains.

Open a GeoPackage using the path to the .gpkg file. The GeoPackageRasters property returns a collection of all rasters in the package. You can work with a GeoPackageRaster as you would any other Raster, including adding it as a RasterLayer to your app’s map.

// Open a local GeoPackage (.gpkg)
GeoPackage myGeoPackage = await GeoPackage.OpenAsync(geoPackageFilePath);

// Get the collection of rasters in the package
IReadOnlyList<GeoPackageRaster> packageRasters = myGeoPackage.GeoPackageRasters;

// Get the first raster in the collection
GeoPackageRaster firstRaster = packageRasters[0];

// Create a RasterLayer using the GeoPackageRaster (which inherits from Raster)
RasterLayer newRasterLayer = new RasterLayer(firstRaster);

Create a raster from a mobile mosaic dataset

Raster data stored in a mobile mosaic dataset A mobile mosaic dataset is a SQLite database that allows developers to store, manage, view, and query small to vast collections of raster and image data. Learn more should be read through the MosaicDatasetRaster, which inherits from Raster. The MosaicDatasetRaster object is instantiated with a path of the mobile geodatabase and a name of the dataset.

// Get mosaic dataset names in the SQLite database.
var names = MosaicDatasetRaster.GetNames(sqliteDbPath);
var rasterName = names[0];

// Create a raster from a mosaic dataset
MosaicDatasetRaster raster = new MosaicDatasetRaster(sqliteDbPath, rasterName);

// Create a RasterLayer to display the Raster
RasterLayer rasterLayer = new RasterLayer(raster);

Create a mobile mosaic dataset and add raster files

MosaicDatasetRaster can also be used to create a mobile mosaic dataset in a new mobile geodatabase and save it to the device. After the mobile mosaic dataset is created, individual raster files can be asynchronously added to it. The mobile geodatabase is created when the MosaicDatasetRaster is loaded successfully.

// Create a new mobile mosaic dataset.
MosaicDatasetRaster rasterMosaic = MosaicDatasetRaster.Create(@"C:\Data\mosaic.sqlite", "Shasta", SpatialReferences.WebMercator);

// Load the mosaic dataset and add some raster files.
rasterMosaic.LoadAsync();
AddRastersParameters parameters = new AddRastersParameters
{
    InputDirectory = @"..\incoming\data\rasters"
};
rasterMosaic.AddRastersAsync(parameters);

Use the AddRastersParameters class to perform tasks, such as the following:

Set the input directory containing the raster files to be added
Control other properties of the mosaic, such as minimum and maximum pixel sizes

Create a raster from an image service

Raster and image data can be shared as an image service An image service is a data service that can store, process, analyze, and share raster data. Learn more using ArcGIS Server. An image service provides access to raster data through a web service. A single raster dataset or a mosaic dataset that contains a collection of raster datasets can be served as one image service. The mosaic dataset can dynamically process and mosaic the images on the fly. An image service supports accessing both the mosaicked image and its catalog, as well as individual rasters in the catalog. For more information on image services, see Key concepts for image services in the ArcGIS help.

Use the ImageServiceRaster class to work with image services in your app. You can create an ImageServiceRaster with the URL of an image service. And if you want to display the raster data on a map, create a raster layer for it.

For mosaicked images, a mosaic rule defines how the individual rasters are combined. You can use the default rule defined with the service or define rule settings to control how overlapping areas in the mosaic are handled. In addition to how it’s displayed, the mosaic rule may affect values returned when identifying, computing a histogram, or exporting the image.

ImageServiceRaster is a subclass of Raster, so any operation that can be applied to the Raster class, such as raster functions, can also be applied to ImageServiceRaster. Besides the common properties inherited from the Raster class, ImageServiceRaster has additional properties and capabilities, such as the image service metadata and rendering rules. After the image service raster has been loaded, the metadata of the image service can be retrieved through the service info property, which is represented by ArcGISImageServiceInfo. However, only a subset of the metadata, including attribution text and a list of information on predefined service rendering rules, is exposed by this API. For more information on the metadata of an image service, see Image Service in the ArcGIS services reference.

// Create an image service raster from a URI
var imageServerUri = new Uri("http://sampleserver6.arcgisonline.com/arcgis/rest/services/CharlotteLAS/ImageServer");
ImageServiceRaster serviceRaster = new ImageServiceRaster(imageServerUri);

// When the image service raster loads, the service info and rendering rule info will be available
serviceRaster.Loaded += (s, e) =>
{
    // Get service info
    ArcGISImageServiceInfo serviceInfo = serviceRaster.ServiceInfo;

    // Get rendering rule info list
    IReadOnlyList<RenderingRuleInfo> renderingRuleInfos = serviceInfo.RenderingRuleInfos;

    // Load the raster with one of the rules
    // (Note: the rendering rule cannot be set on an ImageServiceRaster that is already loaded)
    RenderingRule myRenderingRule = new RenderingRule(renderingRuleInfos[3]);

    // Create a new image service raster
    ImageServiceRaster myImageServiceRaster = new ImageServiceRaster(imageServerUri)
    {
        // Set the image service raster's rendering rule to the rendering rule created earlier
        RenderingRule = myRenderingRule
    };

    // Call a function to create and add a raster layer to the map
    _ = AddRasterLayer(myImageServiceRaster);
};

// Load the image service raster
serviceRaster.LoadAsync();

Create a raster from a raster function

Raster functions can be applied to a raster to process that data. This processing is not permanently applied to the data; instead, it is applied on the fly as the rasters are accessed.

A subset of raster functions is supported.

// Create a new hillshade raster function from a JSON definition (stored in a text file).
var hillshadeFunction = new RasterFunction(pathToHillshadeFunctionJSON);

// Get the function's arguments.
RasterFunctionArguments rasterFunctionArguments = hillshadeFunction.Arguments;

// Assuming rasterNames has 1 entry, set the input raster.
IReadOnlyList<string> rasterNames = rasterFunctionArguments.GetRasterNames();
var inputRaster = new Raster(pathToInputTIF);
rasterFunctionArguments.SetRaster(rasterNames[0], inputRaster);

// Create a new raster based on the function.
Raster raster = new Raster(hillshadeFunction);

// Create a RasterLayer to display the Raster, add it to the map.
RasterLayer rasterLayer = new RasterLayer(raster);
MyMapView.Map = new Map(new Basemap(rasterLayer));

Supported Raster functions

The supported raster functions are detailed in this section, along with the syntax for using them. Note that the syntax is similar to the ArcGIS REST syntax for the same functions but is not exactly the same.

The general syntax for raster functions is the following:

{
  "raster_function":{"type":"<Raster Function Name>"},
  "raster_function_arguments":
  {
    "argument1":"<JSON Value Object>",
    "argument2":"<JSON Value Object>",
    "argumentN":"<JSON Value Object>",
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Clip

{
  "raster_function":{"type":"Clip_function"},
  "raster_function_arguments":
  {
    "minx":{"double":value,"type":"Raster_function_variable"},
    "miny":{"double":value,"type":"Raster_function_variable"},
    "maxx":{"double":value,"type":"Raster_function_variable"},
    "maxy":{"double":value,"type":"Raster_function_variable"},
    "dx":{"double":cell_size_x,"type":"Raster_function_variable"},
    "dy":{"double":cell_size_y,"type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Colormap

{
  "raster_function":{"type":"Colormap_function"},
  "raster_function_arguments":
  {
    "raster_colormap":{"colors":[color1,color2,...,colorN],"type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Colormap_to_RGB

{
  "raster_function":{"type":"Colormap_to_RGB_function"},
  "raster_function_arguments":
  {
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Color_ramp

{
  "raster_function":{"type":"Color_ramp_function"},
  "raster_function_arguments":
  {
    "resizable":{"bool":false,"type":"Raster_function_variable"},
    "color_ramp":
    {
      "color_ramp":
      {
        "ramps":
        [
         {"to_color":[0,255,0],"from_color":[0,191,191],"num_colors":3932,"type":"Algorithmic_color_ramp","algorithmic_type":"hsv"},
         {"to_color":[255,255,0],"from_color":[0,255,0],"num_colors":3932,"type":"Algorithmic_color_ramp","algorithmic_type":"hsv"},
         {"to_color":[255,127,0],"from_color":[255,255,0],"num_colors":3932,"type":"Algorithmic_color_ramp","algorithmic_type":"hsv"},
         {"to_color":[191,127,63],"from_color":[255,127,0],"num_colors":3932,"type":"Algorithmic_color_ramp","algorithmic_type":"hsv"},
         {"to_color":[20,20,20],"from_color":[191,127,63],"num_colors":3935,"type":"Algorithmic_color_ramp","algorithmic_type":"hsv"}
        ],
        "type":"Multipart_color_ramp"
      },
      "type":"Raster_function_variable"
    },
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Composite_band

{
  "raster_function":{"type":"Composite_band_function"},
  "raster_function_arguments":
  {
    "raster_names":{"name":"raster_names","string_array":["r1","r2","r3","r4"],"type":"Raster_function_variable"},
    "r1":{"name":"r1","is_raster":true,"type":"Raster_function_variable"},
    "r2":{"name":"r2","is_raster":true,"type":"Raster_function_variable"},
    "r3":{"name":"r3","is_raster":true,"type":"Raster_function_variable"},
    "r4":{"name":"r4","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Extract_band

{
  "raster_function":{"type":"Extract_band_function"},
  "raster_function_arguments":
  {
    "exact_match":{"bool":false,"type":"Raster_function_variable"},
    "band_indexes":{"int_array":[2,1,0],"type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Geometric

{
  "raster_function":{"type":"Geometric_function"},
  "raster_function_arguments":
  {
    "raster_transform":{"raster_transform":"Raster Transform JSON object","type":"Raster_function_variable"},
    "z_offset":{"double":0,"type":"Raster_function_variable"},
    "z_factor":{"double":1,"type":"Raster_function_variable"},
    "raster":{"is_raster":true,"name":"raster","type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Hillshade

{
  "raster_function":{"type":"Hillshade_function"},
  "raster_function_arguments":
  {
    "z_factor":{"double":0.0002,"type":"Raster_function_variable"},
    "slope_type":{"raster_slope_type":"none","type":"Raster_function_variable"},
    "azimuth":{"double":315,"type":"Raster_function_variable"},
    "altitude":{"double":45,"type":"Raster_function_variable"},
    "nbits":{"int":8,"type":"Raster_function_variable"}, // Number of bits per pixel for output raster
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Mask

{
  "raster_function":{"type":"Mask_function"},
  "raster_function_arguments":
  {
    "nodata_values":{"double_array":[value1, value2, ..., valueN],"type":"Raster_function_variable"},
    "nodata_interpretation":{"nodata_interpretation":"all","type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Pansharpen

{
  "raster_function":{"type":"Pansharpen_function"},
  "raster_function_arguments":
  {
    "weights":{"double_array":[0.10000000000000001,0.5,0.40000000000000002,0.29999999999999999],"type":"Raster_function_variable"},
    "pansharpen_type":{"pansharpen_type":"gram_schmidt","type":"Raster_function_variable"},
    "pan_raster":{"name":"pan_raster","is_raster":true,"type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Raster_calculator

{
  "raster_function":{"type":"Raster_calculator_function"},
  "raster_function_arguments":
  {
    "expression":{"string":"r1 + r2","name":"expression","type":"Raster_function_variable"},
    "raster_names":{"name":"raster_names","type":"Raster_function_variable"},
    "raster_names":{"name":"raster_names","string_array":["r1","r2"],"type":"Raster_function_variable"},
    "r1":{"name":"r1","is_raster":true,"type":"Raster_function_variable"},
    "r2":{"name":"r2","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Stretch

{
  "raster_function":{"type":"Stretch_function"},
  "raster_function_arguments":
  {
    "stretch_type":{"raster_stretch_type":"minimum_maximum","type":"Raster_function_variable"},
    "min_values":{"double_array":[-10977],"type":"Raster_function_variable"},
    "max_values":{"double_array":[8685],"type":"Raster_function_variable"},
    "estimate_stats":{"bool":false,"type":"Raster_function_variable"},
    "raster":{"name":"raster","is_raster":true,"type":"Raster_function_variable"},
    "type":"Raster_function_arguments"
  },
  "type":"Raster_function_template"
}

Use raster info to access cell size

After a Raster has loaded, you can retrieve its RasterInfo to access source metadata such as cell size, extent, and spatial reference.

This information is useful when you need to work with source resolution, for example, to calculate a map scale for zooming to native raster resolution, or to set meaningful min and max map scales.

If raster info is not available for a raster source, RasterInfo will be null.

Add a raster using a raster layer

It’s not necessary to display the raster data you work with in your app. However, if you want your users to view raster data on a map, add the raster using the RasterLayer class. RasterLayer can render raster data from any type of raster.

// Create a raster layer to display a raster dataset.
var rasterLayer = new RasterLayer(raster);

// Create  a basemap with the layer.
var basemap = new Basemap(rasterLayer);

// Create a new map that uses the basemap.
var map = new Map(basemap);

// Alternatively, you could add the raster layer as an operational layer.
MainMapView.Map.OperationalLayers.Add(rasterLayer);

You can add a raster layer A raster layer is a layer type that allows developers to display raster data in their applications. Learn more to a map as either a basemap or an operational layer. When adding a raster layer as an operational layer to a map with a different spatial reference, the layer will be reprojected on the fly and added to the map.

You can also change the renderer to control how the data is visualized on the map.

See Layers for more information about creating and working with raster layers.

Set the resampling method on the layer

You can specify the resampling method to use when rendering the raster layer by setting the RasterResamplingType property. This controls how raster cell values are calculated when the layer is rendered at a different resolution than the raster’s native cell size, or when the raster is transformed (for example, scaled or reprojected).

By default, this property is set to Automatic, which indicates that if the raster data type can be determined from its raster properties, the resampling method will be automatically set accordingly. For example, discrete data will use nearestNeighbor, which preserves data values, and continuous data will use bilinearInterpolation, which transforms cell values for smoother visual transitions. If the type of data cannot be determined, bilinearInterpolation will be applied by default for ImageServiceRaster and MosaicDatasetRaster, and nearestNeighbor will be applied by default for all other types.

Set this property to a specific method (for example, bilinearInterpolation) to explicitly override the resampling method for the layer.

Supported raster formats

This API supports a subset of raster file formats that ArcGIS Pro supports. The supported raster file formats include:

ASRP/USRP
CRF
DTED0, 1, 2
GeoTIFF
HFA
HRE
IMG
JPEG
JPEG 2000
MrSID, generations 2, 3, and 4
NITF
PNG
Geospatial PDF
RPF (CIB)
RPF (CADRG)
SRTM1, 2
Mobile mosaic datasets