ImageTools[Draw] - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Graphics : Image Processing : ImageTools Package : Draw Subpackage : ImageTools/Draw/Text

ImageTools[Draw]

  

Text

  

ImageTools:-Draw Text Primitive

 

Calling Sequence

Parameters

Description

Fine Control of Spacing (Manual Kerning)

Changing Font Mid-text

Greek and Cyrillic Alphabets

Symbols

Japanese Characters

Package Usage

Examples

Compatibility

Calling Sequence

Text( image, x, y, text, position, font, font_size, rotation, degrees, color, weight, stretch, constrain )

Parameters

image

-

ImageTools:-Image

x

-

numeric

y

-

numeric

text

-

string

position

-

(optional) identical("N","S","E","W","NE","SE","NW","SW","") := ""

font

-

(optional) integer := 13 (roman duplex)

font_size

-

(optional) {numeric, [numeric,numeric]} := 12.0

rotation

-

(optional) numeric := 0.0

degrees

-

(optional) truefalse := false

color

-

(optional) see description

weight

-

(optional) numeric := 1.0

stretch

-

(optional) {numeric, [numeric,numeric]} := 0 (no stretching)

constrain

-

(optional) {numeric, [numeric,numeric]} := 0 (no constraint)

Description

• 

Images can be annotated with text using the Text primitive. The text produced is based on the Hershey vector fonts, first published by Dr. Allen V. Hershey in 1967. These fonts are platform and resolution independent, and are rendered by ImageTools:-Draw using anti-aliasing. They can be rotated, and scaled independently in width and height. In addition to the usual ASCII characters, the Hershey fonts contain Greek and Cyrillic glyphs, a subset of Japanese characters, and a large collection of symbols.

• 

After first creating an image using ImageTools:-Create, or loading an image with ImageTools:-Read, drawing operations can be performed on it using a number of primitives (functions that draw one kind of object). The first argument to each primitive is the image itself, as returned by Create or Read.

• 

The x and y arguments specify an anchor point for the text to be rendered,

• 

The position argument specifies where the text will appear relative to the anchor point. The position can be specified as a 1 or 2-character string, or ImageTools:-Draw exported symbol as defined in the following table:

""

CENTER

Geometric center of the text will coincide with the anchor point.

"N"

NORTH

Text will appear above the anchor point.

"S"

SOUTH

Text will appear below the anchor point.

"E"

EAST

Text will appear to the right of the anchor point.

"W"

WEST

Text will appear to the left of the anchor point.

"NE"

NORTHEAST

Text will appear above and to the right of the anchor point.

"SE"

SOUTHEAST

Text will appear below and to the right of the anchor point.

"NW"

NORTHWEST

Text will appear above and to the left of the anchor point.

"SW"

SOUTHWEST

Text will appear below and to the left of the anchor point.

• 

The font argument specifies which of the Hershey fonts to use. This is specified by number, but ImageTools:-Draw exports several symbolic names that can also be used.

  

0 - CYRILLIC_COMPLEX or CYRILLIC

  

1 - GOTHIC_ENGLISH_TRIPLEX or GOTHIC

  

2 - GOTHIC_GERMAN_TRIPLEX or GERMAN

  

3 - GOTHIC_ITALIAN_TRIPLEX or ITALIAN

  

4 - GREEK_COMPLEX or GREEK

  

5 - GREEK_COMPLEX_SMALL

  

6 - GREEK_PLAIN

  

7 - GREEK_SIMPLEX

  

8 - ITALIC_COMPLEX or ITALIC

  

9 - ITALIC_COMPLEX_SMALL

  

10 - ITALIC_TRIPLEX

  

11 - ROMAN_COMPLEX or ROMAN or SERIF

  

12 - ROMAN_COMPLEX_SMALL

  

13 - ROMAN_DUPLEX or SANS_SERIF

  

14 - ROMAN_PLAIN

  

15 - ROMAN_SIMPLEX

  

16 - ROMAN_TRIPLEX

  

17 - SCRIPT_COMPLEX or SCRIPT

  

18 - SCRIPT_SIMPLEX

  

The fonts with symbols ending in SMALL were optimized for rendering at smaller sizes, and therefore have lower spatial resolution (fewer control points, spaced closer together) in the original Hershey fonts. In Maple, they are scaled to be the same relative size as all the other fonts, but are a good choice when rending in small sizes.

• 

