Image service parameters
There are many standard parameters for an image service whose defaults are sufficient for most ArcGIS Server services. These include the pooling options and several others. However, due to the nature of raster and image data, there are some parameters that can affect the speed of an image service, data that can be downloaded, querying, and many other options.
Some parameters are necessary when specific capabilities have been enabled. For example, if the Download capability is enabled, then the download parameters should be modified. This also applies to the Catalog, Editing, and Mensuration capabilities.
Default parameters to control the image data
The image service parameters are divided into several sections; each section is dependent on the input for the image service. Most of these parameters are specific to image services serving mosaic datasets and only a few affect an image service created from raster datasets or layers. Many mosaic dataset-related parameters are set when you create the mosaic dataset. Although some can be altered by the server administrator, he or she will not be able to exceed the maximums you have set in the mosaic dataset properties. For example, if you limit the allowed mosaic methods to only three of the methods, the administrator will not be able to add a fourth method. Or, if you set the maximum number of downloadable items, they can reduce the number but not increase this number.
If you change the parameters of the mosaic dataset to exceed or limit a value, such as the maximum size of requests, you need to republish it as an image service for the server to read the modified values. If you only stop and start the image service, the changed properties in the mosaic dataset will not be picked up, whereas if you change the properties of the image service itself, you only need to stop and start the image service for the changes to take effect.
Image parameters
The Image parameters affect the image that users connected to the image service will see.
|
Parameter |
Description |
|---|---|
Data Source | The location and name of the source dataset for the image service. Applicable to all inputs. |
|
Maximum image size per request |
The maximum number of pixel rows and columns that the server allows in a client request. If the client’s request exceeds this value, then none of the pixels will be returned. Applicable to all inputs. |
|
Default resampling method |
The resampling method used in the request. The methods include the following:
Applicable to all inputs. |
|
Allowed compression methods |
The allowable compression methods for the image service. There are three possible compression types available:
A default JPEG Quality and LERC Tolerance can be set in the Configure Allow List dialog box. The client can then choose which allowable compression method to use for transmission. This can be set in the Display tab in the Layer Properties dialog box. This parameter is applicable only to clients that access image services via the SOAP GetImage method, for example, ArcGIS for Desktop and applications built with ArcObjects. For clients accessing services via REST, compression is applied automatically based on the requested format type, regardless of the defined compression methods. |
Return JPGPNG as JPG | When the user requests the image using the JPGPNG format, if there is transparency, a PNG is returned; otherwise, a JPG is returned. The PNG is often much larger than the JPG and thus can take longer to transmit. If transparency is not necessary and you want to be sure the image service is always transmitted using a smaller image size, check this box. Applicable to all inputs. |
Cluster parameters
By default, every ArcGIS Server site has one cluster. If you have multiple server machines, you can configure them to operate in a cluster. Each cluster can be configured to run a dedicated set of services. The Choose the Cluster hosting the service parameter allows you to select the cluster in which your image service will operate.
Output Directory parameters
|
Parameter |
Description |
|---|---|
|
Directory |
Choose the output directory where you want the server to create temporary files. If you don't specify the output directory, the ArcGIS server will only return images as MIME data. By specifying an output directory, the returned images will also be accessible via a URL address. Applicable to all inputs. |
|
Supported Image Return Type |
Shows if the images generated by the ArcGIS server will be returned as MIME data only or both MIME and URL. To access images generated by ArcGIS Server over the Internet, you must specify an output directory for output images. Applicable to all inputs. |
Parameters to control the image service catalog
The Catalog parameters only apply when publishing a mosaic dataset as an image service. These parameters control or limit the access users have to metadata and the catalog fields, as well as limit the requests for records from the mosaic dataset tables. These parameters can affect the load on the server. The more you allow a user to view and query, the greater the draw on the server.
Mosaicking parameters
Parameter | Description |
|---|---|
|
Maximum number of rasters per mosaic |
The maximum number of rasters that can be mosaicked per request. This will prevent the server from needing to open and perform processing on large numbers of rasters for a single request. If the client's request requires more than this number of rasters to be accessed, then only this number of rasters will be accessed. None of the pixels for the additional rasters will be returned potentially resulting in gaps in the resulting image. It is recommended that overviews be built so that the client will not end up with gaps in the display. Applicable to the mosaic dataset only. |
|
Allowed mosaic methods |
The allowable mosaic methods for the image service. The possible mosaic methods include the following:
Applicable to the mosaic dataset only. |
Catalog parameters
These parameters apply when the Catalog capability is checked.
|
Parameter |
Description |
|---|---|
|
Maximum number of records returned per request |
The limit on the number of records transmitted per transaction. If the user’s request exceeds this value, then the image returned uses the maximum allowed rasters. Applicable to the mosaic dataset only. |
|
Raster metadata level |
The metadata that will be transmitted to the client:
Applicable to the mosaic dataset only. |
|
Allowed fields |
This is a list of fields in the attribute table that are transmitted to the client. Uncheck the fields that you don't want a client to view or be able to use in a query. Applicable to the mosaic dataset only. |
Download parameters
When allowing download on an image service, be sure to check the Download capability on the Imaging property page. Also, in addition to the properties below, be sure to configure the output directories on the Parameters properties page.
These parameters affect the load on the server and the access users have to the source images.
|
Parameter |
Description |
|---|---|
|
Maximum number of items downloadable per request |
The maximum number of rasters that the user can download at one time. Applicable to the mosaic dataset only. |
Manage downloaded directories | Allows you to map the physical directories where the images are located to a virtual directory where the image URLs will be mapped. When allowing download, it is critical that the service uses a directory that points to the source rasters of the mosaic dataset. This prevents a huge performance bottleneck that would otherwise occur as the service copies files from the mosaic dataset source directory to the server output directory. The virtual directory provides web applications' access to files created by the ArcGIS server via a URL address. The virtual directory should point to the same disk location as the output directory. You must create the virtual directory in your web server and link it to the physical directory on disk. Refer to your web server documentation on how to create virtual directories. Applicable to the mosaic dataset only. |
Maximum download size per request | This is the total number of megabytes that can be downloaded at one time. Applicable to the mosaic dataset only. |
Parameters to control image service content
Editing parameters
If an image service is created from a mosaic dataset, you can configure the image service to act as a repository for your clients by allowing clients to add their raster data to the mosaic dataset. Once added, the same clients may edit the properties of the data they added or remove it.
These parameters apply when the Editing capability is checked.
Editing cannot be used when serving a referenced mosaic dataset.
Parameter | Description |
|---|---|
Manage dynamic image workspaces | Directory location, accessible from the server and mosaic dataset, where the raster data will be uploaded and stored. This must be set; otherwise, the editing operations cannot be used by the service. Applicable to the mosaic dataset only. |
Editor Info | Choose to add a realm to the user name when applying edits so they can be tracked. When you access a secured image service, ArcGIS for Server remembers the user's name and their edits. ArcGIS for Server will also append any realm that has been configured on the image service. Applicable to the mosaic dataset only (with editor tracking enabled on the mosaic dataset). |
Operations allowed on items added by other users |
Applicable to the mosaic dataset only (with editor tracking enabled on the mosaic dataset). |
Allowed types for add | Choose one or more raster types from which clients can pick when adding raster data to an image service. Applicable to the mosaic dataset only. |
Manage custom types | If you need clients to add data not defined by the basic raster types, you can select one or more raster-type files (.art). Raster-type files can be created and edited in the Add Rasters To Mosaic Dataset tool by opening the raster type's properties and saving the file. Applicable to the mosaic dataset only. |
Parameters to control on-the-fly processing
Function parameters
Functions allow the image service data to be processed by the server to provide specific products to the client. Some functions are exposed directly, such as Hillshade and Slope; however, all the functions that can be applied to the raster data in ArcGIS for Desktop can be exposed to clients using raster function templates. The following parameters control the on-the-fly, server-side processing using functions that will be exposed to clients.
|
Parameter |
Description |
|---|---|
|
Allow client specified rendering rules |
If checked, then clients can access and control the server-side rendering and processing. If unchecked, then the client cannot access and request any server-side rendering. Applicable to all inputs. |
|
Convert Colormap to RGB |
If your raster dataset has a colormap, you can choose to publish it as an RGB image, thereby applying the colormap to the image. This will impact the pixel values since the values will be changed from a single value and associated colormap to a three-band pixel value. To retain the colormap and allow a user to query the pixel based on its colormap, you should not select this option. This applies to raster datasets with a colormap, or when using a raster dataset layer or mosaic dataset using the Colormap function. Applicable to all inputs. |
Manage raster function templates | You can provide one or more function chains that can be used to process the data in the image service. When applied, these functions are applied on the server and the result is transmitted to the user or application. These function chains are created in the Raster Function Template Editor and saved as .rft.xml files, created in ArcMap, that can be applied to the image service. These are provided to allow web applications to perform various on-the-fly processing on the data in the image service. You can choose a default function chain that is applied whenever the image service is used. This is especially useful when using an image service with data that looks better when it is stretched. ArcMap will apply a stretch, but web applications typically cannot; therefore, you can be sure it will always look the way you want if you define the stretch using a function chain. Learn more about server-side processing Applicable to all inputs. |
Parameters to control image mensuration
Mensuration parameters
ArcGIS provides a set of tools for image mensuration, including tools to measure point, distance, area, and height from an image. You can choose whether you want the image service to participate in the ArcGIS image mensuration.
Applicable to all inputs.
|
Parameter |
Description |
|---|---|
|
Allowed mensuration methods |
These allowed methods are derived from the source's mensuration capabilities and listed as part of the dataset's properties. They determine the mensuration tools that can be used with the image service.
Applicable to all inputs. |
|
Elevation Source |
If there is a preferred and available elevation source that should be used when mensurating, you can point to it here. This will allow the user to make measurements in 3D. Valid elevation sources include raster datasets, image service SOAP URLs, and image service layers. If the elevation image service requires authentication, then you should use an image service layer. Applicable to all inputs. |
ComputeTiePoints REST operation
In 10.2 and later versions, image services support a new ComputeTiePoints REST operation. It generates tie points between a raster in the mosaic dataset and a preconfigured reference image. To enable computing tie points on an image service published from a mosaic dataset, follow these steps:
- Log in to the ArcGIS Server Administrator Directory. The URL is typically formatted http://gisserver.domain.com:6080/arcgis/admin.
- Find your service and click Edit.
- Locate the string "maxImageHeight".
- Insert the referenceImage to compute tie points. The referenceImage can be one of the following:
- An image service SOAP URL
- A tiled map service
- A local raster or mosaic dataset
- A layer file pointing to an image service
- Click Save Edits.
In 10.2 and later versions, image services support a new GetSamples REST operation. It generates sample point locations, pixel values, and corresponding spatial resolutions of the source data for a given geometry. The maximum number of sample locations is approximately 1,000 by default, and can be customized by the service author by using the following configuration property: "maxSampleCount":1000,.
Improving the display performance of image services using the cacheControlMaxAge property
When clients send requests to ArcGIS Server to display an image service, the response from the server is typically cached by the browser and reused for a certain period of time. This behavior helps ArcGIS Server achieve the best possible display performance for your image service. However, depending on how your image service and its associated data are used in applications, you may consider adjusting the length of time the browser will use a response in its cache. This can be achieved by adding a property called cacheControlMaxAge to the JavaScript Object Notation (JSON) of the service.
How the cacheControlMaxAge property is used
ArcGIS Server image service responses include a entity tag (ETag) and Cache-Control header. The ETag header value is a unique identifier of the response. The Cache-Control header has a max-age value that provides information to the browser regarding the maximum time period for which it can reuse a response from the browser's cache. This value is controlled by the cacheControlMaxAge property.
When a request is repeated and the maximum age of the cache has not expired, the browser will use the cached response without sending the request to the server. If the maximum age has expired, the browser must send the request to the server and set an IF-NONE-MATCH header with an associated ETag value corresponding to the response in its cache. ArcGIS Server evaluates the request and uses the ETag value to determine if the response has changed. If the response from the server is different from the copy on the browser, the server will send a completely new response to the browser. If the response is identical to the copy on the browser, the server alerts the browser to continue to use the response in its cache.
Defining the value of the cacheControlMaxAge property
As an ArcGIS Server administrator, you can define the cacheControlMaxAge property to specify how long a browser is allowed to use a cached response. By mitigating the need for ArcGIS Server to send a full response, you allow your browser caches to be more efficient, help optimize your applications, and save network bandwidth.
The default value for image services is 12 hours (43200 seconds). This means that if a request is repeated within 12 hours, the browser will use the response from its cache. This value works well for most applications.
For image services with frequently changing datasets or symbology, a value such as 5 minutes (300 seconds) is recommended. In applications with animations or time-aware data, you should consider increasing the value to give your application a smoother animation experience.
To add the cacheControlMaxAge property to your service and specify its default value, do the following:
- In a web browser, open the ArcGIS Server Administrator Directory and log in with a user that has administrator privileges. The URL is formatted http://gisserver.domain.com:6080/arcgis/admin.
- Click services and select the image service you want to modify from the Services list. If you don't see your service listed, it may be in a directory under the Root folder.
- On the Service - <service name> (<service type>) page, scroll to the bottom and click edit.
- In the Service Properties dialog box, locate the "properties" section of the service JSON.
- Add the cacheControlMaxAge property to the section and specify the value (in seconds) for the property, for example:
"properties": { "cacheControlMaxAge": "300", - Click Save Edits.
- On the Service - <service name> (<service type>) page, verify that the cacheControlMaxAge property and the value you specified for it appears in the Properties section.