qc_get_font_glyphs :: QUARC MATLAB Functions

navigation bar

qc_get_font_glyphs

Gets detailed information about characters in a font, including glyphs for each character in the given text.

Syntax

details = qc_get_font_glyphs(font, text, ...)   % Get character information

Description

Gets detailed information about a font and selected characters within the font, including glyphs for the selected characters.

The details structure returned has two fields:

Field Name	Description
font	A structure describing the font metrics.
glyphs	A structure array describing each character in the given text, including monochrome and grayscale bitmaps for each character.

The fields of the font structure are:

Field Name

Description

height

The height of characters (ascent + descent).

ascent

The ascent of characters i.e. units above the baseline.

descent

The descent of characters i.e. units below the baseline.

internal_leading

The amount of leading or space inside the bounds of the character height where accents and other diacritical marks may occur.

external_leading

The amount of extra leading or space to add between rows. This area is outside the character cell so nothing is drawn in this area.

average_character_width

The average width of characters in the font, which is generally the width of the character 'x'. It does not include extra width for bold or italic characters.

maximum_character_width

The maximum width of a character in the font.

weight

The weight of the font.

overhang

The extra width per string that may be added for some synthesized fonts, such as bold or italic fonts that are synthesized.

digitized_aspect_x

The horizontal aspect of the device on which the font was designed.

digitized_aspect_y

The vertical aspect of the device on which the font was designed.

first_character

The value of the first character defined in the font.

last_character

The value of the last character defined in the font.

default_character

The character to use when a character is not defined in the font.

break_character

The character to use when defining word breaks for text justification.

italic

Whether the font is italic (true) or not (false).

underlined

Whether the font is underlined (true) or not (false).

struck_out

Whether the font is struck out (true) or not (false).

pitch

A cell array of strings defining the pitch of the font. Possible values are:

'device'	=	the font is a device font.
'truetype'	=	the font is a TrueType font.
'variable'	=	the font is variable pitch. If absent, the font is variable pitch.
'vector'	=	the font is a vector font.

family

A string indicating the font family. Possible values are: 'decorative', 'dontcare', 'modern', 'roman', 'script', 'swiss'.

character_set

A string indicating the character set to which the font belongs. Possible values are: 'default', 'ansi', 'baltic', 'chinesebig5', 'easteurope', 'gb2312', 'greek', 'hangul', 'mac', 'oem', 'russian', 'shiftjis', 'symbol', 'turkish', 'vietnamese', 'johab', 'arabic', 'hebrew', 'thai'.

panose

A structure defining the PANOSE information for the font. If defined, the fields of the structure are:

family_type	=	A string describing the PANOSE family type. Possible values are: 'any', 'no_fit', 'text_and_display', 'script', 'decorative' or 'pictorial'.
serif_style	=	A string describing the PANOSE serif style. Possible values are: 'any', 'no_fit', 'cove', 'obtuse_cove', 'square_cove', 'obtuse_square_cove', 'square', 'thin', 'bone', 'exaggerated', 'triangle', 'normal_sans', 'obtuse_sans', 'perp_sans', 'flared' or 'rounded'.
weight	=	A string describing the PANOSE weight. Possible values are: 'any', 'no_fit', 'very_light', 'light', 'thin', 'book', 'medium', 'demibold', 'bold', 'heavy', 'black', 'nord'.
proportion	=	A string describing the PANOSE proportion. Possible values are: 'any', 'no_fit', 'old_style', 'modern', 'even_width', 'expanded', 'condensed', 'very_expanded', 'very_condensed', 'monospaced'.
contrast	=	A string describing the PANOSE contrast. Possible values are: 'any', 'no_fit', 'none', 'very_low', 'low', 'medium_low', 'medium', 'medium_high', 'high', 'very_high'.
stroke_variation	=	A string describing the PANOSE stroke variation. Possible values are: 'any', 'no_fit', 'gradual_diagonal', 'gradual_transitional', 'gradual_vertical', 'gradual_horizontal', 'rapid_vertical', 'rapid_horizontal', 'instant_vertical'.
arm_style	=	A string describing the PANOSE arm style. Possible values are: 'any', 'no_fit', 'straight_arms_horizontal', 'straight_arms_wedge', 'straight_arms_vertical', 'straight_arms_single_serif', 'straight_arms_double_serif', 'bent_arms_horizontal', 'bent_arms_wedge', 'bent_arms_vertical', 'bent_arms_single_serif', 'bent_arms_double_serif'.
letter_form	=	A string describing the PANOSE letter formation. Valid values are: 'any', 'no_fit', 'normal_contact', 'normal_weighted', 'normal_boxed', 'normal_flattened', 'normal_rounded', 'normal_off_center', 'normal_square', 'oblique_contact', 'oblique_weighted', 'oblique_boxed', 'oblique_flattened', 'oblique_rounded', 'oblique_off_center', 'oblique_square'.
midline	=	A string describing the PANOSE midline. Valid values are: 'any', 'no_fit', 'standard_trimmed', 'standard_pointed', 'standard_serifed', 'high_trimmed', 'high_pointed', 'high_serifed', 'constant_trimmed', 'constant_pointed', 'constant_serifed', 'low_trimmed', 'low_pointed', 'low_serifed'.
x_height	=	A string describing the PANOSE X height. Valid values are: 'any', 'no_fit', 'constant_small', 'constant_standard', 'constant_large', 'ducking_small', 'ducking_standard', 'ducking_large'.

selection

A cell array of strings defining the font selection pattern. Valid strings are: 'italic', 'underscore', 'negative', 'outline', 'strikeout', 'bold'.

licensing

A string defining the font licensing. If it is empty there are extra licensing restrictions. Valid values are:

'do not embed'	=	the font may not be embedded in another document.
'read-only'	=	the font embedding is read-only.

slope_rise

The vertical displacement defining the slope of the cursor.

slope_run

The horizontal displacement defining the slope of the cursor.

italic_angle

The italic angle of the font in degrees, measured counterclockwise from vertical. It may be fractional. Italic fonts typically have a negative angle (e.g. -12 degrees)

em_square

The width or height of the em square for this font in logical units.

maximum_ascent

The maximum distance characters in this font extend above the baseline (the typographic ascent of the font).

maximum_descent

The maximum distance characters in this font extend below the baseline (the typographic descent of the font).

line_gap

The distance between lines of text when using single spacing.

font_box

A structure defining the bounding box for the font. The fields of the structure are: top, left, bottom, and right.

mac_ascent

The maximum distance characters in this font extend above the baseline on the Macintosh.

mac_descent

The maximum distance characters in this font extend below the baseline on the Macintosh.

mac_line_gap

The distance between lines of text when using single spacing on the Macintosh.

minimum_pixels_per_em_square

The smallest recommended size for this font in pixels per em square.

subscript_size

A structure defining the recommended size for subscripts. The fields of the structure are x and y.

subscript_offset

A structure defining the recommended offset for subscripts. The fields of the structure are x and y.

superscript_size

A structure defining the recommended size for superscripts. The fields of the structure are x and y.

superscript_offset

A structure defining the recommended offset for superscripts. The fields of the structure are x and y.

strikeout_size

The width of the strikeout stroke, which is usually the width of the em dash character.

strikeout_position

The position of the strikeout stroke relative to the baseline of the font.

underline_size

The thickness of the underline character.

underline_position

The position of the underline character relative to the baseline of the font.

family_name

A string defining the font family.

face_name

A string defining the font face.

style_name

A string defining the font style.

full_name

A string defining the full name of the font.

The fields of the glyphs structure are:

Field Name

Description

mono_bitmap

A monochrome bitmap of the character glyph. Each byte is either 0 or 255. This bitmap may be displayed using

gray_bitmap

A grayscale bitmap of the character glyph. The number of grayscale levels depends on the options passed to the qc_get_font_glyphs function. See the 'gray5', 'gray17' and 'gray65' options below. This bitmap may be displayed using

metrics

A structure defining certain metrics of the character glyph. The fields of the structure are:

black_box	=	A structure defining the bounding box of the glyph. The fields of the structure are x and y.
origin	=	The top, left corner of the bounding box of the glyph relative to the baseline of the character.
cell_increment	=	The distance to the next character when displaying a string of characters.

outline

A structure array defining the contours for the character. This field is only defined for TrueType fonts and is useful for writing EPS or SVG files using the font, but drawing the characters as shapes rather than text. The first contour generally defines the shape of the character, while subsequent contours define holes in the character (e.g. the holes in the number '8'). The fields of the structure are:

start

A structure defining the starting point for the contour. The fields of the structure are x and y.

curves

A structure array defining the curves in the contour. The fields of this structure are:

type	=	A string defining the type of curve. Valid values are: 'line', 'quadratic_spline' and 'cubic_spline'. Cubic splines are generated when the 'cubic' option is passed to qc_get_font_glyphs.
points	=	A structure array defining the points in the curve. The field of this structure are x and y.

Parameters

font

A structure defining the font to use. The structure has the following optional fields. If a field is omitted then a suitable default is used.

Field Name	Description
height	The height of the font in pixels.
width	The width of the font in pixels.
escapement	The escapement angle in degrees (may be fractional).
orientation	The orientation angle in degrees (may be fractional).
weight	The font weight (1.0 = normal, smaller is thinner, larger is bolder, 1.75 is standard bold, 2.5 is maximum weight).
italic	Whether to make the font italic (true or false).
underline	Whether to underline the font (true or false).
strikeout	Whether to strike out the font (true or false).
character_set	A string indicating the character set to use. Valid values are: 'default', 'ansi', 'baltic', 'chinesebig5', 'easteurope', 'gb2312', 'greek', 'hangul', 'mac', 'oem', 'russian', 'shiftjis', 'symbol', 'turkish', 'vietnamese', 'johab', 'arabic', 'hebrew', 'thai'.
output_precision	A string indicating the output precision. Valid values are: 'default', 'character', 'device', 'outline', 'ps_only', 'raster', 'string', 'stroke', 'tt_only', 'tt'.
clip_precision	A string indicating the clip precision. Valid values are: 'default', 'character', 'stroke'.
quality	A string indicating the quality. Valid values are: 'antialiased', 'cleartype', 'default', 'draft', 'nonantialiased', 'proof'.
pitch	A string indicating the pitch. Valid values are: 'default', 'fixed', 'variable'.
family	A string indicating the family. Valid values are: 'decorative', 'dontcare', 'modern', 'script', 'swiss'.
face	A string containing the name of the font face to use e.g. 'Times New Roman'.

text

A string containing the characters for which to obtain the glyph information.

...

The function may take additional options as arguments:

Option	Description
'native'	Return outlines in rasterizer's native format (default).
'cubic'	Return cubic Bezier splines instead of the rasterizer's native format.
'unhinted'	Return unhinted outlines only.
'gray5'	Retrieve gray_bitmap with five levels of gray
'gray17'	Retrieve gray_bitmap with 17 levels of gray.
'gray65'	Retrieve gray_bitmap with 65 levels of gray (default).

Outputs

details

A structure array containing the details about the characters in the font. See the above description for more information.

Examples

font.height = 100;                          % make text 100 pixels high
details = qc_get_font_glyphs(font, 'abcd'); % get glyphs for the characters 'a', 'b', 'c' and 'd'
imshow(details.glyphs(1).gray_bitmap);      % show letter 'a' as an image