utfGrid

URI

<map_uri>/utfgrid[.<format>]

支持的方法

父资源

介绍

utfGrid 资源把交互的地理数据编码成节省空间的数据切片。utfGrid 在客户端展示中使用，例如鼠标滑过包含地理要素的地图切片时，会自动显示鼠标提示。

将完整的地图以像素为单位切割成多个相同大小的格网，那么地图就可以由多个小块拼合而成。utfGrid 资源表示的就是这些小块对应的地理要素，并以字符画的形式呈现出来。通过对 utfGrid 资源执行 GET 请求，可以获取地图中相应格网的 utfGrid，可以在 URI 中包含一些定制的 utfGrid 参数，如设置图层、图片大小，格网行列号等。这些参数必须包含在 URI 中，不能放在请求体里。

utfGrid 是一个 JSON 格式的字符串，用来描述一张切片中每个像素所关联的地理要素信息。将地图瓦片中的地理要素信息用字符串表示。该 JSON 包含三个部分：

Grid 是一个字符串的数组，每个字符对应一个地理要素的 key。
Keys 是由 Key 构成的数组，每个 Key 对应一个地理要素。
Data 是由地理要素集合构成的一个 JSON 对象，可以通过 Data[key]的方式取出 key 对象的地理要素。

支持的方法：

GET：获取地图图层对应格网的地理要素信息的字符画，URI 中的参数确定了格网的位置等信息。
HEAD：检查 utfGrid 资源是否存在，权限是否可以访问。

支持的表述格式：RJSON、JSON、HTML、JSONP、FASTJSON。

资源层次

HTTP 请求方法

对如下 URI 执行 HTTP 请求，以 rjson 输出格式为例加以说明，其中，supermapiserver 是服务器名，“世界地图”是地图名（{mapName}）。

http://supermapiserver:8090/iserver/services/map-world/rest/maps/世界地图/utfGrid.rjson

GET 请求

获取地图图层对应瓦片的地理要素信息的字符画，URI 中的参数确定了字符画瓦片的位置等信息。

请求参数

对 utfgrid 资源执行 GET 请求，获取地图瓦片的地理要素，需要在 URI 中包含相关参数，如果没有指定参数，则会按照地图的当前状态为准，进行切割。参数如下所示：

名称	类型	含义
x	int	格网在地图中列号，从左向右递增。默认情况下，切片从地图最左上角开始，其格网列号为0。
y	int	格网在地图中行号，从上向下递增。默认情况下，切片从地图最左上角开始，其格网行号为0。
scale	double	地图的比例尺。如0.0001表示比例尺为1：10000。详见比例尺的定义。
width	int	格网的宽度，单位是像素，默认为 256 像素。
height	int	格网的高度，单位是像素，默认为 256 像素。
pixCell	int	格网中的每个单元格像素宽度。如 pixCell=2，在 width=256,height=256大小的格网中，每个单元格为2x2的像素构成，返回结果的 grid 字符串数组 length 为256/2=128。
layerNames	String[]	指定图层的名称列表，支持的类型为矢量图层（点、线、面及文本图层），目前支持传入一个图层，例如：layerNames=['Countries%40World']。
origin	Point2D	切片的起始参考点，默认为地图范围的左上角。如果指定为其他值，则以所赋值作为切片的起始参考点，计算切片行列号。如对示范数据中的“世界地图”设置了切片起始点为 origin={"x":-200,"y":45}，则 origin 位于行列号为（0，0）的切片左上角，同时位于行列号为（-1，-1）的切片的右下角。
_cache	boolean	是否使用缓存，默认为 true。如果为 false，则关闭所有缓存。
random	boolean	是否采用随机数的方式出图，默认为 false。如果为 true，则 scale、x、y 三个参数中未指定的参数会在各自的取值范围内采用随机数的方式赋值。
filters	String[]	针对图层的属性条件过滤，该数组与 layerNames 数组中的图层对应，例如：filters=['sqkm=420.77 and smid>200']。

响应结构

如果获取地图图层相应格网的地理要素信息，可指定表述格式为 RJSON、JSON、HTML、JSONP，则返回的表述结构如下：

	类型	说明
grid	String	是一个字符串的数组，每一个字符对应一个地理要素
keys	String	key 构成的数组，每一个 ke 对应一个地理要素的 SMID 字段
data	String	Data 是由地理要素集合构成的一个JSON 对象。可以通过 Data[key]的方式取出

响应示例

对 utfGrid 资源请求 layerNames=['Countries@World']时对应格网的地理要素信息。则需执行 GET 请求：http://localhost:8090/iserver/services/map-world/rest/maps/世界地图/utfGrid.rjson?scale=0.000000025632&x=0&y=1&width=256&height=256&pixCell=8&layerNames=['Countries@World']&prjCoordSys={"epsgCode":4326}

则返回的 rjson 的资源描述如下：

{ "data": { "1": { "CAPITAL": "莫斯科", "COLOR_MAP": "4", "CONTINENT": "亚洲", "COUNTRY": "俄罗斯", "POP_1994": "1.518276E8", "SMAREA": "2931.554593770361", "SMID": "1", "SMPERIMETER": "1536.1744180956796", "SMUSERID": "0", "SQKM": "1.6911282E7", "SQMI": "6529445.0" }, "188": { "CAPITAL": "华盛顿", "COLOR_MAP": "2", "CONTINENT": "北美洲", "COUNTRY": "美国", "POP_1994": "2.58833E8", "SMAREA": "1116.6706382613484", "SMID": "188", "SMPERIMETER": "726.1061295947409", "SMUSERID": "0", "SQKM": "9449362.0", "SQMI": "3648398.75" } }, "grid": [ "!!!!!!!!!!!! ################", "!!!!!!!!!!!!! ##############", " !!!!! ##############", " #### #########", " #### ############", " ##############", " #############", " ## ##############", " ## ###############", " ########", " ########", " ###", " #####", " ####### ", " ####### ", " # ###### ", " ## # # ", " ## ## ", " ## ## ", " # ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " " ], "keys": [ "", "1", "188" ] }

HEAD 请求

返回跟 GET 请求一样的 HTTP 响应头，但是没有响应实体。可以在不必传输整个响应内容的情况下，获取包含在响应消息头中的元数据信息。元数据信息包括媒体类型，字符编码，压缩编码，实体内容长度等。

HEAD 请求可以用来判断 utfGrid 资源是否存在，或者客户端是否有权限访问 utfGrid 资源。通过对加.<format>的 URI 执行 HEAD 请求，还可以快速判断 utfGrid 资源是否支持<format>格式的表述。