要素查询 / 几何

分类代号：C.3 本章共 4 个接口

本章汇集所有"拿到几何 / 属性 / 投影"的基础操作。其中 queryFeatures 是最常用的接口，根据 querytype 可覆盖点/矩形/表达式/条件 4 种查询场景，因此 SDK 只暴露一个 query_features(querytype=...) 统一入口。

---

快速索引

---

26 · 要素查询 queryFeatures

URL：POST /api/v1/map/cmd/queryFeatures/{mapid}/{version}
SDK：svc.query_features(querytype, ...) / svc.queryFeatures({ querytype, ... })

querytype 枚举

⚠️ expresion 是后端拼写，不是 expression。

⚠️ limit/beginpos 分页（GeomRender）：rect（有无 bounds）+ limit:3 返回 3 条，不传 limit 默认上限 100；condition + limit/beginpos 正常翻页。0 命中时返回 {}（无 recordCount/result 键），不是 {recordCount:0}。point 查询不传 maxReturnCount 时后端强制按 1 处理（传了则按所传值）。

⚠️ 图形引擎部分响应 Content-Type 不规范（octet-stream 里实为 JSON）。SDK 已按首字符嗅探自动解析；手写 fetch 时注意不能只看 content-type。

可选参数（所有 querytype 通用）

注意：point/rect 分支不读 limit，要用 maxReturnCount。geom 不是"返回几何"的开关（那是 includegeom/realgeom），而是命令路由开关：缺省按该图的打开方式路由；geom:true 走几何库进程；geom:false 强制走内存进程——内存进程只实现 point/rect/expresion，condition 一律回 {"error":"not support query type!"}。所以从未以 GeomRender（geom:true）打开过的图（缺省路由看 mapinfos ini 里该版本的 geom 标记；旧版 SDK 因发 mapopenway 而非 geom，新建的图都是这样）做不了 condition 查询；一般不传 geom，图按 GeomRender 打开过即可。

响应结构

{
  "recordCount": 5,
  "result": [
    {
      "id": 1,
      "objectid": "EA_ED__EE_#",
      "layerindex": 13,
      "name": "AcDbArc",
      "geojson": "...",
      "envelop": "POLYGON(...)",
      "bounds": "[minx,miny,maxx,maxy]",
      "isEnvelop": true,
      "color": -65281,
      "linetype": "BYLAYER",
      "xdata": "",
      "center": "x,y,z",
      "points": "x1,y1,z1;x2,y2,z2;...",
      "colorIndex": 6
    }
  ]
}

• recordCount：后端实际扫到的全量数量，不是本次返回条数。想分页时根据 recordCount + beginpos 自行控制。
• geojson 是字符串而非对象，调用方需要再 JSON.parse()。
• isEnvelop=true 说明 geojson 被替换成了 envelop（单条太大或命中 maxGeomBytesSize）。

实采（rect 查询 sys_zp/v1，limit=5）

{
  "recordCount": 5,
  "result": [{
    "id": 1,
    "objectid": "EA_ED__EE_#",
    "layerindex": 13,
    "name": "AcDbArc",
    "geojson": "{\"type\":\"GeometryCollection\",\"geometries\":[{\"type\":\"Polygon\",\"coordinates\":[[[2271440.45,-685837.25],[2271440.45,-679783.61],[2276451.33,-679783.61],[2276451.33,-685837.25],[2271440.45,-685837.25]]]}]}",
    "envelop": "POLYGON((2271440.45 -685837.25, ... ))",
    "bounds": "[587661158.58,3103885970.22,587661256.00,3103886087.91]",
    "isEnvelop": true,
    "color": -65281,
    "linetype": "BYLAYER"
  }]
}

实采（condition 查询，limit=1）

{
  "recordCount": 6982,
  "result": [{
    "id": 1,
    "name": "AcDbArc",
    "geojson": "",
    "envelop": "POLYGON(...)",
    "bounds": "[...]",
    "isEnvelop": false,
    "color": -65281,
    "center": "587661197.39,3103886029.19,-152738.04",
    "points": "x1,y1,z1;x2,y2,z2;x3,y3,z3",
    "colorIndex": 6
  }]
}

