Back to Top

Raster

In this topic

  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample

Summary

Creates a raster object that can be used in Python or in a Map algebra expression. A raster object is a variable that references a raster dataset.

A raster object can be created by supplying the path to an existing raster on disk, by supplying a RasterInfo object, or it can be the result of any map algebra statement that results in a raster output.

License:

Either an ArcGIS Spatial Analyst extension or an ArcGIS Image Analyst extension is necessary to run map algebra statements.

Discussion

The raster object created from existing data can be used in subsequent map algebra expressions and will have all the associated raster properties and methods.

# out_raster is a resultant raster object
out_raster = Raster("c:/data/inraster")

Any tool or operator (see Work with operators in map algebra) that produces an output raster to the left of the equal sign creates a raster object. For example, in the following expression, out_raster is a raster object.

out_raster = Slope("inelevation")

When a Raster object is returned from a map algebra expression, the object (the variable and associated dataset) is temporary by default.

The temporary dataset associated with a raster object can become permanent by calling the raster object's save method.

If the referenced raster is not made permanent, the variable and the referenced raster dataset will be deleted when the variable is out of scope, such as when a stand-alone script completes or ArcGIS is closed. When a raster object references permanent data on disk, the data is not deleted.

Certain operators exist in both map algebra and in Python. If you want an operator to work on a raster (as opposed to a scalar), the input rasters must be cast as a raster object by calling the Raster class constructor Raster("inRaster").

# The plus operator (available with Spatial Analyst or Image Analyst) is
# used on the input rasters to create an output raster object
out_raster = Raster("input1") + Raster("input2") 
																																												
# The Python plus operator is used on numbers, creating a scalar variable
out_var = 4 + 7 

# When there is a combination of rasters with numbers, the Spatial Analyst
# operator is used, creating an output raster object
out_raster = Raster("input") + 10

Certain properties associated with the raster object are only available if the referenced raster dataset is permanent. When the referenced raster dataset is temporary, these properties will be assigned a value of None. The affected properties are catalogPath, compressionType, format, hasRAT, name, and path.

Once permanent, the referenced raster dataset cannot return to the temporary state.

When a raster object is created by supplying the path to an existing raster on disk, its readOnly property is True by default and its cell values can be read using the [row, column] index notation. 

in_raster = Raster('c:/data/inraster')

# Read the cell value at the second row and third column
v = in_raster[1, 2]

When a raster object is created by supplying a RasterInfo object as input, it will create a temporary raster in the ArcGIS temp directory. The readOnly property of such a raster object is False by default and its cell values can be modified using the [row, column] index notation. 

in_raster = Raster('c:/data/inraster')
raster_info = in_raster.getRasterInfo()
new_raster = Raster(raster_info)  # Create a new raster

# Modify the cell value at the second row and third column
new_raster[1, 2] = 3
new_raster.save('c:/output/outraster1')

In a RasterCellIterator loop, Raster objects are used to read and write data at cell level using the [row, column] index notation.

Syntax

 Raster (inRaster, {is_multidimensional})
ParameterExplanationData Type
inRaster
[inRaster,...]

The input raster dataset or list of raster datasets.

When multiple multidimensional raster datasets are provided, the files will be interpreted as a single multidimensional dataset, with variables and dimensions unioned together. If two files contain the same variable with the same dimension values, the slices in the output raster will come from the first multidimensional raster in the list.

You can also specify a RasterInfo object as the input inRaster, which will create a new raster dataset on disk. In this case, the is_multidimensional input parameter will be ignored.

Raster
is_multidimensional

Determines whether the input raster will be treated as multidimensional. Specify True if the input is multidimensional and should be processed as multidimensional, where processing occurs for every slice in the dataset. Specify False if the input is not multidimensional, or if it is multidimensional and should not be processed as multidimensional.

(The default value is False)

Boolean

Properties

PropertyExplanationData Type
bandCount
(Read Only)

The number of bands in the referenced raster dataset.

Integer
bandNames
(Read Only)

The band names in the referenced raster dataset.

String
blockSize
(Read Only)

The block size of the referenced raster dataset.

tuple
catalogPath
(Read Only)

The full path and the name of the referenced raster dataset.

String
catalogPaths
(Read Only)

The full path and the name of each item comprising a mosaic dataset.

String
compressionType
(Read Only)

Specifies the compression type. The following are the available types:

  • LZ77
  • JPEG
  • JPEG 2000
  • PACKBITS
  • LZW
  • RLE
  • CCITT GROUP 3
  • CCITT GROUP 4
  • CCITT (1D)
  • None

String
extent
(Read Only)

The extent of the referenced raster dataset.

Extent
format
(Read Only)

Specifies the raster format.

  • BIL—Esri Band Interleaved by Line file
  • BIP—Esri Band Interleaved by Pixel file
  • BMP—Bitmap graphic raster dataset format
  • BSQ—Esri Band Sequential file
  • DAT—ENVI DAT file
  • GIF—Graphic Interchange Format for raster datasets
  • Grid—Esri Grid raster dataset format
  • IMAGINE Image—ERDAS IMAGINE raster data format
  • JP2000—JPEG 2000 raster dataset format
  • JPEG—Joint Photographic Experts Group raster dataset format
  • PNG—Portable Network Graphic raster dataset format
  • TIFF—Tagged Image File Format for raster datasets

String
functions
(Read Only)

Retrieves a raster function template using the path to the rft.xml file. Rasters can be processed with the retrieved template using the Apply function.

String
hasRAT
(Read Only)

Specifies whether an associated attribute table exists: True if an attribute table exists or False if no attribute table exists.

Boolean
hasTranspose
(Read and Write)

Specifies whether a transposed version of the multidimensional data is associated with the raster: True if an associated transpose exists or False if no transpose exists.

Boolean
height
(Read Only)

The number of rows.

Integer
isInteger
(Read Only)

Specifies whether the raster dataset has an integer type. It's True if the raster dataset has an integer type.

Boolean
isMultidimensional
(Read Only)

Specifies whether the raster dataset is multidimensional. It's True if the raster dataset is multidimensional.

Boolean
isTemporary
(Read Only)

Specifies whether the raster dataset is temporary (True)or permanent (False).

Boolean
maximum
(Read Only)

The maximum value in the referenced raster dataset.

Double
mean
(Read Only)

The mean value in the referenced raster dataset.

Double
meanCellHeight
(Read Only)

The cell size in the y direction.

Double
meanCellWidth
(Read Only)

The cell size in the x direction.

Double
minimum
(Read Only)

The minimum value in the referenced raster dataset.

Double
mdinfo
(Read Only)

