【硬核干货】玩转 AutoCAD .NET API：全网最全 Dimension 标注家族大户口普查与实战指南

【硬核干货】玩转 AutoCAD .NET API：全网最全 Dimension 标注家族大户口普查与实战指南

各位掉发如雨、键盘冒烟的 CAD 二次开发大师们，好久不见！

在 CAD 二次开发的世界里，如果说几何算法是我们的“内功心法”，那标注（Dimension）绝对就是我们的“面子工程”。图纸画得再精准，标注一乱，秒变“车祸现场”。

今天我们就来彻底扒光 AutoCAD .NET API (Autodesk.AutoCAD.DatabaseServices) 中所有常见 Dimension 子类的底裤，看看到底怎么在代码里优雅地调教它们，顺便聊聊那些让人抓狂的底层几何坑。

一、 Dimension 家族大户口普查（核心表格）

为了方便大家“查字典”，我们先把最核心的成员、几何特征以及实战避坑指南列成一张表格。建议收藏，写代码时随时翻阅。

(线性标注) | XLine1Point

XLine2Point

DimLinePoint

Rotation | Rotation (弧度)

决定了标注轴线的方向。 | 最常用的线性标注！

· 水平标注：Rotation = 0，此时应统一两点的 $Y$ 轴对齐。

· 竖直标注：Rotation = Math.PI/2，此时应统一两点的 $X$ 轴对齐。

· 盲目使用“最近点”极易拉出畸形的 $Z$ 字形标注。 |
| AlignedDimension | 对齐标注 | XLine1Point

XLine2Point

DimLinePoint | 无独立角度，尺寸线永远平行于两测量点连线。 | 适用于标注倾斜的构件（如斜梁、斜倒角）。

注意：不要用它来代替水平/竖直标注，否则用户微调测量点时，标注线会跟着变斜！ |
| RadialDimension | 半径标注 | Center

ChordPoint

LeaderLength

TextPosition | ChordPoint：圆弧上的箭头点。

Center：圆心。 | 惊天大坑：当文字被拖出圆外生成折弯引线（Dogleg）时，TextPosition 根本不是文字的几何中心，而是引线和文字相交的挂钩点（Hook Point）！自动生成序号球时必须根据左右方向推开一整个文字宽度！ |
| DiametricDimension | 直径标注 | ChordPoint

FarChordPoint

LeaderLength

TextPosition | ChordPoint 与 FarChordPoint 构成直径线。 | 底层逻辑与 RadialDimension 完全一致。同样要注意 TextPosition 的挂钩点特性。 |
| RadialDimensionLarge | 折弯半径标注 | Center

ChordPoint

OverrideCenter

JogPoint | OverrideCenter：替代圆心。

JogPoint：折弯点。 | 适用于圆心超出了图纸边界的大圆弧标注。计算折弯点位置时，需要严谨的向量投影算法，否则折弯线会交叉乱飞。 |
| ArcDimension | 弧长标注 | Center

XLine1Point

XLine2Point

ArcPoint | ArcPoint：尺寸弧线通过的点。 | 用于标注圆弧的实际展开长度。注意它的文字上方默认会带一个“小弧长帽”符号（$⌢$）。 |
| LineAngularDimension2 | 两线角度标注 | XLine1Start, XLine1End

XLine2Start, XLine2End

ArcPoint | 两条显式直线的端点。 | 必须保证两条直线不平行（即有交点），否则抛异常。ArcPoint 决定的象限直接决定了标注的是锐角、钝角还是优角。 |
| Point3AngularDimension | 三点角度标注 | CenterPoint

XLine1Point

XLine2Point

ArcPoint | CenterPoint 为角度顶点。 | 哪怕图纸上没有实际的线段，只要指定三个点（顶点、起点、终点）就能强行标出角度。极其适合做算法工程中的虚拟特征标注。 |

二、 核心标注实战演练（源码级干货）

光说不练假把式，下面挑出我们在开发中最常蹂躏的三个大佬，奉上标准、严谨的代码模板。

1. 旋转标注（RotatedDimension）—— 规整的水平/竖直标注

在自动化出图（比如箱体、钢结构、模具）中，90%的尺寸链都是由它构成的。

