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
Text( image, x, y, text, position, font, font_size, rotation, degrees, color, weight, stretch, constrain )
image
-
ImageTools:-Image
x
numeric
y
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)
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 an 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.
"B"
BASELINE
Geometric center of the text's baseline will coincide with the anchor point.
"BE"
BASELINE_EAST
Text will appear to the left of the anchor point, with the baseline passing through the anchor point.
"BW"
BASELINE_WEST
Text will appear to the right of the anchor point, with the baseline passing through 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.
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.
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):
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).
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):
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.
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(..).
with⁡ImageTools:
with⁡ImageTools:-Draw:
Collage of text samples.
img≔Create⁡240,320,channels=3,background=white:
Text⁡img,5,235,Text Samples,position=SE,font=16,font_size=20,weight=1.5,color=maroon:
Text⁡img,10,145,Roman Plain,position=E,font=14,font_size=20,weight=1.2,color=0,0.5,0,rotation=15,degrees:
Text⁡img,5,110,Italic Triplex,position=E,font=10,font_size=20,weight=1.5,color=0,0.5,0.5:
Text⁡img,10,80,Script Complex,position=E,font=17,font_size=20,weight=1.5,color=blue,rotation=−π12:
Text⁡img,310,120,Vertical Text,position=N,font=1,font_size=25,color=0.5,0,0.5,rotation=90,degrees:
Text⁡img,270,135,Kirillica,position=N,font=0,font_size=20,color=0.25,0.25,0.25,rotation=π2:
Text⁡img,5,5,WIDE,position=NE,font=11,font_size=45,20,weight=1.2,color=0.5,0.5,0:
Text⁡img,195,5,NARROW,position=NE,font=11,font_size=10,20,weight=1.5,color=0.75,0.5,0:
Embed⁡img
Sample of each font 10.
img≔Create⁡35,320,channels=3,background=white:
Text⁡img,5,17,ABCD abcd 0123 $&?*,position=E,font=10,font_size=17,weight=1.2,color=0:
The font_size argument.
img≔Create⁡120,400,channels=3,background=white:
Text⁡img,10,100,font_size=20,position=E,font=11,font_size=20,weight=1.5,color=0:
Text⁡img,10,60,font_size=[14,20],position=E,font=11,font_size=14,20,weight=1.5,color=0:
Text⁡img,10,20,font_size=[28,20],position=E,font=11,font_size=28,20,weight=1.5,color=0:
The rotation argument.
img≔Create⁡400,400,channels=3,background=0.1,0.1,0.1:
forrfrom0by30to359doText⁡img,200,200,sprintf⁡--rotation=%3d\e718,r,position=E,font=11,font_size=15,weight=1.10,rotation=r,degrees=true,color=HSV,r360,1,1enddo:
Effect of the weight argument with different font sizes.
img≔Create⁡380,620,channels=3,background=white:
Text⁡img,10,360,font_size=12,position=E,font=11,font_size=12,weight=1.5,color=blue:
Text⁡img,10,336,font_size=20,position=E,font=11,font_size=20,weight=1.5,color=blue:
Text⁡img,12,290,weight=1.0,position=E,font=11,font_size=12,weight=1.0,color=0:
Text⁡img,12,210,weight=1.5,position=E,font=11,font_size=12,weight=1.5,color=0:
Text⁡img,12,130,weight=2.0,position=E,font=11,font_size=12,weight=2.0,color=0:
Text⁡img,12,50,weight=3.3,position=E,font=11,font_size=12,weight=3.3,color=0:
Text⁡img,10,260,weight=1.0,position=E,font=11,font_size=20,weight=1.0,color=0:
Text⁡img,10,180,weight=1.5,position=E,font=11,font_size=20,weight=1.5,color=0:
Text⁡img,10,100,weight=2.0,position=E,font=11,font_size=20,weight=2.0,color=0:
Text⁡img,10,20,weight=3.3,position=E,font=11,font_size=20,weight=3.3,color=0:
Text⁡img,255,350,font_size=40,position=E,font=11,font_size=30,40,weight=1.5,color=blue:
Text⁡img,255,280,weight=1.0,position=E,font=11,font_size=40,weight=1.0,color=0:
Text⁡img,255,200,weight=1.5,position=E,font=11,font_size=40,weight=1.10,color=0:
Text⁡img,255,120,weight=2.0,position=E,font=11,font_size=40,weight=2.0,color=0:
Text⁡img,255,40,weight=3.3,position=E,font=11,font_size=40,weight=3.3,color=0:
Using the stretch argument.
wL,hL,xOff,yOff≔240,60,50,30:
fntSz≔wL13:
wR,hR≔330,floor⁡fntSz⋅0.9:
img≔Create⁡4⁢hL+5⁢yOff,wL+wR+3⁢xOff,channels=3,background=0.5:
forcwin0,1doforchin0,1dor≔1−cw⋅2+1−ch;x≔xOff;y≔r⁢yOff+hL+yOff;SolidRectangle⁡img,x,y,x+wL,y+hL,color=0.75,0,0;Text⁡img,x+wL2,y+hL2,sprintf⁡stretch=[%03d,%03d],wL⁢cw,hL⁢ch,position=*,font=16,font_size=fntSz,color=1,stretch=wL⁢cw,hL⁢ch;x≔xOff⋅2+wL;y≔y+hL−hR2;SolidRectangle⁡img,x,y,x+wR,y+hR,color=0.75,0,0;Text⁡img,x+wR2,y+hR2,sprintf⁡stretch=[%03d,%03d],wR⁢cw,hR⁢ch,position=*,font=16,font_size=fntSz,color=1,stretch=wR⁢cw,hR⁢chenddoenddo:
Using the constrain argument.
r≔3:
forcwin0,1doforchin0,1dor≔1−cw⋅2+1−ch;x≔xOff;y≔r⁢yOff+hL+yOff;SolidRectangle⁡img,x,y,x+wL,y+hL,color=0.75,0,0;Text⁡img,x+wL2,y+hL2,sprintf⁡constrain=[%03d,%03d],wL⁢cw,hL⁢ch,position=*,font=16,font_size=fntSz,color=1,constrain=wL⁢cw,hL⁢ch;x≔xOff⋅2+wL;y≔y+hL−hR2;SolidRectangle⁡img,x,y,x+wR,y+hR,color=0.75,0,0;Text⁡img,x+wR2,y+hR2,sprintf⁡constrain=[%03d,%03d],wR⁢cw,hR⁢ch,position=*,font=16,font_size=fntSz,color=1,constrain=wR⁢cw,hR⁢chenddoenddo:
Manual kerning using b and t.
img≔Create⁡105,420,channels=3,background=white:
Text⁡img,10,75,ACTIVATION Typewriter,position=E,font=13,font_size=25,weight=1.2,color=0:
Text⁡img,10,25,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,position=E,font=13,font_size=25,weight=1.2,color=0:
Changing font mid-text using f.
img≔Create⁡55,600,channels=3,background=white:
Text⁡img,10,25,Embedded \f8italic\f11 and \f17script\f11 text,position=E,font=11,font_size=25,weight=1.2,color=0:
Generate the charts mapping Latin to Greek and Cyrillic characters.
w,h≔720,round⁡w⋅811:
rs,cs≔round⁡h13,round⁡w9:
fntSz≔h33.33:
forLin0,cy-map,4,gr-mapdoimg≔Create⁡h,w,3,background=white;forrfrom0to11doforcfrom0to7doch≔convert⁡r⋅8+c+32,bytes;Text⁡img,c+1⁢cs,h−r+1⁢rs,sprintf⁡%s=\f%02d%s,ch,L1,ch,position=*,font=13,font_size=fntSz,color=0enddoenddo;ifL2=cy-mapthenimgC≔imgelseimgG≔imgendifenddo:
Embed⁡imgC
Embed⁡imgG
A sample of some of the available non-ASCII glyphs.
img≔Create⁡200,450,channels=3,background=white:
Text⁡img,10,175,Math: \e1411 \e2268 \e2269 \e2265 \e2266 \e2270 ...,position=E,font=11,font_size=25,weight=1.2,color=0:
Text⁡img,10,125,Zodiac: \e2301 \e2302 \e2303 \e2304 \e2305 ...,position=E,font=11,font_size=25,weight=1.2,color=0:
Text⁡img,10,75,Music: \e2324 \e2325 \e2330 \e2381 \e2378 ...,position=E,font=11,font_size=25,weight=1.2,color=0:
Text⁡img,10,25,Weather: \e764 \e765 \e766 \e767 \e768 ...,position=E,font=11,font_size=25,weight=1.2,color=0:
Generate the charts of (1) Japanese characters and (2) all other glyphs.
glyphW≔67:
forchartinround⁡21.3⁢glyphW,jp,4000,4757,round⁡21.3⁢glyphW,sy1,1,2200,round⁡21.3⁢glyphW,sy2,2201,3926dow,file,lo,hi≔op⁡chart;h≔round⁡w⋅1.7;x,y≔glyphW4,10;img≔Create⁡h,w,3,background=white;dymax≔0;fornfromlotohidos≔sprintf⁡\e%d,n;dx,dy≔TextSize⁡img,s,font=14,font_size=12,weight=1.2;dx,dy≔dx−1,dy−1;ifdx,dy≠0.,0.thenText⁡img,x+5,h−y,sprintf⁡%d,n,position=SE,font=14,font_size=10,color=red,weight=1.2;Text⁡img,x+5,h−y−17,s,position=SE,font=14,font_size=12,color=0,weight=1.2;while−5<dxdox≔x+glyphW;dx≔dx−glyphWenddo;ifdymax<dythendymax≔dyendif;ifw−3⁢glyphW4≤xorn=hithenx≔glyphW4;y≔y+25+dymax;dymax≔0;ifh≤ythenbreakendifendifendifenddo;img≔img1..round⁡y+10,..,..;assign⁡cat⁡img_,chart2,imgenddo:
Embed⁡img_jp
Embed⁡img_sy1
Embed⁡img_sy2
ASCII to Cyrillic and Greek mapping.
img≔Create⁡105,640,channels=3,background=white:
Text⁡img,10,75,Vostok, Pilot = \f0Vostok, Pilot,position=E,font=11,font_size=25,weight=1.2,color=0:
Text⁡img,10,25,Archimedes = \f4Arximhdhw,position=E,font=11,font_size=25,weight=1.2,color=0:
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
Download Help Document