ZIMG(1)

NAME
zimg - Display 2-D data of arbitrary format

SYNOPSIS

zimg [options] [file ...]

DESCRIPTION
The zimg program generates png images out of almost arbitrary formatted 2-D data.

zimg is capable of generating images from a big variety of input format files: both plain unformatted ascii and binary input are supported

INPUT FILES
If no input files are given, zimg reads from stdin. If the input file ends in .gz, .bz2, .z or .Z and your operating system supports the popen() call, the file is filtered through gunzip, bunzip2 or uncompress respectively. If an input file is not accessible, the availability of the file with the suffixes .gz, .bz2, .z or .Z appended is checked (multiview). If no command line options are specified, zimg assumes plain ascii input, where the dimensions of the image are taken from the first two convertable integers and comment lines are marked by a hash `#' mark at the very first column of each line. If ascii data is read the first lines are parsed for zimg modelines until the first data point is read. See below in the section MODELINES. Currently the `ESRF data format' (edf and ehf) is the only binary input format which is detected automatically by zimg (if this option was not disabled at compile time). In the case of ehf, the data is read from a different file as specified by the tag EDF_BinaryFileName. If the size was not specified and no binary option was selected, the first bytes of the source file are examined to check if the source is already a png file. This works only on systems where there's no difference between reading ascii and binary data (UNIX). If the source file is a png, all options except the labelling and output options are ignored. This is mainly useful for labelling a png file later (or a png file that was not created by zimg). It can also be used to just convert png to jpeg. Note that this check is not available if zimg was linked with an older libgd version.

OPTIONS
In almost all cases you'll need to specify at least a few command line options to tell zimg something about the input format and specify the output style.

Note, that the order of command line options is important: in the case of mutually exclusive options the last one wins; in the case of a switch which turns an option on, a second occurence of this switch turns the option off again. Example: -x -x does nothing. This is useful for overwriting options which were set in the resource files ~/.zimgrc and .zimgrc (see section FILES). If an options overwrites another option (e.g. in `--red --blue', the second switch would overwrite the first), this is silently ignored. Some switches can be defined more than once and are position dependent. These switches include
    --differentiate
    --curvature
    --smooth
    --logarithmic
    --fabs
    --absolute
    --relative This means that in
    zimg --relative=10-60 --differentiate the relative scaling applies to the raw data, but in
    zimg --differentiate --relative=10-60 the relative scaling applies to the differentiated data.

Spaces separating the single-letter options from their parameters are optional. Quite a lot of options are not available if the gd driver was disabled at compile time. Use the --help option to get a list of valid options for your binary version of zimg.

-r, --size=widthxheight
    specifies the width and height of the 2-D data.

-p, --pattern=pattern
    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.

-b, --block=number
    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[=bytes/lines]
    skip this amount of lines when reading ascii data. Skip bytes, if reading binary data. Note that the unit is bytes, irrespective of the intput type (short ..). If the optional size argument is missing, the option is reset to its default. This default behaviour 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 <width>x<height> items of the input stream will be taken. If you don't like this feature you can disable it explicitely by using the switch `--skip=0'. For ascii data no skipping will be done by default.

--output=path
    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" depending on the gd version which was used at compile time.

--big-endian
    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.

--little-endian
    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
    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.

-f, --float
    read binary float (normally 4 bytes) data.

-d, --double
    read binary double (normally 8 bytes) data.

--char
    read signed char data.

--short
    read signed short data.

--int
    read signed int data.

--long-int
    read signed long-int data.

-c, --unsigned-char
    read unsigned char data.

-s, --unsigned-short
    read unsigned short data.

-i, --unsigned-int
    read unsigned int data.

--unsigned-long-int
    read unsigned long int data.

--complex-float[=(abs/length|phase|real|imaginary)]
    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).

--complex-double=(abs/length|phase|real|imaginary)
    Like --complex-float, but for complex double binary input data.

--red
    use a red scale color map.

--blue
    use a blue scale color map.

--grey, --gray
    use a grey scale color map.

-m, --colormap[=number]
    select colormap number. Currently 2 colormaps are available. If none of the color switches is given, a geographical color mapping is used. This is equivalent to --colormap=1. If the optional argument number is omitted, the colormap is reset to the default.

-m, --colormap=path
    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 0xff (255).

-m, --colormap=red[,green[,blue]]
    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]:
        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;

-I, --invert
    invert the selected color map.

-x, --xor
    do an exclusive or ^0xff with the selected color map. For the gray scale color map this equivalent to the --invert switch.

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

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

--smooth[=sigma]
    wipe out hot spots. The average and sigma of the nearest neighbours 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 neighbours. This is a position dependent switch

-l, --logarithmic[=scale]
    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

-a, --fabs
    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

--absolute=min,max
    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 - can be used as separator instead of the ,. This is a position dependent switch

--relative=min,max
    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

-S, --scale=xy

-S, --scale=xxy

-S, --scale=1/xy

-S, --scale=1/xx1/y
    Integer scaling or binning. The factors must be either integers or reciprocal integers indicated as 1/x. If only one number is given, it is applied to both directions.

-C, --crop=left-rightxtop-bottom
    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.

-A, --align=horizontal[xvertical][,bordercolor]
    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.

