什么是基线（Baseline）What is the Baseline

在排版学和 CAD 绘图中，基线（Baseline）是文字字符所坐落的一条假想水平线。对于拉丁字母（如 a, b, c），字符的主体部分坐落在基线上，而下伸部分（如 g, p, y 的尾部）则会延伸到基线下方。In typography and CAD drawing, the baseline is an imaginary horizontal line on which text characters sit. For Latin letters (a, b, c), the main body rests on the baseline, while descenders (like g, p, y) extend below it.

在 DXF 的 TEXT 实体中，默认的插入点（组码 10/20/30）就位于文字的左端基线处。也就是说，当你输入一个 TEXT 实体而不指定任何对齐方式时，文字将从插入点开始向右侧延伸，字符底部坐落在基线上。这与 MTEXT 不同：MTEXT 默认的插入点位于文字的左上角。In DXF TEXT entities, the default insertion point (group codes 10/20/30) is at the left end of the baseline. When you create a TEXT entity without specifying alignment, text extends to the right from the insertion point with characters sitting on the baseline. This differs from MTEXT, whose default insertion point is at the top-left corner of the text.

TEXT 与 MTEXT 核心区别TEXT vs MTEXT Core Differences

TEXT 实体详解TEXT Entity in Detail

TEXT 是 DXF 中最基本的文字实体，用于表示单行文字。它的插入点、高度、旋转角度和对齐方式都由独立的组码控制。TEXT is the most basic text entity in DXF, representing a single line of text. Its insertion point, height, rotation angle, and alignment are controlled by independent group codes.

TEXT 专属组码TEXT-Specific Group Codes

TEXT 水平对齐（halign，组码 72）TEXT Horizontal Alignment (halign, code 72)

TEXT 垂直对齐（valign，组码 73）TEXT Vertical Alignment (valign, code 73)

MTEXT 实体详解MTEXT Entity in Detail

MTEXT（多行文字）是功能更强大的文字实体，支持多行显示、内嵌格式代码、段落设置和分栏。它的对齐方式由单一的 attachment_point 字段控制。MTEXT (multiline text) is a more powerful entity supporting multiple lines, inline format codes, paragraph settings, and columns. Its alignment is controlled by a single attachment_point field.

MTEXT 专属组码MTEXT-Specific Group Codes

MTEXT 附着点（attachment_point，组码 71）MTEXT Attachment Point (code 71)

MTEXT 的 attachment_point 用单个数值 1~9 表示九宫格位置，同时控制水平和垂直对齐：MTEXT’s attachment_point uses a single value 1-9 to represent a 3×3 grid position, controlling both horizontal and vertical alignment simultaneously:

对齐机制对比总表Alignment Mechanism Comparison

TEXT 对齐组合表TEXT Alignment Combination

默认基准点对比Default Anchor Point Comparison

如何理解 BBox（边界框）Understanding BBox (Bounding Box)

在 CAD 编程中，BBox（Bounding Box，边界框）是指能够完全包围一个实体的最小轴对齐矩形。对于文字实体，BBox 是计算文字渲染后的实际占据空间所得到的矩形。In CAD programming, BBox (Bounding Box) is the minimum axis-aligned rectangle that fully encloses an entity. For text entities, the BBox is calculated from the actual rendered space occupied by the text.

TEXT 的 BBoxTEXT BBox

TEXT 的 BBox 由以下因素决定：TEXT’s BBox is determined by:

• 文字内容：字符数量决定宽度Text content: character count determines width
• 文字高度（组码 40）：决定从基线到 ascent 的距离Text height (code 40): determines baseline-to-ascent distance
• 宽度因子（组码 41）：水平缩放比例Width factor (code 41): horizontal scale ratio
• 倾斜角度（组码 51）：使 BBox 倾斜Oblique angle (code 51): tilts the BBox
• 旋转角度（组码 50）：使整个 BBox 绕插入点旋转Rotation angle (code 50): rotates entire BBox around insertion point
• 文字样式：不同字体的字符宽度不同Text style: different fonts have different character widths

MTEXT 的 BBoxMTEXT BBox

MTEXT 的 BBox 更为复杂，因为：MTEXT’s BBox is more complex because:

• 包含多行文字，高度由行数和行间距决定Contains multiple lines; height depends on line count and spacing
• 每行可能有不同格式（高度、字体、颜色），导致各行高度不同Each line may have different formatting (height, font, color), causing varying line heights
• 自动换行使宽度受限于组码 41（参考矩形宽度）Automatic wrapping limits width to group code 41 (reference rectangle width)
• 内边距和段落间距也会贡献到总高度Padding and paragraph spacing also contribute to total height

BBox 的数学表达BBox Mathematical Expression

# 伪代码：BBox 结构
class BBox:
    min_x: float   # 包围盒左边界
    min_y: float   # 包围盒下边界
    min_z: float   # 包围盒前边界（通常文字在 XY 平面，Z=0）
    max_x: float   # 包围盒右边界
    max_y: float   # 包围盒上边界
    max_z: float   # 包围盒后边界

    @property
    def width(self) -> float:
        return self.max_x - self.min_x

    @property
    def height(self) -> float:
        return self.max_y - self.min_y

    @property
    def center(self) -> Point:
        return Point(
            (self.min_x + self.max_x) / 2,
            (self.min_y + self.max_y) / 2,
            (self.min_z + self.max_z) / 2
        )

text_size 与 mtext_size 方法text_size and mtext_size Methods

在 CAD 编程库（如 ezdxf）中，text_size 和 mtext_size 是用于计算文字实体渲染尺寸的工具函数。它们帮助开发者预估文字在图纸上的实际占据空间。In CAD programming libraries (like ezdxf), text_size and mtext_size are utility functions for calculating the rendered size of text entities. They help developers estimate the actual space text occupies on the drawing.

text_size 方法text_size Method

text_size 专门用于单行文字（TEXT 实体），其计算逻辑相对简单：text_size is designed for single-line text (TEXT entities) with relatively simple calculation logic:

# ezdxf 风格的 text_size 计算逻辑（示意）
def text_size(text_entity, font_info) -> Tuple[float, float]:
    """
    计算 TEXT 实体的渲染宽度和高度。
    返回: (width, height)
    """
    text = text_entity.dxf.text          # 组码 1
    height = text_entity.dxf.height      # 组码 40
    width_factor = text_entity.dxf.width # 组码 41（默认 1.0）
    oblique = text_entity.dxf.oblique    # 组码 51（倾斜角）

    # 1. 获取每个字符在指定字体下的宽度
    char_widths = [font_info.get_char_width(c) for c in text]
    base_width = sum(char_widths) * height * width_factor

    # 2. 倾斜会增加有效宽度
    if oblique != 0:
        base_width += height * abs(tan(radians(oblique)))

    # 3. 高度 = 文字高度 + 下伸部（如果有）
    # 注意：不同字体的 ascent/descent 比例不同
    actual_height = height * font_info.ascent_ratio

    return (base_width, actual_height)

mtext_size 方法mtext_size Method

mtext_size 用于多行文字（MTEXT 实体），计算更复杂，需要解析格式代码：mtext_size is for multiline text (MTEXT entities) and requires more complex calculation involving format code parsing:

# ezdxf 风格的 mtext_size 计算逻辑（示意）
def mtext_size(mtext_entity, font_info) -> Tuple[float, float]:
    """
    计算 MTEXT 实体的渲染宽度和高度。
    返回: (width, height)
    """
    content = mtext_entity.text            # 组码 1 + 3 拼接
    nominal_height = mtext_entity.dxf.height  # 组码 40（标称高度）
    rect_width = mtext_entity.dxf.width    # 组码 41（参考宽度）
    line_spacing = mtext_entity.dxf.line_spacing_factor  # 组码 44

    # 1. 解析格式代码（如 \H0.5x; 表示高度为标称的 0.5 倍）
    formatted_lines = parse_mtext_formatting(content)

    # 2. 逐行计算尺寸
    max_line_width = 0
    total_height = 0
    for i, line in enumerate(formatted_lines):
        line_height = line.get_height(nominal_height)  # 考虑 \H 代码
        line_width = calculate_line_width(line, font_info, line_height)
        max_line_width = max(max_line_width, line_width)

        # 首行不加间距，后续行加行间距
        if i > 0:
            total_height += line_height * line_spacing
        else:
            total_height += line_height

    # 3. 如果设定了参考宽度，实际宽度 = min(内容宽度, 参考宽度)
    actual_width = max_line_width
    if rect_width > 0:
        actual_width = min(max_line_width, rect_width)
        # 若内容被截断换行，高度需要重新计算
        if max_line_width > rect_width:
            total_height = recalc_wrapped_height(formatted_lines, rect_width)

    return (actual_width, total_height)

常见 MTEXT 格式代码Common MTEXT Format Codes

常见错误与注意事项Common Errors & Pitfalls

错误 1：对 MTEXT 读取 halign / valignError 1: Reading halign/valign on MTEXT

# 错误代码 ❌
for entity in msp:
    h = entity.dxf.halign   # MTEXT 会报错！
    v = entity.dxf.valign

# 正确代码 ✅
for entity in msp:
    if entity.dxftype() == 'TEXT':
        h = entity.dxf.halign
        v = entity.dxf.valign
    elif entity.dxftype() == 'MTEXT':
        att = entity.dxf.attachment_point

错误 2：混淆默认插入点Error 2: Confusing Default Insertion Points

错误 3：忽略对齐点（组码 11/21/31）Error 3: Ignoring Alignment Point (codes 11/21/31)

当 TEXT 的 halign 或 valign 非零时，组码 10/20/30 不再是文字的实际定位点，真正的对齐参考点是组码 11/21/31。若只读取插入点而忽略对齐点，渲染位置会偏差。When TEXT’s halign or valign is non-zero, group codes 10/20/30 are no longer the actual positioning point; the true alignment reference is codes 11/21/31. Reading only the insertion point while ignoring the alignment point will cause rendering position errors.

错误 4：MTEXT 内容截断Error 4: MTEXT Content Truncation

MTEXT 的内容超过 250 字符时会被拆分到多个组码 3 中。只读取组码 1 会导致内容不完整，必须按顺序拼接所有组码 3 的值。When MTEXT content exceeds 250 characters, it is split across multiple group code 3 entries. Reading only group code 1 will result in incomplete content; you must concatenate all group code 3 values in order.

# ezdxf 会自动处理拼接，但原生 DXF 解析需注意
# 正确读取 MTEXT 内容的逻辑：
content = code_1_value
for extra in all_code_3_values:
    content += extra