recordCount=6982 表示该地图共 6982 个要素满足条件；limit=1 只取第一条。

Python

# 矩形查询：sys_zp/v1 全图前 5 条
meta = svc.open_map(mapid="sys_zp", version="v1", mapopenway=MapOpenWay.GeomRender)
x1, y1, x2, y2 = [float(x) for x in meta["bounds"][1:-1].split(",")][:4]
res = svc.query_features(
    querytype="rect",
    mapid="sys_zp", version="v1",
    x1=x1, y1=y1, x2=x2, y2=y2,
    limit=5,
)
for item in res["result"]:
    print(item["id"], item["name"])

# 点查询：屏幕 5 像素范围
res = svc.query_features(
    querytype="point",
    x=587661197.39, y=3103886029.19,
    zoom=10,
    pixelsize=5,
    pixel_to_geo_length=100.0,
    limit=3,
)

Node.js

const res = await svc.queryFeatures({
  querytype: 'rect',
  mapid: 'sys_zp', version: 'v1',
  x1, y1, x2, y2, limit: 5,
});

const byExpr = await svc.queryFeatures({
  querytype: 'expresion',
  expr: "layerindex=13",
  limit: 10,
});

curl

curl -X POST "http://127.0.0.1:27660/api/v1/map/cmd/queryFeatures/sys_zp/v1?token=$TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"querytype":"condition","layername":"","zoom":1,"limit":1}'

---

27 · 构造实体几何 createEntityGeoData

URL：POST /api/v1/map/cmd/createEntityGeoData/_null/v1
SDK：svc.create_entity_geo_data(mapdata=..., map_extent=..., render_accuracy=..., exclude_attribute=..., use_zip=...)

mapdata 是前端绘图模块构造的 DWG 结构体（JSON 字符串）。独立使用场景较少，通常和前端绘图配合。后端特判：mapdata 内含 "isSvgData": 时会先走 imageSvgToDwg 把 SVG 转成 DWG 结构再生成几何。

请求参数

响应

• 合法输入：{ "result": [...], "bounds": "...", ... }（与 queryFeatures 类似）

---

28 · 坐标转换 coordtransform

URL：POST /api/v1/map/cmd/coordtransform/_/_
SDK：svc.coord_transform(srs=..., crs=..., points=..., four_parameter=..., is_inverse_four_parameter=...)

请求参数

SDK 的 points 接受：

• 单点 (x,y) 或 {"x":1,"y":2}
• 多点 [(x1,y1),(x2,y2)]
• fourParameter 支持 "x,y,s,r" 或 [x,y,s,r]

响应（实采：4326 → 3857 两点）

{
  "points": [
    [12957254.769864663, 4852582.082864688],
    [13522423.824622115, 3662655.1833045874]
  ]
}

Python

res = svc.coord_transform(
    srs="EPSG:4326",
    crs="EPSG:3857",
    points=[(116.397, 39.908), (121.474, 31.23)],
)
print(res["points"])  # [[12957254.77, 4852582.08], [13522423.82, 3662655.18]]

Node.js

const res = await svc.coordTransform({
  srs: 'EPSG:4326',
  crs: 'EPSG:3857',
  points: [[116.397, 39.908], [121.474, 31.23]],
});
console.log(res.points);

---

29 · WKT → PROJ4 prjWktToPrj4Str

URL：POST /api/v1/map/cmd/prjWktToPrj4Str/_/_
SDK：svc.prj_wkt_to_prj4_str(wkt, from_="")

请求参数

响应（实采：WGS84 WKT）

{ "proj4": "+proj=longlat +datum=WGS84 +no_defs" }

Python

wkt = open("sample.prj", encoding="utf-8").read()
res = svc.prj_wkt_to_prj4_str(wkt)
print(res["proj4"])

Node.js

import { readFileSync } from 'node:fs';
const wkt = readFileSync('sample.prj', 'utf8');
const res = await svc.prjWktToPrj4Str(wkt);
console.log(res.proj4);

---