ezdxf 坐标标注(Ordinate Dimension)完整实战指南:全局/局部特征点、LCS 旋转与测量文字控制
ezdxf 坐标标注(Ordinate Dimension)完整实战指南:全局/局部特征点、LCS 旋转与测量文字控制
坐标标注(Ordinate Dimension)用于只关心目标位置的 x 或 y 坐标值、且所有尺寸都从同一个基准点(datum)出发的工程场景。本文以 ezdxf 官方教程 ordinate_dimension.rst 为主体,结合 dim_ordinate.py 渲染器与 graphicsfactory.py 工厂方法源码,系统讲解两种创建方式(全局特征点、局部特征点 + UCS)、局部坐标系(LCS)的旋转原理、测量文字的默认放置规则及其限制,并给出可直接运行的完整代码示例。
前置要求:请先阅读 ezdxf 线性尺寸教程 linear_dimension.rst,坐标标注中的测量文字覆盖、文字格式与样式、公差与极限等内容均与该教程共享同一套机制。此外需注意:ezdxf 并不会考虑全部 DIMSTYLE 变量,因此其渲染结果与 CAD 应用(如 AutoCAD、BricsCAD)存在差异,这是 ezdxf 官方文档明确声明的限制。
何时使用坐标标注
坐标标注适用于这样的场景:图形中每个"特征点"(feature location)的尺寸只需要给出 x 坐标或 y 坐标,而不需要同时标注两者。所有特征点的尺寸都从同一个基准位置出发,该基准位置在本教程中被称为"origin"(原点)。
典型的应用是:
- 机械加工图纸中大量孔位、角点的坐标定位;
- 只需单一坐标方向的连续特征测量;
- 需要保持测量基准统一、避免链式累计误差的场合。
在 DXF 中,坐标标注对应的 DIMENSION 实体类型为 DIM_ORDINATE,源码常量定义见 const.py:DIM_ORDINATE = 6,而 DIM_ORDINATE_TYPE = 64(64 位不置位表示 x 型标注,置位表示 y 型标注)。
局部坐标系(LCS)与测量基准
坐标标注的测量是在一个**局部坐标系(Local Coordinate System,LCS)**中完成的。该 LCS 由两个要素定义:
- origin:基准点(datum),即所有坐标测量的起点;
- rotation:LCS 绕渲染 UCS 的 z 轴旋转的角度。
默认情况下渲染 UCS 就是世界坐标系(WCS)。也就是说,LCS 是"以 origin 为原点、绕 z 轴旋转 rotation 角度"的坐标系,标注测量得到的数值是特征点在 LCS x 轴或 y 轴上的绝对投影距离,而不是两点间的相对距离。
在渲染器 dim_ordinate.py 中可以看到 LCS 的实现细节:
horizontal_direction(组码 51)按 DXF 规范的顺时针方向存储,渲染器读取时取负号转换为数学角度:self.horizontal_dir = -dimension.dxf.get("horizontal_direction", 0.0);- 局部 x 轴由该角度计算:
self.local_x_axis = Vec2.from_angle(self.rotation); - 局部 y 轴是 x 轴的正交向量:
self.local_y_axis = self.local_x_axis.orthogonal()。
测量值的计算见 update_measurement() 方法(dim_ordinate.py):x 型标注取特征点相对 origin 的向量在局部 x 轴上的投影长度,y 型标注取其在局部 y 轴上的投影长度,且"坐标标注的测量永远是绝对值"(ordinate measurement is always absolute),不做任何缩放换算之外的处理。
创建坐标标注的工厂方法
ezdxf 提供两个工厂方法(定义于 graphicsfactory.py):
| 工厂方法 | 类型 | 底层 dtype 参数 |
|---|---|---|
msp.add_ordinate_x_dim(...) |
x 型(测量 x 坐标) | dtype=1 |
msp.add_ordinate_y_dim(...) |
y 型(测量 y 坐标) | dtype=0 |
两者的完整签名(以 add_ordinate_dim 为核心实现,见 graphicsfactory.py):
msp.add_ordinate_x_dim(
feature_location, # 特征点位置(见下方全局/局部两种坐标系说明)
offset, # 引线终点相对特征点的偏移向量(在 LCS 中定义)
origin=NULLVEC, # LCS 原点,默认 (0, 0)
rotation=0.0, # LCS 绕 z 轴的旋转角度(度)
text="<>", # 测量文字模板
dimstyle="EZDXF", # 使用的 DIMSTYLE 名称
override=None, # DIMSTYLE 属性覆盖字典
dxfattribs=None, # DIMENSION 实体附加 DXF 属性
)
所有创建坐标标注的工厂方法都要求以**全局坐标(UCS 坐标)**定义特征点位置。各参数的核心含义(与源码 docstring 一致,graphicsfactory.py):
feature_location:特征点在全局坐标系(渲染 UCS,默认 WCS)中的位置;offset:引线终点相对特征点的偏移向量,在 LCS 中定义;origin:LCS 原点在 UCS 中的坐标;rotation:LCS 的旋转角度(度),该角度按 DXF 规范以顺时针方向存入horizontal_direction组码(代码中写为dxfattribs["horizontal_direction"] = -rotation);text:None或"<>"表示显示真实测量值;单个空格" "表示抑制测量文字;其他任意字符串作为测量文字显示;dimstyle:DIMSTYLE 表条目名,默认"EZDXF";override:DIMSTYLE 属性覆盖字典。
返回值:不是 DIMENSION 实体
重要:工厂方法返回的 dim 不是 DIMENSION 实体,而是 DimStyleOverride 对象,真正的 DIMENSION 实体存放在 dim.dimension 属性中。必须手动调用 dim.render() 才会生成包含标注几何图形的匿名 BLOCK(这是 AutoCAD 显示标注所必需的第二步),这一两步式流程允许你在创建实体与渲染之间对 DIMENSION 实体做额外处理。该行为在 dimstyleoverride.py 的 render() 方法中实现:它新建匿名 BLOCK、将 dimension.dxf.geometry 指向该 BLOCK 并调用渲染器。
另外,在创建实体时工厂方法会组合 DIMENSION 的 dimtype 标志:DIM_ORDINATE | DIM_BLOCK_EXCLUSIVE | (DIM_ORDINATE_TYPE * dtype)(graphicsfactory.py),DIM_BLOCK_EXCLUSIVE 表示该标注的几何图形存放在独占的匿名块中。
DIMENSION 实体中的定义点
坐标标注渲染器使用三个必需的定义点(见 dim_ordinate.py 与 get_defpoints() 方法):
| 定义点 | DXF 组码 | 含义 |
|---|---|---|
defpoint |
组码 10 | LCS 原点(origin) |
defpoint2 |
组码 13 | 特征点位置(feature location) |
defpoint3 |
组码 14 | 引线终点(end of leader) |
用户文字位置(组码 11)被渲染器忽略,并由 ezdxf 计算出的默认位置替换。
示例一:全局特征点(WCS 直接定义)
第一个示例直接在渲染 UCS(此处即 WCS)中定义特征点坐标,这也是 DIMENSION 实体期望的坐标形式。完整可运行代码见 dimension_ordinate_global_features.py:
import ezdxf
from ezdxf.math import Vec3
from ezdxf.render import forms
# Use argument setup=True to setup the default dimension styles.
doc = ezdxf.new(setup=True)
# Add new entities to the modelspace:
msp = doc.modelspace()
# Add a rectangle: width=4, height = 2.5, lower left corner is WCS(x=2, y=3)
origin = Vec3(2, 3)
msp.add_lwpolyline(
forms.translate(forms.box(4, 2.5), origin),
close=True
)
# Add an x-type ordinate DIMENSION with global feature locations:
msp.add_ordinate_x_dim(
# lower left corner
feature_location=origin + (0, 0), # feature location in the WCS
offset=(0, -2), # end of leader, relative to the feature location
origin=origin,
).render()
msp.add_ordinate_x_dim(
# lower right corner
feature_location=origin + (4, 0), # feature location in the WCS
offset=(0, -2),
origin=origin,
).render()
# Add an y-type ordinate DIMENSION with global feature locations:
msp.add_ordinate_y_dim(
# lower right corner
feature_location=origin + (4, 0), # feature location in the WCS
offset=(2, 0),
origin=origin,
).render()
msp.add_ordinate_y_dim(
# upper right corner
feature_location=origin + (4, 2.5), # feature location in the WCS
offset=(2, 0),
origin=origin,
).render()
# Necessary second step to create the BLOCK entity with the dimension geometry.
# Additional processing of the DIMENSION entity could happen between adding
# the entity and the rendering call.
doc.saveas("ord_global_features.dxf")
代码要点:
origin同时用于两个用途:既是矩形的定位点,也是坐标标注 LCS 的原点;- 每个角点分别添加一个 x 型标注(测 x 坐标)和一个 y 型标注(测 y 坐标),例如右下角点
(6, 3)的 x 坐标为 4(相对 origin 的 x 投影),y 坐标为 0; offset决定引线终点:x 型标注的(0, -2)表示引线终点位于特征点下方 2 个单位,y 型标注的(2, 0)表示引线终点位于特征点右侧 2 个单位;- 每个
add_ordinate_*_dim(...)调用后都必须紧跟.render()完成第二步渲染。
示例二:局部特征点(UCS + 局部坐标)
全局方式的问题在于:当 LCS 发生旋转时,手工换算全局特征点坐标变得非常繁琐。第二个示例展示了如何通过渲染 UCS(UCS 类)使用局部坐标定义特征点。完整代码见 dimension_ordinate_local_features.py:
import ezdxf
from ezdxf.math import Vec3, UCS
from ezdxf.render import forms
doc = ezdxf.new(setup=True)
msp = doc.modelspace()
# Create a special DIMSTYLE for "vertical" centered measurement text:
dimstyle = doc.dimstyles.duplicate_entry("EZDXF", "ORD_CENTER")
dimstyle.dxf.dimtad = 0 # "vertical" centered measurement text
# Add a rectangle: width=4, height = 2.5, lower left corner is WCS(x=2, y=3),
# rotated about 30 degrees:
origin = Vec3(2, 3)
msp.add_lwpolyline(
forms.translate(forms.rotate(forms.box(4, 2.5), 30), origin),
close=True
)
# Define the rotated local render UCS.
# The origin is the lower-left corner of the rectangle and the axis are
# aligned to the rectangle edges:
# The y-axis "uy" is calculated automatically by the right-hand rule.
ucs = UCS(origin, ux=Vec3.from_deg_angle(30), uz=(0, 0, 1))
# Add a x-type ordinate DIMENSION with local feature locations:
# the origin is now the origin of the UCS, which is (0, 0) the default value of
# "origin" and the feature coordinates are located in the UCS:
msp.add_ordinate_x_dim(
# lower left corner
feature_location=(0, 0), # feature location in the UCS
offset=(0.25, -2), # leader with a "knee"
dimstyle="ORD_CENTER",
).render(ucs=ucs) # Important when using a render UCS!
msp.add_ordinate_x_dim(
# lower right corner
feature_location=(4, 0), # feature location in the UCS
offset=(0.25, -2), # leader with a "knee"
dimstyle="ORD_CENTER",
).render(ucs=ucs) # Important when using a render UCS!
# Add a y-type ordinate DIMENSION with local feature coordinates:
msp.add_ordinate_y_dim(
# lower right corner
feature_location=(4, 0), # feature location in the UCS
offset=(2, 0.25), # leader with a "knee"
dimstyle="ORD_CENTER",
).render(ucs=ucs) # Important when using a render UCS!
msp.add_ordinate_y_dim(
# upper right corner
feature_location=(4, 2.5), # feature location in the UCS
offset=(2, 0.25), # leader with a "knee"
dimstyle="ORD_CENTER",
).render(ucs=ucs) # Important when using a render UCS!
doc.saveas("ord_local_features.dxf")
代码要点:
- UCS 定义:
UCS(origin, ux=Vec3.from_deg_angle(30), uz=(0, 0, 1))以矩形左下角为原点、x 轴指向 30 度方向、z 轴为 (0,0,1)。未给出的 y 轴由右手定则自动计算——这正是 UCS 构造器 的行为:缺失的轴由已给轴的叉积得到并归一化; - 局部特征点:
feature_location=(0, 0)、(4, 0)、(4, 2.5)均为 UCS 局部坐标,无需手工换算;此时origin参数可省略(默认 (0,0),即 UCS 原点); - 必须传
ucs=ucs:.render(ucs=ucs)是使用渲染 UCS 的关键一步。渲染器在transform_ucs_to_wcs()(dim_ordinate.py)中把所有定义点(defpoint、defpoint2、defpoint3、text_midpoint)从 UCS 变换到 WCS/OCS,并把horizontal_direction变换为 OCS 角度(注意符号取反,因为组码 51 是顺时针方向); - 带"膝弯"的引线:
offset=(0.25, -2)这类在特征点同侧给出一小段水平/垂直偏移(0.25)再垂直延伸的偏移量,会在引线上产生一个折点(knee),用于避免引线与文字或图元重叠; - 自定义 DIMSTYLE:
doc.dimstyles.duplicate_entry("EZDXF", "ORD_CENTER")从默认样式EZDXF复制出ORD_CENTER,再设置dimstyle.dxf.dimtad = 0(测量文字垂直居中)。EZDXF是 ezdxf 默认尺寸样式,由setup_dimstyles()在 standards.py 中创建。
引线(Leader)几何的生成
两条示例中可见的"折线式引线"由 add_ordinate_leader() 方法生成(dim_ordinate.py),其几何结构为三段线:
/---1---TEXT
x----0----/
- 特征点 (x) 到第一个转折点 0:沿测量方向的正交方向延伸(
start0到end0),其中已包含延伸线偏移量extension_lines.offset,且至少保证一段leg_size = arrows.arrow_size * 2.0的长度; - 转折点 0 到点 1:水平/垂直连接到引线终点方向;
- 点 1 到引线终点:最后一段短线段(长度
leg_size),若测量文字垂直放置非居中(vertical_placement != 0),还会额外加上半个文字框宽度。
引线使用第一延伸线的 DXF 属性(颜色、线型等,attribs = self.extension_lines.dxfattribs(1)),引线方向始终垂直于测量方向。
测量文字的放置规则
ezdxf 的坐标标注渲染器对测量文字位置有一项明确限制:文字始终放置在默认位置,原因在于引线终点的位置由工厂方法中的 offset 参数给出,这本身已经提供了灵活的测量文字放置手段。
具体而言(dim_ordinate.py):
- 不支持用户自定义文字位置:
get_default_text_location()的注释明确指出"user text location is not supported and ignored",传入的text_midpoint(组码 11)会被默认位置覆盖; - 不支持用户文字旋转:
get_default_text_rotation()同样忽略用户旋转,文字旋转角度固定为(90.0 if self.x_type else 0.0) + self.horizontal_dir——即 x 型标注文字旋转 90 度(沿 y 轴方向书写)、y 型标注文字旋转 0 度,并叠加 LCS 的水平方向角; - 文字始终对齐 LCS 的 x 轴和 y 轴:文字方向与局部坐标系的轴向一致,这是坐标标注的典型外观(x 型标注文字垂直于 x 轴阅读,y 型标注文字沿 x 轴方向阅读)。
默认文字位置的计算公式(get_default_text_location()):
text_location = end_of_leader
+ measurement_orthogonal * (text_box.width * 0.5)
+ text_vertical_shifting_dir * measurement.text_vertical_distance()
即:以引线终点为基准,沿测量正交方向偏移半个文字框宽度,再按文字的垂直放置方式(由 dimtad 等 DIMVAR 决定)偏移一段文字垂直距离。
调整文字位置的推荐手段:既然用户位置被忽略,就应该通过 offset 参数控制引线终点(进而控制文字位置),或像示例二那样通过 dimstyle.dxf.dimtad 控制文字的垂直对齐(0 = 垂直居中,1 = 上方,4 = 下方等,具体取值与线性尺寸教程一致)。ezdxf 的默认样式 EZDXF 设置 dimtad = 1(文字在标注线上方,见 standards.py),示例二中的 ORD_CENTER 正是把它改为 0 实现垂直居中。
测量文字覆盖、格式与公差
坐标标注的以下三项功能与线性尺寸完全共享同一套机制,ezdxf 官方教程明确指向线性尺寸教程的相关章节(linear_dimension.rst):
覆盖测量文字(Overriding Measurement Text)
参考线性尺寸教程的 Overriding Measurement Text 一节。核心机制:通过 DIMENSION 实体的 text 属性覆盖真实测量值:
- 特殊值
" "(单个空格):完全抑制测量文字; - 空字符串
""或"<>":显示真实测量值; - 其他字符串:原样显示为测量文字。
所有尺寸工厂方法都提供显式的 text 参数,该参数始终覆盖 dxfattribs 中的 text 值。例如 text=">1m" 可以显示自定义前缀文本。在坐标标注中调用方式相同:msp.add_ordinate_x_dim(..., text="CUSTOM")。
测量文字的格式与样式(Formatting and Styling)
参考线性尺寸教程的 Measurement Text Formatting and Styling 一节,可用的 DIMVAR 包括:
| DIMVAR | 作用 |
|---|---|
dimtxsty |
测量文字使用的文字样式名 |
dimtxt |
文字高度(绘图单位) |
dimclrt |
测量文字颜色(ACI) |
dimtfill / dimtfillclr |
文字背景填充开关与填充颜色(DXF R2007+) |
dimdec |
小数位数(DXF R2000+) |
dimdsep |
小数点字符(ASCII 码) |
dimrnd |
测量距离取整值 |
dimzin |
零抑制(4=抑制前导零,8=抑制尾随零,12=两者) |
dimlfac |
测量比例因子(如 1 绘图单位 = 1m、需要以 cm 显示时设为 100) |
dimpost |
文字模板,<> 代表测量值(如 "~<>cm") |
推荐使用 DimStyleOverride.set_text_format 或 DimStyle.set_text_format 方法设置这些值。
公差与极限(Tolerances and Limits)
参考线性尺寸教程的 Tolerances and Limits 一节。要点:
- 公差与极限通过 MTEXT 实体的内联代码实现,因此需要 DXF R2000 及以上版本;DXF R12 文件中不会被显示(渲染器在 dim_base.py 中检测到不支持 MTEXT 时会自动关闭公差与极限渲染);
- 公差与极限不能同时使用;
- 推荐使用 DimStyleOverride.set_tolerance 和 set_limits 方法设置,它们会自动管理
dimtol、dimlim、dimtp、dimtm、dimtfac、dimtolj、dimtdec、dimtzin等 DIMVAR; - 坐标标注的测量值处理流程与公差联动:渲染器在初始化时执行
if self.tol.has_limits: self.tol.update_limits(self.measurement.value)(dim_ordinate.py),保证极限上下限基于真实测量值计算。
综合示例脚本
仓库中的 dimension_ordinate.py 是更完整的演示脚本,覆盖了上述所有要点:
ordinate_wcs():在 WCS 中分别用rotation=0和rotation=30两种旋转创建多组 x/y 型坐标标注,遍历dimtad取值为 1(上方)、0(居中)、4(下方),并针对每个特征点向四个方向((±1, ±3))放置引线;ordinate_ucs():通过UCS(origin, ux=Vec3.from_deg_angle(rotate), uz=(0, 0, 1))在 30 度旋转的 UCS 中创建标注,复用ORD_CENTER样式;- 演示了
override字典的用法(如override<a href="https://link.gitcode.com/i/73d57840d0d530b548907f04438b645e" target="_blank">"dimtad"] = dimtad)以及dim.render(discard=BRICSCAD)的可选参数——discard=True会丢弃生成的几何 BLOCK(仅适用于 BricsCAD 这类会自动渲染标注的 CAD 应用,AutoCAD 会拒绝打开缺少几何 BLOCK 的 DIMENSION 实体,见 [dimstyleoverride.py 的说明)。
运行该脚本会生成三个 DXF 文件:ordinate_wcs_R2013.dxf、ordinate_rot_30_deg_wcs_R2013.dxf 与 ordinate_ucs_R2013.dxf。
常见问题与限制汇总
- 渲染结果与 CAD 应用不同:ezdxf 不实现全部 DIMSTYLE 变量(共 80 多个),官方教程与源码 docstring(graphicsfactory.py)均明确提示这一限制;
- DXF R12 特性受限:公差/极限(依赖 MTEXT)、部分 DIMVAR(如
dimltype、dimtxsty)在 DXF R12 中不支持或不被写入文件,ezdxf 只写入所用 DXF 版本支持的 DIMVAR 以避免生成无效 DXF 文件; - 文字位置/旋转不可自定义:坐标标注渲染器固定使用默认文字位置与固定文字旋转,只能通过
offset、dimtad等 DIMVAR 间接调整; - 不存在的 DIMSTYLE 会回退:引用了不存在的 DIMSTYLE 时,DXF 导出(
save/saveas)时会被替换为Standard样式(该规则在线性尺寸教程中说明,对坐标标注同样适用),因此务必先用ezdxf.new(setup=True)建立默认样式; - 必须两步式创建:忘记调用
.render()将导致 DXF 中只有 DIMENSION 实体而没有几何 BLOCK,AutoCAD 无法正常显示。
通过以上两个可直接运行的示例(全局特征点版 dimension_ordinate_global_features.py 与局部特征点版 dimension_ordinate_local_features.py),你可以快速在 ezdxf 中生成带基准原点、支持 LCS 旋转的 x/y 型坐标标注,并利用 offset、DIMSTYLE 覆盖与 UCS 渲染掌握测量文字与引线的完整控制手段。若需进一步查阅 DIMVAR 图形化参考与高级信息,可阅读 dimstyle_table.rst;创建自定义 DIMSTYLE 的方法可参考 standards.py 中的 setup_dimstyle() 实现。

