Initial commit

1 files changed, 635 insertions, 0 deletions

diff --git a/vendor/x11iraf/Notes-V2.0.txt b/vendor/x11iraf/Notes-V2.0.txt
new file mode 100644
index 00000000..4587c6ac
--- /dev/null
+++ b/vendor/x11iraf/Notes-V2.0.txt
@@ -0,0 +1,635 @@
+
+		    	X11IRAF V2.0 RELEASE NOTES
+		    	==========================
+
+		 Last Modified:  Mon Nov 17 12:00:11 MST 2008
+
+-------------------------------------------------------------------------------
+
+Release History:
+
+    November 17, 2008	-- Initial V2.0BETA public release
+
+-------------------------------------------------------------------------------
+
+
+Table of Contents:
+------------------
+
+    Executive Summary
+
+    1. Download and Installation
+	1.1  Downloading the Distribution
+	1.2  Installing Pre-Built Binaries
+	1.3  Building From Source
+	1.4  Comments, Suggestions and Bug Reports
+
+    2. XImtool Revisions
+	2.1  XGterm Revisions
+
+    3. Platform Support Issues
+	3.1  Linux Systems
+	    3.1.1  Determining your Graphics Hardware
+	    3.1.2  Intel Chipset Issues
+	    3.1.3  NVidia Issues
+	3.2  Mac OSX Systems
+	    3.2.1  Tiger and Leopard Support
+	3.3  Other Platforms
+
+    4. OBM (Widget Server) Revisions
+	4.1  GTerm Widget Changes
+	4.2  Athena Widget Changes
+
+    5. Client Display Library (CDL) Revisions
+	5.1  Display Protocol Changes
+
+    6. Technical Notes
+	6.1  IIS Protocol Changes
+	    6.1.1  IIS Protocol Summary
+	    6.1.2  Faster Sub-Raster Writes
+
+    7. Post-Release Notes
+
+-------------------------------------------------------------------------------
+
+==================
+Executing Summary
+==================
+
+This release provides the following improvements over previous versions:
+
+    1)  24-bit display Support for XImtool
+    2)  24-bit display Support for XGterm applications using imaging
+    3)  General platform support improvements
+
+For those accustomed to DS9 and not familiar with XImtool, a summary of
+features is provided at
+
+	ftp://iraf.noao.edu/iraf/x11iraf/Notes-V1.3.html
+
+This document will be updated as needed, see the 'Revisions' file for a
+detailed list of changes made in the source code.
+
+
+-------------------------------------------------------------------------------
+	
+=============================
+1. DOWNLOAD AND INSTALLATION
+=============================
+	
+1.1  Downloading the Distribution
+---------------------------------
+
+	The X11IRAF v2.0 system is being distributed as tarballs of either
+pure-source or prebuilt binaries.  The convention in open-source software
+is that such tarballs create the toplevel directory for the application, 
+however we require that users first create a directory for the distribution
+file since we don't want to impose a directory name that might overlap 
+existing versions.  We may reconsider this based on user suggestions, but
+users should be aware that creating the package directory is required before
+unpacking either source or binaries.
+
+Distributions are available in the following files:
+
+  Source Distribution:
+
+    http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-src.tar.gz
+
+  Pre-built Binaries:
+
+    http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.redhat.tar.gz
+    http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.macosx.tar.gz
+    http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.macintel.tar.gz
+
+Once the system is out of the Beta-test phase the version string will
+change, additional platform binaries will be added as they become
+available.  The Mac OSX binaries are suitable for Tiger or Leopard systems,
+Redhat binaries should run on most Linux systems whether based on a Redhat
+distribution or not.  See the platform-specific notes below for additional
+details.
+
+        
+1.2  Installing Pre-Built Binaries
+----------------------------------
+
+	Installing from binaries is a simple matter of finding the approp-
+riate distribution file for your platform.  Unpacking the file can be
+done using the commands (e.g.)
+
+	% mkdir /path/x11iraf		# create the X11IRAF directory
+	% cd /path/x11iraf		# go into X11IRAF directory
+
+and then unpack the tarball using a command such as 
+
+	% tar zxvf x11iraf-v2.0BETA-bin.macintel.tar.gz
+
+This will create an 'x11iraf' directory in the place you execute the
+command that contains the distribution.  
+
+Installing to the default system directories will require root permission
+and can be accomplished with the commands:
+
+	% su				# become the root user
+	# ./install			# install the files (interactive)
+or
+	% sudo ./install		# execute install as root
+	
+
+
+1.3  Building From Source
+-------------------------
+        
+	Installing from source is a simple matter downloading the
+source distribution and unpacking the file in a directory you create.
+Unpacking the file can be done using the commands (e.g.)
+
+	% mkdir /path/x11iraf		# create the X11IRAF directory
+	% cd /path/x11iraf		# go into X11IRAF directory
+
+and then unpack the tarball using a command such as 
+
+	% tar zxvf x11iraf-v2.0BETA-src.tar.gz
+
+This will create an 'x11iraf' directory in the place you execute the
+command that contains the distribution.
+
+To build and install from an unpacked source distribution:
+
+	    % mkdir /path/x11iraf	create the X11IRAF directory
+	    % cd /path/x11iraf		go into X11IRAF directory
+	    % xmkmf			build the package Makefile
+	    % make World		build binaries from sources
+
+	    % su			become the root user
+	    # ./install			install the files (interactive)
+or
+	    % sudo ./install		execute install as root
+
+Only the last two commands are required to install from an unpacked binary
+distribution.  Note that root permission is required in order to install to
+the default system locations.  The X development environment for your
+platform must be installed prior to building sources, otherwise please
+install from one of the available binary distributions.
+
+
+1.4  Comments, Suggestions and Bug Reports
+------------------------------------------
+
+	Please report any bugs, comments or suggestions to 
+
+		fitz@noao.edu
+
+Additionally, X11IRAF announcements and a user-forum is available at
+
+		http://iraf.net
+
+
+When reporting problems, please provide as much information as possible
+(e.g. platform, OS version, commands used, buttons pushed, etc) so the
+error can be reproduced.
+
+
+
+--------------------------------------------------------------------------------
+
+======================
+2.  XIMTOOL REVISIONS
+======================
+
+	The scope of this upgrade was limited entirely to supporting the
+existing X11IRAF applications and features on TrueColor visuals (so-called
+'24-bit displays').  As such, the changes to XImtool itself were relatively
+minor and mostly limited to internal changes and not user-features.
+
+	The one exception to this is the addition of a new GUI feature on
+the display window we call the 'colormap focus slider'.  This is a new GUI
+element that is used to set the size of an interactive update box on the
+display window that will be refreshed as the user slides the mouse around
+to do the contrast stretching of the image.  By default, this will be the
+entire display window (i.e. the slider is all the way to the right), but it
+can be changed to make the update window smaller to the point where when
+the slider is on the far-left a box of 128x128 (deemed to be the minimally
+useful size) is set.  Upon releasing the mouse window, the entire display
+will be updated.
+
+    [NOTE:  At present, there are known issues in the V2.0BETA version 
+	    with this box not being properly updated as a result of window
+	    resizing.  These problems will be addressed.]
+
+	On many systems, the refresh rates for contrast stretching will be
+satisfactory, however certain OS/hardware configurations exhibit problems
+resulting in poor performance.  Details (as they are known) of these
+configurations are described below, however this slider is meant as a 
+stopgap for users to change the refresh box as needed to achieve acceptable
+rates.  Even on fully-supported hardware, this box can be used to mitigate
+performance problems when using XImtool over remote X connections.
+
+	A long list of possible XImtool enhancements is prepared, however
+we are relying on the user-community to provide input in the way of
+suggestions and comments that this work is needed before deciding to allocate
+scarce resources to further development.
+
+
+2.1  XGterm Revisions
+----------------------
+
+	No changes to XGterm we made specifically during this upgrade,
+however the underlying Gterm widget changes means that IRAF tasks in the 
+XAPPHOT package of the GUIAPPS external package can now be used on 24-bit
+displays.  Because of the color changes required, some work still remains
+to fixup resource in the XAPPHOT gui itself, however for the most part it
+is now functional on 24-bit displays as well.
+
+
+--------------------------------------------------------------------------------
+
+============================
+3.  PLATFORM SUPPORT ISSUES
+============================
+
+
+3.1  Linux Systems
+------------------
+
+	In early testing, a number of issues arose that were caused in part
+by host-system graphics issues.  With TrueColor support, the interactive
+contrast stretching requires many times more screen refreshes than in the 
+8-bit version where only the colormap was updated.  As a result, even though
+the machines have become much faster, there is a greater dependence on how
+well the underlying hardware is supported by the system.  Combined with a
+general switch from the old XFree86 X11 systems to the newer (and supposedly
+better) X.org code base, we are once again faced with the issue of driver
+support under Linux systems.
+
+	Proprietary drivers such as for NVidia graphics card present a 
+challenge for Linux developers since much of the system has to be reverse-
+engineered.  NVidia itself is improving it's support for Linux but the most
+recent drivers have not yet made their way into mainstream linux
+distributions.  Likewise, there are problems with other graphics chipsets
+or specific window managers, but there are also a large number of users who
+will see no specific problems at all.
+
+	The sections below will be updated as new problems (and solutions)
+are found, and if changes can be made in the XImtool application itself they
+will be implemented.  Most commonly, any problems you experience will be 
+with the rate at which the screen refreshes in response to brightness/contrast
+scaling of the image.  Window resizing is another issue that may come up
+and will depend on the type of window manager used.  When reporting issues,
+please be as specific as possible about the hardware, window manager and 
+OS version you are using as well as steps needed to reproduce any problem.
+
+
+    
+3.1.1  Determining your Graphics Hardware
+-----------------------------------------
+
+	On many Linux systems the 'lspci' command can be used to print
+the PCI hardware of the machine.  For example
+
+    %  /sbin/lspci | grep -i VGA
+    22:06:01.0 VGA compatible controller: ATI Technologies Inc Rage XL (rev 27)
+
+indicates this machine has an ATI Rage XL graphics card.  The location of
+the command may vary but /sbin is common.
+
+	Additionally, systems such as Ubunto have control-panel applications
+that can be used to list details of machine hardware.
+
+    
+
+3.1.2  Intel Chipset Issues
+----------------------------
+
+	Intel graphics chips are common on many laptops, however the default
+'EXA' acceleration is known to be slow on systems using recent versions of
+the X.org server.  The suggested workaround is to edit your /etc/X11/xorg.conf
+file and add the following to your 'Device' section:
+
+    Option "AccelMethod"        "exa"
+    Option "MigrationHeuristic" "greedy"
+    Option "ExaNoComposite"     "false"
+
+This has been reported to improve the screen-refresh performance of a number
+of applications.
+
+	An alternative, is to change the 'AccelMethod' option to be 'xaa'
+to use a different accelerator.  The disadvantage here is that certain
+applications requiring video capability (such as Compiz-Fusion window manager
+on Ubuntu) will no longer work properly.  For older X.org systems, however,
+this may be the only option.
+
+
+
+3.1.3  NVidia Issues
+---------------------
+
+	Linux systems running the X.org server with the stock 'nv' driver
+have reported slow refresh rates when stretching the image contrast.  To
+help alleviate thi sproblem the 'colormap focus slider' on the bottom of
+the main window can be used to adjust the size of the interactive refresh
+area to tolerable rates.
+
+	A better solution is to install the latest version of the nvidia
+driver available for linux from the driver page at:
+
+		http://www.nvidia.com/object/unix.html
+
+This driver update has been reported to greatly improve the performace of
+the system and is recommended to those comfortable doing the upgrade.
+
+
+
+3.1.4  Ubuntu Issues
+---------------------
+
+	Ubuntu linux systems using the Compiz-Fusion window manager have
+reported problems with some of the static colors being rendered properly.
+At this time, there are no known workarounds while the problem is being
+investigated.
+
+
+
+3.2  Mac OSX Systems
+--------------------
+
+3.2.1  Tiger and Leopard Support
+--------------------------------
+
+	An Intel MacBook Pro running 10.4 (Tiger) was used as a primary
+development platform, however the same code base compiled under 10.4 is
+known to run on 10.5 (Leopard) systems for both Intel and PPC systems.
+
+	With 10.5, Apple switched from an XFree6-based X11 environment to
+one based on the X.org server, and the resulting problems are well documented
+on the net but pertain mainly to 8-bit application support.  As far as this
+package is concerned, the only issue appears to be one of screen-refresh 
+speeds on machines with NVidia graphics cards (e.g. 12" MacBook Pro and other
+older systems).  This is similar to speed problems seen under Linux and may
+be solved in future updates of the Apple X11 server.  For now, the workaround
+is to utilize the "colormap focus slider" described above to set an update
+box-size that gives satisfacory performance.
+
+	Other issues and solutions found with Mac systems will be documented
+here as they arise.
+
+
+3.3  Other Platforms
+--------------------
+
+	As of this release the only major system lacking support is the
+Windows platform using Cygwin, however this is planned before the final
+public release of the package.  
+
+	Issues identified with Mac version support (considering the
+upheavals in the X support under 10.5) will be addressed as they come up
+with the goal that a single binary for each CPU architecture will be all 
+that is required.  A Universal binary is being considered but was not a 
+focus of this release.
+
+
+
+--------------------------------------------------------------------------------
+
+==================================
+4.  OBM (WIDGET SERVER) REVISIONS
+==================================
+
+	The primary focus of changes in this release is to update all 
+tasks and toolkits to support 24-bit (more generically, 'TrueColor visual')
+displays.  No signbificant new features were added however many files 
+were checked and slightly modified so they would work in the new display
+environment.
+
+	
+4.1  GTerm Widget Changes
+-------------------------
+
+	The custom Gterm widget obviously underwent significant change
+during this upgrade.  To summarize the issue:  With an 8-bit PseudoColor
+display the contrast stretching is done by simply rewriting the scaled
+colormap to the display (256 elements), but with a TrueColor visual there
+is no colormap and the RGB value of *each pixel on the screen* must be
+updated and refreshed when a change is made (i.e. 512x512 pixels or more
+depending on the screen size).  Increased CPU/GPU power makes fast updates
+possible compared to 10 years ago, however much depends on the graphics
+hardware and how well it is supported by the underlying OS and the X server
+used.
+
+	Fundamentally, the Gterm widget still retains the concept of a
+colormap so that the higher-level applications which rely on it can remain
+almost completely unchanged.  The support for TrueColor displays is added
+at the lowest level of the widget that interacts directly with the X
+display.  For example, in XImtool a "frame" consists internally of a client
+XImage that holds the 8-bit display data sent by the client and is the size
+of the frame buffer.  This frame also has a 'pixmap' that is the same depth
+as the display visual (e.g. 24-bits) however it is only the size of the
+Gterm window.  It is the pixmap that is rendered to the screen and so we
+can implement 24-bit support by mapping the 8-bit XImage data to the 24-bit
+pixmap when we pan/zoom or stretch the display contrast.  Converting these
+pixels is done using the colormap still present in the widget and set by
+the user and the conversion is optimized with lookup-tables to minimize
+computation time.
+
+	The static colors in the widget are unchanged and we are able to
+fully utilize all 200+ colors available in the Gterm color model.  Vector
+graphics and "markers" in the widget were largely unchanged except for
+cases where resource colors (e.g. the vector color in a plot) needed to be
+specified explicitly.
+
+	This approach worked remarkably well in limiting the changes to the
+Gterm widget itself and requiring (relatively) little in the way of changes
+needed by applications such as XImtool or XGterm.  A number of small issues
+remain to be solved (and new ones will no-doubt be found) during the
+beta-test period, but a fully-supported and stable system is clearly within
+reach.
+
+
+4.2  Athena Widget Changes
+--------------------------
+
+	The Athena3D widget toolkit used also had problems under 24-bit
+systems, mostly related to the definition of color resources.  This toolkit
+provides the 3-D effect for common widgets such as Buttons, Menus and 
+Toggles and changes were needed to allow these widgets to be used on
+TrueColor visuals.
+
+	Other projects had encountered these same problems and patches for
+the toolkit were easily found on the web and applied.  The older version of
+the library source was retained in the distribution for reference in case
+future bugs are found.
+
+	One issue still to be investigated is the rendering of widgets on
+8-bit pseudocolor displays, which on some systems appears to lose the 3-D
+effect.  This will be resolved during the "cleanup" phase and would only
+affect a very small numbers of users.
+
+
+--------------------------------------------------------------------------------
+
+===========================================
+5.  CLIENT DISPLAY LIBRARY (CDL) REVISIONS
+===========================================
+
+
+5.1  Display Protocol Changes
+-----------------------------
+
+	The following CDL methods were modified in order to implemented the
+faster sub-raster I/O described below in section 5.1.2:
+
+        cdl_readSubRaster (cdl, lx, ly, nx, ny, &pix)
+       cdl_writeSubRaster (cdl, lx, ly, nx, ny, pix)
+
+The changes made are internal to the procedure and do not affect the
+application interface, only the behavior of the procedure.
+
+	Specfically, if the connection to the display server detects a WCS
+version greater than "10" (i.e. v1.0), then a new method for writing
+subraster data will be used that transfers data directly to the region 
+specified.  This should greatly improve the performance of applications that
+do many subraster transfers of this type and is fully backward compatible 
+to other display servers.
+
+	All that is required to use this feature is to relink the CDL
+application with the new version of the library, and to use the XImtool
+server distributed with X11iraf V2.0 or later.
+
+
+
+--------------------------------------------------------------------------------
+
+===================
+6. TECHNICAL NOTES
+===================
+
+
+6.1  IIS Protocol Changes
+-------------------------
+
+
+	The IIS protocol was modified slightly in this release in order
+to provide greatly improved performance of sub-raster read and write oper-
+ations from client applications.  The change was made to accomodate a
+Real-Time Display capability for a new IR Mosaic instrument recently
+developed in which the display is loaded simultaneously by independent
+clients responsible for different parts of the focal plane.  The change
+resulted in a 200-fold increase in speed allowing a 4k x 4k image to be
+displayed from multiple machines in under a second.
+
+	The details of this change are covered in detail in section 5.1.2
+below but will be automatic for any application linking against the new
+version of the CDL library.  In summary, earlier versions of the subraster
+display were done by reading back the entire width of the frame buffer,
+editing the affected pixels and then writing back the rows in the buffer.
+For small sub-raster this is highly inefficient but usually acceptable
+because of the small number of subraster reads/writes being done.  In this
+improved version, the pixels in the frame buffer are written directly to
+the screen, avoiding the unnecessary readback-edit-write cycle as before.
+When displaying a full image into a frame buffer approximately the same
+size as the image, the change will not be noticeable.  However, when the
+image is much smaller than the buffer, or when writing many small
+subrasters to the display (e.g tiling images or editing indivual regions),
+users should notice a considerable improvement in the speed.
+
+
+
+6.1.1  IIS Protocol Summary
+---------------------------
+
+	This section is meant to provide an up-to-date reference of the IIS
+protocol used in X11IRAF v2.0, including any changes described above or in
+following sections.  These changes are implemented in XImtool display
+server, the VXImtool virtual frame buffer, and the CDL application library
+included with this release.  Necessary changes in the current IRAF v2.14
+release are also implied.
+
+
+                 		   IIS Header Packet Summary
+
+                      TID            Subunit     Tct   X   Y    Z   T    Data
+              +------------------+-------------+-----+---+---+----+---+--------+
+Read Data     | IIS_READ|PACKED  | MEMORY      | -NB | x | y | fr |nx | nbytes |
+Write Data    | IIS_WRITE|PACKED | MEMORY      | -NB | x | y | fr |nx | nbytes |
+Read Cursor   | IIS_READ         | IMCURSOR    |  -  | - | - | wcs| - | -      |
+Write Cursor  | IIS_WRITE        | IMCURSOR    |  -  | x | y | wcs| - | -      |
+Set Frame     | IIS_WRITE        | LUT|COMMAND | -1  | - | - | -  | - | 2      |
+Erase Frame   | IIS_WRITE | fb   | FEEDBACK    |  -  | - | - | fr | - | -      |
+              |                  |             |     |   |   |    |   |        |
+Old Read WCS  | IIS_READ         | WCS         |  -  | - | - | fr | - | 320    |
+Old Write WCS | IIS_WRITE|PACKED | WCS         | -N  | - | - | fr |fb | 320    |
+              |                  |             |     |   |   |    |   |        |
+WCS Version?  | IIS_READ         | WCS         |  -  | 1 | 1 | -  | - | 320    |
+WCS by Num.?  | IIS_READ         | WCS         |  -  | 1 | - | fr |wcs| 1024   |
+New Read WCS  | IIS_READ         | WCS         |  -  | 1 | - | fr | - | 1024   |
+New Write WCS | IIS_WRITE|PACKED | WCS         | -N  | 1 | - | fr |fb | 1024   |
+              +------------------+-------------+-----+---+---+----+---+--------+
+
+
+Where   nbytes | NB  = number of bytes expected or written
+        x            = x position of operation in frame buffer coords
+        y            = y position of operation in frame buffer coords
+	nx	     = width of data to be read/written.  If zero, the width
+			of the current frame buffer is assumed.
+        fr           = frame number (passed as bitflag (i.e. 1, 2 ,4 8, etc)
+        fb           = frame buffer config number (zero indexed)
+        N            = length of WCS string
+        wcs          = WCS number (usually zero)
+        Data         = the number of bytes of data to be read or written
+			following the header packet.
+
+        IIS_WRITE    = 0400000
+        IIS_READ     = 0100000
+        COMMAND      = 0100000
+        PACKED       = 0040000
+        IMC_SAMPLE   = 0040000
+
+        MEMORY       = 001
+        LUT          = 002
+        FEEDBACK     = 005
+        IMCURSOR     = 020
+        WCS          = 021
+
+
+	    
+6.1.2  Faster Sub-Raster Writes
+-------------------------------
+
+	Sub-raster I/O is a special case of the IIS_READ and IIS_WRITE
+commands in which the caller specifies the (x,y) position of the operation
+and the number of bytes to be transferred.  Traditionally, the X position
+was always zero (indicating the starting row of the frame buffer), the Y
+position was the row to be written and the data sent represented one or
+more complete rows of the frame buffer.
+
+	In the new scheme, we take advantage of the unused 't' register in
+the IIS header packet to specify the width of the subraster.  If this value
+remains 0 (zero), we use the old behavior and assume the data are the full
+width of the frame buffer.  For values greater than zero in the 't'
+register, the value is taken to be the width of the subraster to be written
+at the given (x,y) position.  The size of the subraster is then 't' pixels
+wide by 'nbytes/t' rows high.
+
+	When using the cdl_readSubRaster() or cdl_writeSubRaster() methods
+in the CDL application library, the setting of the 't' register is handled
+automatically on behalf of the caller.  This faster display model is used
+only if the "iis_version" is greater than 10 meaning CDL applications
+should remain backward compatible with the current (as of this writing)
+DS9.
+
+
+
+-------------------------------------------------------------------------------
+    
+7. POST-RELEASE NOTES
+=====================
+
+
+11/18/08 -- Fixed a problem seen on some systems resulting in a BadAlloc
+	    error.  This was caused by the resizing of the hcut/vcut plots
+	    such that the widget sizes was being seen as 65534 or so (i.e.
+            actually negative).
+
+11/20/08 -- Trapped a bad read on the ISM socket that causes an error message
+	    to be written when you quit XImtool.  It is unclear whether 
+	    this is related to a 'memory corrupted' message sometimes seen
+	    when quitting.