Next Previous Contents

6. Image Display

6.1 imdisplay


Render a stack of still images or display an animation


imdisplay( FileName_or_ImageArray_or_Option [, ...])


This function accepts an arbitrary number of images as input, and by default renders them stacked upon one another, respecting transparency. The composite image may be easily tiled or scaled, as well as auto- matically scrolled for images too large to fit reasonably within your display. Pressing any button while the mouse is positioned over the image will show the color value for that pixel, in either RGB or RGBA format (for images with an alpha channel); an alpha value of 1.0 indicates that the pixel is fully opaque, while 0.0 indicates full transparency.

Images may also be displayed in one of several alternate modes: First, the panes option causes each input image to be displayed within its own window, tiled either vertically or horizontally; second, the 'anim' option may be used to animate a series of 2D still images, with the ability to pause and step forward/backward between frames; finally, 'anim' can also animate 3D volumes (as series of 2D slices), although this is often not necessary because; imdisplay() will automatically animate 3D arrays of dimension [N, M, Z>4] (as they are clearly not RGBA images), as well as images specified via Array_Type[N] and List_Type[N].

By default image windows are chained to each other, and the control window, so that all may be moved onscreen, at once, simply by moving the master.

The images passed in may be names of files, GDK pixbufs, or S-Lang arrays (2D/greyscale, 3D/RGB, or 3D/RGBA, or arbitrary 3D volumes). If any input image in a composite contains an alpha channel (transparency) then the rendered result will as well.

A wide variety of input file formats are supported, including JPEG, PNG, GIF, XPM, TIFF, animations and (optionally) the FITS file format popular in astronomy. The rendered result may also be saved to a variety of formats, including JPEG, PNG, GIF (still and animated) and FITS. The range of supported formats depends upon how your Gtk distribution was compiled.

Comma-delimited options to imdisplay() may be specified either as strings within the argument list or via qualifiers separated from the argument list by a semicolon. Most options affect the composite image just prior to display, and include:

        anim[=delay]            Animate input images into a movie.  The
                                optional frame refresh delay should be a
                                single scalar value in milliseconds, and
                                defaults to 500 (0.5 sec) if omitted.

        fill=<rule>               how to fill new space created in image
                                display window when it is enlarged; one of

                                   none    no fill; keep original image
                                   tile    fill with consecutive image copies
                                   scale   fill by enlarging image to fit

        flip                    mirror the image vertically
        flop                    mirror the image horizontally

        save=<name>[/type]        Instead of rendering image(s) onscreen, save
                                to <filename>; a file type may be specified
                                via a /gif, /png, etc. optional qualifier
                                [see _gdk_pixbuf_get_formats()] or inferred
                                from the file extension; if no file type can
                                be determined then still images will be saved
                                in PNG format; animations are always saved
                                in GIF format.

        size=<geometry>           resize the image; geometry may either
                                be a scaling percentage or an absolute
                                pixel size, such as 150x200% or 100x300;
                                when only one value is provided it will
                                be applied to both axes of the image

        scale=<geometry>  synonym for size= option.

        panes=<layout>            how to display multiple images; layout may be

                                one | single    composite all images into
                                                one window (the default)
                                horiz[ontal]    tile images horizontally
                                vert[ical]      tile images vertically

                                No compositing is performed for horizontal
                                or vertical tiling.

        horiz[ontal]            shorthand for panes=horiz[ontal]
        vert[ical]              shorthand for panes=vert[ical]
The default display options may be changed with imdisplay_defaults(); the new defaults will persist between subsequent invocations of imdisplay() (in the same process) or until imdisplay_defaults() is called with no arguments.

At launch all of the windows created by imdisplay will be chained: e.g. the control window will be chained to the window of the last image loaded, meaning that the controller will follow the image window around onscreen when the latter is moved; when the controller is moved its new gravity (i.e. placement relative to the image) will be remembered. An entire vertical (or horizontal) tiling of windows may be moved simply by moving its top- (or left-) most window.

To disable chaining, ensure that the slave window you wish to unchain has focus, then hold down the SHIFT key while moving the slave. This will disconnect the slave from its own master, but leave intact any chains in which the slave is itself a master.


The sequence of commands

        unix% cd <slgtk_distribution_on_your_system>/images

        unix% slsh
        slsh> require("imdisplay")

        slsh> pb1 = gdk_pixbuf_new_from_file("stars.fits")
        slsh> im1 = _reshape( [1:200*300], [200,300])
        slsh>  imdisplay(im1, pb1, "gtk-logo-rgb.gif", "flip,size=70%", "red.png")
should yield the visual


        slsh> red = UChar_Type[100,100,4]
        slsh> red[*,*,0] = 255
        slsh> red[*,*,3] = 127                       % 50% transparency
        slsh> blue = UChar_Type[200,200,3]
        slsh> blue[*,*,2] = 255
        slsh> imdisplay("size=211x79", blue, "flip", red, "flop")

  should yield


imdisplay may also be used from the OS prompt as an executable script. In this form only files may be loaded, but all other options are supported, including the "help" switch which provides detailed usage information.

Next Previous Contents