OpenSCAD User Manual/Text

The text object module draws a single string of text as a 2D geometric object, using fonts installed on the local system or provided as separate font file.

[Note: Requires version 2015.03 (see [Release Notes ] )]

Parameters

text
String. A single line of text. Limitation: non-printable ASCII characters like newline and tab rendered as placeholders
font
String in the form "fontname", or optionally, "fontname:style=stylename". The format of the parameter is described below.
size
non-negative decimal, default=10. The generated text has a height above the baseline of approximately this value, varying for different fonts but typically being slightly smaller.
halign
String, default="left". The horizontal alignment for the text. Possible values are "left", "center" and "right".
valign
String, default="baseline". The vertical alignment for the text. Possible values are "top", "center", "baseline" and "bottom".
spacing
float, default=1. Multiplicative factor that increases or decreases spacing between characters.
direction
String, default="ltr". Direction of text. Possible values are "ltr" (left-to-right), "rtl" (right-to-left), "ttb" (top-to-bottom) and "btt" (bottom-to-top).
language
String. The language of the text (e.g., "en", "ar", "ch"). Default is "en".
script
String, default="latin". The script of the text (e.g. "latin", "arabic", "hani").
$fn
higher values generate smoother curves (refer to Special Variables)

Example 

text("OpenSCAD");

Text Parameter While text() cannot draw multi-line blocks of text they may be simulated using transforms to space the lines apart. Fonts that descend below the baseline need to be spaced apart vertically by about 1.4*size to not overlap. Some word processing programs use a more generous spacing of 1.6*size for "single spacing" and double spacing can use 3.2*size.

Font & Style Parameter The font drawn by the method is the selected by the combination of its logical font name and a style selection. The fonts available for use in the app are those

  • registered in the local system
  • included in the OpenSCAD installation
  • imported at run-time by a program

Calling fontmetrics() with no parameters, thus using the defaults for everything, shows the default font and style for the installation and platform: 

fm = fontmetrics();
echo( fm );
/*
ECHO: { nominal = { ascent = 12.5733; descent = -2.9433; };
max = { ascent = 13.6109; descent = -4.2114; };
interline = 15.9709;
font = { family = "Liberation Sans"; style = "Regular"; }; }
*/

Here we see that the logical font name is the combination of the font itself with the title of a variation. The common members of a font family are sans and serif though many others will be seen in the list of fonts available

Each font variation can be drawn with a style to support textual emphasis. The default appearance is usually "Regular" with "Bold", "Italic", and "Bold Italic" being the other three styles commonly included in a font. In general the styles offered by a font may only be known by using the platform's font configuration tools or the OpenSCAD font list dialog.

The menu item Help > Font List shows the list of available fonts and the styles included in each one.

In the absence of a standard for the fonts available on the platforms OpenSCAD supports the app includes the Liberation font family with three variations Mono, Sans, and Serif. Using this font family is recommended to avoid problems of font availability.

Fonts may be added to the installation by drag-and-drop into the editor window.

It is also possible to add fonts to a particular project by importing them with the use statement in this form: 

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

Supported font file formats are TrueType fonts (*.ttf) and OpenType fonts (*.otf). Once a file is registered to the project the details of the fonts in it may be seen in the font list dialog so that the logical font names and their available styles are available for use in the project.

Examples of Font Usage 

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

Size Parameter The formula to convert the size value to "points" is pt = size/3.937, so a size argument of 3.05 will give about 12pt text, for instance. Note: if you know a point is 1/72" this may not look right, but point measurements of text are the distance from ascent to descent, not from ascent to baseline as in this case.

Vertical Alignment

top
The text is aligned so the top of the tallest character in your text is at the given Y coordinate.
center
The text is aligned with the center of the bounding box at the given Y coordinate. This bounding box is based on the actual sizes of the letters, so taller letters and descending below the baseline will affect the positioning.
baseline
The text is aligned with the font baseline at the given Y coordinate. This is the default, and is the only option that makes different pieces of text align vertically, as if they were written on lined paper, regardless of character heights and descenders.
bottom
The text is aligned so the bottom of the lowest-reaching character in your text is at the given Y coordinate.

Note: only the "baseline" vertical alignment option will ensure correct alignment of texts that use mix of fonts and sizes. 

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

Horizontal Alignment

left
The text is aligned with the left side of the bounding box at the given X coordinate.
center
The text is aligned with the center of the bounding box at the given X coordinate.
right
The text is aligned with the right of the bounding box at the given X coordinate.
 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]);
     }
   }
 }

Spacing Parameter

Characters in a text element have the size dictated by their glyph in the font being used. As such their size in X and Y is fixed. Each glyph also has fixed advance values (it is a vector [a,b], see textmetrics) for the offset to the origin of the next character. The position of each following character is the advance.x value multiplied by the space value. Obviously letters in the string can be stretched out when the factor is greater than 1, and can be made to overlap when space is a fraction closer to zero, but interestingly, using a negative value spaces each letter in the opposite of the direction parameter.

Fonts in OpenSCAD

The "name" of a font is the combination of its logical font name, its variation, and a style selection. The common variations in a font family are sans and serif though many others will be seen in the list of fonts available. Then, each font variation can be drawn with a style to support textual emphasis. The default, upright appearance is usually called "Regular" with "Bold", "Italic", and "Bold Italic" being the other three styles commonly included in a font.

The fonts available for use in the app are those:

  • registered in the local system
  • included in the OpenSCAD installation
  • imported at run-time by a program

A call to fontmetrics() using only default settings shows the installation's standard font and settings: 

echo( fontmetrics() );

gives this output (formatted for readability) 

{ 
nominal = {
  ascent = 12.5733;
  descent = -2.9433;
  };
max = {
  ascent = 13.6109; descent = -4.2114;
  };
interline = 15.9709;
font = {
  family = "Liberation Sans";
  style = "Regular";
  };
}

In general the styles offered by a font may only be known by using the platform's font configuration tools or the OpenSCAD font list dialog.

The menu item Help > Font List shows the list of available fonts and the styles included in each one.

None of the platforms OpenSCAD is available on include the Liberation font family so having it as part of the app's installation, and making it the default font, avoids problems of font availability. There are three variations in the family, Mono, Sans, and Serif.

Note: It was previously noted in the docs that fonts may be added to the installation by drag-and-drop of a font file into the editor window, but as of version 2025 Snapshot this is not the case

In the following sample code a True Type Font, Andika, has been added to the system fonts using its available Font Management service.

It is also possible to add fonts to a particular project by importing them with the use statement in this form: 

text( "sample", font="Andika:style=bold" ); // installed in system fonts

use <Andika-Italic.ttf>;

translate( [0,-10, 0] )
    color("green")
        text( "test", font="Andika:style=italic");

Supported font file formats are TrueType fonts (*.ttf) and OpenType fonts (*.otf). Once a file is registered to the project the details of the fonts in it may be seen in the font list dialog (see image) so that the logical font names, variations, and their available styles are available for use in the project.

Example of Font Usage 

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

3D text

Text can be changed from a 2 dimensional object into a 3D object by using the linear_extrude function. 

//3d Text Example
linear_extrude(4)
    text("Text");

Metrics

[Note: Requires version Development snapshot (see [snapshot Release Notes ] )]

textmetrics() Function

The textmetrics() function accepts the same parameters as text(), and returns an object describing how the text would be rendered.

The returned object has these members:

position
a vector [X,Y], the origin of the first glyph, thus the lower-left corner of the drawn text.
size
a vector [a,b], the size of the generated text.
ascent
positive float, the amount that the text extends above the baseline.
descent
negative float, the amount that the text extends below the baseline.
offset
a vector default [0, 0], the lower-left corner of the box containing the text, including inter-glyph spacing before the first glyph.
advance
a vector default [153.09, 0], amount of space to leave to any following text.

This example displays the text metrics for the default font used by OpenSCAD: 

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); // "size" is of the bounding box

displays (formatted for readability): 

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

The fontmetrics() function accepts a font size and a font name, both optional, and returns an object describing global characteristics of the font.

Parameters

size
Decimal, optional. The size of the font, as described above for text().
font
String, optional. The name of the font, as described above for text().

Note that omitting the size and/or font may be useful to get information about the default font.

Returns an object:

  • nominal: usual dimensions for a glyph:
    • ascent: height above the baseline
    • descent: depth below the baseline
  • max: maximum dimensions for a glyph:
    • ascent: height above the baseline
    • descent: depth below the baseline
  • interline: design distance from one baseline to the next
  • font: identification information about the font:
    • family: the font family name
    • style: the style (Regular, Italic, et cetera)
   echo(fontmetrics(font="Liberation Serif"));

yields (reformatted for readability): 

   ECHO: {
       nominal = {
           ascent = 12.3766;
           descent = -3.0043;
       };
       max = {
           ascent = 13.6312;
           descent = -4.2114;
       };
       interline = 15.9709;
       font = {
           family = "Liberation Serif";
           style = "Regular";
       };
   }
This article is issued from Wikibooks. The text is available under Creative Commons Attribution-Share Alike 4.0 unless otherwise noted. Additional terms may apply for the media files.