Add raster data

You can add rasters to your map. A raster consists of 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 are digital aerial photographs, imagery from satellites, digital pictures, or even scanned maps. For more information on rasters, see What is raster data? in the ArcGIS help.

To add raster files stored on your device into an ArcGIS Runtime map, create a FileRasterSource, instantiate a RasterLayer from the FileRasterSource, and then add that layer to your map as follows.

JMap map = new JMap();
String rasterPath = "c:/path/to/raster.tif";
FileRasterSource rasterSource;
try {  
  rasterSource = new FileRasterSource(rasterPath);
  RasterLayer rasterLayer = new RasterLayer(rasterSource);
} catch (IllegalArgumentException iex) {
  // handle exception
} catch (FileNotFoundException fe) {
  // handle exception
} catch (RuntimeException re) {
  // handle exception

FileRasterSource is an object that represents the raw raster file on disk. RasterLayer is the object that can be added to the map to allow the raw raster file to be rendered.

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

Set a spatial reference

Like other layers, when a RasterLayer is added to an empty map, it becomes the basemap of that map, and the spatial reference of the map is set to equal that of the RasterLayer.

You can also add a RasterLayer as an operational layer to a map whose spatial reference is the same as the layer's. However, when adding a RasterLayer as an operational layer to a map with a different spatial reference, the layer can't be reprojected on the fly (can't be added to the map successfully). To address this, reproject your FileRasterSource as shown in the following code snippet.

JMap map = new JMap();
// e.g. add a tiled layer as a basemap, this will set the map's spatial reference
map.getLayers().add(new ArcGISTiledMapServiceLayer(URL_MAP_SERVICE));
// the spatial reference of the map is set once the 'mapReady' event has fired
FileRasterSource rasterSource = new FileRasterSource("c:/path/to/raster.tif");
// project the raster source to your map's spatial reference
RasterLayer rasterLayer = new RasterLayer(rasterSource);
// the raster layer will be projected to the map's spatial reference when displayed

On-the-fly reprojection might add to rendering time.

Change the renderer

When a RasterLayer is created from a FileRasterSource, a default renderer is applied to the layer based on its properties so that it can be visualized on a map. As with other layer types supported by ArcGIS Runtime, RasterLayer allows you to change its renderer by creating a RasterRenderer and applying it to the layer. When you change the renderer of a RasterLayer, only the visual aspect of the layer will be changed on the fly. The raster data won’t be affected.

An example of setting a StretchRenderer with a Minimum-Maximum stretch type on a RasterLayer.

RasterLayer rasterLayer = ...;
StretchParameters stretchParams = = new MinMaxStretchParameters();
StretchRenderer renderer = new StretchRenderer();


RasterRenderer is the interface that all the renderers that can be applied to a RasterLayer must implement. It allows the raster layer in the map to change how the data is displayed. You can specify that you want to use one of the renderers described below.

  • BlendRenderer—Allows you to specify elevation data for a raster you're displaying and allows a hillshade to be computed and blended 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.
  • HillshadeRenderer—Creates a grayscale 3D representation of the surface, with the sun's relative position taken into account for shading the image. It can be applied to a RasterLayer created with single-band raster data.
  • StretchRenderer—Displays continuous raster cell values across a gradual ramp of colors. Use the StretchRenderer to draw a single band of continuous data. The StretchRenderer 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 StretchedRenderer but allows you to combine bands as red, green, and blue composites.

Supported rasters

Supported raster file formats include the following:

  • DTED0, 1, 2
  • GeoPackage
  • GeoTIFF
  • HFA
  • HRE
  • IMG
  • JPEG
  • JPEG 2000
  • NITF
  • PNG
  • RPF
  • SRTM1, 2

Not all RPF products/formats are listed here, but they're generally supported. See the MIL-STD-2411 publication for details.


Rasters stored in geodatabases (personal, file, or enterprise) are not supported.

For a list of raster file formats supported by Local Server, see Supported raster dataset file formats.