图框图元下载

接口概述

根据图框 ID 下载该图框内的图元数据，响应以附件形式直接返回 gzip 压缩的 JSON 文件（{frameId}-Entities.json.gz），而不是通用的 { code, message, data } 响应结构。

图元数据量通常较大，接口按「文件下载」语义设计：调用方应把响应流直接写入本地文件，并按下载场景设置超时与重试策略，避免单次请求长时间阻塞。下载得到的是 gzip 压缩包，解压后即为一个完整的图元 JSON 文件。

frameId 来自图框基本信息结果获取接口返回的 data[].frameId。

请求地址

http

GET /result/pre/download/drawingFrameEntities

请求头

参数	必填	说明
apiKey	是	API 访问凭证，值为 `YOUR_API_KEY`

查询参数

参数	类型	必填	说明
frameId	String	是	图框唯一标识

请求示例

bash

# -o 让 curl 直接把响应流写入文件，避免内容进内存；
# 图元文件较大时需放宽整体超时时间（示例为 10 分钟）
curl -G "https://openapi.bangtu-ai.com/openApi/result/pre/download/drawingFrameEntities" \
  -H "apiKey:  YOUR_API_KEY" \
  --data-urlencode "frameId=frame-001" \
  --connect-timeout 10 \
  --max-time 600 \
  -o frame-001-Entities.json.gz

下载得到的 frame-001-Entities.json.gz 是 gzip 压缩文件，需先解压再解析，例如执行 gunzip frame-001-Entities.json.gz，解压后得到 frame-001-Entities.json。

返回结果

调用成功时返回 HTTP 200 与文件流：

响应头	值
Content-Type	`application/octet-stream`
Content-Disposition	`attachment;filename*=utf-8''{frameId}-Entities.json.gz`
Cache-Control	`no-cache`

响应体是 gzip 压缩的图元文件：解压后为一个完整的 JSON 对象，由 protobuf 消息 EntityList 直接转换而来，字段结构见下节图元结构。

响应体是二进制 gzip 流（文件头 magic number 为 1F 8B），不是明文 JSON。gzip 只做压缩、不打包多个文件，解压后即得到单个图元 JSON 文件（如 {frameId}-Entities.json）；可用 gunzip、Java GZIPInputStream 等解压。

触发下载的是 Content-Disposition: attachment 响应头，浏览器/客户端据此把响应体保存为文件；Content-Type 固定为 application/octet-stream，表示响应体是待保存的文件流，不需要内联渲染。文件名取自 Content-Disposition 的 filename*，不要用 Content-Type 判断文件名或格式。

服务端把已生成的 gz 文件按固定缓冲区分块原样写出，不做解压与转换，因此下载得到的文件与预审阶段生成的图元 gz 文件完全一致。

图元结构

顶层结构

gzip 解压后的 JSON 是一个对象，按 CAD 实体类型分成 29 个数组字段，每个数组承载该类型的图元列表。29 个 key 始终存在，图纸中没有该类型图元时对应 value 为空数组 []。

