OpenSCAD Labeling

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

Quick Start

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

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.

When to Use This Skill
What This Skill Does
Instructions 3.1 Define Faces with BOSL2 3.2 Add Text to Flat Faces 3.3 Add Text to Curved Surfaces 3.4 Install Labeling Libraries
Supporting Files
Expected Outcomes
Requirements
Red Flags to Avoid

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?"

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)

Instructions

3.1 Define Faces with BOSL2

BOSL2 provides named face constants that eliminate manual coordinate calculations.

Standard faces:

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:

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:

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

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

3.2 Add Text to Flat Faces

Pattern 1: Raised text (embossed)

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)

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

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

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

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

Check library installation status:

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

Option 1: text_on_OpenSCAD (curved surfaces)

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)

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)

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);

3.4 Install Labeling Libraries

text_on_OpenSCAD (curved surfaces + internationalization):

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

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

Verify installation:

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

attachable_text3d (BOSL2-compatible, accurate metrics):

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

Verify installation (requires BOSL2):

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

Check what's already installed:

ls -la ~/Documents/OpenSCAD/libraries/

Common pre-installed libraries:

BOSL2 (always available in this project)
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

Expected Outcomes

Success: Text appears on correct face, properly centered

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

// ❌ 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.

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

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

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.

openscad-labeling