Drawing module
#include "diplib/generation.h"
dip::FreeTypeTool class

Class used to draw text using a specified font file (TTF, OTF, etc).

Reference

An object of this class must first be given the file name of a font on disk, which can be done either in the constructor or through dip::FreeTypeTool::SetFont. This font is subsequently used to render text in an image using dip::FreeTypeTool::DrawText. The text size can be specified by calling dip::FreeTypeTool::SetSize before rendering.

This class supports the most common font file formats (TrueType, Type 1, CID-keyed and OpenType/CFF fonts are supported). A default font is not provided because there is no standard for where these files are to be found (on some platforms it’s an easier problem than on others). A program that uses FreeTypeTool could be distributed with a font file.

Example usage:

dip::FreeTypeTool freeTypeTool( "/usr/share/fonts/truetype/times.ttf" );

FreeTypeTool objects cannot be copied, they can only be moved.

Constructors, destructors, assignment and conversion operators

FreeTypeTool(): A default-constructed object cannot be used until a font is set with dip::FreeTypeTool::SetFont.
FreeTypeTool(dip::String const& font) explicit: This constructor immediately sets a font, see dip::FreeTypeTool::SetFont for details.

Classes

struct TextInfo: Data structure returned by dip::FreeTypeTool::DrawText.

Functions

void SetFont(dip::String const& font): Set the font to be used to render text.
void SetSize(dip::dfloat size): Set the font size to be used to render text.
void DrawText(dip::Image& out, dip::String const& text, dip::FloatArray origin, dip::Image::Pixel const& value = {1}, dip::dfloat orientation = 0, dip::String const& align = S::LEFT): Render text in an existing image.
auto DrawText(dip::String const& text, dip::dfloat orientation = 0) -> dip::FreeTypeTool::TextInfo: Alternate version of the function above that returns a new image tightly cropped around the rendered text.

Class documentation

struct TextInfo

Data structure returned by dip::FreeTypeTool::DrawText.

Variables
dip::Image image	The image with the rendered text.
dip::IntegerArray left	Coordinates within `image` of the point on the baseline at the left edge of the text.
dip::IntegerArray right	Coordinates within `image` of the point on the baseline at the right edge of the text.

Function documentation

void SetFont(dip::String const& font)

Set the font to be used to render text.

font is the full path to a file with a type face description (TrueType, Type 1, CID-keyed and OpenType/CFF fonts are supported).

It is fine to switch fonts in between calls to dip::FreeTypeTool::DrawText. When changing the font, the size selected through dip::FreeTypeTool::SetSize is not preserved, and needs to be set anew. By default, the size is set to 12 pixels.

This function is not thread-safe.

void SetSize(dip::dfloat size)

Set the font size to be used to render text.

size is the EM square size in pixels (equivalent to the size in points at 72 dpi). It depends on the selected font how many pixels a letter actually takes up.

void DrawText(dip::Image& out, dip::String const& text, dip::FloatArray origin, dip::Image::Pixel const& value = {1}, dip::dfloat orientation = 0, dip::String const& align = S::LEFT)

Render text in an existing image.

Draws text in the image out, at location origin, with a color given by value, and rotated according to orientation.

text is any UTF-8 encoded string, even if Unicode support was not enabled when building DIPlib. But note that any ASCII string is also a properly UTF-8 encoded string. Characters that don’t have a glyph in the given type face font will be rendered with the character known as “missing glyph”, typically a box or a space. Note that control characters such as the newline and the backspace are not treated specially, and thus they will be drawn as a missing glyph. To draw multiple lines of text, call this function for each line in turn.

origin is the pixel coordinates of a point on the base line. If align is "left", origin is a point on the left edge of the rendered text; if align is "right", it is a point on the right edge; and if it is "center", it is the point halfway between the left and right edges. orientation is in radian, with 0 for horizontal text, and increasing clockwise.

out must be a forged 2D image. If out is binary, the anti-aliased glyphs will be thresholded. value must have the same number of tensor elements as out. If value is scalar, this value will be used for all tensor elements.

dip::FreeTypeTool::TextInfo DrawText(dip::String const& text, dip::dfloat orientation = 0)

Alternate version of the function above that returns a new image tightly cropped around the rendered text.

The output image is a 2D scalar image of type dip::DT_UINT8, with white text on a black background. The output data structure additionally contains the two end points of the baseline, on either side of the rendered text.

See dip::FreeTypeTool::DrawText for a description of the text and orientation arguments.