key	实体类型	说明
AcDbLine	直线	起点、终点
AcDbPolyline	轻量多段线	顶点列表、线宽、凸度、闭合
AcDb2dPolyline	二维多段线	顶点列表、点类型、凸度
AcDbArc	圆弧	圆心、半径、起止角、弧长
AcDbCircle	圆	圆心、半径
AcDbEllipse	椭圆/椭圆弧	中心、主次轴、起止角
AcDbText	单行文字	文字内容、对齐方式、字高、四角点
AcDbMText	多行文字	文字行列表、对齐、分栏
AcDbAttribute	块属性	含 `AcDbText` 全部字段，另有标记
AcDbAttributeDefinition	属性定义	含 `AcDbText` 全部字段，另有标记、提示
AcDbBlockReference	块参照	块名、块内图元 ID、剪裁边界
AcDbMInsertBlock	多重插入块	含 `AcDbBlockReference` 全部字段，另有行列数与间距
AcDbHatch	填充	图案名、边界信息、图案线条
AcDbTable	表格	行列数、单元格文字、合并单元格
AcDbAlignedDimension	对齐标注	测量值、标注文字、尺寸线
AcDbRotatedDimension	转角标注	同对齐标注，另有标注线角度
AcDb2LineAngularDimension	两点角度标注	两条测量线、弧线位置
AcDbLeader	引线	起终点、箭头、引线顶点
AcDbMline	多线	多线样式、每条线的点集
AcDbPoint	点	坐标、粗细
AcDbSolid	二维实体	顶点列表
AcDbTrace	迹线	顶点列表
AcDbSpline	样条曲线	是否闭合、控制点
AcDbWipeout	遮罩	顶点列表
AcDbViewport	视口	模型/布局空间范围、UCS 变换、视口内图元
AcDbPolyFaceMesh	多面网格	顶点列表、面的顶点索引
AcDbRasterImage	光栅图像	位置、UV 方向、图像文件
AcDbOle2Frame	OLE 对象	位置、显示宽高、文档类型
AcDbProxyEntity	代理实体	仅通用字段

通用字段 `super`

每个实体对象都包含 super 字段（protobuf 消息 entityObject.EntityObject），承载图元公共属性：

字段	类型	说明
id	String	图元 ID
objEntityName	String	图元名称，如 `AcDbLine`
layerFollow	String	所属图层
color	Color	颜色
visibility	Boolean	是否可见
isPlottable	Boolean	是否可打印
normalVector	Vector3d	法向量
referenceInfo	ReferenceInfo[]	块参照变换信息
blockReferenceBorder	Position[]	块裁剪边界点
isBlockReferenceBorder	Boolean	是否为裁剪边界
lineWeight	Double	线宽
isDash	Boolean	是否虚线线型
dashLength	Double[]	虚线段长列表
linetypeScale	Double	线型比例
lineTextList	String[]	线型内文字
minPoint	Position	图元包围盒最小点
maxPoint	Position	图元包围盒最大点
xDir / yDir / ORG	Vector3d	WCS 转 UCS 的 X 轴、Y 轴、原点
block	String	从属块的 ID
inClipArea	Boolean	是否在裁剪区域内
MBlockX / MBlockY	Double	多重插入块变换参数
orderedIndex	Integer	图元顺序索引（`AcDbWipeout` 覆盖时使用）
linetypeStr	String	线型字符描述
linetypeInt	Integer	线型枚举

referenceInfo 元素（ReferenceInfo）字段：basePointx、basePointy（变换原点）、rotate（旋转角）、xFactor / yFactor（变换因子）、transformInfo（{ xDir, yDir } 参照块变换矩阵）。

基础类型

类型	字段	说明
Position	x, y	二维坐标点
Vector3d	x, y, z	三维向量/点
Color	red, green, blue	颜色分量
IntList	intRep[]	整数列表（如多面网格的面的顶点索引）
BoolList	boolRep[]	布尔列表
DoubleList	doubleRep[]	浮点列表（如视口变换矩阵，按行展开）
TextInfo	center, text[], rotate, visibility	块参照内文字信息（已弃用）
HatchLine	startPoint, endPoint	填充线条
BorderData	lines[], arcs[], polylines[], ellipse[], nurbCurve[]	填充边界
PatternLines	offset, angle, dash[], basePoint	填充图案线
PolylineArc	pointindex, center, radius, startAng, endAng, samplePoints, startPoint, endPoint, deg	多段线中的弧线段
TableText	textString, textHeight	表格单元格文字
TableMergedRow	rowFlags[], rowSize[], rowColor[]	表格合并单元格信息
MlineStyle	name, showMiters, startSquareCap, endSquareCap, startRoundCap, endRoundCap, startInnerArcs, endInnerArcs, startAngle, endAngle, filled, fillColor, numElements, offset[], lineColor[]	多线样式
MlinePoints	point[]	多线中一条线上的所有点

各实体类型字段

除 super 外，各类型自身字段如下（字段为 [] 表示数组）。

