URI
<dataset_uri>/imageValues[.<format>]
Supported methods
Parent resource
Introduction
imageValues indicates the pixel information value of an image dataset. Through sending a GET request on imageValues resource, you can query the pixel value information within a specified geographic extent, which includes band value, image row, image column, color and so on.
Supported Methods:
- GET: Gets the pixel value information within a specified geographic extent.
- POST: Queries the pixel value information by passing in multiple geographic extent.
- HEAD: Checks whether the imageValues resource exists or whether the client has permission to access the resource.
Supported output formats: RJSON, JSON, HTML, XML.
Resource hierarchy
HTTP request methods
Perform an HTTP request with the following URI, here we take rjson as the output format to demonstrate, where supermapiserver is the server name.
http://supermapiserver:8090/iserver/services/data-world/rest/data/datasources/World/datasets/WorldEarth/imageValues.rjson
GET request
Gets the pixel value information within a specified geographic extent.
Note: The maximum number of queries supported by iServer is 500,000. If the number of pixels in the target range exceeds 500,000, the system will report an error.
Request parameter
To acquire image information through implementing the GET request on imageValues resource, following parameters should be included in the URI:
| Name | Type | Description |
| bounds | String |
The geographic range. Querying rectangle, polygon, round range is supported. Such as: 1. Rectangle {"leftBottom":{"x":112.351881,"y":34.663401},"rightTop":{"x":113.361881,"y":35.673401}} 2. Polygon, need to specify not less than three sides: {"points": [{"x": 107.669629,"y": 32.888868},{"x": 108.012838,"y": 33.594138}, { "x": 108.674593, "y": 33.281041},{ "x": 107.669629,"y": 32.888868}]}3. Circle, need to specify the center point and radius: "circle":{"centerPoint":{"x":112.351881,"y":35.673401},"radius": 1}} |
Response structure
After performing a GET request on gridValues resource, the returned response body structure is as follows:
| Field | Type | Description |
| columnCount | int | The column number of pixel. |
| rowCount | int | The row number of pixel. |
| values | ImageValue[][] | Information for all pixels in the target range. Including raster row/column number, band or color value, pixel value and so on. Please reference imageValue for detail. |
| valuesCount | int | The pixel number in target range. |
Response example 1
The information of color value is returned after querying a 24-bit or 32-bit true color image. Sending get request to imageValues resources: http://supermapiserver:8090/iserver/services/data-world/rest/data/datasources/World/datasets/WorldEarth/imageValues.rjson?bounds={"leftBottom":{"x":112.351881,"y":34.663401},"rightTop":{"x":113.461881,"y":34.773401}} to get the pixel information of the dataset WorldEarth. The response is as follows:
{
"columnCount": 7,
"rowCount": 1,
"values": [[
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 50,
"green": 84,
"red": 74
},
"column": 1663,
"row": 314,
"value": 4871218
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 42,
"green": 77,
"red": 73
},
"column": 1664,
"row": 314,
"value": 4803882
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 45,
"green": 80,
"red": 76
},
"column": 1665,
"row": 314,
"value": 5001261
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 42,
"green": 77,
"red": 73
},
"column": 1666,
"row": 314,
"value": 4803882
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 34,
"green": 69,
"red": 65
},
"column": 1667,
"row": 314,
"value": 4277538
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 31,
"green": 66,
"red": 62
},
"column": 1668,
"row": 314,
"value": 4080159
},
{
"bounds": null,
"color": {
"alpha": 255,
"blue": 37,
"green": 73,
"red": 67
},
"column": 1669,
"row": 314,
"value": 4409637
}
]],
"valuesCount": 7
}
Response example 2
The band value bounds is returned for the image of other pixel format. Such as: getting the pixel information of worldimage dataset. Sending get request to imageValues resources: http://supermapiserver:8090/iserver/services/data-world/rest/data/datasources/World/datasets/worldimage/imageValues.rjson?bounds={"leftBottom":{"x":112.351881,"y":34.663401},"rightTop":{"x":112.361881,"y":34.673401}}, the response is as follows:
{
"columnCount": 1,
"rowCount": 2,
"values": [
[{
"bounds": [
232,
229,
193
],
"color": null,
"column": 8770,
"row": 1660,
"value": 0
}],
[{
"bounds": [
232,
232,
187
],
"color": null,
"column": 8770,
"row": 1659,
"value": 0
}]
],
"valuesCount": 2
}
POST request
Queries the pixel value information by passing in multiple geographic extent.
Request parameters
To get pixel value info by performing a POST request on imageValues resource, the following parameters should be contained in the request entity:
| Field | Type | Description |
| leftBottom |
JsonObject |
Used when inputting a rectangle, which specifies the left and bottom of the input rectangle. |
| rightTop |
JsonObject |
Used when inputting a rectangle, which specifies the right and top of the input rectangle. |
| points | JsonArray | Used when inputting a polygon, which specifies the position of points of the polygon. |
| circle |
JsonObject |
Used when inputting a circle. |
| centerPoint |
JsonObject |
Used to specify the central point of the input circle. |
| radius | int | Used to specify the radius of the input circle. |
| point |
jsonObject |
Used when inputting a point. Specifies the x and y coordinate of the input point. |
Response structure
The structure of the response entity is as follows:
| Field | Type | Description |
| columnCount | int | The column number of pixel. |
| rowCount | int | The row number of pixel. |
| values | ImageValue[][] | Information for all pixels in the target range. Including raster row/column number, band or color value, pixel value and so on. Please reference imageValue for detail. |
| valuesCount | int | The pixel number in target range. |
Response example
Execute a POST request on imageValues resource with URI: http://supermapiserver:8090/iserver/services/data-world/rest/data/datasources/World/datasets/WorldEarth/imageValues.json and the following request body:
[
{
"leftBottom": {
"x": 11.8504725147077,
"y": -37.1891792186755
},
"rightTop": {
"x": 12.0051569150709,
"y": -37.1065254101062
}
},
{
"circle": {
"centerPoint": {
"x": 112.351881,
"y": 35.673401
},
"radius": 0.1
}
}
]
the returned representation in rjson format is as follows:
[
{
"valuesCount": 1,
"values": [
[
{
"color": {
"red": 2,
"green": 5,
"blue": 20,
"alpha": 255
},
"column": 1091,
"bounds": null,
"row": 723,
"value": 132372,
"centerPoint": {
"x": 11.865234375,
"y": -37.177734375
}
}
]
],
"rowCount": 1,
"columnCount": 2
},
{
"valuesCount": 1,
"values": [
[],
[
{
"color": {
"red": 50,
"green": 64,
"blue": 28,
"alpha": 255
},
"column": 1663,
"bounds": null,
"row": 309,
"value": 3293212,
"centerPoint": {
"x": 112.412109375,
"y": 35.595703125
}
}
]
],
"rowCount": 2,
"columnCount": 2
}
]
HEAD request
Returns the same HTTP response header as the GET request, but no response entity, which can be used to retrieve the meta data contained in response message header without having to transmit the entire response content. Meta data information includes media type, character coding, compression coding, entity content length, etc.
HEAD request is used to determine whether the imageValues resource exists, or if the client has the authority to access it. By executing an HEAD request with a .<format> URI, you can quickly determine whether the imageValues resource supports the <format> representation.