openscad-labeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSCAD Labeling

OpenSCAD标签添加

Add text labels to 3D model faces, part numbers, dimension annotations, and curved surface text in OpenSCAD.

在OpenSCAD中为3D模型面、零件编号、尺寸标注及曲面添加文本标签。

Quick Start

快速开始

Label a cube's top face using BOSL2's attach system (most common use case):

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("TOP", size=8, halign="center", valign="center");

This creates raised text on the top face without calculating positions manually.

使用BOSL2的attach系统为立方体顶面添加标签（最常见用法）：

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("TOP", size=8, halign="center", valign="center");

这样无需手动计算位置，就能在顶面创建凸起的文本。

When to Use This Skill

适用场景

Explicit Triggers:

"Label this model"
"Add text to the TOP face"
"How do I add part numbers in OpenSCAD?"
"Text on cylinder"
"Install text_on_OpenSCAD"

Implicit Triggers:

Creating parts that need identification
Building labeled storage bins
Making dimension annotations for debug
Wrapping text around curved objects
Engraving text into surfaces

Debugging Triggers:

"Why isn't my text showing on the right face?"
"Text is backwards/upside down"
"How do I center text on a face?"

明确触发场景：

"Label this model"
"Add text to the TOP face"
"How do I add part numbers in OpenSCAD?"
"Text on cylinder"
"Install text_on_OpenSCAD"

隐含触发场景：

创建需要标识的零件
制作带标签的收纳盒
添加用于调试的尺寸标注
在曲面上包裹文本
在表面雕刻文本

调试触发场景：

"为什么文本没有显示在正确的面上？"
"文本是反向/倒置的"
"如何让文本在面上居中？"

What This Skill Does

功能说明

This skill helps you:

Define faces using BOSL2's semantic anchor system (TOP, BOTTOM, LEFT, etc.)
Attach text to faces without manual position calculations
Choose libraries based on surface type (flat vs curved) and requirements
Install libraries for advanced text features (curved surfaces, font metrics)
Create practical patterns (part labels, dimension annotations, engraved text)

本技能可帮助你：

定义面：使用BOSL2的语义锚点系统（TOP、BOTTOM、LEFT等）
附着文本：无需手动计算位置即可将文本附着到面上
选择库：根据表面类型（平面/曲面）及需求选择合适的库
安装库：安装用于高级文本功能的库（曲面文本、字体指标）
创建实用样式：零件标签、尺寸标注、雕刻文本

Instructions

操作步骤

3.1 Define Faces with BOSL2

3.1 用BOSL2定义面

BOSL2 provides named face constants that eliminate manual coordinate calculations.

Standard faces:

openscad

include <BOSL2/std.scad>

// The six primary faces
TOP, BOTTOM, LEFT, RIGHT, FRONT, BACK

Face reference table:

Face	Direction	Normal Vector	Notes
TOP	+Z	[0, 0, 1]	Points up
BOTTOM	-Z	[0, 0, -1]	Points down
FRONT	-Y	[0, -1, 0]	Points toward viewer
BACK	+Y	[0, 1, 0]	Points away
LEFT	-X	[-1, 0, 0]	Points left
RIGHT	+X	[1, 0, 0]	Points right

Attach objects to faces:

openscad

cuboid([50, 30, 20]) {
    attach(TOP) color("red") cuboid([10, 10, 5]);
    attach(FRONT) color("blue") cyl(d=8, h=3);
    attach(LEFT+BOTTOM) color("green") sphere(d=5);
}

Edges and corners:

openscad

// Edges (combine two faces)
TOP+LEFT, BOTTOM+RIGHT, FRONT+TOP

// Corners (combine three faces)
TOP+LEFT+FRONT, BOTTOM+RIGHT+BACK

BOSL2提供命名的面常量，无需手动计算坐标。

标准面：

openscad

include <BOSL2/std.scad>

// 六个基本面
TOP, BOTTOM, LEFT, RIGHT, FRONT, BACK

面对照表：

面	方向	法向量	说明
TOP	+Z	[0, 0, 1]	指向上方
BOTTOM	-Z	[0, 0, -1]	指向下方
FRONT	-Y	[0, -1, 0]	指向观察者
BACK	+Y	[0, 1, 0]	背向观察者
LEFT	-X	[-1, 0, 0]	指向左侧
RIGHT	+X	[1, 0, 0]	指向右侧

将对象附着到面上：

openscad

cuboid([50, 30, 20]) {
    attach(TOP) color("red") cuboid([10, 10, 5]);
    attach(FRONT) color("blue") cyl(d=8, h=3);
    attach(LEFT+BOTTOM) color("green") sphere(d=5);
}

边和角：

openscad

// 边（组合两个面）
TOP+LEFT, BOTTOM+RIGHT, FRONT+TOP

// 角（组合三个面）
TOP+LEFT+FRONT, BOTTOM+RIGHT+BACK

3.2 Add Text to Flat Faces

3.2 为平面添加文本

Pattern 1: Raised text (embossed)

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("LABEL", size=8, halign="center", valign="center");

Breakdown:

```
attach(TOP, BOT)
```
- Attach to TOP face, align text's BOT to surface
```
linear_extrude(2)
```
- Extrude 2mm tall
```
halign="center", valign="center"
```
- Center text on face

Pattern 2: Engraved text (debossed)

openscad

include <BOSL2/std.scad>

diff()
cuboid([50, 30, 20])
    attach(TOP, BOT, inside=true)
        tag("remove")
        linear_extrude(1)
            text("CUT", size=8, halign="center", valign="center");

Breakdown:

```
diff()
```
- Enable boolean difference mode
```
inside=true
```
- Attach inside the surface
```
tag("remove")
```
- Mark for subtraction

Pattern 3: Multiple labeled faces

openscad

include <BOSL2/std.scad>

module labeled_box(size, labels) {
    faces = [TOP, BOTTOM, FRONT, BACK, LEFT, RIGHT];

    diff()
    cuboid(size)
        for (i = [0:5])
            if (labels[i] != "")
                attach(faces[i], BOT)
                    tag("remove")
                    linear_extrude(1)
                        text(labels[i], size=size.x/8, halign="center", valign="center");
}

labeled_box([50, 30, 20], ["TOP", "BOT", "FRONT", "BACK", "L", "R"]);

Pattern 4: Part number label tag

openscad

include <BOSL2/std.scad>

module part_label(txt, size=[40, 15, 2]) {
    diff()
    cuboid(size, rounding=1, edges="Z")
        attach(TOP, BOT, inside=true)
            tag("remove")
            linear_extrude(0.5)
                text(txt, size=size.y*0.5, halign="center", valign="center");
}

part_label("PN-001");

样式1：凸起文本（浮雕）

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("LABEL", size=8, halign="center", valign="center");

说明：

```
attach(TOP, BOT)
```
- 附着到TOP面，将文本的BOT面与表面对齐
```
linear_extrude(2)
```
- 挤出2毫米高
```
halign="center", valign="center"
```
- 让文本在面上居中

样式2：雕刻文本（沉雕）

openscad

include <BOSL2/std.scad>

diff()
cuboid([50, 30, 20])
    attach(TOP, BOT, inside=true)
        tag("remove")
        linear_extrude(1)
            text("CUT", size=8, halign="center", valign="center");

说明：

```
diff()
```
- 启用布尔差集模式
```
inside=true
```
- 附着到表面内部
```
tag("remove")
```
- 标记为要减去的部分

样式3：多面标签

openscad

include <BOSL2/std.scad>

module labeled_box(size, labels) {
    faces = [TOP, BOTTOM, FRONT, BACK, LEFT, RIGHT];

    diff()
    cuboid(size)
        for (i = [0:5])
            if (labels[i] != "")
                attach(faces[i], BOT)
                    tag("remove")
                    linear_extrude(1)
                        text(labels[i], size=size.x/8, halign="center", valign="center");
}

labeled_box([50, 30, 20], ["TOP", "BOT", "FRONT", "BACK", "L", "R"]);

样式4：零件编号标签

openscad

include <BOSL2/std.scad>

module part_label(txt, size=[40, 15, 2]) {
    diff()
    cuboid(size, rounding=1, edges="Z")
        attach(TOP, BOT, inside=true)
            tag("remove")
            linear_extrude(0.5)
                text(txt, size=size.y*0.5, halign="center", valign="center");
}

part_label("PN-001");

3.3 Add Text to Curved Surfaces

3.3 为曲面添加文本

For curved surfaces (cylinders, spheres), use specialized libraries.

Check library installation status:

bash

ls ~/Documents/OpenSCAD/libraries/text_on_OpenSCAD
ls ~/Documents/OpenSCAD/libraries/openscad_attachable_text3d

Option 1: text_on_OpenSCAD (curved surfaces)

openscad

use <text_on_OpenSCAD/text_on.scad>

// Text wrapped around cylinder
text_on_cylinder("LABEL", r=15, h=30, size=4, font="Liberation Sans");

// Text on sphere surface
text_on_sphere("Hello World", r=20, size=5);

// Text on cube face (alternative to BOSL2)
text_on_cube("FRONT", size=8, face="front", cube_size=50);

Option 2: attachable_text3d (BOSL2-compatible)

openscad

include <BOSL2/std.scad>
use <openscad_attachable_text3d/attachable_text3d.scad>

// Attachable 3D text with accurate font metrics
cuboid([50, 30, 20])
    attach(TOP)
        attachable_text3d("Label", size=10, h=2);

Benefits:

Works with BOSL2's attach system
Accurate bounding box for alignment
Better font metric calculations

Option 3: Write.scad (classic library)

openscad

use <Write.scad>

// Text on cube faces
writecube("TEXT", [50, 30, 20], face="front", t=2, h=8);

// Text on sphere
writesphere("GLOBE", 25, t=2, h=6);

// Text on cylinder
writecylinder("LABEL", r=15, h=30, t=2);

对于曲面（圆柱、球体），请使用专用库。

检查库安装状态：

bash

ls ~/Documents/OpenSCAD/libraries/text_on_OpenSCAD
ls ~/Documents/OpenSCAD/libraries/openscad_attachable_text3d

选项1：text_on_OpenSCAD（曲面专用）

openscad

use <text_on_OpenSCAD/text_on.scad>

// 包裹在圆柱上的文本
text_on_cylinder("LABEL", r=15, h=30, size=4, font="Liberation Sans");

// 球体表面的文本
text_on_sphere("Hello World", r=20, size=5);

// 立方体面上的文本（BOSL2的替代方案）
text_on_cube("FRONT", size=8, face="front", cube_size=50);

选项2：attachable_text3d（兼容BOSL2）

openscad

include <BOSL2/std.scad>
use <openscad_attachable_text3d/attachable_text3d.scad>

// 可附着的3D文本，字体指标精准
cuboid([50, 30, 20])
    attach(TOP)
        attachable_text3d("Label", size=10, h=2);

优势：

兼容BOSL2的attach系统
精准的边界框用于对齐
更准确的字体指标计算

选项3：Write.scad（经典库）

openscad

use <Write.scad>

// 立方体面上的文本
writecube("TEXT", [50, 30, 20], face="front", t=2, h=8);

// 球体上的文本
writesphere("GLOBE", 25, t=2, h=6);

// 圆柱上的文本
writecylinder("LABEL", r=15, h=30, t=2);

3.4 Install Labeling Libraries

3.4 安装标签库

text_on_OpenSCAD (curved surfaces + internationalization):

bash

cd ~/Documents/OpenSCAD/libraries  # macOS

text_on_OpenSCAD（曲面+国际化支持）：

bash

cd ~/Documents/OpenSCAD/libraries  # macOS

cd ~/.local/share/OpenSCAD/libraries # Linux

git clone https://github.com/brodykenrick/text_on_OpenSCAD.git


Verify installation:
```openscad
use <text_on_OpenSCAD/text_on.scad>
text_on_cylinder("TEST", r=10, h=20, size=3);

attachable_text3d (BOSL2-compatible, accurate metrics):

bash

cd ~/Documents/OpenSCAD/libraries
git clone https://github.com/jon-gilbert/openscad_attachable_text3d.git

Verify installation (requires BOSL2):

openscad

include <BOSL2/std.scad>
use <openscad_attachable_text3d/attachable_text3d.scad>
attachable_text3d("TEST", size=10, h=2);

Check what's already installed:

bash

ls -la ~/Documents/OpenSCAD/libraries/

Common pre-installed libraries:

BOSL2 (always available in this project)
NopSCADlib
MCAD

git clone https://github.com/brodykenrick/text_on_OpenSCAD.git


验证安装：
```openscad
use <text_on_OpenSCAD/text_on.scad>
text_on_cylinder("TEST", r=10, h=20, size=3);

attachable_text3d（兼容BOSL2，指标精准）：

bash

cd ~/Documents/OpenSCAD/libraries
git clone https://github.com/jon-gilbert/openscad_attachable_text3d.git

验证安装（需BOSL2）：

openscad

include <BOSL2/std.scad>
use <openscad_attachable_text3d/attachable_text3d.scad>
attachable_text3d("TEST", size=10, h=2);

检查已安装的库：

bash

ls -la ~/Documents/OpenSCAD/libraries/

常见预安装库：

BOSL2（本项目中默认可用）
NopSCADlib
MCAD

Supporting Files

支持文件

References:

```
references/library-comparison.md
```
- Detailed comparison of text_on_OpenSCAD, attachable_text3d, Write.scad
```
references/font-reference.md
```
- Cross-platform fonts, font parameters, system font usage

Examples:

```
examples/practical-labels.scad
```
- Part labels, dimension annotations, debug labels
```
examples/curved-text.scad
```
- Cylinder/sphere text wrapping examples
```
examples/engraved-embossed.scad
```
- Raised vs cut text patterns

Scripts:

```
scripts/check-text-libraries.sh
```
- Verify text library installations
```
scripts/list-system-fonts.sh
```
- List available fonts for OpenSCAD

参考资料：

```
references/library-comparison.md
```
- text_on_OpenSCAD、attachable_text3d、Write.scad的详细对比
```
references/font-reference.md
```
- 跨平台字体、字体参数、系统字体使用说明

示例：

```
examples/practical-labels.scad
```
- 零件标签、尺寸标注、调试标签
```
examples/curved-text.scad
```
- 圆柱/球体文本包裹示例
```
examples/engraved-embossed.scad
```
- 凸起与雕刻文本样式

脚本：

```
scripts/check-text-libraries.sh
```
- 验证文本库安装情况
```
scripts/list-system-fonts.sh
```
- 列出OpenSCAD可用的系统字体

Expected Outcomes

预期效果

Success: Text appears on correct face, properly centered

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("SUCCESS", size=6, halign="center", valign="center");

Output: Text centered on top face, raised 2mm, easily readable.

Failure: Text backwards, wrong face, or positioning errors

openscad

// ❌ WRONG: Manual positioning without BOSL2
cube([50, 30, 20]);
translate([25, 15, 20])  // Easy to miscalculate
    linear_extrude(2)
        text("WRONG", size=6, halign="center");

Problem: Manual calculations prone to errors, text may be backwards or misaligned.

成功： 文本显示在正确的面上，且居中对齐

openscad

include <BOSL2/std.scad>

cuboid([50, 30, 20])
    attach(TOP, BOT)
        linear_extrude(2)
            text("SUCCESS", size=6, halign="center", valign="center");

输出：文本居中显示在顶面，凸起2毫米，清晰可读。

失败： 文本反向、显示在错误的面上，或定位错误

openscad

// ❌ 错误：未使用BOSL2，手动定位
cube([50, 30, 20]);
translate([25, 15, 20])  // 容易计算错误
    linear_extrude(2)
        text("WRONG", size=6, halign="center");

问题：手动计算容易出错，文本可能反向或对齐偏差。

Requirements

要求

Required:

OpenSCAD 2021.01+ (text() function)
BOSL2 library (for attach system)

Optional:

text_on_OpenSCAD (curved surfaces)
attachable_text3d (better font metrics)
Write.scad (classic curved text)

Knowledge:

Basic BOSL2 attach syntax
Understanding of face normals
OpenSCAD text() parameters

必备：

OpenSCAD 2021.01+（支持text()函数）
BOSL2库（用于attach系统）

可选：

text_on_OpenSCAD（曲面文本）
attachable_text3d（更精准的字体指标）
Write.scad（经典曲面文本）

知识储备：

基础BOSL2 attach语法
面法线的理解
OpenSCAD text()参数

Red Flags to Avoid

注意事项

Manual text positioning - Use attach() instead of translate/rotate calculations
Forgetting halign/valign - Text won't center without these parameters
Wrong face attachment point - Use
```
attach(TOP, BOT)
```
not
```
attach(TOP, TOP)
```
Missing libraries - Check installation before using specialized text functions
Text too large for surface - Scale text size relative to face dimensions
Backwards text on faces - BOSL2's attach handles orientation automatically
Using inside=true for raised text - Only use for engraved/cut text
Forgetting tag("remove") in diff() - Text won't be cut without tag
Assuming Write.scad is installed - It's not bundled with OpenSCAD
Not centering text - Default text origin is bottom-left corner

避免手动定位文本 - 使用attach()替代translate/rotate手动计算
不要忘记halign/valign - 没有这些参数，文本无法居中
正确选择附着点 - 使用
```
attach(TOP, BOT)
```
而非
```
attach(TOP, TOP)
```
检查库是否安装 - 使用专用文本函数前先确认库已安装
文本尺寸适配表面 - 根据面的尺寸缩放文本大小
面上的文本反向 - BOSL2的attach会自动处理方向
凸起文本不要用inside=true - 该参数仅用于雕刻/切割文本
diff()模式下不要忘记tag("remove") - 没有tag，文本无法被切割
不要假设Write.scad已安装 - 它并未随OpenSCAD捆绑
务必居中文本 - 文本默认原点在左下角

Notes

备注

Library decision tree:

Need text on model?
├─ Flat surface?
│  ├─ Using BOSL2? → attach() + text()
│  └─ Not using BOSL2? → text_on_OpenSCAD or Write.scad
└─ Curved surface (cylinder/sphere)?
   ├─ BOSL2 workflow? → attachable_text3d (if installed)
   └─ Classic approach? → text_on_OpenSCAD or Write.scad

Performance tip: Use

$fn=$preview ? 32 : 64

to speed up text rendering in preview mode.

Font availability: Use "Liberation Sans", "Liberation Mono", or "Liberation Serif" for cross-platform compatibility.

Text depth guidelines:

Raised text: 1-2mm for labels, 0.5mm for fine detail
Engraved text: 0.5-1mm depth (too deep weakens part)

See references/ for detailed library comparisons and advanced examples.

库选择决策树：

需要给模型添加文本？
├─ 平面？
│  ├─ 使用BOSL2？ → attach() + text()
│  └─ 不使用BOSL2？ → text_on_OpenSCAD或Write.scad
└─ 曲面（圆柱/球体）？
   ├─ 使用BOSL2工作流？ → attachable_text3d（若已安装）
   └─ 经典方式？ → text_on_OpenSCAD或Write.scad

性能优化技巧： 使用

$fn=$preview ? 32 : 64

可加快预览模式下的文本渲染速度。

字体兼容性： 使用“Liberation Sans”“Liberation Mono”或“Liberation Serif”以确保跨平台兼容。

文本深度指南：

凸起文本：标签用1-2毫米，精细细节用0.5毫米
雕刻文本：0.5-1毫米深度（过深会削弱零件强度）

更多详细的库对比及高级示例，请查看references/目录。

openscad-labeling

Original

Translation

OpenSCAD Labeling

OpenSCAD标签添加

Quick Start

快速开始

Table of Contents

目录

When to Use This Skill

适用场景

What This Skill Does

功能说明

Instructions

操作步骤

3.1 Define Faces with BOSL2

3.1 用BOSL2定义面

3.2 Add Text to Flat Faces

3.2 为平面添加文本

3.3 Add Text to Curved Surfaces

3.3 为曲面添加文本

3.4 Install Labeling Libraries

3.4 安装标签库

cd ~/.local/share/OpenSCAD/libraries # Linux

cd ~/.local/share/OpenSCAD/libraries # Linux

Supporting Files

支持文件

Expected Outcomes

预期效果

Requirements

要求

Red Flags to Avoid

注意事项

Notes

备注