VIMAGE 0.9  Oct 29, 1991 -- Lee Iverson

This package can now be considered to be a full beta release of the
vimage application and widget set.  It is a collection of Xt widgets
which create a cohesive image viewing tool.  The user-interface is
still somewhat flexible but probably won't change much from now until
the 1.0 release.  It works fine with X11R5 and should continue to work
with R4.

Why another one?  The answers are of two types.

1) I wanted a widget that could be easily used either standalone or
   embedded in a larger application.  An earlier poll of
   comp.windows.x searching for such a beast turned up nil.

2) I needed something that would allow arbitrary user-defined
   extensibility to new image types and display variations.  This
   meant the adoption of an objected-oriented image type heirarchy (a
   la Xt).  Eventually such things as EdgeMap and ImageFlow can be
   implemented and seamlessly integrated into the overall application.

INSTALLATION:

Should be straightforward.  Configuration information is in Imakefile and
config.h.  Edit those files appropriate to your system and you should be fine.
Pay special attention to compiler selection and VIMLIBDIR and VIMINCDIR
at the top of the Imakefile.  Once this is done, then
	xmkmf
	make depend
	make World
	make install

If you don't have xmkmf and imake, you will have to deal with the raw Makefile
provided.  Oh well...

RECOMMENDED TOOLS:

- JPEG: The free JPEG distribution is an excellent intro to JPEG file
  compression.  The latest release is available from
  uunet.uu.net:graphics/jpeg/jpegsrc.v1.tar.Z.

- libXukc: This is a widget set which extends the functionality of the
  Athena widgets considerably.  They are available as part of the Dirt
  interface builder system (export.lcs.mit.edu:contrib/dirt.A1.10.tar.Z).
  Currently, the three components of this system I depend on are
  included with this package.

- ad2c.  This is an extremely useful way of providing a consistent
  set of fallback application defaults.  It essentially compiles the .ad
  file for an application into a set of strings which should be loaded
  into the application context at startup.  Actually, ad2c is only required
  if you change VImage.ad and want the new defaults compiled in as
  fallback resources.

- ezMenu.  This is a nice, simple Menu interface which gives a clean
  and simple interface to the Athena SimpleMenu structure.  I've
  modified it slightly, but only to make it a little more robust.

- dld-3.2.3.  Dynamic loading facilities.  This is an excellent
  package for dynamically loading code into a running applications.  I
  use it to deal with user-defined (and identified) file types.
  Available from aeneas.mit.edu:/pub/gnu/dld-3.2.3.tar.Z

- Xpm-3.0.  Facility for handling Xpm files etc.  This is an X pixmap
  external data format analogous to the XBM format.  Available from
  export.lcs.mit.edu:/contrib/xpm-3.0.tar.Z

FEATURES:

- ImageViewport widget.  A viewport widget which manages and 
  with arbitrary resizing of the child widget.  It is clearly derived
  from the Xaw Viewport widget, and includes both it's copyright and
  my own.  Supports a popup menu bar and a large number of actions for
  display and manipulation of the image.

- Image widget.  A general purpose image viewing, zooming, and
  examining base.  This is the part of the system which is the most
  volatile at the moment, since I have plans to extend this to an
  ImageStack widget (mostly done) (i.e. a number of images overlayed
  on on another!).  A set of interaction primitives enable arbitrary
  image zooming.

- FileDialog widget.  A Mac-like modal File dialog widget.  Needs some
  work, but is quite functional and has a nice interface for only
  selectively seeing certain files.  Depends on the regexp(3) library
  functions (included).

- CMManage.  A set of routines for managing a consistent colormap
  within an application in which there are a potentially broad variety
  of different areas of the program which are trying to allocate
  colors.  This overrides the standard Xt StringToColor translations,
  so that resource manager color definitions will work properly even
  when this color manager is being used.

- notifier.  A simple application which takes input from its stdin and
  pops up an AsciiText widget to display them.  A utility function
  (provided) will pipe stderr fromm your X application to the
  notifier!

- An Xt-like class heirarchy of Image types.  The analog for Core is
  the GenericImage type.  Three standard Image types are currently
  provided: BitImage, ByteImage and RGBImage, all rectangular bitmaps.
  ByteImage has a colormap associated with it.  The image reading
  functions (currently supporting only PBM, PGM, PPM and GIF) create
  one of these types.  The Image widget interfaces to a set of generic
  object-oriented calls which are redefined (as necessary for the image
  types). 

