Scripting using imview

Image Viewer (imview)


The imview task offers scriptable access to many viewer options. This enables the production of customized plots without invoking the GUI and allows one to open the viewer to a carefully selected state.

imview has the following inputs:

#   imview :: View an image
raster      =    {}     # (Optional) Raster filename (string)
                        #   or complete raster config
                        #   dictionary. The allowed dictionary
                        #   keys are file (string), scaling
                        #   (numeric), range (2 element numeric
                        #   vector), colormap (string), and
                        #   colorwedge (bool).
contour     =    {}     # (Optional) Contour filename (string)
                        #   or complete contour config
                        #   dictionary. The allowed dictionary
                        #   keys are file (string), levels
                        #   (numeric vector), unit (float), and
                        #   base (float).
zoom        =    1      # (Optional) zoom can specify
                        #   intermental zoom (integer), zoom
                        #   region read from a file (string) or
                        #   dictionary specifying the zoom
                        #   region. The dictionary can have two
                        #   forms. It can be either a simple
                        #   region specified with blc (2 element
                        #   vector) and trc (2 element vector)
                        #   [along with an optional coord key
                        #   ("pixel" or "world"; pixel is the
                        #   default) or a complete region
                        #   rectangle e.g. loaded with
                        #   "rg.fromfiletorecord( )". The
                        #   dictionary can also contain a
                        #   channel (integer) field which
                        #   indicates which channel should be
                        #   displayed.
axes        =    -1     # (Optional) this can either be a
                        #   three element vector (string) where
                        #   each element describes what should
                        #   be found on each of the x, y, and z
                        #   axes or a dictionary containing
                        #   fields "x", "y" and "z" (string).
out         =    {}     # (Optional) Output filename or
                        #   complete output config dictionary.
                        #   If a string is passed, the file
                        #   extension is used to determine the
                        #   output type (jpg, pdf, eps, ps, png,
                        #   xbm, xpm, or ppm). If a dictionary
                        #   is passed, it can contain the
                        #   fields, file (string), scale
                        #   (float), dpi (int), or orient
                        #   (landscape or portrait). The scale
                        #   field is used for the bitmap formats
                        #   (i.e. not ps or pdf) and the dpi
                        #   parameter is used for scalable
                        #   formats (pdf or ps).

The raster and contour parameters specify which images to load and how these images should be displayed. These parameters take python dictionaries as inputs. The fields in these dictionaries specify how the image will be displayed.

An example call to imview looks like this:

imview(raster={'file': 'ngc5921.clean.image',

     'range': [-0.01,0.03],

     'colormap': 'Hot Metal 2',

     'scaling': -1},

     contour={'file': 'ngc5921.clean.image'},

     axes={'x':'Declination'} ,

     zoom={'channel': 7, 'blc': [75,75], 'trc': [175,175],

     'coord': 'pixel'},



The argument to raster is enclosed in the curly braces { } . Within these braces are a number of "key":"value" pairs. Each sets an option in the viewer, with the GUI parameter to set defined by the "key" and the value to set it to defined by "value." In the example above, file=’ngc5921.clean.image’ sets the file name of the raster image, range= [-0.01,0.03] sets the range of pixel values used for the scaling.

contour works similarly to raster but can accept multiple dictionaries in order to produce multiple contour overlays on a single image. To specify multiple contour overlays, simply pass multiple dictionaries (comma delimited) in to the contour argument:

contour={'file': 'file1.image', 'levels': [1,2,3] }, {'file': 'file2.image', 'levels': [0.006, 0.008, 0.010] }

zoom specifies the part of the image to be shown. The example above specifies a channel as well as the top right corner "trc" and the bottom left corner "blc" of the region of interest.

axes defines what axes are shown. By default, the viewer will show ’x’:’Right Ascension’, ’y’:’Declination’ but one may also view position-frequency images.

out defines the filename of the output, with the extension setting the file type.

Currently, the following parameters are supported:

raster  -- (string) image file to open
           (dict)   file (string)     => image file to open
                    scaling (float)   => scaling power cycles
                    range (float*2)   => data range
                    colormap (string) => name of colormap
                    colorwedge (bool) => show color wedge?
contour -- (string) file to load as a contour
           (dict)   file (string)     => file to load
                    levels (float*N)  => relative levels
                    base (numeric)    => zero in relative levels
                    unit (numeric)    => one in the relative levels
zoom    -- (int)    integral zoom level
           (string) region file to load as the zoom region
           (dict)   blc (numeric*2)   => bottom left corner
                    trc (numeric*2)   => top right corner
                    coord (string)    => pixel or world
                    channel (int)     => channel to display
           (dict)     => record loaded
                                         e.g., rg.fromfiletorecord( )
axes    -- (string*3) dimension to display on the x, y, and z axes
           (dict)   x                 => dimension for x-axes
                    y                 => dimension for y-axes
                    z                 => dimension for z-axes
out     -- (string) file with a supported extension
                    [jpg, pdf, eps, ps, png, xbm, xpm, ppm]
           (dict)   file (string)     => filename
                    format (string)   => valid ext (filename ext overrides)
                    scale (numeric)   => scale for non-eps, non-ps output
                    dpi (numeric)     => dpi for eps or ps output
                    orient (string)   => portrait or landscape

Examples are also found in help imview.