AcDbLine（直线）

字段	类型	说明
startPoint	Position	起点
endPoint	Position	终点

AcDbPolyline（轻量多段线）

字段	类型	说明
numverts	Integer	顶点数量
points	Position[]	顶点列表
lineWeightList	Position[]	线宽列表
firstDerivList	Vector3d[]	一阶导数列表
arcindex	PolylineArc[]	弧线段信息
lineindex	Integer[]	直线段索引
isClosed	Boolean	是否闭合
area	Double	围合面积

AcDb2dPolyline（二维多段线）

字段	类型	说明
points	Position[]	顶点列表
lineWeightList	Position[]	线宽列表
polyType	Integer	多段线类型
isClosed	Boolean	是否闭合
bulges	Double[]	突起值，用于转弧线
pointsType	Integer[]	每个顶点的类型：0 普通顶点、1 样条拟合控制点、2 样条拟合生成点、3 曲线拟合生成点

AcDbArc（圆弧）

字段	类型	说明
center	Position	圆心
startPoint	Position	起点
samplePoint	Vector3d	取样点，一般为弧线中点
endPoint	Position	终点
startAngle	Double	起始角（弧度）
endAngle	Double	终止角（弧度）
radius	Double	半径
length	Double	弧长
isClock	Boolean	是否顺时针绘制
isExcellenceArcFlag	Boolean	是否为精确圆弧标记

AcDbCircle（圆）

字段	类型	说明
center	Position	圆心
radius	Double	半径

AcDbEllipse（椭圆/椭圆弧）

字段	类型	说明
center	Position	中心
startAngle / endAngle	Double	起止角（弧度）
majorAxis / minorAxis	Double	主轴、次轴长度
startpoint / endpoint	Position	起始点、终止点
normal	Vector3d	法向量
rotate	Double	主轴偏移角
startAngleDraw / endAngleDraw	Double	绘图用起止角（角度制，绘制时取负值）
cadRotate	Double	主轴偏移角（前端绘图用）

AcDbText（单行文字）

字段	类型	说明
fontHeight	Double	字高
textString	String	文字内容
position	Position	基准点
alignmentPoint	Position	对齐点
horizontalMode	Integer	水平对齐：0 Left、1 Center、2 Right、3 Align、4 Mid、5 Fit
verticalMode	Integer	垂直对齐：0 Base、1 Bottom、2 Mid、3 Top
rotation	Double	旋转角
widthFactor	Double	宽度因子
width	Double	文字宽度
topleft / bottomright / bottomleft / topright	Position	文本框四角点
isMirroredInX / isMirroredInY	Integer	X/Y 方向镜像
bottomleftOrg / rotationOrg	Position / Double	块变换前的左下点与旋转角（前端绘图用）

AcDbMText（多行文字）

字段	类型	说明
fontHeight	Double	字高
position	Position	文字位置
rotation	Double	旋转角
textString	String[]	文字内容行列表
width / actualWidth / actualHeight	Double	文本框宽度、文字实际宽度与高度
attachment	Integer	对齐点
topleft / bottomright / bottomleft / topright	Position	文本框四角点
lineSpacingFactor	Double	行间距因子
mode	Integer	文字模式
horizontalMode / verticalMode	Integer	水平、垂直对齐方式
bottomleftOrg / rotationOrg	Position / Double	块变换前的左下点与旋转角
columnType	Integer	分栏类型：0 不分栏、1 静态分栏、2 动态分栏
columnAutoHeight	Boolean	分栏高度自适应
columnCount / columnWidth / columnGutterWidth	Integer / Double / Double	分栏数量、栏宽、栏间距
columnFlowReversed	Boolean	分栏是否反向排列
columnHeightList	Double[]	各栏高度

AcDbAttribute（块属性）/ AcDbAttributeDefinition（属性定义）

super 类型为 AcDbText，即包含上表全部文字字段，另有：

字段	类型	说明
tag	String	属性标记
prompt	String	提示（仅 AcDbAttributeDefinition）
isPreset	Boolean	是否使用预置值（仅 AcDbAttribute）

