Add raster data

You can add raster data stored on your desktop or device or from an image service to your ArcGIS Runtime map by:

Raster data provides a unique way of conceptualizing, analyzing, and visualizing geographic phenomena that is distinct from vector formats (using points, lines, and polygons to represent geographic features, in other words). For more information on raster data, including advantages and disadvantages of using it, see What is raster data? in ArcGIS Desktop help.

Raster data is represented by the Raster class. Your ArcGIS Runtime app can work with a range of raster data including raster files, 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, which asynchronously accesses raster data from remote services or datasets.

Create a raster from a raster file

To add raster files stored on your desktop or device to your app, create aRaster 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 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. Using ArcGIS Runtime SDK, you can read a local GeoPackage and load the feature tables and rasters it contains.

Open a GeoPackage using the path to the file (.gpkg). 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 mosaic dataset

Raster data stored in a local mosaic dataset should be read through MosaicDatasetRaster, which inherits from Raster. A MosaicDatasetRaster object is instantiated with a path of the local 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 new mobile mosaic dataset and add raster files to it

MosaicDatasetRaster can also be used to create a mobile mosaic dataset (SQLite database format) and save it to the device. Once the mobile mosaic dataset is created, individual raster files can be asynchronously added to it. The SQLite database is created when the MosaicDatasetRaster is loaded successfully.

Use the AddRastersParameters to set the input directory containing the raster files to be added. AddRastersParameters can also be used to 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 using ArcGIS Server. An image service provides access to raster data through a web service. A single raster dataset or a mosaic dataset which 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 ArcGIS Runtime app. You can create an ImageServiceRaster with the URL of an image service. And then if you want to display the raster data on a map, create a raster layer for it.

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. Once 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 info of predefined service rendering rules are exposed in ArcGIS Runtime. For more info on the metadata of an image service, see Image Service in the ArcGIS REST API help.

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


// 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;


    // Call a function to load the raster with one of the rules
    // (Note: the rendering rule cannot be set on an ImageServiceRaster that is already loaded)
    AddRasterWithRenderingRule(renderingRuleInfos[3]);
};


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

Rendering rules

A rendering rule defines how the requested image should be rendered or processed. ImageServiceRaster allows you to apply service-defined or client-defined rendering rules on an image service by setting its rendering rule property. You can create a RenderingRule from a RenderingRuleInfo object or a JSON string that specifies a service-defined or client-defined rendering rule and then set it on the image service raster. For the syntax of rendering rules, see raster function (JSON) objects in the ArcGIS REST API help.

private void AddRasterWithRenderingRule(RenderingRuleInfo ruleInfo)
{
    // Create an image service raster from a URI
    ImageServiceRaster serviceRaster = new ImageServiceRaster(new Uri("http://sampleserver6.arcgisonline.com/arcgis/rest/services/CharlotteLAS/ImageServer"));


    // Use RenderingRuleInfo to create a rendering rule
    RenderingRule renderingRule = new RenderingRule(ruleInfo);


    // Apply the rendering rule to the image service raster
    serviceRaster.RenderingRule = renderingRule;


    // Create a raster layer to display the raster
    RasterLayer layer = new RasterLayer(serviceRaster);


    // Dispatch to the UI thread to show the raster layer as a basemap
    Dispatcher.Invoke(() =>
    {
        MyMapView.Map = new Map(new Basemap(layer));
    });
}

Alternatively you can create a RenderingRule using a JSON string that specifies a service-defined or client-defined rendering rule.

// Use a JSON string to define the RenderingRule
RenderingRule renderingRule = new RenderingRule("{\"rasterFunction\" : \"Hillshade\",\"rasterFunctionArguments\" : {\"Azimuth\" : 215.0,\"Altitude\" : 75.0,\"ZFactor\" : 0.3},\"variableName\" : \"DEM\"}");

Create a raster from a raster function

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.

ArcGIS Runtime supports a subset of raster functions that the ArcGIS REST API supports.

The following example uses a raster function (stored in a local JSON file).

// Create a new hillshade raster function from a JSON definition (stored in a text file)
var hillshadeFunction = new RasterFunction(@"C:\Data\RasterFunctions\hillshade.json");


// 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(@"C:\Data\Rasters\SRTMCalifornia.tif");
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));

Raster functions supported by ArcGIS Runtime

ArcGIS Runtime supports a subset of raster functions supported by the ArcGIS REST API. The raster functions supported by ArcGIS Runtime are provided in this section, along with the syntax for using them. The syntax is close to the ArcGIS REST syntax for the same functions but is not exactly the same.

The general syntax for ArcGIS Runtime 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_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"
  },
  "raster_function":{"type":"Clip_function"},
  "type":"Raster_function_template"
}

Colormap

{
  "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"
  },
  "raster_function":{"type":"Colormap_function"},
  "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_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"
  },
  "raster_function":{"type":"Extract_band_function"},
  "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_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"
  },
  "raster_function":{"type":"Raster_calculator_function"},
  "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"
}

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 as a RasterLayer. A RasterLayer can render raster data from any type of Raster.

You can add it to a map as either a basemap or an operational layer. When adding a raster layer as an operational layer to a map with different spatial reference, the layer will be reprojected on the fly and be added to the map.

You can also change the renderer, as described below, to control how the data is visualized on the map.

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

Change the renderer

When a raster layer is created from a raster, a default renderer is used to display the data on a map. As with other layer types supported by ArcGIS Runtime, a raster layer allows you to change how it is symbolized by creating a raster renderer (RasterRenderer) and applying it to the layer. When you change the renderer of a raster layer, only the display properties of the layer are updated. The underlying raster data won’t be affected.

double[] minVals = { 0 };
double[] maxVals = { 100 };
MinMaxStretchParameters minMaxParams = new MinMaxStretchParameters(minVals, maxVals);
ColorRamp elevationColorRamp = ColorRamp.Create(PresetColorRampType.Elevation);
var rendrr = new StretchRenderer(minMaxParams, null, true, elevationColorRamp);
inRasterLayer.Renderer = rendrr;

RasterRenderer is the base class inherited by all renderers available to display a raster layer and allows you to control how raster data are presented (visualized). Each of the following renderers are types of RasterRenderer and can be used to display your raster layer in different ways.

  • HillshadeRenderer—Creates a grayscale 3D representation of an elevation surface, with the sun's (hypothetical) position taken into account for shading the image. It can be applied to a raster layer created with single-band raster data.
  • BlendRenderer—Blends a hillshade image (derived from the raster) with the original raster. This provides a look similar to the original raster but with some terrain shading, for a rich, textured look.
  • ColormapRenderer—Provides a discrete mapping of raster pixel values to colors. All pixels matching the specified value are rendered using the mapped color. This can be useful for tasks such as land classification.
  • StretchRenderer—Displays continuous raster cell values across a gradual ramp of colors. Use the stretch renderer to draw a single band of continuous data. The stretch renderer works well when you have a large range of values to display, such as in imagery, aerial photographs, or elevation models.
  • RGBRenderer—Uses the same methods as the stretch renderer but allows you to combine bands as red, green, and blue composites.

Blend renderer showing elevation with hillshade

Supported raster formats

ArcGIS Runtime supports a subset of raster file formats that ArcGIS Desktop supports. The raster file formats ArcGIS Runtime supports include the following:

  • ASRP/USRP
  • CIB1, 5, 10
  • CRF
  • DTED0, 1, 2
  • GeoTIFF
  • HFA
  • HRE
  • IMG
  • JPEG
  • JPEG 2000
  • NITF
  • PNG
  • RPF
  • SRTM1, 2
  • Mobile mosaic datasets

Not all RPF products/formats are listed here, but they're generally supported. For descriptions of RPF formats supported by the U.S. military, see the MIL-STD-2411 publication for details.

Note:

You can create a mobile mosaic dataset by using the Mosaic Dataset to Mobile Mosaic Dataset geoprocessing tool in ArcGIS Pro.

About raster data

A raster consists of a matrix of cells (pixels) organized into rows and columns (a grid, in other words) where each cell contains a value representing information. Rasters are things like digital aerial photographs, imagery from satellites, digital pictures, elevation models, output from spatial analysis, and so on. Rasters used as GIS data are generally categorized into two broad types: thematic, representing discrete features on the ground in much the same way a polygon data set might (zoning or land use, for example) and continuous, modeling a phenomenon that changes continuously across a surface (temperature or elevation, for example). Photographs and scanned images are another type of raster data that you might use in your mapping app, perhaps for visualizing an area or as additional information associated with features in your map.

Raster data set examples