Get Teem at SourceForge.net. Fast, secure and Free Open Source software downloads
teem / bin

  ilk

ilk demonstrates functionality in the moss library. It is a fairly general tool for performing geometric transformations on "images": any non-block-type 2D and 3D NRRD. I know and love the Image Magick tools, and most of the functionality here is a subset of what is available in mogrify, but ilk will happily work on an image with 50 doubles per pixel.

This page gives a summary of the various capabilities of ilk. Everytime that an image is preceeded by some text in mono-spaced font, that text can be pasted into a shell in order to regenerate the image. This assumes that ilk, unu, and cjpeg are all in your path, or are aliased.

General Usage Information

ilk: (I)mage (L)inear Trans(X-->K)forms. Applies linear (homogenous
coordinate) transforms to a given image, using the given kernel for resampling.

Usage: ilk [@file ...] [-i <image>] [-0 <origin>] -t <xform0 ...> \
       [-k <kernel>] [-min <xMin yMin>] [-max <xMax yMax>] [-b <boundary>] \
       [-bg <bg0 bg1 ...>] [-s <xSize ySize>] [-o <filename>]

        @file ... = response file(s) containing command-line arguments
       -i <image> = input image; default: "-"
      -0 <origin> = where to location (0,0) prior to applying transforms.
                  o "u:<float>,<float>" locate origin in a unit box
                    [0,1]x[0,1] which covers the original image
                  o "p:<float>,<float>" locate origin at a particular
                    pixel location, in the index space of the image
                    default: "p:0,0"
  -t <xform0 ...> = transform(s) to apply to image. Transforms are applied in
                    the order in which they appear.
                  o "identity": no geometric transform, just resampling
                  o "translate:x,y": shift image by vector (x,y), as
                    measured in pixels
                  o "rotate:ang": rotate CCW by ang degrees
                  o "scale:xs,ys": scale by xs in X, and ys in Y
                  o "shear:fix,amnt": shear by amnt, keeping fixed the
                    pixels along a direction <ang> degrees from the X axis
                  o "flip:ang": flip along axis an angle <ang> degrees
                    from the X axis
                  o "a,b,c,d,tx,ty": specify the transform explicitly 
                    (1 or more 2D transforms)
      -k <kernel> = reconstruction kernel; default: "cubic:0,0.5"
 -min <xMin yMin> = lower bounding corner of output image. Default (by not
                    using this option) is the lower corner of input image.
                    (2 doubles)
 -max <xMax yMax> = upper bounding corner of output image. Default (by not
                    using this option) is the upper corner of input image.
                    (2 doubles)
    -b <boundary> = what to do when sampling outside original image.
                  o "bleed": copy values at image border outward
                  o "wrap": do wrap-around on image locations
                  o "pad": use a given background value (via "-bg")
                    default: "bleed"
-bg <bg0 bg1 ...> = background color to use with boundary behavior "pad".
                    Defaults to all zeroes. (1 or more floats)
 -s <xSize ySize> = For each axis, information about how many samples in
                    output:
                  o "x<float>": number of output samples is some scaling
                    of the number input samples; multiplied by <float>
                  o "<int>": specify exact number of samples
                    (2 sampling specifications)
                    default: "x1 x1"
    -o <filename> = file to write output nrrd to (string); default: "-"
The "-t" option is the only required one. The input and output default to standard input and standard output, respectively. The options may come in any order. Options my be repeated, but seqsequent appearance override previous ones. You don't build up a transformation in steps with multiple "-t" flags: the single "-t" takes an arbitrary number of transformations after it, as demonstrated later on this page.

Options which will be used verbatim many times may be entered into a "response file"; when these are indicated on the command line with "@filename", the contents of the file are effectively inserted there on the command line. Within the response file, line breaks count as white space, and comments lines begin with "#".

Demonstration image

To demonstrate, we'll use a cropping (huysumcrop.ppm) of a still life by Jan van Huysum. For ease of display on this page, we'll actually use a downsampled version of the image, and results of processing will be saved out as high-quality JPEGs, using cjpeg.
unu resample -i huysumcrop.ppm -s = x0.6 x0.6 -o init.ppm
cjpeg -quality 99 init.ppm > init.jpg
Note: this isn't entirely true. If you want to follow along with the examples here by running the commands yourself, you should hand-edit init.ppm so that it doesn't have any "# NRRD>" comment/headers, since these will change the behavior of some of the commands demonstrated here, in a way that will only complicate the explanation.

The output of ilk is a NRRD file, but it will have the same dimension and type as the input 8-bit color image, which means it can be converted to a PPM file (really just changing the header), and then saved as a JPEG, with the following sequence:

 ... | unu save -f pnm | cjpeg -quality 99 out.jpg
Because this will be used so often, I'll create an alias for it:
alias tojpg "unu save -f pnm | cjpeg -quality 99"
HOWEVER, the thing to keep in mind as you read this page, is that ilk will happily process any 3D NRRD file; it will just take the number of samples along the fastest axis as the number of components/channels associated with each pixel. This means that ilk is good for operating on spectral image data, as well doing axis-aligned operations on 3D scalar fields.

The axes, the origin

The "X" and "Y" axes that ilk uses may take a little getting used to; they are the raster directions of the image data, meaning that the origin of this basis is in the upper left:
(0,0) -----------> X
  |
  |
  |
  v

  Y
When describing angles, the units are always degrees, and "0" means parallel with the X axis, "90" means parallel with the Y axis, with angles increasing counter-clockwise.

There are two ways of specifying the origin to ilk:

  1. -0 u:<X>,<Y>: The (X,Y) location of the origin is relative to position inside a unit box spanning the image, using the same axes orientation as shown above. -0 u:0.5,0.5 is the center of the image.
  2. -0 p:<X>,<Y>: The (X,Y) location of the origin is in the index space of the image itself, so these are effectively pixel locations (but they don't have to be integers).
The little pages describing different capabilities and uses: