ArcGIS Runtime SDK for macOS

Add raster data

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

Note:

Options for customizing raster layer display are described in the Symbolize data topic.

Raster data provides a unique way of analyzing and visualizing geographic phenomena. Rasters 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 What is raster data? in ArcGIS Desktop help.

Raster data are represented by the AGSRaster class. Your ArcGIS Runtime app can work with many sources 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 AGSRaster 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 an AGSRaster object using the path of the raster file.

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.

Create a raster from a mobile mosaic dataset

Raster data stored in a mobile mosaic dataset should be read through the AGSMosaicDatasetRaster, which inherits from AGSRaster. The AGSMosaicDatasetRaster object is instantiated with a path of the mobile geodatabase and a name of the dataset.

Note:

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

Create a new mobile mosaic dataset and add raster files

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

Use the AGSAddRastersParameters class to set the input directory containing the raster files to be added and 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 AGSImageServiceRaster class to work with image services in your ArcGIS Runtime app. You can create an AGSImageServiceRaster 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.

AGSImageServiceRaster is a subclass of AGSRaster, so any operation that can be applied to the AGSRaster class, such as raster functions, can also be applied to AGSImageServiceRaster. Besides the common properties inherited from the AGSRaster class, AGSImageServiceRaster 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 AGSArcGISImageServiceInfo. 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 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.

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

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 using the AGSRasterLayer class. AGSRasterLayer can render raster data from any type of AGSRaster.

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.

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
  • CRF
  • DTED0, 1, 2
  • GeoTIFF
  • HFA
  • HRE
  • IMG
  • JPEG
  • JPEG 2000
  • MrSID, generations 2, 3, and 4
  • NITF
  • PNG
  • RPF (CIB)
  • RPF (CADRG)
  • SRTM1, 2
  • Mobile mosaic datasets