This directory contains Andrew Dorrell's (dorrell@ihf.uts.edu.au) port
of the pict image type to STk.  The original code  is available from a
number of Tcl/Tk archive sites and is distributed both as a standalone
pict  image type and as part  of an  image processing oriented package
called  visu.     This code is    in fact  a  rework  of  the visu-2.0
distribution  (I  didn't  know about   the standalone version   when I
started  work on it... in  fact it is possible that  the pict type was
independently extracted and posted after I started work on this port).
Anyway the code is a rework  of previously copyrighted software as per
the comments in  the source files.  The  README file from the original
visu distribution is included with this reworked release.


LICENSE TERMS  

This  code are copyrighted by   various individuals and organisations.
The  original copyright  notices in the  source  files  have not  been
modified however  modifications and additions unique  to this port are
copyright by  Andrew Dorrell.  The code is  re-released under the same
terms   and conditions  as  the  original  visu  package for tk.   See
license.terms for details.


ABOUT PICT

What is the pict image  type?  It is a  tk image type designed for use
with greyscale and pseudocolour images.   It is therefore well  suited
for   use with image  processing work.    For this  type  of image  it
provides superior display and manipulation capabilities to the regular
photo widget and in particular supports look-up table manipulations.

Having ported the code  I made a number of  modifications to it.  Most
of  these modifications  are  aimed  ot providing  better support  for
really big images.

Modifications include:

*  -height and -width options disabled

   They  were  resulting in unnecessary internal   copying of data and
   just plain got in the  way of my plans  to ad arbitrary image  data
   resampling.  The  functions they used to have  was identical to the
   photo image options of the same names.  For many applications there
   is no real loss here.

*  -xdnsample -ydnsample -xupsample -yupsample commands added

   The displaed image is resampled (although no interpolation of
   smoothing is dome).  A neat feature is that up and downsample
   commands can be combined to allow image resizing with arbitrary
   rational rates, independently in x and y!

*  -shallowcopy command added

   This is great.   It  allows multiple pict images  to  share the one
   master data block.  This was multiple instances can be used to show
   different zoomed versions of the same  image without having to load
   it more  than once.   Essential  for really big images.   Watch out
   though... if you reload the image containing the master data, other
   images which  share the data will  not be  updated and segmentation
   faults will follow.  The solution is to ensure all ``slave'' images
   point to  something safe  (an empty  image) prior to  reloading the
   master.

*  -hack command added

   This really is a hack --- lesser software suppliers would have left
   this as an undoccumented  feature :-)  Returns  the address of  the
   master image data block in memory.  Comments to the rational behind
   this blatantly hideous hack are best read from the source itself...
   Not intended for general use.

*  -datasize command added

   So that you can still  find out how big  the original data array is
   after you have resampled it (as resampling changes the image size).

*  -rdbinary command modified:

   Modified  the FileReadRAW finction   to prevent  unnecessary memory
   allocations and data copies.  This  is fairly well commented in the
   source.  Added an -order option to this  command for specifying the
   raw   byte  ordering.   Allowable   values  are ``bigendian''   and
   ``littlendian'' defaults  to  native byte ordering.   The  rdbinary
   command also   changes the  image   size to match    the dimensions
   specified  by  the  -width and    -height  options.  This  was  not
   previously the case as the command was  geared towards reading data
   into a  region of an existing image  (aka photo read command).  The
   modifications is significant as it  means that the rdbinary command
   now behaves much more like the -file command.

*  -clip command removed

   This command was redundant

*  convert,  close_holes,  dt,    dilation, erosion, get,   get_holes,
   gradient, histogram,   laplacian,   overlay, snap2photo, snap2pict,
   smooth, snake, threshold, thres_isodata commands removed.

   Most of these choices   were expedient.  I  use  the tk canvas  for
   displaying  graphic image overlays; I already  had code to do image
   processing  and all I really   wanted was a  fast, memory efficient
   display object.  Cutting all this stuff made the port managable



From the original visu documentation, here is a summary of the
remaining available pict image commands:

