Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

GMImage.Annotate

Annotate image (draw text on image).

Component Version macOS Windows Linux Server iOS SDK
GraphicsMagick 2.0 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MBS( "GMImage.Annotate"; ImageRef; text { ; boundingArea; gravity; degrees } )   More

Parameters

Parameter Description Example Flags
ImageRef The image reference number. 1
text Some text "Hello World"
boundingArea The rectangle where to draw. Geometry is specified as a width and height "100x200". With an optional offset "100x200+10+20". For percent values, add a percent on the end, for % values add a %: "100x200%!" "100x200+10+20" Optional
gravity The position of the text.
Can be number of text value.
Can be ForgetGravity=0, NorthWestGravity=1, NorthGravity=2, NorthEastGravity=3, WestGravity=4, CenterGravity=5, EastGravity=6, SouthWestGravity=7, SouthGravity=8, SouthEastGravity=9, StaticGravity=10.		 "SouthWestGravity" Optional
degrees The rotation in degrees. 0 Optional

Result

Returns "OK" on success.

Description

Annotate image (draw text on image).
Annotates an image with text. Optionally you can include any of the following bits of information about the image by embedding the appropriate special characters:

%b file size in bytes. %c comment. %d directory in which the image resides. %e extension of the image file. %f original filename of the image. %h height of image. %i filename of the image. %k number of unique colors. %l image label. %m image file format. %n number of images in a image sequence. %o output image filename. %p page number of the image. %q image depth (8 or 16). %p page number of the image. %q image depth (8 or 16). %s image scene number. %t image filename without any extension. %u a unique temporary filename. %w image width. %x x resolution of the image. %y y resolution of the image.

Set a font with full path and @ in front. e.g. "@/Library/Fonts/Arial.ttf". This way the plugin loads it directly.

Gravity values:
NorthWestGravity1text bottom-left corner placed at top-left
NorthGravity2text bottom-center placed at top-center
NorthEastGravity3text bottom-right corner placed at top-right
WestGravity4text left-center placed at left-center
CenterGravity5text center placed at center
EastGravity6text right-center placed at right-center
SouthWestGravity7text top-left placed at bottom-left
SouthGravity8text top-center placed at bottom-center
SouthEastGravity9text top-right placed at bottom-right
StaticGravity10static

You can pass empty text for parameters or not pass parameters. This function can work in 5 modes:
  • Annotate with text using specified text, bounding area, placement gravity, and rotation.
  • Annotate using specified text, bounding area, and placement gravity
  • Annotate with text (bounding area is entire image) and placement gravity
  • Annotate using specified text, and placement location
  • Annotate with text (bounding area is entire image) and placement south
Depending on which parameters you specify or leave empty, we pick the best mode.

The function does wrap text. Please use Char(10) as line ending or Text.ReplaceNewline with mode 2 to prepare text.
Please use GMImage.FontTypeMetrics to measure how much space text needs.

With version 8.3 or newer you can pass font names without file path, as we now recognize most standard fonts. Only for special fonts you need full path.

Use GMImage.SetFontFamily, GMImage.SetFontPointsize, GMImage.SetFontStretch, GMImage.SetFontStyle and GMImage.SetFontWeight to define the font to use.

If the font is not found, GraphicsMagick may try postscript and that normally fails "Coder did not return an image" until you installed the command line tools for it. Otherwise it may also report, that the font is not found.

Examples

Write three lines at 200/200 into the picture:

MBS( "GMImage.Annotate"; $ImageRef; "Hello\nWorld\nAgain"; "200x200"; 0; 0 )

Setup and write Hello:

MBS("GMImage.SetLineWidth"; $img; 1)
MBS("GMImage.SetStrokeColor"; $img; "RGB 0 0 0")
MBS("GMImage.SetFont"; $img; "@/Library/Fonts/Arial.ttf")
MBS("GMImage.SetFontPointsize"; $img; 14)
MBS("GMImage.Annotate"; $img; "Hello World"; "+20+20")

For Windows use different font path:

MBS("GMImage.SetFont"; $img; "@c:\Windows\Fonts\Tahoma.ttf")
MBS("GMImage.Annotate"; $img; "Hello World"; "+20+20")

Load pictures, sets puts text on it in yellow and centered:

