Create Imagery Layers

Introduction

Hosted imagery layers can be used to manage, share, and analyze raster and imagery data in your organization. You can use a hosted imagery layer as an input to analysis tools, create custom workflows with raster functions, manage large collections of imagery, and include imagery layers in maps.
In this guide, you will learn how to create imagery layers for your data quickly and easily using the ArcGIS API for Python.

Prerequisites

If you are creating imagery layers, you must have your GIS (either ArcGIS Online or ArcGIS Enterprise >= 10.9) properly configured for raster analysis, and you must have privileges to create content and publish hosted imagery layers.
For privilege information for ArcGIS Online, refer here.
For privilege information for ArcGIS Enterprise, refer here.

For this functionality to work in ArcGIS Online, Azure library packages for Python (Azure SDK for Python - azure-storage-blob: 12.1<= version <=12.8) needs to be pre-installed. Refer here for more information https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-install

import arcgis
from arcgis.gis import GIS
from arcgis.raster.analytics import copy_raster, create_image_collection, list_datastore_content

# Log into ArcGIS Online or ArcGIS Enterprise, ensuring that you have the required privileges as mentioned above.
gis = GIS("home")

By using the copy_raster function you can create one imagery layer by mosaicking multiple images.

Image mosaic

By using the [copy_raster] (https://developers.arcgis.com/python/api-reference/arcgis.raster.analytics.html#copy-raster) function you can create one imagery layer by mosaicking multiple images. This option supports generating a single imagery layer that is a mosaic of multiple images over space, multidimensional raster data, and many raster types that allow you to control how your satellite or aerial products are processed. Use this option for imagery layers where advanced metadata is required, such as for multiband pre-processed satellite scenes.

The copy_raster function can be used to create an image mosaic from local raster datasets. The following parameters can be configured to create an image mosaic:

• The path to the local raster data can be specified using the input_raster parameter.
• The name of the output imagery layer can be specified using the output_name parameter.
• Using the raster_type_name parameter, you can specify the raster type, which identifies metadata such as georeferencing, acquisition date, sensor type, and band wavelengths, along with a raster format. The supported raster types can be found in the table at the end of this guide.
• raster_type_params can be used to configure the options for your imagery layer. This parameter is accepted as a dictionary and can be utilized to configure the following properties:
  • The productType key can be used to specify the type of product included in your satellite imagery. Product types are typically identified by various processing levels associated with the specific sensor. The list of product types for each raster type can be found in the table at the end of this guide.
  • The processingTemplate key can be used to perform common imagery processing tasks, such as extracting specific bands, pansharpening, orthorectification, stretching, and other tasks. The processing templates that can be used depends on the raster type you selected. The list of processing templates for each raster type can be found in the table at the end of this guide.
  • The pansharpenType key helps you specify the pansharpen type you prefer. Further, you can also specify the filter and band weights. This option is honored when the input raster type includes coincident panchromatic and multispectral imagery data.
    Possible values include: "Mean", "IHS", "Brovey", "Esri", "Mean", "Gram-Schmidt".
  • The stretchType key can be used to stretch each raster item in the imagery layer. The value can be one of: MinMax; <min>; <max>, PercentMinxMax; <MinPercent>; <MaxPercent>, StdDev; <NumberOfStandardDeviation>.

    Example: {"productType":"All","processingTemplate":"Pansharpen", "pansharpenType":"Gram-Schmidt", "filter":"SharpenMore", "pansharpenWeights":"0.85 0.7 0.35 1", "StretchType": "MinMax; 0; 100"}

• You can also specify additional settings through the context parameter. The settings that can be configured are:
  • The output spatial reference to project the output raster.

    Example: {"outSR": {"wkid":3857}}

  • You can also specify whether to build footprints. You can choose to build footprints for your imagery layer such that only pixels within a given range are included. This will help eliminate null data value pixels resulting in seamless mosaics. If you choose to build footprints, you can also provide additional footprint settings.
    You can also choose to define a NoData value for pixels in the imagery layer. Pixels with the NoData value will display as transparent in the map.

    Example: {"buildFootprints":True, "footprintsArguments":{"method":"RADIOMETRY","minValue":1,"maxValue":5, "shrinkDistance":50,"skipOverviews":True,"updateBoundary":True, "maintainEdge":False,"simplification":None,"numVertices":20, "minThinnessRatio":0.05,"maxSliverSize":20,"requestSize":2000, "minRegionSize":100}, "defineNodata":True, "noDataArguments":{"noDataValues":[500],"numberOfBand":99,"compositeValue":True}, "buildOverview":True}

• The tiles_only parameter can be used to decide whether you would like the imagery layer to be a Tiled Imagery Layer or a Dynamic Imagery Layer. On ArcGIS Online, the default is Tiled Imagery Layer. This can be set to Dynamic Imagery Layer by setting the value of this parameter to False.
  On ArcGIS Enterprise, this parameter is not honored and will always generate a Dynamic Imagery Layer.

input_raster_folder = r"C:\data\input_rasters"
mosaic_imagery_layer = copy_raster(input_raster=input_raster_folder,
                                   output_name="mosaic_imagery_layer",
                                   raster_type_name="Raster Dataset",
                                   gis=gis)

Below are some examples for satellite imagery for the Landsat and Pleiades satellites along with the appropriate raster_type_name and raster_type_params:

landsat_data = r"C:\data\Landsat15MSS"
landsat_imagery_layer = copy_raster(input_raster=landsat_data,
                                    output_name="landsat_imagery_layer",
                                    raster_type_name="Landsat 1-5 MSS",
                                    raster_type_params={"productType": "Level1", "processingTemplate": "Multispectral"},
                                    gis=gis)

pleiades_data = r"C:\data\Pleiades1"
pleiades_imagery_layer = copy_raster(input_raster=pleiades_data,
                                     output_name="pleiades_imagery_layer",
                                     raster_type_name="Pleiades-1",
                                     raster_type_params={"productType": "ORTHO", "processingTemplate": "Pansharpen"},
                                     tiles_only=False,
                                     gis=gis)

Further, on ArcGIS Enterprise you can also make use of the data in your datastore (fileShares, rasterStores, cloudStores) to create hosted imagery layers. More information on creating datastores can be found here.

You can view the content in your datastore using the list_datastore_content function.

datastore_path = "/rasterStores/RasterDataStore/sentinel_data_folder"
list_datastore_content(datastore_path, gis=gis)

{'/rasterStores/RasterDataStore/sentinel_data_folder': ['/rasterStores/RasterDataStore/sentinel_data_folder/L1C_T10SEJ_A006760_20180622T190432/',
  '/rasterStores/RasterDataStore/sentinel_data_folder/L1C_T10SEJ_A015697_20180624T190108/']}

sentinel_imagery_layer = copy_raster(input_raster=datastore_path,
                                     output_name="sentinel_imagery_layer",
                                     raster_type_name="Sentinel-2",
                                     raster_type_params={"productType": "All", "processingTemplate": "Multispectral"},
                                     context={"image_collection_properties": {"imageCollectionType": "Satellite"}, "byref":True},
                                     gis=gis)

One image

The copy_raster function also enables you to create an imagery layer from just one image. This option supports all supported raster and image formats, multidimensional raster data, and configuration with various source types and compression settings. Use this option for simple imagery layers where advanced metadata is not needed.

Here, the input_raster parameter can accept the path to the local raster dataset. Since the only raster type that is supported is the Raster Dataset type, we do not have to specify the raster_type_name parameter here.

input_raster_path = r"C:\data\input_raster.tif"
single_image_layer = copy_raster(input_raster=input_raster_path,
                                 output_name="output_imagery_layer",
                                 gis=gis)

On ArcGIS Enterprise, you can also use data from your datastore as described above in the Image mosaic section.

datastore_path = "/rasterStores/rasterstore"
list_datastore_content(datastore_path, gis=gis)

{'/rasterStores/rasterstore': ['/rasterStores/rasterstore/090161.tif',
  '/rasterStores/rasterstore/esa_ca.crf/',
  '/rasterStores/rasterstore/Hosted_amberg_test_crf_cr_021.crf/',
  '/rasterStores/rasterstore/Hosted_CopyRaster_WEO4G6.crf/',
  '/rasterStores/rasterstore/Hosted_crf_2_byref.crf/',
  '/rasterStores/rasterstore/Hosted_output_imagery_layer_1.crf/',
  '/rasterStores/rasterstore/Hosted_testPotentialSolarPowerPlant02.crf/']}

input_raster = "/rasterStores/rasterstore/090161.tif"
single_image_layer_1 = copy_raster(input_raster=input_raster,
                                   output_name="output_imagery_layer_1",
                                   context={"byref": True},
                                   gis=gis)

Image collection

The create_image_collection function is another function that can be used to create hosted imagery layers on ArcGIS Online and ArcGIS Enterprise. This function will help you create an imagery layer that manages a collection of many images. It supports querying single images within the imagery layer that is made up of a collection of images. It further supports storing the imagery in the original source format.

The create_image_collection function can be used to create an imagery layer from multiple input rasters. The following parameters can be configured to create an image collection:

• The image_collection parameter helps you set the name of the image collection you would like to create.
• Using the input_rasters parameter, you can pass in the list of rasters to be used to create the image collection via the local raster data folder path.
• With the raster_type_name parameter you can specify the raster type which identifies and uses metadata such as georeferencing, acquisition date, sensor type, and band wavelengths. The supported raster types can be found in the table at the end of this guide.
• The raster_type_params can be used to configure the options for your imagery layer. A detailed explanation of these is given under the Image mosaic section of this guide.
• The context parameter can be used to provide additional input parameters.
  • The image_collection_properties can be set through the context as:

    {"image_collection_properties": {"imageCollectionType": "Satellite"}}

  • Additionally, other settings such as buildFootprints and NoData values can be set here. More details on this are explained in the Image mosaic section of this guide.

landsat_data = r"C:\data\Landsat15MSS"
landsat_imagery_layer = create_image_collection(image_collection="landsat15_image_collection",
                                                input_rasters=landsat_data,
                                                raster_type_name="Landsat 1-5 MSS",
                                                raster_type_params={"productType": "Level1", "processingTemplate": "Multispectral"},
                                                gis=gis)

On ArcGIS Enterprise you can also make use of the data in your datastore (fileShares, rasterStores, cloudStores) to create hosted imagery layers. More information on creating datastores can be found here.

You can view the content in your datastore using the list_datastore_content function.

datastore_path = "/rasterStores/RasterDataStore/sentinel_data_folder"
list_datastore_content(datastore_path, gis=gis)

{'/rasterStores/RasterDataStore/sentinel_data_folder': ['/rasterStores/RasterDataStore/sentinel_data_folder/L1C_T10SEJ_A006760_20180622T190432/',
  '/rasterStores/RasterDataStore/sentinel_data_folder/L1C_T10SEJ_A015697_20180624T190108/']}

sentinel_imagery_layer = create_image_collection(image_collection="sentinel_image_collection",
                                                 input_rasters=datastore_path,
                                                 raster_type_name="Sentinel-2",
                                                 raster_type_params={"productType":"All","processingTemplate":"Multispectral"},
                                                 context={"image_collection_properties":{"imageCollectionType":"Satellite"},"byref":True},
                                                 gis=gis)

Conclusion

In this guide, you've learned how to create imagery layers from your local raster data or data in your datastore using the copy_raster and create_image_collection functions. These functions provide a simple way of creating an imagery layer from a normal raster dataset, multidimensional datasets, and even satellite datasets. You have also seen how to create an imagery layer from either a single or multiple raster datasets.

Your imagery layers are now published and ready for further analysis. A comprehensive guide on using imagery layers can be found at https://developers.arcgis.com/python/guide/using-imagery-layers/.

Supported raster types