DWG SDK API 文档

UTUM Data Engine（UDE）当前以 dwg_sdk 为主要 SDK 包，面向 DWG 图纸的读取、对象查询、显示准备、Viewer 数据导出和指定范围的 DWG 写出。

本文档对应当前公共接口：

快速开始

读取一个 DWG

C++ API 使用 Runtime 创建运行时，用 Input 表示文件路径或内存数据，再通过 readDatabase() 得到不可变 Database 快照。

#include <iostream>
#include "dwg/sdk/sdk.hpp"

int main(int argc, char** argv) {
  if (argc != 2) return 2;
  auto runtime = dwg::sdk::Runtime::create();
  if (!runtime.ok()) return 1;
  auto result = runtime.value().readDatabase(
      dwg::sdk::Input::fromPath(argv[1]));
  if (!result.ok()) return 1;
  const auto info = result.value().database.info();
  const auto coverage = result.value().database.coverage();
  std::cout << info.version_marker
            << " objects=" << coverage.materialized_objects
            << " entities=" << coverage.decoded_entities << "\n";
  return 0;
}

ReadDatabaseReport 返回解析状态、Database、诊断集合和分阶段耗时。图纸对象、符号表和显示快照都依附于这个不可变数据库快照。

从内存读取

std::vector<std::uint8_t> bytes = loadBytes();
auto result = runtime.value().readDatabase(
    dwg::sdk::Input::fromMemory(bytes.data(), bytes.size()));

Input::fromPath() 和 Input::fromMemory() 是公共入口。需要自定义资源来源时，可以在 RuntimeOptions 中注入宿主服务。

包与构建

安装 UDE SDK 后，消费工程通过 CMake 查找 dwg_sdk 配置并链接 dwg_sdk 目标：

find_package(dwg_sdk CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE dwg_sdk)

公共头文件按功能放在 include/dwg/ 下：

核心调用流程

Runtime::create
    -> Runtime::readDatabase / Runtime::open
    -> ReadDatabaseReport
    -> Database
        -> objects / layers / blocks / layouts / entities
        -> prepareDisplay -> PreparedDisplay -> Viewer outputs

Runtime 管理运行时资源；Database、对象视图和符号视图持有只读快照租约。已经取得的数据库视图可以在会话关闭后继续查询。

DWG 读取与查询

Runtime

OpenOptions 可以选择 strict、audit 或 recovery 解析策略，并设置文件、解压数据、记录、对象和递归深度预算。

Database

分页查询返回 QueryPage<T>，包含当前页、总数、next_offset 和 has_more。大图纸应使用 next_offset 继续读取。

EntityView

对象转为实体视图后，可以按实体类型读取强类型数据：

auto object = database.openHandle(handle);
if (!object.ok()) return;
auto entity = object.value().asEntity();
if (!entity.ok()) return;
auto line = entity.value().line();
if (line.ok()) {
  // 使用 line.value().start 和 line.value().end
}

当前公共实体视图覆盖 LINE、CIRCLE、ARC、ELLIPSE、POINT、SOLID、TEXT/MTEXT、INSERT、DIMENSION、传统二维 POLYLINE、LWPOLYLINE、SPLINE、LEADER 和 HATCH。字段读取结果带有解析状态，调用方应先判断 Result<T>::ok()。

图层与布局

LayerView 提供名称、可见性、冻结、锁定、可打印状态、颜色和线型引用。LayoutView 提供布局名称、模型空间/图纸空间、页签顺序、块引用和视口分页。

布局选择使用 LayoutSelection：

auto model = dwg::sdk::LayoutSelection::modelSpace();
auto paper = dwg::sdk::LayoutSelection::paperSpace();
auto by_name = dwg::sdk::LayoutSelection::byName("Layout1");

名称重名时应使用 LayoutSelection::byId()。

未知对象

未知对象可以先通过 UnknownObjectView::rawSize() 查询大小，再用 copyRaw() 按单对象和总预算复制 record 或 payload。预算不足时返回明确错误，SDK 不返回截断缓冲区。

显示与 Viewer 导出

dwg::sdk::DisplayOptions options;
auto display = database.prepareDisplay(
    dwg::sdk::LayoutSelection::modelSpace(),
    options,
    dwg::sdk::OperationContext());
if (!display.ok()) return 1;

auto exported = display.value().exportViewerOutputs(
    "output/render.bin", "output/entities.bin");

DisplayOptions 控制场景、几何、文字、代理文字、外部参照和 RenderPlan 选项。字体和外部 DWG 资源通过 DisplayResources 或 HostServices 显式提供。

PreparedDisplay::visitDisplayItems() 按显示顺序访问原生图元和代理布局项，回调返回 false 时停止遍历。Runtime::convert() 适合一次性转换；prepareDisplay() 适合需要查询、显示和导出共用同一快照的应用。

编辑与写出 DWG

编辑入口使用显式事务：

auto editor = runtime.value().openEditor(
    dwg::sdk::Input::fromPath("input.dwg"));
if (!editor.ok()) return 1;
auto transaction = editor.value().startTransaction();
if (!transaction.ok()) return 1;

auto status = editor.value().setEntityColorIndex(entity_id, 3);
if (!status.ok()) {
  transaction.value().abort();
  return 1;
}
if (!transaction.value().commit().ok()) return 1;
auto report = editor.value().writeFile("output.dwg");

当前编辑接口包括图层、ACI/真彩色、LINE、CIRCLE、TEXT、ARC、LWPOLYLINE、INSERT 的修改，以及 LINE/CIRCLE 的新增和实体删除。writeFile() 写入文件，writeToMemory() 写入内存缓冲区。具体可写实体和目标版本由运行时能力报告与写出结果共同决定。

C ABI

C ABI 使用不透明句柄、版本化结构体、显式销毁和状态码，适合 C、C#、Rust、Go 或其他 FFI 宿主封装。

当前 ABI 版本为 1.1，仍兼容 1.0 协商。调用方必须按 struct_size 和 abi_version 初始化结构体，并在使用完成后调用对应的 destroy 函数。

状态与错误

C++ API 通过 dwg::core::Result<T> 返回成功值或错误。解析状态可能是 ok、partial、unsupported、unresolved、recovered、budget_exceeded、cancelled 或 failed。

C ABI 将粗粒度调用状态和详细错误原因分开返回。应用应记录 dwg_error_code()、dwg_error_reason_code()、解析状态以及诊断集合中的消息，不要只根据一个布尔值判断整张图纸是否完整。

支持的 DWG 版本

写入能力以当前 SDK 构建的能力报告和 WriteReport 为准。DWG 版本标记表示文件格式，同一标记可以对应多个 AutoCAD 年份。

示例与交付内容

SDK 安装包包含读取数据库、遍历模型空间、查询图层、读取未知对象、准备指定布局显示和 C ABI 查询示例。示例统一使用已安装的 dwg_sdk 目标和公共头文件。

接口稳定性

Runtime、Database、对象/实体/符号视图、分页查询、显示准备、Viewer 导出、C ABI 1.0/1.1 和编辑写出入口属于当前公开 SDK API。直接访问内部模型指针、内部 Scene/Geometry 类型和实现身份信息属于实现层接口。

如果需要新增实体字段、格式版本或宿主语言绑定，请通过联系咨询获取对应 SDK 版本和授权包。