public static void AddHorizontalOrVerticalDim(BlockTableRecord btr, Transaction trans, Point3d pt1, Point3d pt2, Point3d dimLinePt, bool isHorizontal)
{
    // 精细化几何对齐：如果是竖直标注，强行把尺寸线点的 X 坐标与测量点统一，防止拉斜
    // 如果是水平标注，则统一 Y 坐标
    double rotation = isHorizontal ? 0.0 : Math.PI / 2.0;
    
    RotatedDimension rotDim = new RotatedDimension(
        rotation,
        pt1,
        pt2,
        dimLinePt,
        "<>", // "<>" 代表让 AutoCAD 自动测量并显示真实数值
        ObjectId.Null // 传入 Null 代表使用当前默认的 DimStyle
    );

    // 设置图层和颜色规范（工程图推荐红色或特定标注图层）
    rotDim.ColorIndex = 1; 

    btr.AppendEntity(rotDim);
    trans.AddNewlyCreatedDBObject(rotDim, true);
}

2. 半径标注（RadialDimension）—— 别再让我的文字压线了

半径标注最让人抓狂的是：文字一旦拖出去，方向就反了，或者干起来直接盖在圆弧上。

public static void AddSafeRadialDimension(BlockTableRecord btr, Transaction trans, Point3d center, Point3d chordPt, double leaderLength)
{
    // 构造半径标注
    RadialDimension radDim = new RadialDimension(
        center,
        chordPt,
        leaderLength,
        "<>",
        ObjectId.Null
    );
    
    radDim.ColorIndex = 1;

    // 【避坑指南】手动调整 TextPosition 时，务必注意它在底层的“挂钩点”行为
    // 如果你希望文字在右边，TextPosition 应该在文字的左侧起始处
    // 这里我们先让 AutoCAD 默认生成，后续如果做符号球遮挡，需用算法进行 Full Width Push。

    btr.AppendEntity(radDim);
    trans.AddNewlyCreatedDBObject(radDim, true);
}

3. 三点角度标注（Point3AngularDimension）—— 特征提取必备

当你要给两根不相交的中心线，或者提取出的特征孔群标注角度时，用它最香。

public static void AddAngularDim(BlockTableRecord btr, Transaction trans, Point3d vertex, Point3d startPt, Point3d endPt, Point3d arcPt)
{
    Point3AngularDimension angDim = new Point3AngularDimension(
        vertex,   // 角度顶点
        startPt,  // 第一条边的端点
        endPt,    // 第二条边的端点
        arcPt,    // 标注弧线经过的位置（决定了半径和象限）
        "<>",
        ObjectId.Null
    );

    angDim.ColorIndex = 1;

    btr.AppendEntity(angDim);
    trans.AddNewlyCreatedDBObject(angDim, true);
}

三、 二次开发高级避坑玄学

作为常年跟 AutoCAD 数据库肉搏的专业选手，以下三条硬核经验请死死刻在脑子里：

1. TextPosition 的“精神分裂”

• 对于 RotatedDimension 和 AlignedDimension，TextPosition 默认是文字的正几何中心。你按照它的上下左右偏个 fontSize，妥妥没问题。
• 对于 RadialDimension 和 DiametricDimension，一旦引线折弯（Dogleg），TextPosition 就变成了引线折角的挂钩点！文字全在它的某一侧（左或右）。如果你算符号球（Balloon）坐标时还按“中心点”去加减偏移，你的符号球就会精准地压在尺寸文字的正中间，显得极不严谨。

2. 多段线（Polyline）非等比缩放的噩梦
   如果你的标注锚定在块引用（BlockReference）内部的几何顶点上，当这个块被非等比缩放（例如 $X$ 缩放 1.0，$Y$ 缩放 2.0）时，标注的 Measurement 可能会错乱，或者拉伸线直接爆掉。开发自动标注时，尽量在 WCS（世界坐标系）下动态计算最终的几何点位，不要过分依赖匿名块内部的原始坐标。
3. 智能文字避让的“高精度浮点校验”
   在编写尺寸链自动重叠避让算法（比如 ResetHorLocation）时，判断两个标注是否共线，千万不要用 ==。CAD 里的坐标经常产生 0.000000001 的扰动。必须使用高精度容差判定：

public static bool IsEqual(double a, double b, double tolerance = 1e-6)
{
    return Math.Abs(a - b) < tolerance;
}

结语

调教 CAD 的标注就像哄女朋友，你得摸透它的脾气（底层几何属性），知道它的痛点（TextPosition 的切换），它才能在图纸上给你展现出最完美、最规整的姿态。

下次写自动标注再遇到压字、方向反转、引线乱飞的问题，直接把这篇文章翻出来，对照着属性挨个排查，绝对药到病除！

如果你觉得有用，点个赞，点赞不秃头~
最后 ， 我是一名快乐的程序员 ， 周杰伦fans~