AcDbBlockReference（块参照）

字段	类型	说明
blockName	String	块名
entitylist	String[]	块内图元 ID 列表
clipPoints	Position[]	剪裁边界点
isClipInverted	Boolean	是否反向裁剪
rotate	Double	旋转角
scanMinPoint / scanMaxPoint	Position	图元可见的最小、最大点
textInfoList	TextInfo[]	块内文字列表（已弃用）

AcDbMInsertBlock（多重插入块）

super 类型为 AcDbBlockReference，包含上表全部字段，另有：

字段	类型	说明
columns / rows	Integer	列数、行数
columnSpacing / rowSpacing	Double	列间距、行间距
rotation	Double	旋转角

AcDbHatch（填充）

字段	类型	说明
isGradient	Boolean	是否渐变色
isSolid	Boolean	是否实心填充
associative	Boolean	边界是否关联
backgroundColor	Color	背景色
backgroundColorFlag	Boolean	是否启用背景色
patternName	String	图案名称
hatchColor	Color	填充颜色
hatchlines	HatchLine[]	填充线条（非实心填充）
area	Double	填充区域面积
data	BorderData[]	填充边界信息
plines	PatternLines[]	填充图案线条
looptype	Integer[]	边界 loop 类型
hatchStyle	Integer	填充样式：0 Normal、1 Outer、2 Ignore
patternAngle	Double	图案角度（弧度，取值 [0, 0.628)）
patternScale	Double	图案比例

AcDbTable（表格）

字段	类型	说明
position	Position	基准点
width / height	Double	表格宽、高
numRows / numColumns	Integer	行数、列数
direction	Integer	行列方向
rowHeightList / columnWidthList	Double[]	各行高、各列宽
textList	TableText[]	单元格文字列表
mergedInfo	TableMergedRow[]	合并单元格信息

AcDbAlignedDimension（对齐标注）

字段	类型	说明
xLine1Point / xLine2Point	Position	测量对象点 1、点 2
dimLinePoint / dimLine1Point	Position	测量线点
value	Double	测量值
text	String	标注文字
cadShow	String	计算后 CAD 实际显示值，显示优先级低于 `text`
dimfac / dimscale	Double	标注比例、标注全局比例
textPosition / textRotate / textFontHeight	Position / Double / Double	标注文字位置、旋转角、字高
textLineSpaceFactor	Double	文字行间距因子
textAttachmentFlag	Integer	文字对齐方式
useDefaultTextPos	Boolean	是否使用默认文字位置
linePoints / subBlkPoints	Position[]	尺寸线顶点列表、点列表
dimrnd / dimasz	Double	标注舍入、箭头大小
dimsd1 / dimsd2	Boolean	尺寸线 1、2 开关
valueShow	Double	已弃用

AcDbRotatedDimension（转角标注）

字段与对齐标注一致，另多一个 rotation（Double，标注线角度）。

AcDb2LineAngularDimension（两点角度标注）

字段	类型	说明
arcPoint	Position	弧线位置
xLine1Start / xLine1End	Position	测量对象线 1 起点、终点
xLine2Start / xLine2End	Position	测量对象线 2 起点、终点
value	Double	测量值
text / cadShow	String	标注文字、CAD 实际显示值
textPosition / textRotate / textFontHeight	Position / Double / Double	文字位置、旋转角、字高
textLineSpaceFactor / textAttachmentFlag / useDefaultTextPos	Double / Integer / Boolean	文字行间距因子、对齐方式、是否使用默认位置
dimfac / dimscale / dimrnd / dimasz	Double	标注比例、全局比例、舍入、箭头大小
linePoints / subBlkPoints	Position[]	直线顶点列表、点列表
dimsd1 / dimsd2	Boolean	尺寸线 1、2 开关
valueShow	Double	已弃用

AcDbLeader（引线）

字段	类型	说明
startPoint / endPoint	Position	引线起点、终点
hasArrowHead	Boolean	是否带箭头
arrowheadSize	Double	箭头尺寸
vertices	Position[]	引线点集
annoWidth	Double	标注宽度
dimscale	Double	标注全局比例

