Add raster data

You can add raster data 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 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? and Imagery and raster in ArcGIS Pro in the ArcGIS Desktop help.

Raster data is represented by the Raster 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 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 MapView or SceneView for RasterLayers.

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.

Use dark colors for code blocksCopy
// create a raster from a raster file
String rasterFilePath = "/path/to/raster.format";
Raster raster = new Raster(rasterFilePath);

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 .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.

Use dark colors for code blocksCopy
// open a local GeoPackage (.gpkg)
GeoPackage geoPackage = new GeoPackage(pathToGeoPackage);
geoPackage.loadAsync();

// get the collection of rasters in the package
geoPackage.addDoneLoadingListener(() -> {
  if (geoPackage.getLoadStatus() == LoadStatus.LOADED) {
    List<GeoPackageRaster> geoPackageRasters = geoPackage.getGeoPackageRasters();

    // get the first raster in the collection
    GeoPackageRaster firstRaster = geoPackageRasters.get(0);

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

    // add as an operational layer
    mapView.getMap().getOperationalLayers().add(rasterLayer);
  }
});

Create a raster from a mobile mosaic dataset

Raster data stored in a mobile mosaic dataset 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.

Use dark colors for code blocksCopy
// create raster and raster layer
String rasterFilePath = "/path/to/raster.format";
Raster raster = new Raster(rasterFilePath);
RasterLayer rasterLayer = new RasterLayer(raster);


// add as a basemap
ArcGISMap map = new ArcGISMap(new Basemap(rasterLayer));


// Alternatively you can create a raster layer from a mosaic dataset
MosaicDatasetRaster mosaicDatasetRaster = new MosaicDatasetRaster("/path/to/mosaic.sqlite", "rasterName");
RasterLayer mosaicDatasetRasterLayer = new RasterLayer(mosaicDatasetRaster);


// add as an operational layer
map.getOperationalLayers().add(mosaicDatasetRasterLayer);

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.

Use dark colors for code blocksCopy
// create a new mobile mosaic dataset
MosaicDatasetRaster mosaicDatasetRaster = MosaicDatasetRaster
    .create(pathToMosaicDatabase, rasterName, SpatialReferences.getWebMercator());

// add some raster files to the mobile mosaic dataset
mosaicDatasetRaster.addDoneLoadingListener(() -> {
  if (mosaicDatasetRaster.getLoadStatus() == LoadStatus.LOADED) {
    AddRastersParameters parameters = new AddRastersParameters();
    parameters.setInputDirectory(pathToRasters);
    mosaicDatasetRaster.addRastersAsync(parameters);
  }
});

mosaicDatasetRaster.loadAsync();

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 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 ArcGIS Runtime 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, starting with 100.9.0, define rule settings to control how overlapping areas in the mosaic are handled. In addition to how it's displayed, the mosaic rule may effect 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 in ArcGIS Runtime. For more information on the metadata of an image service, see Image Service in the ArcGIS services reference.

Use dark colors for code blocksCopy
// Load the image service raster.
final ImageServiceRaster serviceRaster =
  new ImageServiceRaster("https://sampleserver7.arcgisonline.com/server/rest/services/amberg_germany/ImageServer");
serviceRaster.addDoneLoadingListener(() -> {
  if (serviceRaster.getLoadStatus() == LoadStatus.LOADED) {
    // Get service metadata.
    ArcGISImageServiceInfo serviceInfo = serviceRaster.getServiceInfo();
  }
});
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.

ArcGIS Runtime supports a subset of raster functions.

The code below gives an example of how to create a raster from a raster function.

Use dark colors for code blocksCopy
// create a raster function
RasterFunction rasterFunction = new RasterFunction("/path/to/raster/function.json");


// initialize the arguments of the raster function
RasterFunctionArguments rasterFunctionArguments = rasterFunction.getArguments();
List<String> rasterNames = rasterFunctionArguments.getRasterNames();
// assuming rasterNames has 2 entries, set the 2 rasters
rasterFunctionArguments.setRaster(rasterNames.get(0), new Raster("/path/to/raster/0"));
rasterFunctionArguments.setRaster(rasterNames.get(1), new Raster("/path/to/raster/1"));


// create a new raster based on the function
Raster raster = new Raster(rasterFunction);

Raster functions supported by ArcGIS Runtime

ArcGIS Runtime supports a subset of raster functions supported. 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:

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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

Use dark colors for code blocksCopy
{
  "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 RasterLayer class. RasterLayer can render raster data from any type of raster. See Layers for more information about creating and working with raster layers.

Use dark colors for code blocksCopy
// create a raster layer
RasterLayer rasterLayer = new RasterLayer(raster);
// add as a basemap
ArcGISMap map = new ArcGISMap(new Basemap(rasterLayer));

You can add a raster layer 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 added to the map.

Use dark colors for code blocksCopy
// Alternatively you can add as an operational layer
RasterLayer mosaicDatasetRasterLayer = new RasterLayer(mosaicDatasetRaster);
// add as an operational layer
map.getOperationalLayers().add(mosaicDatasetRasterLayer);

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.

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

ArcGIS Runtime API for Java

Add raster data

Was this page helpful?