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 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.
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
val rasterFilePath = getExternalFilesDir(null)?.path.toString() + File.separator + rasterFileName
val raster = Raster.createWithPath(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. 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 Geo
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 path to a supported raster format.
val geoPackagePath =
getExternalFilesDir(null)?.path.toString() + File.separator + getString(R.string.app_name) + File.separator + localGeoPackageName
// open the GeoPackage
val geoPackage = GeoPackage(geoPackagePath)
lifecycleScope.launch {
geoPackage.load().onSuccess {
val geoPackageRasters = geoPackage.geoPackageRasters
if (geoPackageRasters.isNotEmpty()) {
// Read raster images and get the first one.
val geoPackageRaster = geoPackageRasters[0]
// Create a layer to display the raster.
val rasterLayer = RasterLayer(geoPackageRaster)
// Add the raster layer to the mutable map's operational layers used by the MapView composable.
map.operationalLayers.add(rasterLayer)
}
}.onFailure { Log.e(localClassName, "Geopackage failed to load.") }
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.
// Get mosaic dataset names in the SQLite database.
val sqliteDbPath = getExternalFilesDir(null)?.path.toString() + File.separator + sqliteDbName
val rasterNames = MosaicDatasetRaster.getNames(sqliteDbPath)
// check that the rasterNames list is not empty
if (rasterNames.isNotEmpty()) {
// Get the first raster name in the list rasterNames.
val rasterName = rasterNames[0]
// Create a raster from a mosaic dataset.
val raster = MosaicDatasetRaster(sqliteDbPath, rasterName)
// Create a raster layer using the raster.
val rasterLayer = RasterLayer(raster)
// Load the raster layer
lifecycleScope.launch {
rasterLayer.load().onSuccess {
val extent = rasterLayer.fullExtent ?: return@launch showError("Error retrieving extent of the raster layer.")
// use MapViewProxy operation to set the viewpoint
mapViewProxy.setViewpoint(Viewpoint(extent))
}.onFailure { showError("Raster layer failed to load.") }
}
// add the raster layer to the mutable map's operational layers
map.operationalLayers.add(rasterLayer)
}
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 raster from a path to a supported raster format
val mosaicSqlitePath = getExternalFilesDir(null)?.path.toString() + File.separator + getString(R.string.app_name) + File.separator + "mosaic.sqlite"
val mosaicDatasetRaster = MosaicDatasetRaster.create(mosaicSqlitePath, "Shashta", SpatialReference.webMercator())
val pathToIncomingDataRasters = getExternalFilesDir(null)?.path.toString() + File.separator + getString(R.string.app_name) + File.separator + "raster-file"
// Load the mosaic dataset raster
lifecycleScope.launch {
mosaicDatasetRaster.load().onSuccess {
Log.i(localClassName, "Mobile mosaic dataset loaded successfully")
val addRastersParameters = AddRastersParameters.create().apply {
inputDirectory = pathToIncomingDataRasters
}
mosaicDatasetRaster.addRasters(addRastersParameters).onSuccess {
// Create a raster layer with the mosaic dataset raster
val mosaicDatasetRasterLayer = RasterLayer(mosaicDatasetRaster)
mosaicDatasetRasterLayer.load().onSuccess {
// add the raster layer to the mutable map's operational layers
map.operationalLayers.add(mosaicDatasetRasterLayer)
// use MapViewProxy operation to set the viewpoint
mapViewProxy.setViewpoint(Viewpoint(40.750306470878606, -122.1600, 72000.0))
}.onFailure { Log.e(localClassName, "Mosaic dataset raster layer failed to load.") }
}
}.onFailure { Log.e(localClassName, "Mobile mosaic dataset failed to load.") }
}
Use the Add
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 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 ArcGIS
. 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
val imageServiceURL = "https://sampleserver7.arcgisonline.com/server/rest/services/amberg_germany/ImageServer"
val imageServiceRaster = ImageServiceRaster(imageServiceURL)
// When the image service raster loads, the service info and rendering rule info will be available
lifecycleScope.launch {
// Load the service raster so you can get its list of rendering rule infos
imageServiceRaster.load().onSuccess {
// Get service info.
val serviceInfo = imageServiceRaster.serviceInfo
showError("imageServiceRaster.serviceInfo is: ${imageServiceRaster.serviceInfo}")
// If using rendering rules: Access the list of available rendering rule info instances.
serviceInfo?.renderingRuleInfos?.forEachIndexed { index, renderingRuleInfo ->
var message ="renderingRuleInfos[$index].name is ${renderingRuleInfo.name}, and its "
message += "description is: ${renderingRuleInfo.description}"
showMessage(message)
}
// If using rendering rules: After you load an image service raster, you can access the list of
// available rendering rules, but you cannot assign a rule to the loaded raster. To assign
// one of the available rendering rules, create a new ImageServiceRaster instance and assign
// the rule to the renderingRule property of the instance. Then create a raster layer from
// that new image service raster.
// Load the image service raster you just created
val rasterLayer = RasterLayer(imageServiceRaster)
// To add the raster layer to the map, call operationalLayers() on the
// mutable map property used by the MapView composable.
map.operationalLayers.add(rasterLayer)
val viewpoint = Viewpoint(49.443589, 11.859372, 30000.0)
// use MapViewProxy operation to set the viewpoint
mapViewProxy.setViewpoint(viewpoint)
}.onFailure { showError("serviceRaster failed to load.") } }
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 raster function from json string.
// If RasterFunction.fromJson() returns null, then return from current function, showing error message.
val hillsideRasterFunctionFromJson = RasterFunction.fromJsonOrNull(getString(R.string.hillshade_simplified))
?: return showError("Error creating raster function from Json file.")
// Get parameter name value pairs used by hillside.
val hillsideRasterFunctionArguments = hillsideRasterFunctionFromJson.arguments
// Get a list of raster names associated with the raster function.
val rasterNames = hillsideRasterFunctionArguments?.rasterNames
// Set an existing raster as an argument to the raster function. This is the raster that will be
// modified by the function.
hillsideRasterFunctionArguments?.setRaster(rasterNames?.get(0).toString(), raster)
// Create a Raster object for the modified raster returned by the raster function.
// Then create a raster layer from it.
val modifiedRaster = Raster.createWithRasterFunction(hillsideRasterFunctionFromJson)
val hillshadeRasterLayer = RasterLayer(modifiedRaster)
// add the layer to the mutable map's operational layers
map.operationalLayers.add(hillshadeRasterLayer)
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"
}
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.
// create a raster layer using the raster
val rasterLayer = RasterLayer(raster)
lifecycleScope.launch {
rasterLayer.load().onSuccess {
// Create a basemap with the raster layer, and create a new map with that basemap.
// Display the map by assigning it to the mutable map property used by the Composable MapView.
map = ArcGISMap(Basemap(rasterLayer))
// Alternatively, you could add the raster layer as an operational layer.
// map.operationalLayers.add(rasterLayer)
}.onFailure { Log.e(localClassName, "Raster layer failed to load.") }
}
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.
Supported raster formats
This API supportes a subset of raster file formats that ArcGIS Desktop 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
- RPF (CIB)
- RPF (CADRG)
- SRTM1, 2
- Mobile mosaic datasets