--contours=levels[,log][,bg=color]
    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=' forces controur-only drawing i.e. colors the background with the specified color. This color must be an integer between 0 and 100 and is specific to the selected color map. The number is interpreted as a relative value (percentage) in the colormap of the processed data. Instead of a color number the keyword `black' might be used. The contour algorithm is pretty fast and does not spline when enlarging the image.

--interlace
    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.

-j, --jpeg[=quality]
    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.

-t, --time-stamp[=string]
    print the date and the input filename. If an optional string is given it is printed instead of the filename.

--top-left=string

--bottom-left=string

--top-right=string

--bottom-right=string
    print string in the specified corner of the image. The string can be a multiline string separated by '\n', e.g. "this\nis\nmultiline\ntext". All four forms can be used together with different strings. The offsets to the image boundaries are calculated automatically. For the --top-right and --bottom-right the text can be left-aligned with the --left-align switch.

--xlabel=x,y,string
    --ylabel=x,y,string Draw a horizontal or vertical text label at x,y respectively. Useful in combination with the scale switches (see below).

-F, --font=integer
    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.

-T, --textcolor=xxxxxx
    The xxxxxx 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 --align switch. If the text color is not given, it will be chosen automatically and should give normally a high contrast.

-X, --xscale=x,y,pixels
    -Y, --yscale=x,y,pixels draw a horizontal or vertical scale respectively with pixels length at the position x,y. A scale is a thin line with small perpendicular end delimiters. This is NOT for scaling the image, use the -S switch for scaling the image.

--left-align
    Left align the text of the --top-right and --bottom-right options. This is only meaningful for multiline strings. Left alignment is calculated with the length of the longest line of a multiline pattern.

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

-V, --version
    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.

-v, --verbose
    switch on some informational output. Might not be too useful.

--statistics
    print histogram like statistics of the processed data to stderr.

--help
    Prints a help message to stderr and dies.

MODELINES
If the input data is ascii (or at least the header is ascii), zimg looks for modelines like some versions of vi or vim do. This is done only until the first data point is read. The format for modelines is as follows:
    <space>zimg:<zimg options>: You can have multiple modelines and even use a modeline to switch to binary input. Example:
    #!/usr/local/bin/zimg
    # zimg: -l10 -C50-550x200-450:
    # zimg: -m7,5,15 -t -r547x633 -s --swap:
    ... Note that in this case the order is important. Everything after the line containing the -s (unsigned short binary) is considered as binary data. So exchanging the two modelines like in the next example would interpret the second modeline as binary data (which is probably not what you want):
    #!/usr/local/bin/zimg
    # zimg: -m7,5,15 -t -r547x633 -s --swap:
    # zimg: -l10 -C50-550x200-450:
    ...

EXAMPLES

zimg my.dat > my.png
    This one of the most simple examples. The file my.dat is assumed to hold the dimensions of your 2-D data as the first two convertable integers. Everything before the first convertable integer is silently skipped, so it is also valid to have the dimension specifiers after a comment (hash) mark like this:
        # 128 128
        45.12
        76.70
        ...

my.dat > my.png
    If your operating system supports the specification of an interpreter by preceeding it with #! you can make your data file an executable like this (you probably have also to change the permissions of my.dat e.g. `chmod +x my.dat' on UNIX):
        #!/usr/local/bin/zimg
        # 128 128
        # zimg:--red:
        45.12
        76.70
        ...

zimg my.dat.gz | xv -
    pipe the output of zimg directly to your favourite image viewer (here: xv). The file will be filtered by gunzip.

zimg --red -r1200x1200 --skip=2400 -S1/2 -s l408_01.image | xv -
    read binary data which hold 1200 x 1200 unsigned short data values. Skip the first 2400 bytes. Use the red scale color map. Scale the image down to 600 x 600 pixels and pipe it to xv. Note that the skip option is not really necessary as long as the data is located at the very end of the input file. In this case the header size would be calculated by zimg.

zimg my.png --xlabel=10,10,'love is like oxygen' --jpeg > my.jpg
    read the png as source image, apply a label and write it as jpeg.

ENVIRONMENT VARIABLES

HOME
    When this variable is found, zimg looks there for a file with the name .zimgrc which may contain command line options.

FILES
the .zimgrc file in the HOME and the current directory are read in this order. These files are read before command line parsing is done, so command line options given on the command line will eventually overwrite previously defined settings of the resource files. The .zimgrc files in the HOME and the currrent working directory might contain command line options separated by any white spaces including newlines. Blank lines and everything behind a hash `#' mark is considered to be a comment.

BUGS
probably.

SEE ALSO
The official zimg web site at:

    http://www.zellner.org/zimg/index.html

AUTHOR
Johannes Zellner <johannes@zellner.org>

HISTORY
This version of zimg was originally derived from the program z2ppm which was able to write portable pixmap (ppm) files.

CREDITS

Thomas Boutell <boutell@boutell.com>, the author of the gd driver.

Petr Mikulik's <mikulik@physics.muni.cz> for the color code
    (getcolor.c, see also http://www.sci.muni.cz/~mikulik/gnuplot.html) and the OS/2 port

Levente Novak <novak@jaguar.dote.hu> for the DOS/DJGPP port.