The font_size argument, if given as a single numeric values, specifies the height, in pixels, of the capital letter "X". The size can also be specified as a list of two values, in which case the second value specifies the height. The first value specifies the width, not of a specific glyph, but relative to the second value. For example, font_size=[15,20] specifies than an "X" will be 20 pixels high, and that all glyphs should be scaled to 3/4 of their natural width at the specified height.

• 

Text can be rotated using the rotation argument. Rotations are specified in radians (unless the degrees is true), and proceed counter-clockwise from the positive x-axis. The rotation is performed around the anchor point as implied by the position argument. In the example below, the anchor point is in the center of the image, and position is "E":

• 

The degrees argument specifies if the rotation is in degrees or radians. If degrees is false (i.e. degrees=false is passed, which is the default), the rotation argument must be in radians. If degrees is true (degrees=true or just degrees), the rotation argument must be in degrees. This argument can be specified only as a keyword argument.

• 

The color argument specifies the color of the text and can be specified in one of several forms:

gray

A numeric value between 0 and 1 specifying a shade of gray. The value 0 corresponds to black, and 1 to white.

[r,g,b]

A list of three numeric values between 0 and 1 specifying the red, green, and blue components separately.

[r,g,b,α]

A list of four numeric values between 0 and 1 specifying the red, green, blue, and opacity (alpha) separately. When the opacity is less than 1, the color will be blended with the existing content of the image.

ColorTools:-Color

A value of type ColorTools:-Color.

ColorTools:-Color argument(s)