- A dynamic loading interface for image formats and associated support
  functions.  One of the really essential things for supporting an
  experimental image-processing environment is the ability to define
  special image types (e.g. EdgeMap or OpticalFlow) and allow the user
  to use them in as transparent a manner as possible.  This depends on
  dld-3.2.3 (and the patches below).

- Adoption of a generic image format that supports cross-platform
  portable images with arbitrary data formats (also using dynamic
  loading).  I'm not sure whether something out there already will work
  (maybe CGM), but if nothing really fits what I need, then (sigh!)
  another image format.

- Automatically uncompresses, unbtoa's and translates from any PBMPLUS
  recognized format to something that it can read!  This is a Wow!

BUGS:

- Currently the relationship between Image files and ImageDisplays is not
  as well put-together as it should be.  As a result, the attempt to reread
  a file from the StackEditor causes a core dump.

CAVEATS:

- There is currently NO DOCUMENTATION (except this file).  A little
  bit of application default browsing and source code reading should
  elucidiate things for now, but real docs will come along soon.

- I've only really tested this on a Sun4 OS 4.1 with mono and 8bit
  color displays and on VAX/Ultrix, but my ability to get close
  to other hardware is limited, so no guarantees.  Sigh!

- If you are using the MIT X11R4 Xt library (patchlevel 15+), there is
  a bug in XtDestroyWidget that bites pretty big.  The R5 work has
  forced an end to official patches for R4, so you will need to apply
  the following patch in lib/Xt.

*** Destroy.c.~1~	Mon May  6 12:25:26 1991
--- Destroy.c	Mon May  6 12:26:45 1991
***************
*** 225,233 ****
      while (i < app->destroy_count) {
  	if (dr->dispatch_level >= dispatch_level)  {
  	    Widget w = dr->widget;
! 	    if (--app->destroy_count)
  		bcopy( (char*)(dr+1), (char*)dr,
! 		       app->destroy_count*sizeof(DestroyRec)
  		      );
  	    XtPhase2Destroy(w);
  	}
--- 225,234 ----
      while (i < app->destroy_count) {
  	if (dr->dispatch_level >= dispatch_level)  {
  	    Widget w = dr->widget;
! 	    /* This was writing well past the end of the list! -- leei */
! 	    if (--app->destroy_count > i)
  		bcopy( (char*)(dr+1), (char*)dr,
! 		       (app->destroy_count - i)*sizeof(DestroyRec)
  		      );
  	    XtPhase2Destroy(w);
  	}

- If you are using dld-3.2.3, there are two bugs which I've tickled
  that should be fixed.  They've been reported and will be  in the
  next release.  Patches follow:

*** dld.c.~1~   Thu May 30 03:13:31 1991
--- dld.c       Wed Jul 10 04:02:39 1991
***************
*** 2015,2021 ****
      if (_dld_latest_entry->library_flag && _dld_latest_entry->subfiles == 0) {
        free (_dld_latest_entry->local_sym_name);
        if (_dld_latest_entry->filename != _dld_latest_entry->local_sym_name)
!           free (_dld_latest_entry->filename);

        _dld_latest_entry = kill_entry (_dld_latest_entry);
        file_close ();
--- 2015,2024 ----
      if (_dld_latest_entry->library_flag && _dld_latest_entry->subfiles == 0) {
        free (_dld_latest_entry->local_sym_name);
        if (_dld_latest_entry->filename != _dld_latest_entry->local_sym_name)
!         free (_dld_latest_entry->filename);
!
!       _dld_latest_entry->local_sym_name = 0;
!       _dld_latest_entry->filename = 0;

        _dld_latest_entry = kill_entry (_dld_latest_entry);
        file_close ();

*** dld.c.~1~	Wed Jul 10 04:02:39 1991
--- dld.c	Sun Aug 25 12:13:18 1991
***************
*** 290,296 ****
  int size;
  {
      register int result = malloc (size);
!     if (!result)
  	fatal (DLD_ENOMEMORY);
      return result;
  } /* _dld_malloc */
--- 290,296 ----
  int size;
  {
      register int result = malloc (size);
!     if (size && !result)
  	fatal (DLD_ENOMEMORY);
      return result;
  } /* _dld_malloc */


Planned Extensions:

- Documentation. Some. Any...

- A shared memory image manager (probably a separate program) for fast
  and efficient communication between image processing programs and
  the viewer.

------------------------------------------------------------------------------

Lee Iverson			McGill Research Centre for Intelligent Machines
leei@mcrcim.mcgill.edu		Computer Vision and Robotics Lab
				McGill University, Montreal