imc v4.1 Reference Manual

Index

General syntax
Special types

`ANGLES`	`ARC`	`BACKGROUND`	`CIRCLE`	`ELLIPSE`
`FILL`	`FILLCOLOR`	`IMAGE`	`IMAGEALIGN`	`IMAGEMIRROR`
`IMAGEROTATE`	`INTERLACED`	`LINE`	`LINECOLOR`	`LINETO`
`LINEWIDTH`	`MOVETO`	`ORIGIN`	`RECTANGLE`	`SIZE`
`TEXT`	`TEXTALIGN`	`TEXTAT`	`TEXTCOLOR`	`TEXTMIRROR`
`TEXTROTATE`	`TEXTSIZE`

General syntax rules

Releases with the same major version number have a backward compatible syntax.
The input files consists of a number of input lines. The backslash, followed by a newline, can be used as line continuation character.
Leading and trailing whitespace on an input line is ignored.
Comments: Two types of comments are allowed:
- Shell-style comment: starts with # (which must be the first non-whitespace character on the line) and ends at the input line end
- C-style comment: starts with /* and ends with */
Comments are ignored by imc.
Lines consist generally of commands (a keyword followed by some arguments). Excess arguments produce an error. The keywords are case insensitive; the arguments are also case insensitive, unless otherwise specified.
A command can have, next to its fixed parameters, optional parameters, e.g. the color of a line to be drawn. These optional parameters always start with a keyword, in the given example this would be "COLOR", and should be regarded as sub-commands. The order in which the sub-commands are given is not important, as the keyword of the sub-command identifies it completely; the mandatory parameters however should be provided in the correct order.
A semi-colon can be used to separate commands in a line. It can also be used to terminate a line, but that is not necessary.
When the program is configured to use a C pre-processor, the input file (or standard input) is fed through the pre-processor first, before imc processes it.
A pair of curly braces { and } can delimit arithmetic expressions. These expressions are fed to the Perl evaluator and replaced by the result. This happens after the pre-processing stage (if there is one), but before the actual processing of the imc commands. Between the braces only numbers, brackets and the characters +, -, / and * are allowed. The result is automatically rounded to the nearest integer.

Special types

(Note that some tools, notably xv, don't take transparency into account, so that images may seem wrong on these tools; also, some versions of Netscape don't render PNG images with transparency correctly; however, GQview shows PNG images as they should be...).

The model is the color model used; the following color models are supported at the moment:

RGB

the args should be three integers between 0 and 255 (bounds included) and specify the red, green and blue component of the color.

X11

the args should be 1 argument, which can be a color name or a numeric specification in the form:

#RGB
#RRGGBB
#RRRGGGBBB
#RRRRGGGGBBBB

as specified in the X11 protocol (see there).

The color name (case insensitive, but bounded by quotes if there are spaces included) is looked up in the rgb.txt file to map it to an RGB color. The rgb.txt file is looked for in the following directories:

current directory
directory of the input file
/etc/X11
/usr/lib/X11

Note:

In all the commands the substring COLOR can be replaced by COLOUR.

Commands

`ORIGIN`

    ORIGIN spec

Sets the orientation of the vertical axis. The spec can be:

TOP: sets the origin to the top left (and thus the vertical axis oriented downwards). This is the default value.
BOTTOM: sets the origin to the bottom left (vertical axis oriented upwards).

This command must be specified before any commands that use coordinates.

Example:

    ORIGIN bottom

`ANGLES`

    ANGLES spec

Sets the orientation of angles. The spec can be:

CLOCKWISE (this is the default value)
ANTICLOCKWISE (or its synonym COUNTERCLOCKWISE)

Example:

    ANGLES counterclockwise

`SIZE`

    SIZE width height

Fixes the size of the image to width, height. If this command is not specified in the input file, the image is just big enough to contain all drawed items.

Example:

    SIZE 200 300

`MOVETO`

    MOVETO x y

Moves the current position to the point with coordinates (x, y). Initially, the current position is at (0, 0).

Example:

    MOVETO 10 100

`LINETO`

    LINETO x y [COLOR colorspec] [WIDTH width]

Draws a line from the current position to the point with coordinates (x, y). Makes the end point the new current position. The color and width may be specified in the command; if not specified, the current values are used (see LINECOLOR and LINEWIDTH).

Example:

    LINETO 20 100 COLOR RGB 100 100 100

`LINE`

    LINE x1 y1 x2 y2 [COLOR colorspec] [WIDTH width]

As LINETO, but draws a line from the coordinates (x1, y1) to (x2, y2). The current position is not changed.

`TEXT`

    TEXT string [COLOR colorspec] [SIZE size]
                [ALIGN [valign] [halign]] [ROTATE angle]
		[MIRROR]

Prints the given text (case sensitive, of course) on the current position. The relative position of the current position to the text depends on the current alignment. The current position is not changed.

If the text contains whitespace, it has to be completely enclosed in quotes.

The text color, size, alignment and rotation, and whether it should be mirrored, can be specified on the command; if omitted, the current values are used (see TEXTCOLOR, TEXTSIZE, TEXTALIGN, TEXTROTATE and TEXTMIRROR).

Note that the alignment is always relative to the bounding rectangle (with horizontal and vertical edges) of the text, also when it is rotated. Mirroring is always horizontal and is done before rotating.

Example:

    TEXT "This is a test" SIZE large ALIGN top center

`TEXTAT`

    TEXTAT x y string [COLOR colorspec] [SIZE size]
                      [ALIGN [valign] [halign]] [ROTATE angle]
		      [MIRROR]

As TEXT, but prints the text at the coordinates (x, y). The current position is not changed.

`CIRCLE`

    CIRCLE x y radius [FILLED [colorspec]] [COLOR colorspec]
                      [WIDTH width]

Draws a circle with the given radius around the point with coordinates (x, y). The current position is not changed.

If the FILLED specification is given, the circle is filled with the given color. If the color is omitted, the current fill color is used (see FILLCOLOR).

The drawing color and width can be specified on the command; if omitted, the current values are used (see LINECOLOR and LINEWIDTH).

Example:

    CIRCLE 100 100 50 FILLED RGB 0 0 20

`ELLIPSE`

    ELLIPSE x y h_radius v_radius
            [FILLED [colorspec]] [COLOR colorspec]
            [WIDTH width]

Draws an ellipse with the given horizontal and vertical radius around the point with coordinates (x, y). The current position is not changed.

If the FILLED specification is given, the ellipse is filled with the given color. If the color is omitted, the current fill color is used (see FILLCOLOR).

The drawing color and width can be specified on the command; if omitted, the current values are used (see LINECOLOR and LINEWIDTH).

Example:

    ELLIPSE 100 100 50 100 FILLED

`ARC`

    ARC x y h_radius v_radius start_angle end_angle
        [COLOR colorspec] [WIDTH width] [CLOSED [PIE|SEGMENT]]
	[FILLED [colorspec]]

Draws an arc with the given horizontal and vertical radius around the point with coordinates (x, y) over an angle starting from start_angle to end_angle. The current position is not changed.

The drawing color and width can be specified on the command; if omitted, the current values are used (see LINECOLOR and LINEWIDTH).

When CLOSED or CLOSED PIE is specified, lines are drawn from the end points of the arc to the center of the arc, which can be interesting for pie charts. When CLOSED SEGMENT is specified, a line is drawn between the two end points of the arc. When the arc is closed, the keyword FILLED will cause the closed arc to be filled with the given color. If the color is omitted, the current fill color is used (see FILLCOLOR).

Example:

    ARC 100 100 50 100 -20 40

`RECTANGLE`

    RECTANGLE x1 y1 x2 y2 [FILLED [colorspec]]
              [COLOR colorspec] [WIDTH width]

Draws a rectangle between the points with coordinates (x1, y1) and (x2, y2). The current position is not changed.

If the FILLED specification is given, the rectangle is filled with the given color. If the color is omitted, the current fill color is used (see FILLCOLOR).

The drawing color and width can be specified on the command; if omitted, the current values are used (see LINECOLOR and LINEWIDTH).

Example:

    RECTANGLE 100 100 200 200 FILLED X11 Blue

`IMAGE`

    IMAGE x y [filename] [SIZE width height]
          [ALIGN [valign] [halign]] [ROTATE angle]
	  [MIRROR]

Imports the PNG, JPG, X Bitmap or X Pixmap image stored in the given file (case sensitive) on the position given by the coordinates (x, y). The relative position of the current position to the image depends on the current alignment. The current position is not changed.

When the filename is omitted, the previously used filename is used (if, of course, there was one; if not, an error message is generated). This allows to use the same image again and again without having to load it every time.

A size can be specified to scale the image to the given size. An integer bigger than 0 specifies an absolute size, a floating point percentage bigger than 0 (ending with %) specifies a relative size.

The alignment, rotation angle and whether the image has to be mirrored can be specified on the command; if omitted, the current values are used (see IMAGEALIGN, IMAGEROTATE and IMAGEMIRROR).

Note that the alignment is always relative to the bounding rectangle (with horizontal and vertical edges) of the resulting image, also when it is rotated. Mirroring is always horizontal and is done before rotating, but after resizing.

Example:

    IMAGE 10 10 oldfile.png ALIGN middle center MIRROR

`FILL`

    FILL x y [BORDER colorspec] [COLOR colorspec]

Flood-fills a region that contains the point with coordinates (x, y). If the BORDER color is given, filling stops when it hits the color specified by the border color; else filling stops when it hits a point of a different color than the starting point.

If the COLOR specification is given, the region is filled with the given color. If the color is omitted, the current fill color is used (see FILLCOLOR).

Example: