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]

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

Decimal >0, default=1. A value greater than 1 increases spacing while a value greater than zero and less than 1 decreases it.

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

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]

textmetrics()

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: the position of the lower-left corner of the generated text.
• size: the size of the generated text.
• ascent: the amount that the text extends above the baseline.
• descent: the amount that the text extends below the baseline.
• offset: the lower-left corner of the box containing the text, including inter-glyph spacing before the first glyph.
• advance: the "other end" of the text, the point at which additional text should be positioned.

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

yields (reformatted 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];
   }

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

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


Category:Book:OpenSCAD User Manual#Text%20