# OpenSCAD User Manual/Text

The text module creates 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. The text to generate.

## size

    Decimal. The generated text has an ascent (height above the baseline) of approximately the given value. Default is 10. Different fonts can vary somewhat and may not fill the size specified exactly, typically they render slightly smaller. On a metric system a size of 25.4 (1" imperial) will correspond to 100pt ⇒ a 12pt font size would be 12×0.254 for metric conversion or 0.12 in imperial.

## font

    String. The name of the font that should be used. This is not the name of the font file, but the logical font name (internally handled by the fontconfig library). This can also include a style parameter, see below. A list of installed fonts & styles can be obtained using the font list dialog (Help -> Font List).

## halign

    String. The horizontal alignment for the text. Possible values are "left", "center" and "right". Default is "left".

## valign

    String. The vertical alignment for the text. Possible values are "top", "center", "baseline" and "bottom". Default is "baseline".

## spacing

    Decimal. Factor to increase/decrease the character spacing. The default value of 1 results in the normal spacing for the font, giving a value greater than 1 causes the letters to be spaced further apart.

## direction

    String. Direction of the text flow. Possible values are "ltr" (left-to-right), "rtl" (right-to-left), "ttb" (top-to-bottom) and "btt" (bottom-to-top). Default is "ltr".

## language

    String. The language of the text (e.g., "en", "ar", "ch"). Default is "en".

## script

    String. The script of the text (e.g., "latin", "arabic", "hani"). Default is "latin".

## $fn

    used for subdividing the curved path segments provided by freetype
Example

## Notes

To allow specification of particular Unicode characters, you can specify them in a string with the following escape codes;
* \x03 - hex char-value (only hex values from 01 to 7f are supported)
* \u0123 - Unicode char with 4 hexadecimal digits (note: lowercase \u)
* \U012345 - Unicode char with 6 hexadecimal digits (note: uppercase \U)
The null character (NUL) is mapped to the space character (SP).
Example

### Using Fonts & Styles

Fonts are specified by their logical font name; in addition a style parameter can be added to select a specific font style like "bold" or "italic", such as:
The font list dialog (available under Help > Font List) shows the font name and the font style for each available font. For reference, the dialog also displays the location of the font file. You can drag a font in the font list, into the editor window to use in the text statement.
OpenSCAD includes the fonts Liberation Mono, Liberation Sans, and Liberation Serif. Hence, as fonts in general differ by platform type, use of these included fonts is likely to be portable across platforms.
For common/casual text usage, the specification of one of these fonts is recommended for this reason. Liberation Sans is the default font to encourage this.
In addition to the installed fonts ( for windows only fonts installed as admin for all users ), it's possible to add project specific font files. Supported font file formats are TrueType Fonts (*.ttf) and OpenType Fonts (*.otf). The files need to be registered with use<>.
After the registration, the font is listed in the font list dialog, so in case logical name of a font is unknown, it can be looked up as it was registered.
OpenSCAD uses fontconfig to find and manage fonts, so it's possible to list the system configured fonts on command line using the fontconfig tools in a format similar to the GUI dialog.
Under Windows, fonts are stored in the Windows Registry. To get a file with the font file names, use the command:
reg query "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts" /s > List_Fonts_Windows.txt
Example

### Alignment
#### 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 descenders 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.
Multi line text is not supported with `text` but translating each line size × .72 will result in a leading (line spaceing) of 1 em (em= fonts body height or points). 20% (× 1.2) may be added.

#### Horizontal alignment
##### left

    The text is aligned with the left side of the bounding box at the given X coordinate. This is the default.

##### 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.

### 3D text

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

## 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.
yields (reformatted for readability):

### 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)
yields (reformatted for readability):