zimg [OPTIONS ...] [FILE ...]

[-r, --size=width,height]

specifies the width and height of the 2-D data. If height is not given it is set equal to width. The separator 'x' (instead of ',') can be used also for backwards compatibility.

Mark comment blocks. This option is used when reading unformatted ascii data. Each line will be truncated at pattern. This options might be used repeatedly to specify more than one comment pattern. This option was not really tested and might be still buggy. For the future it is planned to include also regular expressions.

read column number (ascii input). Multiple columns can be selected by using this option repeatedly. Currently this is limited to the 32 first columns. If number is omitted, the data of all columns will be used.

skip this amount of lines when reading ascii data. Skip bytes., if reading binary data. Note that the unit is bytes, irrespective of the input type (short ..). If the optional size argument is missing, the option is reset to its default. This default behavior is as follows: for binary data, all available data is read from the input stream and the header size (which will be skipped) is then calculated as the difference between the size of input data and the size of the image as specified by the -r switch. Or in short: the last widthxheight items of the input stream will be taken. If you don't like this feature you can disable it explicitly by using the switch [--skip=0]. For ascii data no skipping will be done by default.

apply switches, if the input filename matches regexp. Especially useful if used in a .zimgrc file. The separator character can be any character which is not present in regexp, for example [--options=#/usr/local#switches]. See also the [--input-filter] switch. [--options] is only available if your system provides the POSIX regular expression functions regcomp / regexec (check zimg [-V] for availability).

files thru filter. If filter contains a %s, it is substituted with the file name, else the filename is appended to the filter. This switch is especially useful if used in a .zimgrc file. Example: --options='/\.int$/--input-filter=int < %s'. See also the [--options] switch. [--input-filter] is only %available if your system supports the popen() call (check zimg % [-V] for availability).

normally zimg writes to stdout. You don't ever need this option, if you redirect stdout to you destination file or pipe. If more than one input file is given, path should be an existing directory where the output files should be stored. In this case the output names are constructed from path, the input file name and a suffix ".gif" or ".png" / ".jpg" depending on the gd version which was used at compile time (and eventually the [-j] switch)

binary input data is big-endian. This option overwrites [--swap] and can be overwritten by [--swap] and [--little-endian]. This switch does nothing if the machine where zimg runs is also big-endian, otherwise the words get swapped.

binary input data is little-endian. This option is the opposite of big-endian, overwrites [--swap] and can be overwritten by [--swap] and [--big-endian]. This switch does nothing if the machine where zimg runs is also little-endian, otherwise the words get swapped.

swap bytes when reading binary input. This might be necessary when using binary files from different platforms. If zimg runs on a little-endian machine (e.g. Intel) [--swap] assumes the binary input data created by a big-endian machine and vice versa. All three switches [--swap], [--big-endian] and [--little-endian] overwrite each other and therefore it is recommended to use only one of these switches.

read binary float (normally 4 bytes) data.

read binary double (normally 8 bytes) data.

read signed char (1 byte) data.

read signed short (2 bytes) data.

read signed integer (4 bytes) data.

read signed long integer (8 bytes) data.

read unsigned char (1 byte) data.

read unsigned short (2 bytes) data.

read unsigned integer (4 bytes) data.

read unsigned long integer (8 bytes) data.

input data is binary complex float. (ascii parsing of complex numbers is not implemented yet. The value of the switch determines how to display the complex numbers. The default is abs or the alias length (the length of the complex number).

Like [--complex-float], but for complex double binary input data.

use a red scale color map.

use a blue scale color map.

use a grey scale color map.

use custom colormap from the file path. The file must hold r g b triplets with values ranging from 0 to 0xff (255). There must be exactly one triplet per line, where empty lines and lines beginning with a hash `#' mark are skipped. The maximum number of columns is defined in zimg.h and currently 240 (16 colors are reserved for "LINE COLORS"). The colormap file is searched in the current directory, then in ~/.zimg/cmap, then in /usr/local/share/zimg/cmap. If the optional argument number is omitted, the colormap is reset to the default.

create a colormap using predefined colormap formulae. red, green and blue must be integers between -36 and 36. If blue and/or green are missing, they're set to green or red respectively (so a gray colormap value can be created by specifying red only). The numbers select one of the predefined formulae which are used to map the z value to a color intensity. Negative numbers invert the color intensity. Currently the following formulae are defined where x ranges from [0, 1]: If the optional argument number is omitted, the colormap is reset to the default.

 0    x = 0
 1    x = 0.5
 2    x = 1
 3    x = x    (identity)
 4    x = x * x
 5    x = x * x * x
 6    x = x * x * x * x
 7    x = sqrt(x)
 8    x = sqrt(sqrt(x))
 9    x = sin(90 * x)
10    x = cos(90 * x)
11    x = fabs(x - 0.5); 
12    x = (2 * x - 1) * (2 * x - 1); 
13    x = sin(180 * x); 
14    x = fabs(cos(180 * x)); 
15    x = sin(360 * x); 
16    x = cos(360 * x); 
17    x = fabs(sin(360 * x)); 
18    x = fabs(cos(360 * x)); 
19    x = fabs(sin(720 * x)); 
20    x = fabs(cos(720 * x)); 
21    x = 3 * x; 
22    x = 3 * x - 1; 
23    x = 3 * x - 2; 
24    x = fabs(3 * x - 1); 
25    x = fabs(3 * x - 2); 
26    x = (1.5 * x - 0.5); 
27    x = (1.5 * x - 1.0); 
28    x = fabs(1.5 * x - 0.5); 
29    x = fabs(1.5 * x - 1.0); 
30
         if (x <= 0.25)
             return 0;
         if (x >= 0.57)
             return 1;
         x = x / 0.32 - 0.78125; 
31
         if (x <= 0.42)
             return 0;
         if (x >= 0.92)
             return 1;
         x = 2 * x - 0.84; 
32
         if (x <= 0.42)
             x *= 4;
         else
             x = (x <= 0.92) ? -2 * x + 1.84 : x / 0.08 - 11.5;
33
         x = fabs(2 * x - 0.5); 
34
         x = 2 * x;
35
         x = 2 * x - 0.5;
36
         x = 2 * x - 1;

draw a labelled colorbox right to the image. If the number of labels n isn't given, it is calculated automatically according to the image and font heights. Labelling can be turned off by specifying [--colorbox=0].

format is a c sprintf format string for floats, e.g. %3.6g (see the sprintf(3) manual), which is used for formatting the colorbox legend. Turns on [--cbox] implicitely.

Print string next to the colorbox (e.g. a unit for the colorbox numbers). Turns on [--cbox] implicitely. string can be a multiline string, see for example the [--label] switch.

dump a colormap to stdout as it can be read back with the [-m] switch. This can be useful for manually editing and reading back the colormap. The [--dump-colormap] switch disables most of the other switches -- no processing of data files is done. The only exception is if the source files are png files: in this case not the (specified) colormap of zimg, but the color entries of the source png are dumped.

invert the selected color map.

do an exclusive or with the specified color (defaults to white). For the gray scale color map this equivalent to the [--invert] switch.

apply a discrete differentiation (1'st derivative) to the data. This is a position dependent switch.

display the curvature (2'nd derivative) of the data. This is a position dependent switch

wipe out hot spots. The average and sigma of the nearest neighbors of each pixel are calculated. If the pixel's value is greater than (`threshold' * sigma + average), it will be set to the average of the neighbors. This is a position dependent switch.

use a logarithmic color scale where scale must be strictly positive. The data is scaled to the range 0 - scale, then the log1p () is taken. The default for scale is 1. The best way to understand this is to compare the results for different scale values. This is a position dependent switch.

take the absolute value of the input data. The long option [--fabs] was named after the c function fabs(), because the [--absolute] switch is used for absolute scaling (see below). This is a position dependent switch.

set everything below min to min and every thing above max to max. The partial notations [--abs=min,] and [--abs=,max] can be used. If both min and max are given, a - (dash) can be used as separator instead of the comma. This is a position dependent switch.

same as above, but min and max are to be given relative (in percent) to the data's min and max. This is a position dependent switch.

set data points which are equal to val to the color color (default: black). If val isn't specified, it is guessed from the border of the data.

filter data through the c-style string expression string. This feature is compile-time dependent and only available, if zimg [-V] shows the string dynaload. The expression string string will be compiled on the fly. The expression is wrapped in a function which will be called for each data value z (double) with the current x (unsigned int), width (unsigned int) and y (unsigned int), height (unsigned int) values supplied. Example:

# zimg -e "cos(z) - (width - x)" ...

Use file.c as input file name for compiling the expression. If the switch [--expr] is not given, [--expr-source] should point to an existing file which holds the c source for the expression function. If the switch [--expr] is given, it will be wrapped in a c function and stored in the [file.c] given by [--expr-source]. If [--expr-source] is not given, the expression given by [--expr] will be stored in a temporary c-file which will be deleted after the expression evaluation. The switch [--expr-source] can be used for reusing the expression source:

# zimg -e "cos(z) - (width - x)" -R myfunc.c
# zimg -R myfunc.c ... file.dat

Use file.so as output file name for compiling the expression. If none of the switches [--expr] and [--expr-source] is given, file.so should exist and be a valid object file which was probably compiled before by zimg. Shared objects are searched in the current directory, then in the directory ~/.zimg/expr, then in /usr/local/lib/zimg/expr and then in the search path of your dynamic loader (refer to the manual pages of dlopen() or shl_load(), depending on the implementation). If [--expr-object] is not given, the expression given by [--expr] or [--expr-source] will be compiled to a temporary shared object file which will be deleted after the expression evaluation.

If at least one of the switches [--expr] or [--expr-source] are given, the expression will be compiled to file.so. This can be used for compiling a shared object file for later use:

# zimg -e "cos(z) - (width - x)" -O myfunc.so
# zimg -O myfunc.so ... file.dat

For complicated expressions it might be useful to create the c-source for the expression with an editor and compile it 'by hand'. Please refer to the manual page of your c-compiler for how to create shared object files (for gcc it is the switch -shared). The shared object must export a function zimg_expression with the zimg_expression_t as given in zimg.h. Example

#include <zimg.h>

float
zimg_expression(unsigned int x, unsigned int y,
    float z, const zimg_expression_info_t* info)
{
    unsigned int height = info->height;
    return z - (float)x * (float)(height - y);
}

Scaling of the image. If only one numer is given, it is use for both directions. Any non-numeric character may be used as separator. The factors should be greater 1. SCALING IS STILL EXPERIMENTAL.

crop the raw data to the specified size. Note that the numbers given apply to the raw data, not to the eventually enlarged or binned image. If the optional argument is omitted, the data is cropped automatically: all data with the same value as the border is cropped.

align to an integer multiple of the specified pixels. If vertical is omitted, it it set to horizontal. Example: -A16 will pad the resulting image so that it's (both) dimensions are multiples of 16. This is useful, if the images are used to create an mpeg sequence for example (otherwise mpeg_encode will cut the images down so that the dimensions are multiples of 16). The data is centered within the resulting image. The optional argument bordercolor must be given as 6-digit hexadecimal number, where the first digits are the red value, the second two digits the green value and the last two digits the blue value (so the color values for each color are between 0 and ff). Note that zimg will try to choose a color out of the existing color map which comes close to what you've specified, but depending on the color map you might not get exactly what you've requested. See also the [--textcolor] switch. If the bordercolor is not given, the image border color is chosen to be the most frequent color of the original data's border.

draw contour lines. This option is still experimental. Optional arguments are probably subject to future changes. The optional argument `log' distributes the contour levels logarithmically over the image. The optional argument bg=color forces contour-only drawing i.e. colors the background with the specified color. This color must be give as 3 or 6 digit hex value or the special keyword 'black'. fg=color uses the specified color as contour line color. bg and fg and should not used together. The contour algorithm is pretty fast and does not spline when enlarging the image.

write an interlaced image. [--interlace] is off by default. If you write a jpeg image using the [--jpeg] switch, the [--interlace] switch will be interpreted to write a progressive JPEG.

write a jpeg instead of a png image. [quality] must be an integer number between (inclusive) 0 and 100. If [quality] is omitted, an appropriate default quality is used. Jpeg is only available, if zimg was compiled with libgd >= 1.8. If you have set image interlacing using the [--interlace] switch, this switch is interpreted to write a progressive JPEG. Some programs (e.g., Web browsers) can display progressive JPEGs incrementally; this can be useful when browsing over a relatively slow communications link, for example. Progressive JPEGs can also be slightly smaller than sequential (non-progressive) JPEGs.

print string at the specified position of the FINAL image. 'Final' means the image size with all padding and scaling applied. The string can be a multiline string separated by '\n', e.g. "this\nis\nmultiline\ntext". x and y can be negative coordinates, in which case they're interpreted as offsets of the right and bottom text bounding box from the right and bottom border of the image respectively. If you specify for example [--label=-1-1,string], the string is entirely visible, having the lower right border of it's bounding box in the bottom right corner on the image. Long multiline strings should preferably be passed by specifying this option several times (e.g. for each line separately) because of limitations of the option parser. See also STRING ESCAPES.

same as the [--label] option, but prints the string vertically. See also STRING ESCAPES.

print string outside the image region black on white. The legend is either placed right or botto. of the image depending on the ratio of the resulting total image (smaller ratio wins). The string can be a multiline string separated by '\n', e.g. "this\nis\nmultiline\ntext". The extra space needed for the legend is reserved automatically. Long multiline strings should preferably be passed by specifying this option several times (e.g. for each line separately) because of limitations of the option parser. The string can be reset to zero length (e.g. for multifile input together with modelines) by using [--legend] w/o string argument. See also STRING ESCAPES.

font size. Must be between (inclusive) 1 and 4. If the font size is not specified, it is chosen according to the image dimensions: a larger image gets a larger font size.

The xxxxxx must be given as 6-digit or 3-digit hexadecimal number, where the first digit(s) are the red value, the second two digit(s) the green value and the last two digit(s) the blue value (so the color values for each color are between 0 and ff). Note that zimg will try to choose a color out of the existing color map which comes close to what you've specified, but depending on the color map you might not get exactly what you've requested. Alternatively the color can be also specified by one of the predefined color names, see the section "LINE COLORS". If the text color is not given, it will be chosen automatically and should give normally a high contrast.

draw a line or polyline from x1, y1 to x2, y2 (and more vertices) on the FINAL image. 'Final' means the image size with all padding and scaling applied. Example --line=+10+10+10+20 draws a horizontal line. All coordinates are absolute. Negative coordinates are interpreted from the right and bottom border respectively.

same as [--line], but all coordinates except x1 and x2 are interpreted relatively to x1 and x2.

Display some license information. zimg is published under the terms of a BSD type License.

Prints a version identifier for zimg to standard error. This is guaranteed to always contain the string "zimg" and the version number. Additionally the string "png" or "gif" indicates the output format which depends on the gd driver which was compiled in. Compile time options as edf support are appended in brackets.

switch on some informational output. Might not be too useful.

print histogram like statistics of the processed data to stderr.

Prints a help message to stderr and dies.