OpenSCAD Benutzerhandbuch/Text

Das text-Modul erzeugt Text als 2D-geometrisches Objekt – entweder mit Schriftarten, die auf deinem System installiert sind, oder mit externen Schriftdateien.

Vorlage:Requires

Parameter

text: Zeichenkette. Der zu generierende Text.

size: Dezimalzahl. Der generierte Text hat eine Aufstrichhöhe (also Höhe über der Grundlinie) von ungefähr diesem Wert. Standard ist 10. Je nach Schriftart kann die tatsächliche Höhe leicht abweichen (meist etwas kleiner).

Um den size-Wert in „Punkt“ (pt) umzurechnen, gilt: pt = size * 3.937. Beispiel: Ein size-Wert von 3,05 ergibt etwa 12-pt-Text. Hinweis: Obwohl ein Punkt normalerweise 1/72 Zoll entspricht, misst man bei Schriftarten üblicherweise vom höchsten Aufstrich bis zum tiefsten Abstrich – hier wird aber nur die Höhe über der Grundlinie berücksichtigt.

font: Zeichenkette. Der logische Name der gewünschten Schriftart (nicht der Dateiname!). Intern wird dies von der fontconfig-Bibliothek verarbeitet. Du kannst auch einen Stil wie „bold“ oder „italic“ angeben (siehe unten). Eine Liste aller verfügbaren Schriften und Stile findest du im Schriftarten-Dialog (Hilfe → Font List).

halign: Zeichenkette. Horizontale Ausrichtung: „left“, „center“ oder „right“. Standard: „left“.

valign: Zeichenkette. Vertikale Ausrichtung: „top“, „center“, „baseline“ oder „bottom“. Standard: „baseline“.

spacing: Dezimalzahl. Faktor zur Vergrößerung/Verkleinerung des Zeichenabstands. Standardwert 1 = normaler Abstand. Werte > 1 vergrößern den Abstand.

direction: Zeichenkette. Textrichtung: „ltr“ (links nach rechts), „rtl“ (rechts nach links), „ttb“ (oben nach unten) oder „btt“ (unten nach oben). Standard: „ltr“.

language: Zeichenkette. Sprache des Texts (z. B. „en“, „ar“, „ch“). Standard: „en“.

script: Zeichenkette. Schriftsystem (z. B. „latin“, „arabic“, „hani“). Standard: „latin“.

$fn: Steuert die Unterteilung gekrümmter Pfadsegmente (von FreeType bereitgestellt).

Beispiel

text("OpenSCAD");

Hinweise

Um bestimmte Unicode-Zeichen anzugeben, kannst du Escape-Codes in der Zeichenkette verwenden:

\x03 – hexadezimaler Zeichenwert (nur Werte von 01 bis 7f unterstützt)
\u0123 – Unicode-Zeichen mit 4 hexadezimalen Stellen (Achtung: kleines \u)
\U012345 – Unicode-Zeichen mit 6 hexadezimalen Stellen (Achtung: großes \U)

Das Nullzeichen (NUL) wird automatisch auf das Leerzeichen (SP) abgebildet:

assert(version() == [2019, 5, 0]);
assert(ord(" ") == 32);
assert(ord("\x00") == 32);
assert(ord("\u0000") == 32);
assert(ord("\U000000") == 32);

Beispiel

t="\u20AC10 \u263A"; // 10 Euro und ein Smiley

Schriftarten und Stile verwenden

Schriftarten werden über ihren logischen Namen angesprochen. Optional kannst du einen Stil hinzufügen, z. B.:

font="Liberation Sans:style=Bold Italic"

Der Schriftarten-Dialog (Hilfe → Font List) zeigt für jede verfügbare Schrift den Namen, den Stil und den Speicherort der Datei an. Du kannst eine Schrift direkt aus dem Dialog in das Editorfenster ziehen, um sie im `text()`-Befehl zu verwenden.

OpenSCAD bringt standardmäßig die Schriften Liberation Mono, Liberation Sans und Liberation Serif mit. Da Schriftarten je nach Betriebssystem unterschiedlich sein können, empfiehlt es sich aus Portabilitätsgründen, diese mitgelieferten Schriften zu nutzen. Liberation Sans ist daher die Standard-Schriftart.

Zusätzlich zu den systemweit installierten Schriften (unter Windows: nur solche, die für alle Benutzer installiert wurden) kannst du projektspezifische Schriftdateien einbinden. Unterstützt werden TrueType (*.ttf) und OpenType (*.otf). Die Dateien müssen mit `use<>` registriert werden:

use <ttf/paratype-serif/PTF55F.ttf>

Danach erscheint die Schrift im Font-List-Dialog – falls du den logischen Namen nicht kennst, kannst du ihn dort nachschauen.

OpenSCAD nutzt fontconfig zur Verwaltung der Schriften. Unter Linux/macOS kannst du die verfügbaren Schriften auch in der Kommandozeile auflisten:

$ fc-list -f "%-60{{%{family[0]}%{:style[0]=}}}%{file}\n" | sort

...
Liberation Mono:style=Bold Italic /usr/share/fonts/truetype/liberation2/LiberationMono-BoldItalic.ttf
Liberation Mono:style=Bold        /usr/share/fonts/truetype/liberation2/LiberationMono-Bold.ttf
Liberation Mono:style=Italic      /usr/share/fonts/truetype/liberation2/LiberationMono-Italic.ttf
Liberation Mono:style=Regular     /usr/share/fonts/truetype/liberation2/LiberationMono-Regular.ttf
...

