- URL:https://<imageservice-url>/getSamples
- Required Capability:Image
- Version Introduced:10.2
Description
The getSamples operation is performed on an image service resource and is supported by both mosaic dataset and raster dataset image services.
The result of this operation includes sample point locations, pixel values, and corresponding spatial resolutions of the source data for a given geometry. When the input geometry is a polyline, envelope, or polygon, sampling is based on sampleCount or sampleDistance; when the input geometry is a point or multipoint, the point or points are used directly.
The number of sample locations in the response is based on the sampleDistance or sampleCount parameter and cannot exceed the limit of the image service (the default is 1,000, which is an approximate limit).
The sample location that will be used is the intersection of the geometry and the raster item's footprints, which are filtered by the mosaicRule and the pixelSize.
You can provide arguments to the getSamples operation as query parameters defined in the following parameters table:
Request parameters
Parameter | Details |
---|---|
geometry (Required) | A geometry that defines the locations to be sampled. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. Applicable geometry types are point, multipoint, polyline, polygon, and envelope. When spatialReference is omitted in the input geometry, it will be assumed to be the spatial reference of the image service. Syntax
Example
|
geometryType (Required) | The type of geometry specified by the geometry parameter. The geometry type can be point, multipoint, polyline, polygon, or envelope. Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope |
sampleDistance | The distance interval used to sample points from the provided path. The unit is the same as the input geometry. If neither sampleCount nor sampleDistance is provided, no densification can be done for paths (polylines), and a default sampleCount (100) is used for areas (polygons or envelopes). Example
|
sampleCount | The approximate number of sample locations from the provided path. If neither sampleCount nor sampleDistance is provided, no densification can be done for paths (polylines), and a default sampleCount (100) is used for areas (polygons or envelopes). Example
|
mosaicRule | Specifies the mosaic rule defining the image sort order. Additional filtering can be applied to the WHERE clause and FIDs of a mosaic rule. See the mosaic rule JSON objects for the syntax and examples. |
pixelSize | The raster that is visible at the specified pixel size in the mosaic dataset will be used for sampling. If pixelSize is not specified, the service's pixel size is used. The structure of the esri_codephpixelSize parameter is the same as the structure of the point object returned by the ArcGIS REST API. In addition to the JSON structure, you can specify the pixel size with a simple comma-separated syntax. |
returnFirstValueOnly | Indicates whether to return all values at a point, or return the first non-NoData value based on the current mosaic rule. The default is true. Values: true | false |
interpolation | Added at 10.3. The resampling method. The default is nearest neighbor. Values: RSP_BilinearInterpolation | RSP_CubicConvolution | RSP_Majority | RSP_NearestNeighbor |
outFields | Added at 10.3. The list of fields to be included in the response. This list is a comma-delimited list of field names. You can also specify the wildcard character (*) as the value of this parameter to include all the field values in the results. Example
|
sliceId | Added at 10.9. The slice ID of the multidimensional raster. This parameter is available if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider. Syntax
Example
|
time | Added at 10.9. The time instant or time extent of the raster to be sampled. This parameter is only valid if the image service supports time and if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider. Syntax
Note:A null value specified for start time or end time will represent infinity for start or end time, respectively. Example
|
f |
The response format. The default response format is html. Values: html | json |
Example usage
Sample multiple points
https://myserver/arcgis/rest/services/myimage/ImageServer/getSamples?geometryType=esriGeometryMultipoint&geometry={"points":[[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]],"spatialReference":{"wkid":4326}}&f=json
Sample pixel values along a given path
https://myserver/arcgis/rest/services/myimage/ImageServer/getSamples?geometryType=esriGeometryPolyline&geometry={"paths":[[[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]],[[-97.06326,32.759],[-97.06298,32.755]]],"spatialReference":{"wkid":4326}}&sampleCount=20&f=json
JSON Response syntax
{
"samples": [
{
"location": <point>,
"value": "<value1>";
"rasterId": <rasterId>,
"resolution": <resolution>,
"locationId": <locationId1>,
"attributes": {
"fieldname1": <value>,
...
}
},
{
"location": <point>,
"value": "<value2>";
"rasterId": <rasterId>,
"resolution": <resolution>,
"locationId": <locationId2>,
"attributes": {
"fieldname1": <value>,
...
}
}
]
}
JSON Response example
{
"samples": [
{
"location": {
"x": -8844874,
"y": 5401062,
"spatialReference": {
"wkid": 3857
}
},
"value": "287,395,1228",
"rasterId": 5,
"resolution": 4,
"locationId": 1
},
{
"location": {
"x": -8834874,
"y": 5408062,
"spatialReference": {
"wkid": 3857
}
},
"value": "855,926,1089",
"rasterId": 2,
"resolution": 1,
"locationId": 2
}
]
}