AcDbMline（多线）

字段	类型	说明
numVertices	Integer	顶点数
justification	Integer	多线对正方式
scale	Double	多线比例
closedMline	Boolean	是否闭合
mlStyle	MlineStyle	多线样式
mlinePoints	MlinePoints[]	计算后每条多线上的点集

AcDbPoint（点）

字段	类型	说明
position	Position	点坐标
thickness	Double	粗细

AcDbSolid（二维实体）/ AcDbTrace（迹线）

字段	类型	说明
points	Position[]	顶点列表

AcDbSpline（样条曲线）

字段	类型	说明
isClosed	Boolean	是否闭合
controlpoints	Position[]	控制点列表

AcDbWipeout（遮罩）

字段	类型	说明
verts	Position[]	顶点列表

AcDbViewport（视口）

字段	类型	说明
viewCenter / centerPoint	Position	布局空间中心点、模型空间中心点
width / height	Double	布局空间宽、高
viewWidth / viewHeight	Double	模型空间宽、高
viewzoom	Double	模型/布局缩放比例
maxPoint / minPoint	Position	布局空间最大、最小点
viewMaxpoint / viewMinpoint	Position	模型空间最大、最小点
frozenLayer	String[]	冻结图层
xDir / yDir	Vector3d	布局空间 UCS 变换 X、Y 轴
modelXDir / modelYDir	Vector3d	模型空间 UCS 变换 X、Y 轴
entitylist	String[]	视口内图元 ID 列表
mswcs2pswcs	DoubleList	模型空间到布局空间的 4×4 变换矩阵

AcDbPolyFaceMesh（多面网格）

字段	类型	说明
numVertices / numFaces	Integer	顶点数、面数
positionList	Position[]	顶点列表
vertexIndexList	IntList[]	每个面的顶点索引（从 1 开始计数）
isEdgeVisibleList	BoolList[]	每个面的边是否可见

AcDbRasterImage（光栅图像）

字段	类型	说明
position	Position	图像左下角
uDir / vDir	Position	图像 U、V 方向
size	Position	图像尺寸
sourceFileName	String	图像文件名
isClipped	Boolean	是否裁剪
isClipInverted	Boolean	是否反向裁剪
kShow	Boolean	是否显示图像
clipPoints	Position[]	裁剪点

AcDbOle2Frame（OLE 对象）

字段	类型	说明
wcsHeight / wcsWidth	Double	显示高度、宽度
location	Position	左上点
userType	String	文档类型
rowFilePath	String	文件存储地址

AcDbProxyEntity（代理实体）

字段	类型	说明
isTz	Boolean	代理实体标记

字段输出规则（解析要点）

命名映射：protobuf 字段名含下划线时按下划线转小驼峰，例如 layer_follow → layerFollow、sample_point → samplePoint、blockReferenceBorder 保持原样；不含下划线的字段名原样输出，因此实体类型 key 为大写开头的 AcDbLine，ORG、MBlockX、objEntityName 等也保持原样。
key 顺序按 protobuf 字段编号输出，调用方不要依赖字段顺序。
标量与数组字段总会出现：未设置时输出默认值（数值 0 / 字符串 "" / 布尔 false / 数组 []），无法与真实的 0 值区分；顶层 29 个数组字段同理，一定存在。
嵌套消息字段只在设置后才出现：例如圆的 center、直线的 startPoint、通用字段中的 color / normalVector / xDir 等，如果该图元没有对应数据，这些 key 会直接缺失，解析时必须判空，不要假定 key 一定存在。
继承关系用 super 嵌套表达：AcDbAttribute / AcDbAttributeDefinition 的 super 是 AcDbText 对象；AcDbMInsertBlock 的 super 是 AcDbBlockReference 对象（其内部还有自己的 super）。读取公共属性时需逐层进入 super。
坐标一般为 WCS 二维点（Position 只有 x、y），需要空间信息的字段使用 Vector3d（含 z）；角度除字段说明中特别标明外均为弧度。