Unter Windows sind Schriftarten in der Registry gespeichert. Um eine Liste mit Dateinamen zu erhalten, verwende:

reg query "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts" /s > List_Fonts_Windows.txt

Beispiel

square(10);

translate([15, 15]) {
  text("OpenSCAD", font = "Liberation Sans");
}

translate([15, 0]) {
  text("OpenSCAD", font = "Liberation Sans:style=Bold Italic");
}

Ausrichtung

Vertikale Ausrichtung

top: Der höchste Buchstabe des Texts liegt auf der angegebenen Y-Koordinate.
center: Die Mitte des umschließenden Rechtecks liegt auf der Y-Koordinate (berücksichtigt Auf- und Abstriche).
baseline: Die Grundlinie des Texts liegt auf der Y-Koordinate. Das ist der Standard – und die einzige Option, bei der mehrere Textzeilen wie auf kariertem Papier sauber untereinander stehen, unabhängig von den Buchstabenformen.
bottom: Der tiefste Abstrich liegt auf der Y-Koordinate.

text = "Align";
font = "Liberation Sans";

valign = [
  [  0, "top"],
  [ 40, "center"],
  [ 75, "baseline"],
  [110, "bottom"]
];

for (a = valign) {
  translate([10, 120 - a[0], 0]) {
    color("red") cube([135, 1, 0.1]);
    color("blue") cube([1, 20, 0.1]);
    linear_extrude(height = 0.5) {
      text(text = str(text,"_",a[1]), font = font, size = 20, valign = a[1]);
    }
  }
}

Das text()-Modul unterstützt keinen mehrzeiligen Text. Stattdessen rufst du `text()` für jede Zeile einzeln auf und verschiebst sie mit translate(). Ein Zeilenabstand von mindestens 1,4 × size verhindert Überlappungen (bei Buchstaben mit Abstrichen). 1,6 × size entspricht etwa dem Standard-Einzug in Textverarbeitungsprogrammen. Für gleichmäßigen Zeilenabstand solltest du valign = "baseline" verwenden.

Horizontale Ausrichtung

left: Linker Rand des Texts liegt auf der X-Koordinate (Standard).
center: Mittelpunkt des Texts liegt auf der X-Koordinate.
right: Rechter Rand des Texts liegt auf der X-Koordinate.

text = "Align";
font = "Liberation Sans";

halign = [
  [10, "left"],
  [50, "center"],
  [90, "right"]
];

for (a = halign) {
  translate([140, a[0], 0]) {
    color("red") cube([115, 2,0.1]);
    color("blue") cube([2, 20,0.1]);
    linear_extrude(height = 0.5) {
      text(text = str(text,"_",a[1]), font = font, size = 20, halign = a[1]);
    }
  }
}

3D-Text

Du kannst 2D-Text in ein 3D-Objekt verwandeln, indem du ihn mit linear_extrude extrudierst:

// 3D-Text-Beispiel
linear_extrude(4)
    text("Text");

Metriken

Vorlage:Requires

textmetrics()

Die Funktion textmetrics() akzeptiert dieselben Parameter wie text() und gibt ein Objekt zurück, das beschreibt, wie der Text gerendert würde.

Das zurückgegebene Objekt enthält folgende Eigenschaften:

position: Position der linken unteren Ecke des generierten Texts.
size: Breite und Höhe des Texts.
ascent: Wie weit der Text über die Grundlinie ragt.
descent: Wie weit der Text unter die Grundlinie reicht (negativer Wert).
offset: Ursprung des Texts nach der Ausrichtung. Der Text beginnt typischerweise etwas rechts davon.
advance: Endpunkt des Texts – hier sollte weiterer Text ansetzen (relativ zu „offset“). Der Text endet meist etwas links davon.

s = "Hello, World!";
size = 20;
font = "Liberation Serif";

tm = textmetrics(s, size=size, font=font);
echo(tm);
translate([0,0,1]) text("Hello, World!", size=size, font=font);
color("black") translate(tm.position) square(tm.size);

Ergebnis (lesbar formatiert):

ECHO: {
    position = [0.7936, -4.2752];
    size = [149.306, 23.552];
    ascent = 19.2768;
    descent = -4.2752;
    offset = [0, 0];
    advance = [153.09, 0];
}

fontmetrics()

Die Funktion fontmetrics() akzeptiert optional eine Schriftgröße und einen Schriftnamen und liefert ein Objekt mit globalen Eigenschaften der Schrift.

Parameter

size: Dezimalzahl (optional). Schriftgröße wie bei text().
font: Zeichenkette (optional). Schriftname wie bei text().

Ohne Angabe erhältst du Informationen zur Standard-Schriftart.

Rückgabeobjekt:

nominal: typische Abmessungen eines Zeichens:

  ascent: Höhe über der Grundlinie  
  descent: Tiefe unter der Grundlinie

max: maximale Abmessungen eines Zeichens:

  ascent: maximale Höhe  
  descent: maximale Tiefe

interline: Design-Abstand von einer Grundlinie zur nächsten
font: Identifikationsdaten:

  family: Schriftfamilie  
  style: Stil (Regular, Italic usw.)

echo(fontmetrics(font="Liberation Serif"));

Ergebnis (lesbar formatiert):

ECHO: {
    nominal = {
        ascent = 12.3766;
        descent = -3.0043;
    };
    max = {
        ascent = 13.6312;
        descent = -4.2114;
    };
    interline = 15.9709;
    font = {
        family = "Liberation Serif";
        style = "Regular";
    };
}