API Docs

Class: Font

PD. Font

Converts JSON font data into cached shape geometry.

This is basically a re-implementation of the THREE.Font class, but giving access to the glyph generation code and allowing the creation and caching of each glyph as THREE.Shape objects with raw vertex, contour and face data.

The key benefit of caching font geometry is that you can know the dimensions of each character beforehand. This allows for the alignment and formatting of complex and multi-line text strings.

When cached, all font geometry is normalised to a size of 1 font unit. Every glyph in the font will fit inside a box that is 1 font unit wide and one font unit high. This allows the font to be accurately sized and scaled, but often means that formatting information needs to be given in font units rather than absolute dimensions. To get absolute dimensions, simply multiply font units by the required font size.

new Font(fontData)

Creates a new cached font.

Parameters:
Name Type Description
fontData object

The parsed JSON object that defines a THREE font.
Author:
  • drajmarsh

Members

:object

glyphCache

A mapped cache of generated geometry from font glyphs.

Each entry in the glyph cache is an object with the following properties:

Type Name Description
number width The width of the normalised character (0 to 1).
Array shapes An array of zero or more THREE.Shape objects.
Array data The cached geometric data object, normalised to unit size.
Array data[n].vertices An array of THREE.Vector3 giving the vertices in the shape.
Array data[n].contours An array of contours with vertex indices for the outer boundary and internal holes.
Array data[n].faces An array of triangular faces, each with three vertex indexes.
Type
  • object
:boolean

isFont <readonly>

A flag identifying this object as a font.

Type
  • boolean
:number

lineHeight

The relative vertical distance between font baselines.

Type
  • number
:number

lineHeightFactor

The fraction of the line height to apply.

Type
  • number
:PD.Font

defaultFont <static>

A cut-down font with just numerals and some punctuation.

This font contains just those characters needed to display dimensions lines.

Type

Methods

addTextToBRep(brep, face, text [, xform] [, align] [, offset])

Adds positioned, scaled and aligned face geometry from a text string.

Parameters:
Name Type Argument Default Description
brep PD.BRep

The BRep the face belongs to.
face PD.BRep.Face

The face to add the glyph into.
text string

The string of characters to represent in the mesh.
xform THREE.Matrix4 | PD.LocalCoordinates <optional>

A transformation matrix to apply or a set of local coordinates.
align PD.ALIGN <optional>
 0

The alignment of the text relative to the anchor position.
offset number <optional>
 0

An optional vertical offset given in font units.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font

addTextToMeshBuilder(builder, text, matrix [, align] [, offset])

Adds positioned, scaled and aligned mesh geometry from a text string.

Parameters:
Name Type Argument Default Description
builder PD.MeshBuilder

The mesh builder to add the glyph data to.
text string

The string of characters to represent in the mesh.
matrix THREE.Matrix4

The transformation matrix to multiply the geometry by.
align PD.ALIGN <optional>
 0

The alignment of the text relative to the anchor position.
offset number <optional>
 0

An optional vertical offset given in font units.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font

addTextToPolyMesh(mesh, text, matrix [, align] [, offset])

Adds positioned, scaled and aligned mesh geometry from a text string.

Parameters:
Name Type Argument Default Description
mesh PD.PolyMesh

The dynamic mesh to add the text geometry to.
text string

The string of characters to represent in the mesh.
matrix THREE.Matrix4

The transformation matrix to multiply the geometry by.
align PD.ALIGN <optional>
 0

The alignment of the text relative to the anchor position.
offset number <optional>
 0

An optional vertical offset given in font units.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font

addTextToPolyMeshInLocalCoords(mesh, text, coords [, align] [, offset])

Adds positioned, scaled and aligned mesh geometry from a text string.

Parameters:
Name Type Argument Default Description
mesh PD.PolyMesh

The dynamic mesh to add the text geometry to.
text string

The string of characters to represent in the mesh.
coords PD.LocalCoordinates

The local coordinate system to use.
align PD.ALIGN <optional>
 0

The alignment of the text relative to the anchor position.
offset number <optional>
 0

An optional vertical offset given in font units.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font

addTextToShell(shell, poly, text [, xform] [, align] [, offset])

Adds positioned, scaled and aligned face geometry from a text string.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell the facet belongs to.
poly PD.Polygon

The polygonal facet to add the glyph into.
text string

The string of characters to represent in the mesh.
xform THREE.Matrix4 | PD.LocalCoordinates <optional>

A transformation matrix to apply or a set of local coordinates.
align PD.ALIGN <optional>
 0

The alignment of the text relative to the anchor position.
offset number <optional>
 0

An optional vertical offset given in font units.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font

generateShapes(text, size)

Generates an array of shapes representing the text at the given size.

This works in exactly the same way as the generateShapes() method on a THREE.Font. It does not use any cached glyphs, but generates the shapes in the right position within the string and at the given size.

Parameters:
Name Type Default Description
text string

The string of characters to represent as shapes.
size number 1000

The size of each character shape in model units.
Returns:

Returns an array of shapes representing the text.

Type
Array

generateTextAsPolygons(text, pos, size, align)

Generates an array of polygons from a positioned, scaled and aligned text string.

NOTE: Some characters such as double quotes will actually require two polygons to represent them, so there is not always a direct correspondence between the index of a character in the text string and the resulting polygon.

Parameters:
Name Type Default Description
text string

The string of characters to represent as polygons.
pos THREE.Vector3

The anchor position of the text block in model space.
size THREE.Vector2 | number 250

The size of each character as a number or vector, in model units.
align PD.ALIGN 0

The alignment of the text relative to the anchor position.
Returns:

Returns an array of polygons representing the text.

Type
Array

generateTextAsShapes(text, pos, size, align)

Generates an array of positioned, scaled and aligned text shapes.

Parameters:
Name Type Default Description
text string

The string of characters to represent as shapes.
pos THREE.Vector3

The anchor position of the text block in model space.
size number 250

The size of each character shape in model units.
align PD.ALIGN 0

The alignment of the text relative to the anchor position.
Returns:

Returns an array of shapes representing the text.

Type
Array

getTextHeight(text)

Calculates the total height of all lines in the text string, in font units.

Calculated line heights are given in font units. To obtain the actual height, simply multiply the returned height value by the size of font you want.

Parameters:
Name Type Description
text string

A single or multi-line text string to compute the height of.
Returns:

Returns the total line height in font units.

Type
number

getTextWidth(text)

Calculates the width of the widest line in the text string in font units.

Calculated line widths are given in font units. To obtain the actual width, simply multiply the returned width value by the size of font you want.

In order to compute the width of each character, calling this method will also update the cache with the characters in the text.

Parameters:
Name Type Description
text string

A single or multi-line text string to compute the width of.
Returns:

Returns the total normalised line width in font units.

Type
number

initialiseCache(text)

Seeds the glyph cache with characters in the given string.

Parameters:
Name Type Description
text string

A text string containing the characters to seed the cache with.
Returns:

Returns this cached font to support method chaining.

Type
PD.Font