# load image from container
Set Variable [$ref; Wert:MBS("GMImage.NewFromContainer"; Annotate Image::InputImage)]
# set font and font size
Set Variable [$r; Wert:MBS("GMImage.SetFontPointsize"; $ref; Annotate Image::FontSize)]
Set Variable [$r; Wert:MBS("GMImage.SetFont"; $ref; Annotate Image::FontPath)]
# set color to yellow
Set Variable [$r; Wert:MBS("GMImage.SetFillColor"; $ref; "RGB 1 1 0")]
# draw in rectangle with width and height of image (here 640 by 480) centered.
Set Variable [$r; Wert:MBS("GMImage.Annotate"; $ref; Annotate Image::Text; "640x480"; "CenterGravity")]
# save image
Set Field [Annotate Image::OutputImage; MBS( "GMImage.WriteToPNGContainer"; $ref )]
# and free memory
Set Variable [$Error; Wert:MBS("GMImage.Release";$ref)]

Text and gravity only:

MBS("GMImage.Annotate"; $ref; Annotate Image::Text; ""; "SouthWestGravity")

Write text with Arial Black:

Set Variable [ $ref ; Value: MBS("GMImage.NewFromContainer"; Annotate Image::InputImage) ]
Set Variable [ $r ; Value: MBS("GMImage.SetFontPointsize"; $ref; 72) ]
Set Variable [ $r ; Value: MBS("GMImage.SetFont"; $ref; "Arial Black") ]
Set Variable [ $r ; Value: MBS("GMImage.SetFillColor"; $ref; "RGB 0 0 0") ]
Set Variable [ $r ; Value: MBS("GMImage.Annotate"; $ref; "Hello World"; "100x200+10+80"; 1) ]
Set Field [ Annotate Image::OutputImage ; MBS( "GMImage.WriteToPNGContainer"; $ref ) ]
Set Variable [ $Error ; Value: MBS("GMImage.Release";$ref) ]

Write Japanese text with unicode font and UTF-8 encoding:

# This script loade the original picture to an image environment set the settings for the font and write a text on a picture. Then we save the image in a container.
#
Set Variable [ $ref ; Value: MBS("GMImage.NewFromContainer"; Annotate Image::InputImage) ]
# Settings for the font
Set Variable [ $r ; Value: MBS("GMImage.SetTextEncoding"; $ref; "UTF-8") ]
Set Variable [ $r ; Value: MBS("GMImage.SetFontPointsize"; $ref; 40) ]
Set Variable [ $r ; Value: MBS("GMImage.SetFont"; $ref; "ArialUnicodeMS") ]
Set Variable [ $r ; Value: MBS("GMImage.SetFillColor"; $ref; "RGB 0 0 0") ]
# Write the text to the picture
Set Variable [ $r ; Value: MBS("GMImage.Annotate"; $ref; "Hello こんにちは世界"; "100x200+10+40"; 1) ]
Set Field [ Annotate Image::OutputImage ; MBS( "GMImage.WriteToPNGContainer"; $ref ) ]
# Free image
Set Variable [ $Error ; Value: MBS("GMImage.Free";$ref) ]

Annotate an image on an Ubuntu FileMaker Server:

Go to Layout [ “Annotate Test” ; Animation: None ]
Go to Record/Request/Page [ First ]

Set Variable [ $ref ; Value: MBS( "GMImage.New"; "200x200"; "white" ) ]
# Settings for the font
Set Variable [ $r ; Value: MBS("GMImage.SetFontPointsize"; $ref; 12) ]
Set Variable [ $r ; Value: MBS("GMImage.SetFont"; $ref; "@/usr/share/fonts/truetype/ubuntu/Ubuntu-R.ttf") ]
Set Variable [ $r ; Value: MBS("GMImage.SetFillColor"; $ref; "RGB 0 0 0") ]
# Write the text to the picture
Set Variable [ $r ; Value: MBS("GMImage.Annotate"; $ref; "Hello World"; "100x200+10+40"; 1) ]
# store the picture in the field
Set Field [ WebHook Chat::File ; MBS( "GMImage.WriteToPNGContainer"; $ref ) ]
Commit Records/Requests [ With dialog: Off ]
# Free image
Set Variable [ $Error ; Value: MBS("GMImage.Free";$ref) ]

See also

Release notes

  • Version 12.1
  • Version 8.4
    • Fixed font mapping in GraphicsMagick for Mac and Windows, so SVG convert better and GMImage.Annotate can take font name instead of full path.
  • Version 7.4
    • Improved GMImage.Annotate to work in 5 different modes depending on what parameters you pass.

Example Databases

Blog Entries

This function checks for a license.

Created 18th August 2014, last changed 31st October 2023


GMImage.Affine - GMImage.AutoOrient