Attributes that are supported as text style definitions for imageapi_text

font-size
eg: font-size: 14px;
Must be in pixels and include units. [default 12px] (SVG CSS2)
fill
eg: fill: #DD3333;
The hex color of the body of the text [default #333333] (SVG) (equiv to CSS:color) See color
fill-opacity
eg: fill-opacity: 0.7;
A decimal between 0.0 and 1.0 [default 1, but modified by "opacity" value and color alpha]
line-height
eg: line-height: 20px;
Must be in pixels and include units. [default auto].
padding-top*
eg: padding-top: 10px;
Transparent spacing at the top. [default 0]
padding-bottom*
eg: padding-bottom: 10px;
Transparent spacing at the bottom. [default 0]
padding-left*
eg: padding-left: 10px;
Transparent spacing at the left. [default 0]
padding-right*
eg: padding-right: 10px;
Transparent spacing at the right. [default 0]
top*
eg: top: 10px;
Offset from the top. [default centered]
bottom*
eg: bottom: 10px;
Offset from the bottom. [default centered]
left*
eg: right: 10px;
Offset from the left. [default centered]
right*
eg: right: 10px;
Offset from the right. [default centered]
stroke
eg: stroke: #00FF00;
The color of the outline. [default none] (SVG) See color
stroke-width
eg: stroke-width: 2px;
Width in pixels of the stroke. Note that this actually behaves as an outside border, not a true outline stroke line. Results may not be nice if larger than a few pixels. [default none] (SVG) See also CSS3 text-outline
stroke-opacity
eg: stroke-opacity: 0.7;
A decimal between 0.0 and 1.0 [default 1, but modified by "opacity" value and color alpha]
text-shadow
text-shadow: color xpos vpos blur;
eg: text-shadow: #666666 3px 2px 3px;
will place a dropshadow 3px right and 2px down from the text. [default none] (blur not yet supported) (CSS2). (Offsets of 0 should be able to produce a "glow" effect if blur worked.) Note that shadow only applies to the text, not the stroke - yet.
text-shadow-opacity
eg: text-shadow-opacity: 0.7;
A decimal between 0.0 and 1.0 . no official spec! [default 1, but modified by "opacity" value and color alpha] See color
opacity
eg: opacity: 0.7;
A decimal between 0.0 and 1.0 [default 1] (SVG) (fill-opacity, stoke-opacity maybe later)
Elements can modify their own opacity with specific *-opacity attributes as well as the alpha channel of the color. This overall opacity setting multiplies over any other opacities. See opacity notes
transform
eg: transform: rotate(30);
- Almost unknown (proposal?), but I THINK this is how it's supposed to work? Units assumed to be degrees, positive values are clockwise.
text-transform
eg: text-transform: uppercase;
Note this is the CSS spec [capitalize, uppercase, lowercase]. For small-caps you need "font-variant" (unsupported)
text-effect
No specification. This is a highly experimental hook to support custom contributed effects, such as 3d, perspective, gradient or other things.
eg: text-effect: embedded-underline;
Text-effects can be placed in the imageapi_text/contrib folder.
text wrapping
See white-space
background-color
eg: background-color: #DDEEEE;
The hex color of the background [default transparent]
For best results, use with a defined height and width, as the background will be placed only against the bounding box or the text.
Background opacity can be defined in the alpha channel of the color.
width
eg: width: 200px;
Normally the text will be returned with its own bounding box, but you can define the dimensions of the result manually also. Doing so may truncate the result.
Width is required if you want text-wrapping (white-space:normal) or text-align.
When used in context of other image processes, percent values may be used to define width and height.
height
eg: height: 20px;
Normally the text will be returned with its own bounding box, but you can define the dimensions of the result manually also.
white-space
eg: white-space: normal;
"Normal" means apply word-wrap, although the default is no-wrap.
Supported values: [pre, normal] The default is pre - because that's the gd toolkit behavior. pre means that hard newlines in the input text will be respected, but long lines may go off the right side. Word-wrap can only apply if the target image has some width set, either width=300px or width=100% (if rendering in context of another image). If no width is set, the returned image will be as wide as it feels it needs to be.
width=100% will not mean anything compared to the HTML context it is put in, only when blending imageapi_text with other imageapi images.
If white-space is set to 'normal' andem> there is a width set, then the string will be tokenized into 'words' and the test will wrap to the next line.
Newlines in the input will also be maintained, whatever the whitespace settings.
text-align
eg: text-align: center;
Supported values: [left, center, right] Default: left.
text-align is only effective when width is also set. If the text image has no set width, then a compact bounding box (plus padding) is produced and no text alignment happens.

*Padding When using padding, extra transparent space will be given to the image, so later positioning and alignment will be done relative to that. In stand-alone image generation, this is different to positioning, as positioning is expected to happen relative to a larger context that is not available to the text-image-generation process.
padding:a, b, c, d; all-in-one syntax is not supported.

*Positioning is done relative to the entire bounding box that will fit the text, as this most often gives the expected alignment effect in simple cases. It has no effect in simple text-only generation, which generates an image with a tight bounding box + padding. It may work when being used as part of a process to overlay text on a larger background image. Illustration But this can be inconsistent with decorative text, rotation or text descenders if trying to put the text in an exact position.

*Relative Positioning Additional keywords may be supported if the text is being placed in context of a larger image.

top:bottom-80px;
left:center+10%;
        
is a valid value.
{textblock_side}:{keyword}[+,-]{value}{unit}
        where:
        {textblock_side} = [top, bottom, left, right]
        {keyword} = [top, bottom, left, right, middle, center]
        {value} = numeric
        {unit} = ['px', '%']
        

center:center;
        
- (or nothing) will leave the text right in the middle of the available space.
top:center;
        
- will start the text from the centerline.
top:center-100;
        
- will start the text from above the centerline.

*Color #RRGGBBAA (color with alpha channel) is supported in most places color can be set. eg: background-color: #BBCCEE44
Alpha transparency range is from 0 (opaque) to 7F (transparent) only, it is not 00-FF. Remember that transparency and opacity are opposites, high alpha == low opacity.
This 4-part hex code appears to be non-standard notation, but imageapi supports it.

*Opacity Color-alpha is combined with any other opacity settings, producing a more transparent result. eg: background-color: #BBCCEE40; fill-opacity:0.7; opacity:0.7
= (0.5 * 0.7 * 0.7) ~= 0.25

font-family, font-weight, font-style, text-decoration, not supported. These are properties of the font file chosen. We must use full font file path instead.

Operations

Processing happens basically in the order:

  1. Word wrapping, lines are calculated according to white-space rules, font-size, and available width.
  2. Draw text, with effects
  3. Text is aligned within given space
  4. Rotate, based on minimum bounding box
  5. Add padding to the new bounding box
  6. Underlay background