示例

下面是一条图元及其顶层数组的真实输出（为便于阅读，省略了默认值字段与其余 27 个空数组）：

json

{
  "AcDbLine": [
    {
      "super": {
        "objEntityName": "AcDbLine",
        "layerFollow": "0",
        "color": { "red": 255, "green": 0, "blue": 0 },
        "visibility": true,
        "lineWeight": 0.25,
        "minPoint": { "x": 100.0, "y": 200.0 },
        "maxPoint": { "x": 300.0, "y": 200.0 },
        "id": "2F"
      },
      "startPoint": { "x": 100.0, "y": 200.0 },
      "endPoint": { "x": 300.0, "y": 200.0 }
    }
  ],
  "AcDbCircle": [
    {
      "super": { "layerFollow": "0", "id": "2F0" },
      "radius": 50.0
    }
  ]
}

大文件下载建议

图元文件体积可能达到几十 MB 甚至更大（gzip 压缩后仍可能达到几十 MB），请按下载文件的方式处理，避免单次请求长时间阻塞或客户端内存溢出：

响应体是 gzip 二进制流，请以二进制方式流式读取并写入本地文件，不要按文本读取，也不要把整个响应体读成字符串再落盘。
保留较短的连接超时（如 10 秒），同时把读超时设置得足够长（建议 5 分钟以上），大文件下载耗时会明显长于普通查询接口。
服务端不返回 Content-Length，采用分块（chunked）传输，因此拿不到下载进度百分比，可通过已接收字节数观察进度。
建议先下载到临时文件，解压 gzip 并确认 JSON 能完整解析后，再重命名/入库为正式文件，避免把不完整内容当成结果。
下载失败时（响应头中没有 Content-Disposition、响应体是明文错误 JSON 而非 gzip 流、或解压后 JSON 无法解析）应删除临时文件后重试。

失败响应

接口异常时返回通用 JSON 错误结构：

json

{
  "code": 500,
  "message": "系统繁忙，请稍后再试",
  "data": null,
  "timestamp": 1784533710000
}

成功响应的 Content-Type 为 application/octet-stream，失败响应为通用 JSON 错误结构（Content-Type: application/json）。调用方可通过 Content-Disposition 响应头是否存在来判断本次请求是否返回了文件，也可用 Content-Type 区分下载与错误报文。

调用流程

调用图纸基本信息识别任务创建接口，获取 taskId。
轮询任务状态查询接口，等待状态变为 SUCCESS。
调用图框基本信息结果获取接口，获取图框列表及 frameId。
使用 frameId 调用本接口下载图框图元文件。

注意事项

本接口是文件下载接口，响应体是 gzip 压缩的二进制流，请使用支持流式响应的 HTTP 客户端以二进制方式调用（如 curl -o、Java HttpClient 的 BodyHandlers.ofInputStream()），不要用「一次性读取响应体为字符串」的方式调用。
下载得到的文件为 {frameId}-Entities.json.gz，需先按 gzip 解压才能得到图元 JSON。
frameId 必须来自同一图纸识别任务的结果，否则会因查不到图框数据而失败。
图元文件可能较大，建议将响应流直接保存到本地文件，不要在内存中先拼接完整字符串。
响应未设置 Content-Length，采用分块输出，请不要通过响应体长度判断下载是否完整。
请按大文件场景设置客户端读超时，超时时间过短会导致下载被中途断开。
接口不做缓存，重复调用会重新读取图元 gz 文件并原样返回。
frameId 应按字符串传递，不要转换为数字。

图框图元下载 ​

接口概述 ​

请求地址 ​

请求头 ​

查询参数 ​

请求示例 ​

返回结果 ​

图元结构 ​

顶层结构 ​

通用字段 super ​

基础类型 ​

各实体类型字段 ​

字段输出规则（解析要点） ​

示例 ​

大文件下载建议 ​

失败响应 ​

调用流程 ​

注意事项 ​