webCOMAND

#IMAGE Annotate

Place text on an image.

Only supported by ImageMagick image processing engine.

Prototype

#IMAGE($image_bytes, 'Annotate', $font, $point_size, $stroke_color, $fill_color, $x, $y, $align, $text, ...)

Required Parameters

  • font - Arial, Courier, Generic, Tahoma, Times, Verdana.  Custom True Type fonts may be installed to the webCOMAND fonts folder and referenced by filename.  If no filename extension is specified, ".ttf" is assumed.  Font filenames are not case-sensitive and the installed filename should be all lower-case.  Text styles, such as bold or italic are possible through the use of specifically styled fonts.
  • point_size - Point size of the font in pixels.
  • stroke_color - Color used to outline each character (may be "none").
  • fill_color - Color used to fill each character (may be "none").
  • x - Horizontal offset in pixels from the left edge to start text.
  • y - Vertical offset in pixels from the top edge to start text.
  • align - Left, Center, Right.  An empty string will use Gravity to determine alignment.  If Align nor Gravity is specified, Left will be used.
  • text - String of text characters, which may include newline characters, represented as "\n".  Backslashes are represented with "\\".

Optional Parameters

  • Wrap Width - Number of pixels to extend text before wrapping.  Wrapping will occur at spaces and hyphens when words are shorter than wrap width.  When words are longer than the wrap width, they will be broken into two lines.  An empty string (default) represents no wrap width.  Point Size must be defined in order to wrap text.
  • Fit Width - Increase or decrease the point size in order to fit the longest line of text within the specified width in pixels.  It may be used in conjunction with Wrap Width to first wrap the text to a certain width with a certain Point Size, the scale up the text to fit another width.  If Wrap Width is not specified, but Point Size is, the font size will be reduced to fit within the Fit Width, but will not be increased.  This is useful for producing text that must shrink to fit within a button or region if it is too large, but should use the specified font size otherwise for a consistent size relative to other buttons or regions.  An empty string (default) disables this functionality.
  • Stroke Width - Number of pixels (default is 1) for the outline around each text character.
  • Under Color - Color of background behind the text.  An empty string is used to specify no color (transparent).
  • Line Height - Number of pixels to advance for each line of text, expressed as a decimal multiplied by the height of the font Point Size.  For example, a a Point Size of 12 and Line Height of 1.5 would advance 18 pixels down per line of text.  The default Line Height is dependent on the specified font.  Some fonts do not provide a default line height and therefore may require a Line Height to display text with newlines properly.
  • Kerning - Decimal number of pixels to display between each character.  A negative value can be used to reduce the spacing or overlap characters.  If no value is specified, the default font kerning will be used.  Note, Kerning only works with ImageMagick version 6.4.7-8 or higher.  Check the version with #IMAGE GetVersion.
  • Gravity - If no alignment is provided, these values will position the text relative to the "canvas".  Possible values are: NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast.
  • Rotate - Number of degrees to rotate the text, as a decimal number.
  • Encoding - Can be used to enable character encoding.  Only one value is valid: "UTF-8".

Example

#/ write "Hello World" in grey 12 point Arial font at 40, 40, left-aligned
#NEW($Thumbnail)#IMAGE($Image, Annotate, arial, 12, 'none', '#ccc', 40, 40, 'Left', 'Hello World')#ENDNEW