Any form accepted by the ColorTools:-Color constructor, such as a string giving a color name (e.g. "red", palette and color name (e.g. "Niagara DarkOrchid"), or palette and color number (e.g. "Nautical 1"). Two argument forms are accepted as well, but then it is necessary to always use the keyword form of the color argument, since otherwise the two arguments will be interpreted as two separate arguments to the drawing primitive. For example, color=("HSV",[0.5,0.6,0.6]).

• 

The default line weight can be modified via the weight argument of the Text primitive. The value of this argument is interpreted as a multiplier for the default weight. Weights in the range of 1.2 to 1.8 will typically result in the glyphs becoming completely filled in. Weights that are too heavy will result in a blurring effect:

  

The Hershey fonts were originally designed to be rendered on a vector device, such as an oscilloscope display or pen plotter. As such, the concept of line weight was never incorporated into the original design, as this would depend entirely on the characteristics of the device. ImageTools:-Draw chooses a default line weight (i.e. thickness) based on the font and font_size to replicate the appearance on a typical vector device.

• 

The effect of the weight argument, and how the default is affected by font_size can be seen in this image:

• 

The stretch or constrain arguments can be used to fit text to a specified width and/or height. Each argument accepts either a single numeric value specifying both the width and height, or a list of two values specifying width and height respectively.

  

If the stretch argument is used, the text is stretched or compressed as necessary to fit into the desired space. The result will be text that exactly fills the specified width and/or height. If either the width or height is given as zero, that dimension of the text remains unaffected.

• 

The constrain argument is similar to stretch, except that the text is never enlarged. If it already fits a dimension, its size in that dimension is not altered. Furthermore, if both width and height are constraints are given, the text is scaled the same amount in both dimensions to satisfy the tighter constraint. Its aspect ratio does not change.

• 

The Text primitive returns a pair of values giving the font size that was actually used. If neither the stretch nor constrain arguments were passed, then these sizes will be the same as the font_size that was passed (or the default if none was given).

• 

The options beginning with position are best provided as keyword equations, but can also be provided as positional arguments starting in the 5th position as declared in the calling sequence above.  Only the degrees option must be passed as a keyword argument if used.

Fine Control of Spacing (Manual Kerning)

• 

Each glyph in the Hershey fonts has its own defined bounding box. When the characters are rendered, the bounding boxes are placed adjacent to one another. Although this produces acceptable output for most applications, it is sometimes desirable to increase or decrease the inter-character spacing to be more aesthetically pleasing. The Text primitive understands two special characters, backspace (entered into a string as "\b") and tab ("\t"), which respectively remove or insert one half of the current thickness of line used to render the characters.

  

The second line in the image above was created by passing the string, "A\b\bC\bT\tIV\b\b\b\bA\b\bT\tIO\bN T\b\b\b\by\b\bp\be\b\bw\b\br\t\titer" to the Text primitive.

Changing Font Mid-text

• 

Usually, an entire string is rendered by the Text primitive using a single font. It is possible to change fonts in the middle of a string by including a formfeed character (entered into a string as "\f"), followed by one or two digits specifying the new font number (if a digit is to appear immediately after changing to a single-digit font, simply include a leading zero before the font number).

• 

For example, the string "Embedded \f8italic\f11 and \f17script\f11 text" will render like this (assuming font 11 was specified as the font argument initially):

Greek and Cyrillic Alphabets

• 

Because of the close correspondence between the Latin alphabet, and the Greek and Cyrillic alphabets, the Text primitive will map Latin characters to Greek or Cyrillic characters when the appropriate font is selected. The following image shows the mapping, with the Latin (ASCII) character on the left, and the corresponding Greek or Cyrillic character on the right.

  

Mapping of Latin to Greek characters:

  

Mapping of Latin to Cyrillic characters:

• 

These mappings allow many, but far from all, Greek or Cyrillic words to be specified using the English transliteration (not translation) of the word. For example, the first line of the image below was generated from the string, "Vostok, Pilot = \f0Vostok, Pilot", whereas the second line required "Archimedes = \f4Arximhdhw":

  

An example of Latin to Cyrillic and Greek mapping:

• 

Notice also that there is an accent missing on the first η, as the Text primitive currently has no way to indicate accented characters (although the accent marks do exist as separate glyphs).

Symbols

• 

The Hershey font set contains a large number of glyphs for special symbols that are not part of the usually 7-bit ASCII character set. The Text primitive lets you include these symbols within a string by inserting an escape character (entered into a string as "\e"), followed by a series of up to four digits giving the glyph number (if a digit is to appear immediately after a symbol whose glyph number is less than four digits, simply include enough leading zeros to pad the number out to four digits).

• 

Note that the glyph numbers do not correspond to Unicode symbol numbers (a mechanism to accept Unicode strings is planned for a future version of ImageTools:-Draw).

• 

Images showing all of the glyphs, including those of the ordinary ASCII characters in the various supported fonts, are reproduced below:

• 

All supported alphanumeric and symbol glyphs (1 of 2). Click to view full size (1427×2262 pixels):

• 

All supported alphanumeric and symbol glyphs (2 of 2). Click to view full size (1427×2276 pixels):

Japanese Characters

• 

In addition to the symbols described above, the font set contains a very small subset of Japanese characters (758 in total, including some that are obsolete). These are used in the same way as the symbols, by inserting an escape character and the four-digit number of the glyph.

Package Usage

• 

This function is part of the ImageTools:-Draw package, so it can be used in the short form Text(..) only after executing the command with(ImageTools:-Draw). However, it can always be accessed through the long form of the command by using ImageTools:-Draw:-Text(..).

Examples

withImageTools:

withImageTools:-Draw:

Collage of text samples.

img ≔ Create240,320,channels=3,background=white:

Textimg,5,235,Text Samples,position=SE,font=16,font_size=20,weight=1.5,color=maroon:

Textimg,10,145,Roman Plain,position=E,font=14,font_size=20,weight=1.2,color=0,0.5,0,rotation=15,degrees:

Textimg,5,110,Italic Triplex,position=E,font=10,font_size=20,weight=1.5,color=0,0.5,0.5:

Textimg,10,80,Script Complex,position=E,font=17,font_size=20,weight=1.5,color=blue,rotation=Pi12:

Textimg,310,120,Vertical Text,position=N,font=1,font_size=25,color=0.5,0,0.5,rotation=90,degrees:

Textimg,270,135,Kirillica,position=N,font=0,font_size=20,color=0.25,0.25,0.25,rotation=Pi2:

Textimg,5,5,WIDE,position=NE,font=11,font_size=45,20,weight=1.2,color=0.5,0.5,0:

Textimg,195,5,NARROW,position=NE,font=11,font_size=10,20,weight=1.5,color=0.75,0.5,0:

Embedimg

Sample of each font 10.

img ≔ Create35,320,channels=3,background=white:

Textimg,5,17,ABCD abcd 0123 $&?*,position=E,font=10,font_size=17,weight=1.2,color=0:

Embedimg

The font_size argument.

img ≔ Create120,400,channels=3,background=white:

Textimg,10,100,font_size=20,position=E,font=11,font_size=20,weight=1.5,color=0:

Textimg,10,60,font_size=[14,20],position=E,font=11,font_size=14,20,weight=1.5,color=0:

Textimg,10,20,font_size=[28,20],position=E,font=11,font_size=28,20,weight=1.5,color=0:

Embedimg

The rotation argument.

img ≔ Create400,400,channels=3,background=0.1,0.1,0.1:

forrfrom0by30to359doTextimg,200,200,sprintf--rotation=%3d718,r,position=E,font=11,font_size=15,weight=1.10,rotation=r,degrees=true,color=HSV,r360,1,1end do:

Embedimg

Effect of the weight argument with different font sizes.

img ≔ Create380,620,channels=3,background=white:

Textimg,10,360,font_size=12,position=E,font=11,font_size=12,weight=1.5,color=blue:

Textimg,10,336,font_size=20,position=E,font=11,font_size=20,weight=1.5,color=blue:

Textimg,12,290,weight=1.0,position=E,font=11,font_size=12,weight=1.0,color=0:

Textimg,12,210,weight=1.5,position=E,font=11,font_size=12,weight=1.5,color=0:

Textimg,12,130,weight=2.0,position=E,font=11,font_size=12,weight=2.0,color=0:

Textimg,12,50,weight=3.3,position=E,font=11,font_size=12,weight=3.3,color=0:

Textimg,10,260,weight=1.0,position=E,font=11,font_size=20,weight=1.0,color=0:

Textimg,10,180,weight=1.5,position=E,font=11,font_size=20,weight=1.5,color=0:

Textimg,10,100,weight=2.0,position=E,font=11,font_size=20,weight=2.0,color=0:

Textimg,10,20,weight=3.3,position=E,font=11,font_size=20,weight=3.3,color=0:

Textimg,255,350,font_size=40,position=E,font=11,font_size=30,40,weight=1.5,color=blue:

Textimg,255,280,weight=1.0,position=E,font=11,font_size=40,weight=1.0,color=0:

Textimg,255,200,weight=1.5,position=E,font=11,font_size=40,weight=1.10,color=0:

Textimg,255,120,weight=2.0,position=E,font=11,font_size=40,weight=2.0,color=0:

Textimg,255,40,weight=3.3,position=E,font=11,font_size=40,weight=3.3,color=0:

Embedimg

Using the stretch argument.

wL,hL,xOff,yOff ≔ 240,60,50,30:

fntSz ≔ wL13:

wR,hR ≔ 330,floorfntSz0.9:

img ≔ Create4hL+5yOff,wL+wR+3xOff,channels=3,background=0.5:

forcwin0,1doforchin0,1dor ≔ 1cw2+1ch;x ≔ xOff;y ≔ ryOff+hL+yOff;SolidRectangleimg,x,y,x+wL,y+hL,color=0.75,0,0;Textimg,x+wL2,y+hL2,sprintfstretch=[%03d,%03d],wLcw,hLch,position=*,font=16,font_size=fntSz,color=1,stretch=wLcw,hLch;x ≔ xOff2+wL;y ≔ y+hLhR2;SolidRectangleimg,x,y,x+wR,y+hR,color=0.75,0,0;Textimg,x+wR2,y+hR2,sprintfstretch=[%03d,%03d],wRcw,hRch,position=*,font=16,font_size=fntSz,color=1,stretch=wRcw,hRchend doend do:

Embedimg

Using the constrain argument.

wL,hL,xOff,yOff ≔ 240,60,50,30:

fntSz ≔ wL13:

wR,hR ≔ 330,floorfntSz0.9:

img ≔ Create4hL+5yOff,wL+wR+3xOff,channels=3,background=0.5:

r ≔ 3:

forcwin0,1doforchin0,1dor ≔ 1cw2+1ch;x ≔ xOff;y ≔ ryOff+hL+yOff;SolidRectangleimg,x,y,x+wL,y+hL,color=0.75,0,0;Textimg,x+wL2,y+hL2,sprintfconstrain=[%03d,%03d],wLcw,hLch,position=*,font=16,font_size=fntSz,color=1,constrain=wLcw,hLch;x ≔ xOff2+wL;y ≔ y+hLhR2;SolidRectangleimg,x,y,x+wR,y+hR,color=0.75,0,0;Textimg,x+wR2,y+hR2,sprintfconstrain=[%03d,%03d],wRcw,hRch,position=*,font=16,font_size=fntSz,color=1,constrain=wRcw,hRchend doend do:

Embedimg

Manual kerning using b and t.

img ≔ Create105,420,channels=3,background=white:

Textimg,10,75,ACTIVATION Typewriter,position=E,font=13,font_size=25,weight=1.2,color=0:

Textimg,10,25,ACT IVAT ION Typewr iter,position=E,font=13,font_size=25,weight=1.2,color=0:

Embedimg

Changing font mid-text using f.

img ≔ Create55,600,channels=3,background=white:

Textimg,10,25,Embedded 8italic11 and 17script11 text,position=E,font=11,font_size=25,weight=1.2,color=0:

Embedimg

Generate the charts mapping Latin to Greek and Cyrillic characters.

w,h ≔ 720,roundw811:

rs,cs ≔ roundh13,roundw9:

fntSz ≔ h33.33:

forLin0,cy-map,4,gr-mapdoimg ≔ Createh,w,3,background=white;forrfrom0to11doforcfrom0to7doch ≔ convertr8+c+32,bytes;Textimg,c+1cs,hr+1rs,sprintf%s=%02d%s,ch,L1,ch,position=*,font=13,font_size=fntSz,color=0end doend do;ifL2=cy-mapthenimgC ≔ imgelseimgG ≔ imgend ifend do:

EmbedimgC

EmbedimgG

A sample of some of the available non-ASCII glyphs.

img ≔ Create200,450,channels=3,background=white:

Textimg,10,175,Math: 1411 2268 2269 2265 2266 2270 ...,position=E,font=11,font_size=25,weight=1.2,color=0:

Textimg,10,125,Zodiac: 2301 2302 2303 2304 2305 ...,position=E,font=11,font_size=25,weight=1.2,color=0:

Textimg,10,75,Music: 2324 2325 2330 2381 2378 ...,position=E,font=11,font_size=25,weight=1.2,color=0:

Textimg,10,25,Weather: 764 765 766 767 768 ...,position=E,font=11,font_size=25,weight=1.2,color=0:

Embedimg

Generate the charts of (1) Japanese characters and (2) all other glyphs.

glyphW ≔ 67:

forchartinround21.3glyphW&comma;jp&comma;4000&comma;4757&comma;round21.3glyphW&comma;sy1&comma;1&comma;2200&comma;round21.3glyphW&comma;sy2&comma;2201&comma;3926dow&comma;file&comma;lo&comma;hi ≔ opchart&semi;h ≔ roundw1.7&semi;x&comma;y ≔ glyphW4&comma;10&semi;img ≔ Createh&comma;w&comma;3&comma;background&equals;white&semi;dymax ≔ 0&semi;fornfromlotohidos ≔ sprintf%d&comma;n&semi;dx&comma;dy ≔ TextSizeimg&comma;s&comma;font&equals;14&comma;font_size&equals;12&comma;weight&equals;1.2&semi;dx&comma;dy ≔ dx1&comma;dy1&semi;ifdx&comma;dy0.&comma;0.thenTextimg&comma;x&plus;5&comma;hy&comma;sprintf%d&comma;n&comma;position&equals;SE&comma;font&equals;14&comma;font_size&equals;10&comma;color&equals;red&comma;weight&equals;1.2&semi;Textimg&comma;x&plus;5&comma;hy17&comma;s&comma;position&equals;SE&comma;font&equals;14&comma;font_size&equals;12&comma;color&equals;0&comma;weight&equals;1.2&semi;while5<dxdox ≔ x&plus;glyphW&semi;dx ≔ dxglyphWend do&semi;ifdymax<dythendymax ≔ dyend if&semi;ifw3glyphW4xorn&equals;hithenx ≔ glyphW4&semi;y ≔ y&plus;25&plus;dymax&semi;dymax ≔ 0&semi;ifhythenbreakend ifend ifend ifend do&semi;img ≔ img1..roundy&plus;10&comma;..&comma;..&semi;assigncat&apos;img_&apos;&comma;chart2&comma;imgend do&colon;

Embedimg_jp

Embedimg_sy1

Embedimg_sy2

ASCII to Cyrillic and Greek mapping.

img ≔ Create105&comma;640&comma;channels&equals;3&comma;background&equals;white&colon;

Textimg&comma;10&comma;75&comma;Vostok, Pilot = 0Vostok, Pilot&comma;position&equals;E&comma;font&equals;11&comma;font_size&equals;25&comma;weight&equals;1.2&comma;color&equals;0&colon;

Textimg&comma;10&comma;25&comma;Archimedes = 4Arximhdhw&comma;position&equals;E&comma;font&equals;11&comma;font_size&equals;25&comma;weight&equals;1.2&comma;color&equals;0&colon;

Embedimg

Compatibility

• 

The ImageTools[Draw][Text] command was introduced in Maple 2018.

• 

For more information on Maple 2018 changes, see Updates in Maple 2018.

See Also

ImageTools

ImageTools:-Draw:-Circle

ImageTools:-Draw:-Line

ImageTools:-Draw:-Poly

ImageTools:-Draw:-SolidRectangle

ImageTools:-Draw:-TextSize