The multidimensional information of the raster dataset, including variable names; descriptions and units; and dimension names, units, intervals, and ranges. For example, a multidimensional raster containing monthly temperature data over 10 months will return the following: {"variables": [{"name":"Temp", "dimensions":[{"name":"StdTime", "field":"StdTime", "hasRegularIntervals":true, "interval":1, "intervalUnit":"Months", "extent":["1982-01-15T00:00:00", "1982-10-15T00:00:00"], "hasRanges":false,"values":["1982-01-15T00:00:00", "1982-02-15T00:00:00, ... "1982-10-15T00:00:00"]}]}], "layout":1}

If the raster is not a multidimensional raster, this property returns None.

String
name
(Read Only)

The name of the referenced raster dataset.

String
names
(Read Only)

The name of each item comprising a mosaic dataset.

String
noDataValue
(Read Only)

The NoData value of the referenced raster dataset.

Double
noDataValues
(Read Only)

The NoData value for each band in the referenced multiband raster dataset.

tuple
path
(Read Only)

The full path of the referenced raster dataset.

String
pixelType
(Read Only)

Specifies the pixel type of the referenced raster dataset. The types are the following:

  • U1—1 bit
  • U2—2 bits
  • U4—4 bits
  • U8—Unsigned 8-bit integers
  • S8—8-bit integers
  • U16—Unsigned 16-bit integers
  • S16—16-bit integers
  • U32—Unsigned 32-bit integers
  • S32—32-bit integers
  • F32—Single-precision floating point
  • F64—Double-precision floating point

String
properties
(Read Only)

The property name and value pairs in the referenced raster dataset.

Dictionary
RAT
(Read Only)

The attribute table of the referenced raster dataset. For example, the attribute table for a raster dataset with two classes will return {'OID': [0, 1], 'Value': [10, 20], 'ClassName': ['Low', 'High'], 'Red': [178, 56], 'Green': [178, 168], 'Blue': [178, 0], 'Alpha': [255, 255], 'Count': [887412.0, 962159.0]}. If the raster is multidimensional, there will be a Count field for each slice in the dataset.

If no attribute table exists, None is returned.

Dictionary
readOnly
(Read and Write)

Specifies whether the raster cell values are writable using the [row, column] notation. When this property is True, they are not writable. If it's False, they are writable.

Boolean
slices
(Read Only)

The attribute information of each slice, including its variable name, dimension names, and dimension values returned as a list of dictionaries. For example, a multidimensional raster containing temperature data over 24 months will return the following: [{'variable': 'temp', 'StdTime': '2017-1-15'}, {'variable': 'temp', 'StdTime': '2017-2-15'}, .....{'variable': 'temp', 'StdTime': '2018-12-15'}]

String
spatialReference
(Read Only)

Specifies the spatial reference of the exported image. Supported options include the following:

  • None
  • SpatialReference data type
  • ICS or ICS:<object_id> in which the object_id value provides the specific raster whose image coordinate system will be used.
If no value is specified, the spatial reference of the raster dataset will be used.

SpatialReference
standardDeviation
(Read Only)

The standard deviation of the values in the referenced raster dataset.

Double
sum
(Read Only)

The sum of the values in the referenced raster dataset.

Double
uncompressedSize
(Read Only)

The size of the referenced raster dataset on disk.

Double
variables
(Read Only)

The variable names and their dimensions in the multidimensional raster dataset. For example, a multidimensional raster containing temperature data over 24 months will return ['temp(StdTime=24)'].

String
variableNames
(Read Only)

The variable names in the multidimensional raster dataset.

String
width
(Read Only)

The number of columns.

Integer

Method Overview

MethodExplanation
addDimension (variable, new_dimension_name, dimension_value, {dimension_attributes})

Adds a new dimension to a variable in a multidimensional raster object so that the multidimensional raster can be compatible with other multidimensional datasets.

appendSlices (mdRaster)

Appends the slices from another multidimensional raster.

computeGSD (locations, spatial_reference, {dem})

Returns the ground sample distance (GSD) x- and y-values for an input image.

computeHistograms ({variable}, {aoi}, {cellsize})

Returns the histogram of the raster. If the raster is multidimensional, it returns the histogram of a variable.

computeStatistics ({variable}, {aoi}, {cellsize})

Returns the statistics of the raster. If the raster is multidimensional, it returns the statistics of a variable.

exportImage ({width}, {height}, {format}, {extent}, {spatial_reference}, {mosaic_rule})

Exports the raster object as an IPython Image object to be used for visualization in Jupyter Notebook.

fromSTACItem (stac_item, {request_params}, {context})

Creates a Raster object from a SpatioTemporal Asset Catalog (STAC) item.

getColormap ({variable_name})

Returns the color map of the raster. If the raster is multidimensional, returns the color map of a variable.

getDimensionAttributes (variable_name, dimension_name)

Returns the attribute information of a dimension for a specific variable in a multidimensional raster dataset, for example, description, unit, and so on.

getDimensionNames (variable_name)

Returns the dimension names associated with a variable in a multidimensional raster dataset.

getDimensionValues (variable_name, dimension_name)

Returns the values of a dimension associated with a variable in a multidimensional raster dataset.

getHistograms ({variable_name})

Returns the histograms of the raster. If the raster is multidimensional, it returns the histogram of a variable. If the raster is multiband, it returns the histogram of each band.

getProperty (property_name)

Returns the value of the given property.

getRasterBands ({band_ids_or_names})

Returns a Raster object for each band specified in a multiband raster dataset.

getRasterInfo ()

Returns a RasterInfo object whose properties are initialized using the raster object properties.

getStatistics ({variable_name})

Returns the statistics of the raster. If the raster is multidimensional, returns the statistics of a variable.

getVariableAttributes (variable_name)

Returns the attribute information of a variable in a multidimensional raster dataset (for example, description, unit, and so on).

isConstant (constantValue)

Identifies whether a raster only contains a constant value.

read ({upper_left_corner}, {origin_coordinate}, {ncols}, {nrows}, {nodata_to_value}, {cell_size})

Reads a raster and converts the raster to a NumPy array.

removeVariables (variable_names)

Removes a variable or a list of variables from a Cloud Raster Format (CRF) multidimensional raster dataset.

renameBand (current_band_name_or_index, new_band_name)

Renames a band in a multiband raster dataset.

renameVariable (current_variable_name, new_variable_name)

Renames a variable in a Cloud Raster Format (CRF) multidimensional raster dataset.

save ({name})

Permanently saves the dataset referenced by the raster object.

setColormap (color_map, {variable_name})

Sets the color map for the raster. If the raster is multidimensional, it sets the color map for a variable.

setHistograms (histogram_obj, {variable_name})

Sets the histograms of the raster. If the raster is multidimensional, sets the histogram of a variable.

setProperty (property_name, property_value)

Add a customized property to the raster dataset.

If the property name exists, the existing property value will be overwritten.

setStatistics (statistics_obj, {variable_name})

Sets the statistics for the raster. If the raster is multiband, it sets the statistics for each band. If the raster is multidimensional, it sets the statistics for a variable.

setVariableAttributes (variable_name, variable_attributes)

Sets the attribute information of a variable in a multidimensional raster (for example, description, unit, and so on).

write (array, {upper_left_corner}, {origin_coordinate}, {value_to_nodata})

Converts a three- or four-dimensional NumPy array to a raster.

Methods

addDimension (variable, new_dimension_name, dimension_value, {dimension_attributes})
ParameterExplanationData Type
variable

The name of the variable to which the dimension will be added. Only multidimensional rasters in Cloud Raster Format (.crf) are supported.

String
new_dimension_name

The name of the new dimension.

String
dimension_value

The value to assign to the new dimension.

Only one value can be added, as more values (for example, multiple depths) would require new slices to be added to the dataset. To add more than one dimension value along with the new slices, use the addDimension method, then use the Merge function to merge existing data with the raster object.

Double
dimension_attributes

A Python dictionary that contains attribute information to be added to the new dimension, such as description or unit. For example, to add a unit attribute, use {"unit": "meters"}.

(The default value is None)

Dictionary
Return Value
Data TypeExplanation
String

The list of variable names and the corresponding dimensions of the multidimensional raster.

appendSlices (mdRaster)
ParameterExplanationData Type
mdRaster

The multidimensional raster containing the slices to be appended.

This raster must have the same variables, with the same dimension names, as the target raster. The cell sizes, extents, and spatial reference systems must also match.

The slices in this raster must be for dimension values that follow the dimension values of the slices in the target raster.

If a variable has two dimensions, slices will be appended along one dimension. The other dimension must have the same number of slices as the dimension in the target raster. For example, if a salinity variable contains slices over time and depth dimensions, time slices can be appended to another salinity multidimensional raster but only if the same number of depth slices exist in both rasters.

Raster
Return Value
Data TypeExplanation
String

A string containing the variable names and the associated dimensions in the multidimensional raster. For example, if the resulting raster has 10 time slices with precipitation data, it will return 'prcp(StdTime=10)'.

computeGSD (locations, spatial_reference, {dem})
ParameterExplanationData Type
locations
[locations,...]

A list of x,y-coordinates.

List
spatial_reference

The spatial reference of the input locations. For example, the spatial reference can be specified using the following format: WGS_1984_UTM_Zone_11N.

(The default value is None)

String
dem

The DEM to be used in the GSD computation.

(The default value is None)

String
Return Value
Data TypeExplanation
String

A list of the ground sample distance values.

computeHistograms ({variable}, {aoi}, {cellsize})
ParameterExplanationData Type
variable

The variable name for the multidimensional dataset. If a variable is not specified and the raster is multidimensional, the histogram of all variables will be calculated.

String
aoi
[aoi,...]

The area of interest to calculate statistics for. This can be provided as Polygon object or a list of coordinates in the raster's spatial reference system in the form of [min_x, min_y, max_x, max_y].

List
cellsize

The cell size to calculate statistics from. The raster will be resampled to the specified cell size before statistics are calculated.

If no value is specified, the cell size of the raster will be used.

Double
Return Value
Data TypeExplanation
Dictionary

A list of dictionaries containing the histogram of the raster or variable. For example, if the histogram is computed for a single band or variable, the output will be returned in the following format: [{'size': 251, 'min': -0.5, 'max': 250.5, 'counts': [814.0, 894.0, 836.0, 902.0, 1317.0, 1263.0, 1360.0]}].

computeStatistics ({variable}, {aoi}, {cellsize})
ParameterExplanationData Type
variable

The variable name of the multidimensional dataset. If a variable is not provided and the raster is multidimensional, the histogram of all variables will be calculated.

String
aoi
[aoi,...]

The area of interest that will be used to calculate statistics. This can be provided as a Polygon object or a list of coordinates in the raster's spatial reference system in the form of [min_x, min_y, max_x, max_y].

List
cellsize

The cell size that will be used to calculate statistics. The raster will be resampled to the specified cell size before statistics are calculated.

If no value is specified, the cell size of the raster will be used.

Double
Return Value
Data TypeExplanation
Dictionary

A list of dictionaries containing the statistics of the raster or variable. For example, if statistic are computed for a single band or variable, the output will be returned in the following format: [{'min': 0.0, 'max': 250.0, 'mean': 114.60855843925984, 'sum': 51931430.0, 'standardDeviation': 97.18526137567137, 'median': 78.0, 'mode': 250.0, 'skipX': 1, 'skipY': 1, 'count': 453120.0, 'covariances': '0.000000'}].

exportImage ({width}, {height}, {format}, {extent}, {spatial_reference}, {mosaic_rule})
ParameterExplanationData Type
width

The width of the output image in pixels. If a value is not specified, but the height is provided, the aspect ratio of the original raster will be maintained. If neither width nor height are specified, the width of the original raster dataset is used.

(The default value is None)

Integer
height

The height of the output image in pixels. If a value is not specified, but the width is provided, the aspect ratio of the original raster will be maintained. If neither width nor height are specified, the height of the original raster dataset is used.

(The default value is None)

Integer
format

The image format of the exported data. The supported formats include JPG, PNG, and PNG32.

(The default value is PNG32)

String
extent

The extent or bounding box of the exported image. If a value is not specified, the extent of the raster dataset is used.

(The default value is None)

Extent
spatial_reference

The spatial reference of the exported image. Supported options include the following:

  • None
  • SpatialReference data type
  • ICS or ICS:<object_id>, where object_id selects the specific raster whose image coordinate system should be used.
If a value is not specified, the spatial reference of the raster dataset is used.

(The default value is None)

SpatialReference
mosaic_rule

Specifies how the input raster data should be mosaicked. This is applicable when the input raster dataset is a mosaic dataset. For information on how to format the mosaic rule, see Mosaic rule objects.

(The default value is None)

Dictionary
Return Value
Data TypeExplanation
Object

The exported image as an IPython Image object.

fromSTACItem (stac_item, {request_params}, {context})
ParameterExplanationData Type
stac_item

The URL of the STAC item or a pystac.Item object. The URL can be a static STAC item URL or a STAC API item URL, for example, "https://planetarycomputer.microsoft.com/api/stac/v1/collections/naip/items/tx_m_2609719_se_14_060_20201217".

STAC items from the following STAC APIs are supported:

  • https://planetarycomputer.microsoft.com/api/stac/v1—The following collections are supported: daymet-annual-pr, daymet-daily-hi, 3dep-seamless, 3dep-lidar-dsm, sentinel-1-rtc, gridmet, daymet-annual-na, daymet-monthly-na, daymet-annual-hi, daymet-monthly-hi, daymet-monthly-pr, hgb, cop-dem-glo-30, cop-dem-glo-90, terraclimate, gnatsgo-rasters, 3dep-lidar-hag, 3dep-lidar-intensity, 3dep-lidar-pointsourceid, mtbs, noaa-c-cap, alos-fnf-mosaic, 3dep-lidar-returns, mobi, landsat-c2-l2, chloris-biomass, daymet-daily-pr, 3dep-lidar-dtm-native, 3dep-lidar-classification, 3dep-lidar-dtm, gap, alos-dem, jrc-gsw, hrea, sentinel-2-l2a, daymet-daily-na, nrcan-landcover, ecmwf-forecast, noaa-mrms-qpe-24h-pass2, sentinel-1-grd, nasadem, io-lulc, landsat-c2-l1, drcog-lulc, chesapeake-lc-7, chesapeake-lc-13, chesapeake-lu, noaa-mrms-qpe-1h-pass1, noaa-mrms-qpe-1h-pass2, noaa-nclimgrid-monthly, usda-cdl, esa-cci-lc, esa-cci-lc-netcdf, noaa-climate-normals-netcdf, noaa-climate-normals-gridded, io-lulc-9-class, io-biodiversity, naip, noaa-cdr-sea-surface-temperature-whoi, noaa-cdr-ocean-heat-content, noaa-cdr-sea-surface-temperature-whoi-netcdf, sentinel-3-olci-wfr-l2-netcdf, noaa-cdr-ocean-heat-content-netcdf, sentinel-3-synergy-v10-l2-netcdf, sentinel-3-olci-lfr-l2-netcdf, sentinel-3-slstr-lst-l2-netcdf, sentinel-3-slstr-wst-l2-netcdf, sentinel-3-synergy-syn-l2-netcdf, sentinel-3-synergy-vgp-l2-netcdf, sentinel-3-synergy-vg1-l2-netcdf, and esa-worldcover, modis-64A1-061, modis-17A2H-061, modis-11A2-061, modis-17A2HGF-061, modis-17A3HGF-061, modis-09A1-061, modis-16A3GF-061, modis-21A2-061, modis-43A4-061, modis-09Q1-061, modis-14A1-061, modis-13Q1-061, modis-14A2-061, modis-15A2H-061, modis-11A1-061, modis-15A3H-061, modis-13A1-061, modis-10A2-061, modis-10A1-061, aster-l1t
  • https://earth-search.aws.element84.com/v0—All collections are supported.
  • https://earth-search.aws.element84.com/v1—All collections are supported.
  • https://services.sentinel-hub.com/api/v1/catalog—All collections are supported.
  • https://landsatlook.usgs.gov/stac-server—All collections are supported.
  • https://geoportalstac.azurewebsites.net/stac—All collections are supported.
  • https://gpt.geocloud.com/sentinel/stac —All collections are supported.

STAC items from the following static catalogs (and their underlying child catalogs) are supported:

  • https://capella-open-data.s3.us-west-2.amazonaws.com/stac/catalog.json–The GEO, GEC, and SICD product types are supported.
  • https://maxar-opendata.s3.amazonaws.com/events/catalog.json
  • https://storage.googleapis.com/cfo-public/catalog.json
  • https://nz-imagery.s3-ap-southeast-2.amazonaws.com/catalog.json
  • https://raw.githubusercontent.com/m-mohr/oam-example/main/catalog.json
  • https://dop-stac.opengeodata.lgln.niedersachsen.de/catalog.json
  • https://pta.data.lit.fmi.fi/stac/root.json
  • https://datacloud.icgc.cat/stac-catalog/catalog.json
  • https://bdc-sentinel-2.s3.us-west-2.amazonaws.com/catalog.json
String
request_params

The STAC item request parameters. These are the requests.get() method parameters and values in dictionary format.

This parameter is honored when the stac_item parameter is a URL.

{
"verify": False,
"headers": {"Authorization": "Bearer access_token_string"}
}
Dictionary
context

Additional properties to control the creation of the object.

The dictionary supports the assetManagement and processingTemplate keys.

The assetManagement key specifies how to manage and select assets for the RasterCollection object. If multiple assets are selected, the collection will be composed of multiband rasters from those selected asset types. The value can be a list, string, or dictionary.

When working with individual assets, the asset key can be specified directly, for example, "B02" or {"key": "B02"}, or as a list. Each item in the list represents an asset key or identifier. Items in the list can be strings representing the asset key directly, or dictionaries providing additional details for locating the asset.

If the value of the assetManagement key is a dictionary, the following keys are supported:

  • key—A string representing the unique identifier for an asset, for example: "red".
  • path—A list representing the hierarchy of keys to navigate to the asset, for example: ["alternate", "s3"].
  • hrefKey—A string representing the key to access the asset URL, for example: "msft:https-url". If this value different from the default href key, it should be specified here.

Examples:

{
    "assetManagement": [
        "red",
        "blue"
    ]
}
{
    "assetManagement": {
       "key": "tasmin",
       "hrefKey": "msft:https-url"
    }
}
{
    "assetManagement": [
       {"key": "TRAD",
        "path": ["alternate", "s3"]},
       {"key": "DRAD", 
        "path": ["alternate", "s3"]}
    ]
}

The processingTemplate key specifies the processing template that will be applied to the raster. This is supported for selected collections and raster types. For more information about collections and raster types, see Satellite sensor raster types. The default for supported raster types is "Multiband"; otherwise, it's None.

Example:

{
    "processingTemplate": "Surface Reflectance"
}
Dictionary
Return Value
Data TypeExplanation
Raster

A new instance of this class is returned.

getColormap ({variable_name})
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the color map of the first variable will be returned.

String
Return Value
Data TypeExplanation
Dictionary

A Python dictionary containing the color map of the raster or variable. Pixel values are listed first, followed by the corresponding color map values in HEX color codes—for example, {'type': 'RasterColormap', 'values': [10, 20, 30], 'colors': ['#66FF33', '#0033CC', '#FF00FF']}.

getDimensionAttributes (variable_name, dimension_name)
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset.

String
dimension_name

The dimension name of the multidimensional raster dataset.

String
Return Value
Data TypeExplanation
String

The attribute information of the dimension, for example, the minimum and maximum dimension values, the time step interval, and the interval units.

getDimensionNames (variable_name)
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset.

String
Return Value
Data TypeExplanation
String

The dimension names associated with the variable. 

getDimensionValues (variable_name, dimension_name)
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset.

String
dimension_name

The dimension name of the multidimensional raster dataset.

String
Return Value
Data TypeExplanation
String

The dimension values of the variable. 

getHistograms ({variable_name})
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the histogram of the first variable will be returned.

String
Return Value
Data TypeExplanation
Dictionary

The histogram values of the raster or variable—for example, [{'size': 10, 'min': 0.0, 'max': 364.0, 'counts': [882.0, 18.0, 9.0, 0.0, 9.0, 0.0, 18.0, 9.0, 18.0, 0.0]}].

getProperty (property_name)
ParameterExplanationData Type
property_name

The property name of the raster dataset.

String
Return Value
Data TypeExplanation
String

The value of the property.

getRasterBands ({band_ids_or_names})
ParameterExplanationData Type
band_ids_or_names
[band_ids_or_names,...]

The index number or names of the bands to return as Raster objects. If not specified, all bands will be extracted.

(The default value is None)

String
Return Value
Data TypeExplanation
Raster

The Raster object for each band specified.

getRasterInfo ()
Return Value
Data TypeExplanation
Object

A RasterInfo object.

getStatistics ({variable_name})
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the statistics of the first variable will be returned.

String
Return Value
Data TypeExplanation
Dictionary

The statistics of the raster or variable.

getVariableAttributes (variable_name)
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset.

String
Return Value
Data TypeExplanation
String

The attribute information of the variable. 

isConstant (constantValue)
ParameterExplanationData Type
constantValue

The value to evaluate for in the raster.

Double
Return Value
Data TypeExplanation
Boolean

A Boolean that indicates whether the raster only contains the constant value.

read ({upper_left_corner}, {origin_coordinate}, {ncols}, {nrows}, {nodata_to_value}, {cell_size})
ParameterExplanationData Type
upper_left_corner

The coordinates relative to the origin_coordinate from which to extract the processing block to convert to an array. This should be formatted as a tuple with two values indicating the direction to move in the x- and y-direction, respectively. For example, a value of (2,0) indicates that the array should be extracted starting at the pixel that is two pixels away, in the x-direction, from the origin_coordinate.

If no value is specified, (0,0) is used.

(The default value is None)

tuple
origin_coordinate

The point of origin within the Raster object from which to extract the processing block to convert to an array. The coordinates must be in the units of the raster.

If no value is specified, the origin of the raster will be used.

(The default value is None)

Point
ncols

The number of columns from the upper_left_corner in the Raster object to convert to the NumPy array.

If no value is specified, the number of columns of the raster will be used.

(The default value is None)

Integer
nrows

The number of rows from the upper_left_corner in the Raster object to convert to the NumPy array.

If no value is specified, the number of rows of the raster will be used.

(The default value is None)

Integer
nodata_to_value

The pixel value to assign in the NumPy array for those pixels labeled as NoData in the Raster object.

If no value is specified, the NoData value of the raster will be used.

(The default value is None)

Variant
cell_size

The cell size to use in the NumPy array. This should be formatted as a tuple with two values indicating the cell size in the x- and y-direction, respectively, and units should match those used by the raster. For example, a value of (2, 1) indicates the output cell size should be 2 units in the x-direction and 1 unit in the y-direction. If the cell size is different from the data source, the cell values are resampled using bilinear interpolation.

If no value is specified, the cell size of the raster will be used.

(The default value is None)

tuple
Return Value
Data TypeExplanation
NumPyArray

The output NumPy array.

If the raster is a single- or multiband raster, the dimensions of the array will be rows, columns, and number of bands.

If the raster is a multidimensional raster, the dimensions of the array will be number of slices, rows, columns, and number of bands.

removeVariables (variable_names)
ParameterExplanationData Type
variable_names
[variable_names,...]

The variable name or a list of variable names to be removed from the multidimensional raster dataset.

String
renameBand (current_band_name_or_index, new_band_name)
ParameterExplanationData Type
current_band_name_or_index

The name or the index of the band to be renamed. The band indexing begins at 1. This argument can be a string or integer value.

String
new_band_name

The new band name.

String
Return Value
Data TypeExplanation
Raster

The Raster object with renamed bands.

renameVariable (current_variable_name, new_variable_name)
ParameterExplanationData Type
current_variable_name

The current name of the variable in a multidimensional raster dataset.

String
new_variable_name

The new name of the variable in a multidimensional raster dataset.

String
save ({name})
ParameterExplanationData Type
name

The name to assign to the raster dataset on disk.

This method supports persisting a multidimensional raster dataset as Cloud Raster Format (CRF).

String
setColormap (color_map, {variable_name})
ParameterExplanationData Type
color_map

The color map to apply to the raster. This can be a string indicating the name of the color map or color ramp to use, for example, NDVI or Yellow To Red, respectively. This can also be a Python dictionary with a custom color map or color ramp object—for example, a custom color map {'values': [0, 1, 2, 3, 4, 5], 'colors': ['#000000', '#DCFFDF', '#B8FFBE', '#85FF90', '#50FF60','#00AB10']} or a custom color ramp {"type": "algorithmic", "fromColor": [115, 76, 0, 255],"toColor": [255, 25, 86, 255], "algorithm": "esriHSVAlgorithm"}.

String
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the color map of the first variable will be set.

String
setHistograms (histogram_obj, {variable_name})
ParameterExplanationData Type
histogram_obj
[histogram_obj,...]

A list of Python dictionaries containing histogram information to be set—for example, [{'size': 5, 'min': 19.0, 'max': 42.0, 'counts': [275, 17, 3065, 4, 22]}].

If the raster is multiband, the histogram for each band will be set with each dictionary in the list. The first band will use the histogram in the first dictionary. The second band will use the histogram in the second dictionary, and so on.

  • size—The number of bins in the histogram
  • min—The minimum pixel value
  • max—The maximum pixel value
  • counts—A list containing the number of pixels in each bin, in the order of bins
Dictionary
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the histogram will be set for the first variable.

String
setProperty (property_name, property_value)
ParameterExplanationData Type
property_name

The property name of the raster dataset.

String
property_value

The value to assign to the property.

String
setStatistics (statistics_obj, {variable_name})
ParameterExplanationData Type
statistics_obj
[statistics_obj,...]

A list of Python dictionaries containing statistics and corresponding values to set. For example, [{'min': 10, 'max': 20}] sets the minimum and maximum pixel values.

If the raster is multiband, the statistics for each band will be set with each dictionary in the list. The first band will use the statistics in the first dictionary. The second band will use the statistics in the second dictionary, and so on.

  • min—The minimum pixel value
  • max—The maximum pixel value
  • mean—The mean pixel value
  • median—The median pixel value
  • standardDeviation—The standard deviation of the pixel values
  • count—The total number of pixels
  • skipX—The horizontal skip factor
  • skipY—The vertical skip factor
List
variable_name

The variable name of the multidimensional raster dataset. If a variable is not specified and the raster is multidimensional, the statistics of the first variable will be set.

String
setVariableAttributes (variable_name, variable_attributes)
ParameterExplanationData Type
variable_name

The variable name of the multidimensional raster dataset.

String
variable_attributes

A Python dictionary that contains attribute information to replace the current attribute information of the variable—for example, {'Description': 'Daily total precipitation', 'Unit': 'mm/day'}.

Dictionary
Return Value
Data TypeExplanation
String

The attribute information of the variable.

write (array, {upper_left_corner}, {origin_coordinate}, {value_to_nodata})
ParameterExplanationData Type
array

The input NumPy array.

(The default value is None)

NumPyArray
upper_left_corner

The coordinates relative to the origin_coordinate from which to extract the processing block to convert to a raster. This should be formatted as a tuple with two values indicating the number of pixels to move along the x- and y- direction, respectively. For example, (2,0), indicates that the position from which the NumPy array will be written into the raster is 2 pixels away, in the x-direction, from the origin_coordinate.

If no value is specified, (0,0) is used.

(The default value is None)

tuple
origin_coordinate

A Point object defining the origin, from which the numpy array will be written into the Raster. The x- and y-values are in th units of the raster. If no value is specified, the upper left corner of the raster, will be used.

If no value is specified, the origin of the raster will be used. This is the default.

(The default value is None)

Point
value_to_nodata

A value in the NumPy array to be used as the NoData value in the Raster. The value can be an integer or a float. If no value is specified, the NoData value of the Raster will be used.

The default value is None.

(The default value is None)

Double

If the raster is a single-band raster, the dimensions of the array must be rows, columns, 1.

If the raster is a multiband raster, the dimensions of the array must be rows, columns, band count.

If the raster is a multidimensional raster, in which each slice is single band, the dimensions of the array must be number of slices, rows, columns, 1.

If the raster is a multidimensional raster, in which each slice is multiband, the dimensions of the array must be number of slices, rows, columns, band count.

Code sample

Raster example 1

Creates a Raster object from a raster dataset and gets properties for analysis.

import arcpy

my_raster = arcpy.Raster('elevation')
my_min = my_raster.minimum
my_max = my_raster.maximum
my_area = (my_raster.width * my_raster.height) * my_raster.meanCellWidth
Raster example 2

Creates a Raster object, retrieves the raster function templates from the raster dataset, and applies the processing templates.

import arcpy

#Create raster object
ras = arcpy.Raster(r"D:\Data\ndfd.crf")

#Define two raster function templates from the input CRF
ras.functions =[r"C:\weather.rft.xml", r"C:\heatindex.rft.xml"]

#Retrieve the first rft and process the raster object using the Apply function
rft = ras.functions
processed_raster = arcpy.ia.Apply(ras, json.dumps(rft[1]))
Raster example 3

Creates a Raster object, gets properties, creates a random error raster (+/- 3 feet), adds it to an elevation raster, and converts its units from feet to meters.

import arcpy
from arcpy.sa import *

elev_raster = Raster('c:/data/elevation')
my_extent = elev_raster.extent
my_cellsize = (elev_raster.meanCellHeight + elev_raster.meanCellWidth) / 2
res01 = arcpy.CreateRandomRaster_management("", "error3", "UNIFORM 0.0 3.0",
                                            my_extent, my_cellsize)
elev_meters = (elev_raster + Raster(res01)) * 0.3048
elev_meters.save("c:/output/fgdb.gdb/elevM_err")
Raster example 4

Creates a Raster object from a multidimensional raster dataset and gets multidimensional information including variables and dimension values.

import arcpy

## Load a netCDF file as a multidimensional raster
mdim_raster = Raster("Precip_2000_2018.nc", True)

## Check if it is multidimensional raster
is_multidimensional = mdim_raster.isMultidimensional

## Return the multidimensional information 
my_mdinfo = mdim_raster.mdinfo

## Return the list of variable names and their dimensions
my_variables = mdim_raster.variables

## Get the time dimension values for the precipitation variable
my_dimensionValues = mdim_raster.getDimensionValues("precip", "StdTime")

# save as a mdim crf
mdim_raster.save("c:/output/Precip_18_yr.crf")
Raster example 5

Creates a Raster object from a multidimensional raster dataset and computes the statistics for a variable.

import arcpy

#Load a netCDF file as a multidimensional raster
mdim_raster = Raster("Precip_2000_2018.nc", True)

#Create an array that contains the corner coordinates for a bounding box
array = arcpy.Array([arcpy.Point(-119.8082436, 38.2177764), arcpy.Point(-119.7794812, 38.2038911), arcpy.Point(-119.7432803, 38.2232313), arcpy.Point(-119.7928706, 38.2425716)])

#Specify a spatial reference
spatial_reference = arcpy.SpatialReference(4326)

#Create a polygon object that will be used to specify the aoi
aoi= arcpy.Polygon(array, spatial_reference)

#return the statistics 
stats = mdim_raster.computeStatistics('precip', aoi, cellsize = 463)
Raster example 6

Creates a Raster object from a STAC Item.

from arcpy.ia import *
from arcpy import AIO

# 1) Creates a raster object from NAIP data accesible through Planetary Computer STAC API

naip_ras = Raster.fromSTACItem(
stac_item="https://planetarycomputer.microsoft.com/api/stac/v1/collections/naip/items/tx_m_2609719_se_14_060_20201217"
)

# Apply grayscale raster function to the raster object
gray_ras = Grayscale(naip_ras)

# 2) Creates a raster object from Sentinel-2 L2A data accesible through Earth Search STAC API

sentinel_2_ras = Raster.fromSTACItem(
     stac_item="https://earth-search.aws.element84.com/v1/collections/sentinel-2-l2a/items/S2A_45XWD_20230328_0_L2A"
)

# Retrieve raster object properties
cols, rows = sentinel_2_ras.width, sentinel_2_ras.height

# 3) Creates a raster object from Landsat C2-L2 data accesible through USGS

# LandsatLook STAC API (with custom processing template selection) - Requires acs (AIO object).

landsat_acs = AIO(r"C:\acs_files\s3_landsat_c2.acs")

qa_landsat_ras = Raster.fromSTACItem(
        stac_item="https://landsatlook.usgs.gov/stac-server/collections/landsat-c2l2-sr/items/LC09_L2SP_088084_20230729_20230801_02_T2_SR",
        context={
	"processingTemplate": "QA",
	},
)

# 4) Creates a raster object from CBERS data accesible through
# CBERS/AMAZONIA on AWS (static) STAC (with custom asset selection) - Requires acs (AIO object).

cbers_acs = AIO(r"C:\acs_files\s3_cbers_pds.acs")

cbers_ras = Raster.fromSTACItem(
        stac_item="https://br-eo-stac-1-0-0.s3.amazonaws.com/CBERS4/MUX/043/076/CBERS_4_MUX_20230630_043_076_L2.json",
        context={"assetManagement": ["B7", "B6", "B5"]},
)

Feedback on this topic?

In this topic
  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample