Image Service

An image service (also called a hosted imagery layer) enables storage, delivery, processing, analysis, and sharing of raster imagery via REST endpoints and APIs. Clients—whether web, desktop, or mobile—can request imagery by spatial extent, apply raster functions, perform analytics, or fetch tiles. The image service can dynamically mosaic multiple images, execute on‑the‑fly processing, and expose tailored capabilities depending on how it is configured.

The URL for an image service layer hosted in ArcGIS Online typically resembles the following pattern: https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/ImageServer/

Register a GIS

Authentication will be required when saving an image service to ArcGIS Online. GeoAnalytics Engine supports authentication by registering a GIS (i.e. a connection to ArcGIS Online) with the register_gis) function.

The default GIS in register_gis is ArcGIS Online. The following example shows registering ArcGIS Online as a GIS with a username and password for a built-in account.

1
2
3

import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")

Each GIS name can only be registered once. To remove a GIS, use the unregister_gis function as shown in the following example.

1
2
3

import geoanalytics
geoanalytics.unregister_gis("myGIS")

Read from image services

GeoAnalytics Engine supports loading data from image services into a Spark DataFrame for use with any operations supported on a DataFrame in GeoAnalytics Engine or Spark.

The following example shows the Python syntax for loading an image service into a Spark DataFrame, where URL is the URL to an image service.

1
spark.read.format("image-service").option().load(URL)

Below is a table of options that GeoAnalytics Engine supports when loading an image service with Spark DataFrameReader.

When loading a public image service layer, you can pass the URL without options gis or token:

1
spark.read.format("image-service").load(URL)

When loading a secured image service layer, a GIS connection or token will be required. For example:

1
2
3
4

import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")
spark.read.format("image-service").option("gis", "myGIS").load(URL)

Write to image services

GeoAnalytics Engine extends Spark and supports saving data in image services. You can serve and share image services over the internet. You can also access, visualize, or edit the published image services in an ArcGIS Online portal.

The following script shows the Python syntax of saving image services that GeoAnalytics Engine currently supports:

1
df.write.format("image-service").option().save()

Below is a table of options and modes that GeoAnalytics Engine supports when saving an image service with Spark DataFrameWriter.

When saving an image service, a registered GIS is required. Below is an example of registering a GIS and saving an image service.

1
2
3
4
5
6
7
8
9
10

import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")

df = spark.read.format("raster").load(data_path)

df.write.format("image-service") \
        .option("gis", "myGIS") \
        .option("serviceName", "raster_output") \
        .save()

Usage notes

• A registered GIS is required when saving an image service.
• When writing to an image service, the promotion policy is applied. This policy converts the raster to the next largest pixel type and assigns the largest possible value of the new type as the NoData value. For instance, if a raster dataset with a Float32 pixel type is written to an image service, the resulting image service will have a pixel type of Float64. If the input raster dataset already has a pixel type of Float64, no conversion will occur, and the largest value of Float64 will be used as the NoData cell value.
• Writing a Spark DataFrame with a raster column lacking spatial references may result in an empty image service. If the column contains a mix of spatially referenced and unreferenced raster records, only those with spatial references will be included in output image service.
• When working with large image services and planning to perform a spatial transformation, it is recommended to specify the sr (spatial reference) option directly in the image service read operation, rather than applying the RT.Transform function after reading the image. This approach is preferred because reading large image services typically involves tiling, and performing the transformation afterward can introduce slight gaps or missing pixels at tile boundaries. By specifying the desired spatial reference during the read, you ensure that the transformation is handled efficiently and accurately, minimizing the risk of data loss or visual artifacts.
• Image services are loaded as value rasters by default when reading.