image create pict [options] 

     Creates an image 

     options: -data <string> Specifies contents of image in a
     supported format. Not supported. -file <fileName> Gives name of
     file whose contents define the image in supported format. -format
     <formatName> Specifies format for data specified with the -data
     or -file options. In the VISU extension, only the GIF/
     PPM/PGM/RAS/VIFF/VIEW formats are supported. -height <number>
     Specifies pixel height of the image. -width <number> Specifies
     pixel width of the image.

<imageName> blank

     Blanks the image so that it has no data and is completely transparent. \

<imageName> cget 

     Standard way to retrieve default values.

<imageName> configure 

     Standard way to set or query default values.

<imageName> cmap_level [value] 

     With no arguments, returns the current level for the image
     displayed. With an argument in the range [0-3], changes the
     colormap.  

<imageName> cmap_stretch [intensity|red|green|blue] cwidth clen x0 y0 ... xn yn

     Stretches the colormap in a piecewise-linear way. Each of the
     intensity, red, green, blue look-up tables can be changed
     independently. The coordinates of the points are in the range
     [0,cwidth] and [0,clen] for x and y respectively. The first point
     should have either its x or y value set to 0. The last point
     should have its x value set to cwidth or its y value set to
     clen. If you installed the plb_segment library, and no arguments,
     a histogram stretch will be performed.  

<imageName> cmap_threshold loval hival

     Thresholds the colormap so that all the pixels between loval and
     hival appear white and the rest black.  <imageName> colormap
     [gray|ct|hot|cold|hls|rgb|spectrum|invert|
     random|bowlerhat|tophat|hatgray|hatct]

     Loads one of the default look-up tables.
     
<imageName> copy <sourceImage> [options] 

     Copies region from <sourceImage> to <imageName> using given
     options:

     -from x1 y1 x2 y2 Specifies rectangular region of sourceImage to
     be copied. -to x1 y1 x2 y2 Specifies rectangular region of
     sourceImage to be affected. -shrink Will clip target to copied
     region is in bottom-right corner. -zoom x y Magnifies source
     region by x y in respective directions. -subsample x y Subsamples
     source region by x y in respective directions.

<imageName> convert <srcImg> -type [byte|short|int|float] 

     Converts data in source image to the type wanted (plb_segment
     library).

<imageName> get x y 

     Returns actual pixel value (not normalized for display) at pixel
     x y.

<imageName> getmin
<imageName> getmax 

     Returns the minimum and maximum values of the image.

<imageName> range min max 

     Sets a minimum and maximum value for images. Side effects only
     for non-byte images. Useful to compare short, int or float images
     that don't have the same dynamic range. It is the user's
     responsibility to ensure the range specified is larger than the
     actual range.
     
<imageName> read <fileName> [options] 

     Reads image data from file <fileName> into image using given options. 

     -format <formatName> Specifies image format of file. -from x1 y1
     x2 y2 Specifies a rectangular of the image file to copy
     from. -shrink Will clip image so copied region is in bottom-right
     corner. -to x y Specifies coords of the top left corner in image
     to copy into.

<imageName> rdbinary -file <fileName> <options>

     Reads binary image data from file <fileName> or <channelName>
     into image using given options.

     -from x1 y1 x2 y2 Specifies a rectangular of the image file to
     copy from. -width w Specify width/height/nb_slices of the
     data. -height h -nb_slices nb -skip s Number of bytes to be
     skipped from file beginning -type [byte|short|int|float]

<imageName> redither 

     Redithers the image.

<imageName> rxsize <rxsize> 

     Specifies physical dimension of pixel in x-direction
     
<imageName> rysize <rysize> 

     Specifies physical dimension of pixel in y-direction

<imageName> type 

     Returns type of image.

<imageName> write <fileName> [options] 

     Writes image data into file <fileName> (only VIEW, PGM and RAS
     supported)

     -format <formatName> Specifies image format for the output file. 
     -from x1 y1 x2 y2 Specifies a rectangular of the image to copy from.
     
<imageName> wrbinary -file <fileName> 

     Writes image data into raw binary file <fileName>