# AXIS 2000 Programs

This page was created by the IDL library routine `mk_html_help`. For more information on this routine, refer to the IDL Online Help Navigator or type:

         ? mk_html_help

at the IDL command line prompt.

Last modified: Mon Dec 29 13:34:41 2008.

# List of Routines

- AA_COM.PRO
- ALIGN
- ALIGNCOM
- ALS2NCDF
- ALS_SPECIN
- ALS_SPECTRA
- ALS_SPECTRA_EVENTCB
- AXB_LOAD
- AXB_SAVE
- AXIS2000
- AXIS[1]
- AXIS[2]
- AXIS_ADD
- AXIS_APP
- AXIS_COM.PRO
- AXIS_C[1]
- AXIS_C[2]
- AXIS_DIALOG
- AXIS_INI
- AXIS_LNX
- AXIS_LOG
- AXIS_OPTIONS_EVENTCB[1]
- AXIS_OPTIONS_EVENTCB[2]
- AXIS_PEEM_EVENTCB
- AXIS_READ_IMAGE
- AXIS_START.PRO
- AXIS_START_EVENTCB
- AXIS_WEB[1]
- AXIS_WEB[2]
- AX_BIN
- AX_CGO
- AX_CIMAGE.PRO
- AX_CLEAR
- AX_COLOR
- AX_COLORBAR
- AX_CONV
- AX_CONV_TOF-ALL
- AX_COPY
- AX_CURVFIT
- AX_DELTAMIN
- AX_FILE_LOAD
- AX_FIX_ROLLOVER
- AX_GEN_STACK
- AX_HISTOGRAM
- AX_IMAGE_ADD
- AX_IMAGE_APPEND
- AX_IMG_AVG
- AX_IMG_DEL
- AX_IMG_LINE
- AX_IMSCL
- AX_INTERP
- AX_LOAD_LOGO
- AX_LOX
- AX_MACRO
- AX_MESH
- AX_NAME
- AX_NC2GIF
- AX_ONE_PT
- AX_ORDER
- AX_PARTICLES
- AX_PAR_LOAD
- AX_PAR_SAVE
- AX_PC
- AX_PEEM_COM.PRO
- AX_PEEM_READ
- AX_POL_FIT[1]
- AX_POL_FIT[2]
- AX_POL_FIT[3]
- AX_POL_MAP[1]
- AX_POL_MAP[2]
- AX_PROF_RAD
- AX_RD_IM
- AX_READ_ROI
- AX_READ_XAS
- AX_REGRESS_SPECTRA
- AX_RGB
- AX_RGB_COM
- AX_RGB_MAP
- AX_RGB_WIDGET
- AX_ROTATE
- AX_SDF
- AX_SDF_EARLY
- AX_SDF_EVENTCB
- AX_SELECT
- AX_SELECT_COM
- AX_SEP
- AX_SHIFT_ALL
- AX_SHIFT_IMAGES
- AX_SLICER3
- AX_SORT_MONO
- AX_SORT_NAMES
- AX_SPEC_DELETE
- AX_STXM4NC
- AX_SVD
- AX_SVD_SPECTRA
- AX_SWITCH
- AX_TOMO_READ
- AX_WAIT
- AX_WRITE_XAS
- AX_XYCAL
- AX_XYDIS
- AX_XYSCL
- AX_ZOOM_CURSOR
- AX_ZOOM_CUT
- AX_ZOOM_PAN
- BMP_TO_NCB[1]
- BMP_TO_NCB[2]
- BNL_LOAD
- BOX
- BOX_CURSOR
- BSIF_COMMON.PRO
- BUFFER
- BX_CURSOR
- CAPERS-SCALE
- CG_OPTIMIZE
- CHKFILEBLOCKS.PRO
- CIMAGE.PRO
- CINDEX[1]
- CINDEX[2]
- CLEAN
- CLIP
- COLORBAR
- COPY_BYTES.PRO
- CRYO_TO_STXM
- CW_RSLIDER
- DEGLITCH
- DINDEX
- DISP3COL
- DISTANCE
- EDGEGAUSS
- ENERGY_SORT
- FILE.PRO
- FILE2STRING
- FILENAME_IN_CAPITALS[1]
- FILENAME_IN_CAPITALS[2]
- FILE_OVERWRITE
- GEN_AA_STRING
- GEN_READ
- GET_NUM
- GET_PATH.PRO
- GET_TEXT
- IDL_STARTUP
- IMG_ALIGN
- IMG_ASAV
- IMG_COM.PRO
- IMG_LOAD
- IMG_WARP
- INTERP.PRO[1]
- INTERP.PRO[2]
- IRMAP_LOAD
- JOIN_STRING
- LINE_FIT
- LITHO_READ
- LITHO_SAVE
- LN_ADD
- LN_ALIGN
- LN_LOAD
- LN_LOCAT.PRO
- LN_NORM
- LN_SUBSP
- LOADSPEM
- LOAD_NEX
- LOOK[1]
- LOOK[2]
- LOX_COM.PRO
- MAKE_SQUARE
- MATH.PRO
- MBUF
- MISC
- NCB_TO_MPG
- NCDF2ALS
- PARSE_SDF
- PEM_LOAD
- PICKFILE2
- PLOT2D
- PLOT3D.PRO
- PLOTBUF
- PLOTSECT
- PRINT
- PRINT-EK
- RANDOMFILE
- RD_PEEM[1]
- RD_PEEM[2]
- RD_SPEM.PRO
- READSTRBIG
- READWIN
- READ_ALL
- READ_ALS
- READ_AXM
- READ_A_N
- READ_BESSY_STACK.PRO
- READ_BESSY_STXM.PRO
- READ_BESSY_XML.PRO
- READ_BL5
- READ_BNL
- READ_BSP
- READ_CRYO
- READ_CSV
- READ_FILEINFO_P3B
- READ_LOX
- READ_LOX_SPECTRA
- READ_MAPPER[1]
- READ_MAPPER[2]
- READ_MRC_FILE
- READ_P3B
- READ_P3B_SPECTRUM
- READ_PEEM3
- READ_SDF
- READ_SDF-INT
- READ_SDF-INT1
- READ_SDFE
- READ_STXM
- READ_STXM4
- READ_TAGS
- READ_TOMO
- READ_UVIEW
- READ_XAS
- REFRESH
- REGION_ANALYZE
- REMOVE_ZEROS.PRO
- RESETPLOTS
- SAV_ALS
- SAV_HDF
- SAV_HDFM
- SAV_NSLS.PRO
- SDF_COM.PRO
- SF[1]
- SF[2]
- SM_IPAR
- SPC_LOAD
- SPC_SAVE
- SPECTRA
- SPLIT_STRING
- SPLOT
- SPLOT2D
- SPLOT3D
- SPLOTA
- SROTATE
- STACK_ADD
- STACK_ALIGN
- STACK_ANALYZE.PRO[1]
- STACK_ANALYZE.PRO[2]
- STACK_APPEND
- STACK_BUILDLIST
- STACK_FIT
- STACK_MAKE
- STACK_PROCESS.PRO[1]
- STACK_PROCESS.PRO[2]
- STACK_PROCESS_COM
- STACK_RB
- STACK_READLIST
- STACK_WB
- STAG
- STRING2FILE
- STRUCTURE
- STR_COLUMNS
- STXM4_NCB
- SXM_ACOMMON
- SXM_COMMON
- SXM_FILEEXISTS
- SXM_IPAR
- SXM_READFILE
- SXM_STRCLEAN
- TEXT_READ.PRO
- TEXT_READ1.PRO
- THUMBLBLS
- THUMBZOOM
- TIF2NCDF
- TIFRD_IM
- TIFRD_IM-TEST
- TIF_CONVERT
- TIF_CONVERT_COM.PRO
- TIF_LOAD
- TVIMAGE
- WIN2LPR
- WIN2LPR-APH
- WIN2LPR-SGU
- WIN2TIF
- WIN2TIFF
- WRITE_MRC_FILE
- WRITE_NCDF
- WRITE_P3B
- WRITE_SDF
- WRITE_STXM
- WRITE_TAGS
- WRITE_XAS[1]
- WRITE_XAS[2]
- WVLEN2EN, EN2WVLEN[1]
- WVLEN2EN, EN2WVLEN[2]
- WVLEN2EN, EN2WVLEN[3]
- XAS1
- XAS2
- XM1_LOAD
- XMLOAD
- ZIMBA_RUN
- ZSTACK_ALIGN.PRO
- ZSTACK_COLOR.PRO
- ZSTACK_COLOR_COMMON
- ZSTACK_COMMON
- ZSTACK_DISPLAY_COMMON
- ZSTACK_PLOT.PRO
- ZSTACK_SAVE.PRO
- ZSTACK_SPECTRA.PRO
- ZSTACK_TUNE.PRO

# Routine Descriptions

## AA_COM.PRO

[Next Routine] [List of Routines]

    NAME:
    		AA_COM.PRO

    LAST CHANGED: -----------------------------------  09-Mar-07

     PURPOSE: Common Blocks For AA Program

     CATEGORY:
    	Data manipulation. Called from aXis2000 as a sav file,

     CALLING SEQUENCE:  not applicable

     MODIFICATION HISTORY:
     (03-jan-07 jso) last version supplied
     (09-mar-07 aph) AXIS standard header added

(See c:\axis2000\aa_com.pro)

## ALIGN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	ALIGN

    LAST CHANGED: ----------------------------------- 31-dec-99

     PURPOSE:
    	This procedure is the image alignment part of STACK_ANALYZE.
     It uses 2d fourier transform correlation techniques
     to shift one image to the same pixel scale as a reference image.
     Numerous options to control the alignment procedure are provided

     CATEGORY:
    	AXIS: stack analysis

     CALLING SEQUENCE:
     align,image1,image2,xshift,yshift,image2_shifted,$
        [ sobel=sobel,roberts=roberts,edgegauss=edgegauss,$
        cm=cm,maxshift=maxshift,$
        meanfill=meanfill,medianfill=medianfill,$
        xcorimg_win=xcorimg_win,xcorimg_zoom=xcorimg_zoom,$
        xplot_win=xplot_win,yplot_win=yplot_win,$
        debug=debug,help=help ]

     INPUTS:
    	IMAGE1  - reference image
    	IMAGE2  - image to be shifted to reference image

     KEYWORDS:
    	SOBEL	- use sobel edge sharpening
    	ROBERTS	- use roberts edge sharpening
    	EDGEGAUSS = # - sigma value for gaussian edge sharpening (default = 4)
    	CM	- align on centre-of-mass of correlation FFT (default = peak)
    	MAXSHIFT - maximum number of pixels to shift
    	MEANFILL - use mean for image pixels not in shifted image
    	MEDIANFILL - use median for image pixels not in shifted image
    			(default is to leave those pixels as zero)
    	XCORING_WIN - number of window to display correlation image
    	XCORIMG_ZOOM - zoom factor for alignment images
    	XPLOT_WIN - number of window to display x-shifts
    	YPLOT_WIN - number of window to display y-shifts
    	DEBUG - debug code implemented
    	HELP - display help message

     OUTPUTS:
    	XSHIFT 	- value of x-shift (in fractional pixels)
    	YSHIFT - value of y-shift (in fractional pixels)
    	IMAGE2_SHIFTED - shifted second image

     COMMON BLOCKS:
       none

     EXAMPLE:
    	Call from stack_align.pro :
                align,ref_image,this_image,this_x_shift,this_y_shift,$
                  shifted_image, sobel = sobel, roberts=roberts, $
                  maxshift=maxshift, /meanfill, $
                  xcorimg_win = stack_align_par.diff_image_win, $
                  xcorimg_zoom = img_zoom

     CAUTIONS
    	Image alignment will often fail in cases of ambigous or low contrast

     MODIFICATION HISTORY:
     (25-mar-1998 cjj) modified to deal with 24 bit color
       If you provide the white, red, and green colors, then
       it is assumed that the color table is preloaded.
       "white" is an index for a color table from 0 to 255,
       whereas "red" and "green" are plot color indices
       which might be longs on 24 bit graphics devices.  CJJ
     (11-jul-98 cjj) Significantly modified
     Eliminated the correl option, and made /peak the default (i.e., you
     cannot specify it anymore).  Fit the three pixels about the
     peak to z=a+bx*cx^2 and z=a+by+cy^2 for subpixel location
     (30-dec-99 aph) documented as part of AXIS

(See c:\axis2000\align.pro)

## ALIGNCOM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	ALIGNCOM

    LAST CHANGED: ----------------------------------- 31-dec-99

     PURPOSE:
    	This FILE contains the COMMON block, stack_aligncom

     CATEGORY:
    	AXIS: Stack_analyze common block

     CALLING SEQUENCE:
    	@aligncom (to include in the stack_analyse routines)

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (23-Jan-98 version) CJJ written
     (30-dec-99 aph) added documentation

(See c:\axis2000\aligncom.pro)

## ALS2NCDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	ALS2NCDF

    LAST CHANGED: ----------------------------------- 27-feb-00

     PURPOSE:
    	This procedure converts one or a series of ALS image files
     into netCDF format and, if multiple files, writes a stack_list (*.sl) file
     with names of converted files

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	ALS2NCDF, file

     INPUTS:
    	FILE - an ALS image file (*.im%) to be converted to netCDF format (*.nc)

     KEYWORD PARAMETERS:
    	LIST - name of file with list of image files (*.lst)
    	BIN - average by combining 2x2 pixels (bin=2) or 3x3 pixels (bin=3), etc
       OUTLIST - name of a file to write list of netCDF files (*.sl)
       DELE - delta_E is a photon energy shift (real - measured) (eV)
    	ONE - convert only a single file

     OUTPUTS:
      FILE.NC - image written to a netCDF format binary file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS
       @BSIF_COM - common block for netCDF

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     PROCEDURE:
    	ALS2NCDF assumes that ax_rd_im has put the image and associated information
     into BSIF_COMMON variables:
    	image_data (the array which holds the image - possibly several
    	planes deep for I, IO, CLOCK)

     EXAMPLE:
    	ALS2NCDF is used from AXIS by supplying user-defined keywords

      fileget=PICKFILE2(/Read, FILTER='*.lst', /LPATH, DEFPATH=defpath)
      if strlen(fileget) GT 0 THEN BEGIN
      		WIDGET_CONTROL, Uprompt, SET_VALUE= 'ALS->nc: smooth by binning?'
    		bin_num=1				; optional binning of data
    		bin_num=get_num(Val=bin_num,PROMPT='bin *', group=axis_ID)
    		WIDGET_CONTROL, Uprompt, Bad_ID = badID, SET_VALUE= 'ALS->nc: calibrate E?'
    		del_E=0.
    		del_E = get_num(Val=del_E,PROMPT='dE(real-meas, eV)', group=axis_ID)
    		sl_file = get_text(Prompt = 'stack_list file',val = sl_file, group=axis_ID)
    	    ALS2NCDF,list=fileget,bin=bin_num, outlist=sl_file, delE=del_E
      endif

     MODIFICATION HISTORY:
     (xx-mar-98 aph) developed to support stacks at ALS
     (14-jun-98 aph) axis_com, bsif_com (for Linux idl 5.03)
     ( 2-aug-98 aph) define extension which is the image (switches !)
     (16-aug-98 aph) allow use of *.lst files generated by ALS stxm.vi
     (20-nov-98 aph) get rid of IDL command window prompt
     ( 7-jan-99 aph) sorting out problem with multi-file processing (stalls)
     (12-jan-99 aph) adapt to find data files when using ALS *.lst paths are wrong
     (14-apr-99 aph) DataPath default to Defath
     (13-May-99 aph) conditional plotting at end if 1 file
     ( 6-jul-99 aph) free_lun NOT just close !
     (11-aug-99 aph) fix up path issues;
     (05-sep-99 aph) write to real netcdf
     (19-sep-99 aph) write outlist file in ZIMBA format
     (15-oct-99 aph) correct path information at top oz Zimba format
     (30-dec-99 aph) AXIS standard documentation; add ONE keyword
     (27-feb-00 aph) groupID added to get_text
     (18-jul-01 aph) fixe error in optional /one and /list options

(See c:\axis2000\als2ncdf.pro)

## ALS_SPECIN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	ALS_SPECIN

    LAST CHANGED: ----------------------------------- 19-mar-02

     PURPOSE:
    	This function reads in an ALS BL7.0 stxm spectral data file
    	based on parameters generated by the ALS_SPECTRA widget

     CATEGORY:
    	AXIS: spectra analysis

     CALLING SEQUENCE:
    	Result =  ALS_SPECIN(in_file, REF=ref, COL=col, _extra=e)

     INPUTS:
    	IN_FILE  - name of ALS BL 7.0 STXM data file (transmission or yield signal)

     KEYWORDS:
    	REF - switch to indicate this is incident flux reference
    	COL=# - data column to read in
    	_EXTRA_E - in case one wants to pass plot paramaters

     OUTPUTS:
    	Result is an AXIS 1d data structure.
     The y data values are calculated according to the readin parameters

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    ;
     PROCEDURE:
     uses current values of I_process, Io_process to determine what to do
     set KEYWORD REF to 1 to use Io_process
     I_process =
     'all'  - return both dark and data values
     'none' - ignore dark counts
     'dark' - average dark, subtract
     'OSA'  - ratio signal to OSA (without dark correction)
     'both' -  ratio signal to OSA (with dark correction of each)

     -------- internal parameter, OPT, used to control processing -------
    default (no opt) is to read in E,col1,col2
     OPT = col1:   raw data - ASSUMES transmission detector in col(1); OSA in col(2)
     OPT = col2:  extract col(2)  - OSA (pre-98) or trans (after Dec-97; flipped here)
     OPT = col3;  extract col(3)  - TEY
     OPT = dark:  dark correct signals
     OPT = OSA;   divide by OSA signal (no dark correct)
     OPT = OSA-dark; dark correct, then divide by OSA signal

     ALS BL7.0 point spectra consist of ascii files (*.dat, *.xas)
     ------ FORMAT of *.DAT file (scan details)
    10	5	50000	100000		(#dark points) (#sections) (shutter delay - us) (dwell/dark - us)
    2.7500E+2	2.0000E-1	40	100000 Region 1:(first-E in eV) (step in eV) (number) (dwell)
    2.8300E+2	7.9710E-2	138	100000 Region 2:
    2.9400E+2	1.2000E-1	50	100000 Region 3:
    3.0000E+2	2.0000E-1	75	100000 Region 4:
    3.1500E+2	2.5000E-1	60	100000 Region 5:
     ------ FORMAT of *.xas file
    273.000	36	16
    273.200	37	17		dark signal levels before scan
     .....
    275.000	16774	51465	E, signal_1, signal_2 (as many defined in acquire)
    275.200	16820	52070
    275.400	16824	52848
     .....
    330.200	36	16
    330.400	37	17		dark signal levels after scan
     .....

     CAUTIONS
     the data format was modified several times in 1997
     this routine attempts to auto-detect the format of the file
    	but some errors do occur

     MODIFICATION HISTORY:
     (09-Dec-97 aph) multi-section files; single file to do all types of read-in of ALS STXM spectral files
     (15-feb-98 aph) cancel protect; read 0 dark_pt  files
     (04-mar-98 aph) still problems with 0 dark pts;
     (09-apr-98 aph) save img_shifts; correct spike; add col(3) = TEY
     (07-aug-98 aph) indicate extension (? not done since col indicated already)
     (02-jan-99 aph) derived from XAS1.pro
     (03-jan-99 aph) add ytitle (s.yl)
     (28-jan-99 aph) xlabel consistent with nsls readin; DefPath in pickfile2
     (18-sep-99 aph) correct to allow read-in with no dark points
     (30-dec-99 aph) AXIS standard documentation
     (19-mar-02 aph) adapt to new stxm701 which dies not use OSA (only 2 cols)

(See c:\axis2000\als_specin.pro)

## ALS_SPECTRA

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     ALS_SPECTRA

    LAST CHANGED: ----------------------------------- 31-dec-99

     PURPOSE:
    	These procedures generate a widget used to read in ALS BL 7.0 STXM
     spectral data.

     CATEGORY:
    	AXIS: spectra analysis

     CALLING SEQUENCE:
    	als_spectra [, GROUP_LEADER=wGroup, _EXTRA=_VWBExtra_ ]

     ROUTINES:
    	BSE_ALS_SPECTRA_event, Event - processes the events generated by user
                                using the ALS_SPECTRA_EVENTCB routines
    	BSE_ALS_SPECTRA, GROUP_LEADER=wGroup, _EXTRA=_VWBExtra_ - generates widget structure
    	ALS_SPECTRA - stub for loading

     INPUTS:
    	none

     KEYWORDS:
    	GROUP_LEADER: ID of calling widget

     OUTPUTS:
    	read in of data occurs when the 'GO' button is pushed
    	code for read-in is in ALS_SPECTRA_EVENTCB callback processing

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     Generated on:	01/08/99 12:58.18
     (30-dec-99 aph) AXIS standard documentation

(See c:\axis2000\als_spectra.pro)

## ALS_SPECTRA_EVENTCB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	ALS_SPECTRA_EVENTCB

    LAST CHANGED: ----------------------------------- 31-dec-99

    PURPOSE:
    	This IDL Event Callback procedure processes the events generated
    	by the buttons in the >READ>ALS-STXM spectral input command of AXIS

    CATEGORY:
    	AXIS spectra analysis
    	IDL Event Callback Procedure for als_spectra_eventcb

    ROUTINES:
    	ALS_Spectra_Update - indicate current values of read-in parameters
    	BUT_I_all		BUT_I_none		BUT_I_dark		BUT_I_OSA		BUT_I_both
    	BUT_Io_all		BUT_Io_none		BUT_Io_dark		BUT_Io_OSA		BUT_Io_both
    	TXT_I_check		TXT_I_col		BUT_I_Browse
    	TXT_Io_check	TXT_Io_col		BUT_Io_Browse
    	Scan_Par_Update
    	BUT_Load_Sample
    	BUT_Load_ratio
    	BUT_Load_Absorption
    	BUT_Load_Data
    	BUT_Cancel
    	ALS_SPEC_EVENTCB - stub routine to load all the rest

    INPUTS: none

    KEYWORDS: none

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    RESTRICTIONS:
     Whenever re-generate ALS_Spectra, add the following to pro BSE_ALS_SPECTRA,:
     to ADD an explicit Font command to handle different
     choices of Font Size at Windows level
      @axis_com
      WIDGET_CONTROL, Default_Font = BufLblFont

     NB -- Remove the All_Events keyword from the creation
           of the TXT_I_check and TXT_Io_check text widgets in ALS_Spectra,pro
    		to trigger events only on newlines.
     END OF STUFF to add to pro BSE_ALS_SPECTRA, GROUP_LEADER=wGroup, _EXTRA=_VWBExtra_

    MODIFICATIONS
     First generated on:	01/01/99 16:14.31
     (03-jan-99 aph) add ytitle (sample.yl) to returned Data
     (08-jan-99 aph) change display of parameters to table widget to get round overlap crash
     (11-jan-99 aph) error recovery if request reference with no file defined
     (28-jan-99 aph) DefPath for path and get_path
     (25-jun-99 aph) remove ambiguity of Scan_par_Update (function) & ScanPar_Update (paramater)
     (04-jul-99 aph) correct error in last procedure !
     (10-sep-99 aph) correct error in interpolation
     (30-dec-99 aph) add AXIS documentation

(See c:\axis2000\als_spectra.pro)

## AXB_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXB_LOAD

    LAST CHANGED: ----------------------------------- 14-Jul-07 (aph)

    PURPOSE:
    	This function reads in AXIS format image or spectra from
     the XDR transferrable binary format. (Files written using AXB_SAVE).

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = AXB_LOAD([ NOF=nof, error=err, file=file, _extra=e])

    CALLED FROM AXIS:
    	Read->Images->AXIS (and in many analysis routines)

    INPUTS: none. All input parameters are passed as keywords.

    KEYWORDS:
    	/NOF 	- no filter (default filter = '*.axb')
    	FILE 	- filename to read
    	/SILENT - do not display feedback on progress
    	_EXTRA 	- passed on parameters

    OUTPUTS:
    	RESULT = AXIS 1d or 2d structure

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	AXB_LOAD uses the XDR external, machine-independent binary representation.
     Please see the IDL manual (help under 'XDR') for details.
     AXB_LOAD uses information on the first line to determine the structure type.

    EXAMPLE:
     Create a sample nxn image, write as binary using AXB_SAVE, read using AXB_LOAD
    	n = 100 & t = findgen(n) & d = dist(n)
    	a = {t:'2d', x:t, y:t, xl:'x (um)    E = 288.601 eV     dwell =  0.20 ms', yl:'y', d: d, dl:'test'}
    	t = AXB_SAVE(a)
    	b = AXB_LOAD(file = t)
    	splot2d, b

    MODIFICATION HISTORY:
     (09-aug-97 aph) isolated from AXIS
     (21-jan-98 aph) added s.dn component to 1d structure to be axis-compatible
     (18-jan-99 aph) allow silent readins if provide filename by keyword
     (08-aug-99 aph) image information printed
     (17-oct-99 aph) save energy & dwell in sd.wavelength, sd.dwell  so nsls write works !
     (02-jan-00 aph) AXIS standard documentation
     (26-sep-00 aph) store energy explcitly in 2d structure
     (13-Nov-05 aph) use axis_log for feedback
     (14-jul-07 aph) add /silent keyword

(See c:\axis2000\axb_load.pro)

## AXB_SAVE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXB_SAVE

    LAST CHANGED: ----------------------------------- 29-dec-07

    PURPOSE:
    	This function writes an AXIS format image or spectrum to the XDR
     transferrable binary format.These files can be read using AXB_LOAD.

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = AXB_SAVE(tmp [, NOF=nof, file=file, noLbl = noLbl, silent=silent])

    CALLED FROM AXIS:
    	Read->Images->AXIS

    INPUTS:
    	TMP - AXIS 1d or 2d structure

    KEYWORDS:
    	/NOF - no filter (default filter = '*.axb')
    	NOLBL - if set, do not query for label
    	FILE - filename to read
    	SILENT  flag to control entry to axis log

    OUTPUTS:
    	RESULT = filename (a blank string if the user cancels)

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	uses the XDR external, machine-independent binary representation.
     Please see the IDL manual (help under 'XDR') for details.
     If the filename is not supplied via the FILE keyword, the
     user is prompted for the filename using the pick file dialog.
     If the filename is supplied, a check for overwriting is made unless
     the global flag, overwrite_all is set to 1

    EXAMPLE:
     Create a sample nxn image, write as binary using AXB_SAVE, read using AXB_LOAD
    	n = 100 & t = findgen(n) & d = dist(n)
    	a = {t:'2d', x:t, y:t, xl:'x (um)    E = 288.601 eV     dwell =  0.20 ms', yl:'y', d: d, dl:'test'}
    	t = AXB_SAVE(a)
    	b = AXB_LOAD(file = t)
    	splot2d, b

    ;MODIFICATION HISTORY:
     (  fall-97 aph) first made
     (14-jun-98 aph) axis_com
     (18-jan-99 aph) keyword to allow silent writes (no file dialog)
     ( 8-jul-99 aph) FREE_LUN not just close
     ( 8-sep-99 aph) update label
     (02-jan-00 aph) AXIS standard documentation
     (09-jan-00 aph) add hourglass for long writes
     (27-feb-00 aph) add groupID to get_text
     (06-may-01 aph) remove groupID call if not running axis
     (04-jun-03 aph) add keyword to force label to current value
     (15-Jan-07 aph) add keyword silent
     (29-dec-07 aph) remove path info from log

(See c:\axis2000\axb_save.pro)

## AXIS2000

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS2000

    LAST CHANGED: -----------------------------------  20-Apr-08 (aph)

    PURPOSE:
    	This procedure compiles all files used by the AXIS widget.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:  AXIS2000, directory=directory, start_file='*.ini', , help=help, /dialog

    INPUTS: none

    KEYWORDS:
    	directory	code directory
    	start_file	name of *.ini file
    	dialog		use a pick file dialog to select code directory and start file
    	spin		activate spinning logo
    	help		print a help text

    OUTPUTS: starts execution of AXIS

    COMMON BLOCKS: axis_com

     PROCEDURE

    MODIFICATION HISTORY:
     (08-dec-00 cgz) first written
     (23-jan-01 cgz) Added initial specification of ini_file if start_file is not specified
     (23-jan-01 cgz) Added /help option to give help message
     (31-jan-01 aph) get so that will auto-run on PC from start_file call (redo of 12-jan-01 changes)
     (22-aug-01 aph) add spin keyword
     (28-jul-02 aph) set directory to 'CodePath' (from axis.ini file), if not defined in call
     (20-Apr-08 aph) explicitly force CodePath to 'c:\axis2000' if not exist

(See c:\axis2000\axis2000.pro)

## AXIS[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS

    LAST CHANGED: -----------------------------------  30-nov-00

    PURPOSE:
    	This procedure compiles all files used by the AXIS widget.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:  @axis (at the IDL prompt)

    INPUTS: none

    KEYWORDS: none

    OUTPUTS: starts execution of AXIS

    COMMON BLOCKS: none

     PROCEDURE
    	The AXIS batch file is used to start AXIS in order to
     ensure the  subdirectory from which AXIS is being run
     contains a complete set of pro files. In principle the IDL auto load
     or the RESOLVE_ALL routine could be used to achieve this.
     However, a number of the utility and event call back pro files
     contain multiple routines that are not visible to RESOLVE_ALL.
     The working AXIS code directory can be set from the Utilities->Set preferences
     command in AXIS. The default is C:\axis on WIN machines.
     IDL library files are loaded as needed

    MODIFICATION HISTORY:
     (02-jan-00 aph) AXIS standard documentation. See file for more

(See c:\axis2000\axis.pro)

## AXIS[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS

    LAST CHANGED: -----------------------------------  29-jun-00

    PURPOSE:
    	This procedure compiles all files used by the AXIS widget.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:  @axis (at the IDL prompt)

    INPUTS: none

    KEYWORDS: none

    OUTPUTS: starts execution of AXIS

    COMMON BLOCKS: none

     PROCEDURE
    	The AXIS batch file is used to start AXIS in order to
     ensure the  subdirectory from which AXIS is being run
     contains a complete set of pro files. In principle the IDL auto load
     or the RESOLVE_ALL routine could be used to achieve this.
     However, a number of the utility and event call back pro files
     contain multiple routines that are not visible to RESOLVE_ALL.
     The working AXIS code directory can be set from the Utilities->Set preferences
     command in AXIS. The default is C:\axis on WIN machines.
     IDL library files are loaded as needed

    MODIFICATION HISTORY:
     (02-jan-00 aph) AXIS standard documentation. See file for more

(See c:\axis2000\axis_sub.pro)

## AXIS_ADD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_ADD

    LAST CHANGED: ----------------------------------- 21-apr-05

    PURPOSE:
    	This procedure interpolates then sums the y-values over the
     common x-axis range of two 1-d structures (spectra) in AXIS

    CATEGORY:
    	AXIS: spectra analysis

    CALLING SEQUENCE:
    	AXIS_ADD

    CALLED FROM AXIS:
    	Spectra->Add->Buffers

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	The sum of the spectra is placed in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	The user is prompted for a scale factor for first file,
     the buffer of the second file, and a scale factor for the second file.

    MODIFICATION HISTORY:
     (09-aug-97 aph) split out from axis_c
     (29-dec-97 aph) remembers numerical factors
     (14-jun-98 aph) axis_com
     (13-dec-98 aph) allow for cancel when choosing 2nd buffer
     (08-jun-99 aph) add group call to get_num
     (30-dec-99 aph) use AX_MESH to interpolate
     (23-feb-99 aph) add groupID to buffer call
     (02-jan-00 aph) AXIS standard documentation
     (21-apr-05 aph) use FIRST keyword for axis_mesh to force E-scale to that of first file
                     when interpolating spectra

(See c:\axis2000\axis_add.pro)

## AXIS_APP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_APP

    LAST CHANGED: ----------------------------------- 23-feb-00

    PURPOSE:
    	This procedure appends two 1-d AXIS data structures (spectra).
     If the data overlaps the user is prompted to select inclusion
     of the first, second or average data in the overlapping region.

    CATEGORY:
    	AXIS: spectra analysis

    CALLING SEQUENCE:
    	AXIS_APP

    CALLED FROM AXIS:
    	Spectra->Add->Append

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	The appended spectrum is placed in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (09-aug-97 aph) isolated from AXIS
     (24-jan-98 aph) corrrected to add s.dn
     (14-jun-98 aph) axis_com
     (02-jan-00 aph) 1st, 2nd, average in common region; AXIS standard documentation
     (23-feb-00 aph) add groupID to call to Buffer

(See c:\axis2000\axis_app.pro)

## AXIS_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_COM.PRO

    LAST CHANGED: ----------------------------------- 18-Sep-08

    PURPOSE:
    	This INCLUDE file contains COMMON blocks for AXIS.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE: @axis_com

     NAMES AND MEANING OF COMMON VARIABLES
     *************************************************************************
     ***********         AXIS COMMON PARAMETERS             ******************
     *************************************************************************

     CAUTION - if you use one of these variable names in a subroutine for
     a different purpose and have included @axis_com, this can be a source
     of hard to trace errors in other routines. A common cuplrit is DATA.

    COMMON aDRAWID,    Axis_ID, MainWid, MainImg, XZPlot, YZPlot, Thumbnails, AxSpin
    	Axis_ID		ID of AXIS widget base
    	MainWid		graphics window # of draw window (not same as Widget ID !!)
    	MainImg		ID of MainImg draw window
    	XZPlot		graphics window #  of XZ line-out draw window
    	YZPlot		graphics window #  of XZ line-out draw window
       ColorbarPlot graphics window #  of colorbar draw window
    	Thumbnails	graphics window #  of Thumbnails draw window
    	AxSpin		= 1 if using spinning globe logo; = 0 if single image
    COMMON aBUF, CurBuf, Data, pData, pNum, pBufs, BufStat, ButIDs, BufButs, OptButs
    	CurBuf		number of current buffer (0-12; only 0-9 directly displayable)
    	Data		pointers to the data structures
    	pData		pointers to spectra components for overplotting
    	pNum		number of plots in temporary storage for overplotting
    	pBufs		original buffers of overplot files (order scrambled by user sleection in overplotting)
    	BufStat		status of displayed buffers (multiple buffer display in overplot)
    	ButIDs		ID values of the buffer labels
    	BufButs		ID values of the buffer selection boxes
    	OptButs		ID values of the option buttons
    COMMON BufScal,    Xscl,Yscl, Zscl,  Xmin, Xmax, Ymin, Ymax, Zmin, Zmax, G_slider
    	Xscl		Array of (xmin, xmax) for all 10 buffers
    	Yscl		Array of (ymin, ymax) for all 10 buffers
    	Zscl		Array of (zmin, zmax) for all 10 buffers
    	Xmin		Widget ID for Text box with user selectable Xmin (15-Nov-99)
    	Xmax		Widget ID for Text box with user selectable Xmax (15-Nov-99)
    	Ymin		Widget ID for Text box with user selectable Ymin (15-Nov-99)
    	Ymax		Widget ID for Text box with user selectable Ymax (15-Nov-99)
    	Zmin		Widget ID for Text box with user selectable Zmin (20-Dec-98)
    	Zmax		Widget ID for Text box with user selectable Zmax (20-Dec-98)
    	G_slider	Widget ID for gamma slider control (16-nov-99)
    COMMON aPATHS,  DefPath, WritePath, ini_file, codepath, last_image_ext,location
    	DefPath		path for READING datafiles
    	WritePath	path for Writing data files
    	ini_file	name of program paramaters
    	codepath	path to code files
       last_image_ext  extension (data type) of last image read by axis (default *.im1)
    	location	physical location (used as switch for some spcific cases)
    COMMON aPRINT,  gr_dev, gr_scale, Print_dev, Pr_Command, print_file
    	gr_dev		IDL device for screen display ('WIN', 'X')
    	gr_scale	graphics scal factor (0.5 to 2.0)
    	Print_dev	IDL device for printing ('PS'=postscript, 'PCL'=HP PCL language)
    	Pr_Command	command to transfer file to printer   (11-May-99)
    	print_file	name of print file
    	Help_cmd	command to load acrobat file (axis.pdf)  (24-may-99)
       Net_command command to start web browser (31-jan-00)
    COMMON aCURS1,	CursorX, CursorY, CursorZ, PixelX, PixelY, xline, yline, Xval, Yval, Zval
    	CursorX		widget ID for x value display
    	CursorY		widget ID for y value display
    	CursorZ		widget ID for z value display
    	PixelX		widget ID of x pixel value display
    	PixelY		widget ID of y pixel value display
    	xline		[x1, x2] data values for user selected line
    	yline		[y1, y2] data values for user selected line
    	Xval		x value of cursor
    	Yval		y value of cursor
    	Zval		z value of cursor
    COMMON aCURS2,	GraphFrozen, CurFroz, CurX, CurY, Xrng, Yrng, Zrng
    	GraphFrozen	switch indicating MainImg cursor nor active (NO LONGER USED)
    	CurFroz		[x,y] values where MainImg cursor is frozen
    	CurX		x-cursor index (device)
    	CurY		y-cursor index (device)
    	Xrng		[Xmin, Xmax] graph limits (data units)
    	Yrng		[Ymin, Ymax] graph limits (data units)
    	Zrng		[Zmin, Zmax] graph limits (data units)
    COMMON aCURS3,
    	Xold		previous X-cursor value (for del-X computation)
    	Yold		previous Y-cursor value (for del-Y computation)
    	MainCurCol	color of cursor (NOT USED ??)
    	First_Plot	flag to indicate whether ax_color should be called
    	Last_Img	flag indicating last display on MainGraf was image (NOT USED ??)
    COMMON aCURS4,	delX, delY, delR, delZ, DXval, DYval, DRval, DZval, click1
    	delX		widget ID for delta-x value display
    	delY		widget ID for delta-y value display
    	delR		widget ID for delta-R value display (distance between points)
    	delZ		widget ID for delta-z value display (image intensity)
    	DXval		delta-x value
    	DYval		delta-y value
    	DRval		delta-R value
    	DZval		delta-z value
    	click1		0 - cursor free; 1 - first point selected; 2 - second point selected
    COMMON aprompt,
    	Uprompt		index for AXIS communication text window
    	version		version identifier (# (date))  					(10-may-98)
       profl		profl=1 - extract profile                       (11-may-98)
    COMMON acolor,     ColTbl, bColor, UserR, UserG, UserB
    COMMON aSCALEBAR,  scale_bar, bar_pos
    	scale_bar	flag to plot or not plot bar
    	bar_pos		[bar_x, bar_y] position of start of bar in fraction of plot units
    COMMON aselect,
    	select_flag	flag to switch Thumbs from replot to select mode (28-sep-99)
       copy_flag   flag to indicate copy operation
    	NewBuf		Number of new buffer
       img_rep_line  flag to indicate mode to identify a replacement line
    	norm_flag	flag to control if ring current normalization is to be carried out (11-mar-07)
    	norm_value	standard ring current (default = 400 mA - ALS top up target) (07-Aug-08)
    COMMON axis_color_common,
    	ax_low_color_index, ax_top_color_index, $
    	ax_black_color_index, ax_white_color_index, $
    	ax_color00_index, ax_color01_index, ax_color02_index, ax_color03_index, $
    	ax_color04_index, ax_color05_index, ax_color06_index, ax_color07_index, $
    	ax_color08_index, ax_color09_index, ax_color10_index, ax_color11_index, $
    	ax_color12_index, ax_color13_index, ax_color14_index, ax_color15_index
    COMMON aLBL,       Label, BufLblFont
    	Label			array of 9 labels displayed with file list
    	BufLblFont		font used for widget (system specific !!)
    COMMON aOPTIONS, Mouse, Line_Sym, pan_smooth
       Mouse		   	switch to indicate if Main_graph is active on mouse MOTION (=1) or click (=0)
    	Line_Sym		switch to determine if symbols are plotted (=1)
    	pan_smooth		switch to indicate if zoom graph updated on mouse MOTION (=1) or click (=0)
       thumb_plot      switch to indicate that a ThumbZoom (4 or 9) is plotted (aph 10-jul-99)
    COMMON aparam,     (3-mar-98, 11-may-99)
    	X_calib  	X-slope, X-intercept for auto spectral scale setting
    	Y_calib     Y-slope, Y-intercept for auto spectral scale setting
    	constant	add/subtract constant
    	gain_m		multiplicative gain constant
    	gain_d		divisive gain constant
    	factor      constants for conversions
    	Xlock       standard (x1,x2) values (for image alignment)
    	Ylock       standard (y1,y2) values (for image alignment)
    	cll         (x,y) lower left of cutout (Zoom; align images)
    	cur  		(x,y) upper right of cutout (Zoom; align images)
    	pix_siz		size of pixel (for image aligmnment)
    COMMON lastpath,	(2-mar-98; 4-jan-00 overwrite_all)
    	lpath			last path accessed in pickfile routine
    	lfile			last file accessed in pickfile routine
    	overwrite_all	switch to indicate ignore overwrite checks in file writes
    COMMON alsRead,	(01-Jan-99)
    	I_process	procedure to massage I_file (none, dark, OSA, both)
    	Io_process	procedure to massage I_file (none, dark, OSA, both)
    	S_file		name of sample data file  (NB I_file used by stacks !!)
    	Io_file		name of reference data file
    	I_col		Column number for sample data
    	Io_col		Column number for reference data
    	als_readin	method of processing sample, ref (data, ratio, absorption)
       Scan_Par_Update  switch to indicate updating paramaters during Browse
    COMMON ax_logo_com, (29-jan-00)
    	ax_logo		array of logo_num logo images
    	logo_rate	display rate
    	logo_num	number of images
    	logo_now 	current image
    	logo_size	size of image (gr_scale*360)
       frontpanel	if = 1 then front panel (single or rotating) is up
    	logo_more	if = 1 continue displaying logo
    	logo_win	array of pixmap indices
    	logo_R		red color
    	logo_G
    	logo_B
     COMMON asfcom (25-nov-01)
    	sf_cmpd		formula
    	sf_emin		minimum energy
    	sf_emax		maximum energy
    	sf_mode		tpye of calculation (trans or mass abs)
    	sf_density	density
    	sf_thick	thickness
     COMMON tofcom  (14-feb-04)
    	tofE		photon energy
     	stop1		stop # 1
    	stop2		stop # 2
    	bin_ns		bin size
    	tof1_min	minimum time for stop 1
    	tof1_max	maximum time for stop 1
    	tof2_min	minimum time for stop 2
    	tof2_max	maximum time for stop 2
     COMMON logtext  (14-sep-04)
    	log_last_line  index of last line in Widget_text box in panel
     COMMON MCF_EVENT, mcf  (26-Oct-04)  for multi-column ascii file read-in
    	MCF_ID		widget ID
    	MCF_Channel_List  list of channels
    	mcf_ext		current file extension
    	MCF_Xcol	column for X
    	MCF_Ycol	column for Y
    	MCF_rows	# of rows to skip
    	MCF_lasfile	name of last file
    	MCF_lastrow	last row
     COMMON aparam2   mesh_x, mesh_y, Io-val, nsmooth
    	mesh_x		#y-pixels to interpolate images to
    	mesh_y		#y-pixels to interpolate images to
    	Io_val		value of Io for converting images to OD
    	nsmooth		number of smooths (Savitsky-Golay or median)
     COMMON ansls,		(2-mar-98)
       SD			ScanData - structure containing info of NSLS image scan
    				sd.wavelength - photon wavelength
    				sd.dwell - pixel dwell for images
    				sd.clock_frequency - something involved with count normalization

    MODIFICATION HISTORY:
     (16-Nov-99 aph) last addition
     (02-jan-00 aph) AXIS standard documentation
     (10-dec-00 cgz) added CurrentPath to COMMON aPATHS
     (25-NOV-01 APH) add asfcom
     (28-dec-01 aph) add pixelX, pixelY to COMMON aCurs1;
    				   frontpanel to ax_logo_com; img_rep_line to aselect
     (29-dec-01 aph) add aROTATE  ax_angle, ax_centre  ; alphabetized common blocks
     (31-dec-01 aph) add AxSpin to ADRAWID
     (16-feb-02 aph) add ascalebar
     (14-feb-04 aph) add tofcom
     (14-sep-04 aph) add log_text, log_last_line  (to use for storable log)
     (26-oct-04 aph) incorporate mcf_com
     (25-Feb-05 aph) add a_param2 - these ones are NOT set at start so must use
                    if n_Elements(parameter) EQ 0 then parameter = 'initial value'
     (23-Apr-05 aph) add nsmooth to a_param2
     (11-mar-07 aph) add flag for ring current normalization
     (17-Aug-08 aph)  not annotated change
     (17-Sep-08 aph) moved aselect down to see if there si a limit of recursive common

(See c:\axis2000\axis_com.pro)

## AXIS_C[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_C

    LAST CHANGED: ----------------------------------- 02-feb-08 (aph)

    PURPOSE:
    	This file contains three procedures (AXIS_C, AXIS_EVENT, AXIS_MENU_EVENT)
     which execute all menu items and displays for the AXIS2000 widget.
     It is the core of the aXis2000 widget.

    CATEGORY:
    	AXIS: data analysis

    CALLING SEQUENCE:
    	AXIS_C [, start_file = start_file, group = group, spin=spin]

     ROUTINES
    	PRO AXISMENU_EVENT, Event
    	PRO AXIS_EVENT, Event
    	PRO AXIS_C, start_file = start_file, GROUP=Group

    INPUTS:
    	EVENT - ID of event code (button push)

    KEYWORDS:
    	START_FILE 	name of initial parameters (default = AXIS.INI)
    	GROUP 		group name (AXIS_ID - stored in AXIS_COM)
    	SPIN		spin the globe on start-up; activate web links

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
       @AX_PEEM_COM  common for PEEM widget read-in
       COMMON tif_convert_common   - common for Tif convert (PEEM stacks)

    PROCEDURE:
      HELP for using aXis2000 is given in AXIS.PDF which can be accessed
     by the AXIS help button which starts Adobe Acrobat to view that file.
      If this does not come up, you may not have the Adobe reader on your
      system and/or, the system level command to run Acrobat may not be correct.
      To fix this:
           1. Download Adobe Acroreader from www.adobe.com (it is freeware)
           2. change the command to execute Acrobat in the axis.ini file
              (use the Windows RUN command to determine the correct syntax)
           3. restart aXis2000
      The source of AXIS.PDF is a Word97 document, axis2000.doc

     HELP for coding aXis2000 and a file-by-file description of the code
     is contained in AXIS_PROGRAMS.HTML which can be viewed with a web browser.

    MODIFICATION HISTORY:
     ***** for detailed history please see the top of the source file (AXIS_C.PRO) *****

(See c:\axis2000\axis_c-02feb08.pro)

## AXIS_C[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_C

    LAST CHANGED: ----------------------------------- 29-Dec-08

    PURPOSE:
    	This file contains three procedures (AXIS_C, AXIS_EVENT, AXIS_MENU_EVENT)
     which execute all menu items and displays for the AXIS2000 widget.
     It is the core of the aXis2000 widget.

    CATEGORY:
    	AXIS: data analysis

    CALLING SEQUENCE:
    	AXIS_C [, start_file = start_file, group = group, spin=spin]

     ROUTINES
    	PRO AXISMENU_EVENT, Event
    	PRO AXIS_EVENT, Event
    	PRO AXIS_C, start_file = start_file, GROUP=Group

    INPUTS:
    	EVENT - ID of event code (button push)

    KEYWORDS:
    	START_FILE 	name of initial parameters (default = AXIS.INI)
    	GROUP 		group name (AXIS_ID - stored in AXIS_COM)
    	SPIN		spin the globe on start-up; activate web links

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
       @AX_PEEM_COM  common for PEEM widget read-in
       COMMON tif_convert_common   - common for Tif convert (PEEM stacks)

    PROCEDURE:
      HELP for using aXis2000 is given in AXIS.PDF which can be accessed
     by the AXIS help button which starts Adobe Acrobat to view that file.
      If this does not come up, you may not have the Adobe reader on your
      system and/or, the system level command to run Acrobat may not be correct.
      To fix this:
           1. Download Adobe Acroreader from www.adobe.com (it is freeware)
           2. change the command to execute Acrobat in the axis.ini file
              (use the Windows RUN command to determine the correct syntax)
           3. restart aXis2000
      The source of AXIS.PDF is a Word97 document, axis2000.doc

     HELP for coding aXis2000 and a file-by-file description of the code
     is contained in AXIS_PROGRAMS.HTML which can be viewed with a web browser.

    MODIFICATION HISTORY:
     ***** for detailed history please see the top of the source file (AXIS_C.PRO) *****

(See c:\axis2000\axis_c.pro)

## AXIS_DIALOG

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_DIALOG

    LAST CHANGED: ----------------------------------- 126-Dec-08 (aph)

    PURPOSE:
    	This procedure creates the widget for use with aXis2000

    CATEGORY:
    	AXIS: data analysis

    CALLING SEQUENCE:
    	AXIS_DIALOG

    INPUTS:  NONE

    KEYWORDS:  NONE

    OUTPUTS: NONE

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (10-mar-00 cgz) initially written
     (30-mar-00 cgz) modifications to acommadate changes by APH in AXIS
     (30-may-00 cgz) modifications to acommadate changes by APH in AXIS
     (09-dec-00 cgz) reconciliation with AXIS v.2.0.b
     (29-dec-00 aph) remove SVD-map from images menu; change Zoom; thumbnails submenus
     (04-jan-01 cgz) created menu button bar for most frequently accessed simple functions
    			modified lineout options for reduced screen use, i.e., laptops
     (22-jan01 cgz) reduced space gap between row of pull down menus and buttons
     (05-feb-01 aph) extend images~average pixels_all; utilities~change mesh re-introduced
     (11-feb-01 aph) add read_bl5 menu items
     (13-feb-01 aph) add spectra~curve fit
     (21-feb-01 aph) add ALS XM-1 image read-in
     (17-apr-01 aph) update identifier to reflect changes
     (07-jun-01 aph) introduce ALS PEEM widget - not functional as of 26-jun-01
     (27-jun-01 aph) read_stxm4 nsls image read in
     (12-jul-01 aph) convert stxmIV for stack read-in
     (27-jul-01 aph) add CGO procedure for stack mapping
     (12-aug-01 aph) add widget for PEEM tif to netCDF conversion
     (29-aug-01 aph) add 5.3.2 stack read in
     (30-sep-01 aph) add Read~spectra~nsls~stxmIV
     (07-oct-01 aph) colorbar fills sub-wiget; rearrangement of panel (gamma to bottom; etc)
     (14-oct-01 aph) SPECTRA: add additional processing
     (28-oct-01 aph) add WRITE_SDF
     (26-nov-01 aph) re-order
     (19-dec-01 aph) version increment
     (28-dec-01 aph) add image~replace_line (to fix up early 5.3.2 errors); frontpanel
     (31-dec-01 aph) add utilities~Execute macro; add PNG write and read
     (16-feb-02 aph) add utilities~scale bar
     (30-mar-02 aph) move overplot command to main line menu
     (17-apr-02 aph) add Elmitecx readin
     (28-apr-02 aph) adapt Elmitec read-in to *.dat (binary format)
     (08-may-02 aph) introduce sphinx stack read-in (adapted ALS PEEM)
     (12-may-02 aph) modify display comand order; delete read~stxm532_early
     (16-jul-02 aph) VERSION J started ;  elmitec peem read-in
     (28-jul-02 aph) clean up log entries on aXis2000 start-up
     (06-aug-02 aph) add Andy Smith's tif_convert for ALS (&SRC) PEEM data
     (09-sep-02 aph) add ax_one_pt
     (30-oct-02 aph) add sphinx-spectra
     (15-feb-03 aph) add multi-column spectral read-in
     (12-mar-03 aph) version identifier set to 2.1m  for release
     (02-jun-03 aph) improve PEEM data conversion
     (18-jun-03 aph) update banner : stack_analyze & stack_fit improvements
     (20-sep-03 aph) add absolute value to spectral processing; multiply buffers
     (15-nov-03 aph) histogram
     (30-dec-03 aph) redfine version (force monotonic in fitting introduced)
     (14-feb-04 aph) add read_all for TOF
     (20-feb-04 aph) add stacks~convert~TOF-all
     (10-Apr-04 aph) add image~remove_zeros
     (02-may-04 aph) update to 2.1p
     (17-may-04 aph) add Lox read-in
     (09-jun-04 aph) update version to 2.1q
     (28-aug-04 aph) update version to 2.1p
     (14-sep-04 aph) add image~average~whole~non-zero function
     (17-0ct-04 aph) add stack_add; change STXM_5.3.2 to ALS_STXM
     (28-Oct-04 aph) change order of stack analysis widgets
     (20-nov-04 aph) generalize binning of images, files
     (21-jun-05 aph) update version
     (03-feb-05 aph) add REGRESS based curve fits
     (20-feb-05 aph) fixed Ax_regress plotting; ALS_STXM map; re-order stacks menu
     (21-mar-05 aph) add utilities~write axis ascii
     (25-mar-05 aph) revise dialog to remove unused buttons
     (28-may-05 aph) revise for correction to PEM_load.pro etc
     (14-Jun-05 aph) fixed non-monotonic (I hope!); improve tif_convert; fix oplot 1-point sections of non-monotonic spectra
     (17-Jun-05 aph) various updates (ALS_STXM, map, 1-image with regions; etc)
     (20-jul-05 aph) update version (stack analyze color problem fixed
     (08-aug-05 aph) add write~litho; remove Sphinx_nc
     (18-sep-05 aph) add reset-color, display~RGB image
     (18-oct-05 aph) add read_lox
     (03-nov-05 aph) add read_xyt and procedure to mask patterns for integration
     (13-nov-05 aph) update tag line
     (14-dec-05 aph) add stacks~tomography~convert
     (28-jan-06 aph) add read~images~roi
     (04-Feb-06 aph) update version identified and some menu labels
     (09-feb-06 aph) read PEEM2 AOIs added
     (16-feb-06 aph) update colors; layout; fix slider (removed /drag)
     (23-feb-06 aph) add access to slicer3; re-arrange read~image to simplify
     (05-mar-06 aph) fix img_warp
     (22-mar-06 aph) fix channel selection in Lox read-inn; normalize to 400 mA (STXM-sdf)
     (15-Apr-06 aph) add convert to BE
     (21-apr-06 aph) improve stack_analyze (auto zoom, roi)
     (26-apr-06 aph) read jpg images (1); convert sequence of jpg images
     (01-may-06 gaj) add convert NCB to MRC
     (04-may-06 aph) polarization fit to polarization signals and stacks
     (31-may-06 aph) remove /scroll on initial definition of base; reformat right side a bit
     (10-jun-06 aph) add routine to convert set of SDF images into a stack; JSO adaptation of stack_analyse
     (12-jun-06 aph) add images~roi~lox
     (12-jun-06 gaj) add stacks~convert format~mrc to ncb
     (21-jul-06 jso) added spectra~convert_to_OD1
     (01-Aug-06 gaj) add stacks~convert format~ncb to mpg for making movies
     (13-aug-06 aph) integrate GAJ and JSO changes
     (22-sep-06 aph) re-arrange stack~convert menu; fix line_fit  (B. Watts bug finder)
                     incorporate Remy Coulombe's region analysis for PEEM
     (06-oct-06 aph) Remy's region, stack_analyze & axis_dialog update
     (12-Nov-06 aph) add stacks~append, generate_mask~manual
     (04-Dec-06 aph) use scroll bar only for windows operating systems
     (20-Jan-07 aph) add read-in for ALS PEEM3 format images, spectra and stacks
     (11-mar-07 aph) update version
     (01-jun-07 aph) add link to PCA_GUI, update version
     (14-jul-07 aph) add stacks~tomography~axb
     (13-Sep-07 aph) update version
     (10-Dec-07 aph) add bin Lox stacks
     (29-Dec-07 aph) add  stack~ax_rgb_widget; stack~transmission
     (01-Feb-08 aph) convert_to_OD fixed and menu changed
     (21-Mar-08 aph) update version
     (20-Apr-08 aph) update version
     (04-Jun-08 aph) update version; change XAS spectrum to multi-col
     (15-Jun-08 aph) update version
     (17-sep-08 aph) add in CJJ stack_analyze
     (11-oct-08 aph) add read Bessy stxm images
     (26-Dec-08 aph) start Read~stacks menu item; add read_ftir (IR maps from Nicolet / soleil)

(See c:\axis2000\axis_dialog.pro)

## AXIS_INI

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_INI

    LAST CHANGED: ----------------------------------- 24-Jan-05 (aph)

    PURPOSE:
    	This function reads and writes default values for AXIS.

    CATEGORY:
    	AXIS: utility

    ROUTINES:
    	 test = AXIS_INI_SAVE (filename = filname)  - code that writes parameter file

    CALLING SEQUENCE:
    	test = AXIS_INI(file=file, out=out, set = set)

    CALLED FROM AXIS:
    	Utilities->Set preferences
     and at start up and Quit

    INPUTS: none

    KEYWORDS:
    	FILE - initialization file name
    	/OUT - write initialization file
    	/SET - interactive setting of default values

    OUTPUTS:
    	axis.ini (or user defined file name)

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     looks up  default values from AXIS.INI or a user-defined file
     if no file, establish defaults
     on exit from AXIS writes out default values to AXIS.INI or a user-specified file

    MODIFICATION HISTORY:
     (28-jun-98 aph) first version
     (12-dec-98 aph) introduce font switching for widget (to adapt IDL 4, IDL 5)
     (13-dec-98 aph) add /set option
     (29-dec-98 aph) use AXIS_OPTIONS to establish defaults (IDL 5.2)
     (03-Jan-99 aph) set default WIN font to Arial*14; switch on 5.2 NOT 5
     (11-May-99 aph) establish axis_ini_save subroutine;
    				  allowed 'Printer' to be full command line, not just language
     (24-may-99 aph) extend to include HELP file command
     (16-nov-99 aph) 'loc' -> 'location' to see if this is why it is not preserved
     (02-jan-00 aph) AXIS standard documentation
     (31-jan-00 aph) add  net browser command
     (27-feb-00 aph) add groupID to get_text
     (07-apr-00 aph) modify to force saving to codepath area by passing on file to axis_ini_save
     (30-nov-00 cgz) added statements to ensure that no leading or trailing spaces are
    				included in parameters once read in from *.ini file
     (05-dec-00 cgz) reversed order of AXIS_INI and AXIS_INI_SAVE
     (09-dec-00 cgz) added conversion of float(strtrim(gr_scale,2))
     (23-jan-01 cgz) added dialog to axis_ini_save, also cleaned up logical path
     (31-jan-01 aph) change prompt
     (22-apr-01 aph) fix crash when load using axis.ini from separate directory - drop axis_options
     (07-oct-01 aph) re-activate axis_options
     (28-oct-04 aph) allow for rescue if user pushes 'cancel' on 'exit'
     (08-nov-04 aph) fix problem that axis2000 does NOT use saved last_file / path information
                problem was LPath not DefPath was saved, but previously it worked; probably was change in axis_ini_save
     (24-jan-05 aph) replace test for read-in which failed in IDL5.2

(See c:\axis2000\axis_ini.pro)

## AXIS_LNX

[Previous Routine] [Next Routine] [List of Routines]

     ************************** axis.PRO ***********************************
     start-up file for AXIS_C.PRO:
     IDL4.0 WIDGET for analysing X-ray microscopy spectral and image data
     @Hitchcock Enterprises unlimited
     ======================================== LAST CHANGED: (aph 14-Jun-98)

(See c:\axis2000\axis_lnx.pro)

## AXIS_LOG

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AXIS_LOG

    LAST CHANGED: ----------------------------------- 	05-Jun-06

     PURPOSE:
    	This procedure displays messages in the aXis2000 log buffer, the IDL log area
     and (when implemented!!) the saved log file for a session

     CATEGORY:
    	utility.

     CALLING SEQUENCE:
    	AXIS_LOG, TEXT, CLEAR = clear, CLOSE = close, OPEN = open

     INPUTS:
       TEXT   text string to display

     KEYWORDS:
    	CLEAR	clear the aXis2000 log buffer (DEFAULT is to append)
    	CLOSE	close current session log file
    	OPEN	open a session log file (close any existing open log)

     OUTPUTS:
    	Display in Uprompt Widget_Text box
    	print to IDL log and (optionally) a log file

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     RESTRICTIONS:
    	Log file not yet implemented

     MODIFICATION HISTORY:
     (14-sep-04 aph) first created
     (16-jun-05 aph) ensure works outside axis2k
     (13-Nov-05 aph) force log_last_line to be scalar
     (05-jun-06 aph) .... and force log_last_line(0) when used (IDL5.2)

(See c:\axis2000\axis_log.pro)

## AXIS_OPTIONS_EVENTCB[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_OPTIONS_EVENTCB

    LAST CHANGED: ----------------------------------- 07-oct-01

    PURPOSE:
    	This set of procedures are the event processing for the AXIS_OPTIONS widget.

    CATEGORY:
    	AXIS: utility

    ROUTINES
     AXIS_Opts_Update - loads current default values into AXIS_OPTIONS widget
     BUT_Update, Event - takes info from the AXIS_OPTIONS widget
                         and writes the ini file
    	BUT_Cancel	- cancel
    	BUT_WIN		BUT_X		BUT_OpSys_Other	TXT_Set_Op_Sys - op. system
    	BUT_PS	BUT_PCL		BUT_Print_Other		TXT_Set_Print_device - printer
    	BUT_Mac	BUT_ALS	BUT_NSLS	BUT_Location_Other	TXT_Set_Location - location
    	BUT_Size_050	BUT_Size_075	BUT_Size_100	BUT_Size_125
    	BUT_Size_150	- size of AXIS
    	Zero_buts	- sets exclusive buttons to zero on starting widget
    	Load_def_Win	- loads default parameters for Windows systems
    	Load_Def_X		- loads default parameters for unix systems
    	BUT_INI_Browse	BUT_SOURCE_Browse	BUT_DATA_Browse	BUT_Print_Browse
    	browse for file names
    	axis_options_eventcb - auto loading stub

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     	works with AXIS_OPTIONS.PRO Widget to establish AXIS defaults

    MODIFICATION HISTORY:
     Generated on:	12/28/98 21:13.49
     (aph 29-Dec-98) first written using new IDL 5.2 GUIBuilder (aph^2)
     (aph 03-Jan-99) set Windows default font to Arial*14
     (aph 24-May-99) revise to display/modify Pr_command (replace print_file)
     (16-nov-99 aph) change 'loc' to 'location' (for place specific features)
     (03-jan-00 aph) AXIS standard documentation
     (31-jan-00 aph) add Web browser command; re-arrange
     (30-dec-00 aph) merged with axis_options to make run with Zimba compile-on-fly
     (22-apr-01 aph) attemt to get working - no go !!
     (07-oct-01 aph) got working in aXis2000; only turns on (from axis.ini) in Windows

(See c:\axis2000\axis_options.pro)

## AXIS_OPTIONS_EVENTCB[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_OPTIONS_EVENTCB

    LAST CHANGED: ----------------------------------- 31-jan-00

    PURPOSE:
    	This set of procedures are the event processing for the AXIS_OPTIONS widget.

    CATEGORY:
    	AXIS: utility

    ROUTINES
     AXIS_Opts_Update - loads current default values into AXIS_OPTIONS widget
     BUT_Update, Event - takes info from the AXIS_OPTIONS widget
                         and writes the ini file
    	BUT_Cancel	- cancel
    	BUT_WIN		BUT_X		BUT_OpSys_Other	TXT_Set_Op_Sys - op. system
    	BUT_PS	BUT_PCL		BUT_Print_Other		TXT_Set_Print_device - printer
    	BUT_Mac	BUT_ALS	BUT_NSLS	BUT_Location_Other	TXT_Set_Location - location
    	BUT_Size_050	BUT_Size_075	BUT_Size_100	BUT_Size_125
    	BUT_Size_150	- size of AXIS
    	Zero_buts	- sets exclusive buttons to zero on starting widget
    	Load_def_Win	- loads default parameters for Windows systems
    	Load_Def_X		- loads default parameters for unix systems
    	BUT_INI_Browse	BUT_SOURCE_Browse	BUT_DATA_Browse	BUT_Print_Browse
    	browse for file names
    	axis_options_eventcb - auto loading stub

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     	works with AXIS_OPTIONS.PRO Widget to establish AXIS defaults

    MODIFICATION HISTORY:
     Generated on:	12/28/98 21:13.49
     (aph 29-Dec-98) first written using new IDL 5.2 GUIBuilder (aph^2)
     (aph 03-Jan-99) set Windows default font to Arial*14
     (aph 24-May-99) revise to display/modify Pr_command (replace print_file)
     (16-nov-99 aph) change 'loc' to 'location' (for place specific features)
     (03-jan-00 aph) AXIS standard documentation
     (31-jan-00 aph) add Web browser command; re-arrange

(See c:\axis2000\axis_options_eventcb.pro)

## AXIS_PEEM_EVENTCB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_PEEM_EVENTCB

    LAST CHANGED: ----------------------------------- 03-jun-01

    PURPOSE:
    	This set of procedures are the event processing for the AXIS_PEEM peem processing widget.

    CATEGORY:
    	AXIS: utility

    ROUTINES
     AXIS_Opts_Update - loads current default values into AXIS_OPTIONS widget
     BUT_Update, Event - takes info from the AXIS_OPTIONS widget
                         and writes the ini file
    	BUT_Cancel	- cancel
    	BUT_WIN		BUT_X		BUT_OpSys_Other	TXT_Set_Op_Sys - op. system
    	BUT_PS	BUT_PCL		BUT_Print_Other		TXT_Set_Print_device - printer
    	BUT_Mac	BUT_ALS	BUT_NSLS	BUT_Location_Other	TXT_Set_Location - location
    	BUT_Size_050	BUT_Size_075	BUT_Size_100	BUT_Size_125
    	BUT_Size_150	- size of AXIS
    	Zero_buts	- sets exclusive buttons to zero on starting widget
    	Load_def_Win	- loads default parameters for Windows systems
    	Load_Def_X		- loads default parameters for unix systems
    	BUT_INI_Browse	BUT_SOURCE_Browse	BUT_DATA_Browse	BUT_Print_Browse
    	browse for file names
    	axis_options_eventcb - auto loading stub

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     	works with AXIS_OPTIONS.PRO Widget to establish AXIS defaults

     RESTRICTIONS
     does not work !!! - from cgz changes to axis Nov00 to Jan01

    MODIFICATION HISTORY:
     (aph 03-jun-01) first written - adapted from axis_options

(See c:\axis2000\axis_peem.pro)

## AXIS_READ_IMAGE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_READ_IMAGE

    LAST CHANGED: ----------------------------------- 03-jan-00

      This function reads image files from formats defined
     by the filename extension into the standard AXIS 2d data structure.
     If a file name is not supplied or if the file cannot be found
     the user is asked to identify the file of interest.
     The extension of the file is set as the default extension
     for future image reading.

     CATEGORY:
    	AXIS: utility

    CALLED FROM AXIS:
    	used in some procedures (SVD ..)

     CALLING SEQUENCE:
    	Result = AXIS_READ_IMAGE( [file=file, /axis] )

     INPUTS: none

     KEYWORD PARAMETERS:
    	FILE:	name of file to be read (including path)
    	AXIS:	flag to indentify if called from AXIS

     OUTPUTS:
      This function returns a 2d AXIS data structure
       s = {t:'2d', x:x, y:y, d:d, xl:x_label, yl: y_label, dl: data_label}

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS
       @BSIF_COM - common block for netCDF

     PROCEDURE:
     	This function is a front end for a number of routines used to read in
       the various data formats that AXIS supports.
    	FORMAT         PROCEDURE	EXTENSION
     ---------------------------------------
    	AXIS			AXB_LOAD	*.axb
    	ALS-STXM		READ_ALS	*.im%
    	NSLS-old		READ_BNL	*.nc
    	NSLS-cryo		READ_CRYO	*.sxm
    	ALS-PEEM		READ_PEEM	*.tif

     Although not implemented (as of 3-Jan-00) the idea is
     to develop auto file identification and read-in capability.

     EXAMPLE:
     	a = axis_read_image(file='f:\stxm\9909\914\90914100.im1')

     MODIFICATION HISTORY:
     (17-Oct-99 aph) first version
     (03-jan-00 aph) AXIS standard documentation

(See c:\axis2000\axis_read_image.pro)

## AXIS_START.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_START.PRO

    LAST CHANGED: ----------------------------------- 20-May-00

    PURPOSE:
    	This set of procedures is a widget to guide IDL start-up

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	AXIS_START

    ROUTINES
    	AXIS_START_BASE_event, event
    	AXIS_START_BASE, GROUP_LEADER=wGroup, _EXTRA=_VWBExtra_
    	AXIS_start, GROUP_LEADER=wGroup, _EXTRA=_VWBExtra_

    INPUTS: none

    KEYWORDS: none

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     Generated on:	09/26/99 11:48.55
     (5-nov-99 aph) larger zimba button
     (20-may-00 aph) AXIS standard documentation

(See c:\axis2000\axis_start.pro)

## AXIS_START_EVENTCB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_START_EVENTCB

    LAST CHANGED: ----------------------------------- 20-jan-00

    PURPOSE:
    	This set of procedures processes choices from IDL start-up procedure
     This is the event call back file for AXIS_START

    CATEGORY:
    	STAND ALONE: utility

    ROUTINES
    	BUT_AXIS, Event - give prompt to user to run AXIS
    	BUT_ZimbaStack, Event - compile and run zinba stack analyze (ZIMBA_RUN)
    	BUT_IDL, Event = goto IDL
    	AXIS_start_eventcb - stub for autoloading

    MODIFICATION HISTORY:
     Generated on:	09/26/99 11:48.55
     (16-Oct-99 aph) current version
     (03-jan-00 aph) AXIS standard documentation
     (20-jan-00 aph) removed ZSTACK_MANALIGN to match new Zimba codes

(See c:\axis2000\axis_start_eventcb.pro)

## AXIS_WEB[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_WEB

    LAST CHANGED: ----------------------------------- 25-Feb-08

    PURPOSE:
    	This procedure executes a net browser command to access
     synchrotron or other sites via the web.
     The browser command will be system / computer specific.

    CATEGORY:
    	AXIS: utility (captive)

    CALLING SEQUENCE:
    	AXIS_WEB, event_X, event_Y

    CALLED FROM AXIS:
    	while rotating logo visible only

    INPUTS:
    	EVENT_X - from Xmanager, X-value of pixel clicked
    	EVENT_Y - from Xmanager, Y-value of pixel clicked

    KEYWORDS:
    	SITE - code for web site to go to (to use from "utilities/XRM sites")

    OUTPUTS:
    	A new window with the web info is generated.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    SIDE EFFECTS:
    	A window is created/destroyed.

    PROCEDURE:
    	uses IDL spawn command. The form of the Net command MUST be one
     that will operate from an MS-DOS window in win-95. Thus 8.3 file names and
     no embedded blanks in paths.

    MODIFICATION HISTORY:
     (31-jan-00 aph) first created; adapted to variable size
     (22-aug-00 aph) add link to aXis2000 home base
     (22-aug-01 aph) update axis2000 home base
     (25-Feb-08 aph) update web links

(See c:\axis2000\axis_web-new.pro)

## AXIS_WEB[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AXIS_WEB

    LAST CHANGED: ----------------------------------- 22-aug-01

    PURPOSE:
    	This procedure executes a net browser command to access
     synchrotron or other sites via the web.
     The browser command will be system / computer specific.

    CATEGORY:
    	AXIS: utility (captive)

    CALLING SEQUENCE:
    	AXIS_WEB, event_X, event_Y

    CALLED FROM AXIS:
    	while rotating logo visible only

    INPUTS:
    	EVENT_X - from Xmanager, X-value of pixel clicked
    	EVENT_Y - from Xmanager, Y-value of pixel clicked

    KEYWORDS:
    	SITE - code for web site to go to (to use from "utilities/XRM sites")

    OUTPUTS:
    	A new window with the web info is generated.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    SIDE EFFECTS:
    	A window is created/destroyed.

    PROCEDURE:
    	uses IDL spawn command. The form of the Net command MUST be one
     that will operate from an MS-DOS window in win-95. Thus 8.3 file names and
     no embedded blanks in paths.

    MODIFICATION HISTORY:
     (31-jan-00 aph) first created; adapted to variable size
     (22-aug-00 aph) add link to aXis2000 home base
     (22-aug-01 aph) update axis2000 home base

(See c:\axis2000\axis_web.pro)

## AX_BIN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_BIN

    LAST CHANGED: ----------------------------------- 10-dec-07

    PURPOSE:
    	This procedure reads in a sequence of NetCDF image files (*.nc)
     or one image file if keyword_set(one), and smooths
     by binning BIN times (2 implies (2x2) pixels merged to 1 pixel ETC
     The smoothed image is written into b______.nc
     where _____ is all but first letter of name suplied

    CATEGORY:
    	AXIS: stack analysis

    CALLING SEQUENCE:
    	AX_BIN, list [, bin=bin, one=one, stack=stack ]

    CALLED FROM AXIS:
    	->Stacks->bin.{current image, NSLS.{1,file}, stack (*.ncb,lox)}

    INPUTS:
    	LIST = file containing list of *.nc files (typically a *.sl stack list)

    KEYWORDS:
    	BIN = # - number of (#x#) pixels to average
    	ONE     - if set, read in only a single file (use pickfile dialog if needed)
    	STACK   - process a *.ncb binary stack file
    	LOX		- lox stack data set

    OUTPUTS:
    	b_____.nc binned file written in default subdirectory
       stack____s.ncb

    COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	BSIF_COM	NetCDF common block

    MODIFICATION HISTORY:
     (aph 12-jan-99) first written - adapted from ax_rd_im, bin
     (aph 17-May-99) corrected to resize on x as well as y
     (31-dec-99 aph) AXIS standard documentation
     (09-jan-00 aph) fixed up output filename to remove ___nc.nc
     (20-nov-04 aph) add bin of stacks; activate read one *.nc file
     (10-dec-07 aph) add lox stack binning

(See c:\axis2000\ax_bin.pro)

## AX_CGO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_CGO

    LAST CHANGED: ----------------------------------- 17-sep-08

    PURPOSE:
    	This procedure generates component maps by using
     pixel-by-pixel conjugate gradient optimization curve fitting. It handles
     an arbitary number of images fit to up to 8 components.
     Except for individual image by image read in mode, AX_CGO
     assumes all image files have similar SIZE.
     AX_CGO ignores (x,y) scales (no interpolation)

    CATEGORY:
    	STAND ALONE: image, stack analysis

    CALLING SEQUENCE:
    	AX_CGO [,  axis=axis, comp_images = comp_images, coeff = coeff, $
             help=help, images = images, stack = stack, verbose = verbose]

    CALLED FROM AXIS:
    	->Stacks->maps ->CGO curve fit

    INPUTS:
    	All inputs are through keywords. User is prompted for missing data.

    KEYWORDS:
    	AXIS - if on, then called from AXIS widget
    	COEFF = fit parameter file with names of spectral files
    	COMP_IMAGES = file with names of files to store component images (*.axb)
    	HELP - set to print how-to-use statement
    	IMAGES = file with list of images to be analysed
       STACK = name of a binary format stack (*.ncb)
    	VERBOSE  - print additional documentation of SVD procedure

    OUTPUTS:
    	Component maps, residuals etc are output to disk.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	stack_process_com
    	COMMON volume_data, image_stack
    	bsif_com

    PROCEDURE:
    	The images are first read in - either as a binary stack (if stack keyword set)
     or from the list of images, or from pickfile dialog.
     The absorption coefficents for each component at the energies of the images
     are then read in, either through interpolation of a reference spectrum
     (read in via pickfile dialog), or from a file of absorption coefficients
     in a  standard format (see example below, written by AX_CGO); or by manual input.
     The CGO_OPTIMIZE curve fit procedure is then applied on a pixel-by-pixel basis.
     Component maps are generated. written to files, and displayed either in
     IDL windows (if run stand alone) or in AXIS buffers.

     EXAMPLE:
     Absorption coefficient data file format (version as of Jul-01)
     # components
      (line per energy; E, sig-1  sig-2  sig-3   sig-4)
      (labels for the components)
     -----------------------
          4.00000
          281.824  0.000687768  0.000191430  0.000572100  0.000390513
          282.199  0.000678105  0.000192197  0.000618820  0.000361705
          282.574  0.000753450  0.000189890  0.000628327  0.000574156
          282.949  0.000803872  0.000187579  0.000724339  0.000398248
     ....
      mtx
      san
      pipa
      fg

    MODIFICATION HISTORY:
     (27-jul-01 aph) first developed from ax_svd
     (06-oct-01 aph) add xl to temp plots to allow re-use
     (14-may-03 aph) modify paramter files to store names only
     (28-may-03 aph) force '.par' extension (pickfile, filter= & /write); comp_names
     (04-jun-03 aph) use ax_par_save & ax_par_load
     (30-dec-03 aph) add ax_sort_mono to force stack E-scale and reference spectral scales to be monotonic
     (20-jan-04 aph) use dialog_message to control residual stack writing
    				  ensure E-value (0.0) added to component maps
     (21-jan-05 aph) increase default convergence to 1e-10
     (01-feb-05 aph) fix ax_sort_mono to use structure (ricochet change from lox change)
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_cgo.pro)

## AX_CIMAGE.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_CIMAGE.PRO

    LAST CHANGED: ----------------------------------- 	12-Sep-07 (aph)

     PURPOSE:
    	This procedure cleans up images by removing very low and very high values.
     These appear in some CCD camera outputs due to dead or easily saturated pixels

     CATEGORY:
    	Image processing

     CALLING SEQUENCE:
     	RESULT = AX_CIMAGE(IMG_ARR)

     INPUTS:
    	IMG_ARR  - 2-d array (integer, double or real)

     KEYWORDS: none

     OUTPUTS:
    	Modified Image

     COMMON BLOCKS: none

     SIDE EFFECTS: none

     RESTRICTIONS: does not work if low contrast, Error trapped if flat image

     PROCEDURE:
    	This procedure calculates a histogram and determine two levels (Top and Bottom)
     such that 2 rows worth of pixels are above and two rows worth of
     pixels are below these levels. The image is then clipped between Top and Bottom

     EXAMPLE:
    	a=RD_PEEM()		; read in test ALS PEEM2 file (pass_test_data\ALS_PEEM2_full_0609_#020.tif)
    	splot2d, a		; display to show out-of-limits aspects of image
    	q=AX_CIMAGE(a)	; process - works for structures and images
    	splot2d, q		; display to show correction of out-of-limits aspects

     MODIFICATION HISTORY:
     (22-Jan-07 as) Andreas Scholl provided routine as a solution to problem of arbitary removal
             of first 5 columns (causes dimensional problems); NB his code is object oriented IDL5.5;
    		  translated back to IDL4.2 compatible code
     (12-Sep-07 aph) incorporated into aXis2000; AXIS standard header added

(See c:\axis2000\ax_cimage.pro)

## AX_CLEAR

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_CLEAR

    LAST CHANGED: ----------------------------------- 08-jul-02 (aph)

     PURPOSE:
    	This procedure clears one or more AXIS buffers.
     It is also used to display the AXIS logo on startup or an all-clear call

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	AX_CLEAR [, all=all, select=select, current = current, spin=spin]

    CALLED FROM AXIS:
    	->Utilities->Clear->{current,selected,all}

    INPUTS: none

    KEYWORDS:
    	ALL - clear all buffers and display logo
    	SELECT - clear user-selected buffers
    	CURRENT - clear current buffer only
    	SPIN - use rotating logo (actually triggered from AxSpin flag in axis_com)

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (19-sep-99 aph) isolated from aaa_axis to use elsewhere (img_aln)
     (26-sep-99 aph) fix logic to execute only 1 of the 3 choices
     (28-sep-99 aph) make clear,/all work correctly
     (30-oct-99 aph) set background to white
     (16-nov-99 aph) introduce WIDGET_CONTROL, CLEAR_events to dump mouse clicks
     (31-dec-99 aph) AXIS standard documentation
     (29-jan-00 aph) rotating logo
     (20-feb-00 aph) correct color for logo if >256 colors
     (05-dec-00 cgz) added in platform context for logo directory
     (19-dec-00 cgz) modified ax_black_color_index to ax_plot_bkgd_color_index
     (29-dec-00 aph) get to work properly with zoom~thumbnails
     (20-aug-01 aph) add group call to mbuf for modal action
     (22-aug-01 aph) rescue rotating logo
     (31-dec-01 aph) delete buffer 0 if all_clear; introduce ax_clear_oneworld, ax_clear_allworld
     (14-may-02 aph) change to png
     (08-jul-02 aph) switch depending on IDL version

(See c:\axis2000\ax_clear.pro)

## AX_COLOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	AX_COLOR

    LAST CHANGED: -----------------------------------16-feb-06

    PURPOSE:
    	Establish color table and color_index variables for AXIS

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	AX_COLOR

    INPUTS: none

    KEYWORDS:
    	SHOW - set to show 16 x 16 grid of color table
       NOLOAD - do not load last user (R,B,G) defined color table (for first time through)

    OUTPUTS: none

    COMMON BLOCKS:
    	axis_color_common	:
    	ax_top_color_index, ax_black_color_index, ax_white_color_index, $
    	ax_blue_color_index, ax_red_color_index, ax_green_color_index, $
    	ax_cyan_color_index, ax_magenta_color_index, ax_yellow_color_index, $
    	ax_lime_color_index, ax_gold_color_index, ax_rose_color_index, ax_yelgrn_color_index, $
    	ax_purple_color_index, ax_orange_color_index, ax_sky_color_index, ax_beige_color_index

    MODIFICATION HISTORY:
     (xx-jun-99 cgz) supplied routine (zimba_color.pro is similar)
     (24-jun-99 aph) converted from zstack_color; set 255=white; 0 = black; 241 = beige
     (29-jun-99 aph) make axis_color_common independent of other commons
     ( 1-jul-99 aph) move hard colors low; add keywourd 'noload'
     ( 8-sep-99 aph) re-activate show keyword
     (31-dec-99 aph) AXIS standard documentation
     (20-feb-00 aph) removed decomposed=0
     (07-apr-00 cgz) restored decomposed=0
    			changed color index names to be generic
    			changed assignment of ax_black_color_index and ax_white_color_index
    			added test for the number of colors and subsequent allocation of the number of colors
     (15-dec-00 cgz) modified no_load operation
     (16-feb-06 aph) change yellow (old-7) to light blue (old-13)

(See c:\axis2000\ax_color.pro)

## AX_COLORBAR

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_COLORBAR

    LAST CHANGED: ----------------------------------- 13-Oct-05

    PURPOSE:
    	This procedure displays a vertical color bar according to current gamma
     The low and high limits are displayed in AXIS separately.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
     	AX_COLORBAR [, destroy ]

    CALLED FROM AXIS:
    	(from PlotBuf)

    INPUTS: none

    KEYWORDS:
    	DESTROY - remove the colorbar (if not displaying an image)

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	Uses IDL colorbar procedure but adapted to AXIS widget
     by positioning the bar in a draw window set up by AXIS

    MODIFICATION HISTORY:
     (12-nov-99 aph) first verion adapted from examples in Fanning's colorbar_define.pro
     (31-dec-99 aph) AXIS standard documentation
     (07-apr-00 cgz) Added ncolors option to call of colorbar.
    				This gives the correct presentation of the gray-scale color bar
     (30-dec-00 aph) aborted attemt to add limits; shift to abut image
     (07-oct-01 aph) modify to fill sub-wdget; axis2000 modified to add Z-limits to bar
     (13-Oct-05 aph) trap out cases where limits are equal and make them slightly different

(See c:\axis2000\ax_colorbar.pro)

## AX_CONV

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_CONV

    LAST CHANGED: ----------------------------------- 31-dec-99

    PURPOSE:
    	This function convert one or a sequence of ALS image files
     to netCDF image file format. Optional binning for smoothing.

    CATEGORY:
    	AXIS: stack analysis

    CALLING SEQUENCE:
     for functions:
    	Result = AX_CONV()

    CALLED FROM AXIS:
    	->Stacks->convert format->ALS to netCDF->many

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	*.sla (input list); {filename.nc}, *.sl file written to disk
    	result = 1 is returned regardless of action

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	generates an input list file and bin parameter for ALS2NCDF

    EXAMPLE:
    	Please provide a simple example here. An example from the PICKFILE
    	documentation is shown below. Please try to include examples that
           do not rely on variables or data files that are not defined in
           the example code. Your example should execute properly if typed
           in at the IDL command line with no other preparation.

    	Create a PICKFILE widget that lets users select only files with
    	the extensions 'pro' and 'dat'.  Use the 'Select File to Read' title
    	and store the name of the selected file in the variable F.  Enter:

    		F = PICKFILE(/READ, FILTER = ['pro', 'dat'])

    MODIFICATION HISTORY:
    (03-dec-98 aph) extracted from axis_c
    ( 7-jan-99 aph) added, bad_ID to widget_controls to allow stand-alone use
    ( 8-jun-99 aph) modify get_num call to identify group
    ( 7-jul-99 aph) FREE_LUN not just close
    (31-dec-99 aph) AXIS standard documentation

(See c:\axis2000\ax_conv.pro)

## AX_CONV_TOF-ALL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_CONV_TOF-ALL

    LAST CHANGED: ----------------------------------- 21-feb-04

    PURPOSE:
    	This function convert a sequence of ALL correlated time-of-flight files
     to  axis binary file format. Optional binning for smoothing.

    CATEGORY:
    	AXIS: stack analysis

    CALLING SEQUENCE:
     for functions:
    	Result = AX_CONV_ALL(AXIS_ON=AXIS_ON)

    CALLED FROM AXIS:
    	->Stacks->convert format->TOF-ALL

    INPUTS: none

    KEYWORDS:
     AXIS_ON   if set, called from aXis2000

    OUTPUTS:
    	*.ncb

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
       ANALCOM     stack_analyse common
    	BSIF_COM	common for netCDF format data
     	VOLUME_DATA  image_stack 3-d array

    PROCEDURE:

    EXAMPLE:

    MODIFICATION HISTORY:
     (14-feb-04 aph) adapted from AX_CONV
     (21-feb-04 aph) working in aXis2000; optional Io normalization; save PIPICO(1)

(See c:\axis2000\ax_conv_all.pro)

## AX_COPY

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_COPY

    LAST CHANGED: ----------------------------------- 31-dec-99

    PURPOSE:
    	This procedure completes the copy of structure data from CurBuf to
     NewBuf using Thumbs to identify NewBuf. The output buffer is identiifed
     by left-clicking on one of the thumbnail images or the buffer label.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	AX_COPY

    CALLED FROM AXIS:
    	->Copy then (AXIS_EVENT processing)

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	Data structure is copied from CurBufto NewBuf

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	A flag is set from the COPY command. When the user
     next clicks on one of the thumbnails or labels this defined NewBuf

    MODIFICATION HISTORY:
     (28-sep-99 aph) isolated from axis_c
     (30-oct-99 aph) removed label change
     (31-dec-99 aph) AXIS standard documentation

(See c:\axis2000\ax_copy.pro)

## AX_CURVFIT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_CURVFIT

    LAST CHANGED: ----------------------------------- 22-Jun-05

    PURPOSE:
    	This procedure executes the CG_Optimize procedure (Billy Loo @2000)
     to fit a spectrum to a set of reference spectra.
     AX_CURVFIT will run stand alone (prompting user for AXIS format files) or from AXIS.

    CATEGORY:
    	STAND ALONE: spectral analysis

    CALLING SEQUENCE:
    	AX_CURVFIT[SPC, axis=axis, help = help, coeff = coeff, set_start = set_start, pos_only=pos_only ]

    CALLED FROM AXIS:
    	->{Spectra}->Curve fFit

    INPUTS:
    	SPC		spectrum to be fit in axis 1d structure form

    KEYWORDS:
     AXIS 		called from AXIS widget
     COEFF	filename with spectral information
     HELP		print help text
     SET_START	allow users to set starting values
     POS_ONLY	force only positive coefficients
     LIMITS	[min, max] 2-vector defining lower and upper limits

    OUTPUTS: 	No explicit outputs.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	The reference spectra are read in and the coefficient matrix generated.
     CG_OPTIMIZE is then called to get the mixing coefficients

    MODIFICATION HISTORY:
     (13-feb-01 aph) first version
     (27-mar-01 aph) changed title of file input dialog
     (26-jul-01 aph) neatened code ; get pos_only working; explicitly include A, B in call
     (04-jun-03 aph) adapt for reading ref spectra names etc from ax_par_load & save to ax_par_save
     (30-dec-03 aph) force monotonic spectral data (source of NaN fits !!)
     (20-oct-04 aph) set defaults to
     (03-feb-05 aph) add auto-plot of all fit at end
     (19-feb-05 aph) correct display at end
     (22-jun05 aph) correct syntax for axis_log calls

    ro ax_CurvFit, spc, axis=axis, help=help, coeff = coeff, set_start=set_start, pos_only=pos_only

    axis_com

    F keyword_set(help) THEN BEGIN
       print,'AX_CurvFit'
       print,'Executes CG_Optimize procedure of Billy Loo to fit a spectrum'
       print, 'Uses AXIS format spectra files (*.txt) as input/output'
       print, ' KEYWORDS: '
       print, '	AXIS   = if on, then called from AXIS widget'
     	print, '	HELP   = print this how-to-use statement'
     	print, '	SET_START = allow user to define starting parameters'
     	print, '	POS_ONLY = force fit coefficients to be positive'
     	print, '    LIMITS = define bounds for fit coefficients'
     	print, '    SWAP = if on, make too low values upper and vice-versa'
       return
    NDIF

     assume AXIS is running (therefore may have called ax_curvfit)
     either when AXIS keyword is supplied or if any widget active
    f  keyword_set(axis) then axis_on = 1 else axis_on = widget_info(/active)
    rint, ' '
    rint, ' Curve fit analysis by CG_Optimize'
    rint, ' -------------------------------------------'

(See c:\axis2000\ax_curvfit.pro)

## AX_DELTAMIN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_DELTAMIN

    LAST CHANGED: ----------------------------------- 	01-Jun-08

     PURPOSE:
    	This function returns the smallest spacing in a 1-d array

     CATEGORY:
    	stand alon utility

     CALLING SEQUENCE:
    	Result = AX_DELTAMIN(X)

     OUTPUTS: minimum spacing

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (01-jun-08 aph) first written

(See c:\axis2000\ax_deltamin.pro)

## AX_FILE_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_FILE_LOAD

    LAST CHANGED: ----------------------------------- 16-jun-05

    PURPOSE:
    	This set of procedures is a widget to select columns of a multi-column ascii file
     to read in as a (x,y) 1-d data set. The widget uses SPC_LOAD to execute the read-in

    CATEGORY:
      AXIS: utility

     AX_SPC_LOAD_EVENT ROUTINES:

     TEXT_SPC_LOAD_FNAME		modify filename; when changed, execute BUT_SPC_LOAD_FNAME_BROWSE to get parameters
     BUT_SPC_LOAD_FNAME_BROWSE browse for new filename; if found, load new parameters
     BUT_SPC_LOAD_DISPLAY_HDR  show all file
     BUT_SPC_LOAD_OK			proceed with loading multi-column file into AXIS
     BUT_SPC_LOAD_CANCEL		abort read in

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks (inludes mcf_com)

    MODIFICATION HISTORY:
     (14-feb-03 aph) first version
     (26-oct-04 aph) save last file name; merge mcf_com with axis_com
     (16-jun-05 aph) correct indexing for rows to skip

(See c:\axis2000\ax_file_load.pro)

## AX_FIX_ROLLOVER

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_FIX_ROLLOVER

    LAST CHANGED: ----------------------------------- 4-jul-00

    PURPOSE:
    	This function modifies one or a sequence of *.nc image files
     to replace all values below 0 with that value + 65,535.
     This repairs a roll-over issue in conversion of some PEEM files

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
     for functions:
    	Result = AX_FIX_ROLLOVER()

    CALLED FROM AXIS:
    	->Images->Fix rollover

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	repaired files are written to disk.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (04-Jul-00 aph) first version

(See c:\axis2000\ax_fix_rollover.pro)

## AX_GEN_STACK

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_GEN_STACK

    LAST CHANGED: ----------------------------------- 10-Jun-06 (aph)

     PURPOSE:
    	This function processes a set of folders containing multi-images stacks for tomography read-in

     CATEGORY:
    	Input / output utilty; stand alone

     CALLING SEQUENCE:
    	Result = AX_GEN_STACK(GROUP=GROUP, CHANNEL=CHANNEL)

     INPUTS: none  [*.lst is a file giving path then a set of {name, angle}]

     KEYWORDS
    	GROUP 	ID of calling program
    	CHANNEL	number of data channel (default = 1)

     OUTPUTS: binary format (*.ncb) stack written

     COMMON:
    	AXIS
    	BSIF
    	ANAL
       VOLUME_DATA

     USAGE:

     format of list file for tomography applications is
     path
     name1, angle1
     name2, angle2
     . . . .

     MODIFICATION HISTORY:
     (09-Jun-06 gaj) first version for use in axis and stand alone (for tomography)
     (10-jun-06 aph) linked into aXis2000

(See c:\axis2000\ax_gen_stack.pro)

## AX_HISTOGRAM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_HISTOGRAM

    LAST CHANGED: ----------------------------------- 	29-Dec-07

     PURPOSE:
    	This function generates the histogram of an image

     CATEGORY:
    	Utility

     CALLING SEQUENCE:
    	Result = AX_HISTOGRAM(IMAGE, N_BINS=N_BINS)

     INPUTS:
    	IMAGE	2-d array

     KEYWORDS:
    	N_BINS	number of bins

     COMMON BLOCKS:
        none

     MODIFICATION HISTORY:
     (27-Dec-07 aph) isolated from axis_c and AXIS standard header added
     (29-Dec-07 aph) array sizing error corrected (check: test\data\17seps.ncb, 3-fit)

(See c:\axis2000\ax_histogram.pro)

## AX_IMAGE_ADD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMAGE_ADD

    LAST CHANGED:-------------------------- 13-oct-05

    PURPOSE
      This procedure adds the currently displayed image
      to a user-selected second image with a user-selected scale factor.
      A negative scale factor subtracts the second image from the first.
      The common (x,y) region is interpolated to the mesh of
      the more finely sampled image.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
     	ax_img_add

    INPUT: none (uses AXIS_COM common blocks for input/output)

    KEYWORDS: none

    OUTPUT:
    	(Image in buffer_9) = (1st_image) + (scale_factor)*(2nd_image)

    COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (28-dec-99 aph) isolated from AXIS_C
     (31-dec-99 aph) AXIS standard documentation
     (23-feb-00 aph) add groupID to buffer call (avoid modal error)
     (14-Oct-05 aph) fix sum/ratio error from McNeil

(See c:\axis2000\ax_image_add.pro)

## AX_IMAGE_APPEND

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMAGE_APPEND

    LAST CHANGED:-------------------------- 29-jun-00

    PURPOSE
      This procedure appends the currently displayed image
      to a user-selected second image with averaging in the common region.
      The final image is interpolated to the mesh of
      the more finely sampled image.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
     	ax_image_append

    INPUT: none (uses AXIS_COM common blocks for input/output)

    KEYWORDS: none

    OUTPUT:
    	(Image in buffer_9) = (1st_image) appended to (2nd_image)

    COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (29-jun-00) first version

(See c:\axis2000\ax_image_append.pro)

## AX_IMG_AVG

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMG_AVG

    LAST CHANGED: ----------------------------------- 24-mar-05

     PURPOSE:
    	This procedure computes the mean and standard deviation
       of all pixels in a user-selected region.

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	AX_IMG_AVG [, /NOZEROS]

    CALLED FROM AXIS:
    	->Images->Average by region->{all pixels, no zeros}

     INPUTS:
    	All input parameters are passed as keywords or through AXIS_COM

     KEYWORDS:
    	NOZEROS - if set, report average of only non-zero pizels in selected region
    	WHOLE	- if set, average all pixels in the image

     OUTPUTS:
    	Results are printed to log window and the AXIS com window.

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     PROCEDURE:
    	Uses DefROI widget for felxible region of interest definition.

     EXAMPLE:
    	only executable from AXIS

     MODIFICATION HISTORY:
     (31-dec-99 aph) isolated from AXIS_C and merged with /nozeros (corected !)
                     AXIS standard documentation
     (03-feb-01 aph) add keyword WHOLE to report average of full image
     (14-sep-04 aph) extend format field for axis log; extend to whole without zeros
                      extend variable size to accomodate large images; append to log
     (08-mar-05 aph) incrase precision
     (24-mar-05 aph) correct error for evlauating images bigger than pixel mapped display

(See c:\axis2000\ax_img_avg.pro)

## AX_IMG_DEL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMG_DEL

    LAST CHANGED: ----------------------------------- 31-dec-99

     PURPOSE:
    	This procedure replaces all pixels in a user-selected region
     by user-selected value (0 or mean).

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	AX_IMG_DEL

    CALLED FROM AXIS:
    	->Images->Delete region

     INPUTS:
    	All input parameters are passed as keywords or through AXIS_COM

     KEYWORDS: none

     OUTPUTS:
    	Modified image placed in buffer 0.

     COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

     PROCEDURE:
    	Uses DefROI widget for felxible region of interest definition.

     RESTRICTIONS:
    	only executable from AXIS

     MODIFICATION HISTORY:
     (31-dec-99 aph) first written

(See c:\axis2000\ax_img_del.pro)

## AX_IMG_LINE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMG_line

    LAST CHANGED: ----------------------------------- 20-Jan-05

     PURPOSE:
    	This procedure replaces all pixels in a user-selected line
     with those of another user-selected line.

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	AX_IMG_line

    CALLED FROM AXIS:
    	->Images->Delete region, after user clicks on a line

     INPUTS:
    	All input parameters are passed as keywords or through AXIS_COM

     KEYWORDS: none

     OUTPUTS:
    	Modified image placed in buffer 0.

     COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    ; RESTRICTIONS:
    	only executable from AXIS

     MODIFICATION HISTORY:
     (29-dec-01 aph) first written
     (20-Jan-05 aph) add ability to define the y-index of line to be changed

(See c:\axis2000\ax_img_line.pro)

## AX_IMSCL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_IMSCL

    LAST CHANGED: ----------------------------------- 31-dec-99

    PURPOSE:
    	This function maps the intensity values of an image
     to a reduced byte_scale: (0 is set to top_color_index, not 255)

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	Result = ax_imscl(G_data)

    CALLED FROM AXIS:
    	->Stacks->bin NSLS->{1,file}

    INPUTS:
    	G_data - 2d image array

    KEYWORDS: none

    OUTPUTS:
    	Result, the re-scaled data array

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	If needed, modify ax_color.pro to set ax_top_color_index
     and the number/values of reserved colors

    MODIFICATION HISTORY:
     (25-jun-99 aph) first version; from zstack_spectra.pro
     (01-jul-99 aph) adapt for hard colors low
     (31-dec-99 aph) AXIS standard documentation

(See c:\axis2000\ax_imscl.pro)

## AX_INTERP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_INTERP

    LAST CHANGED: ----------------------------------- 04-Aug-07

    PURPOSE:
    	This function changes meshes of 1-d (spectra) or
     2-d (images) AXIS data buffers, based on user input
     used to force image or spectra to a particular spacing

    CATEGORY:
    	AXIS: image and spectral processing

    CALLING SEQUENCE:
    	RESULT = AX_INTERP( tmp, mesh=mesh )

    CALLED FROM AXIS:
    	(utilities~change mesh) TMP -  spectrum or image

    KEYWORDS:
    	MESH 	[x-pixels, y-pixels]

     OUTPUT
    	RESULT is the input data converted to modified mesh

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (01-nov-00 aph) first version
     (31-dec-01 aph) add MESH keyword for auto operation
     (02-feb-05 aph) unknown update
     (04-aug-07 aph) corrected for distortion (see 70804-utilities-mesh-bug)

(See c:\axis2000\ax_interp.pro)

## AX_LOAD_LOGO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_LOAD_LOGO

    LAST CHANGED: ----------------------------------- 14-Jun-05

    PURPOSE:
    	This procedure loads the image files used to display
     the rotating globe aXis2000 logo

    CATEGORY:
    	AXIS:  utility. Can be run stand alone for testing

    CALLING SEQUENCE:
    	AX_LOAD_LOGO, axis = axis, step = step

    CALLED FROM AXIS:
    	from ax_clear (used both at start-up and if all buffers cleared)

    INPUTS: none

    KEYWORDS:
    	AXIS - if set, indicates ax_load_logo was called from AXIS
       STEP - loop step variable. If step=2 every second logo file is used

    OUTPUTS:
    	details of the logo are transferred to other programs via common

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    SIDE EFFECTS:
    	A set of 36 pixmaps - 18 Mb - is created. This can be a memory issue.

    PROCEDURE:

    MODIFICATION HISTORY:
     (01-feb-00 aph) first version
     (20-feb-00 aph) merge read and pixmap
     (22-feb-00 aph) AXIS standard documentation
     (22-aug-01 aph) add tag in AXIS log window
     (12-may-02 aph) convert from tif (unsupported past IDL5.3) to png.
     (09-jul-02 aph) use rotate, not reverse for 5.5
     (03-jun-04 aph) change 'reverse (..., 3) to reverse(..., 2) for  IDL 6.0
     (14-jun-05 aph) add switch to get spin logo correct in IDL 4.2

(See c:\axis2000\ax_load_logo.pro)

## AX_LOX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_LOX

    LAST CHANGED: ----------------------------------- 18-mar-06

    PURPOSE:
    	This set of procedures is a widget to read in files
     in the LOX format (*.lox) developed for CaPeRS PEEM.
     The header information uses XML syntax conventions.
     The widget uses read_lox to perform the file input.

    CATEGORY:
    	AXIS: utility

     AX_LOX_EVENT ROUTINES:
     TEXT_LOX_FNAME		modify filename; when changed, execute BUT_LOX_FNAME_BROWSE to get parameters
     BUT_LOX_FNAME_BROWSE 	browse for new filename; if found, load new parameters
     BUT_LOX_DISPLAY_HDR   show parameters
     BUT_LOX_OK			proceed with loading LOX file into AXIS
     BUT_LOX_CANCEL		abort read in
     WID_DLIST_CHANNEL		drop list used to display and select the data channel
     WID_DLIST_REGION		drop list to display and select region

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@LOX_COM 	structure with header info

    MODIFICATION HISTORY:
     (16-Oct-05 aph) first generated by adapting AX_SDF
     (13-nov-05 aph) stacks working, improve aspects
     (18-mar-06 aph) data channel selection fixed; all widget drop lists were coded wrong

(See c:\axis2000\ax_lox.pro)

## AX_MACRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME: AX_MACRO

    LAST CHANGED: ----------------------------------- 02-may-04

     PURPOSE:
    	This sequence of commands is a MACRO
     which is inserted into aXis2000 at the command Utilities~execute Macro
     whenever program is restarted OR axis_c is compiled

     CATEGORY:
    	user modifiable command sequence

     CALLING SEQUENCE:
      Utilities~execute Macro - captive to axis2000

     INPUTS: none (incorporate in commands)

     KEYWORDS: none (incorporate in commands)

     OUTPUTS:

     COMMON BLOCKS: none

     SIDE EFFECTS: none

     RESTRICTIONS:
     **********************************************************
    	COMMANDS KNOWN TO BE EXECUTABLE AS A MACRO - see those files for details
    	ax_rotate - rotate and mesh images
    	ax_zoom_cut	- numerically truncate and re-mesh images

     MODIFICATION HISTORY:
     (31-dec-01 aph) first introduced into aXis2000
     (02-mar-04 aph) modified header

(See c:\axis2000\ax_macro.pro)

## AX_MESH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_MESH

    LAST CHANGED: ----------------------------------- 21-apr-05

    PURPOSE:
    	This function meshes two 1-d (spectra) or 2-d (images) AXIS data buffers
     to a common (x) or (x,y) scale

    CATEGORY:
    	AXIS: image and spectral processing

    CALLING SEQUENCE:
    	Result = AX_MESH( tmp1, tmp2, nd, first=first )

    CALLED FROM AXIS:
    	(ax_image_add, image_multiply, spectral_add)

    	TMP1 - first spectrum or image
    	TMP2 - second spectrum or image
    	ND   - 1 = spectra; 2 = images
       FIRST - if set, use mesh of the first file (spectra only)

    KEYWORDS: none

     OUTPUT
    	Result = 1 signifies successful completion
    	TMP1 and TMP2 are returned converted to common scales

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     ( 3-Dec-98 aph) first generated
     (11-Jan-99 aph) removed print lines
     (04-jul-99 aph) correct for images
     (28-dec-99 aph) correct for images (after extracting ax_image_add from axis_c)
     (31-dec-99 aph) spectral meshing ; AXIS standard documentation
     (09-jun-04 aph) include energy in output structures
     (21-apr-05 aph) add option to force mech to the first file (spectra only)

(See c:\axis2000\ax_mesh.pro)

## AX_NAME

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_NAME

    LAST CHANGED: ----------------------------------- 11-Oct-08 (aph, jso)

    PURPOSE:
    	This function parses an arbitrary text string as
     a filename and returns independently the path, main_name, & extension
     The path ends with the separator appropriate to the current operating system.
     The separator of the main_name & extension is not returned.

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = ax_name(FILENAME)

    CALLED FROM AXIS:
    	(MANY PLACES)

    KEYWORDS: none

    INPUT: string with filename

    OUTPUTS:
    	RESULT - 3-element array:
     result(0) = path    result(1) = main_name    result(2) = extension

    COMMON BLOCKS: none

    EXAMPLE:
     Create a name and parse it
    	name = 'c:\axis\axis_dev\test-code\circle.axb'
    	t = ax_name(name)
    	print, t(0), '   ', t(1), '   ', t(2)
       	c:\axis\axis_dev\test-code\   circle   axb

     MODIFICATION HISTORY:
     (25-jun-99 aph) first developed
     (13-aug-06 jso) ensure compatible with 532 - string aray element 0 specified
     (11-Oct-08 aph) adapt to work with main names containing '.'s - assume extension
                     is all parts of string from back to first '.' (NB may not work with IDL 5.1)

(See c:\axis2000\ax_name.pro)

## AX_NC2GIF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_NC2GIF

    LAST CHANGED: ----------------------------------- 31-dec-99

     PURPOSE:
    	This procedure converts one or a series of NetCDF image files
     into gif format. Written for use with ENVI principle component procedures.

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	AX_NC2GIF

     INPUTS:
    	FILE - a NetCDF image file (*.nc) to be converted to gif (*.gif)

     KEYWORDS: none

     OUTPUTS:
      FILE.gif - image written as a GIF byte-scaled image file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS
       @BSIF_COM - common block for netCDF

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     PROCEDURE:

     RESTRICTIONS:
    	ax_nc2gif assumes that filename has a sequence number is cols.6-8
     This works with  X1A  (ddMMMxxx.nc) and ALS2NCDF (YMMDDxxx.nc) filenames

     MODIFICATION HISTORY:
     (31-dec-99 aph) isolated from AXIS_C; standard documentation

(See c:\axis2000\ax_nc2gif.pro)

## AX_ONE_PT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_ONE_PT

    LAST CHANGED: ----------------------------------- 9-sep-02

    PURPOSE:
    	This procedure allows the user to delete or add a single point in a spectrum
     or to change a point in an image

    CATEGORY:
    	AXIS: spectrum analysis (captive to aXis2000)

    CALLING SEQUENCE:
    	AX_ONE_PT

    CALLED FROM AXIS:
    	Spectra->Modify one point
    	Images->Modify one point

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	modified spectrum or image is placed in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (09-sep02 aph) first version; adapted from zx_xycal.pro

(See c:\axis2000\ax_one_pt.pro)

## AX_ORDER

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_ORDER

    LAST CHANGED: ----------------------------------- 14-nov-00

    PURPOSE:
    	This function forces image data in a structure
     to adopt increasing (x,y) values

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = AX_ORDER(structure)

    CALLED FROM AXIS:
    	PlotBuf

    INPUTS:
    	s_in - AXIS 2d structure

    KEYWORDS: none

    OUTPUTS:
    	Result = AXIS 2d structure with x, y values increasing

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	Image data is also reversed to preserve image position information.

    MODIFICATION HISTORY:
     ( 6-jul-99 aph) first developed to get correct lineouts
     (31-dec-99 aph) AXIS standard documentation
     (14-nov-00 cgz) Replaced calls to GET_RANGE function with ecplicit MIN and MAX calls

(See c:\axis2000\ax_order.pro)

## AX_PARTICLES

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PARTICLES

    LAST CHANGED: ----------------------------------- 19-dec-00

    PURPOSE:
    	This FUNCTION derives particle sizes from masked images
      A histogram of the particles sizes is generated.

    CATEGORY:
    	STAND ALONE: image processing

    CALLING SEQUENCE:
    	Result = AX_PARTICLES( [ ])

    CALLED FROM AXIS:
    	->Images->Particle analyze

    ROUTINES
    	add_part(i,j) - function that adds (i,j) pixel to list
    	ax_p_adj(i,j) - function that checks 4-adjacent pixels to see if they are 1

    INPUTS:
    	INPUT - POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

    KEYWORDS:
          SIMAGE =  image in AXIS structure format
                    (if not included; user is prompted for an AXIS format image)
          FILE  =  name of file to read (AXIS binary (*.axb))
          AXIS_ON = flag indicating AX_PARTICLES is being run from AXIS

    OUTPUT:
          array indicating size of all particles

    OPTIONAL OUTPUT
         when run stand alone, ;
              the image is plotted with particles indicated
              a histogram of the particles sizes is plotted

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
      ax_part, image, particles, nx, ny, p, np, p_now, npix
                   - common for ax_particles only

    PROCEDURE:
    	This function is meant to apply to MASKED data (use Generate_mask
     to convert image to (1/0) map based on user-selected threshold.
     AX_PARTICLES then loops through all pixels. When it finds a 1
     it searches all 4 adjacent pixels (N,S,E,W), marking those alos 1, until
     a local search no longer finds 1's. The number of pixels defines
     the size of that particle
     It returns an ARRAY p(np) listing the size (in pixels) of each particle.
     The array for currently analysed particle is p_now(npix,2)
     where npix is the number of pixels in particle np
           np is the number of particles
           2nd index of p_now: 0 = x, 1 = y index co-ordinate in image

    MODIFICATION HISTORY:
     (04-oct-99 aph) first developed
     (31-dec-99 aph) AXIS standard documentation
     (16-jan-00 aph) add lower, upper bound and display
     (09-dec-00 cgz) modified names of color indices (blue and green)
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index

(See c:\axis2000\ax_particles.pro)

## AX_PAR_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PAR_LOAD

    LAST CHANGED: ----------------------------------- 04-jun-03

    PURPOSE:
    	This function reads path and file names of reference spectra used in
     stack  (ax_svd, stack_fit, cgo_fit), line (line_fit) and spectra ( ax_curvefit) fitting procedures

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	PARS = AX_PAR_LOAD (par_file)

    CALLED FROM AXIS:
    	stacks~maps~(ax_svd, stack_fit, cgo_fit); linescans~line fit; spectra~curve fit

    INPUTS:
    	PAR_FILE - name of parameter file

    KEYWORDS: none

    OUTPUTS:
    	PARS = structure (n = number of ref. spectra; names = names; files = filenames)
              or 0 if there is an error in reading par file or locating files

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	Path is determined from par file. If files not foud, check if DefPath works, then ask user

    MODIFICATION HISTORY:
     (04-jun-03) first developed from duplicates in stack fitting routines

(See c:\axis2000\ax_par_load.pro)

## AX_PAR_SAVE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PAR_SAVE

    LAST CHANGED: ----------------------------------- 04-jun-03

    PURPOSE:
    	This procedure writes path, and file names of reference spectra used in
     stack  (ax_svd, stack_fit, cgo_fit), line (line_fit) and spectra ( ax_curvefit) fitting procedures

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	AX_PAR_SAVE,par_file, ncomp, comp_names, comp_files

    CALLED FROM AXIS:
    	stacks~maps~(ax_svd, stack_fit, cgo_fit); linescans~line fit; spectra~curve fit

    INPUTS:
    	PAR_FILE	parameter file name
    	NCOMP	number of components
    	COMP_NAMES - (ncomp) 1-d array of fit names
    	COMP_FILES - (ncomp) 1-d array of files

    KEYWORDS: none

    OUTPUTS:
    	none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	Path is determined from comp_names

    MODIFICATION HISTORY:
     (04-jun-03) first developed from duplicates in stack fitting routines

(See c:\axis2000\ax_par_save.pro)

## AX_PC

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PC

    LAST CHANGED: ----------------------------------- 17-sep-08

    PURPOSE:
    	This procedure executes the PCOMP principle component analysis
     on an arbitary number of images for arbitrary number of components

    CATEGORY:
    	STAND ALONE: image analysis

    CALLING SEQUENCE:
    	AX_PC [,stack = ncb_file, standardize = standardize, axis=1]

    CALLED FROM AXIS:
    	->Stacks->Principle Components

     INPUTS:
    	all inputs are either from files identified by keywords or by a pickfile dialog

     KEYWORD PARAMETERS:
    	AXIS = if on, then called from AXIS widget
    	HELP = print how-to-use statement
    	IMAGES = file with list of images to be analysed
       STACK = name of a binary format stack (*.ncb)
    	STANDARDIZE = standardize input (mean of zero and variance of one).

     OUTPUTS:
    	all outputs are either to files via dialog or to AXIS buffers

     COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	stack_process_com
    	COMMON volume_data, image_stack
    	bsif_com

    PROCEDURE:
      This procedure uses the IDL code (PCOMP.SAV - nb no source provided)
      to compute the eigenvalues (strengths) and eigenvectors (principle components)
      from a set of spectromicroscopy images

    MODIFICATION HISTORY:
     (28-oct-99 aph) first written (adapted ax_svd to use stack read_in)
     (31-dec-99 aph) AXIS standard documentation
     (27-feb-00 aph) add groupID to get_text
     (14-may-00 aph) make cancel abort first time
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_pc.pro)

## AX_PEEM_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PEEM_COM.PRO

    LAST CHANGED: ----------------------------------- 20-Jan-07

    PURPOSE:
    	This INCLUDE file contains COMMON blocks for AX-PEEM-READ widget.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE: @ax_peem_com

     COMMON BLOCKS
    	-------- COMMON PEEM -------------------
    	axis_on			if set, axis2000 running
    	dark_path		dark file path
    	gain_path		gain file dath
    	peem_aoi		Area of Interest file
    	peem_aoi_dark	if set, apply AOI to dark file
    	peem_aoi_gain	if set, apply AOI to gain file
    	peem_bin		binning (nXn) reduced to 1 pixel (default = 1)
    	peem_bits12		if set, all data files are 12-bit (ALS PEEM-2 camera default)
    	peem_col12		gives number of columns to drop for 12-bit readin (to avoid header noise)
    	peem_dark		dark data file
       peem_dark_avg	if set, average multiple dark files
       peem_dark_last	number of final dark of a sum of dark files
    	peem_dwell		exposure time (sec)
       peem_E			energy (eV)
    	peem_first		first/single data file
    	peem_gain		gain data file
    	peem_ID			Widget ID
    	peem_last		last data file
    	peem_median		if set, 3-point median smooth
    	peem_multi		if set, then multiple file conversion to net_CDF
       peem_ncb        if set, write directly to ncb file (no *.nc)
    	peem_process	string defining action
    				('no correct', dark correct', 'gain correct', dark and gain correct')
    	peem_region		if set, select a subregion, in real space parameters
    	peem_scale		size of pixel (um)
    	peem_sphinx     flag that data format is sphinx
       peem_3			flag that data format is ALS peem3 (jan07)
    	peem_struct		output of the ax_peem_read function (structure or a flag)
    	region 			4-vector defining xmin, xmax, ymin, ymax of region
    	source_path		source path

     NAMES AND MEANING OF COMMON VARIABLES
     *************************************************************************
     ***********         AX_PEEM_READ PARAMETERS            ******************
     *************************************************************************

    MODIFICATION HISTORY:

(See c:\axis2000\ax_peem_com.pro)

## AX_PEEM_READ

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     AX_PEEM_READ

    LAST CHANGED: ----------------------------------- 12-Sep-07

     PURPOSE:
    	This file contains the codes for a WIDGET used to define parameters
     and read in one or a sequence of PEEM data files from various PEEMs
     12-bit or 16-bit ALS PEEM2 format, ALS PEEM3 format (ALS PEEM3 read with separate widget)
     and 16-bit SPHINX (SRC, Labview generated) files are read.

     CATEGORY:
    	Image input (stand alone, axis2000)

     CALLING SEQUENCE:
     for procedures:
    	Result = AX_READ_PEEM()

     INPUTS: none - widget defines inputs for RD_PEEM

     KEYWORDS
     SPHINX - adapt to Sphinx format data (16-bit tif; dat multicolumn energy)
     AXIS - called from axis
     MULTI - multiple files (image sequence)
     COL12 - 12-bit data (old ALS camera)
     PEEM3 - data format for ALS PEEM3
     GROUP_LEADER - group leader variable
      _EXTRA - extra parameters

     CONTENTS
    	BUT_Cancel		cancel job; kill widget
    	BUT_Read_data	execute job (parameters from AX_PEEM_COM set in widget)
    	BUT_no_correct	set no_correction
    	BUT_subtract_dark set subtract_dark
    	BUT_gain  		set gain_correction
    	BUT_dark_gain	set dark & gain correction
    	BUT_median		switch for mediam smooth
    	BUT_bits12		switch for 12-bit / 16-bit

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
       ANALCOM     stack_analyse common
    	BSIF_COM	common for netCDF format data
     	AX_PEEM_COM	default path and filename information specific to PEEM
    	-------- COMMON PEEM -------------------
    	axis_on			if set, axis2000 running
    	dark_path		dark file path
    	gain_path		gain file dath
    	peem_aoi		Area of Interest file
    	peem_aoi_dark	if set, apply AOI to dark file
    	peem_aoi_gain	if set, apply AOI to gain file
    	peem_bin		binning (nXn) reduced to 1 pixel (default = 1)
    	peem_bits12		if set, all data files are 12-bit (ALS PEEM-2 camera default)
    	peem_col12		gives number of columns to drop for 12-bit readin (to avoid header noise)
    	peem_dark		dark data file
       peem_dark_avg	if set, average multiple dark files
       peem_dark_last	number of final dark of a sum of dark files
    	peem_dwell		exposure time (sec)
       peem_E			energy (eV)
    	peem_first		first/single data file
    	peem_gain		gain data file
    	peem_ID			Widget ID
    	peem_last		last data file
    	peem_median		if set, 3-point median smooth
    	peem_multi		if set, then multiple file conversion to net_CDF
       peem_ncb        if set, write directly to ncb file (no *.nc)
    	peem_process	string defining action
    				('no correct', dark correct', 'gain correct', dark and gain correct')
    	peem_region		if set, select a subregion, in real space parameters
    	peem_scale		size of pixel (um)
    	peem_sphinx     flag that data format is sphinx
       peem_3			flag that data format is ALS peem3 (jan07)
    	peem_struct		flag indicating success (1) or failure (0) of conversion
    	region 			4-vector defining xmin, xmax, ymin, ymax of region
    	source_path		source path

     SIDE EFFECTS:
    	A widget is created/destroyed. If run standalone, result is plotted.

     MODIFICATION HISTORY:
     (05-jun-01 aph) first version; AXIS standard header added
     (31-jun-01 aph) enabled, non-functional
     (12-aug-01 aph) got working in Aug 1-12 period
     (08-may-01 aph) adapt to convert Elmitec PEEM (sphinx); through *.nc and directly to NCB
     (16-jul-02 aph) adapt to 8-bit tif file name convention (Sphinx)
     (05-oct-02 aph) auto-sort energies
     (02-nov-02 aph) increase file numbering scheme for sphinx data to full 5-digit format
     (17-feb-03 aph) fixed problem of extension in filename parsing
     (18-mar-03 aph) correction for file numbering error introcuded by ALS change into sphinx !
     (02-may-04 aph) change header
     (20-nov-04 aph) fix problem of not working in VM mode
     (13-aug-05 aph) fix not working in IDL6.1 (SGU bug report Aug-05: PEEM_ID not valid for tmp files)
     (22-feb-06 aph) fix not working - problem was that single images are not sent back to aXis2000 !!
     (20-jan-07 aph) adapt for ALS PEEM3 images (but eventually used a separate widget based on Scholl routines)
     (12-Sep-07 aph) clean up; adapt for use of ax_cimage to remove extrema to remove columns (NB NOT changed for stacks)

(See c:\axis2000\ax_peem_read.pro)

## AX_POL_FIT[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_POL_FIT

    LAST CHANGED: ----------------------------------- 	19-Feb-07

     PURPOSE:
    	This function fits a curve of I(angle) to the expression for
     photoexcitation polarization dependence:
            I = constant + amplitude(Angle-AngleRef)
     using CURVEFIT (IDL non-linear least squares fit)
     Equal weighting of all data points is used

     CATEGORY:
     Data analysis; called from axis2000 spectra~curefit~ax_pol_fit
     Used as part of fit to polarization maps

     CALLING SEQUENCE:
    	Result = AX_POL_FIT(CURV, MAX_ITER=MAX_ITER, PARAM=PARAM, SIGMA=SIGMA, TOL=TOL)

     INPUTS:
      CURV:   (angle, intensity) 2-d array

     KEYWORDS:
     MAX_ITER:	if defined, the maximum number of iterations (default = 20)
     SIGMA: 	if defined, returns the standard definition
     SILENT:	if set, do not report results in axis or IDL log
     STATUS	if set, returns the status of the fit
    			    (0 = successful; 1 = divergent, 2 = non-convergent)
     PARAM;	if defined, gives & returns the (constant, amplitude, angle_reference) values
     TOL:    	if defined, the tolerance (default = 1e-8)

     OUTPUTS:
      the fit function

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     EXAMPLE: see IDL help file for example this was modelled from

     MODIFICATION HISTORY:
     (04-May-06 aph) first derived
     (25-Jan-07 aph) set default tolerance to 1e-6, max iter to 500
     (19-Feb-07 aph) change sign in fit function

(See c:\axis2000\ax_pol_fit-19feb07.pro)

## AX_POL_FIT[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_POL_FIT

    LAST CHANGED: ----------------------------------- 	19-Feb-07

     PURPOSE:
    	This function fits a curve of I(angle) to the expression for
     photoexcitation polarization dependence:
            I = constant + amplitude(Angle-AngleRef)
     using CURVEFIT (IDL non-linear least squares fit)
     Equal weighting of all data points is used

     CATEGORY:
     Data analysis; called from axis2000 spectra~curefit~ax_pol_fit
     Used as part of fit to polarization maps

     CALLING SEQUENCE:
    	Result = AX_POL_FIT(CURV, MAX_ITER=MAX_ITER, PARAM=PARAM, SIGMA=SIGMA, TOL=TOL)

     INPUTS:
      CURV:   (angle, intensity) 2-d array

     KEYWORDS:
     MAX_ITER:	if defined, the maximum number of iterations (default = 20)
     SIGMA: 	if defined, returns the standard definition
     SILENT:	if set, do not report results in axis or IDL log
     STATUS	if set, returns the status of the fit
    			    (0 = successful; 1 = divergent, 2 = non-convergent)
     PARAM;	if defined, gives & returns the (constant, amplitude, angle_reference) values
     TOL:    	if defined, the tolerance (default = 1e-8)

     OUTPUTS:
      the fit function

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     EXAMPLE: see IDL help file for example this was modelled from

     MODIFICATION HISTORY:
     (04-May-06 aph) first derived
     (25-Jan-07 aph) set default tolerance to 1e-6, max iter to 500
     (19-Feb-07 aph) change sign in fit function

(See c:\axis2000\ax_pol_fit-aph.pro)

## AX_POL_FIT[3]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_POL_FIT

    LAST CHANGED: ----------------------------------- 	19-Apr-08

     PURPOSE:
    	This function fits a curve of I(angle) to the expression for
     photoexcitation polarization dependence:
            I = constant + amplitude(Angle-AngleRef)
     using CURVEFIT (IDL non-linear least squares fit)
     Equal weighting of all data points is used

     CATEGORY:
     Data analysis; called from axis2000 spectra~curefit~ax_pol_fit
     Used as part of fit to polarization maps

     CALLING SEQUENCE:
    	Result = AX_POL_FIT(CURV, MAX_ITER=MAX_ITER, PARAM=PARAM, SIGMA=SIGMA, TOL=TOL)

     INPUTS:
      CURV:   (angle, intensity) 2-d array

     KEYWORDS:
     MAX_ITER:	if defined, the maximum number of iterations (default = 20)
     SIGMA: 	if defined, returns the standard definition
     SILENT:	if set, do not report results in axis or IDL log
     STATUS	if set, returns the status of the fit
    			    (0 = successful; 1 = divergent, 2 = non-convergent)
     PARAM;	if defined, gives & returns the (constant, amplitude, angle_reference) values
     TOL:    	if defined, the tolerance (default = 1e-8)

     OUTPUTS:
      the fit function

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     EXAMPLE: see IDL help file for example this was modelled from

     MODIFICATION HISTORY:
     (04-May-06 aph) first derived
     (25-Jan-07 aph) set default tolerance to 1e-6, max iter to 500
     (19-Feb-07 aph) change sign in fit function
     (19-Apr-08 aph) added /noderivative ot make ref angle fit better (from Martin Obst 25-Mar-08)

(See c:\axis2000\ax_pol_fit.pro)

## AX_POL_MAP[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	  AX_POL_MAP

    LAST CHANGED: ----------------------------------- 18-mar-07

    PURPOSE:
    	This procedure fits a stack of angle dependent images
     to I(angle)=constant + amplitude*cos^2(angle-angle_Ref)
     with provision to force the reference angle within unser-set limits

    CATEGORY:
    	AXIS:  polarization stack analysis (operates stand-alone as well)

    CALLING SEQUENCE:
     for procedures:
    	AX_POL_MAP(/AXIS,/verbose)

    CALLED FROM AXIS:
    	->Stacks->maps~polarization fit

    INPUTS:
    	All input parameters are obtained through user dialogs.

    KEYWORDS:
    	AXIS - if set, indicates called from AXIS
    	VERBOSE - if set, displays results as generated line-by-line (SLOW!)

    ROUTINES
    	AX_POL_FIT - main routine

    OUTPUTS:
    	If run from AXIS, the results are placed in AXIS buffers
     buffer 4 = contant
     buffer 5 = amplitude
     buffer 6 = reference angle
     buffer 7 - Standard deviation of the constant
     buffer 8 - Standard deviation of the amplitude
     buffer 9 - Standard deviation of the ref. angle

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@ANALCOM  - STACK (cjj)
    	Volume_data - STACK
     	@BSIF_COM - nc data

    PROCEDURE:
    	Uses ax_pol_fit applied to the curve at each pixel

    MODIFICATION HISTORY:
     ***********
     (04-May-06 aph) first developed from stack_fit.pro
     (19-Feb-07 aph) make tolerance a parameter; report no-change parameters
     (18-mar-07 aph) add limits to ref_angle

(See c:\axis2000\ax_pol_map-aph.pro)

## AX_POL_MAP[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	  AX_POL_MAP

    LAST CHANGED: ----------------------------------- 18-sep-08

    PURPOSE:
    	This procedure fits a stack of angle dependent images
     to I(angle)=constant + amplitude*cos^2(angle-angle_Ref)
     with provision to force the reference angle within unser-set limits

    CATEGORY:
    	AXIS:  polarization stack analysis (operates stand-alone as well)

    CALLING SEQUENCE:
     for procedures:
    	AX_POL_MAP(/AXIS,/verbose)

    CALLED FROM AXIS:
    	->Stacks->maps~polarization fit

    INPUTS:
    	All input parameters are obtained through user dialogs.

    KEYWORDS:
    	AXIS - if set, indicates called from AXIS
    	VERBOSE - if set, displays results as generated line-by-line (SLOW!)

    ROUTINES
    	AX_POL_FIT - main routine

    OUTPUTS:
    	If run from AXIS, the results are placed in AXIS buffers
     buffer 4 = contant
     buffer 5 = amplitude
     buffer 6 = reference angle
     buffer 7 - Standard deviation of the constant
     buffer 8 - Standard deviation of the amplitude
     buffer 9 - Standard deviation of the ref. angle

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@stack_process_com
    	Volume_data - STACK
     	@BSIF_COM - nc data

    PROCEDURE:
    	Uses ax_pol_fit applied to the curve at each pixel

    MODIFICATION HISTORY:
     ***********
     (04-May-06 aph) first developed from stack_fit.pro
     (19-Feb-07 aph) make tolerance a parameter; report no-change parameters
     (18-mar-07 aph) add limits to ref_angle
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_pol_map.pro)

## AX_PROF_RAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_PROF_RAD

    LAST CHANGED: ----------------------------------- 12-sep02

    PURPOSE:
     This procedure generates radial profiles from images.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
    	AX_PROF_RAD [, axis = axis]

    CALLED FROM AXIS:
    	->Images->Profiles->Radial

     INPUTS:
    	Uses data in currently displayed buffer

     KEYWORDS
    	AXIS - if set, indicates called from AXIS

     OUTPUT
     (1) average diameter profile spectrum (put into user selected buffer)
     (2) linearized diametric profile image (put into user selected buffer)
     further analysis of the radial profile can be done using the linescan routines

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

     RESTRICTIONS
     Must be called from AXIS

    PROCEDURE:
    	The user identifies a diameter across the structure
     of interest, and selects the sampling mode: Linear (1) or Circular (2).
     The routine samples the image as requested
     and generates the avarage diametric profile as well as an angular map (0-180o)
     Optional symmetrization and alignment routines are included.

    MODIFICATION HISTORY:
     (26-dec-99 aph) first isolated from AXIS_C (written Dec-99)
     (31-dec-99 aph) AXIS standard documentation
     (23-feb-00 aph) add groupID to call to buffer
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
     (12-sep-02 aph) use correct groupID for buffer !

(See c:\axis2000\ax_prof_rad.pro)

## AX_RD_IM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_RD_IM

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
    	This procedure reads ALS BL7 image files (*.im*) and
     converts all files of same main name to a a single NetCDF format file.
     used by AXIS to process ALS *.im* to *.nc files for use in stack_analyze
     designed to process one file at a time
     e.g. {90123001.im0, 90123001.im1} -> 90123001.nc

    CATEGORY:
    	AXIS: stack analysis

    CALLING SEQUENCE:
    	AX_RD_IM [, fileheader, bin=bin, img=img, help = help]

    CALLED FROM AXIS:
    	->Stacks->bin NSLS->{1,file}

    INPUTS:
    	FILEHEADER - file with list of filenames

    KEYWORDS:
    	BIN - smooth the image by binnning (e.g. bin =2 -> 2x2 -> 1 pixel)
     	IMG - sets filter to '*.img' for old-style ALS filenames
    	HELP - prints a help message

    OUTPUTS:
    	No explicit outputs.   A new window is created if necessary

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	The filenames in FILEHEADER are read
     Each file is read in using explicit open, readf, close commands
     and therefore is dependent on knowing the explicit structure
     of the ALS BL7.0 data files. Asssumes post Dec-97 filestructure.

    MODIFICATION HISTORY:
     (Jacobsen, Jan-98) reads ALS data and structures it as a netCDF file (nsls)
     (aph 23-Feb-98) added other parameters (SD = scan data) and binning
     (aph 5-mar-98) set-up as an axis-specific routine to avoid conflict with CJ
     (aph 16-Aug-98) removed processing of *.lst files written by STXM.vi
     (aph 7-jan-99) trouble-shooting readin (Common name wrong !)
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_rd_im.pro)

## AX_READ_ROI

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_READ_ROI

    LAST CHANGED: ----------------------------------- 	29-Dec-08

     PURPOSE:
    	This function reads a roi from different formats and saves it as a 0/1 mask-image

     CATEGORY:
    	Image display.

     CALLING SEQUENCE:

     for functions:
    	Result = AX_READ_ROI(file-file, filter=filter, roi_type=roi_type, template=template)

     INPUTS:
    	All input parameters are passed as keywords.

     KEYWORDS:
    	FILE:  name of file ; if not supplied, program requests it
     	FILTER:   extension
    	ROI_TYPE: type of region of interest (stack, peem2, lox)
       TEMPLATE:   AXB image defining the x, y scales and pixel numbers (*.axb)

     OUTPUTS:
    	internal axis format structure is generated

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     RESTRICTIONS:
    	only reads the I_roi portion; format supports storage of both Io_roi and I_roi

     MODIFICATION HISTORY:
     (28-jan-06 aph) first version; STACK ROI read-in taken from stack_analyze
     (09-Feb-06 aph) extend to PEEM2 AOI files
     (12-jun-06 aph) extend to Lox ROI files
     (29-Dec-08 aph) add title to guide user when need ot get template image from disk

(See c:\axis2000\ax_read_roi.pro)

## AX_READ_XAS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_READ_XAS

    LAST CHANGED: ----------------------------------- 22-feb-00

    PURPOSE:
    	This function reads in data from an ascii XAS format file (annotated spectral format)
     and places the result into an AXIS 1d structure.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	Result = ax_read_xas(file = file, nof = nof)

    CALLED FROM AXIS:
    	->Read->NSLS->XAS

    INPUTS:
    	INPUT - POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

    KEYWORDS:
    	FILE = filename. If not supplied the user is prompted.
       NOF = no filter (default is *.xas)

    OUTPUTS:
    	The result is placed in buffer 0.

     PROCEDURE:
       Uses X1A routine READ_XAS.PRO to read data, then packages as an AXIS 1d structure.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (22-feb-00 aph) AXIS standard documentation

(See c:\axis2000\ax_read_xas.pro)

## AX_REGRESS_SPECTRA

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_regress_spectra

    LAST CHANGED: ----------------------------------- 22-Jun-05

    PURPOSE:
    	This procedure uses linear regression to fit a spectrum to a set of reference spectra.
     AX_REGRESS_spectra will run stand alone (prompting user for AXIS format files) or from AXIS.

    CATEGORY:
    	STAND ALONE: spectral analysis

    CALLING SEQUENCE:
    	AX_REGRESS_SPECTRA[SPC, axis=axis, help = help]

    CALLED FROM AXIS:
    	->{Spectra}->Curve Fit~linear regression

    INPUTS:
    	SPC		spectrum to be fit in axis 1d structure form

    KEYWORDS:
     AXIS 		called from AXIS widget
     COEFF		filename with spectral information
     HELP		print help text

    OUTPUTS: 	No ecoefflicit outputs.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	The reference spectra are read in and the coefficient matrix generated.
     REGRESS is then called to get the fittin coefficients

    MODIFICATION HISTORY:
     (03-feb-05 aph) first version - adapted from ax_curvfit (20-oct-04 version)
     (19-feb-05 aph) correct final display
     (22-jun-05 aph) fix display of results (axis_log); switch to avoid 'regress' in IDL5.2

(See c:\axis2000\ax_regress_spectra.pro)

## AX_RGB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_RGB

    LAST CHANGED: ----------------------------------- 18-Sep-05 (aph)

     PURPOSE:
    	This procedure allows user to select 3 images from existing buffers
     and generates an RGB composite image, with optional storage.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	AX_RGB [, NO_SAVE=NO_SAVE]

    CALLED FROM AXIS:
    	->Utilities->RGB composite

    INPUTS: none

    KEYWORDS:
    	NO_SAVE  - do not ask for file name

    OUTPUTS: RGB image in MainImg and (optional) tif file on disk

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (18-sep-05 aph) first written; generated from images~RGB composite in axis_c

(See c:\axis2000\ax_rgb.pro)

## AX_RGB_COM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_RGB_COM

    LAST CHANGED: ----------------------------------- 29-Dec-07

     PURPOSE:
    	This FILE contains the COMMON block, AX_RGB_COM

     CATEGORY:
    	AXIS: AX_RGB_COM common block

     CALLING SEQUENCE:
    	@AX_RGB_COM (to include in the stack_analyse routines)

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (28-dec-07 aph) first version

(See c:\axis2000\ax_rgb_com.pro)

## AX_RGB_MAP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_RGB_MAP

    LAST CHANGED: ----------------------------------- 	29-Dec-07

     PURPOSE:
    	This set of procedures is a widget which generates R_G-B composite maps
      It allows mage selection and ; adjustment of min/max scales for each color.
     A color circle and separate R, G, B color scales can be optionally selected

     CATEGORY:
    	aXis2000 capitve. Image display.

     CALLING SEQUENCE:
    	AX_RGB_MAP

     INPUTS: default set of buffers are R=4, G=5, B=6

     KEYWORDS: none

     OUTPUTS:
     (optional)  a TIF image of the RGB composite map can be stored

     AX_RGB_MAP_EVENT ROUTINES:

     NUM_FORMAT		standard number format for limits
     MAKERGB			generate composite image
     LIST_RGB_RED		select buffer for RED
     LIST_RGB_GREEN	select buffer for GREEN
     LIST_RGB_BLUE		select buffer for BLUE
     BUT_RGB_CIRCLE	on/off color circle display
     BUT_RGB_SCALES	on/off R, G, B scales
     SLIDER_R			adjust red min / max value
     SLIDER_G			adjust green max value
     SLIDER_B			adjust blue max value
     TEXT_RGB_RMAX		adjust red max value
     TEXT_RGB_GMAX		adjust green max value
     TEXT_RGB_BMAX		adjust blue max value
     TEXT_RGB_RMIN		adjust red min value
     TEXT_RGB_GMIN		adjust green min value
     TEXT_RGB_BMIN		adjust blue min value
     ABSOLUTE_SCALE	set all colors to global limits
     RGB_RESCALE		set each color to limits of its data
     BUT_RGB_CANCEL	cancel
     BUT_RGB_SAVE		save composite map

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	AX_RGB_COM  parameters specifc to ax_rgb_map

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:
    	Any known ?

     MODIFICATION HISTORY:
     (16-Jun-03 aph) first verasion started
     (10-Mar-06 aph) widget structure generated from AX_RGB_WIDGET.PRC
     (29-Dec-07 aph) coded

(See c:\axis2000\ax_rgb_map.pro)

## AX_RGB_WIDGET

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_RGB_WIDGET

    LAST CHANGED: ----------------------------------- 	20-apr-08

     PURPOSE:
    	This set of procedures is a widget which generates R_G-B
     composite maps with full control on source, limits etc
     uses CW_slider - a complex slider with 2-levels of control taken from web (Thomas Döring, June 2007)

     CATEGORY:
    	Image display - captive to aXis2000

     CALLING SEQUENCE:
     for procedures:
    	AX_RGB_WIDGET

     INPUTS: default set of buffers are R=4, G=5, B=6 if not previously selected

     KEYWORDS: none

     OUTPUTS:
    		RGB image saved as a tif file

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	AX_RGB_COM  common block  for AX_RGB_WIDGET

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:

     MODIFICATION HISTORY:
     (10-Mar-06 aph) widget structure first generated
     (26-Dec-07 aph) coded
     (20-apr-08 aph) clean up description

(See c:\axis2000\ax_rgb_widget.pro)

## AX_ROTATE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_ROTATE

    LAST CHANGED: ----------------------------------- 02-jan-02

    PURPOSE:
    	This procedure rotates 2-d data (images) about a user defined point.
     It depends on geting data from AXIS2000 data buffers

    CATEGORY:
    	AXIS: image processing

    CALLING SEQUENCE:
    	AX_ROTATE, TMP, ANGLE=ANGLE, CENTRE=CENTRE, PIXELSIZE=PIXELSIZE, MINVAL=MINVAL

    CALLED FROM AXIS:
    	(images~rotate)

     INPUT:
     TMP -  image

    KEYWORDS:
     ANGLE		rotation angle
     CENTRE	[x,y] - centre for rotation in data units
     PIXELSIZE	size of pixels to mesh to (in microns)
     MAXDIST	maximum distance from centre to a corner (sets size of output image)
     MINVAL	if = 1 then set outside regions to minimum in image

     OUTPUT
    	rotated 2-d structure is placed in buffer 0

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (15-nov-01 aph) isolated from axis2000
     (25-nov-01 aph) make added region have the average color of the image
     (31-dec-01 aph) introduce keywords to allow operation without user input
    			give option for minimum or average color for extending image
    			change from function to procedure; add max_distance keyword
     (02-jan-02 aph) remove pivot keyword in call to ROT

(See c:\axis2000\ax_rotate.pro)

## AX_SDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SDF

    LAST CHANGED: ----------------------------------- 19-May-07

    PURPOSE:
    	This set of procedures is a widget to read in files
     in the ascii self defining format (SDF) developed initally for ALS BL 5.3.2 STXM
     The widget uses read_sdf and parse_sdf to perform the file input.

    CATEGORY:
    	AXIS: utility

     AX_SDF_EVENT ROUTINES:
     TEXT_SDF_FNAME		modify filename; when changed, execute BUT_SDF_FNAME_BROWSE to get parameters
     BUT_SDF_FNAME_BROWSE 	browse for new filename; if found, load new parameters
     BUT_SDF_DISPLAY_HDR   show parameters
     BUT_SDF_OK			proceed with loading SDF file into AXIS
     BUT_SDF_CANCEL		abort read in
     WID_DLIST_CHANNEL		drop list used to display and select the data channel
     WID_DLIST_REGION		drop list to display and select region

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@SDF_COM 	structure with header info

    MODIFICATION HISTORY:
     (25-feb-01 aph) first written using IDL 5.2 GUIBuilder
     (27-jun-01 aph) add groupID for better feedback on reads
     (29-jul-01 aph) add regions selector to the panel; introduced sdf_com; reverted to pickfile2
     (19-aug-01 aph) adapt to regions change & change in structure names; define regions & channels
     (04-nov-01 aph) add sdf_lastfile to sdf_com to save last name
     (09-nov-01 aph) activate all_regions read-in for spectra and images
     (26-nov-01 aph) complete use of name label as a way to select file
     				  add specific image read-in for stacks - incomplete !!
     (31-dec-01 aph) make defaut width of display parameters = 132
     (17-feb-02 aph) 'motor scan'; single images from sequences
     (11-dec-02 aph) VLM images read-in
     (17-oct-04 aph) separate PATH box; reload last file info  if possible
     (28-oct-04 aph) ensure works if SDF_Path or SDF_lastfile are not defined (at startup)
     (19-feb-05 aph) stack-map, single image read in added
     (12-mar-05 aph) make single image read-in work with IDL5.2
     (17-Jun-05 aph) channels and regions working for map and 1-image read-in
     (13-Nov-05 aph) got rid of last call involving 'group=SDF_ID'
     (22-Mar-06 aph) add Normalize indicator on panel
     (11-mar-07 aph) add normalization control to panel (sets norm_flag)
     (18-May-07 aph) correct read-in of 1-image for multi-channel data (B. Watts)

(See c:\axis2000\ax_sdf.pro)

## AX_SDF_EARLY

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_sdf_EARLY

    LAST CHANGED: ----------------------------------- 21-aug-01

    PURPOSE:
    	This set of procedures constitute a widget to read in files
     in the ascii self defining format (SDF). The widget uses
     read_sdfe and parse_sdf to actually do the file input.

    CATEGORY:
    	AXIS: utility

     AX_sdfE_EVENT ROUTINES:
     TEXT_sdfE_FNAME		modify filename; when changed, execute read_sdfe
     BUT_sdfE_FNAME_BROWSE 	browse for new filename
     BUT_sdfE_OK			proceed with loading SDF file into AXIS
     BUT_sdfE_CANCEL		abort read in
     WIDE_DLIST_CHANNEL		drop list used to display and select the data channel
     ax_sdfE_eventcb		auto loading stub

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	sdfE_EVENT, SDF	structure with header info

    MODIFICATION HISTORY:
     (25-feb-01 aph) first written using IDL 5.2 GUIBuilder
     (21-aug-01 aph) rescued to enable readin of early files

(See c:\axis2000\ax_sdfe.pro)

## AX_SDF_EVENTCB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SDF_EVENTCB

    LAST CHANGED: ----------------------------------- 04-nov-01

    PURPOSE:
    	This set of procedures constitute a widget to read in files
     in the ascii self defining format (SDF) developed for ALS BL5.3.2 STXM. The widget uses
     read_sdf and parse_sdf to perform the file input.

    CATEGORY:
    	AXIS: utility

     AX_SDF_EVENT ROUTINES:
     TEXT_SDF_FNAME		modify filename; when changed, execute READ_SDF
     BUT_SDF_FNAME_BROWSE 	browse for new filename
     BUT_SDF_OK			proceed with loading SDF file into AXIS
     BUT_SDF_CANCEL		abort read in
     WID_DLIST_CHANNEL		drop list used to display and select the data channel
     WID_DLIST_REGION		drop list to display and select region
     ax_sdf_eventcb		auto loading stub

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@SDF_COM 	structure with header info

    MODIFICATION HISTORY:
     (25-feb-01 aph) first written using IDL 5.2 GUIBuilder
     (27-jun-01 aph) add groupID for better feedback on reads
     (29-jul-01 aph) add regions selector to the panel; introduced sdf_com; reverted to pickfile2
     (19-aug-01 aph) adapt to regions change & change in structure names; define regions & channels
     (04-nov-01 aph) add sdf_lastfile to sdf_com to save last name

(See c:\axis2000\ax_sdf-jab.pro)

## AX_SELECT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_SELECT

    LAST CHANGED: ----------------------------------- 	29-Dec-07

     PURPOSE:
    	This set of procedures is a widget which allows user to select
      a range of the data to make a 0/1 BIT MASK which can be used as
      a region of interest (ROI) selector in stack_analyze

     CATEGORY:
    	aXis2000 capitve. Image manipulation

     CALLING SEQUENCE:
    	AX_SELECT

     INPUTS: default set of buffers are R=4, G=5, B=6

     KEYWORDS: none

     OUTPUTS:
     a ROI file suitable to be used in stack_analyze is written

     AX_SELECT_EVENT ROUTINES:

     NUM_FORMAT			standard number format for limits
     MAKE_Threshold_Image 	generate image with threshold overlay
     SLIDER_R				adjust  min / max value
     TEXT_select_max		adjust max value
     TEXT_select_min		adjust min value
     BUT_select_CANCEL		cancel
     BUT_select_SAVE		save ROI file

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	AX_SELECT_COM  parameters specifc to ax_select

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:
    	Any known ?

     MODIFICATION HISTORY:
     (29-Dec-07 aph) first version adapted from AX_RGB_MAP

(See c:\axis2000\ax_select.pro)

## AX_SELECT_COM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SELECT_COM

    LAST CHANGED: ----------------------------------- 29-Dec-07

     PURPOSE:
    	This FILE contains the COMMON block, AX_SELECT_COM

     CATEGORY:
    	AXIS: AX_SELECT_COM common block

     CALLING SEQUENCE:
    	@AX_SELECT_COM (to include in the stack_analyse routines)

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (29-dec-07 aph) first version

(See c:\axis2000\ax_select_com.pro)

## AX_SEP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SEP

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
     	This function returns the valid directories separator
     for the operating system (system dependent)

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = AX_SEP()

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	RESULT = 1-ascii character which is the system separator
    	Windows = '\', Unix = '/'  Macintosh = ':'

    MODIFICATION HISTORY:
     (14-Oct-99 aph) first written
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_sep.pro)

## AX_SHIFT_ALL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SHIFT_ALL

    LAST CHANGED: ----------------------------------- 7-dec-01

     PURPOSE:
    	This procedure uses ax_shift_image to
     rotate and shift a set of images identified by a stack_list file.
     The rotation and shift parameters are read from a file.
     Developed as part fo the 3d chemical mapping suite.

     CATEGORY:
    	stand alone ; AXIS: stack analysis

     CALLING SEQUENCE:
     ax_shift_all, sl = sl, aln=aln

     INPUTS: none

      FORMAT of *.rsl angle shift file
      path								c:\stxm532\01-11\X1-3d\rotate-iwata\
      name, angle, xshift, yshift		x1-1r.nc, 0,   18.5000,  -32.5000
     ..... for each file

     KEYWORDS:
    	SL  - stack list and lignment parameters (angle, x-shift, y-shift)

     OUTPUTS:
    	sl file with names of transformed images - default name is same name with
      't_' prefix appended

     COMMON BLOCKS:
       none

    ; MODIFICATION HISTORY:
     (04-dec-01 aph) first written
     (07-dec-01 aph) add global offsets

(See c:\axis2000\ax_shift_all.pro)

## AX_SHIFT_IMAGES

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SHIFT_IMAGES

    LAST CHANGED: ----------------------------------- 5-dec-01

     PURPOSE:
    	This function rotates and shifts a single image by the
     values contained in user-supplied variables, or from user dialog.

     CATEGORY:
    	stand alone ; AXIS: stack analysis

     CALLING SEQUENCE:
     ax_shift_images, angle=angle, xshift=xshift,yshift=yshift

     INPUTS:
    	IMAGE  - reference image
    	ANGLE   - rotation angle (clock-wise)
    	XSHIFT 	- value of x-shift (in fractional pixels)
    	YSHIFT  - value of y-shift (in fractional pixels)

     KEYWORDS: none

     OUTPUTS:
    	shifted image

     COMMON BLOCKS:
       bsif_common

     MODIFICATION HISTORY:
     (04-dec-01 aph) adapted from zstack_align

(See c:\axis2000\ax_shift_image.pro)

## AX_SLICER3

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_SLICER3

    LAST CHANGED: ----------------------------------- 	17-Sep-08

     PURPOSE:
    	This procedure reads a stack in *.ncb format into slicer3

     CATEGORY:
    	3d image display.

     CALLING SEQUENCE:
    	AX_SLICER3

     INPUTS: none

     KEYWORDS:  none

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
      stack_process_com
    	volume_data  - image stack

     MODIFICATION HISTORY:
     (21-feb-06 aph) AXIS standard header added
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_slicer3.pro)

## AX_SORT_MONO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SORT_MONO

    LAST CHANGED: ----------------------------------- 12-jun-05-05

    PURPOSE:
    	This function sorts (x,y) data sets in ascending values of x
       and replaces cases of 2 identical X-values with slightly differing values
       to force monotonic property required for the INTERPOL function

    CATEGORY:
    	STAND ALONE: spectral analysis

    CALLING SEQUENCE:
    	AX_SORT_MONO[D]

    CALLED FROM AXIS:
    	->{Spectra}->Curve Fit

    INPUTS:
    	D		X, Y-values in a 2-d array

    KEYWORDS:
    	AXIS	if flag is set the input is a structure; otherwise a 2-d array

    OUTPUTS: returns array with x-values organized monotonically; no change to y-values

    COMMON BLOCKS: none

    PROCEDURE:

    MODIFICATION HISTORY:
     (30-dec-03 aph) first version
     (30-Jan-05 aph) remove 2-d array code
     (12-jun-05 aph) modified equal value correction to avoid generating a non-monotonic file !

(See c:\axis2000\ax_sort_mono.pro)

## AX_SORT_NAMES

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_SORT_NAMES

    LAST CHANGED: ----------------------------------- 	23-may-04

     PURPOSE:
    	This function sorta a list o filenames by sequence number
     using filename conventions used in NSLS, ALS-PEEM, ALS-STXM, Sphinx, and Lox

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result = AX_SORT_NAMES(filename_list, [numbers=numbers])

     INPUTS:
     	filename_list = array of strings

     KEYWORDS:
    	NUMBERS - if selected, returns an integer array of file numbers rather than sorted names

     OUTPUTS: ordered array

     COMMON BLOCKS:  none

     MODIFICATION HISTORY:
     (23-may-04 aph) first version; adapted from tif_convert

(See c:\axis2000\ax_sort_names.pro)

## AX_SPEC_DELETE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SPEC_DELETE

    LAST CHANGED: ----------------------------------- 19-jun-00

    PURPOSE:
    	This procedure deletes all data points in a spectrum between user selected
     x-axis limits.

    CATEGORY:
    	AXIS: spectra analysis

    CALLING SEQUENCE:
     for procedures:
    	AX_SPEC_DELETE

    CALLED FROM AXIS:
    	->Spectra->Delete

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	Spectrum with deleted data is placed in Buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	Cursors used to define two limits. All data points
     betwen limits are deleted. Spectrum is replotted without changing
     scales in case user has a zoomed scale for more precise deletion.

    MODIFICATION HISTORY:
     (31-dec-99 aph) isolated from AXIS_C; AXIS standard documentation

(See c:\axis2000\ax_spec_delete.pro)

## AX_STXM4NC

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_STXM4NC

    LAST CHANGED: ----------------------------------- 18-Jul-01

     PURPOSE:
    	This procedure converts one or a series of NSLS STXM 4 image files
     into netCDF format and, if multiple files, writes a stack_list (*.sl) file
     with names of converted files

     CATEGORY:
    	AXIS: image analysis ; runs standalone

     CALLING SEQUENCE:
    	AX_STXM4NC, file

     INPUTS:
    	FILE - an NSLS STXM 4 image file (*.sm) to be converted to netCDF format (*.nc)

     KEYWORD PARAMETERS:
    	LIST - name of file with list of image files (*.lst)
       OUTLIST - name of a file to write list of netCDF files (*.sl)
    	ONE - convert only a single file

     OUTPUTS:
      FILE.NC - image written to a netCDF format binary file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS
       @BSIF_COM - common block for netCDF

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     PROCEDURE:
    	AX_STXM4NC assumes that ax_rd_im has put the image and associated information
     into BSIF_COMMON variables:
    	image_data (the array which holds the image - possibly several
    	planes deep for I, IO, CLOCK)

     MODIFICATION HISTORY:
     (18-Jul-01 aph) derived from  als2ncdf using readSTXM4

(See c:\axis2000\ax_stxm4nc.pro)

## AX_SVD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SVD

    LAST CHANGED: ----------------------------------- 17-Sep-08

    PURPOSE:
    	This procedure executes the SVD procedure to generate component maps
     from an arbitary number of images for an arbitrary number of components.
     Will run stand alone (prompting user for AXIS format files) or from AXIS.

    CATEGORY:
    	STAND ALONE: image, stack analysis

    CALLING SEQUENCE:
    	AX_SVD[,  axis=axis,  coeff = coeff, comp_images = comp_images, $
             help=help, images = images, stack = stack, verbose = verbose]

    CALLED FROM AXIS:
    	Stacks->SVD

    INPUTS:
    	All inputs are through keywords. User is prompted for missing data.

    KEYWORDS:
    	/AXIS - if on, then called from AXIS widget
    	COEFF = fit parameter file with names of spectral files
    	COMP_IMAGES = list of component images (*.axb)
    	/HELP - set to print how-to-use statement
    	IMAGES = file with list of images to be analysed
       STACK = name of a binary format stack (*.ncb)
    	/VERBOSE  - print additional documentation of SVD procedure

    OUTPUTS:
    	No explicit outputs.   A new window is created if necessary

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	stack_process_com
    	COMMON volume_data, image_stack
    	bsif_com

    PROCEDURE:
    	The images are first read in - either as a binary stack (if stack keyword set)
     or from the list of images, or from pickfile dialog.
     The absorption coefficents for each component at the energies of the images
     are then read in, either through interpolation of a reference spectrum
     (read in via pickfile dialog), or from a standard absorption coefficient file
     (see example below) or by manual input.
     The SVD procedure is then applied.
     Component maps are generated. written to files, and displayed either in
     IDL windows (if run stand alone) or in AXIS buffers.

    EXAMPLE:
     example of file to provide list of images (same as stack_list files)

    	f:\stxm\9909\10-13\			; path to images
    	a1013_01.axb
    	a1013_02.axb
    	a1013_03.axb
    	a1013_04.axb
    	a1013_05.axb
    	a1013_06.axb
    	a1013_07.axb
    	a1013_08.axb
    	a1013_09.axb

     example of file to provide mass absorption coefficents
    	2900  155000     8200  76700
    	3400   29900   139600  52000
       DVB
       EGDMA
    	SF-normalized values		; ignores ANY text after ncomp lines and labels
    	species	281 285	 288.3	305	; each with n_image entries (abs. coeff. for that species)
    	DVB   (divinylbenzene)  EGDMA (acrylate)

    MODIFICATION HISTORY:
    	Developed by ANDY WINESETT, NCSU , 1998, 1999
    	Modified from SGU's version by GEM 7/15/99 to do 3 image SAP stacks
    	updated 7/16/99, GEM to save data files in XRD format
    	updated March 5, 1999 (SGU)
     (29-jul-99 aph) generalised to a dialog
     (10-aug-99 aph) installed in AXIS; use reform to remove need to reload maps
     (17-aug-99 aph) auto-truncate to match size of all images NB does NOT use (x,y) scales
     (14-oct-99 aph) auto-extract intensity coeff from files if coeff set
     (17-oct-99 aph) further improvements to file handling stuff; allow use of any file format
     (23-oct-99 aph) plot coefficents for feedback to user
     (27-oct-99 aph) correct error in (x,y) scales of images
     (01-jan-00 aph) AXIS standard documentation
     (27-feb-00 aph) add groupID to get_text
     (11-apr-00 aph) add residual and chi square evaluation
     (22-aug-00 aph) force interpolation
     (19-oct-00 aph) increase to 8 components max
     (28-jul-01 aph) neaten up while developing AX_CGO; ensure stand-alone operation
     (12-aug-01 aph) correct error from 28-jul-01 change
     (07-oct-01 aph) add xl to temporary files to allow use later
     (13-dec-01 aph) fix error on component map name definition
     (29-dec-01 aph) add E to 2d structure
     (26-jan-02 aph) set correct path for par file
     (13-May-03 aph) convert coeff file to list of reference spectra files
     (04-jun-03 aph) force '.par' extension (pickfile, filter= & /write); fix comp_names for no blanks
     (04-jun-03 aph) use ax_par_load and ax_par_save
     (30-dec-03 aph) add ax_sort_mono to force stack E-scale and reference spectral scales to be monotonic
     (20-jan-04 aph) use dialog_message to control residual stack writing
    				  ensure E-value (0.0) added to component maps
     (01-apr-04 aph) fix ERROR in writing component maps (duplicate E)
     (12-dec-04 aph) reformat component spectra to allow other uses
     (01-feb-05 aph) fix ax_sort_mono to use structure (ricochet change from lox change)
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_svd.pro)

## AX_SVD_SPECTRA

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SVD_spectra

    LAST CHANGED: ----------------------------------- 03-feb-05

    PURPOSE:
    	This procedure uses SVD to fit a spectrum to a set of reference spectra.
     AX_SVD_spectra will run stand alone (prompting user for AXIS format files) or from AXIS.

    CATEGORY:
    	STAND ALONE: spectral analysis

    CALLING SEQUENCE:
    	AX_SVD_spectra[SPC, axis=axis, help = help, coeff = coeff, set_start = set_start, pos_only=pos_only ]

    CALLED FROM AXIS:
    	->{Spectra}->Curve Fit~SVD_spectra

    INPUTS:
    	SPC		spectrum to be fit in axis 1d structure form

    KEYWORDS:
     AXIS 		called from AXIS widget
     COEFF		filename with spectral information
     HELP		print help text
     SET_START	allow users to set starting values
     POS_ONLY	force only positive coefficients
     LIMITS	[min, max] 2-vector defining lower and upper limits

    OUTPUTS: 	No explicit outputs.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	The reference spectra are read in and the coefficient matrix generated.
     SVD is then called to get the fittin coefficients

    MODIFICATION HISTORY:
     (03-feb-04 aph) first version - adapted from ax_curvfit (20-oct-04 version )

(See c:\axis2000\ax_svd_spectra.pro)

## AX_SWITCH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_SWITCH

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
    	This procedure switches the active buffer using the thumbnails
     or the buffer labels. It also processes flags for other uses for the
     thumbnail switches, such as copying buffers.

    CATEGORY:
    	AXIS:  utility

    CALLING SEQUENCE:
     for procedures:
    	AX_SWITCH, BufNum

    CALLED FROM AXIS:
    	->on mouse click on a thumbnail

    INPUTS:
    	BUFNUM - number of buffer selected by left mouse click.
    	other control parameters transferred via common

    KEYWORDS: none

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

     PROCEDURE:
     switches among buffers & processes flags
     meaning of variables
    	NewBuf - (axis_common) new buffer number
     	CurBuf - (axis_common) current buffer number
    	select_flag - identifies that thumbnail 'button push' is being
                     used to select buffer for a function other than plotting
     NB - this code always resets select_flag regardless of action
    	copy_flag = identifies action as a copy from CurBuf to NewBuf

    MODIFICATION HISTORY:
     (30-oct-99 aph) first written to use new thumbnails as switches
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_switch.pro)

## AX_TOMO_READ

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		AX_TOMO_READ

    LAST CHANGED: ----------------------------------- (17-Sep-08 aph)

     PURPOSE:
    	This function processes a set of folders of files containing multi-images stacks for tomography read-in

     CATEGORY:
    	Input / output utilty; stand alone

     CALLING SEQUENCE:
    	Result = AX_TOMO_READ(FILE=FILE, ONE_IMAGE=ONE_IMAGE, MAP=MAP, STACK=STACK, AXB=AXB, GROUP=GROUP)

     INPUTS: none

     KEYWORDS
    	CHANNEL		data channel to read
     	FILE		list of folders to process
    	ONE_IMAGE  	read in one image at each angle
    	MAP        	read in map (diff of OD of 2 images) at each angle
    	STACK		read in stack of stacks (not yet implemented)
       TIF			read in set of tif files (from SVD) (ABORTED 14-Jul-07 due to no color)
    	AXB			read in set of axb files (from SVD)

     OUTPUTS:
    	folder with selected files

     COMMON:
    	AXIS
    	BSIF
    	STACK_PROCESS_COM
       VOLUME_DATA

     MODIFICATION HISTORY:
     (15-dec-05 aph) first version fur use  in axis and stand alone (for tomography)
     (17-may-06 gaj) added /no_interpolate keyword to call of read_sdf() to aviod rounding error of number of pixels
     (10-jul-06 gaj) fixed some bugs with Stack~Tomography~map
     (14-jul-07 aph) read set of '*.axb' files (component maps) and convert to *.ncb angle sequence
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\ax_tomo_read.pro)

## AX_WAIT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_WAIT

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
    	This procedure turns on or off the widget_event hourglass
     widget_event(hourglass=0)  does not seem to work !!

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	AX_WAIT, OFF = off

    INPUTS: none

    KEYWORDS:
    	OFF - turn off if 1, turn on if 0

    MODIFICATION HISTORY:
     (19-sep-99 aph) first written to avoid persistent hourglass
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_wait.pro)

## AX_WRITE_XAS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	 AX_WRITE_XAS

    LAST CHANGED: ----------------------------------- 04-jun-08

    PURPOSE:
    	This procedure writes a 1d data structure (spectrum) as a
     nsls X1A *.xas format, annotated ascii file.
     The user is prompted for header information and can choose from
     nsls or gas-phase-database format for entries

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	 AX_WRITE_XAS, tmp, file = file, nof = nof

    CALLED FROM AXIS:
    	->WRite->XAS

    INPUTS:
    	TMP - AXIS 1d-structure

    KEYWORDS:
    	FILE 	filename. If not supplied the user is prompted for the filename.
    	NOF		no filter (default filter is *.xas)
    	MULTI	write multiple spectra with user selectable point spacing

    OUTPUTS:
    	An XAS-format file is written.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (31-jan-00 aph) first written to allow use of axis data as Io for Zimba stack_analyze.
     (27-feb-00 aph) AXIS standard documentation; groupID for get_text
     (04-Jun-08 aph) incorporate multi-spectral write (what is displayed)

(See c:\axis2000\ax_write_xas.pro)

## AX_XYCAL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_XYCAL

    LAST CHANGED: ----------------------------------- 28-oct-01

    PURPOSE:
    	This procedure calibrate the XY-values of currently displayed image.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
    	AX_XYCAL, ONE=one

    CALLED FROM AXIS:
    	Images->CalibrateXY->{1 point, 2 points}

    INPUTS: none

    KEYWORDS:
    	ONE - use only 1-point to calibrate (shift)
     The default is a 2-point calibration (stretch-shift)

    OUTPUTS:
    	recalibrated image is placed in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     ( 4-Jun-98 aph) added 1-point version
     (14-jun-98 aph) axis_com
     (30-Dec-98 aph) format Uprompt
     ( 8-jun-99 aph) add group to get_num call; FIXED major error for 2-point calib !
     (20-oct-99 aph) add meshing and truncating to make same as image alignment procedure
     (01-jan-00 aph) set (xmin, xmax, ymin, ymax to limits); AXIS standard documentation
     (07-nov-00 aph) add tmp.E to preserve Energy of images
     (28-oct-01 aph) add check for tmp.E, set to zero if not found

(See c:\axis2000\ax_xycal.pro)

## AX_XYDIS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_XYDIS

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
    	This procedure modifies (x,y) pixel size based on user-defined conversion

    CATEGORY:
    	AXIS: image utility

    CALLING SEQUENCE:
    	AX_XYDIS

    CALLED FROM AXIS:
    	Images->Distort XY scale

    INPUTS: none

    KEYWORDS: none

    OUTPUTS:
    	modified image is written to buffer 0

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (fall-97 aph) - first wrote for Mephisto data
     (14-jun-98 aph) axis_com
     (08-jun-99 aph) add group call to get_num
     (14-dec-99 aph) get correct (x,y) values
     (25-dec-99 aph) interpolate to square pixels
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_xydis.pro)

## AX_XYSCL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_XYSCL

    LAST CHANGED: ----------------------------------- 01-jan-00

    PURPOSE:
    	This procedure sets the (x,y) scales of images

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	AX_XYSCL

    CALLED FROM AXIS:
    	Images->Set XY scale

    INPUTS: none

    KEYWORDS: none

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (xx-sep-97 aph) first wrote for Mephisto data
     (14-jun-98 aph) axis_com
     (08-jun-99 aph) add group keyword to get_num; fixed error !
     (01-jan-00 aph) AXIS standard documentation

(See c:\axis2000\ax_xyscl.pro)

## AX_ZOOM_CURSOR

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_ZOOM_CURSOR

    LAST CHANGED: ----------------------------------- 21-aug-01

    PURPOSE:
    	This procedure zooms a sub region of the current image displayed
     by using a marquee (Box cursor) to select the zoom region.
     The zoomed region is extracted from the original data and
     placed as a new AXIS structure in buffer 0.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
    	AX_ZOOM_CURSOR

    CALLED FROM AXIS:
    	Zoom->Images->cursor - cut

    INPUT: none

    KEYWORDS: none

    OUTPUTS:
    	Region cut from image is placed as a new AXIS 2d structure in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     	Uses BX_CURSOR to define a region to zoom
     nb - BX_CURSOR is derived from IDL's BOX_CURSOR
     but the left and middle buttons have been swapped
     to make it compatible with 2-button mice
     NB this routine is written to handle spectra as well, but currently not used.
     Spectra->Truncate performs the equivalent function for spectra.

    MODIFICATION HISTORY:
     (28-dec-99 aph) isolated from AXIS_C
     (01-jan-00 aph) AXIS standard documentation
     (17-apr-01 aph) added E to output structure
     (21-aug-01 aph) ensured code compatible with 2d structures without E

(See c:\axis2000\ax_zoom_cursor.pro)

## AX_ZOOM_CUT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	AX_ZOOM_CUT

    LAST CHANGED: ----------------------------------- 23-feb-06

    PURPOSE:
    	This procedure cuts out a region from an AXIS image
     based on numerical limits.

    CATEGORY:
    	AXIS: image analysis

    CALLING SEQUENCE:
    	AX_ZOOM_CUT, limits=limits

    CALLED FROM AXIS:
    	Zoom->Images->Numerical

    INPUTS: none - acts on CurBuf

    KEYWORDS:
    	LIMITS  [xmin,xmax,ymin,ymax] in data units
    	MESH	[x-pixels, y-pixels] - number of pixels
    	NO_PLOT  if set, do not plot

    OUTPUTS:
    	Modified image placed in buffer 0.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (15-nov-99 aph) isolated from axis_c
     (01-jan-00 aph) AXIS standard documentation
     (17-apr-01 aph) added E to output structure
     (29-dec-01 aph) changed to procedure; set up for macro operation
     (31-dec-01 aph) add keyword MESH = [number of x, y pixels] - to ensure equal size outputs
     (23-feb-06 aph) add no_plot keyword to allow use for zooming

(See c:\axis2000\ax_zoom_cut.pro)

## AX_ZOOM_PAN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      AX_ZOOM_PAN

    LAST CHANGED: ----------------------------------- 02-may-04

     PURPOSE:
    	Display part of an image (or graphics) from the current window
    	enlarged in another window.The cursor is used to mark the center of the zoom.

     CATEGORY:
    	STAND ALONE: Image display.

     CALLING SEQUENCE:
    	AX_ZOOM_PAN [, FACT = Fact, /INTERP, XSIZE = Xs, YSIZE = Ys, /CONTINUOUS, $
    		/KEEP, ZOOM_WINDOW=Zoom_Win, /NEW_WINDOW ]

     INPUTS:
    	All input parameters are passed as keywords.

     KEYWORDS:
    	FACT:	Zoom factor.  This parameter must be an integer.  The default
    		zoom factor is 4.
    	INTERP:	Set this keyword to use bilinear interpolation, otherwise
    		pixel replication is used.
    	XSIZE:	The X size of the zoom window.  The default is 512.
    	YSIZE:	The Y size of the zoom window.  The default is 512.
    	CONTINUOUS:	Set this keyword to make the zoom window track the mouse
    		without requiring the user to press the left mouse button.
    		This feature only works well on fast computers.
    	KEEP: Keep the zoom window after exiting the procedure.
    	ZOOM_WINDOW:	When used with KEEP, returns the index of the zoom window.
    		Otherwise, if KEEP is not set, then -1 is returned.
    	NEW_WINDOW:	Normally, if ZOOM is called with /KEEP and then called again,
    		it will use the same window to display the zoomed image.
    		Calling ZOOM with /NEW_WINDOW forces it to create a new window
    		for this purpose.

     OUTPUTS:
    	No explicit outputs.   A new window is created if necessary. It
    	is destroyed upon exit if KEEP is not specified.

     COMMON BLOCKS:
    	common zoom_window, zoom_w
    	axis_com

     SIDE EFFECTS:
    	A window is created/destroyed.
    	When ZOOM is reusing a zoom window from a previous call to ZOOM,/KEEP,
    	then the XSIZE and YSIZE parameters are reset to the actual size of the
    	window.

     RESTRICTIONS:
    	ZOOM only works with color systems.

     PROCEDURE:
    	Straightforward.

     MODIFICATION HISTORY:
    	?
       William Thompson, March 1992, added common block ZOOM_WINDOW and KEEP keyword.
    	William Thompson, 20 May 1993, added ZOOM_WINDOW and NEW_WINDOW keywords.
     (?         aph) adapted from IDL version to handle 2-button mice
     (30-Dec-98 aph) use Get_Num to change zoom factor
     (08-jun-99 aph) add group id to get_num
     (30-dec-99 aph) changed name from ax_zoom to ax_zoom_pan
     (02-jan-99 aph) AXIS standard documentation
     (13-oct-01 aph) add ax_color to make pan display color correctly
     (02-may-04 aph) change header

(See c:\axis2000\ax_zoom_pan.pro)

## BMP_TO_NCB[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	BMP_TO_NCB

    LAST CHANGED: ----------------------------------- 26-Apr-06

     PURPOSE:
    	This procedure converts a series of Windows *.bmp image files
     into a binary stack file. The BMP files are those listed in a '*.sl' file

     CATEGORY:
    	AXIS: stack analysis

     CALLING SEQUENCE:
    	RESULT = BMP_TO_NCB(group_leader=axis_ID)

     INPUTS:
    	none

     KEYWORD PARAMETERS:
    	GROUP_LEADER - identification of caller for modal control

     OUTPUTS:
      FILE.NCB - stack binary file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     MODIFICATION HISTORY:
     (21-Feb-06 aph) first developed (adapted from stxm4_ncb)
     (26-apr-06 aph) clean up and add conversion tags

(See c:\axis2000\bmp_to_ncb.pro)

## BMP_TO_NCB[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	BMP_TO_NCB

    LAST CHANGED: ----------------------------------- 26-Feb-06

     PURPOSE:
    	This procedure converts a series of JPEG (*.jpg) image files
     into a binary stack file. The BMP files are those listed in a '*.sl' file

     CATEGORY:
    	AXIS: stack analysis

     CALLING SEQUENCE:
    	RESULT = JPG_TO_NCB(group_leader=axis_ID)

     INPUTS:
    	none

     KEYWORD PARAMETERS:
    	GROUP_LEADER - identification of caller for modal control

     OUTPUTS:
      FILE.NCB - stack binary file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     MODIFICATION HISTORY:
     (26-Feb-06 aph) first developed (adapted from BMP_TO_NCB)

(See c:\axis2000\jpg_to_ncb.pro)

## BNL_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	BNL_LOAD

    LAST CHANGED: ----------------------------------- 23-feb-00

    PURPOSE:
    	This function loads  spectral data from the nsls X1A
     standard ASCII format file into AXIS 1d data structure

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	Result = BNL_LOAD(NOF=nof, DEFPATH=DefPath)

    CALLED FROM AXIS:
    	->Read->NSLS->ascii

    INPUTS:
    	All input parameters are passed as keywords.

    KEYWORDS:
    	NOF - no filter
       DEFPATH - default path (used in pickfile routine)

    OUTPUTS:
    	The result is placed in the Current Buffer.

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (aph 7-aug-97) broke out of spectral; type defined
     (23-feb-00 aph) AXIS standard documentation

(See c:\axis2000\bnl_load.pro)

## BOX

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	BOX
     PURPOSE:
    	Draws a rubber band box according to cursor motion, returns corners.
     CATEGORY:
    	Who Knows -- Need a list of the valid responses
     CALLING SEQUENCE:
    	BOX,xv,yv [,ratio=ratio,/device [,/data ] ]
     INPUTS:
    	ratio	Ratio of the length of the box sides
    	/device	Specifies use of device coordinates
    	/data	Specifies use of data coordinates
     OUTPUTS:
    	xv	2 point vector of x-coordinate for opposite box corners
    	yv	2 point vector of y-coordinate for opposite box corners
     COMMON BLOCKS:
    	NONE
     SIDE EFFECTS:
    	Makes user think SHE/HE is a terminator.
     RESTRICTIONS:
    	Display must be able to support DEVICE,SET_GRAPH=6
     PROCEDURE:
    	STRAIGHTFORWARD (seems to be the default value of this field).
     MODIFICATION HISTORY:
    	Written Early 1991 by J. M. Zawodny, NASA LaRC
    		zawodny@arbd0.larc.nasa.gov

(See c:\axis2000\box.pro)

## BOX_CURSOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	BOX_CURSOR

     PURPOSE:
    	Emulate the operation of a variable-sized box cursor (also known as
    	a "marquee" selector).

     CATEGORY:
    	Interactive graphics.

     CALLING SEQUENCE:
    	BOX_CURSOR, x0, y0, nx, ny [, INIT = init] [, FIXED_SIZE = fixed_size]

     INPUTS:
    	No required input parameters.

     OPTIONAL INPUT PARAMETERS:
    	x0, y0, nx, and ny give the initial location (x0, y0) and
    	size (nx, ny) of the box if the keyword INIT is set.  Otherwise, the
    	box is initially drawn in the center of the screen.

     KEYWORD PARAMETERS:
    	INIT:  If this keyword is set, x0, y0, nx, and ny contain the initial
    	parameters for the box.

    	FIXED_SIZE:  If this keyword is set, nx and ny contain the initial
    	size of the box.  This size may not be changed by the user.

    	MESSAGE:  If this keyword is set, print a short message describing
    	operation of the cursor.

     OUTPUTS:
    	x0:  X value of lower left corner of box.
    	y0:  Y value of lower left corner of box.
    	nx:  width of box in pixels.
    	ny:  height of box in pixels.

    	The box is also constrained to lie entirely within the window.

     COMMON BLOCKS:
    	None.

     SIDE EFFECTS:
    	A box is drawn in the currently active window.  It is erased
    	on exit.

     RESTRICTIONS:
    	Works only with window system drivers.

     PROCEDURE:
    	The graphics function is set to 6 for eXclusive OR.  This
    	allows the box to be drawn and erased without disturbing the
    	contents of the window.

    	Operation is as follows:
    	Left mouse button:   Move the box by dragging.
    	Middle mouse button: Resize the box by dragging.  The corner
    		nearest the initial mouse position is moved.
    	Right mouse button:  Exit this procedure, returning the
    			     current box parameters.

     MODIFICATION HISTORY:
    	DMS, April, 1990.
    	DMS, April, 1992.  Made dragging more intutitive.
    	June, 1993 - Bill Thompson
    			prevented the box from having a negative size.
           SJL, Nov, 1997.  Formatted, conform to IDL style guide.
                           Prevented crash from unitialized corner.
           RJF, Feb, 1998. Replaced !ERROR_STATE.CODE w/ !MOUSE.BUTTON and
    			fixed some problems w/sizing when a corner might swap.

(See c:\axis2000\box_cursor.pro)

## BSIF_COMMON.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           BSIF_COMMON.PRO

     LAST CHANGED ---------------------------  23-Feb-00

     PURPOSE:
     Defines the common block used in NSLS X1A imaging routines for images read
     from BSIF files. Longname version of BSIF_COM.PRO

       VERSION
           BSIF file format version number - not currently used, allows for future
           changes in file format.
       FIRST_DATA_RECORD
           First data record in file. This field is set by WRITE_BSIF and is not
           needed by any IDL routines.
       N_COLS, NROWS
           The number of columns and rows in the image
       N_DATA
           The number of data values at each pixel
       X_NORMAL
           Non-zero (TRUE) if X scan direction is "normal" e.g. left-to-right.
           This variable is not presently used by any IDL routines.
       Y_NORMAL
           Non-zero (TRUE) if Y scan direction is "normal" e.g. top-to-bottom.
           This variable is not presently used by any IDL routines.
       ROTATED
           Non-zero (TRUE) image image is rotated, e.g. X and Y axes are switched.
           This variable is not presently used by any IDL routines.
       X_START, X_STOP
           The position of the beginning and end of the X scan direction in user
           units, such as mm.
       Y_START, Y_STOP
           The position of the beginning and end of the Y scan direction in user
           units, such as mm.
       X_DIST(N_COLS)
           Array with calibrated X axis positions.
       Y_DIST(N_ROWS)
           Array with calibrated Y axis positions.
       DATA_TYPE
           The data type of image_data as stored in the file.
       COMPRESSION_TYPE
           Data compression type. Currently supported values are
               0 = No compression
               1 = ???
               2 = ???
       DATA_MIN(N_DATA), DATA_MAX(N_DATA)
           The minimum and maximum values of the data in the array. These values
           are not guaranteed to be correct.
       IMAGE_TITLE
           The title of the image - a character string
       X_TITLE
           The title of the X axis of the image, i.e. "Distance in mm"
       Y_TITLE
           The title of the Y axis of the image, i.e. "Distance in mm"
       DATA_TITLE(N_DATA)
           The titles of the data values at each pixel.
       USER_BUFFER
           A user defined array. Stored in IDL as a byte array. May have internal
           structure which is user defined.
       IMAGE_DATA(COLS, ROWS, N_DATA)
           The image data array. The data type of the array is determined by the
           data type definined in the BSIF file. It can be BYTE, INTEGER, LONG or
           FLOAT.

(See c:\axis2000\bsif_common.pro)

## BUFFER

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	BUFFER

    LAST CHANGED: ----------------------------------- 23-feb-00

    PURPOSE:
    	This function selectsan AXIS buffer for use in various processing steps.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	Result = BUFFER(GROUP=Group, Prompt=Prompt)

    CALLED FROM AXIS:
    	many places

    ROUTINES
    	BUFFER_Event, Event - processes button pushes on Buffer widget

    INPUTS:
    	INPUT - POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

    KEYWORDS:
    	 GROUP = parent calling buffer (AXIS_ID from axis) - to allow modal
    	 Prompt = prompt to inform user purpose of buffer selection

    OUTPUTS:
    	The number of the selected buffer is returned.
       If the user pushes cancel, the returned value is -1.

    COMMON BLOCKS:
    	B, Buf - number of selected buffer (to transfer between function & event processor)

    SIDE EFFECTS:
    	A widget is created/destroyed.

    MODIFICATION HISTORY:
     (xx-yyy-07 aph) first written
     (20-dec-98 aph) correct pattern for IDL5.2; add 'Cancel'
     (11-jun-99 aph) extend prompt information
     (23-feb-00 aph) AXIS standard documentation

(See c:\axis2000\buffer.pro)

## BX_CURSOR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	BX_CURSOR

     LAST CHANGED: -------------------------- 23-feb-00

     PURPOSE:
    	Emulate the operation of a variable-sized box cursor (also known as
    	a "marquee" selector).
     (aph) (26-may-97) adapted to swap left and middle button functionality

     CATEGORY:
    	Interactive graphics.

     CALLING SEQUENCE:
    	BOX_CURSOR, x0, y0, nx, ny [, INIT = init] [, FIXED_SIZE = fixed_size]

     INPUTS:
    	No required input parameters.

     OPTIONAL INPUT PARAMETERS:
    	x0, y0, nx, and ny give the initial location (x0, y0) and
    	size (nx, ny) of the box if the keyword INIT is set.  Otherwise, the
    	box is initially drawn in the center of the screen.

     KEYWORD PARAMETERS:
    	INIT:  If this keyword is set, x0, y0, nx, and ny contain the initial
    	parameters for the box.

    	FIXED_SIZE:  If this keyword is set, nx and ny contain the initial
    	size of the box.  This size may not be changed by the user.

    	MESSAGE:  If this keyword is set, print a short message describing
    	operation of the cursor.

     OUTPUTS:
    	x0:  X value of lower left corner of box.
    	y0:  Y value of lower left corner of box.
    	nx:  width of box in pixels.
    	ny:  height of box in pixels.

    	The box is also constrained to lie entirely within the window.

     COMMON BLOCKS:
    	None.

     SIDE EFFECTS:
    	A box is drawn in the currently active window.  It is erased
    	on exit.

     RESTRICTIONS:
    	Works only with window system drivers.

     PROCEDURE:
    	The graphics function is set to 6 for eXclusive OR.  This
    	allows the box to be drawn and erased without disturbing the
    	contents of the window.

    	Operation is as follows:
    	Left   mouse button: Resize the box by dragging.  The corner
    		             nearest the initial mouse position is moved.
    	Middle mouse button: Move the box by dragging.  ! IF 3-button mouse !!
    	Right  mouse button: Exit this procedure, returning the
    			     current box parameters.

     MODIFICATION HISTORY:
    	DMS, April, 1990.
    	DMS, April, 1992.  Made dragging more intutitive.
    	June, 1993 - Bill Thompson
    			prevented the box from having a negative size.
    	May, 1997  - Adam Hitchcock : swap left and middle button
     (23-feb-00 aph) axis standard documentation

(See c:\axis2000\bx_cursor.pro)

## CAPERS-SCALE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CAPERS-SCALE

     last changed ----------------------------- 18-Sep-05 (aph)

     PURPOSE
       This function sets the full size of a CaPeRS image read from a Lox file
     based on values of the Field Lens and Projective 1 Lens currents

     CATEGORY:
    	Image processing.

     CALLING SEQUENCE:
    	Result = CAPERS-SCALE(P1, F1, HBIN=HBIN, VBIN=VBIN)

     INPUTS:
     P1 = Projective 1  lens current (mA)
     FL = Field Lens    lens current (mA)

     KEYWORDS:
      HBIN = integer binning in horizontal direction (on-camera)
      VBIN = integer binning in vertical   direction (on-camera)

     COMMON: none

     WARNINGS

     Note that different Elmitec microscopes have different lenses
     thus the lens current = pixel size look up table contained in the CAPERS_SCALE.PRO file
     may be have to be parameterized to correctly dal with Elmitec microscopes other than CaPeRS

     The {FoV, P1, FL} values and thus limits of the ranges for the preset image modes
     were taken from the values in the LEEM2000 program of CaPeRS in August 2005.

     If reduced portions of the camera output were used the image size must be appropriately adapted
     An alternative  would be to return the pixel size, not the full image size
     However, if there is binning done on-camera (most often the case) that information must be taken into account
     to get the correct pixel size; Since the camera binning parameters are stored in the Lox header
     this is possible to implement.

     If the image data is binned after read-in, the pixel size must be appropriately modified

     MODIFICATION HISTORY:
     (18-Sep-05 aph) first version

(See c:\axis2000\capers_scale.pro)

## CG_OPTIMIZE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CG_OPTIMIZE

     LAST CHANGED: ------------------------------  28-jul-01 (aph)

     PURPOSE:
           This function finds the minimum of a user-specified objective
           function using the conjugate gradient algorithm (Polak-Ribiere
           variant). The objective function to be minimized must return a
           scalar-valued output given a vector-valued input. Also required
           is a function to calculate the gradient of the objective function.

     CATEGORY:
           Optimization

     CALLING SEQUENCE:
           x = CG_OPTIMIZE(xstart, Func, DFunc)

     INPUTS:
           xstart:    A starting guess for the solution vector x. A common
                      starting guess is the zero vector.

           Func:      A string containing the name of the objective function to
                      minimize. The objective function must take a vector-valued
                      input and return a scalar-valued output.

           DFunc:     A string containing the name of a function that calculates
                      the gradient of Func at a vector-valued input point. The
                      output of the function must be a vector of the same length
                      as the input vector.

     KEYWORD PARAMETERS:
           NUM_ITER:  The maximum number of iterations of the algorithm to run.
                      The default is 100.

           TOLERANCE: If set, iterates will be computed until the change in
                      the objective function is smaller than the tolerance,
                      or the maximum number of iterations is reached, whichever
                      comes first.

           OBJECTIVE: A variable to receive the value of the objective function
                      at each iteration. It will therefore be a vector of length
                      one plus the number of iterations performed.

           LINMIN:    A string containing the name of a function that performs
                      one dimensional minimization of an objective function along
                      a vector direction from a starting point. The function
                      must take the following arguments:
                        (start, dir, fmin, Func, DFunc, _EXTRA)
                      where start is the starting point (vector), dir is the
                      direction (vector), fmin is the value of the objective
                      function at the line minimum (scalar), Func, DFunc,
                      and _EXTRA are as described for CG_OPTIMIZE.
                      The 1-D minimization function must return a vector that
                      minimizes the objective function along the specified
                      direction.
                      If not specified, the default function CG_LINMIN is used.

    		POS_ONLY:  If set, force all values to be optimized to be GT 0

    		LIMITS:		[x-min, x-max] lower and upper bounds

    		SWAP:		If set, replace low values with upper limit and vice-verso

           _EXTRA:    Keywords to Func and DFunc may be passed to those functions
                      through the CG_OPTIMIZE function. This is useful for
                      providing data to the objective and gradient functions.

     OUTPUTS:
           x:         The solution vector that minimizes Func.

     ROUTINES INCLUDED IN THIS MODULE:
           CG_LINMIN   The default line minimization routine.
           CG_OPTIMIZE The main function.

           and example functions: CGEX_FUNC, CGEX_DFUNC, CGEX_LINMIN

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           February, 2000

     MODIFICATION HISTORY:
     (29-dec-00 aph) add ALLPOS to force non-negative values (not working as parameter)
     (13-feb-01 aph) adapt for use in a curve-fit routine
     (27-jul-01 aph) get pos_only to work as an option; - executes but no convergence
                  explicitly include A, B in all call functions
     (28-jul-01 aph) add upper / lower bound constraints and swap

(See c:\axis2000\cg_optimize.pro)

## CHKFILEBLOCKS.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CHKFILEBLOCKS.PRO

    LAST CHANGED: ----------------------------------- 11-nov-00

    PURPOSE:
    	CHKFILEBLOCKS - determines block structure of a text string

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = CHKFILEBLOCKS(FILNENAME)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function CHKFILEBLOCKS, FNAME
    	looks in FILE (fname), counts the number of "blocks" of data, where
     a block is a (r x c) block of numbers. If there are no blocks found,
     returns a scalar 0, else returns a (b, 2)-dim array, where b is the
     block index, (b,0) is the number of rows, (b,1) is the number of columns
     and (b,2) is the starting row in the file (counting from 0)

    COMMON BLOCKS: none

(See c:\axis2000\chkfileblocks.pro)

## CIMAGE.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		CIMAGE.PRO

    LAST CHANGED: ----------------------------------- 	12-Sep-07 (aph)

     PURPOSE:
    	This procedure cleans up images by removing very low and very high values.

     CATEGORY:
    	Image processing

     CALLING SEQUENCE:
     for procedures:
    	CIMAGE;;ResetImageRange

     INPUTS: none

     KEYWORDS: none

     OUTPUTS:
    	Image is modified (??)

     COMMON BLOCKS: none

     SIDE EFFECTS: none

     RESTRICTIONS: does not work if low contrast, Error trapped if flat image

     PROCEDURE:
    	This procedure calculates a histogram and determine two levels (Top and Bottom)
     such that 2 rows worth of pixels are above and two rows worth of
     pixels are below these levels. The image is then scaled between Top and Bottom
     instead of using Minimum and Maximum.

     EXAMPLE:

     MODIFICATION HISTORY:
     (22-Jan-07 as) Andreas Scholl provided routine as a solution to problem of arbitary removal
             of first 5 columns (causes dimensional problems)
     (12-Sep-07 aph) incorporated; AXIS standard header added

(See c:\axis2000\cimage.pro)

## CINDEX[1]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CIndex

     PURPOSE:
           This is a program for viewing the current colors in the
           colortable with their index numbers overlayed on each color.
           On 24-bit systems you must click the cursor in the graphics window
           to see the colors in the current color table.

     AUTHOR:
           FANNING SOFTWARE CONSULTING
           David Fanning, Ph.D.
           2642 Bradbury Court
           Fort Collins, CO 80521 USA
           Phone: 970-221-0438
           E-mail: davidf@dfanning.com
           Coyote's Guide to IDL Programming: http://www.dfanning.com

     CATEGORY: Graphics

     CALLING SEQUENCE:  CIndex

     INPUTS:   None.

     Optional Inputs:   None

     OUTPUTS:  None

     OPTIONAL OUTPUTS:  None

     KEYWORD Parameters:   None

     COMMON BLOCKS:  None

     SIDE EFFECTS:   None

     RESTRICTIONS:   Reqires XCOLORS from the Coyote Library:

                         http://www.dfanning.com/programs/xcolors.pro

     PROCEDURE:

      Draws a 31x25 set of small rectangles in 256 different colors.
      Writes the color index number on top of each rectangle.

     MODIFICATION HISTORY:  David Fanning, RSI, May 1995

      Widgetized and made it work in 24-bit color. Colors are
         updated by clicking in window. 22 Oct 98. DWF

      Replace POLYFILL with TV command to avoid underflow error in
         Z-buffer. 8 March 99. DWF

(See c:\axis2000\ax_show_cindex.pro)

## CINDEX[2]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CIndex

     PURPOSE:
           This is a program for viewing the current colors in the
           colortable with their index numbers overlayed on each color.
           On 24-bit systems you must click the cursor in the graphics window
           to see the colors in the current color table.

     AUTHOR:
           FANNING SOFTWARE CONSULTING
           David Fanning, Ph.D.
           2642 Bradbury Court
           Fort Collins, CO 80521 USA
           Phone: 970-221-0438
           E-mail: davidf@dfanning.com
           Coyote's Guide to IDL Programming: http://www.dfanning.com

     CATEGORY: Graphics

     CALLING SEQUENCE:  CIndex

     INPUTS:   None.

     Optional Inputs:   None

     OUTPUTS:  None

     OPTIONAL OUTPUTS:  None

     KEYWORD Parameters:   None

     COMMON BLOCKS:  None

     SIDE EFFECTS:   None

     RESTRICTIONS:   Reqires XCOLORS from the Coyote Library:

                         http://www.dfanning.com/programs/xcolors.pro

     PROCEDURE:

      Draws a 31x25 set of small rectangles in 256 different colors.
      Writes the color index number on top of each rectangle.

     MODIFICATION HISTORY:  David Fanning, RSI, May 1995

      Widgetized and made it work in 24-bit color. Colors are
         updated by clicking in window. 22 Oct 98. DWF

      Replace POLYFILL with TV command to avoid underflow error in
         Z-buffer. 8 March 99. DWF

(See c:\axis2000\cindex.pro)

## CLEAN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CLEAN

    LAST CHANGED: ----------------------------------- 23-feb-00

    PURPOSE:
    	This procedure performs a 2d fourier transform of an image.
      The user then selects a sub-region of the 2dFT which is zeroed.
     The rest of the array is thenn reverse transformed back into image space.
     Apropriate selection of sub-region provides a powerful means
     to remove periodic noise (e.g. from beam motion) from image data.

    CATEGORY:
    	STAND ALONE: image processing

    CALLING SEQUENCE:
    	CLEAN, array

    CALLED FROM AXIS:
    	->Filter->clean(FT)

    INPUTS:
    	ARRAY - 2d array

    KEYWORDS:
    	HELP - if set, gives instructions

    OUTPUTS:
    	The result is placed in the input array

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
       @BSIF_COM   common for BSIF data structures
       @IMG_COM    common for NSLS images

    RESTRICTIONS:
    	Warning :
    	Not assuming responsibility for misuse, or abuse of the image data.
    	Picking too many peaks may damage the data.

    PROCEDURE:
     ORIGINAL (X1A code)
     	Cleans up beam noise by picking noise peaks in the FFT with the mouse.
     	When done picking points, click the mouse off the edge of the FFT.  The
     	routine then puts up the cleaned FFT and writes the STXM file.
     NOW
    	user can only click twice, which defines a box. The contents of this box are removed.

    MODIFICATION HISTORY:
     (09-mar-92 spw) first version
     (xx-feb-93 cjj) improved
     (12-jan-99 aph) incorporated into AXIS
     (23-feb-00 aph) AXIS standard documentation

(See c:\axis2000\clean.pro)

## CLIP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CLIP

    LAST CHANGED: ----------------------------------- 20-oct-04

    PURPOSE:
    	This function selects a subset of intensities of an image.

    CATEGORY:
    	STAND ALONE: image processing

    CALLING SEQUENCE:
    	Result = CLIP(tmp)

    CALLED FROM AXIS:
    	->Images->Clip

    INPUTS:
    	TMP - an AXIS 2d structure (image)

    KEYWORDS:
    	SAVE_HIST  - if set, write out histogram

    OUTPUTS:
    	The result is an AXIS 2d structure with modified intensities.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    SIDE EFFECTS: none

    PROCEDURE:
    	A histogram of the intensities of an image are displayed as a spectrum on
     MainImg (if in AXIS) or on the current or a generated window.
     Two cursor clicks then identify lower and upper bounds of interest.
     Lower intensities are set to the lower bound.
     Higher intensities are set to the upper bound.
     This is an alternate to DEGLITCH. DEGLITCH works nicely for localized,
     single pixel 'glitches' but CLLP is better for extended artefacts

    EXAMPLE:
     Create a sample nxn image, display, clip, and redisplay
    	n = 100 & t = findgen(n) & d = dist(n)
    	a = {t:'2d', x:t, y:t, xl:'x', yl:'y', d: d, dl:'test'}
    	splot2d, a   ; display input
    	b = CLIP(a)	 ; clip
    	splot2d, b

    MODIFICATION HISTORY:
     (31-dec-99 aph) isolated from AXIS_C as a stand-alone
    				  AXIS standard documentation
     (09-jan-00 aph) fixed up error from histogram with big images (out of virtual memory)
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index
     (08-may-01 aph) tried to fix problem with flakey clipping - NOT FIXED !!
    		output of histogram somehow seems to get mis-identified as a structure
    		suspect variable confusion in histogram.pro, but this is not an open file
    		REPLACING FLOAT with a LONG seems to have fixed this - values in array is the issue
     (30-sep-01 aph) removed 'LONG' - this does not seem to do anything useful
     (13-mar-02 aph) add save_hist keyword
     (10-apr-02 aph) replace IDL clip ruotine with where command
     (02-may-02 aph) adopt RSI suggestion to make clip work reliably
     (10-apr-04 aph) add annotation to header
     (20-oct-04 aph) simplify tag

(See c:\axis2000\clip.pro)

## COLORBAR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
       COLORBAR

     PURPOSE:
           The purpose of this routine is to add a color bar to the current
           graphics window.

     CATEGORY:
           Graphics, Widgets.

     CALLING SEQUENCE:
           COLORBAR

     INPUTS:
           None.

     KEYWORD PARAMETERS:

           BOTTOM:   The lowest color index of the colors to be loaded in
                     the bar.

           CHARSIZE: The character size of the color bar annotations. Default is 1.0.

           COLOR:    The color index of the bar outline and characters. Default
                     is !P.Color..

           DIVISIONS: The number of divisions to divide the bar into. There will
                     be (divisions + 1) annotations. The default is 6.

           FONT:     Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.

           FORMAT:   The format of the bar annotations. Default is '(I5)'.

           MAX:      The maximum data value for the bar annotation. Default is
                     NCOLORS.

           MIN:      The minimum data value for the bar annotation. Default is 0.

           MINOR:    The number of minor tick divisions. Default is 2.

           NCOLORS:  This is the number of colors in the color bar.

           POSITION: A four-element array of normalized coordinates in the same
                     form as the POSITION keyword on a plot. Default is
                     [0.88, 0.15, 0.95, 0.95] for a vertical bar and
                     [0.15, 0.88, 0.95, 0.95] for a horizontal bar.
    ;
           RANGE:    A two-element vector of the form [min, max]. Provides an
                     alternative way of setting the MIN and MAX keywords.

           RIGHT:    This puts the labels on the right-hand side of a vertical
                     color bar. It applies only to vertical color bars.

           TITLE:    This is title for the color bar. The default is to have
                     no title.

           TOP:      This puts the labels on top of the bar rather than under it.
                     The keyword only applies if a horizontal color bar is rendered.

           VERTICAL: Setting this keyword give a vertical color bar. The default
                     is a horizontal color bar.

     COMMON BLOCKS:
           None.

     SIDE EFFECTS:
           Color bar is drawn in the current graphics window.

     RESTRICTIONS:
           The number of colors available on the display device (not the
           PostScript device) is used unless the NCOLORS keyword is used.

     EXAMPLE:
           To display a horizontal color bar above a contour plot, type:

           LOADCT, 5, NCOLORS=100
           CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
              C_COLORS=INDGEN(25)*4, NLEVELS=25
           COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]

     MODIFICATION HISTORY:
           Written by: David Fanning, 10 JUNE 96.
           10/27/96: Added the ability to send output to PostScript. DWF
           11/4/96: Substantially rewritten to go to screen or PostScript
               file without having to know much about the PostScript device
               or even what the current graphics device is. DWF
           1/27/97: Added the RIGHT and TOP keywords. Also modified the
                way the TITLE keyword works. DWF
           7/15/97: Fixed a problem some machines have with plots that have
                no valid data range in them. DWF
           12/5/98: Fixed a problem in how the colorbar image is created that
                seemed to tickle a bug in some versions of IDL. DWF.
           1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
           3/30/99: Modified a few of the defaults. DWF.
           3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
           3/30/99: Added the RANGE keyword. DWF.
           3/30/99: Added FONT keyword. DWF
           5/6/99: Many modifications to defaults. DWF.
           5/6/99: Removed PSCOLOR keyword. DWF.
           5/6/99: Improved error handling on position coordinates. DWF.
           5/6/99. Added MINOR keyword. DWF.
           5/6/99: Set Device, Decomposed=0 if necessary. DWF.

(See c:\axis2000\colorbar.pro)

## COPY_BYTES.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           COPY_BYTES.PRO
     PURPOSE:
           Copies bytes between a source and destination regardless of whether or
           not they have the same structure. It can be useful for copying, for
           instance between a byte array and a structure. It must be used
           with care.
     CALLING SEQUENCE:
           COPY_BYTES, n_bytes, source, destination
     INPUTS:
       N_BYTES
           The number of bytes to copy.
       SOURCE
           The location to copy from.
     OUTPUTS:
       DESTINATION
           The location to copy to.
     RESTRICTIONS:
           This routine does not do any error checking. The user must ensure that
           SOURCE and DESTINATION can each hold N_BYTES.
           Under UNIX the use must have write permission in the current default
           directory.
     PROCEDURE:
           Under VMS uses Run-Time Library routine LIB$MOVC3.
           Under UNIX opens a file, write out the source, reads back into
           destination.
     MODIFICATION HISTORY:
           Created Nov. 1991 by Mark Rivers

(See c:\axis2000\copy_bytes.pro)

## CRYO_TO_STXM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CRYO_TO_STXM

    LAST CHANGED: ----------------------------------- 23-feb-00

    PURPOSE:
    	This procedure converts one or more files in cryo-stxm format (*.sxm)
     to the old X1A STXM format (*.nc).

    CATEGORY:
    	STAND ALONE: file utility

    CALLING SEQUENCE:
    	CRYO_TO_STXM, find_file_string

    CALLED FROM AXIS:
    	->Read->Images->NSLS->cryo

    ROUTINES
    	if the file contains multiple PROs
     list these here, along with a brief description of their function

    INPUTS:
    	FINDFILE_STRING = list of files to convert, from findfile routine

    KEYWORDS: none

    OUTPUTS:
    	The result is written to file with same main name and '.nc' extension

    COMMON BLOCKS:
    	@bsif_common - commons for old stxm format
    	@sxm_common - part of sxm common
    	@sxm_acommon - remainder of sxm common

    MODIFICATION HISTORY:
     (xx-mmm-99 cjj) first written as part of sxm package
     (xx-sep-99 aph) adapted from X1A new SXM code to provide ability to read cryo files into AXIS
     (23-feb-00 aph) AXIS standard documentation

(See c:\axis2000\cryo_to_stxm.pro)

## CW_RSLIDER

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	CW_RSLIDER

    LAST CHANGED: ----------------------------------- 	25-Dec-07

     PURPOSE:
    	This procedure and associated functions/procedures is a compound widget that generates a
     colored slider which defines a value range, with independent control
     of lower bound (left click & drag), upper bound (right click & drag)
     or position (left&right (or middle) click & drag)

     CATEGORY:
    	Utility
       used in image~generate mask and stacks~RGB composite map

     CALLING SEQUENCE:
      Result = CW_RSLIDER, base, uvalue = uvalue, uname = uname, color = color, bg_color = bg_color,  $
        maximum = maximum, minimum = minimum, xsize = xsize, ysize =  ysize, $
        xoffset = xoffset, yoffset = yoffset, value = value, reverse = reverse, $
        vertical = vertical, event_pro = event_pro

     INPUTS:
     	BASE    ID of parent widget (compound widgets must be contained in another widget)

     KEYWORDS:
    	uvalue
    	uname
    	color		color of slider as a 3-value byte array  e.g. [255,0,0] = red
     	bg_color 	color of backgound of slider as a 3-value byte array
    	maximum 	maximum limit of slider (double)
    	minimum 	minimum limit of slider (double)
    	xsize		x-dimension in pixels
    	ysize		y-dimension in pixels
    	xoffset		x-offset relative to base
    	yoffset		y-offset relative to base
    	value		value of range of slider (2-value double array)
    	reverse		reverse clicks for lower / upper or left / right limits
    	vertical	orient slider vertically
    	event_pro

     OUTPUTS:
    	A slider is created in the base

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     EXAMPLE:
       see TEST_CW_RSLIDER.PRO for illustration of how this is used

      RS_min = double(r_min - 0.05*(r_max-r_min))
      RS_max = double(r_max + 0.05*(r_max-r_min))
      Rvalue = [double(r_min), double(r_max)]
      RS_base = WIDGET_BASE(RBG_BASE, UNAME='WID_BASE_R', TITLE="Red", XPAD = 5, YPAD = 5, $
               XOFFSET=40, YOFFSET=40, SCR_YSIZE=200,SCR_XSIZE=70)
      sliderR = CW_RSLIDER(RS_BASE, UNAME='SLIDER_R', color=[255,0,0], /vertical, $
                XSIZE=20, YSIZE = 180, MINIMUM=RS_min, MAXIMUM=RS_max, VALUE=Rvalue )

     MODIFICATION HISTORY:
     (27-Dec-07 aph) AXIS standard header added
     (28-Dec-07 aph^2) min/max adjustment added

(See c:\axis2000\cw_rslider.pro)

## DEGLITCH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	DEGLITCH

    LAST CHANGED: ----------------------------------- 19-dec-00

    PURPOSE:
    	This function replaces out-of-bound values with
     a local 3-point average. Bounds are user selected by cursor.

    CATEGORY:
    	STAND ALONE: image processing

    CALLING SEQUENCE:
    	Result = DEGLITCH(tmp)

    CALLED FROM AXIS:
    	->Images->Deglitch

    INPUTS:
    	A - an array (treated as 1-d vector, even if an image)

    KEYWORDS:
    	none

    OUTPUTS:
    	The result is an array with modified intensities.

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    SIDE EFFECTS:
    	A window is created if there is no window currently displayed.

    PROCEDURE:
    	The intensities of an image are displayed as a spectrum on
     MainImg (if in AXIS) or on the current or a generated window.
     Two cursor clicks then identify lower and upper bounds of interest.
     Values outside the range are replaced by local averages
     This is an alternate to CLIP. It works nicely for localized,
     single pixel 'glitches' but CLLP is better for extended artefacts

    EXAMPLE:
     Create a sample nxn image, display, clip, and redisplay
    	n = 100 &  d = dist(n) & d(n/2)=5*d(n/2)
    	tvscl, d   ; display input
    	b = DEGLITCH(d)	 ; deglitch
    	tvscl, b

    MODIFICATION HISTORY:
     (31-dec-99 aph) isolated from AXIS_C as a stand-alone
    				  AXIS standard documentation
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index

(See c:\axis2000\deglitch.pro)

## DINDEX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	DINDEX

    LAST CHANGED: ----------------------------------- 25-feb-00

    PURPOSE:
    	This function gets the index of the data point in a 2-d data structure (image)
     which is closest to the cursor (x,y) values
     It assumes the 2-d data structure has (x,y,d) components

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	Result = DIndex(X,Y,tmp)

    CALLED FROM AXIS:
      many paces

    INPUTS:
    	X - X cursor position in data units
       Y - Y cursor position in data units
       TMP  - the 1-d data structure

    KEYWORDS: none

    OUTPUTS:
    	IND - (i,j) index of data closest to cursor position

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (27-may-97 aph)  first written, in AXIS
     (03-Mar-98 aph) segregated as separate file
     (13-Apr-98 aph) treat (x,y) independently
     (25-feb-00 aph) AXIS standard documentation

(See c:\axis2000\dindex.pro)

## DISP3COL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	DISP3COL

    LAST CHANGED: ----------------------------------- 22-feb-06

    PURPOSE:
    	This procedure generates a composite image from any 3 images using R,G,B mapping
     with user selectable absolute or relative scaling of the components.
     Interpolates to comon mesh prior to RGB generation

    CATEGORY:
    	AXIS: image analysis. Also executes stand-alone

    CALLING SEQUENCE:
     for procedures:
    	DISP3COL,im1, im2, im3, r=r, b=b, g=g, axis_on=axis_on, channel=channel

    CALLED FROM AXIS:
    	->Images->RGB image

    INPUTS:
    	All input parameters are passed as keywords.

    KEYWORDS:
    	IM1 - 2d array with first image
    	IM2 - 2d array with second image
    	IM3 - 2d array with third image
    	R - red color table
    	G - green color table
    	B - blue color table
    	axis_on - indicates called from AXIS
    	channel - indicates number of channels in image (AXIScomposite uses 3)

    OUTPUTS:
    	The RGB-coded combination image is placed in buffer 0
     and saved as a tif file. Default format is 3-channel, byte pixels.

     RESTRICTIONS
      (a) Since write as byte pixels, can be losss of intensity scale resolution
     This is ARTIFICIAL since IDL can write integer or reals (AXIS images are reals)
      (b) Each image is INDEPENDENTLY byte scaled - relative intensities of
     the colors do NOT reflect relative intensities in the 3 component images

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     ( 9-jun-99 aph) first developed from tv3d.pro (Eli's stereo projection code)
     (25-jun-99 aph) adapt to single (image, spectra) color table
     (25-feb-00 aph) AXIS standard documentation
     (16-apr-00 aph) get dimensions correct and set up to display correctly in AXIS
                   remove intermediate writing of bytscl images -> no loss of resolution
     (30-nov-00 cgz) Replaced call of wdivide with explicit !p.multi statement
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement
     (06-dec-00 aph) autoscale option added
     (02-may-04 aph) replace get_num with dialog_message (default is autoscale)
     (22-feb-06 aph) interpolate to same (x,y) pixels

(See c:\axis2000\disp3col.pro)

## DISTANCE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: DISTANCE

    LAST CHANGED: ----------------------------------- 08-may-01

     PURPOSE:
    	This function computes the distance between two points in Cartesian space

     CATEGORY:
    	math utility

     CALLING SEQUENCE:
    	Result = DISTANCE(pt1, pt2)

     INPUTS:
    	PT1 	[x1,y1]
    	PT2		[x2,y2]

     KEYWORDS: none

     OUTPUTS: returns SQRT(|x1-x2|^2 + |y1-y2|^2)

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (08-may-01 aph) first wrote; AXIS standard header added

(See c:\axis2000\distance.pro)

## EDGEGAUSS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	EDGEGAUSS

    LAST CHANGED: ----------------------------------- 25-feb-00

    PURPOSE:
    	This procedure uses gaussian smoothing to edge enhance images
     as part of the stack_align procedure

    CATEGORY:
    	STAND ALONE: image processing

    CALLING SEQUENCE:
     for procedures:
    	EDGEGAUSS, image_array, sigma, dc_value, $
        zero_edge=zero_edge, help=help

    CALLED FROM AXIS:
    	Stack_align

    INPUTS:
    	IMAGE_ARRAY - image
    	SIGMA - width of Gaussian smooth
    	DC_VALUE - offset to be removed prior to smoothing

    KEYWORDS:
    	ZERO_EDGE - if set, force edges of image to zero
    	HELP - print information message

    OUTPUTS:
    	The edge-sharpened image is returned as image_array

    COMMON BLOCKS: none

    PROCEDURE:
     Revised June 30, 1998 to let one zero out the trace along the
     gaussian border.  If you set /zero_edge, the DC value from
     1 sigma to 2 sigma from the border is calculated and subtracted
     from the image, and it is also returned to you

    MODIFICATION HISTORY:
     (30-Jun-98 cjj) add zero_edge keyword
     (25-feb-00 aph) AXIS standard documentation

(See c:\axis2000\edgegauss.pro)

## ENERGY_SORT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		ENERGY_SORT

    LAST CHANGED: ----------------------------------- 29-Oct-05

     PURPOSE: incomplete ROUTINE to sort energies of a stack in increasing energy order

      EXTRACTED from READ_LOX.PRO  29-oct-05

      screws up energy scales big time whe run on IDL 6.2

      for now let the stack reader deal with out-of-order energies

(See c:\axis2000\energy_sort.pro)

## FILE.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	FILE.PRO

    LAST CHANGED: ----------------------------------- 26-feb-00

    PURPOSE:
    	This set of functions processes text information associated with
     reading ascii data files.
     	ISNUMBER - check if string is numerical
    	PARSESTRING - splits text string into constituent numbers.
    	CHKFILEBLOCKS - determines block structure of a text string
    	TEXT_READ - multi-block file read-in
    	TEXT_READ1 - simple text file read-in (single block)

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = text_READ1(FILNENAME) etc

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function ISNUMBER, STRING
    	returns 1 if string is numerical

    	function PARSESTRING, STRING
     	if the input string is a tab or space delimited list of #s,
     parsestring returns an array of numbers.
     if no numbers are found, or other error, returns 0
     you can distinguish the error from "0.0" using the size function,
     since the error condition is a scalar, not a vector

    	function CHKFILEBLOCKS, FNAME
    	looks in FILE (fname), counts the number of "blocks" of data, where
     a block is a (r x c) block of numbers. If there are no blocks found,
     returns a scalar 0, else returns a (b, 2)-dim array, where b is the
     block index, (b,0) is the number of rows, (b,1) is the number of columns
     and (b,2) is the starting row in the file (counting from 0)

    	function TEXT_READ, FNAME, block=b, blkInfo=bi
    	reads the bth block (starting from zero) in the file
     and returns the contents as a matrix
     KEYWORDS:
    	BLOCK - block number to read
    	BLKINFO - string array for header information for block

    	function 	TEXT_READ1, FNAME, print=print
     reads simple text files consisting of 1 block plus a header
     KEYWORDS
    	PRINT - if set, then print header information

    COMMON BLOCKS: none

(See c:\axis2000\file.pro)

## FILE2STRING

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FILE2STRING

     PURPOSE:
           This function reads the contents of a text file into a string array,
           one line per element.

     CATEGORY:
           Input / Output

     CALLING SEQUENCE:
           Out_string = FILE2STRING(Filename, Count)

     INPUTS:
           Filename:     The name of the text file from which to read string data.

     KEYWORD PARAMETERS:
           COMMENT_CHAR: A string containing a single character used to
                         identify comments. If a line in the text file
                         starts with the comment character, it is not read.

     OUTPUTS:
           Out_string:   The string array containing the lines of the text file.

           Count:        A named variable to receive the number of lines read.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           May, 1997

(See c:\axis2000\file2string.pro)

## FILENAME_IN_CAPITALS[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		FILENAME_IN_CAPITALS

    LAST CHANGED: ----------------------------------- 	25-Dec-07

     PURPOSE:
    	This procedure

     CATEGORY:
    	Image display.

     CALLING SEQUENCE:
     for procedures:
    	ZOOM [, FACT = Fact, /INTERP, XSIZE = Xs, YSIZE = Ys, /CONTINUOUS, $
    		/KEEP, ZOOM_WINDOW=Zoom_Win, /NEW_WINDOW ]
     for functions:
    	Result = GET_NUM(Prompt = prompt, Value = value)

     INPUTS:
     This section is for POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

     KEYWORDS:
    	KEY1:

     OUTPUTS:
    	No explicit outputs.   A new window is created if necessary

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:
    	Any known ?

     PROCEDURE:
    	details where needed

     EXAMPLE:
    	Please provide a simple example here. An example from the PICKFILE
    	documentation is shown below. Please try to include examples that
           do not rely on variables or data files that are not defined in
           the example code. Your example should execute properly if typed
           in at the IDL command line with no other preparation.

    	Create a PICKFILE widget that lets users select only files with
    	the extensions 'pro' and 'dat'.  Use the 'Select File to Read' title
    	and store the name of the selected file in the variable F.  Enter:

    		F = PICKFILE(/READ, FILTER = ['pro', 'dat'])

     MODIFICATION HISTORY:
     (25-Dec-07 aph) AXIS standard header added

(See c:\axis2000\axis_header_template.pro)

## FILENAME_IN_CAPITALS[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		FILENAME_IN_CAPITALS

    LAST CHANGED: ----------------------------------- 	10-Oct-08

     PURPOSE:
    	This procedure

     CATEGORY:
    	Image display.

     CALLING SEQUENCE:
     for procedures:
    	ZOOM [, FACT = Fact, /INTERP, XSIZE = Xs, YSIZE = Ys, /CONTINUOUS, $
    		/KEEP, ZOOM_WINDOW=Zoom_Win, /NEW_WINDOW ]
     for functions:
    	Result = GET_NUM(Prompt = prompt, Value = value)

     INPUTS:
     This section is for POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

     KEYWORDS:
    	KEY1:

     OUTPUTS:
    	No explicit outputs.   A new window is created if necessary

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:
    	Any known ?

     PROCEDURE:
    	details where needed

     EXAMPLE:
    	Please provide a simple example here. An example from the PICKFILE
    	documentation is shown below. Please try to include examples that
           do not rely on variables or data files that are not defined in
           the example code. Your example should execute properly if typed
           in at the IDL command line with no other preparation.

    	Create a PICKFILE widget that lets users select only files with
    	the extensions 'pro' and 'dat'.  Use the 'Select File to Read' title
    	and store the name of the selected file in the variable F.  Enter:

    		F = PICKFILE(/READ, FILTER = ['pro', 'dat'])

     MODIFICATION HISTORY:
     (10-Oct-08 aph) AXIS standard header added

(See c:\axis2000\ax_header_template.pro)

## FILE_OVERWRITE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
          FILE_OVERWRITE

     LAST CHANGED ---------------------------- 27-feb-00

     PURPOSE:
          widget to warn user if file over writing is occurring.
    	'0 = change name, 1 = overwrite, 2 = overwrite all' - call from PICKFILE2

     CATEGORY:
           Input/Output.

     CALLING SEQUENCE:
    	Result = FILE_OVERWRITE(PROMPT = 'prompt', VAL = 1, GROUP = AxisID)

     INPUTS: none

     KEYWORDS:
       	PROMPT = prompt to user
           VAL = current (default) value (0 = no overwrite, 1 = overwrite)
    		GROUP = Widget_Id of group leader (must be set to force modal)

     OUTPUTS:
           The function returns a FLOAT value which is either
    		the existing value (user hits )
    		or the first number in the string the user types

     ROUTINES
    	OWRITE_EVENT, event - event processing procedure
    	FILE_OVERWRITE - function

     COMMON BLOCKS:
           Owrite_com, text

     SIDE EFFECTS: None.

     RESTRICTIONS:
           See DESCRIPTION.

     DESCRIPTION:
           This routine handles a user prompt when a file is found to exist.
     If the top level group ID is supplied, the function widget is
     put into modal mode (the dialog box stays on top until user completes input
     and disables other functions of AXIS)

     MODIFICATION HISTORY:
     (31-dec-99 aph) first written
     (27-feb-00 aph) documented

(See c:\axis2000\file_overwrite.pro)

## GEN_AA_STRING

[Previous Routine] [Next Routine] [List of Routines]

    NAME: gen_AA_String

    LAST CHANGED: ----------------------------------- 	02-Nov-07

     PURPOSE:
    	This function genertes and saves to a file a text string
     derived from  a file containing code letters and numbers
     to be used in conjunction with XSpecSIm to simulate protein spectra

     CATEGORY:
    	utility (not in aXis2000)

     CALLING SEQUENCE:
    	Result = gen_AA_String(file = file)

     INPUTS:
     This section is for POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

     KEYWORDS:
    	FILE	filename (if not included user is allowed to browse)

     OUTPUTS:
    	user is prompted for name of a text file to be written

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     MODIFICATION HISTORY:
     (02-Nov-07 aph) first version

(See c:\axis2000\gen_aa_string.pro)

## GEN_READ

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	GEN_READ

    LAST CHANGED: ----------------------------------- 15-nov-00

    PURPOSE:
    	This function reads general ALS BL7 XPS labview format files into a data structure
       uses pickfile2() to select input file if fname not specifed

    CATEGORY:
    	STAND ALONE: utility (als)

    CALLING SEQUENCE:
    	Result = GEN_READ(FNAME, /options)

    CALLED FROM AXIS:
    	->Read->Spectra->ALS SPEM

    INPUTS:
    	FNAME - filename (optional; if not provided, uses pickfile2)

    KEYWORDS:
    	INFO - print information about routine
    	QUIET - no logging comments
    	PATH - path for data file
    	PLOT - plot data
    	DEBUG - turn on debugging code
    	NOREFORM - do not reform the output data array
       TIME=timestr - returns 'Aq. End' date and time string from line 7

    OUTPUTS:
    	The result is a data structure specific to ALS BL 7 XPD and SPEM
     electrn spectroscopy data. (recorded with 16-channel PHI analyser)
    	 answer={fname:fname, summary:summ, phiDescr:phiDesc, $
         IndNames:indnam, IndVars:indv, $
         SingleNames:singnam, singleData:singDat, $
         NormNames:normnam, norm1Dim:norm1D,  RgnInfo:rgninfo, $
         x:-1.*xData, y:yData, yn:ynData}

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    RESTRICTIONS:
    	** doesn't read multiple  (non-VF files properly)

    MODIFICATION HISTORY:
     (xx-mmm-95  er)  created
     (03-dec-95  jd)  added REFORM(xdata,ydata,yndata) in gen_read
     (xx-aug-96  jd)  fixed up bugs in reading MgKa data
                      still problems with multiple spectral ranges
     (xx-dec-96  er)  fixed reading of multiple spectral region files(?)
     (13-feb-97  jd)  added recognition of Quadrupole scan; returns -1
     (16-feb-97  er)  added keyword NOREFORM
     					added recognition of snapshots (have shorter rgninfo)
     (07-apr-98  er) fixed a bug with multiple regions.
     (31-JAN-99  er)  changed max line length 32K --> 64K
     (27-feb-00 aph) AXIS standard documentation
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)

(See c:\axis2000\gen_read.pro)

## GET_NUM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	GET_NUM

    LAST CHANGED: ----------------------------------- 01-Jun-08

    PURPOSE:
    	This procedure is a widget that displays the current value
     of a parameter (if defined) and then allows user to input a replacement value
     A  (enter) will retain the same value

    CATEGORY:
    	AXIS: utility (can run stand alone)

    CALLING SEQUENCE:
    	Result = GET_NUM(Prompt = prompt, Val = value, group = Axis_ID))

    CALLED FROM AXIS:
      many places

    ROUTINES
    	NUM_EVENT, Event - event processing
    	GET_NUM - widget

    INPUTS: none

    KEYWORDS:
           VAL = current (default) value
       	PROMPT = prompt to user
    		GROUP = Widget_Id of group leader (must be set to force modal; Axis_ID is name for axis_c)

    OUTPUTS:
           The function returns a FLOAT value which is either :
    		the existing value (user hits )
    		or the first number in the string the user types

    COMMON BLOCKS:
           TXTCOM (internal to get_num)

    SIDE EFFECTS:
    	A window is created/destroyed.

     DESCRIPTION:
           This routine allows user to provide  a numerical value
    		If the top level group ID is supplied, the function widget is
    		put into modal mode (stays on top until user completes input; disables other functions of AXIS)

     EXAMPLES:
           new_value = get_num(prompt='New value',val=current_value, group = axis_id)

     DEVELOPMENT NOTES:
    		should autosense if AXIS is the caller to avoid having to
    		explicitly provide the group ID

     MODIFICATION HISTORY:
     (20-jun-97 aph) first written
     (05-jun-98 aph) made function return a scalar NOT A 1-element array.
     (07-jun-99 aph) add separate prompt display; use IDL 5.2 modal convention; proper docs
     (27-feb-00 aph) AXIS standard documentation
     (09-sep-02 aph) format displayed number
     (01-Jun-08 aph) fix up documentation to be correct on 'val' and 'Axis_ID'

(See c:\axis2000\get_num.pro)

## GET_PATH.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	GET_PATH.PRO

    LAST CHANGED: ----------------------------------- 20-May-00

    PURPOSE:
    	This function find the location of 'FILE1'
     It is used in filename list processing to get around fact that
     files are frequently moved and thus have different paths
     The valid path to 'file1' is returned (with correct separator for the host computer)
     or '' (empty string) if this cannot be found

    CATEGORY:
    	AXIS:  utility (operates stand alone)

    CALLING SEQUENCE:
    	Result = GET_PATH(file1, list=list)

    CALLED FROM AXIS:
    	various places

    ROUTINES
    	if the file contains multiple PROs
     list these here, along with a brief description of their function

    INPUTS:
    	INPUT - POSITIONAL INPUTS only (not keywords)
    	All input parameters are passed as keywords.

    KEYWORDS:
    	LIST = name of file containing list of file names

    OUTPUTS:
     Path to file1 is returned

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
     If the path associated with 'file1' is not correct, various
     plausible locations are checked (defPath, the current default path in AXIS)
     and the user is requested to locate the file by using pickfile dialog
     if the file is not found through 3 search strategies, an empty string is returned

    MODIFICATION HISTORY:
     (15-jun-99 aph) first version
     (18-jul-99 aph) rewrote to be more flixible
     (20-May-00 aph) AXIS standard documentation

(See c:\axis2000\get_path.pro)

## GET_TEXT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	GET_TEXT

    LAST CHANGED: ----------------------------------- 27-feb-00

    PURPOSE:
    	This function is a pop-up widget that
     allows user to input one string of text

    CATEGORY:
    	AXIS: utility (operates as stand alone)

    CALLING SEQUENCE:
    	Result = GET_TEXT(Prompt = prompt, Value = value, group = AxisID)

    CALLED FROM AXIS:
    	many routines

    ROUTINES
    	TEXT_EVENT, event - event processing procedure
    	GET_TEXT - the widget code

    INPUTS: none

    KEYWORDS:
    	PROMPT - title at top of widget
    	VAL - default value of the text string
    	group - group ID of caller

    OUTPUTS:
    	The string is returned and the widget destroyd.

    COMMON BLOCKS:
    	TXTCOM, txt

    MODIFICATION HISTORY:
     (19-Jun-97 aph) created
     (05-jul-98 aph) made it return string not string array !
     (13-dec-98 aph) make it work with IDL 5.2; VALUE needed to be defined(!)
     (20-dec-98 aph) allow scrolling; append; customize for IDL5.1 (Array-2); IDL4.0(array-1)
     (08-jan-99 aph) error when txt returns only 1 entry
     (27-feb-00 aph) AXIS standard documentation; remove modal call to xmanager

(See c:\axis2000\get_text.pro)

## IDL_STARTUP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      IDL_STARTUP

     LAST CHANGED: ----------------------- 03-Jan-00

    PURPOSE:
    	guides startup of IDL with choices of Zimba stack analyze, AXIS or IDL.
     Users are encouraged to select this as their start-up file for IDL
     so that AXIS will not automatically load (and thus give problems
     assocaited with codes of same names but different content)

    MODIFICATION HISTORY:
     (17-Oct-99 aph) first introduced
     (03-jan-00 aph) AXIS standard documentation

(See c:\axis2000\idl_startup.pro)

## IMG_ALIGN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	IMG_ALIGN

    LAST CHANGED: ----------------------------------- 20-apr-00

    PURPOSE:
    	This procedure aligns one image to the spatial scale of the first file
     processed which acts as the reference for all subsequent files.
     The alignment can be a shift (1-point) or stretch-shift (2-point).

    CATEGORY:
    	AXIS: image analysis (AXIS - captive)

    CALLING SEQUENCE:
    	IMG_ALIGN, one_pt=one_pt

    CALLED FROM AXIS:
    	->Stacks->align->{shift, stretch-shift}

    INPUTS:
    	INPUT - via common - file list

    KEYWORDS:
    	ONE_PT	if set, only align at 1-point, not 2

    OUTPUTS:
    	Aligned, clipped and (optionally) binned file is written as
    	s____.nc (1-point)  or a_____.nc (2-point)

    COMMON BLOCKS:
    	@AXIS_COM	axis standard set of common blocks
    	@BSIF_COM	nsls common

     PROCEDURE
     manual alignment of images
     has ability to linearly distort image to account for sample stretching !!
     if one_pt is set, then only shifts selected point to reference value
     otherwise asks user for 2 fiducials and stretch-shifts each file to MATCH first file
     generates align-shift files in buffers 5,8 (X) &  6,9 (Y), 4 (stretch)
     cuts user-selected region;
     meshes to user-defined pixelation with optimum binning
     stores processed data in netCDF format for use in STACK_ANALYZE
     saves file name to generate list for stack_analyze

     WARNINGS:
    		only prompts user for transformation paramaters on FIRST pass

           CLEAR buffers (4,5,6),8,9 to reset image alignment

    MODIFICATION HISTORY:
     ( 5-Mar-98 aph) first version - worked
     (xx-apr-98 aph) changed something - did not correctly cut data - broken to 6-jun-98
     ( 6-jun-98 aph) replaced direct call to wrstx_ax with sav_nsls
     (14-jun-98 aph) axis_com
     (18-sep-98 aph) cosmetics - checking possible error
     ( 8-jun-99 aph) add group to get_num calls
     (23-aug-99 aph) fixing up 'freeze' when called from axis 1.7
    				 - CURSOR not supposed to be used !!
     (19-sep-99 aph)  complete debugging freeze-up problem
    			a) 'first' used in aaa_axis changed to 'firstimg' -> correct image display
                b) turn-off hourglass (turned on by PlotBuf) - by a kluge
     (15-apr-00 aph) AXIS standard documentation
     (20-apr-00 aph) debug to see why does not work at fine scale

(See c:\axis2000\img_algn.pro)

## IMG_ASAV

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	IMG_ASAV

    LAST CHANGED: ----------------------------------- 15-apr-00

    PURPOSE:
    	This procedure saves shift and stretch parameters in user-defined
     files at the end of IMAG_ALIGN

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	IMG_ASAV, one_pt=one_pt

    CALLED FROM AXIS:
    	->Stacks->image align -> {shift, stretch-shift}

    ROUTINES
    	if the file contains multiple PROs
     list these here, along with a brief description of their function

    INPUTS: via common

    KEYWORDS:
    	one-pt - defines shift only

    OUTPUTS:
     files for shifts (2 or 4); stretch factors are writen to disk
     Filenames (*.sl) and SHIFT data (*.al) files
     Buffer Contents	filename
    	5		X1		*.aX1
    	6		Y1      *.aY1
     	8		X2      *.aX2
    	9 		Y2      *.aY2
    	4 		stretch factor (regenerate independent (X,Y) from files/buffers

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     ( 7-jun-98 aph) extracted from "Image_Process.Image alignment.save shifts"
     (14-jun-98 aph) axis_com
     ( 7-jul-99 aph) FREE_LUN as well as close !
     (15-apr-00 aph) AXIS standard documentation

(See c:\axis2000\img_asav.pro)

## IMG_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	IMG_COM.PRO

    LAST CHANGED: ----------------------------------- 15-apr-00

    PURPOSE:
    	This defines the common block which is used for SPEM image display.

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:  include file

    CALLED FROM AXIS:
    	->images->SPEM

    MODIFICATION HISTORY:
     (15-apr-00 aph) AXIS standard documentation

(See c:\axis2000\img_com.pro)

## IMG_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	IMG_LOAD

    LAST CHANGED: ----------------------------------- 07-jan-07

    PURPOSE:
    	This function reads in an image from (*.tif, *.bmp, *.gif) format files
     and returns it as a '2d' or '3d' type axis structure
     Also reads in Elmitec exported tif files

    CATEGORY:
    	AXIS: image utility (runs stand alone)

    CALLING SEQUENCE:
    	Result = img_load(NOF=nof, error=err, values = values, silent=silent,  $
       	TIF=tif, BMP=bmp, GIF=gif, elmitec=elmitec, lox=lox, _extra=e)

    CALLED FROM AXIS:
    	->Image->Other->{*.tif, *.bmp, *.gif, *.jpg, *.png}

    INPUTS:
    	All input parameters are passed as keywords.

    KEYWORDS:
    	NOF	- no filter
       FILE - file name (no prompt unless that file is not found)
    	VALUES - if set, store as 2d-structure to allow axis display & mainpulation of data values
    			otherwise, store as 3d-structure; if VALUES GT 1 then use Red channel if 3-channel
    	TIF  - TIF read-in
    	GIF - GIF read-in
       JPG - JPG read-in (JPEG)
    	BMP - BMP read-in
    	PNG - PNG read-in
    	ELMITEC - file is in UView2002 format
    	LOX   - file is in Lox format
       SILENT  - do not print (axis_log) the details

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (20-feb-98 aph) first written
     (14-jun-98 aph) axis_com
     (20-jan-99 aph) convert to data!
     (11-jun-99 aph) make tif-read get and set RBG tables; remove reversal
     (25-jun-99 aph) use ax_names to generate fileshort
     (31-jan-00 aph) attempt to get RBG working
     (15-apr-00 aph) AXIS standard documentation
     (16-apr-00 aph) store 3-channel images properly - revise {3d} structure
     (31-dec-01 aph) PNG format added - evetually converge to this one for > IDL 5.1 compatibility
     (17-apr-02 aph) adapt for Elmitec read-in
     (29-apr-02 aph) revise to adapt for axis_c setting of E, size
     (05-may-02 aph) adapt for Sphinx 16-bit tif format
     (14-may-02 aph) reverse PNG
     (16-jul-02 aph) fix up Elmitec PEEM read in - scale too large since used unsigned keyword
     (23-may-04 aph) add lox read-in
     (29-Oct-05 aph) add keyword SILENT
     (22-feb-06 aph) add tmp.E (energy) to output; fix  /values for tif, png
     (25-apr-06 aph) add jpg read-in; add provision to use 1-channel for values
     (07-jan-07 aph) flip Lox Tif images vertically

(See c:\axis2000\img_load.pro)

## IMG_WARP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	IMG_WARP

    LAST CHANGED: ----------------------------------- 05-Mar-06

    PURPOSE:
    	This procedure warps an image to another image to get a common (x,y) scale
     by matching a set of fiducial points identifed
     by a cursor position selected by the user on first image

    CATEGORY:
    	AXIS:  image analysis

    CALLING SEQUENCE:
     for procedures:
    	IMG_WARP

    CALLED FROM AXIS:
    	->Images->waep

    INPUTS: none (uses axis buffers which must be pre-loaded)

    KEYWORDS: none

    OUTPUTS:
    	The result is written to buffer 0

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    RESTRICTIONS:
    	Occasionally does not work properly for unknown reasons

    PROCEDURE:
    	the images are first expanded to full axis window size
     to improve position accuracy - note the routines used are limited to integer pixel
     uses Poly_warp and poly_2d routines to match the two images
     the expanded image is then congridded back to its original dimensions

    MODIFICATION HISTORY:
     (08-jun-99 aph) extracted from aaa_axis - not functioning
                    add group ID to get_num call
     (24-feb-00 aph) add group ID to buffer call; pixels only
     (26-apr-00 aph) develop pixel-based CUT same; large -> small version
     (20-may-00 aph) AXIS standard documentation
     (26-Aug-05 aph) add write out of the w*.sl file (screwed up!)
     (05-Mar-06 aph) correct to write first file and save list as *.sl not *.nc !!

(See c:\axis2000\img_warp.pro)

## INTERP.PRO[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	INTERP.PRO

    LAST CHANGED: ----------------------------------- 15-nov-00

    PURPOSE:
    	Interpolates values
    	may be obsolete and might be eliminated

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = INTERP(Xi,XX,YY,MISSING=MI)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function INTERP, Xi, XX, YY, MISSING=MI
    	interpolates values

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (08-nov-00 cgz) AXIS standard documentation
     (08-nov-00 cgz) migrated from MATH.PRO
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)

(See c:\axis2000\interp.pro)

## INTERP.PRO[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	INTERP.PRO

    LAST CHANGED: ----------------------------------- 08-nov-00

    PURPOSE:
    	Interpolates values
    	may be obsolete and might be eliminated

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = INTERSPLINE(Yin,FIXEDY=FY)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function INTERSPLINE, Yin, FIXEDY=FY
    	pops up an interactive window; user uses cursor to define a spline smooth function
    	returns a spline-fitted array of the same length as yin
    	if fixedy is set, then y-values of spline are constrained to lie on the data.

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (08-nov-00 cgz) AXIS standard documentation
     (08-nov-00 cgz) migrated from MATH.PRO

(See c:\axis2000\interspline.pro)

## IRMAP_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME: IRMAP_LOAD

    LAST CHANGED: ----------------------------------- 19-Dec-08 (aph)

     PURPOSE:
       This prodecure reads an FTIR map from a set of csv files
      consisting of IR spectra at an array of points
      The data are converted to an aXis binary stack (*.ncb)

     CATEGORY:
    	utility; stand-alone or used through aXis2000

     CALLING SEQUENCE:
    IRMAP_LOAD, file=file, filter=filter, xcol=xcol, ycol=ycol, $
             multi=multi, skip=skip, int_factor=int_factor, typ=typ, NOF=nof, _extra=e

     INPUTS: only by keyword

     KEYWORDS:
     FILE		filename (*.map - array dimensions)
     FILTER  	filter extension (*.map)
     XCOL		number of x-axis (if multi-column)
     YCOL		number of y-axis (if multi-column)
     SKIP		number of header lines to skip  (if multi-column)
     MULTI		returns number of columns -1 = number of spectra
     NOF		no filter (*.*)
     _EXTRA	pass through keywords

     OUTPUTS:
    	Result is  a stack (x,y,wavenumber)

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (18-dec-08 aph) first version  - data sent by Paul Dumas (Soleil)

(See c:\axis2000\irmap_load.pro)

## JOIN_STRING

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           JOIN_STRING

     PURPOSE:
           This function joins the elements of a string array into a
           scalar string array, with the original elements separated by
           a user specified delimiter.

     CATEGORY:
           String processing.

     CALLING SEQUENCE:
           Result = JOIN_STRING(Input)

     INPUTS:
           Input:     The string array to be joined.

     KEYWORD PARAMETERS:
           DELIMITER: A string containing the delimiter between words.
                      The default delimiter is a single space.

           HEADER:    A string containing characters to precede the first
                      element. The default is no header.

           FOOTER:    A string containing characters to follow the last
                      element. The default is no footer.

     OUTPUTS:
           Returns the scalar string variable containing the joined result.

     EXAMPLE:
           If the input string is:
             input = ['Hello', 'world']

           then the command sequence:
             result = JOIN_STRING(input, DELIMITER=', ')

           produces the result:
             IDL> print, result
             Hello, world

           Note that the delimiter in this case includes a space.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           December, 1996

(See c:\axis2000\join_string.pro)

## LINE_FIT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    		  LINE_FIT

     LAST CHANGED: -------------------------------- 22-Sep-06

     This procedure selects inputs, fits spectrum at each point along a line spectral scan
     to sum of models.  Uses COMMON blocks to store and transfer data. Maximum 5 components !

     KEYWORDS
    	AXIS - if set, indicates called from AXIS
    	COEFF - name of file listing sources of reference spectra
    	VERBOSE - if set, additional information usppplied

     COMMON
     	AXIS_COM - AXIS
    	ANALCOM  - STACK (cjj)
     	BSIF_COM - nc data

    MODIFICATION HISTORY:
     (23-Dec-99 aph) first developed from stack_fit
     (27-feb-00 aph) add groupID to get_text
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement
     (04-Jun-03 aph) adapt to use ax_par_save & ax_par_load
     (22-sep-06 aph) fix output to display constant & chi-square properly
                     remove groom (left over from kneedler); use axis_log;

(See c:\axis2000\line_fit.pro)

## LITHO_READ

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	LITHO_READ

    LAST CHANGED: ----------------------------------- 22-feb-06

    PURPOSE:
    	This function reads a template (*.xyt)  image
     ( a set of (x,y,t) triplets ) for possible modification

    CATEGORY:
    	STAND ALONE: utility
       called from aXis2000 as read~other~axis_xyt

    CALLING SEQUENCE:
    	Result = LITHO_READ(tmp [, NOF=nof, file=file])

    CALLED FROM AXIS:
    	Read->Images->AXIS

    INPUTS:
    	 ascii file with multi-column data

    KEYWORDS:
    	FILE     - filename to write
       GROUP    - group of parent (axis_ID from axis)
    	VERBOSE  - print feedback on progress for trouble shooting

    OUTPUTS:
    	RESULT = TMP - axis format structure

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    ;MODIFICATION HISTORY:
     (03-Nov-05 aph) developed from litho_save
     (22-feb-06 aph) fix array dimension erorr that prevented read of some xyt files (required kluge)

(See c:\axis2000\litho_read.pro)

## LITHO_SAVE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	LITHO_SAVE

    LAST CHANGED: ----------------------------------- 22-Feb-06

    PURPOSE:
    	This function writes an image as a set of (x,y,t) triplets
     for all non-zero pixels for use as input to STXM_control
     for lthography

    CATEGORY:
    	STAND ALONE: utility
       called from aXis2000 as write~litho

    CALLING SEQUENCE:
    	Result = LITHO_SAVE(tmp [, NOF=nof, file=file])

    CALLED FROM AXIS:
    	Read->Images->AXIS

    INPUTS:
    	TMP - AXIS 2d structure

    KEYWORDS:
    	FILE - filename to write

    OUTPUTS:
    	RESULT = filename (a blank string if the user cancels)

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    ;MODIFICATION HISTORY:
     (04-aug-05 aph) developed from axb_save
     (18-aug-05 aph) add row, column indicators and overall size flag
     (03-Nov-05 aph) add header to indicate Xrange, Yrange and step size
     (22-feb-06 aph) increased number of digits saved for step

(See c:\axis2000\litho_save.pro)

## LN_ADD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      LN_ADD

    LAST CHANGED: ----------------------------------- 13-may-04

     PURPOSE:
    	This procedure adds contents of lines to generate:
      SPECTRA from line scans - sum horizontally (default) or
      Intensity profiles over a range of E  - add vertical by setting VERTICAL keyword

     CATEGORY:
    	Image & linescan processing; captive to AXIS

     CALLING SEQUENCE:
    	 LN_ADD  [, VERTICAL=vertical]

     INPUTS: none

     KEYWORDS:
    	VERTICAL	add vertical lines

     OUTPUTS:
    	summed lines displayed in buffer 9

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none known

     MODIFICATION HISTORY:
     (01-jan-99 aph) segregated from aaa-axis; merged horizontal & vertical
     (01-mar-00 aph) add groupID to buffer, get_text
     (10-may-01 aph) standard header; save limits
     (02-may-04 aph) modify header
     (13-may-04 aph) use Dialog_message

(See c:\axis2000\ln_add.pro)

## LN_ALIGN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	LN_ALIGN

    LAST CHANGED: ----------------------------------- 02-may-04

    PURPOSE:
    	This file tilts a linescan by a user defined line, to correct drift.

     PRO LN_align, curve=curve

    CATEGORY:
    	AXIS: data analysis

    CALLING SEQUENCE:
    	Linescan~align

    INPUTS:   none

    KEYWORDS:
    	CURVE - multi-section curve

    OUTPUTS:
    	returns structure with modified linescan

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

(See c:\axis2000\ln_align.pro)

## LN_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME: LN_LOAD

    LAST CHANGED: ----------------------------------- 	12-may-02

     PURPOSE:
    	This function loads a Beamline 7 STXM Line scan array
     from a text file (*,xa*, *,dat) and maps line-scan to (y)
     Energy-scan to (x)

     CATEGORY:
    	data read-in. stand-alone, or from axis.
     READ~ALS_STXM7.0.1 linescan

     CALLING SEQUENCE:
    	Result = LN_LOAD(file, FILTER=fltr, plot=pl, _extra=e)

     INPUTS:
     FILE	name of file

     KEYWORDS:
    	FILTER - extensiob
    	PLOT - if set, plot data

     OUTPUTS:
    	No explicit outputs.   A new window is created if necessary

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (14-may-98 aph) first developed for line scan mode
     (14-jun-98 aph) axis_com
     (07-aug-98 aph) indicate extension
     (18-jan-99 aph) CHANGE name to ln_load (to group with other LS functions)
                     include dwell on X-axis label
     (25-jun-99 aph) use ax_name to parse file name
     ( 7-jul-99 aph) FREE_LUN as well as close !
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (15-nov-00 cgz) Replaced call of NROWS function by explicit (SIZE(var))(2)
     (13-jun-01 aph) add E to the structure generated
     (31 oct-01 aph) work around for wrong 'npts' in new linescan format; (12-may-02 aph) AXIS standard header added

(See c:\axis2000\ln_load.pro)

## LN_LOCAT.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		LN_LOCAT.PRO

    LAST CHANGED: ----------------------------------- 	07-Jan-07

     PURPOSE:
    	This procedure reads co-rodinates of a linescan and places them on the image currently
     displayed. If the current buffer is not an image or does not contain the
     location of the line, the user is prompted to read an image.
     Default linescan format is SDF (ALS/CLS/SLS); optional for old STXM701; need to develop for NSLS

     CATEGORY:
    	Image display in aXis2000  Linescans~locate line

     CALLING SEQUENCE:
     for procedures:
    	LN_LOCAT [, STXM701=STXM701 ]

     INPUTS:
    	All input parameters are passed as keywords or acquired by prompts.

     KEYWORDS:
    	STXM701	original code for pre2000 files from ALS STXM7.0.1

     OUTPUTS:
    	No explicit outputs.

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     RESTRICTIONS:

     KNOWN ERRORS:
     If start from an empty buffer there are errors as AXIS tries to replot an empty buffer

     MODIFICATION HISTORY:
     (01-jan-99 aph) segregated from aaa-axis
     (10-feb-99 aph) fixed code error !
     (07-Jan-07 aph) AXIS standard header added; adapted to SDF files

(See c:\axis2000\ln_locat.pro)

## LN_NORM

[Previous Routine] [Next Routine] [List of Routines]

     pro ln_norm
     --------------------- last changed: 04-dec-00
     normalised each line of a linescan to subset or file Io

(See c:\axis2000\ln_norm.pro)

## LN_SUBSP

[Previous Routine] [Next Routine] [List of Routines]

    NAME: LN_SUBSP

    LAST CHANGED: ----------------------------------- 29-dec-00 (aph)

     PURPOSE:
    	This procedure subtracts a reference spectrum (chosen from an AXIS buffer)
     from the linescan displayed in the current buffer

     CATEGORY: data conversion - AXIS captive
     called from AXIS~LINESCANS~subtract reference

     CALLING SEQUENCE:
    	LNSUBSP

     INPUTS:none

     KEYWORDS: none

     OUTPUTS: none

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (01-jan-99 aph) segregated from aaa-axis
     (23-feb-00 aph) add groupID to buffer
     (29-dec-00 aph) fix error in name of groupID !!
    	        add standard header; remove line-by-line display

(See c:\axis2000\ln_subsp.pro)

## LOADSPEM

[Previous Routine] [Next Routine] [List of Routines]

     fct LOADSPEM, [fname, pk=pknum , norm=normnum, opts]
        - read SPEM image(s) from XPD labview data file format

        Options:
           /PLOT - display (splot2d) image (first image if multiple)
           /GLITCH - run manual glitch threshold window
           SDEV=n - run auto glitch filter for data outside n std deviations

     (15nov00 cgz) Replaced call of DIMEN function by explicit (SIZE(var))(index+1)
     (15nov00 cgz) Migrated to RD_SPEM.PRO since it was only called from with RD_SPEM.PRO
    			LOADSPEM.PRO is now obsolete and can be eliminated
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement

(See c:\axis2000\loadspem.pro)

## LOAD_NEX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     		LOAD_NEX

    LAST CHANGED: ----------------------------------- 	13-may-02

     PURPOSE:
    	This function loads nexafs spectra recorded by ALS SPEM

     CATEGORY:
    	read-in utility. Stand-alone

     CALLING SEQUENCE:
    	Result = load_nex (file, NOFILTER=nof, _extra=e)

     INPUTS:
     FILE - name of file (*.spc)

     KEYWORDS:
    	NOFILTER

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (12-may-99 aph) first written
     (8-jun-99 aph) add conditional group ID to get_num call; widget_info
     (29-dec-00 aph) filter set to '*.spc'
     (12-may-02 aph) AXIS standard header added

(See c:\axis2000\load_nex.pro)

## LOOK[1]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           LOOK

     PURPOSE:
           This procedure displays an image and relevant statistics on it.

     CATEGORY:
           Image display

     CALLING SEQUENCE:
           LOOK, Image [, Output, Rev_ind]

     INPUTS:
           Image:      The image to be displayed. If input is not 2-D, then
                       it is not displayed, but its histogram is plotted.

     KEYWORD PARAMETERS:
           HISTOGRAM:  If set, the histogram of image intensities is plotted.

                       If the image is an integer type (BYTE, INT, or LONG) then
                       this keyword may be set to the bin size.
                       Default is 1 for BYTE, 128 for INT, and 256 for LONG.

                       If the image is a floating point type (FLOAT or DOUBLE),
                       then this keyword may be set to the number of
                       desired bins in the histogram. Default is 256 bins.

           NOPLOT:     If set, histogram is computed if specified, but not
                       plotted.
                       Ignored if no output variable for histogram is specified.

           NODISPLAY:  If set, display statistics without displaying image.

           NOSTATS:    If set, display image without displaying statistics.

           NOSCALE:    If set, image is displayed with scaling from zero to the
                       maximum value. Also, the histogram is plotted from zero
                       to maximum value.
                       Default is to scale from minimum to maximum value of image.

           FIT_SCREEN: If set to 1, large images are shrunk to fit the screen
                       size, if necessary.

                       If set to 2, images are forced to fit the screen size by
                       shrinking or expanding by the required amount.
                       The aspect ratio is not changed - i.e., the same zoom
                       factor is used for both x and y dimensions.

                       If set to 3, images are forced to conform to the screen
                       shape by shrinking, expanding, or modifying the aspect
                       ratio.

                       The zoom factor used is saved in the ZOOM keyword
                       parameter.

                       Ignored if NODISPLAY is set.

           ZOOM:       The zoom factor to apply when displaying the image.
                       It may have one or two elements. If there is only one
                       element, the same zoom factor is applied to the x and y
                       dimensions. Otherwise, the two elements specify the
                       x and y zoom factors.

                       Alternatively, a variable to receive the zoom factor used
                       when fitting the image to the screen.

                       NOTE: In both cases, the ZOOM keyword parameter is
                       overwritten by the actual zoom factor(s) used, which can
                       be different from the supplied parameter due to roundoff.
                       This can result in conversion of a one element zoom
                       factor into a two element zoom factor.

                       NOTE: Zoom factor < 1 shrinks image.
                             Zoom factor > 1 expands image.

           SCROLL:     If set, and if the displayed image size is larger than
                       75% of the screen size, a scrollable window is used to
                       display the image.
                       Alternatively, this keyword can be set explicitly to the
                       image size as a fraction of the screen size (floating
                       point value between 0.0-1.0) above which scrollbars
                       will be used.

                       NOTE: This keyword is ignored if a desired window index
                             is specified using the WINDOW keyword below.
                             It is also ignored if the FIT keyword is set.

           WINDOW:     The window number in which to display the image.
                       The default is window 0.
                       If an undefined named variable is supplied to this keyword,
                       it will receive the window index of  the window created
                       by the LOOK procedure.

           HWINDOW:    The window number in which to plot the histogram.
                       The default is window 1. If Hwindow is the same as Window,
                       the histogram is displayed in the next higher window
                       number.

     OPTIONAL OUTPUTS:
           Output:     A variable to receive a FLOAT version of the image scaled
                       into the range of 0 to 255. Any applied zoom factor will
                       be reflected in the output.

                       Alternatively, a variable to receive the histogram, if
                       the HISTOGRAM keyword is set.
                       output[*,0] contains the intensities at the bin midpoints.
                       output[*,1] contains the frequency at each intensity.

           Rev_ind:    If the HISTOGRAM keyword is set, a variable to receive
                       the reverse indices array from the histogram operation.
                       See the documentation for HISTOGRAM for details.

     ROUTINES USED BY THIS MODULE:
           CONGRID, STDEV     (IDL User Library)

           XWINDOW SUITE      (Bill Loo's IDL Routines)

     COMMON BLOCKS:
           LOOK_COMMON

     ORIGINALLY WRITTEN BY:
           Werner Meyer-Ilse
           Center for X-Ray Optics
           Lawrence Berkeley National Lab

     REWRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           September, 1996

(See c:\axis2000\look.pro)

## LOOK[2]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           LOOK

     PURPOSE:
           This procedure displays an image and relevant statistics on it.

     CATEGORY:
           Image display

     CALLING SEQUENCE:
           LOOK, Image [, Output, Rev_ind]

     INPUTS:
           Image:      The image to be displayed. If input is not 2-D, then
                       it is not displayed, but its histogram is plotted.

     KEYWORD PARAMETERS:
           HISTOGRAM:  If set, the histogram of image intensities is plotted.

                       If the image is an integer type (BYTE, INT, or LONG) then
                       this keyword may be set to the bin size.
                       Default is 1 for BYTE, 128 for INT, and 256 for LONG.

                       If the image is a floating point type (FLOAT or DOUBLE),
                       then this keyword may be set to the number of
                       desired bins in the histogram. Default is 256 bins.

           NOPLOT:     If set, histogram is computed if specified, but not
                       plotted.
                       Ignored if no output variable for histogram is specified.

           NODISPLAY:  If set, display statistics without displaying image.

           NOSTATS:    If set, display image without displaying statistics.

           NOSCALE:    If set, image is displayed with scaling from zero to the
                       maximum value. Also, the histogram is plotted from zero
                       to maximum value.
                       Default is to scale from minimum to maximum value of image.

           FIT_SCREEN: If set to 1, large images are shrunk to fit the screen
                       size, if necessary.

                       If set to 2, images are forced to fit the screen size by
                       shrinking or expanding by the required amount.
                       The aspect ratio is not changed - i.e., the same zoom
                       factor is used for both x and y dimensions.

                       If set to 3, images are forced to conform to the screen
                       shape by shrinking, expanding, or modifying the aspect
                       ratio.

                       The zoom factor used is saved in the ZOOM keyword
                       parameter.

                       Ignored if NODISPLAY is set.

           ZOOM:       The zoom factor to apply when displaying the image.
                       It may have one or two elements. If there is only one
                       element, the same zoom factor is applied to the x and y
                       dimensions. Otherwise, the two elements specify the
                       x and y zoom factors.

                       Alternatively, a variable to receive the zoom factor used
                       when fitting the image to the screen.

                       NOTE: In both cases, the ZOOM keyword parameter is
                       overwritten by the actual zoom factor(s) used, which can
                       be different from the supplied parameter due to roundoff.
                       This can result in conversion of a one element zoom
                       factor into a two element zoom factor.

                       NOTE: Zoom factor < 1 shrinks image.
                             Zoom factor > 1 expands image.

           SCROLL:     If set, and if the displayed image size is larger than
                       75% of the screen size, a scrollable window is used to
                       display the image.
                       Alternatively, this keyword can be set explicitly to the
                       image size as a fraction of the screen size (floating
                       point value between 0.0-1.0) above which scrollbars
                       will be used.

                       NOTE: This keyword is ignored if a desired window index
                             is specified using the WINDOW keyword below.
                             It is also ignored if the FIT keyword is set.

           WINDOW:     The window number in which to display the image.
                       The default is window 0.
                       If an undefined named variable is supplied to this keyword,
                       it will receive the window index of  the window created
                       by the LOOK procedure.

           HWINDOW:    The window number in which to plot the histogram.
                       The default is window 1. If Hwindow is the same as Window,
                       the histogram is displayed in the next higher window
                       number.

     OPTIONAL OUTPUTS:
           Output:     A variable to receive a FLOAT version of the image scaled
                       into the range of 0 to 255. Any applied zoom factor will
                       be reflected in the output.

                       Alternatively, a variable to receive the histogram, if
                       the HISTOGRAM keyword is set.
                       output[*,0] contains the intensities at the bin midpoints.
                       output[*,1] contains the frequency at each intensity.

           Rev_ind:    If the HISTOGRAM keyword is set, a variable to receive
                       the reverse indices array from the histogram operation.
                       See the documentation for HISTOGRAM for details.

     ROUTINES USED BY THIS MODULE:
           CONGRID, STDEV     (IDL User Library)

           XWINDOW SUITE      (Bill Loo's IDL Routines)

     COMMON BLOCKS:
           LOOK_COMMON

     ORIGINALLY WRITTEN BY:
           Werner Meyer-Ilse
           Center for X-Ray Optics
           Lawrence Berkeley National Lab

     REWRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           September, 1996

(See c:\axis2000\look_a.pro)

## LOX_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		LOX_COM.PRO

    LAST CHANGED: ----------------------------------- 	18-mar-06

     PURPOSE:
    	This file is the common block for the AX_LOX read-in widget

     CATEGORY: utility

     CALLING SEQUENCE:  not applicable

     INPUTS: none

     KEYWORDS: n

     MODIFICATION HISTORY:
     (16-oct-05 aph) adapted from SDF_COM.PRO

(See c:\axis2000\lox_com.pro)

## MAKE_SQUARE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	MAKE_SQUARE

    LAST CHANGED: ----------------------------------- 12-may-02

     PURPOSE:
    	This procedure replaces rectangular images with a square image
     extended with gray space

     CATEGORY:
    	Image display.

     CALLING SEQUENCE:
     for procedures:
    	MAKE_SQUARE, S

     INPUTS:
     	S		AXIS structure data (only operates on t='2d', images

     KEYWORDS: none

     OUTPUTS: square matrix is returned as the entry structure

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (xxDec-99 aph) ~time introduced
     (30-dec-00 aph) Xrng and Yrng set up
    				AXIS standard header added
     (05-mar-01 aph) trying to debug bad read in of some ALS 7.0 linescans (error not found)
    912-may-02 aph) fix up header name format.

(See c:\axis2000\make_square.pro)

## MATH.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	MATH.PRO

    LAST CHANGED: ----------------------------------- 15-nov-00

    PURPOSE:
    	This is a set of array functions
    	DIMEN		- determines dimension of array
    	NCOLS		- determines number of columns in array
    	NROWS		- determines number of rows in array

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = DIMEN(ARRAY)
    	Result = NCOLS(ARRAY)
    	Result = NROWS(ARRAY)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function DIMEN, ARRAY
    	returns the size of the nth (starting from 0) dimension of ARRAY

    	function NCOLS, ARRAY
     	returns the number of columns of ARRAY

    	function NROWS, ARRAY
    	returns the number of rows of ARRAY

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (08-nov-00 cgz) AXIS standard documentation
     (08-nov-00 cgz) created MATH procedure,
    			to be used to compile other functions when called from AXIS startup
     (08-nov-00 cgz) migrated INTERP and INTERSPLINE to separate files as functions
     (08-nov-00 cgz) eliminated MEAN function, superceded by IDL primitive MEAN
    		can probably eliminate some of these small functions
    		why have dimen, ncols, nrows when these can be handled by IDL primitive
     (15-nov-00 cgz) replaced calls of DIMEN, NCOLS, and NROWS in all other AXIS functiosn and procedures
    		DIMEN : LOADSPEM, PARSEBYTES, RD_SPEM
    		NCOLS : GEN_READ, INTERP, LN_LOAD, MISC, PLOT2D, READ_A_N, READ_ALS,
    				READ_NUMBERS, SPLOT2D, SPLOT3D, SPLOTA
    		NROWS : LN_LOAD, PLOT2D, READ_A_N, READ_ALS
    		MATH.PRO is now obsolete and can be eliminated

(See c:\axis2000\math.pro)

## MBUF

[Previous Routine] [Next Routine] [List of Routines]

    NAME: FILENAME_IN_CAPITALS

    LAST CHANGED: ----------------------------------- 31-dec-01

     PURPOSE:
    	This function is a widget that allows selection of multiple buffers

     CATEGORY:
    	utility captive to axis2000

     CALLING SEQUENCE:
    	Result = MBUF(group = group, Val = val)

     INPUTS:
    	All input parameters are passed as keywords.

     KEYWORDS:
    	GROUP	identity of parent group that called mbuf (axis_id)
    	val 	array of buffers for default selection

     OUTPUTS:
      returns array with numbers of selected buffers

     COMMON BLOCKS:
    	COMMON Buffer, BGROUP16, MBufs, cncl

     SIDE EFFECTS:
    	A widget is created/destroyed.

     MODIFICATION HISTORY:
     (13-dec-98 aph) correct layout; all, cancel added
     (20-aug-01 aph) removed modal call at xmanager
     (31-dec-01 aph) when select 'all' it includes buffer 0

(See c:\axis2000\mbuf.pro)

## MISC

[Previous Routine] [Next Routine] [List of Routines]

      fct asc( char )		-- convert char to ascii code
      fct chr( ascii)		-- convert ascii code to character
      fct num2str(num,format)	-- simpler syntax than built-in STRING fct
      fct int2str, num, DIGITS=digits
         -- integer(s) to string with optional padded zeros
            if num is an array output adds brackets and commas ([#,...])
      fct str2arr, str, delimit [, LEN=len, /INT]
    	-- extract an array of values from a string
      fct ZM, image, mag		-- zoom image size, magnification can be noninteger
      fct RANGEN, npts, min, max [,option] -- returns preinitialized 1D floating array
    	option: INCR=increment (recalculates npts; max is then to nearest increment)
      fct GET_LIMITS, arr		-- returns [start, end] vector of 1D array
      fct GET_RANGE, arr		-- returns [min, max] vector any dimen array
      fct INDEX, arr, val,  --returns index of 1D array closest to the given value(s)
    	 	/MODE selects alternate method, /TIM - prints execution time

(See c:\axis2000\misc.pro)

## NCB_TO_MPG

[Previous Routine] [Next Routine] [List of Routines]

    NAME: NCB_TO_MPG

     PURPOSE:
    	This function converts a ncb stack into a MPEG movie

     CATEGORY:
    	stack processing

     CALLING SEQUENCE:
    	NCB_TO_MPG, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS:
    	*.mpg file

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     ANAL_COM
     BSIF_COM
     volume_data, image_stack

     SIDE EFFECTS:

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (14-Jun-06 gaj) first version
     (01-Aug-06 gaj) finished first working version
     (02-Aug-06 gaj) fixed the scaling to avoid colors in the movies

(See c:\axis2000\ncb_to_mpg.pro)

## NCDF2ALS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	NCDF2ALS

    LAST CHANGED: ----------------------------------- 20-May-00

     PURPOSE:
    	This procedure converts one or a series of NSLS image files (*.nc)
     into ALS ascii format (*.img) with a user definable scale factor

     CATEGORY:
    	AXIS: image analysis

     CALLING SEQUENCE:
    	NCDF2ALS, file

     INPUTS:
    	FILE - netCDF format (*.nc) to be converted to ALS ascii format

     KEYWORD PARAMETERS:
    	LIST 	- name of file with list of image files (*.sl)
       OUTLIST - name of a file to write list of netCDF files (*.lst)
    	ONE 	- convert only a single file
    	SCALE 	- scale factor (nb ALS format is integer)

     OUTPUTS:
      FILE.img - image written to a ALS ascii format binary file (*.img, *.dat)

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS
       @BSIF_COM - common block for netCDF

     RESTRICTIONS:
    	caveat emptor

     PROCEDURE:
    	NCDF2ALS uses READ_BNL to put the image and associated information
     into BSIF_COMMON variables:
    	image_data (the array which holds the image - possibly several
    	planes deep for I, IO, CLOCK)
    	then uses SAV_ALS to write the ALS data files

     MODIFICATION HISTORY:
     (20-may-00 aph) adapted from als3ncdf

(See c:\axis2000\ncdf2als.pro)

## PARSE_SDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		PARSE_SDF

    LAST CHANGED: ----------------------------------- 09-Dec-05 (aph)

     PURPOSE:
    	This function generates a structure from a string
     If the string contains multiple structures it only returns the first structure.
     It also trims the input string to all past the extracted structure.
     Where necessary, in partuclar inarrays which contain structures, named structures are used.

     CATEGORY:
    	utility: string manipulation

     CONTENTS:
    	MAKE_STAR	function to make named array from anonymous array
    	PARSE_SDF	main routine

     CALLING SEQUENCE:
    	Result = PARSE_SDF(dummy, struct=struct, verbose = verbose)

     INPUTS:
    	DUMMY	a string containing structure contents
    	EXAMPLES: '{ Name = "Time"; Unit = "sec";};'
    			 '{ Name = "Energy"; Min = 285; Max = 322; Points = (3, 285, 286, 287);};'
    			 '{ Name = "Time"; Unit = "sec";}; embed_str = {name = "new";int = 5;};};'

     KEYWORDS:
    	STRUCT	pre-defined named structure to act as template
    	VERBOSE	print a blow-by-blow descrition (you were warned !!)

     OUTPUTS: anonymous structure which may contain named structures
          (Tag_Name1 : Tag_Definition1,..., Tag_Namen : Tag_Definitionn}

     COMMON BLOCKS: sdformat

     PROCEDURE: The structure is first tested to ensure it starts with {
     It is then read by removing each tagname and using analysis of the following
     string parts to identify one of 7 possible structure components

    				Identify by testing		Isolate	by 		Convert
     Component  	first char	(____;)		extracting		by using
      ---------   ----------------------  -------------   ---------
     STRUCTURE		{						whole string	parse_sdf			**
     Array			(						next ')'		type specific
     ----- after removing (##, ..... identify and convert all ___,
       of STRUCT	{						whole string	parse_sdf			**
       of String	"						sep_parts		none				**
       of Real/Integer			'.'			sep_parts		float				**

     String		"			'"'			to next ';'		none				**
     Real						'.'			to next ';'		float				**
     Integer					(all other)	to next ';'		fix					**
     ------------------------------------------------------------

     BUGS
     	Does not work to handle arrays of structures
     need to find how to make named structure from strings

     MODIFICATION HISTORY:
     (10-feb-01 aph) first version
     (11-feb-01 aph) change from bl5 to sdf (self-defined format); make_star
     (22-feb-01 aph) residual syntax pasring added - Booleans & arrays of structures of structures
     (17-aug-01 aph) tinkered but no mods getting Aug-01 dataformats read
     (12-may-02 aph) correct header name format
     (12-mar-03 aph) change '0','1','2' to 'a0'.. in named array structs
          "          and pt in kluge to replace 'END' tags, for IDL5.6 compatibility
     (09-dec-05 aph) tracking added for troubleshooting new SDF file structures

(See c:\axis2000\parse_sdf.pro)

## PEM_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		PEM_LOAD

    LAST CHANGED: ----------------------------------- 28-May-05 (aph)

     PURPOSE:
    	This function reads an ALS-PEEM 2 NEXAFS format file
     It assumes col(1) = Energy (eV)  and col(3) = signal

     CATEGORY: spectral input
     called from AXIS~READ~ALS-PEEM

     CALLING SEQUENCE:
    	Result = PEM_LOAD(file=file, filter=filter, NOF=nof, print_source = print_source, $
                 ring_normalize=ring_normalize,  _extra=e)

     INPUTS:
    	All input parameters are passed as keywords.

     KEYWORDS:
    	FILE:	filename
    	FILTER:	optional user selectable filter (default = '*.'
    	NOF:	no filter (*.*)
    	PRINT_SOURCE:	if set to 1; print input file as it is read
       RING_NORMALIZE  divide by the ring current if it exists
    	_EXTRA_E:	forward other parameters

     OUTPUTS: none

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     COMMENTS:
    	In Dec-04 found prob lems with 'apparent non-linearity' in ALS PEEM energy scales
       In May-05 realized there had been a file format change sometime in fall 2003
       which removed the header line from the *.dat files written by PEEM-2
       This meant the energy assigned to the image file was one higher (i.e. the n+1 energy
       was assigned to the n image). This, combined with use of non-linearly spaced energies,
       is the likely cause of the  'apparent non-linearity'.

     MODIFICATION HISTORY:
     ( 9-aug-97 aph) broke out of spectral; TYPE defined
     (21-jan-98 aph) added s.dn component to 1d structure to be axis-compatible
     (20-feb-98 aph) set-up to read 2-col only data
     ( 6-mar-98 aph) read *.txt - 2 column ascii files
     ( 7-jun-98 aph) corrected read *.txt ('un' case) to get all data points
     (10-jul-98 aph) retired "*.spc" nomenclature - use *.txt extension
     (13-May-99 aph) set up for multicolumn, skip header reading
     (15-May-99 aph) adapt spc_load to get ALS-PEEM 2 format files
     (25-jun-99 aph) use only fileshort
     ( 7-jul-99 aph) FREE_LUN as well as close
     (29-dec-00 aph) set filter to '*.' ; standard header; add file
     (14-jan-01 aph) set filter to '*.*' since '*.' EXCLUDES files of *. character !!
     (12-aug-01 aph) add title to pickfile dialog
     (12-may-02 aph) correct header name format
     (28-may-05 aph) adapt to 3 different ALS PEEM spectral file formats
                     add ring current normalization option

(See c:\axis2000\pem_load.pro)

## PICKFILE2

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		PICKFILE2

    LAST CHANGED: ----------------------------------- 	22 Nov 2008

     PURPOSE:
    	This function is a dialog which allows user to select a filename.
       It is a wrapper over the old IDL PICKFILE dialog
        with last path, last file options and forcing extension

     CATEGORY:
    	utility. stand alone

     CALLING SEQUENCE:
    	Result = PICKFILE2 (LPATH=lp, TITLE=TITLE, $
                           WRITE=write, LFILE=lf, INFO=info, _extra=e)

     INPUTS: none

     KEYWORDS:
    	FILTER - extension (*.hdr)
    	INFO - print info on this routine
    	LPATH - last path used
    	LFILE - last file used
    	TITLE - user supplied title for dialog
    	WRITE - if set, when selecting a filename, checks & warns for existence

     OUTPUTS: none

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	common lastpath, lpath, lfile

     MODIFICATION HISTORY:
     (06-jul-98 aph) force DefPath to be LastPath from exit
     (04-jan-00 aph) add WRITE, AXIS keywords and build a wrap that warns user of overwriting
     (25-apr-00 aph) attempt to get lpath working properly; allow use outside of axis
     (19-apr-01 aph) add TITLE
     (14-may-02 aph) AXIS standard header added; force filter extension
     (22-nov-08 aph) use axis_log for warnings

(See c:\axis2000\pickfile2.pro)

## PLOT2D

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	PLOT2D

    LAST CHANGED: ----------------------------------- 22-mar-06

    PURPOSE:
    	This generates a 2d image plot with labels and user controllable limits.
     It is intermediate between splot2d and the IDL plot routine.

    CATEGORY:
    	AXIS: utility; also STAND ALONE: image processing

     CALLING SEQUENCE
      	PLOT2D, G_data, xx, yy, xylabels, /LOG, autosize=as, wsize=s, /NORESIZE, _extra=e

    CALLED FROM AXIS:
    	->via splot2d routine exclusively

    INPUTS:
    	G_data	(z) data to plot
    	xx		(X) - values
    	yy		(Y) - values
    	xylabels  labels

    KEYWORDS:
    	LOG		- plot log(G-data)
    	WSIZE	- specify IDL window size
    	AUTOSIZE - uses dimensions to specify IDL window size
    	NORESIZE - ue current window size

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

     PROCEDURE
     generalized 2D intensity plot with x and y axes
     assumes equal pixel unit increments to determine window aspect ratio

    MODIFICATION HISTORY:
     2/13/95  er add keyword /NORESIZE to PLOT2D
     6/15/96  jdd move SPLOT stuff to separate procedure

     ----------- AXIS modifications -------
     (25-jun-99 aph) plot2d: allow co-existing image/spectra color tables (ax_imscl, ax_color)
     ( 6-jul-99 aph) plot2d: allow negative-going plots; try to avoid funny colored backgrounds
     ( 3-oct-99 aph) plot2d: removed explicit color, back statements !
     (15-apr-00 aph) AXIS standard documentation
     (14-nov-00 cgz) Replaced calls to GET_RANGE function with ecplicit MIN and MAX calls
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (15-nov-00 cgz) Replaced call of NROWS function by explicit (SIZE(var))(2)
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index
     (30-dec-00 aph) set XSTYLE=9, YSTYLE=9 for frame (1-sided axes)
    				  set Xmargin=[8,0], Ymargin = [4,2]
     (22-mar-06 aph) try to increase size of labels; allow room for Y-axis label

(See c:\axis2000\plot2d.pro)

## PLOT3D.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	PLOT3D.PRO

    LAST CHANGED: ----------------------------------- 15-apr-00

    PURPOSE:
    	This generates a shade_surface 3d plot of an image.

    CATEGORY:
    	STAND ALONE image processing

    ROUTINES:
    	PLOT3D, G_data, xx, yy, xylabels, AZ=zang, _extra=e
    			xylabels=['xlabel','ylabel']

    CALLED FROM AXIS:
    	->via splot3d routine exclusively

    INPUTS:
    	G_data	(z) data to plot
    	xx		(X) - values
    	yy		(Y) - values
    	xylabels  labels

    KEYWORDS:
    	AZ			- Z-angle plot log(G-data)
    	CHARSIZE	- specify character size for labels

    OUTPUTS: generates a window if run stand-alone

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     12/2/95  jdd fixed labels in plot3d
     6/15/96  jdd move SPLOT stuff to separate procedure
     ----------- AXIS modifications -------
     (15-apr-00 aph) AXIS standard documentation

(See c:\axis2000\plot3d.pro)

## PLOTBUF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		PLOTBUF

    LAST CHANGED: -----------------------------------  15-Jun-08

     PURPOSE:
    	This procedure plots AXIS structure format data (1d, 2d, 3d, 4d)
     where 1d are y(x) - typically spectral or profile plots
    		2d are z(x,y) - images
    		3d are images without own (x,y) scales,
    			typically standard format images (jpg etc) with own color scales
    		4d are f(x,y,z) 3-d volume data (e.g. stacks) (not yet implemented)

     CATEGORY:
    	Image display. AXIS captive

     CALLING SEQUENCE:
     	PLOTBUF, BufNum, Zvalues = Zvalues, same_scale=same_scale, _extra=e

     INPUTS:
    	BUFNUM	Number of AXIS buffer to plot
               (0-9 are standard; 10 thumbnail composite)

     KEYWORDS:
    	ZVALUES:	[zmin, zmax] to allow forcing Z-range
    	SAME_SCALE:	switch if set, keeps same (x,y) scale as in prior plot
    	_EXTRA:		other paramaters to pass to splot, splot2d etc
     	Note - many other plot paramaters are passed via axis_com variables

     OUTPUTS:
    	plot on MainImg window in aXis2000

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (07-aug-97 aph) - generates MainImg plot using SPLOT or SPLOT2D
    				    updates buffer labels; updates thumbnails
     (28-dec-97 aph) - added '3d' type = tif, gif, etc image
     (12-apr-98 aph) - added '4d' type = (E,distance) plot (line scans)
     (19-jun-98 aph) - split out of AXIS_C for code space reasons
     (28-Dec-98 aph) - Zmin, Zmax for 2d plots
     (03-Jan-99 aph) - Zmin, Zmax for 1d plots
     (08-Jan-99 aph) - add 5% top/bottom margin for 1d plots
     (25-Jun-99 aph) - try for consistent image/spectra color table
     (29-jun-99 aph) - adapt 'FIRST_PLOT' to set user-selected colors;
                     - type = '3d' uses internal color tables
     (04-jul-99 aph) - search for color scale error on image -> spectra
     (06-jul-99 aph) - correct image plotting to preserve orientation of (x,y) scales (forced increasing)
     (08-jul-99 aph) - only redo thumbs if CurBuf NE 0; update labels though !
     (13-jul-99 aph) - thumb_plot reset for any use of PlotBuf; add same_scale keyword
     (26-jul-99 aph) - leave all decisions about updating Thumbs and Labels to ThumbLbs
     (12-aug-99 aph) - kluge fix 'relax to white background' problem
     (19-sep-99 aph) - change first to first_plot (common conflict); ax_wait
     (28-oct-99 aph) - update Zmin, Zmax on plot
     (16-nov-99 aph) - implement color bar, gamma for image Z-scales; X,Y controls
     (19-nov-99 aph) - do not clear axis communication box
     (31-jan-00 aph) - reactivate 3d as a simple 'transcribe' for images
     (16-apr-00 aph) - add TRUE=1 to corrctly display 3-channel images (3,x,y)
     (30-nov-00 cgz) Replaced call of wdivide with explicit !p.multi statement
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index
    			commented out !p.background statement
     (30-dec-00 aph) corrected placement of make_square to get line-outs right
    				Zrange larger/smaller than data size implemented
    				AXIS standard header added
     (06-oct-01 aph) sensitive for G_lbl
     (28-dec-01 aph) blank out pixel display when clearing from 2d display
     (17-feb-02 aph) add scale bar and size
     (29-apr-02 aph) nm bar if less than 1 um; not thick
     (12-may-02 aph) correct header name format
     (22-mar-06 aph) increase character size
     (22-dec-07 aph) remove date, time
     (15-jun-08 aph) ignore NaN and Infinities when setting plot ranges

(See c:\axis2000\plotbuf.pro)

## PLOTSECT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		PLOTSECT

    LAST CHANGED: ----------------------------------- 	14-Jun-05

     PURPOSE:
    	This procedure plots multisection (non-monotonic) spectra data using splot

     CATEGORY:
    	Spectral display - captive to aXis2000

     CALLING SEQUENCE:
    	PlotSect, BufNum, AUTOSCALE=auto, SPLIT=split, _extra=e

     INPUTS:
     	BufNum	Number (0-9) of aXis data buffer to display.

     KEYWORDS:
    	AUTOSCALE	- if 1, then display with min/max range
    	SPLIT		- if 1, separate the parts of the non-montonic data
                     into individual, +ve X-going sections in separate buffers
    				- if 0, overlpot in one display buffer, but increment colors
    			       to indicate non-monotonic

     OUTPUTS: none

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (20-dec-97 aph) generates multisection MainImg plot using SPLOT
     (19-jun-98 aph) isolated from AXIS_C
     (26-sep-99 aph) updated with thumbnails separated
     (15-aug-04 aph) fix problem with processing files which do not have an Xlabel
                     standard header
     (14-Jun-05 aph) add correction (kluge!) to allow oplot with 1 point sections

(See c:\axis2000\plotsect.pro)

## PRINT

[Previous Routine] [Next Routine] [List of Routines]

      pro PRA, /LS, /EPS, _extra=e
    	OPEN POSTSCRIPT FILE FOR OUTPUT
    	OPTIONS: /LS (landscape), /EPS (encapsulated postcript)
      pro PRB, 'printer', /NOPRINT
    	CLOSE & PRINT to 'BL7LJ4' (default), 'hp9', etc.
     (29nov00 cgz) Only PRa and PRb are used anywhere within AXIS
    			PRa and PRb are called once from within WINDOW.PRO
    			Migrated PRa and PRb to WINDOWS.PRO
    		PRINT.PRO is now obsolete

(See c:\axis2000\print.pro)

## PRINT-EK

[Previous Routine] [Next Routine] [List of Routines]

      pro PRA, /LS, /EPS, _extra=e
    	OPEN POSTSCRIPT FILE FOR OUTPUT
    	OPTIONS: /LS (landscape), /EPS (encapsulated postcript)
      pro PRB, 'printer', /NOPRINT
    	CLOSE & PRINT to 'BL7LJ4' (default), 'hp9', etc.

(See c:\axis2000\print-ek.pro)

## RANDOMFILE

[Previous Routine] [Next Routine] [List of Routines]

     This routine returns a random file name which is unique
     CJJ, Jan. 93

(See c:\axis2000\randomfile.pro)

## RD_PEEM[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	RD_PEEM

     last changed ----------------------------- 05-apr-07 (aph)

     PURPOSE
       This function reads in a PEEM-2 image file in either the as-recorded 12-bit
      or the converted 16-bit unsigned tif formats.
      Dependending on keywords, it then corrects for gain, background effects;
      applies median smoothing, and assigns the x,y scales and the photon energy
      The data is returned as an AXIS internal format 2d structure

     CATEGORY:
    	Image processing.

     CALLING SEQUENCE:
    	Result = RD_PEEM(file [, bits12 = bits12, col12 = col12, Energy = energy, AXIS = AXIS, $
             CCD_bgnd = CCD_bgnd, scale = scale, smth = smth, CCD_gain = CCD_gain, $
             aoi_box = aoi_box, aoi_data = aoi_data, aoi_gain=aoi_gain, aoi_dark=aoi_dark, $
    		  region = region, sphinx=sphinx, NOFILTER=nof, _extra=e])

     INPUTS:
    	FILE 	name of file to convert (user prompted if not supplied)

     KEYWORDS:
    	AOI_box 	area of interest, defined by box, [x0, y0, x1, y1] acquired by PEEM-2
    					used to extract sub-image from dark and white files
    	AOI_DATA	if set, select AOI from input image
    	AOI_GAIN	if set, select AOI from CCD-gain image
    	AOI_DARK	if set, select AOI from dark image
    	AXIS		if set, indicates called from AXIS2000 widget
    	BITS12 		if set, this turns on the 12-bit read routine
       COL12		if set, defines number of columns to drop in 12-bit mode
    	DWELL		exposure time for image in seconds
    	ENERGY 		sets energy PEEM image was recorded at
    	CCD_BGND 	CCD background image (2-d array) that is subtracted; must be same size as image
    	GROUP		name of group leader calling RD_PEEM
    	NOFILTER	if set, then pickfile dialog does not have filter set to '*.tif'
    	REGION		a 4-number vector [x_start, x_stop, y_start, y_stop]
    				defining the region of the image to be selected
    				(if scale set, in real space units. Otherwise, in pixels)
    	SCALE 		pixel size in microns
    	SMTH 		if set, applies a 3-point median smooth
       SPHINX      if set, switched 16-bit TIF read to signed
    	CCD_GAIN	CCD background image (2-d array) that is divided; must be same size as image
               	(gives response of CCD to uniform illumination)

     COMMON
    	AXIS_COM general common blocks for AXIS

     WARNINGS
    	1024x1024 images from CCD camera can be slow loading with older computers

     MODIFICATION HISTORY:
     (14-may-99 aph) first version
     (15-may-99 aph) save scale (pix_siz), region (cur, cll) values in common
     (08-jun-99 aph) add group to get_num call
     (25-jun-99 aph) report short gile name only
     (17-jul-99 aph) CCD_bgnd used
     (01-nov-99 ads) add nobits keyword & option for reading 12bit PEEM2 images
     (26-dec-99 aph) incorporated in AXIS 1.8c
     (23-oct-00 aph) 12-bit read in from arbitrary size - use Query_Tiff to obtain dimensions
                      dump first 5 columns
     (20-apr-01 aph) getting 1024x1024 12-bit files to read
     (06-jun-01 aph) AXIS standard header; apply full background and gain image correction
    				  implement Area of Interest for gain, image and background
     (12-jul-01 aph) continuing development of improved PEEM read-in
     (31-jul-01 aph) handle bad file names properly; add axis keyword
     (04-aug-01 aph) add group keyword; remove intermediate plotting if group set
     (07-aug-01 aph) add dwell keyword and value to x-axs label if set
     (12-aug-01 aph) added keyword parameter to set 12-bit column drop; change GAIN correction to array
     (05-may-02 aph) add sphinx keyword to correct for signed format
     (12-may-02 aph) corrct name format in header.
     (16-jul-02 aph) read in 12-bit elmitec data stored in 16-bit TIF files correctly
     (23-may-04 aph) get keyword energy to be recognized and stop requesting a value
     (05-apr-07 aph) troubleshooting problem reading ALS PEEM2 files

(See c:\axis2000\rd_peem-test.pro)

## RD_PEEM[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	RD_PEEM

     last changed ----------------------------- 12-Sep-07 (aph)

     PURPOSE
       This function reads in a PEEM-2 image file in either the as-recorded 12-bit
      or the converted 16-bit unsigned tif formats.
      Dependending on keywords, it then corrects for gain, background effects;
      applies median smoothing, and assigns the x,y scales and the photon energy
      The data is returned as an AXIS internal format 2d structure

     CATEGORY:
    	Image processing.

     CALLING SEQUENCE:
    	Result = RD_PEEM(file [, bits12 = bits12, col12 = col12, Energy = energy, AXIS = AXIS, $
             CCD_bgnd = CCD_bgnd, scale = scale, smth = smth, CCD_gain = CCD_gain, $
             aoi_box = aoi_box, aoi_data = aoi_data, aoi_gain=aoi_gain, aoi_dark=aoi_dark, $
    		  region = region, sphinx=sphinx, NOFILTER=nof, _extra=e])

     INPUTS:
    	FILE 	name of file to convert (user prompted if not supplied)

     KEYWORDS:
    	AOI_box 	area of interest, defined by box, [x0, y0, x1, y1] acquired by PEEM-2
    					used to extract sub-image from dark and white files
    	AOI_DATA	if set, select AOI from input image
    	AOI_GAIN	if set, select AOI from CCD-gain image
    	AOI_DARK	if set, select AOI from dark image
    	AXIS		if set, indicates called from AXIS2000 widget
    	BITS12 		if set, this turns on the 12-bit read routine
       COL12		if set, defines number of columns to drop in 12-bit mode
    	DWELL		exposure time for image in seconds
    	ENERGY 		sets energy PEEM image was recorded at
    	CCD_BGND 	CCD background image (2-d array) that is subtracted; must be same size as image
    	GROUP		name of group leader calling RD_PEEM
    	NOFILTER	if set, then pickfile dialog does not have filter set to '*.tif'
    	REGION		a 4-number vector [x_start, x_stop, y_start, y_stop]
    				defining the region of the image to be selected
    				(if scale set, in real space units. Otherwise, in pixels)
    	SCALE 		pixel size in microns
    	SMTH 		if set, applies a 3-point median smooth
       SPHINX      if set, switched 16-bit TIF read to signed
    	CCD_GAIN	CCD background image (2-d array) that is divided; must be same size as image
               	(gives response of CCD to uniform illumination)

     COMMON
    	AXIS_COM general common blocks for AXIS

     WARNINGS
    	1024x1024 images from CCD camera can be slow loading with older computers

     MODIFICATION HISTORY:
     (14-may-99 aph) first version
     (15-may-99 aph) save scale (pix_siz), region (cur, cll) values in common
     (08-jun-99 aph) add group to get_num call
     (25-jun-99 aph) report short gile name only
     (17-jul-99 aph) CCD_bgnd used
     (01-nov-99 ads) add nobits keyword & option for reading 12bit PEEM2 images
     (26-dec-99 aph) incorporated in AXIS 1.8c
     (23-oct-00 aph) 12-bit read in from arbitrary size - use Query_Tiff to obtain dimensions
                      dump first 5 columns
     (20-apr-01 aph) getting 1024x1024 12-bit files to read
     (06-jun-01 aph) AXIS standard header; apply full background and gain image correction
    				  implement Area of Interest for gain, image and background
     (12-jul-01 aph) continuing development of improved PEEM read-in
     (31-jul-01 aph) handle bad file names properly; add axis keyword
     (04-aug-01 aph) add group keyword; remove intermediate plotting if group set
     (07-aug-01 aph) add dwell keyword and value to x-axs label if set
     (12-aug-01 aph) added keyword parameter to set 12-bit column drop; change GAIN correction to array
     (05-may-02 aph) add sphinx keyword to correct for signed format
     (12-may-02 aph) corrct name format in header.
     (16-jul-02 aph) read in 12-bit elmitec data stored in 16-bit TIF files correctly
     (23-may-04 aph) get keyword energy to be recognized and stop requesting a value
     (12-sep-07 aph) remove action of col12 function (drop first few columns); replace higher up with ax_cimage
                     use axis_log instead of print

(See c:\axis2000\rd_peem.pro)

## RD_SPEM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	RD_SPEM.PRO

    LAST CHANGED: ----------------------------------- 30-nov-00

    PURPOSE:
    	This reads SPEM data from a XPD labview format data file

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = RD_SPEM(FILE)

    INPUTS:
    	FILE - SPEM data file

    KEYWORD PARAMETERS:
    	NOFILTER -
    	_EXTRA -

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function LOADSPEM, fname, PK=pknum, NORM=normnum, AVG=avgnum, $
                      PLOT=pl, GLITCH=ngli, SDEV=nsdev, QUIET=quiet
     		Copyright (c) 1998, ALS SpectroMicroscopy Facility, jd
        - read SPEM image(s) from XPD labview data file format
        Options:
           /PLOT - display (splot2d) image (first image if multiple)
           /GLITCH - run manual glitch threshold window
           SDEV=n - run auto glitch filter for data outside n std deviations

    	function Rd_SPEM, file, NOFILTER=nof, _extra=e
        Options:
    	NOFILTER -
    	_EXTRA -

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS

    MODIFICATION HISTORY:
     adapted to put a file picker around LOADSPEM
     (31-Jan-00 aph) add hourglass since slow
     (15-nov-00 cgz) AXIS standard documentation
     (15-nov-00 cgz) migrated LOADSPEM.PRO function into RD_SPEM.PRO
    				since LOADSPEM is only called from within RD_SPEM.PRO
     (15-nov-00 cgz) Replaced call of DIMEN function by explicit (SIZE(var))(index+1) in LOADSPEM
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement

(See c:\axis2000\rd_spem.pro)

## READSTRBIG

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	READSTRBIG

    LAST CHANGED: ----------------------------------- 14-nov-00

    PURPOSE:
    	This function reads all data up to the next end of line character
     from an identified logical unit into a string of arbitrary size.
     It is equivalent to readf,unit,s where s is a string
     The function gets around 32K buffer limit to load lines up to 64K long
     It also recognizes  multi-OP-system end of line characters
     10 (unix), 1010 (?), 1013 (DOS), 13 (mac), 1313 (mac,text)

    CATEGORY:
    	STAND ALONE: utility (als)

    CALLING SEQUENCE:
    	Result = READSTRBIG(unit)

    CALLED FROM AXIS:
    	->ALS file read in routines

    INPUTS:
    	UNIT - logical unit to read

    KEYWORDS:
    	BYTE - read in treated as byte-coded characters

    OUTPUTS:
    	The result is a string. If not successfully read, a blank string is returned.

    COMMON BLOCKS: none

    MODIFICATION HISTORY:
     (xx-mmm-96  er) created
     (27-feb-00 aph) AXIS standard documentation
     (14-nov-00 cgz) Replaced call of CHR function by explicit STRING(BYTE())

(See c:\axis2000\readstringbig.pro)

## READWIN

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READWIN

    LAST CHANGED: ----------------------------------- 29-Dec-00

     PURPOSE:
    	This function reads contents of WNUM graphics window
     into a bytscl array

     CATEGORY: graphics utility; standalone

     CALLING SEQUENCE:
    	RESULT = READWIN, WNUM

     INPUTS:
     WNUM	number of window to read (optional; current window is default)
        wnum is specified either as number
        or as a 5-element array [num, x0, y0, xwid, ywid] for a subset of the window

     KEYWORDS: none

     OUTPUTS: none

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (29-dec-00 aph) isolated from window.pro; AXIS standard header added

(See c:\axis2000\readwin.pro)

## READ_ALL

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_ALL

    LAST CHANGED: ----------------------------------- 22-Feb-06 (aph)

     PURPOSE:
       This function reads ion-ion correlation data from Time-of-Flight measurements
     performed and written by pTA program (C++, Neville)

     CATEGORY:
    	utility; stand-alone or used through axis2000

     CALLING SEQUENCE:
     for functions:
    	Result = ReadAll (file=file, pipico=pipico, axis_on=axis_on, silent=silent, energy=energy)

     INPUTS: none obligatory

     KEYWORDS:
     FILE		filename
     PIPICO  	plot PIPICO to check quality
     AXIS_ON   if set, called from aXis2000
     SILENT	d not prompt for parameters
     ENERGY	energy of all file

     OUTPUTS:
    	Result is an aXis2000 format image of the PEPIPICO signal
     based on user-selected binning parameters

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (14-feb-04 aph) first version
     (21-feb-04 aph) adapt for auto use in all-sequence conversion
     (22-feb-06 aph) correct to use long's for large data sets

(See c:\axis2000\read_all.pro)

## READ_ALS

[Previous Routine] [Next Routine] [List of Routines]

     function read_als, file, PLOT=pl, DEGLITCH=dgl, FILTER=fltr, _extra=e

     ----------------------------------------= LAST CHANGED:  15-nov-00
    PURPOSE:
     reads a Beamline 7 STXM image from a text file (*,im*, *,nrm)
     image size, energy, dwell information is read from (*,dat)
     NB different formats were used for (*.dat)

     ------------- revision history ---------------
     (27-may-97 aph) adapted from READ_IMG.PRO (Stefano code  of Jan97)
     ( 7-Aug-97 aph) separate file  (aph 9-oct-97 control color locally)
     ( 9-dec-97 aph) (16-feb-98) - cosmetics
     ( 3-mar-98 aph) non-square data; read in photon energy, dwell - store in SD
     ( 6-jun-98 aph) add identifier to y label indicating ALS source
     (14-jun-98 aph) axis_com
     (28-jul-98 aph) dwell format
     (07-Aug-98 aph) extension in label
     ( 7-jul-99 aph) FREE_LUN as well as close !
     (26-mar-00 aph) extend energy format for > 1 keV
     (26-sep-00 aph) add E to 2d structure
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (15-nov-00 cgz) Replaced call of NROWS function by explicit (SIZE(var))(2)

(See c:\axis2000\read_als.pro)

## READ_AXM

[Previous Routine] [Next Routine] [List of Routines]

     Copyright (c) 1999, Adam Hitchcock  All rights reserved.
    	Unauthorized reproduction prohibited.

     NAME:
    	READ_AXM

     PURPOSE:
    	This function reads a mapper 1-d data file,  into
       the standard 1d structure used internally in AXIS (ALS format)

     CATEGORY:
    	Data analysis / conversion:

     CALLING SEQUENCE:

    	Result = READ_AXM()

     INPUTS:

     OPTIONAL INPUTS:
    	Parm2:	Describe optional inputs here. If you don't have any, just
    		delete this section.

     KEYWORD PARAMETERS:
    	FILE:  provides filename and thus pickfile dialog not launched (/silent)

     OUTPUTS:
    	Describe any outputs here.  For example, "This function returns the
    	foobar superflimpt version of the input array."  This is where you
    	should also document the return value for functions.

     OPTIONAL OUTPUTS:
    	Describe optional outputs here.  If the routine doesn't have any,
    	just delete this section.

     COMMON BLOCKS:
    	@axis_com

     SIDE EFFECTS:
    	Describe "side effects" here.  There aren't any?  Well, just delete
    	this entry.

     RESTRICTIONS:
    	Describe any "restrictions" here.  Delete this section if there are
    	no important restrictions.

     PROCEDURE:
    	uses X1A READ_MAPPER routine to read mapper file

     EXAMPLE:

    	Can be used as stand-alone (in which case a structure is returned
    	 or as part of AXIS widget.

    		tmp = read_axm()

     MODIFICATION HISTORY:
     	Written by:	Adam Hitchcock - AXIS-wrapper for Jacobsen read_mapper routine. Date. 15-Sep-99

(See c:\axis2000\read_axm.pro)

## READ_A_N

[Previous Routine] [Next Routine] [List of Routines]

     FILE:  read_a_n.pro

    ===================================last changed:  15-nov-00
    PURPOSE:
    	reads a Beamline 7 STXM image from a text file (*,img)
     	then reads corresponding *,nrm normalization file
    	first two lines contain image size (pixels) of (*,dat)

     COMMON
     axis_com

     HISTORY
        adapted from READ_IMG.PRO (Stefano code  of Jan97)
        Eventually - replace with JDD's integrated version

     ( 7-Aug-97 aph) separate file  (aph 9-oct-97 control color locally)
     (16-oct-97 aph)  double read
     ( 4-mar-98 aph) gets photon energy, dwell and stores in SD
     ( 7-jul-99 aph) FREE_LUN as well as close !
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (15-nov-00 cgz) Replaced call of NROWS function by explicit (SIZE(var))(2)

(See c:\axis2000\read_a_n.pro)

## READ_BESSY_STACK.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_BESSY_STACK.PRO

    LAST CHANGED: ----------------------------------- 	13-Oct-08

     PURPOSE:
    	This function reads a sequence of images measured with Bessy STXM (Thieme)
     and converts the set to an  aXxis2000 *.ncb format

     CATEGORY:
    	data read routine. can execute outside of aXis2000

     CALLING SEQUENCE:
    	Result = READ_BESSY_STACK(directory=directory, filter=filter, normalize=normalize, silent=silent)

     INPUTS:

     KEYWORDS:
    	DIRECTORY:  name of directory
    	FILTER: extension (default for images is '*.pgm')
    	NORMALIZE: if set, modify intensities to standard ring current (value of normalize parameter
    	SILENT: if set, do not print tracking comments

     OUTPUTS:
    	No explicit outputs.

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     STACK_PROCESS_COM
     BSIF_COM
     volume_data, image_stack

     SIDE EFFECTS: none

     RESTRICTIONS: none

     PROCEDURE:

     MODIFICATION HISTORY:
     (13-Oct-08 aph) first version

(See c:\axis2000\read_bessy_stack.pro)

## READ_BESSY_STXM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_BESSY_STXM.PRO

    LAST CHANGED: ----------------------------------- 	11-Oct-08

     PURPOSE:
    	This function reads a single image from Bessy STXM (Thieme) and applies
     positional and size information to the displayed image

     CATEGORY:
    	data read. can execute outside of aXis2000

     CALLING SEQUENCE:
    	Result = READ_BESSY_STXM(file=file, filter=filter, normalize=normalize, store=store, silent=silent)

     INPUTS:

     KEYWORDS:
    	FILE:  name of file (*.pgm)
    	FILTER: extension (default is '*.pgm')
    	NORMALIZE: if set, modify intensities to standard ring current (value of normalize parameter
    	STORE: if set, write *.axb (aXis2000 format) binary file of image
    	SILENT: if set, do not print tracking comments

     OUTPUTS:
    	No explicit outputs.

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS: none

     RESTRICTIONS: none

     PROCEDURE:
    adapted from crate_nc.pro supplied by Jurgen Thieme

     MODIFICATION HISTORY:
     (11-Oct-08 aph) first version

(See c:\axis2000\read_bessy_stxm.pro)

## READ_BESSY_XML.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_BESSY_XML.PRO

    LAST CHANGED: ----------------------------------- 	11-Oct-08

     PURPOSE:
    	This function reads a text file witten in XML syntax
     which provides  undulator, beamline, microscope and image parameters for Bessy STXM

     CATEGORY:
    	data read routine. can execute outside of aXis2000

     CALLING SEQUENCE:
    	Result = READ_BESSY_XML(file=file, filter=filter, verbose=verbose)

     INPUTS:

     KEYWORDS:
    	FILE:  name of file (*.pgm)
    	FILTER: extension (default is '*.xml')
    	VERBOSE:  if on, print parameters

     OUTPUTS:
    	retuns an IDL named structure

     COMMON BLOCKS: none

     SIDE EFFECTS: none

     RESTRICTIONS: none

     PROCEDURE:
    adapted from crate_nc.pro supplied

     MODIFICATION HISTORY:
     (11-Oct-08 aph) first version; derived from read_xml.pro by Jurgen Thieme

(See c:\axis2000\read_bessy_xml.pro)

## READ_BL5

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_BL

    LAST CHANGED: ----------------------------------- 10-feb-01

     PURPOSE:
    	This function reads ALS B 5.3 STXM data from self-defining format ascii files.
     Images, stacks and linescans have *.hdr and a set of *.xim files
     for {energies.channels.regions}
     Spectra are a single *.xsp file containing header and multi-column spectra.

     CATEGORY:
    	Input / output utilty

     CALLING SEQUENCE:
    	Result = READ_BL5(file, nof=nof, filter=filter, groupID=groupID, header_only=header_only, _extra=e)

     INPUTS:
     	FILE	optional file name

     KEYWORDS:
    	FILTER	   user defined filter
    	GROUPID		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY print header contents only
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image)

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	BL5FORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (10-feb-01 aph) first version

(See c:\axis2000\read_bl5.pro)

## READ_BNL

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION  READ_BNL, file, sd
     ---------------------------------- last changed: 20-may-00 -----------
     Reads in an NSLS STXM image from netCDF format.

     It puts the image and associated information into BSIF_COMMON variables:
       image_data (the image array - possibly several planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title,
       x_dist, and y_dist

     The STXM scan data is put into "sd"
     Based on Mark Rivers stuff; Chris Jacobsen, June 1993

     ------------ Development history --------------------
     ( 7 -aug-97 aph)  - added type='2d'
     (27-May-97 aph) - adapted from nsls version of READ_STXM
                        to put data into ALS-style STRUCTURE
     ( 8-Mar-98 aph) - add SD to recover and use photon energy; use AXIS common
     (18-apr-98 aph) - SGU reported bug re divide by timer FIXED
     ( 6-Jun-98 aph)  - made xl label identical to that in read_als()
     (14-jun-98 aph) - axis_com
     (19-jun-98 aph) - normalise to average time so counts ~ right
     (29-jun-98 aph) - correct problem with "skew,kurtosis not defined for var=0"
     (28-jul-98 aph) - dwell format
     (25-jun-99 aph) - use ax_name to parse filename
     (01-apr-00 aph) - extend size of E-display format
     (20-may-00 aph) - do not prompt for name if filename given

(See c:\axis2000\read_bnl.pro)

## READ_BSP

[Previous Routine] [Next Routine] [List of Routines]

     function read_bsp, file, sd, header_only=header_only, DEFPATH=DefPath, _extra=e

     --------------------------------------------- last changed: 25-Jun-99
     Reads in a STXM image from netCDF format.

     It puts the image and associated information
     into BSIF_COMMON variables:
       image_data (the array which holds the image - possible several
       		planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title,
       x_dist, and y_dist

     The STXM scan data is put into "sd" BUT ONLY IF

(See c:\axis2000\read_bsp.pro)

## READ_CRYO

[Previous Routine] [Next Routine] [List of Routines]

     Copyright (c) 1999, Adam Hitchcock  All rights reserved.
    	Unauthorized reproduction prohibited.

     NAME:
    	READ_CRYO

     PURPOSE:
    	This function reads a cryo-STXM image file, converts it to NetCDF format, then reads that file into
       the standard 2d structure used internally in AXIS (ALS format)

     CATEGORY:
    	Data analysis / conversion:

     CALLING SEQUENCE:

    	Result = READ_CRYO()

     INPUTS:

     KEYWORD PARAMETERS:
    	FILE:  provides filename and thus pickfile dialog not launched (/silent)

     OUTPUTS:
    	RESULT is a 2d image in AXIS 2d data structure
       s = {t:'2d', x:x, y:y, d:d, xl:x_label, yl: y_label, dl: data_label}

     COMMON BLOCKS:
    	@axis_com

     PROCEDURE:
    	uses cryo_to_stxm routine to convert to *.nc, then uses read_bnl routine to read into axis

     EXAMPLE:

    	Can be used as stand-alone (in which case a structure is returned
    	 or as part of AXIS widget.

    		tmp = read_cryo()

     MODIFICATION HISTORY:
     (15-sep-99) Written by: Adam Hitchcock - based on Jacobsen cryo_to_stxm routine.
     (18-sep-99 aph) auto-correct *.nc file for no NaN or inf data
     (17-Oct-99 aph) improve header. change name to READ_CRYO (was rd_cryo)

(See c:\axis2000\read_cryo.pro)

## READ_CSV

[Previous Routine] [Next Routine] [List of Routines]

     pro read_csv,filename,x,y

       Extracts the data from comma space value files like are used in Excel

       Inputs
       filename    the name of the mapper file to be read

       Outputs
       x   an array containing the x values from the file
       y   an array containing the y values from the file.
                   this could be multidimensional...

       Usage
       read_csv, filename, x, y
    ;
       Completely rewritten Nov. 1997, CJJ
       CJJ, July 24, 1998: skip lines which start with anything other than
         space, tab, or a number or a plus sign or a minus sign or a decimal point

(See c:\axis2000\read_csv.pro)

## READ_FILEINFO_P3B

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_FileInfo_P3B

    LAST CHANGED: ----------------------------------- 	20-Jan-07

     PURPOSE:
    	This procedure reads all the parameters from ALS PEEM3 data file

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  ReadFileInfo_P3B, FileName, PIXEL_TYPE = pixtype, $
                        IMAGE_DIMENSIONS = dims, IMAGE_NUMBER = nframes

     INPUTS:
    	Filename	name of file (ext = '*.p3b')

     KEYWORDS:
    	PIXEL_TYPE  IDL data type number (integer, float, long, etc)
    	IMAGE_DIMENSIONS size of image (nx, ny)
    	IMAGE_NUMBER 	number in a stack

     OUTPUTS: adds tags to data file

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (20-Jan-07 aph) extracted from filetype_p3b.pro (20-jan-07 version of A. Scholl)

(See c:\axis2000\readfileinfo_p3b.pro)

## READ_LOX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_LOX

    LAST CHANGED: ----------------------------------- 11-Jun-08 (aph)

     PURPOSE:
    	This function reads Lox format data files used in CLS CaPeRS PEEM.
     Spectra, images, stacks and linescans have *.lox and a set of associated files
     Image and image sequences are 16-bit TIF format, and can have associated saved signals.
     Spectra are a *#.xsp file for each region (#) containing multi-column spectra.

     CATEGORY:
    	Input / output utilty; stand alone or from axis2000

     CALLING SEQUENCE:
    	Result = READ_LOX(file=file, filter=filter, channel = channel, region = region, verbose=verbose, $
                 group=group, header_only=header_only, map=map, one_image, _extra=e)

     INPUTS:
     	FILE	optional file name

     KEYWORDS:
    	FILE		name of file (if not given, use pickfile2 to obtain filename
    	FILTER	   	user defined filter
    	CHANNEL		preselected data channel
    	MULTI		read all channels
    	REGION		preselected region
    	ALL_REGIONS read in all regions
    	VERBOSE		print out details of parsing structure (testing)
    	GROUP		group leader (Axis_ID if called from aXis2000 and axis)
    	TYPE		 extract and return header contents only
    	MAP			treat NEXAFS Image Scan as a set of 2 images to derive OD difference as a map
       ONE_IMAGE	if defined, index of image to be read
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image, linescan) or 3d (stack, as *.ncb)

     COMMON BLOCKS:
    	@ANALCOM	common for stack_analyze
    	@AXIS_COM	standard set of common blocks
    	@BSIF_COM	stack common
    	VOLUME_DATA	stack data set
    	LOX_COM		common for LOX read in

     MODIFICATION HISTORY:
     (16-Oct-05 aph)  first adapted from read_sdf (Aug-05 version)
            CAUTION  - previously a procedure with this name (READ_LOX) only read spectra
    				  - that routine was re-named READ_LOX_SPECTRA
                     - calls from axis_c, tif_convert were changed - other uses may exist !!
     (29-Oct-05 aph) - adapt for stack read in (partial)
     (13-nov-05 aph) - finsih stack read in ; channels, spectrum
     (16-nov-05 aph) - accomodate binning
     (18-mar-06 aph) only print binning of camera in verbose mode; fix channel read in
     (05-jun-06 aph) error of IDL5.2 reading Lox files solved - line 122 - need to use t(0) (SCALAR) not t (ARRAY)
     (13-aug-06 jso) adapt to new format of Lox files
     (07-jan-07 aph) check if DarkImageSubtracted="True", if so, set lox.dark=0
     (15-jan-07 aph) correct stack read to give correct size
     (11-jun-08 aph) fix first image mis-match array dimension problem - KLUGE  on hbin, vbin !!!

(See c:\axis2000\read_lox.pro)

## READ_LOX_SPECTRA

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_LOX_SPECTRA

    LAST CHANGED: ----------------------------------- 08-jan-07 (aph)

     PURPOSE:
    	This function reada a Lox spectral file into an aXis 1-d structure
     or into a multi-column array

     CATEGORY: spectral input
     called from READ~spectra~Lox

     CALLING SEQUENCE:
    	Result = READ_LOX_SPECTRA(file=file, filter=filter, NOF=nof,  multi = multi, $
                channel=channel, region = region, verbose = verbose, _extra=e)

     INPUTS:
    	All input parameters are passed as keywords.

     KEYWORDS:
    	FILE:			filename
    	FILTER:			optional user selectable filter (default = '*.lox'
    	NOF:			no filter (*.*)
    	MULTI 			read all spectra in multi-column file
    	VERBOSE:		if set to 1; print input file as it is read
    	CHANNEL			read in specific channel of a multi-column file
    	REGION			read-in from file associated with a specific region (now = PEEM-channel)
    	SILENT			if set, no feedback in print or axis_log
    	_EXTRA_E:		forward other parameters to any programs this one calls

     OUTPUTS: returns a structure containing spectrum, unless MULTI keyword is set

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (17-may-04 aph) adapt from pem_load fle
     (01-jun-04 aph) adapt for stack files without
     (30-jan-05 aph) add sorting to make compatible with reverse scanning
     (14-jun-05 aph) correct spectral read in to get correct number of points
     (16-jun-05 aph) add kluge to handle blank line in jun-05 lox_spectra format
     (16-oct-05 aph) CHANGED NAME (from Read_lox  to Read_lox_spectra)
                 set up to do multi-column reading for regions
     (13-Nov-05 aph) read in mesh or specific region signal
     (18-mar-06 aph) activate channel parameter
     (12-jun-06 jso) corrected to be compatible with IDL5.2
     (07-aug-06 aph) merged with main code
     (08-jan-07 aph) define channel, when it is not defined by keyword

(See c:\axis2000\read_lox_spectra.pro)

## READ_MAPPER[1]

[Previous Routine] [Next Routine] [List of Routines]

     pro read_mapper,filename,x,y

       Extracts the data from Mapper files and stores it in the
       float arrays x and y

       Inputs
       filename    the name of the mapper file to be read

       Outputs
       x   an array containing the x values from the Mapper file
       y   an array containing the y values from the Mapper file.
                   this could be multidimensional...

       Usage
       read_mapper, filename, x, y

       Warnings
       Not assuming responsibility for misuse, or abuse of other file
       types. Will not work if data plotted with the LINE command.

       Completely rewritten Nov. 1997, CJJ

(See c:\axis2000\read_mapper.pro)

## READ_MAPPER[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     		READ_MAPPER

    LAST CHANGED: ----------------------------------- 	12-may-02

     PURPOSE:
    	This procedure reads in Zimba format alignment shifts.

     CATEGORY:
    	Image display.

     CALLING SEQUENCE:
    	READ_MAPPER, FILENAME, X, Y

     INPUTS:
     FILENAME	- name
     X		- array of X-shifts
     Y		- array of Y-shifts
     params - parameters

     KEYWORDS:
    	help=help
       quiet=quiet

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     ROUTINES
     zstack_read_mapper_firstnum

     MODIFICATION HISTORY:
     (12-may-02 aph) AXIS standard header added

(See c:\axis2000\zstack_read_mapper.pro)

## READ_MRC_FILE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_MRC_FILE

    LAST CHANGED: ----------------------------------- 12-Jun-06 (gaj)

     PURPOSE:
    	This procedure reads a whole stack (3d (x,y,z) array) from a *.MRC binary file

    	http://bio3d.colorado.edu/imod/doc/mrc_format.txt
    	http://ami.scripps.edu/prtl_data/mrc_specification.htm

     CATEGORY:
    	stack processing

     CALLING SEQUENCE:
    	READ_MRC_FILE, FILE

     INPUTS:
     	FILE	name of the input file

     KEYWORDS: none

     OUTPUTS:

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     ANAL_COM
     BSIF_COM
     volume_data, image_stack

     SIDE EFFECTS:

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (12-Jun-06 gaj) first version based on WRITE_MRC_FILE and STACK_RB
     (13-Jun-06 gaj) corected some variable names and bugs

(See c:\axis2000\read_mrc_file.pro)

## READ_P3B

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_P3B

    LAST CHANGED: ----------------------------------- 	12-Sep-07

     PURPOSE:
    	This function reads a ALS PEEM3 image
     (IDL windows binary with a structure defining microscope parameters)

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  Read_P3B, Filename, TAGS = tags, NTAGS = numtags

     INPUTS:
    	Filename	name of file (ext = '*.p3b')

     KEYWORDS:
    	TAGS	predefined structure which extracts from embeded parameter structure
    	NTAGS	number of tags in predefined variable

     OUTPUTS:
    	RESULT	2-d array with data, and TAGS structure, if requested

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (20-Jan-07 aph) extracted from filetype_p3b.pro (20-jan-07 version of A. Scholl)
     (12-sep-07 aph) updated from late Jan-07 version sent by Andreas

(See c:\axis2000\read_p3b.pro)

## READ_P3B_SPECTRUM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_P3B_SPECTRUM

    LAST CHANGED: ----------------------------------- 	20-Jan-07

     PURPOSE:
    	This function reads a ALS PEEM3 spectrum

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  Read_P3B_spectrum, file=file

     INPUTS: only by keyword

     KEYWORDS:
    	File	name of file (ext = '*.dat')
    	FLTR 	alternative data filter
    	SILENT	do not give log details

     OUTPUTS:
    	RESULT	1-d axis structure

     COMMON BLOCKS:
     @axis.com

     MODIFICATION HISTORY:
     (20-Jan-07 aph) first written

(See c:\axis2000\read_p3b_spectrum.pro)

## READ_PEEM3

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	READ_PEEM3

    LAST CHANGED: ----------------------------------- 07-Aug-08 (aph)

    PURPOSE:
    	This function reads in ALS PEEM3 format image and stores in
     an axis 2d structre

    CATEGORY:
    	STAND ALONE: utility

    CALLING SEQUENCE:
    	Result = READ_PEEM3([file=file, nof=nof,bin=bin, scale=scale, _extra=e])

    CALLED FROM AXIS:
    	Read->Images->AXIS (and in many analysis routines)

    INPUTS: none. All input parameters are passed as keywords.

    KEYWORDS:
    	FILE 	- filename to read
    	NOF   	- no nme filter
    	BIN		- factor to bin by
    	SCALE	- scale in nm/pixel prior to binning
    	_EXTRA - passed on parameters

    OUTPUTS:
    	RESULT = AXIS 2d structure

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (21-Jan-07 aph) first version
     (10-mar-07 sgu) modify for change in ring current key word (beamcurrent => ringcurrent)
     (12-mar-07 aph) generalize to either key word
     (12-sep-07 aph) allow stand alone operation; change to use Scholl faster approach (single read of image)
     (07-Aug-08 aph) remove ring current normalization if ring current less than 1 mA or absent

(See c:\axis2000\read_peem3.pro)

## READ_SDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_SDF

    LAST CHANGED: ----------------------------------- 13-Oct-08

     PURPOSE:
    	This function reads self-defining format ascii files used in ALS Beamline 5.3.2 STXM.
     Spectra, images, stacks and linescans have *.hdr and a set of *.xim files
     Image modes have separate file for each {energies.channels.regions}
     Spectra are a *#.xsp file for each region (#) containing multi-column spectra.
     Images, stacks are normalized to 400 mA ring current (N400)

     CATEGORY:
    	Input / output utilty; stand alone or from ax_sdf / axis2000

     CALLING SEQUENCE:
    	Result = READ_SDF(file, filter=filter, channel = channel, region = region, verbose=verbose, $
                 group=group, header_only=header_only, map=map, one_image, _extra=e)

     INPUTS: none required

     KEYWORDS:
     	FILE		optional file name
    	FILTER	   user defined filter
    	CHANNEL		preselected data channel
    	REGION		preselected region
    	ALL_REGIONS read in all regions
    	VERBOSE		print out details of parsing structure (testing)
    	GROUP		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY extract and return header contents only
    	MAP			treat NEXAFS Image Scan as a set of 2 images to derive OD difference as a map
    	NO_INTERPOLATE  if set, do not convert rectangular to square pixels
       SILENT		do not print any tracking information
       ONE_IMAGE	if defined, index of image to be read
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image, linescan) or 3d (stack, as *.ncb)

     COMMON BLOCKS:
    	@ANALCOM	common for stack_analyze
    	@AXIS_COM	standard set of common blocks
    	@BSIF_COM	stack common
    	VOLUME_DATA	stack data set
    	SDF_COM		common for SDF read in
    	SDFORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (11-feb-01 aph) first version
     (23-feb-01 aph) arrays of structures implemented
     (25-feb-01 aph) option to return structure only implemented
     (27-jun-01 aph) adapt to read focus and OSA scans
     (12-jul-01 aph) enable read-in of spectral modified format
     (29-jul-01 aph) retired read_bl5 spectral read-in; new format with *.hdr is in place
                   regions implemented for spectra
     (14-aug-01 aph) fixed errors found by Ivo in spectra & linescan read-in
     (17-aug-01 aph) adapt to REGIONS (kluge needed !)
     (22-aug-01 aph) stack readin (directly convert to *.ncb file)
     (09-nov-01 aph) activate all region read in for spectra
     (17-feb-02 aph) motor scan processing
     (28-feb-02 aph) ensure works for partial stacks
     (12-may-02 aph) correct header name format
     (28-may-02 aph) delete last column - set of zero's which may cause processing problems
     (11-dec-02 aph) adapt for VLM Image readin; (NB group_ID problem if run stand alone)
     (02-apr-03 aph) 'OSA focus scan' read-in
     (29-apr-03 aph) add tag  in log and axis windows to identify bad images
     (19-jun-04 aph) auto sort energies on readin of stack - NB PROBLEM with IDL sort function !!
     (22-aug-04 aph) replace 'GoTo' with  'ToGo' to avoid problem with IDL 6 throwing error on 'GoTo'
                     kluge solution to out-of-order sort
     (29-aug-04 aph) restricted sort correction to IDL 6 using !version.release check
            NB - array_equal not in pre-IDL6 ; sort still does not work correctly !
     (21-nov-04 aph) read Detector scans
     (20-feb-05 aph) add MAP function to read in a 2-image stack and take OD difference
                     add one_image finction to read one image from a stack
     (09-mar-05 aph) fix IDL 5.2 partial stack read-in problem
     (24-mar-05 aph) simplify label for 1-image read-in (filename indicates it)
     (17-jun-05 aph) channels and regions working for map and 1-image read; default region = 1
     (24-aug-05 aph) extend to 26 channels of data
     (25-aug-05 aph) add Pattern and Chart read-in
     (15-dec-05 aph) adapt to non-axis and non-interactive use (for tomography)
    				  add definition of images for mapping; add keywords SILENT, NO_INTERPOLATE
    				  correct error on interpolation to square pixels
     (22-Mar-06 aph) Images, stacks normalized to 400 mA ring current (N400); add chart scan read in
     (04-May-06 aph) normalize stacks image-by-image to the ring current
     (11-mar-07 aph) switch on panel to set flag to control ring current normalization
     (18-May-07 aph) correct read-in of 1-image for multi-channel data (B. Watts)
     (14-Jun-07 aph) systematically close_lun, free_lun (replaced 2 close,/all commands) to allow stack read and release
     (14-Jul-07 aph) allow transfer of stack to stack_analyze even if do not write raw stack
     (13-Oct-08 aph) convert from stacK-analyze to stack_process

(See c:\axis2000\read_sdf.pro)

## READ_SDF-INT

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_SDF

    LAST CHANGED: ----------------------------------- 17-aug-01

     PURPOSE:
    	This function reads self-defining format ascii files used in ALS Beamline 5.3.2 STXM.
     Spectra, images, stacks and linescans have *.hdr and a set of *.xim files
     Image modes have separate file for each {energies.channels.regions}
     Spectra are a *#.xsp file for each region (#) containing header and multi-column spectra.

     CATEGORY:
    	Input / output utilty

     CALLING SEQUENCE:
    	Result = READ_SDF(file, nof=nof, filter=filter, verbose=verbose, groupID=groupID, header_only=header_only, _extra=e)

     INPUTS:
     	FILE	optional file name

     KEYWORDS:
    	FILTER	   user defined filter
    	VERBOSE		print out details of parsing structure (testing)
    	CHANNEL		preselected data channel
    	REGION		preselected region
    	GROUPID		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY extract and return header contents only
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image, linescan)

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	SDFORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (11-feb-01 aph) first version
     (23-feb-01 aph) arrays of structures implemented
     (25-feb-01 aph) option to return structure only implemented
     (27-jun-01 aph) adapt to read focus and OSA scans
     (12-jul-01 aph) enable read-in of spectral modified format
     (29-jul-01 aph) retired read_bl5 spectral read-in; new format with *.hdr is in place
                   regions implemented for spectra
     (14-aug-01 aph) fixed errors found by Ivo in spectra & linescan read-in
     (17-aug-01 aph) adapt to REGIONS (kluge needed !)

(See c:\axis2000\read_sdf-int.pro)

## READ_SDF-INT1

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_SDF

    LAST CHANGED: ----------------------------------- 14-aug-01

     PURPOSE:
    	This function reads self-defining format ascii files used in ALS Beamline 5.3.2 STXM.
     Spectra, images, stacks and linescans have *.hdr and a set of *.xim files
     Image modes have separate file for each {energies.channels.regions}
     Spectra are a *#.xsp file for each region (#) containing header and multi-column spectra.

     CATEGORY:
    	Input / output utilty

     CALLING SEQUENCE:
    	Result = READ_SDF(file, nof=nof, filter=filter, verbose=verbose, groupID=groupID, header_only=header_only, _extra=e)

     INPUTS:
     	FILE	optional file name

     KEYWORDS:
    	FILTER	   user defined filter
    	VERBOSE		print out details of parsing structure (testing)
    	CHANNEL		preselected data channel
    	REGION		preselected region
    	GROUPID		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY extract and return header contents only
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image, linescan)

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	SDFORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (11-feb-01 aph) first version
     (23-feb-01 aph) arrays of structures implemented
     (25-feb-01 aph) option to return structure only implemented
     (27-jun-01 aph) adapt to read focus and OSA scans
     (12-jul-01 aph) enable read-in of spectral modified format
     (29-jul-01 aph) retired read_bl5 spectral read-in; new format with *.hdr is in place
                   regions implemented for spectra
     (14-aug-01 aph) fixed errors found by Ivo in spectra & linescan read-in

(See c:\axis2000\read_sdf-int1.pro)

## READ_SDFE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: READ_SDFE

    LAST CHANGED: ----------------------------------- 22-aug-01

     PURPOSE:
    	This function reads self-defining format ascii files used in ALS BL 5.3.2 STXM.
     Images, stacks and linescans have *.hdr and a set of *.xim files
     for {energies.channels.regions}
     Spectra are a single *.xsp file containing header and multi-column spectra.

     CATEGORY:
    	Input / output utilty

     CALLING SEQUENCE:
    	Result = READ_SDF(file, nof=nof, filter=filter, verbose=verbose, groupID=groupID, header_only=header_only, _extra=e)

     INPUTS:
     	FILE	optional file name

     KEYWORDS:
    	FILTER	   user defined filter
    	VERBOSE		print out details of parsing structure (testing)
    	CHANNEL		preselected data channel
    	GROUPID		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY print header contents only
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	structure variable; either 1d (spectra) or 2d (image)

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	SDFORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (11-feb-01 aph) first version
     (23-feb-01 aph) arrays of structures implemented
     (25-feb-01 aph) option to return structure only implemented
     (22-aug-01 aph) rescued from axis2000-1b (Jul-01) for early file readin

(See c:\axis2000\read_sdfe.pro)

## READ_STXM

[Previous Routine] [Next Routine] [List of Routines]

     pro read_stxm, file, sd
     -------------------------------------------- last changed: 9-Sep-99

     Reads in a STXM image from netCDF format.

     It puts the image and associated information
     into BSIF_COMMON variables:
       image_data (the array which holds the image - possible several
    		        planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title,
       x_dist, and y_dist

     The STXM scan data is put into "sd"

(See c:\axis2000\read_stxm.pro)

## READ_STXM4

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	READ_STXM4

     LAST CHANGED:                   30-Sep-01

     PURPOSE:
    	This function reads a STXMIV image (spectrum) file into
       the standard 2d (1d) structure used internally in AXIS (ALS format)
    	Spectra are distinguished from images by existence of only one row

     CATEGORY:
    	Data analysis / conversion:

     CALLING SEQUENCE:

    	Result = read_stxm4()

     INPUTS:

     KEYWORD PARAMETERS:
    	FILE:  provides filename and thus pickfile dialog not launched (/silent)
     SILENT:  if set there is no logging of the conversion (for multifile processing)

     OUTPUTS:
    	RESULT is EITHER:
      a 2d image in AXIS 2d data structure
       s = {t:'2d', x:x, y:y, e:energy; d:d, xl:x_label, yl: y_label, dl: data_label}
      OR a 1d spectrum in AXIS 1d data structure
       s = {t:'1d', x:x, d:d, dn:d, xl:x_label, yl: y_label, dl: data_label}

     COMMON BLOCKS:
    	@axis_com
    	@bsif_com

     MODIFICATION HISTORY:
     (29-jun-01 aph) develop to read new STXM IV ; modified from read_cryo
     (18-jul-01 aph) add storage of parameters in sd structure of bsif_com to properly transfer info
     (30-sep-01 aph) adapt to read NSLS STRXM-IV spectra; images in kHz

(See c:\axis2000\read_stxm4.pro)

## READ_TAGS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_TAGS

    LAST CHANGED: ----------------------------------- 	12-Sep-07

     PURPOSE:
    	This function reads parameters from an embedded structure in the ALS PEEM3 data format

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  ReadTags, Unit, TAGS = Tags, NTAGS = numtags, MAXTAGS = maxtags

     INPUTS:
    	Unit	open file unit number
    	Tags	parameters with associated Tag names (IDL structure)
    	NTags	number of tags
    	MaxTags	maximum number of tags

     KEYWORDS: none

     OUTPUTS: adds tags to data file

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (20-Jan-07 aph) extracted from filetype_p3b.pro (20-jan-07 version of A. Scholl)
     (12-sep-07 aph) update to version sent late Jan-07 (seemed the same)

(See c:\axis2000\readtags.pro)

## READ_TOMO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		READ_TOMO

    LAST CHANGED: ----------------------------------- 13-Dec-05

     PURPOSE:
    	This Sript processes a set of folders containing stacks for tomography read-in

     CATEGORY:
    	Input / output utilty; stand alone

     CALLING SEQUENCE:
    	Result =

     INPUTS:
     	FILE	list of folders to process

     OUTPUTS:
    	folder with selected files

     MODIFICATION HISTORY:
     (13-dec-05 aph) adapt to non-axis and non-interactive use (for tomography)

(See c:\axis2000\read_tomo.pro)

## READ_UVIEW

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	READ_UVIEW

    LAST CHANGED: ----------------------------------- 01-Nov-05

    PURPOSE:
    	This function reads in an image from (*.dat) binary format
     of UVIEW2002 camera program from Elmitec PEEM-III
     Format is described in the UVIEW2002 manual
     returns image as an aXis2000 2d structure

    CATEGORY:
    	AXIS: image utility (also runs stand alone)

    CALLING SEQUENCE:
    	Result = READ_UVIEW(file = file, skip=skip, verbose=verbose)

    CALLED FROM AXIS:
    	->Image->Elmitec->{dat}

    INPUTS:
    	All input parameters are passed as keywords.

    KEYWORDS:
     FILE  - name of file; if supplied, and exists, reads silently
     SKIP - do not read header; value of skip is image size (square)
     VERBOSE - if set, print all of file and image headers

    OUTPUTS: none

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

     DETAILS
     Format of Uview binary mage files (*.dat)
     has 3 parts
      Fileheader  (104 bytes)
      Imageheader (48 bytes)
      Data (width x height x 2 bytes)

     struct UKFileHeader{		 size of(UKFileHeader):104
    	20 char id[20];
    	 2 short size;
    	 2 short version;
    	 2 short BitsPerPixel; (= 16 for Sensicam,  storage, not 12-bit acquisition)
        6  [not advetised 6-byte 'bye' for getting long to proper spot ]
            // 6 bytes inserted to get to next 8 byte boundary.
               LONGLONG seems to need to start at 8 byte boundary
      	 8 LONGLONG starttime;
    	 2 short ImageWidth;
    	 2 short ImageHeight;
    	 2 short NrImages;
    	 2 short spareShort;
    	56 BYTE spare[56];
     };

     struct UKImageHeader   size of(UKImageHeader):48
      2	short size;
      2	short version;
      4    // 4 bytes inserted to get to next 8 byte boundary
      8	LONGLONG imagetime;
      4	long LEEMdata1_source;
      4	float LEEMdata1_data;
      2	short spin;
      2	short spareShort;
      4	float LEEMdata2_data;
     16	BYTE spare[16];
    	};

     ISSUES
     conversion from 8 bytes to a long_long time
     imagetime =   80  34 169 121 151 231 193   1
     may be same as
     imagetime =   2041127504 (ulong)

     NEW FORMAT WITH UVIEW2002   version 1.3.10 (October 2005)
     Format of Uview binary mage files (*.dat)
     has 3 parts
      Fileheader  (104 bytes)
      Imageheader (48 bytes - if Version <5; 288 bytes if version >=5)
      Data (width x height x 2 bytes)

    MODIFICATION HISTORY:
     (29-apr-02 aph) first written
     (03-may-02 aph)  get all of header using clues from Uwe
     (09-jun-04 aph) remove tag line in image time (under verbose); check that E is added
     (01-Nov-05 aph) adapt for new data format (1.3.10 - Oct-05); NB skip not working

(See c:\axis2000\read_uview.pro)

## READ_XAS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	READ_XAS

    LAST CHANGED: ----------------------------------- 26-sep-00

    PURPOSE:
    	This procedure reads a spectrum  from  'XAS' format into NetCDF format (nsls)

    CATEGORY:
    	STAND ALONE:  spectral processing

    CALLING SEQUENCE:
     	read_xas,filename,ev,all_data,header,header_only=header_only,help=help

    CALLED FROM AXIS:
    	Read-spectrum-NSLS-XAS

    INPUTS:
    	filename 	name of file
    	ev			energy array returned to caller
    	all_data	intensity array over a number of channels returned to caller
    	header		header returned to caller

    KEYWORDS:
       hader_only	= read header only
    	help		= help

    OUTPUTS:
    	none

    COMMON BLOCKS:
    	none

    MODIFICATION HISTORY:
     file obtained from Jacobsen Feb-98; developed from Mancini / Hitchcock format
     (26-sep-00 aph) AXIS standard documentation

(See c:\axis2000\read_xas.pro)

## REFRESH

[Previous Routine] [Next Routine] [List of Routines]

     FILE: refresh.pro

     LAST CHANGED: --------------------------------------- 26-Dec-07

     PURPOSE:
     Refresh
    	plot current sequence of buffers; update indicators

     ResetPlots
    	Reset the data in the temporary buffers

     COMMON BLOCKS
    	axis_com

     CALLED FROM:  axis_c

     ------------ revision history -----------------
     (03-jan-99 aph) added Zmax, Zmin impact
     ( 9-jul-99 aph) separated from axis_c.pro; fixed major error so now preserves scales
     (28-sep-99 aph) adapted to non-monotonic data
     (30-oct-99 aph) enabled overplots with buffer 0 NOT first file (o = 0 turns off overplot !!)
     (16-nov-99 aph) split our ResetPlots
     (26-Dec-07 aph) remove time/date

(See c:\axis2000\refresh.pro)

## REGION_ANALYZE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		REGION_ANALYZE

    LAST CHANGED: ----------------------------------- 	13-apr-08) (from 03-Mar-08 (MJ)

     PURPOSE:
    	This set of procedures is a widget which allows the use to group regions
     in an image set (stack) based on spectral response. It was developed for use
     with energy filtered PEEM stacks in whch the photoelectron spectrum defines the chemistry
     The user selects multiple (up to 10) spectral signals from a display of the average spectrum
     and the code identifies regions strong in each signal, and presents the reuslts to the user as a map

     CATEGORY:
    	Image analysis - called from aXis2000, via Rstack_Analyse

     CALLING SEQUENCE:
     	REGION_ANALYZE

     INPUTS:
     all inputs are obtained via common form the parent code

     KEYWORDS: none

     OUTPUTS:

     CONTENTS:
    	region_analyze_imgdisp 		stack image display
    	region_analyze_result_disp	display resulting image (colorized)
    	region_analyze_maximg		detects maximum position
    	region_analyze_event		event processing codes
    	region_analyze_sav_bin_test	math check
    	region_analyze_def_reg		define regions (no code)
    	region_analyze_remove_reg	remove last region
    	region_analyze_reset_reg	remove all regions
    	region_analyze_desensitive	desensitize non-useful buttons
    	region_analyze_sensitive	sensitize buttons
    	region_analyze_save			save the image of the identified regions

     COMMON BLOCKS:
    	@region_analyze_common
    	@axis_com
    	@bsif_com
    	@analcom

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS:
    	Any known ?

     PROCEDURE:
    	details where needed

     MODIFICATION HISTORY:
     (18-Aug-06 rec) code provided to APH for incorporation in axis2000
     (22-Sep-06 aph) AXIS standard header added; some docs added
     (03-Mar-08 MJ)  keyword /SCROLL in widget_base() needs X_SCROLL_SIZE
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows

(See c:\axis2000\region_analyze.pro)

## REMOVE_ZEROS.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	REMOVE_ZEROS.PRO

    LAST CHANGED: ----------------------------------- 18-Sep-07

    PURPOSE:
    	This function replaces all zeros in an image file
        with the adjacent non-zero data
       Optionally, it will remove up to 10 hot or cold spots
         hot spots are points at least 5 times larger than the mean
         cold spots are points less than 1/10th of the mean
            (CAUTION - many images have zero spaces)

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = REMOVE_ZEROS(2d_array,  silent=silent, remove_hot=remove_hot, remove_cold = remove_cold)

     KEYWORDS
    	silent			if set, do not display feedback
    	remove_hot 		if set, carry out hot spot removal
    	remove_cold 	if set, carry out cold spot removal

    CALLED FROM AXIS:
    	stack_analyze

    COMMON BLOCKS:
     axis_com

    MODIFICATION HISTORY:
     (10-Apr-04 aph) first version
     (18-Sep-07 aph) hot and cold spot remover added

(See c:\axis2000\remove_zeros.pro)

## RESETPLOTS

[Previous Routine] [Next Routine] [List of Routines]

    NAME
    	ResetPlots

     LAST CHANGED ------------------------------- 16-nov-99

    PURPOSE
    	Reset the data in the temporary buffers

     REVISIONS
     (16-nov-99) separate from refresh.pro; ax_color called

(See c:\axis2000\resetplots.pro)

## SAV_ALS

[Previous Routine] [Next Routine] [List of Routines]

     function sav_als, tmp, file = file, FILTER=fltr, _extra=e

(See c:\axis2000\sav_als.pro)

## SAV_HDF

[Previous Routine] [Next Routine] [List of Routines]

     PRO savHDF, tmp, fltr=fltr, file=file
     ----------------------------------- last changed: 18-jun-98
     writes AXIS 2d-structure as an HDF 2d scientific data format
     used to transfer files from AXIS to ENVI

(See c:\axis2000\sav_hdf.pro)

## SAV_HDFM

[Previous Routine] [Next Routine] [List of Routines]

     PRO savHDFm, list=list
     ----------------------------------- last changed: 18-jun-98
     writes series of NSLS files as HDF 2d scientific data format files
     used to transfer files from AXIS to ENVI

(See c:\axis2000\sav_hdfm.pro)

## SAV_NSLS.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	SAV_NSLS.PRO

    LAST CHANGED: ----------------------------------- 11-Nov-06

     PURPOSE:
     writes 2d-STRUCTURE and BSIF_COMMON info into NSLS netCDF format
     It places the Z-values of the image (in tmp structure)and associated information
     into the BSIF_COMMON variables:
       image_data (the array which holds the image - possibly several
    		planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title

     CATEGORY:
    	Stack analysis and stand alone.
     	Called from aXis2000 by images~nsls~old(*.nc)

     CALLING SEQUENCE:
       SAV_NSLS, TMP, FLTR=FLTR, FILE=FILE

     INPUTS
    	TMP		axis format image

     KEYWORDS
    	FLTR	name of filter
    	FILE	name of file
    	SILENT  flag to control entry to axis log

     COMMON BLOCKS
    	axis_com	common for AXIS2000
    	BSIF_COM	common for NetCDF files

     -------------------- REVISION HISTORY --------------------
     (xx-may-98 aph) first developed
     (14-jun-98 aph) axis_com, bsif_com
     (29-dec-98 aph) added rescale for small dynamic range real data.
     (11-jan-99 aph) remove multiple print messages; BadID
     (09-aug-99 aph) remove scaling as now save using float if needed
     (14-oct-99 aph) store correct energy as sd.wavelength
     (09-jan-00 aph) add hourglass for slow saves
     (15-dec-05 aph) tracking integer error; axis_log ; standard header
     (11-nov-06 aph) add silent keyword

(See c:\axis2000\sav_nsls.pro)

## SDF_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		SDF_COM.PRO

    LAST CHANGED: ----------------------------------- 	17-Mar-07

     PURPOSE:
    	This file contains the common block for the widget which reads SDF files

     CATEGORY:
    	utility

     MODIFICATION HISTORY:
     (17-oct-04 aph) add sdf_path
     (11-mar-07 aph) add norm_string, AXIS standard header added

(See c:\axis2000\sdf_com.pro)

## SF[1]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           SF

     LAST CHANGED: ------------------ aph ------------------------ 02-may-04

     PURPOSE:
           Function to calculate x-ray interaction properties of materials.

     CATEGORY:
           X-ray optics

     CALLING SEQUENCE:
           Result = SF(Compound [, Abscissa])

     INPUTS:
           Compound:    A scalar string containing the compound molecular formula.
                        The structure of the formula must be as follows:
                          Name1 Amount1 Name2 Amount2 ...
                        where Name1, Name2, etc. are the one or two letter
                        standard abbreviations for elements 1 to 92, and
                        Amount1, Amount2, etc. are the values describing the
                        stoichiometry. The spaces are optional. Each element may
                        appear only once in the formula.
                        NOTES: 1. Formula names ARE case-sensitive
                                  (e.g., NI is NOT Ni).
                               2. If an amount is not specified, it is assumed
                                  to be 1 (e.g., H2O is the same as H2 O1).

     OPTIONAL INPUTS:
           Abscissa:    A vector of photon energies or wavelengths at which the
                        result will be evaluated. The type and units of the
                        abscissae are specified by the keyword parameters. The
                        default is to assume the abscissae are photon energies
                        in electron volts.

     KEYWORD PARAMETERS:
           J:           If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in Joules.

           keV:         If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in kiloelectron volts.

           eV:          If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in electron volts.

           m:           If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in meters.

           nm:          If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in nanometers.

           Angstrom:    If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in Angstroms.

           RESULT_TYPE: A string specifying what result to return. The following
                        are the possible choices:
                         "f1":      The compound f1 scattering factor for the
                                    molecule.

                         "f2":      The compound f2 scattering factor for the
                                    molecule.

                         "delta":   The real part of the complex refractive index.

                         "beta":    The imaginary part of the complex refractive
                                    index.

                         "n":       The complex refractive index.

                         "mu":      The mass photoabsorption coefficient,
                                    in cm^2/g. This is the default result type.

                         "mu_a":    The atomic photoabsorption coefficient,
                                    in barns/atom.

                         "mu_l":    The linear photoabsorption coefficient,
                                    in cm^-1.

                         "trans":   The transmissivity of the material.

                         "reflect": The specular reflectivity of unpolarized light
                                    on an ideally smooth surface of the material.

           DENSITY:     The density of the material, in g/cm^3. This is needed
                        if the result type is "delta", "beta", "n", "mu_l",
                        "trans", or "reflect". Otherwise, a default density
                        of 1.0 g/cm^3 is used.

           THICKNESS:   The thickness of the material in micrometers. This is
                        needed if the result type is "trans". Otherwise, a
                        default thickness of 1.0 micron is used.

           ANGLE:       The angle of incidence in milliradians. This is needed
                        if the result type is "reflect". Otherwise, a default
                        angle of incidence of 10.0 mr is used.

           ENERGY:      A variable to receive the x-ray photon energies (in eV)
                        at which the result was evaluated.

           MW:          A variable to receive the molecular weight (in g/mol) of
                        the compound.

           SF_DIR:      A string containing the name of the directory containing
                        the SF data files.

     OUTPUTS:
           Result:      The result specified by the RESULT_TYPE keyword.

     COMMON BLOCKS:
           SF_COMMON

     SIDE EFFECTS:
           SF data is stored into common block variables each time data is read
           from the data files. This takes up memory to gain faster performance.
           The memory can be freed using the SF_DESTROY routine.

     ROUTINES CONTAINED IN THIS MODULE:
           SF_INIT           Procedure to initialize common block for module.
           SF_DESTROY        Procedure to delete common block variables.
           SF_GEN_EL_DATA    Procedure to generate data file for elements.
           SF_READ_DATA      Procedure to read SF data for single elements.
           SF_PARSE_COMPOUND Function to parse molecular formulas.
           SF                Main function to compute materials x-ray properties.

     ROUTINES CALLED BY THIS MODULE:
           IDL User Library routines:
             UNIQ, INTERPOL
           Bill Loo's IDL routines:
             STRING2FILE, FILE2STRING, STR_COLUMNS, WVLEN2EN, EN2WVLEN

     DATA FILES:
           This module requires the scattering factor data files compiled by
           B.L. Henke, E.M. Gullikson, and J.C. Davis, available by anonymous
           ftp at:
             ftp://www-cxro.lbl.gov/pub/sf/sf.tar.Z

           In addition, it requires a file containing the abbreviated element
           names and atomic weights. Such a file can be generated manually
           using the routine SF_GEN_EL_DATA. Just type "SF_GEN_EL_DATA" at the
           IDL prompt, and enter the requested information.

     REFERENCE:
           All formulas are published in:
             B.L. Henke, E.M. Gullikson, and J.C. Davis, "X-ray interactions:
             photoabsorption, scattering, transmission, and reflection at
             E=50-30,000 eV, Z=1-92," Atomic Data and Nuclear Data Tables,
             Vol. 54(2), pp. 181-342, July 1993.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCB / UCSF
           School of Medicine, UCD
           Ernest Orlando Lawrence Berkeley National Lab
           August, 1996

     MODIFICATION HISTORY:

     $Log: sf.pro,v $
     Revision 1.4  1999/03/03 06:14:10  idl
     * Changed function names for more consistent naming.
     * Minor changes to documentation.

     Revision 1.3  1999/02/28 00:26:10  idl
     * Return scalar when result has only one element.

     Revision 1.2  1997/12/16 01:55:20  loo
     * Major revision of SF program module.

     (02-may-04 aph) standardize header

(See c:\axis2000\sf.pro)

## SF[2]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           SF

     LAST CHANGED: ------------------ aph ------------------------ 24-dec-00

     PURPOSE:
           Function to calculate x-ray interaction properties of materials.

     CATEGORY:
           X-ray optics

     CALLING SEQUENCE:
           Result = SF(Compound [, Abscissa])

     INPUTS:
           Compound:    A scalar string containing the compound molecular formula.
                        The structure of the formula must be as follows:
                          Name1 Amount1 Name2 Amount2 ...
                        where Name1, Name2, etc. are the one or two letter
                        standard abbreviations for elements 1 to 92, and
                        Amount1, Amount2, etc. are the values describing the
                        stoichiometry. The spaces are optional. Each element may
                        appear only once in the formula.
                        NOTES: 1. Formula names ARE case-sensitive
                                  (e.g., NI is NOT Ni).
                               2. If an amount is not specified, it is assumed
                                  to be 1 (e.g., H2O is the same as H2 O1).

     OPTIONAL INPUTS:
           Abscissa:    A vector of photon energies or wavelengths at which the
                        result will be evaluated. The type and units of the
                        abscissae are specified by the keyword parameters. The
                        default is to assume the abscissae are photon energies
                        in electron volts.

     KEYWORD PARAMETERS:
           J:           If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in Joules.

           keV:         If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in kiloelectron volts.

           eV:          If set, the abscissae, if supplied, are interpreted
                        as x-ray photon energies in electron volts.

           m:           If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in meters.

           nm:          If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in nanometers.

           Angstrom:    If set, the abscissae, if supplied, are interpreted
                        as x-ray wavelengths in Angstroms.

           RESULT_TYPE: A string specifying what result to return. The following
                        are the possible choices:
                         "f1":      The compound f1 scattering factor for the
                                    molecule.

                         "f2":      The compound f2 scattering factor for the
                                    molecule.

                         "delta":   The real part of the complex refractive index.

                         "beta":    The imaginary part of the complex refractive
                                    index.

                         "n":       The complex refractive index.

                         "mu":      The mass photoabsorption coefficient,
                                    in cm^2/g. This is the default result type.

                         "mu_a":    The atomic photoabsorption coefficient,
                                    in barns/atom.

                         "mu_l":    The linear photoabsorption coefficient,
                                    in cm^-1.

                         "trans":   The transmissivity of the material.

                         "reflect": The specular reflectivity of unpolarized light
                                    on an ideally smooth surface of the material.

           DENSITY:     The density of the material, in g/cm^3. This is needed
                        if the result type is "delta", "beta", "n", "mu_l",
                        "trans", or "reflect". Otherwise, a default density
                        of 1.0 g/cm^3 is used.

           THICKNESS:   The thickness of the material in micrometers. This is
                        needed if the result type is "trans". Otherwise, a
                        default thickness of 1.0 micron is used.

           ANGLE:       The angle of incidence in milliradians. This is needed
                        if the result type is "reflect". Otherwise, a default
                        angle of incidence of 10.0 mr is used.

           ENERGY:      A variable to receive the x-ray photon energies (in eV)
                        at which the result was evaluated.

           MW:          A variable to receive the molecular weight (in g/mol) of
                        the compound.

           SF_DIR:      A string containing the name of the directory containing
                        the SF data files.

     OUTPUTS:
           Result:      The result specified by the RESULT_TYPE keyword.

     COMMON BLOCKS:
           SF_COMMON

     SIDE EFFECTS:
           SF data is stored into common block variables each time data is read
           from the data files. This takes up memory to gain faster performance.
           The memory can be freed using the SF_DESTROY routine.

     ROUTINES CONTAINED IN THIS MODULE:
           SF_INIT           Procedure to initialize common block for module.
           SF_DESTROY        Procedure to delete common block variables.
           SF_GEN_EL_DATA    Procedure to generate data file for elements.
           SF_READ_DATA      Procedure to read SF data for single elements.
           SF_PARSE_COMPOUND Function to parse molecular formulas.
           SF                Main function to compute materials x-ray properties.

     ROUTINES CALLED BY THIS MODULE:
           IDL User Library routines:
             UNIQ, INTERPOL
           Bill Loo's IDL routines:
             STRING2FILE, FILE2STRING, STR_COLUMNS, WVLEN2EN, EN2WVLEN

     DATA FILES:
           This module requires the scattering factor data files compiled by
           B.L. Henke, E.M. Gullikson, and J.C. Davis, available by anonymous
           ftp at:
             ftp://www-cxro.lbl.gov/pub/sf/sf.tar.Z

           In addition, it requires a file containing the abbreviated element
           names and atomic weights. Such a file can be generated manually
           using the routine SF_GEN_EL_DATA. Just type "SF_GEN_EL_DATA" at the
           IDL prompt, and enter the requested information.

     REFERENCE:
           All formulas are published in:
             B.L. Henke, E.M. Gullikson, and J.C. Davis, "X-ray interactions:
             photoabsorption, scattering, transmission, and reflection at
             E=50-30,000 eV, Z=1-92," Atomic Data and Nuclear Data Tables,
             Vol. 54(2), pp. 181-342, July 1993.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCB / UCSF
           School of Medicine, UCD
           Ernest Orlando Lawrence Berkeley National Lab
           August, 1996

(See c:\axis2000\sf_init.pro)

## SM_IPAR

[Previous Routine] [Next Routine] [List of Routines]

     This routine initializes the sm_par structure

(See c:\axis2000\sm_ipar.pro)

## SPC_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME: SPC_LOAD

    LAST CHANGED: ----------------------------------- 16-Jun-05 (aph)

     PURPOSE:
       This function reads a variety of ascii-format files
      spectra (and ascii images) from AXIS2000
      (x,y) single spectra data file; and multi-column
       smart read-in - uses first line to determine type

     CATEGORY:
    	utility; stand-alone or used through axis2000

     CALLING SEQUENCE:
     for functions:
    	Result = spc_load (file=file, filter=filter, xcol=xcol, ycol=ycol, $
             multi=multi, skip=skip, int_factor=int_factor, title=title, typ=typ, NOF=nof, _extra=e)

     INPUTS: only by keyword

     KEYWORDS:
     FILE		filename
     FILTER  	filter extension
     TITLE		optional title on filename dialog
     XCOL		number of x-axis (if multi-column)
     YCOL		number of y-axis (if multi-column)
     SKIP		number of header lines to skip  (if multi-column)
     MULTI		returns number of columns -1 = number of spectra
     TYP		type of file ('UN','MC', '1d', '2d') - use to select for multicolumn file
     NOF		no filter (*.*)
     _EXTRA	pass through keywords

     OUTPUTS:
    	Result is the (x,y) 2-d spectral or image array

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     MODIFICATION HISTORY:
     (08-may-02 aph) AXIS standard header added
     ( 9-aug-97 aph) broke out of spectral; TYPE defined
     (21-jan-98 aph) added s.dn component to 1d structure to be axis-compatible
     (20-feb-98 aph) set-up to read 2-col only data
     ( 6-mar-98 aph) read *.txt - 2 column ascii files
     ( 7-jun-98 aph) corrected read *.txt ('un' case) to get all data points
     (10-jul-98 aph) retired "*.spc" nomenclature - use *.txt extension
     (24-may-99 aph) accomodate non-AXIS files with multi-line headers
     ( 8-Jun-99 aph) remove tag line; adapt for group in get_num
     ( 9-jun-99 aph) fix up ascii image read in error
     (11-jun-99 aph) fix up widget_info error
     (25-jun-99 aph) strip path fromfile name
     ( 6-jul-99 aph) FREE_LUN as well as close !
     ( 9-sep-99 aph) silent read-in if filename is supplied
     (08-may-02 aph) explicit definition of columns in multicolumn; standard header
     (14-may-02 aph) reverse order spectra
     (30-Oct-02 aph) adapt for Sphinx spectra
     (12-Feb-03 aph) correct Sphinx.multi to handle single spectrum
     (13-Feb-03 aph) introduce TYP keyword to read in multi-column files  explicitly
     (15-aug-04 aph) explicitly define X-label for 1d data to get around problem
                     when reading non-monotonic data
     (21-mar-05 aph) add integer factor keyword to allow read-in of non-integer ascii images
     (16-Jun-05 aph) correct multi-column read-in - was missing last point ! - argh !! correction wrong
                     convert print to axis_log

(See c:\axis2000\spc_load.pro)

## SPC_SAVE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	SPC_SAVE

    LAST CHANGED: -----------------------------------  22-Nov-08

    PURPOSE:
    	This function saves 1-d (spectra) or 2-d (images) structures in AXIS ascii format.

    CATEGORY:
    	STAND ALONE: utility & called from aXis2000 write~axis  and utilities~write image ascii

    CALLING SEQUENCE:
    	Result =  SPC_SAVE(S, [file=file, int_factor=int_factor, nolb=nolbl, nof=nof])

    CALLED FROM AXIS:
    	Write->AXIS

    INPUTS:
    	S - AXIS 1d structure

    KEYWORDS:
    	FILE - filename (for silent writes)
    	INT_FACTOR - integer factor used to scale float data to preserve precision still using integer storage (only used for images)
    	NOF - no filter (default filter = '*.txt')
    	NOLBL - if set, do not query for label

    OUTPUTS:
    	An ascii file is written to disk

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     ( 7-mar-98 aph) save new label in axis
     (14-JUN-98 aph) axis_com
     (10-jul-98 aph) use *.txt as default name for ascii files
     ( 8-jul-99 aph) FREE_LUN as well as close
     (31-jul-99 aph) conditional use of handle to allow use outside axis
     (08-sep-99 aph) update buffer label
     (28-oct-99 aph) add file keyword for 'silent' writing
     (04-jan-00 aph) proper cancel; AXIs standard documentation
     (27-feb-00 aph) add groupID to get_text
     (11-apr-00 aph) fix error when writing 1d files with small or large values
     (04-jun-03 aph) add keyword to force label to current value
     (19-feb-05 aph) check for non-monotonic data and correct before saving
     (21-mar-05 aph) add int_factor keyword; confirm image write out works
     (14-Feb-06 aph) correct invalid number of points
             (removed "where", with identification of only non-zero values!)
     (30-apr-07 aph) add space between entires in 2-d write
     (13-apr-08 aph) add check for overwrite; warning and options as for saving image files (axb_save.pro)
     (22-nov-08 aph) remove duplication of overwrite check

(See c:\axis2000\spc_save.pro)

## SPECTRA

[Previous Routine] [Next Routine] [List of Routines]

       fct SPECTRA, struc[ , /INFO, /NORM, LABELS=[xlabel, ylabel'], _extra=e]
           -- extract spectral data into 1D structure {d:, dn:, x:, xl:, dl:} or
              2D structure {d:, dn:, x:, y:, xl:, yl:, dl:, dnl:}
              normalization subfield (dn:) is created unless no I0 exists or
              /NORM option is invoked

(See c:\axis2000\spectra.pro)

## SPLIT_STRING

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           SPLIT_STRING

     PURPOSE:
           This function splits a string into its delimited components.

     CATEGORY:
           String processing.

     CALLING SEQUENCE:
           Result = SPLIT_STRING(Input)

     INPUTS:
           Input:     The string to be split. The string should consist of
                      multiple words separated by a user specified delimiter.

     KEYWORD PARAMETERS:
           DELIMITER: A string containing the delimiter between words.
                      The default delimiter is a single space. Also, if the
                      default delimiter is used, multiple spaces are compressed
                      to a single space before parsing.

     OUTPUTS:
           Returns each word of the input string as one element in the
           output string array, Result.

     EXAMPLE:
           If the input string is:
             input = 'Hello, world'

           then the command sequence:
             result = split_string(input, DELIMITER=', ')

           produces the result:
             IDL> print, result(0)
             Hello
             IDL> print, result(1)
             world

           Note that the delimiter in this case includes a space.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           June, 1996

     MODIFICATION HISTORY:

     $Log: split_string.pro,v $
     Revision 1.2  1997/02/02 06:07:50  loo
     * Corrected bug that occurs if delimiter is first character in string.

     Revision 1.1  1996/06/09  07:56:00  loo
     Initial revision

(See c:\axis2000\split_string.pro)

## SPLOT

[Previous Routine] [Next Routine] [List of Routines]

     FILE: splota.pro

     last changed: ------------------------------  22-Mar-06

     REQUIREMENTS:  graph.pro MUST be compiled prior

     CONTENTS:
      pro SPLOT, s1 [, opt, _extra=e]
          options: /O - overplot
                   /DN - plot dn: field (data norm)
                   /WB - white on black
                   /ZERO - autoscale y from 0
                   _extra=e - pass along PLOT options

     INPUTS
         basic input data structure: s1={d:, x:}
         optional axis and title label fields include {xl:, yl:, dl:}

     COMMON: axis_com

     REVISIONS
     2/19/96  initial creation
     6/15/96  jdd added generalized interpretation of structures
                  in SPLOT, SPLOT2D, SPLOT3D
                  separated splot stuff from graph.pro
     6/29/96  aph allow numerical limts on ranges
     (06-Dec-97 aph) remove print of ytitle
     (03-jan-99 aph) add back in YTitle (!!)
     (24-jun-99 aph) consistent image/spectra color tables
     (13-aug-99 aph) no change - just using debugs to track reform problem
     (14-nov-00 cgz) migrated from SPLOTA.PRO
     (22-Mar-06 aph) increase character size

(See c:\axis2000\splot.pro)

## SPLOT2D

[Previous Routine] [Next Routine] [List of Routines]

     FILE: splota.pro

     last changed: ------------------------------  30-nov-00

     REQUIREMENTS:  graph.pro MUST be compiled prior

     CONTENTS:
      pro SPLOT2D, s2  [, /ASPECT, opt]	-- image plot with axes
          options: /ASPECT rescale window vertical size to
                           aspect ratio similar to the image dimensions
                   /ZOOM allows user to define x,y ranges
                   _extra=e - pass along PLOT options

     INPUTS
         basic input data structure: s2={d:, x:, y:}
         optional axis and title label fields include {xl:, yl:, dl:}

     COMMON: axis_com

     REVISIONS
     2/19/96  initial creation
     6/15/96  jdd added generalized interpretation of structures
                  in SPLOT, SPLOT2D, SPLOT3D
                  separated splot stuff from graph.pro
     6/29/96  aph allow numerical limts on ranges
     (06-Dec-97 aph) remove print of ytitle
     (03-jan-99 aph) add back in YTitle (!!)
     (24-jun-99 aph) consistent image/spectra color tables
     (13-aug-99 aph) no change - just using debugs to track reform problem
     (14-nov-00 cgz) migrated from SPLOTA.PRO
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (30-nov-00 cgz) Replaced call of WSIZE function by explicit [!D.X_SIZE,!D.Y_SIZE]
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement

(See c:\axis2000\splot2d.pro)

## SPLOT3D

[Previous Routine] [Next Routine] [List of Routines]

     FILE: splota.pro

     last changed: ------------------------------  30-nov-00

     REQUIREMENTS:  graph.pro MUST be compiled prior

     CONTENTS:
      pro SPLOT3D, s2  [,opt]	-- surface plot with axes
     options: /ASPECT rescale window vertical size to
              aspect ratio similar to the image dimensions
              /ZOOM allows user to define x,y ranges

     INPUTS
         basic input data structure: s2={d:, x:, y:}
         optional axis and title label fields include {xl:, yl:, dl:}

     COMMON: axis_com

     REVISIONS
     2/19/96  initial creation
     6/15/96  jdd added generalized interpretation of structures
                  in SPLOT, SPLOT2D, SPLOT3D
                  separated splot stuff from graph.pro
     6/29/96  aph allow numerical limts on ranges
     (06-Dec-97 aph) remove print of ytitle
     (03-jan-99 aph) add back in YTitle (!!)
     (24-jun-99 aph) consistent image/spectra color tables
     (13-aug-99 aph) no change - just using debugs to track reform problem
     (14-nov-00 cgz) migrated from SPLOTA.PRO
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (30-nov-00 cgz) Replaced call of WSIZE function by explicit [!D.X_SIZE,!D.Y_SIZE]
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement

(See c:\axis2000\splot3d.pro)

## SPLOTA

[Previous Routine] [Next Routine] [List of Routines]

     FILE: splota.pro

     last changed: ------------------------------  30-nov-00

     REQUIREMENTS:  graph.pro MUST be compiled prior

     CONTENTS:
      pro SPLOT, s1 [, opt, _extra=e]
          options: /O - overplot
                   /DN - plot dn: field (data norm)
                   /WB - white on black
                   /ZERO - autoscale y from 0
                   _extra=e - pass along PLOT options
      pro SPLOT2D, s2  [, /ASPECT, opt]	-- image plot with axes
          /ASPECT resizes window height to match make dx~dy
      pro SPLOT3D, s2  [,opt]	-- surface plot with axes

     INPUTS
         basic input data structure: s1={d:, x:}, s2={d:, x:, y:}
         optional axis and title label fields include {xl:, yl:, dl:}

     COMMON: axis_com

     REVISIONS
     2/19/96  initial creation
     6/15/96  jdd added generalized interpretation of structures
                  in SPLOT, SPLOT2D, SPLOT3D
                  separated splot stuff from graph.pro
     6/29/96  aph allow numerical limts on ranges
     (06-Dec-97 aph) remove print of ytitle
     (03-jan-99 aph) add back in YTitle (!!)
     (24-jun-99 aph) consistent image/spectra color tables
     (13-aug-99 aph) no change - just using debugs to track reform problem
     (15-nov-00 cgz) Replaced call of NCOLS function by explicit (SIZE(var))(1)
     (30-nov-00 cgz) Replaced call of WSIZE function by explicit [!D.X_SIZE,!D.Y_SIZE]
     (30-nov-00 cgz) Replaced call of nwin with explicit window statement

(See c:\axis2000\splota.pro)

## SROTATE

[Previous Routine] [Next Routine] [List of Routines]

       fct SROTATE, struc, [dir , /Trans, /NORM, LABELS=[xlabel, ylabel'], _extra=e]
           -- rotate 2D structure (and dn: subfield) using ROTATE and
    				appropriately exchange and reverse the axis arrays and labels
    		  dir =  direction # [0-7] as defined by ROTATE:
    				  0 deg:		0  [ X, Y]		+ Transpose:   4  [ Y, X]
    				 90 deg:  	1  [-Y, X]		+ Transpose:   5  [-X, Y]
    				180 deg:  	2  [-X,-Y]		+ Transpose:   6  [-Y,-X]
    				270 deg:  	3  [ Y,-X]		+ Transpose:   7  [ X,-Y]
    		 Options:
    			/Trans - transpose X & Y axes  (dir=4)
    			/Hflip - horizontal flip  (dir=5)
    			/Vflip - vertical flip (dir=7), (dir=2, both Hflip & Vflip)

(See c:\axis2000\srotate.pro)

## STACK_ADD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      STACK_ADD

    LAST CHANGED: ----------------------------------- 17-Sep-08

     PURPOSE:
    	This procedure adds two stacks presumed to be on same E and spatial scales

     CATEGORY:
    	stack processing; stand alone operation

     CALLING SEQUENCE:
    	STACK_ADD, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS: 	none

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     stack_process_com
     BSIF_com
     volume_data, image_stack

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (29-Aug-04 aph) first version
     (17-oct-04 aph) provide weighting coefficients
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_add.pro)

## STACK_ALIGN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      STACK_ALIGN

    LAST CHANGED: ----------------------------------- 17-Sep-08

     PURPOSE:
    	This procedure aligns images of a stack

     CATEGORY:
    	stack processing - part of axis2000 stack analyze package

     CALLING SEQUENCE:
    	STACK_ALIGN

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS: 	*.aln file with list of (x,y) pixel shifts to align images

     COMMON BLOCKS:
     BSIF_com
     volume_data, image_stack
     pix_shift

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (25-mar-98 cjj) to deal with 24 bit graphics
     (11-Jul-98 aph) to deal with changes to align.pro
     (12-dec-98 aph) remove all bsif_common
     (08-may-00 aph) add xpix_shift, ypix_shift to transfer size of grey area
     (17-Sep-08 aph) replace analcom with stack_process_com  (there were no occurrences)
                     standard header added

(See c:\axis2000\stack_align.pro)

## STACK_ANALYZE.PRO[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STACK_ANALYZE.PRO

    LAST CHANGED: ----------------------------------- 24-Apr-06

     PURPOSE:
    	This set of procedures and functions is a widget to display
     and extract spectra from stacks.
     This version (derived from from late January 98 version of CJJ) has been
     modifed to handle file names and paths better.
     Read in Io signals from ascii (*.txt) spectral format files (x,y)
     Correct E-scales; normalize yield data; subtract spectra, stacks
     extract images (*.nc format) from stacks.

     CATEGORY:
    	Stack analysis.
     Called from aXis2000 by stacks~stack~analyse~AXIS (or AXIS binary)

     CALLING SEQUENCE:
    	STACK_ANALYZE, [ list_filename, shift_filename, fpath=fpath, binary=binary, $
                       zoom=zoom, text_height=text_height, realign=realign, $
                       help=help, no_align = no_align ]

     INPUTS:
     list_filename		name of file with list of *.nc image files
     shift_filename	name of file with list of x,y pixel shifts for alignment

     KEYWORDS:
     fpath			path for files
     binary		read in as *.ncb binary (all images in one file)
     zoom			zoom factor
     text_height	size of text
     realign		launch stack_align after applying shifs in shift_filename
     help			print help information
     no_align		do not launch stack_align

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	BSIF_COM	common for NetCDF files
    	ANALCOM		common for stack analyze
    	VOLUME_DATA image_stack - 3d array of stack data
    	PIX_SHIFT	set of pixel shifts ( xpix_shift, ypix_shift  )

     ROUTINES
     stack_analyze_readroi
     stack_analyze_writeroi
     stack_analyze_gifmovie
     stack_analyze_roi_event,event
     stack_analyze_roi
     stack_analyze_desensitive
     stack_analyze_sensitive
     stack_analyze_graphics
     stack_analyze_bar
     stack_analyze_makespectrum
     stack_analyze_plotspectrum, i_file
     stack_analyze_imgdisp,i_file
     stack_analyze_event,event

     MODIFICATION HISTORY:
     ( 2-may-98 aph) improve filenames and Io read-in
     (20-may-99 aph) - BINARY keyword added to call
     (13-jun-98 aph) correct printed flag on writes
     (14-jun-98 aph) bsif_com
     (30-jun-98 aph) OD determination;
     (6-jul-98 aph) movie buttons, eV_shift, cursor select frame
     (8-Jan-99 aph) hourglass, close,/all to get round no lun problems (movie); path
     (11-Jan-99 aph) symbols - default to none; noYzero; aloadct for IDL 4
     (14-May-99 aph) add TEY-ON/TEY-OFF button for PEEM stacks
     (15-May-99 aph) drop first line
     (19-may-99 aph) REINTRODUCE option to save only image as the movie
     (22-may-99 aph) read-in from binary files enabled (optiona); write to binary
     (08-jun-99 aph) use new version of get_num: group = stack_analyze_par.main_base
     (25-jun-99 aph) add axis_com to put in top_color_index, white_color_index
     (28-jun-99 aph) remove conflict with 'label' and axis_com use of this
     (10-jul-99 aph) add clipping to common area; reverse -ve slope axes; fixe error
     (16-jul-99 aph) remove infinite loop on check for location of files
     (18-jul-99 aph) adapt stack_wb procedure to work with TEY (I/I-t (no log) data (PEEM; TEY-stxm)
     (26-sep-99 aph) remove aloadct (no longer supporting IDL 4.0 operation)
     (27-oct-99 aph) reset (x,y) scales in stack binary writes
     (28-oct-99 aph) no_align keyword added to call
     (28-oct-99 aph) no_align keyword added to call
     (26-jan-00 aph) let sub-flag work independent of OD flag
     (30-mar-00 aph) added group id to get_text
     (09-apr-00 aph) add save image; subtract image; subtract background stack
     (16-apr-00 aph) initial path is DefPath
     (24-apr-00 aph) path picked up at all writes; images (*.nc) allows all to write
     (30-apr-00 aph) image write - allow start number to sync with original file numbers
     (08-may-00 aph) image write - make file numbers be 3 digits; default start with 1; write *.sl
     (10-may-00 aph) stack_binary (*.ncb) default cols/rows eliminate grey;
     (14-may-00 aph) correct filter for image subtraction
     (19-Jul-00 aph) option to update spectrum in movie
     (30-may-01 aph) force energy values to be sorted and increasing
     (11-may-01 aph) if have subtracted spectrum, image or stack,
                     ensure the difference is what is saved as *.ncb, or images etc
     (23-dec-01 aph) start *.nc numbering at 0; remove desensitize of stack "*.ncb" & others
     (28-dec-01 aph) sesnsitize stack (*.ncb); fix first file blank on image (*.nc)
     (06-jan-01 aph) add slicer3; query removal energy sorting !
     (12-may-02 aph) AXIS standard header added
     (25-may-03 aph) fix co-ordinate error if Io read-in;
    					add all-pixels button; add ratio image button
    					improve sensitize / desensitize
     (15-jun-03 aph) add exchange E-scale; delete image
     (10-jul-03 aph) fix problem of wrong DAT file with multiple 'remove images'
     (26-feb-04 aph) add zoom, x,y axis control
     (01-mar-04 aph) fix display of roi (region, pixels) in zoom mode
     (27-mar-04 aph) add (E,I)-range control; avg stack; median added
     (07-apr-04 aph) remove first image;
     (10-apr-04 aph) add remove_zeros; troubleshoot spectral select
     (02-may-04 aph) continue trouble-shooting spectral select problem
     (15-may-04 aph) sensitize path & filename boxes if ROI selected
     (11-jul-04 aph) try to add scroll bars - failed so far !
                   shrink vertical size of commands to fit on 768 vertical screen
     (31-jul-04 aph) replace gif image with png image (gif not supported by IDL6, XP)
     (21-jan-05 aph) exit stack_analyze after writing stack
     (19-feb-05 aph) add 'constant' and 'gain' controls
     (03-jul-05 aph) add 'ratio to spectrum'
     (07-jul-05 aph) change color reset properties when close to avoid problem of B/W inversion in aXis2000
     (15-nov-05 aph)  average images over E-range displayed
     (15-Dec-05 aph) add clip_images
     (18-feb-06 aph) add map
     (21-feb-06 aph) correct extensions when write out *.sl list file
     (08-apr-06 gaj) add write out of all images in tif format
     (19-apr-06 aph) correct row, column minimums for clipping after alignment; auto-zoom
     (21-apr-06 aph) add *.roi as default name for roi region
     (25-apr-06 aph) multiple region display

(See c:\axis2000\stack_analyze-multi.pro)

## STACK_ANALYZE.PRO[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STACK_ANALYZE.PRO

    LAST CHANGED: ----------------------------- 	13-Apr-08  (aph FROM 26-Feb-04)
       CAUTION - lots of updates of regular stack_analayze missed !!

     PURPOSE:
    	This set of procedures and functions is a widget to display
     and extract spectra from stacks.
     This version (derived from from late January 98 version of CJJ) has been
     modifed to handle file names and paths better.
     Read in Io signals from ascii (*.txt) spectral format files (x,y)
     Correct E-scales; normalize yield data; subtract spectra, stacks
     extract images (*.nc format) from stacks.

     CATEGORY:
    	Stack analysis.
     Called from aXis2000 by stacks~stack~analyse~AXIS (or AXIS binary)

     CALLING SEQUENCE:
    	STACK_ANALYZE, [ list_filename, shift_filename, fpath=fpath, binary=binary, $
                       zoom=zoom, text_height=text_height, realign=realign, $
                       help=help, no_align = no_align ]

     INPUTS:
     list_filename		name of file with list of *.nc image files
     shift_filename	name of file with list of x,y pixel shifts for alignment

     KEYWORDS:
     fpath			path for files
     binary		read in as *.ncb binary (all images in one file)
     zoom			zoom factor
     text_height	size of text
     realign		launch stack_align after applying shifs in shift_filename
     help			print help information
     no_align		do not launch stack_align

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks
    	BSIF_COM	common for NetCDF files
    	ANALCOM		common for stack analyze
    	VOLUME_DATA image_stack - 3d array of stack data
    	PIX_SHIFT	set of pixel shifts ( xpix_shift, ypix_shift  )

     ROUTINES
     stack_analyze_readroi
     stack_analyze_writeroi
     stack_analyze_gifmovie
     stack_analyze_roi_event,event
     stack_analyze_roi
     stack_analyze_desensitive
     stack_analyze_sensitive
     stack_analyze_graphics
     stack_analyze_bar
     stack_analyze_makespectrum
     stack_analyze_plotspectrum, i_file
     stack_analyze_imgdisp,i_file
     stack_analyze_event,event

     MODIFICATION HISTORY:
     ( 2-may-98 aph) improve filenames and Io read-in
     (20-may-99 aph) - BINARY keyword added to call
     (13-jun-98 aph) correct printed flag on writes
     (14-jun-98 aph) bsif_com
     (30-jun-98 aph) OD determination;
     (6-jul-98 aph) movie buttons, eV_shift, cursor select frame
     (8-Jan-99 aph) hourglass, close,/all to get round no lun problems (movie); path
     (11-Jan-99 aph) symbols - default to none; noYzero; aloadct for IDL 4
     (14-May-99 aph) add TEY-ON/TEY-OFF button for PEEM stacks
     (15-May-99 aph) drop first line
     (19-may-99 aph) REINTRODUCE option to save only image as the movie
     (22-may-99 aph) read-in from binary files enabled (optiona); write to binary
     (08-jun-99 aph) use new version of get_num: group = stack_analyze_par.main_base
     (25-jun-99 aph) add axis_com to put in top_color_index, white_color_index
     (28-jun-99 aph) remove conflict with 'label' and axis_com use of this
     (10-jul-99 aph) add clipping to common area; reverse -ve slope axes; fixe error
     (16-jul-99 aph) remove infinite loop on check for location of files
     (18-jul-99 aph) adapt stack_wb procedure to work with TEY (I/I-t (no log) data (PEEM; TEY-stxm)
     (26-sep-99 aph) remove aloadct (no longer supporting IDL 4.0 operation)
     (27-oct-99 aph) reset (x,y) scales in stack binary writes
     (28-oct-99 aph) no_align keyword added to call
     (28-oct-99 aph) no_align keyword added to call
     (26-jan-00 aph) let sub-flag work independent of OD flag
     (30-mar-00 aph) added group id to get_text
     (09-apr-00 aph) add save image; subtract image; subtract background stack
     (16-apr-00 aph) initial path is DefPath
     (24-apr-00 aph) path picked up at all writes; images (*.nc) allows all to write
     (30-apr-00 aph) image write - allow start number to sync with original file numbers
     (08-may-00 aph) image write - make file numbers be 3 digits; default start with 1; write *.sl
     (10-may-00 aph) stack_binary (*.ncb) default cols/rows eliminate grey;
     (14-may-00 aph) correct filter for image subtraction
     (19-Jul-00 aph) option to update spectrum in movie
     (30-may-01 aph) force energy values to be sorted and increasing
     (11-may-01 aph) if have subtracted spectrum, image or stack,
                     ensure the difference is what is saved as *.ncb, or images etc
     (23-dec-01 aph) start *.nc numbering at 0; remove desensitize of stack "*.ncb" & others
     (28-dec-01 aph) sesnsitize stack (*.ncb); fix first file blank on image (*.nc)
     (06-jan-01 aph) add slicer3; query removal energy sorting !
     (12-may-02 aph) AXIS standard header added
     (25-may-03 aph) fix co-ordinate error if Io read-in;
    					add all-pixels button; add ratio image button
    					improve sensitize / desensitize
     (15-jun-03 aph) add exchange E-scale; delete image
     (10-jul-03 aph) fix problem of wrong DAT file with multiple 'remove images'
     (26-feb-04 aph) add x,y axis control

     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS
                     over-write warning when writing spectra or images

(See c:\axis2000\stack_analyze-TOF.pro)

## STACK_APPEND

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      STACK_APPEND

    LAST CHANGED: ----------------------------------- 17-sep-08

     PURPOSE:
    	This procedure appends two stacks if they have the same  pixel dimensions

     CATEGORY:
    	stack processing; stand alone operation or from axis2000

     CALLING SEQUENCE:
    	STACK_ADD, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS: 	none

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     stack_process_com
     BSIF_com
     volume_data, image_stack

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (12-Nov-06 aph) first written; modified from stack_add
     (02-mar-08 aph) resolve filename dimension error
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_append.pro)

## STACK_BUILDLIST

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      STACK_BUILDLIST

    LAST CHANGED: ----------------------------------- 17-Sep-08

     PURPOSE:
    	This procedure construts a stack from individual *.nc images (old NSLS format)

     CATEGORY:
    	stack processing;

     CALLING SEQUENCE:
    	STACK_BUILDLIST

     INPUTS: FILENAME

     KEYWORDS: none

     OUTPUTS: 	none

     COMMON BLOCKS:
     BSIF_com
     volume_data, image_stack
     stack_bldlst_common

     SIDE EFFECTS:
    	A window is created/destroyed.

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (17-Sep-08 aph) standard header added

(See c:\axis2000\stack_buildlist.pro)

## STACK_FIT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	  STACK_FIT

    LAST CHANGED: ----------------------------------- 18-Sep-08

    PURPOSE:
    	This procedure selects inputs for fitting the spectrum at each pixel
     in a stack to sum of model spectra
     It uses COMMON blocks to store and transfer data

    CATEGORY:
    	AXIS:  stack analysis (operates stand-alone as well)

    CALLING SEQUENCE:
     for procedures:
    	STACK_FIT(/AXIS,/verbose)

    CALLED FROM AXIS:
    	->Stacks->stack_fit

    INPUTS:
    	All input parameters are obtained through user dialogs.

    KEYWORDS:
    	AXIS - if set, indicates called from AXIS
    	VERBOSE - if set, displays results as generated line-by-line (SLOW!)

    ROUTINES
    	STACK_FIT - main routine to execute stack fit
    	GROOM1 - linear fit to pre-edge values
    	INPUTS to GROOM1
    	spectrum - the input and the result after subtraction of back
    	back     - the constant to be subtracted
    	integral - integrated value in background region
    	zero     - number of points to evaluate constant background

    OUTPUTS:
    	If run from AXIS, the results are placed in AXIS buffers
     buffer 1 - n are the spectra of the n-models to be used in the fit,
                  interpolated to the energy values of the stack.
     buffer 4 - (4+n) are the resulting composition maps for the n components
     buffer 8 - linear term of fit
     buffer 9 - chi-square of the fit
     otherwise display windows are generated as required

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	@stack_process_com
    	Volume_data - STACK
     	@BSIF_COM - nc data

    PROCEDURE:
    	After reading in the stack (*.nc) and the model spectra (*.txt)
     and the names to be used for the output files,
     the spectrum at each pixel is fit to (linear) + SUM{coeff(i)*model spectra(i)}
     The coefficients at each pixel constitute the component map for species i.
     The user can choose to perform a pre-edge subtraction based on the first {m} -data points
     in order to base the analysis on solely the core spectra signal

    MODIFICATION HISTORY:
     ***********
     ORIGINAL kernel of this routine was written by Rick Kneedler
     ***********
     (25-May-99 aph) first developed from Kneedler code
     (19-Jun-99 aph) allow user choice to background subtract image spectra
     (07-jul-99 aph) extend to arbitrary number of components
     (09-sep-99 aph) store all results automatically; correct (x,y) scale stuff
     (20-sep-99 aph) remove linear term; set NaN, Inf to zero; integer col #
     (23-oct-99 aph) force plot of components on store
     ( 7-oct-99 aph) allow assignment of simple names to output files
     (26-nov-99 aph) get rid of error message for text prompt
     (23-Dec-99 aph) correct bad point filter on output component maps
     (27-feb-00 aph) add groupIP to get_text cal; axis standard documentation
     (09-apr-00 aph) change groom.pro to fit a sloped line with feedback
     (19-oct-00 aph) increased max # of components to 8
     (13-nov-00 aph) fixed error for GE 5 component; model data
     (09-jan-01 aph) move groom to run with compile-on-fly
     (12-aug-01 aph) put overwrite checking into file writing procedure
     (14-may-03 aph) use comment line, not filename for prompt for name
    					 par filesaves filenames and labels only
     (28-may-03 aph) fix-up no par; force extension to 'par'; fix up comp_names
     (04-jun-03 aph) use ax_par_save, ax_par_load
     (11-jun-03 aph) fix 1 boo-boo
     (30-dec-03 aph) add ax_sort_mono to force stack E-scale and reference spectral scales to be monotonic
     (20-jan-04 aph) use dialog_message to control residual stack writing
    				  ensure E-value (0.0) added to component maps
     (10-Jun-04 aph) remove pre-edge background subtraction
     (01-feb-05 aph) fix ax_sort_mono to use structure (ricochet change from lox change)
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_fit.pro)

## STACK_MAKE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		STACK_MAKE

    LAST CHANGED: ----------------------------------- 18-Sep-08

     PURPOSE:
    	This procedure generates a stack from the product of an image times a spectrum.
     Typically this would be used to strip out a component from a stack, or for simulations.

     CATEGORY:
    	Stack analysis

     CALLING SEQUENCE:
    	STACK_MAKE, SPEC, IMAGE

     INPUTS:
    	SPEC  - 1-d axis structure which has spectrum of the component
    	IMAGE - 2-d axis structure which has image (typically component map)

     KEYWORDS: none

     OUTPUTS:
    	The stack is saved to disk

     COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks
    	analcom
    	COMMON volume_data, image_stack
    	bsif_com

     MODIFICATION HISTORY:
     (11-apr-00 aph) first version
     (10-nov-00 aph) corrected infor for *.dat file
     (29-jan-01 aph) defined energy array (eV) and filename_ev_msec_list
     (12-may-02 aph) correct header name format
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_make.pro)

## STACK_PROCESS.PRO[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STACK_PROCESS.PRO

    LAST CHANGED: ----------------------------------- 21-Sep-08 (aph)

     PURPOSE:
    	This set of procedures and functions is a widget to display
     and extract spectra from stacks.
     This version (derived from from late January 98 version of CJJ) has been
     modifed to handle file names and paths better.
     Read in Io signals from ascii (*.txt) spectral format files (x,y)
     Correct E-scales; normalize yield data; subtract spectra, stacks
     extract images (*.nc format) from stacks
     RENAMED 17-Sep-08 (old name: stack_analyze - conflicted with CJJ).

     CATEGORY:
    	Stack analysis.
     Called from aXis2000 by stacks~analyse~AXIS or stacks~analyse~AXIS binary

     CALLING SEQUENCE:
    	STACK_PROCESS, [ list_filename, shift_filename, fpath=fpath, binary=binary, $
                       zoom=zoom, text_height=text_height, realign=realign, $
                       help=help, no_align = no_align ]

     INPUTS:
     list_filename		name of file with list of *.nc image files
     shift_filename	name of file with list of x,y pixel shifts for alignment

     KEYWORDS:
     fpath			path for files
     binary		read in as *.ncb binary (all images in one file)
     zoom			zoom factor
     text_height	size of text
     realign		launch stack_align after applying shifs in shift_filename
     help			print help information
     no_align		do not launch stack_align

     COMMON BLOCKS:
    	AXIS_COM	       standard set of common blocks
    	BSIF_COM	       common for NetCDF files
    	STACK_PROCESS_COM  common for stack process
    	VOLUME_DATA        image_stack - 3d array of stack data
    	PIX_SHIFT	       set of pixel shifts ( xpix_shift, ypix_shift  )

     ROUTINES
     stack_analyze_readroi
     stack_analyze_writeroi
     stack_analyze_gifmovie
     stack_analyze_roi_event,event
     stack_analyze_roi
     stack_analyze_desensitive
     stack_analyze_sensitive
     stack_analyze_graphics
     stack_analyze_bar
     stack_analyze_makespectrum
     stack_analyze_plotspectrum, i_file
     stack_analyze_imgdisp,i_file
     stack_analyze_event,event
     stack_analyze_maximg

     MODIFICATION HISTORY:
     ( 2-may-98 aph) improve filenames and Io read-in
     (20-may-99 aph) - BINARY keyword added to call
     (13-jun-98 aph) correct printed flag on writes
     (14-jun-98 aph) bsif_com
     (30-jun-98 aph) OD determination;
     (6-jul-98 aph) movie buttons, eV_shift, cursor select frame
     (8-Jan-99 aph) hourglass, close,/all to get round no lun problems (movie); path
     (11-Jan-99 aph) symbols - default to none; noYzero; aloadct for IDL 4
     (14-May-99 aph) add TEY-ON/TEY-OFF button for PEEM stacks
     (15-May-99 aph) drop first line
     (19-may-99 aph) REINTRODUCE option to save only image as the movie
     (22-may-99 aph) read-in from binary files enabled (optiona); write to binary
     (08-jun-99 aph) use new version of get_num: group = stack_analyze_par.main_base
     (25-jun-99 aph) add axis_com to put in top_color_index, white_color_index
     (28-jun-99 aph) remove conflict with 'label' and axis_com use of this
     (10-jul-99 aph) add clipping to common area; reverse -ve slope axes; fixe error
     (16-jul-99 aph) remove infinite loop on check for location of files
     (18-jul-99 aph) adapt stack_wb procedure to work with TEY (I/I-t (no log) data (PEEM; TEY-stxm)
     (26-sep-99 aph) remove aloadct (no longer supporting IDL 4.0 operation)
     (27-oct-99 aph) reset (x,y) scales in stack binary writes
     (28-oct-99 aph) no_align keyword added to call
     (28-oct-99 aph) no_align keyword added to call
     (26-jan-00 aph) let sub-flag work independent of OD flag
     (30-mar-00 aph) added group id to get_text
     (09-apr-00 aph) add save image; subtract image; subtract background stack
     (16-apr-00 aph) initial path is DefPath
     (24-apr-00 aph) path picked up at all writes; images (*.nc) allows all to write
     (30-apr-00 aph) image write - allow start number to sync with original file numbers
     (08-may-00 aph) image write - make file numbers be 3 digits; default start with 1; write *.sl
     (10-may-00 aph) stack_binary (*.ncb) default cols/rows eliminate grey;
     (14-may-00 aph) correct filter for image subtraction
     (19-Jul-00 aph) option to update spectrum in movie
     (30-may-01 aph) force energy values to be sorted and increasing
     (11-may-01 aph) if have subtracted spectrum, image or stack,
                     ensure the difference is what is saved as *.ncb, or images etc
     (23-dec-01 aph) start *.nc numbering at 0; remove desensitize of stack "*.ncb" & others
     (28-dec-01 aph) sesnsitize stack (*.ncb); fix first file blank on image (*.nc)
     (06-jan-01 aph) add slicer3; query removal energy sorting !
     (12-may-02 aph) AXIS standard header added
     (25-may-03 aph) fix co-ordinate error if Io read-in;
    					add all-pixels button; add ratio image button
    					improve sensitize / desensitize
     (15-jun-03 aph) add exchange E-scale; delete image
     (10-jul-03 aph) fix problem of wrong DAT file with multiple 'remove images'
     (26-feb-04 aph) add zoom, x,y axis control
     (01-mar-04 aph) fix display of roi (region, pixels) in zoom mode
     (27-mar-04 aph) add (E,I)-range control; avg stack; median added
     (07-apr-04 aph) remove first image;
     (10-apr-04 aph) add remove_zeros; troubleshoot spectral select
     (02-may-04 aph) continue trouble-shooting spectral select problem
     (15-may-04 aph) sensitize path & filename boxes if ROI selected
     (11-jul-04 aph) try to add scroll bars - failed so far !
                   shrink vertical size of commands to fit on 768 vertical screen
     (31-jul-04 aph) replace gif image with png image (gif not supported by IDL6, XP)
     (21-jan-05 aph) exit stack_analyze after writing stack
     (19-feb-05 aph) add 'constant' and 'gain' controls
     (03-jul-05 aph) add 'ratio to spectrum'
     (07-jul-05 aph) change color reset properties when close to avoid problem of B/W inversion in aXis2000
     (15-nov-05 aph)  average images over E-range displayed
     (15-Dec-05 aph) add clip_images
     (18-feb-06 aph) add map
     (21-feb-06 aph) correct extensions when write out *.sl list file
     (08-apr-06 gaj) add write out of all images in tif format
     (19-apr-06 aph) correct row, column minimums for clipping after alignment; auto-zoom
     (21-apr-06 aph) add *.roi as default name for roi region
     (31-may-06 jso) adapt Readroi to read *.png type ROI files from Lox stacks
     (10-jun-06 aph) integrate Jacob's alternate Lox ROI, using *.png images
     (07-jul-06 rec) add stack_analyze_maximg
     (22-Sep-06 aph) correct multi-image write out to get *.sl file
     (22-Sep-06 aph) cosmetic changes
     (12-Nov-06 aph) correct multi-image write out to get *.sl file (again)
                     put energy sort into binary read; add ratio to constant (gain)
     (11-jan-07 aph) multiply constant, image
     (26-feb-07 aph) replaced direct use of interpolate with ax_mesh to get subtraction of spectra correct
     (17-jul-07 aph) optimize read-in from memory rather than disk; leave widget on top
     (17-Sep-07 aph) do remove_zeros image-by-image
     (29-Dec-07 aph) correct name in header; leave widget on top - TRY #2
     (03-Mar-08 MJ)  keyword /SCROLL in widget_base() needs X_SCROLL_SIZE
     (21-mar-08 aph) fix up stack_analyze subtract stack (missing read-in !!); merged MJ version
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS
                     over-write warning when writing spectra or images
     (17-sep-08 aph) convert name from stack_analyze to stack_process; change analcom to stack_process_com
     (21-sep-08 aph) add ability to revert to tranmsission, given the Io signal

(See c:\axis2000\stack_process-21sep08.pro)

## STACK_PROCESS.PRO[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STACK_PROCESS.PRO

    LAST CHANGED: ----------------------------------- 19-Dec-08 (aph)

     PURPOSE:
    	This set of procedures and functions is a widget to display
     and extract spectra from stacks.
     This version (derived from from late January 98 version of CJJ) has been
     modifed to handle file names and paths better.
     Read in Io signals from ascii (*.txt) spectral format files (x,y)
     Correct E-scales; normalize yield data; subtract spectra, stacks
     extract images (*.nc format) from stacks
     RENAMED 17-Sep-08 (old name: stack_analyze - conflicted with CJJ).

     CATEGORY:
    	Stack analysis.
     Called from aXis2000 by stacks~analyse~AXIS or stacks~analyse~AXIS binary

     CALLING SEQUENCE:
    	STACK_PROCESS, [ list_filename, shift_filename, fpath=fpath, binary=binary, $
                       zoom=zoom, text_height=text_height, realign=realign, $
                       help=help, no_align = no_align ]

     INPUTS:
     list_filename		name of file with list of *.nc image files
     shift_filename	name of file with list of x,y pixel shifts for alignment

     KEYWORDS:
     fpath			path for files
     binary		read in as *.ncb binary (all images in one file)
     zoom			zoom factor
     text_height	size of text
     realign		launch stack_align after applying shifs in shift_filename
     help			print help information
     no_align		do not launch stack_align

     COMMON BLOCKS:
    	AXIS_COM	       standard set of common blocks
    	BSIF_COM	       common for NetCDF files
    	STACK_PROCESS_COM  common for stack process
    	VOLUME_DATA        image_stack - 3d array of stack data
    	PIX_SHIFT	       set of pixel shifts ( xpix_shift, ypix_shift  )

     ROUTINES
     stack_analyze_readroi
     stack_analyze_writeroi
     stack_analyze_gifmovie
     stack_analyze_roi_event,event
     stack_analyze_roi
     stack_analyze_desensitive
     stack_analyze_sensitive
     stack_analyze_graphics
     stack_analyze_bar
     stack_analyze_makespectrum
     stack_analyze_plotspectrum, i_file
     stack_analyze_imgdisp,i_file
     stack_analyze_event,event
     stack_analyze_maximg

     MODIFICATION HISTORY:
     ( 2-may-98 aph) improve filenames and Io read-in
     (20-may-99 aph) - BINARY keyword added to call
     (13-jun-98 aph) correct printed flag on writes
     (14-jun-98 aph) bsif_com
     (30-jun-98 aph) OD determination;
     (6-jul-98 aph) movie buttons, eV_shift, cursor select frame
     (8-Jan-99 aph) hourglass, close,/all to get round no lun problems (movie); path
     (11-Jan-99 aph) symbols - default to none; noYzero; aloadct for IDL 4
     (14-May-99 aph) add TEY-ON/TEY-OFF button for PEEM stacks
     (15-May-99 aph) drop first line
     (19-may-99 aph) REINTRODUCE option to save only image as the movie
     (22-may-99 aph) read-in from binary files enabled (optiona); write to binary
     (08-jun-99 aph) use new version of get_num: group = stack_analyze_par.main_base
     (25-jun-99 aph) add axis_com to put in top_color_index, white_color_index
     (28-jun-99 aph) remove conflict with 'label' and axis_com use of this
     (10-jul-99 aph) add clipping to common area; reverse -ve slope axes; fixe error
     (16-jul-99 aph) remove infinite loop on check for location of files
     (18-jul-99 aph) adapt stack_wb procedure to work with TEY (I/I-t (no log) data (PEEM; TEY-stxm)
     (26-sep-99 aph) remove aloadct (no longer supporting IDL 4.0 operation)
     (27-oct-99 aph) reset (x,y) scales in stack binary writes
     (28-oct-99 aph) no_align keyword added to call
     (28-oct-99 aph) no_align keyword added to call
     (26-jan-00 aph) let sub-flag work independent of OD flag
     (30-mar-00 aph) added group id to get_text
     (09-apr-00 aph) add save image; subtract image; subtract background stack
     (16-apr-00 aph) initial path is DefPath
     (24-apr-00 aph) path picked up at all writes; images (*.nc) allows all to write
     (30-apr-00 aph) image write - allow start number to sync with original file numbers
     (08-may-00 aph) image write - make file numbers be 3 digits; default start with 1; write *.sl
     (10-may-00 aph) stack_binary (*.ncb) default cols/rows eliminate grey;
     (14-may-00 aph) correct filter for image subtraction
     (19-Jul-00 aph) option to update spectrum in movie
     (30-may-01 aph) force energy values to be sorted and increasing
     (11-may-01 aph) if have subtracted spectrum, image or stack,
                     ensure the difference is what is saved as *.ncb, or images etc
     (23-dec-01 aph) start *.nc numbering at 0; remove desensitize of stack "*.ncb" & others
     (28-dec-01 aph) sesnsitize stack (*.ncb); fix first file blank on image (*.nc)
     (06-jan-01 aph) add slicer3; query removal energy sorting !
     (12-may-02 aph) AXIS standard header added
     (25-may-03 aph) fix co-ordinate error if Io read-in;
    					add all-pixels button; add ratio image button
    					improve sensitize / desensitize
     (15-jun-03 aph) add exchange E-scale; delete image
     (10-jul-03 aph) fix problem of wrong DAT file with multiple 'remove images'
     (26-feb-04 aph) add zoom, x,y axis control
     (01-mar-04 aph) fix display of roi (region, pixels) in zoom mode
     (27-mar-04 aph) add (E,I)-range control; avg stack; median added
     (07-apr-04 aph) remove first image;
     (10-apr-04 aph) add remove_zeros; troubleshoot spectral select
     (02-may-04 aph) continue trouble-shooting spectral select problem
     (15-may-04 aph) sensitize path & filename boxes if ROI selected
     (11-jul-04 aph) try to add scroll bars - failed so far !
                   shrink vertical size of commands to fit on 768 vertical screen
     (31-jul-04 aph) replace gif image with png image (gif not supported by IDL6, XP)
     (21-jan-05 aph) exit stack_analyze after writing stack
     (19-feb-05 aph) add 'constant' and 'gain' controls
     (03-jul-05 aph) add 'ratio to spectrum'
     (07-jul-05 aph) change color reset properties when close to avoid problem of B/W inversion in aXis2000
     (15-nov-05 aph)  average images over E-range displayed
     (15-Dec-05 aph) add clip_images
     (18-feb-06 aph) add map
     (21-feb-06 aph) correct extensions when write out *.sl list file
     (08-apr-06 gaj) add write out of all images in tif format
     (19-apr-06 aph) correct row, column minimums for clipping after alignment; auto-zoom
     (21-apr-06 aph) add *.roi as default name for roi region
     (31-may-06 jso) adapt Readroi to read *.png type ROI files from Lox stacks
     (10-jun-06 aph) integrate Jacob's alternate Lox ROI, using *.png images
     (07-jul-06 rec) add stack_analyze_maximg
     (22-Sep-06 aph) correct multi-image write out to get *.sl file
     (22-Sep-06 aph) cosmetic changes
     (12-Nov-06 aph) correct multi-image write out to get *.sl file (again)
                     put energy sort into binary read; add ratio to constant (gain)
     (11-jan-07 aph) multiply constant, image
     (26-feb-07 aph) replaced direct use of interpolate with ax_mesh to get subtraction of spectra correct
     (17-jul-07 aph) optimize read-in from memory rather than disk; leave widget on top
     (17-Sep-07 aph) do remove_zeros image-by-image
     (29-Dec-07 aph) correct name in header; leave widget on top - TRY #2
     (03-Mar-08 MJ)  keyword /SCROLL in widget_base() needs X_SCROLL_SIZE
     (21-mar-08 aph) fix up stack_analyze subtract stack (missing read-in !!); merged MJ version
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS
                     over-write warning when writing spectra or images
     (17-sep-08 aph) convert name from stack_analyze to stack_process; change analcom to stack_process_com
     (21-sep-08 aph) add ability to revert to tranmsission, given the Io signal
     (22-Nov-08 aph) add file overwrite check to saving spectra & make it work
     (19-Dec-08 aph) write out only images in range of E displayed (shrink stacks)

(See c:\axis2000\stack_process.pro)

## STACK_PROCESS_COM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STACK_PROCESS_COM

    LAST CHANGED: ----------------------------------- 17-sep-08

     PURPOSE:
    	This FILE contains the COMMON block, stack_process_common

     CATEGORY:
    	AXIS: Stack_analyze common block

     CALLING SEQUENCE:
    	@stack_process_com (to include in the stack_process (axis2000 version of stack_analyze) routines)

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     DETAILS: - variables in the common block:
       plot_cols, plot_rows: size of plot region in pixels
       char_ypix: height of a character in pixels
       charsize: scaling to have characters come out at char_ypix height
       textregion_ypix: height of text plus scalebar region below image
       textregion_nlines: number of lines to text plus scalebar region
       r,g,b: color vectors for 8 bit display
       i_color_index, i0_color_index: color indices for I and I0 respectively
       top_color_index: full white
    	disp_xmin, disp_xmax, disp_ymin, disp_ymax

     MODOFICATIONS
     (16-apr-98 aph) - added filepath, filesave to common !!
      filename_header = filepath + sep + filesave,
                      where sep is system specific separator
                      and parameters related to Io readin
     (30-jun-98 aph) - added OD_flag, rescale_flag,stop_flag
     ( 6-jul-98 aph) - moviestate, framenum, framerate:  for movies
     ( 6-jul-98 aph) - spectrum_x_scale, spectrum_y_scale: to allow cursor selection of image
     ( 6-jul-98 aph) - filename_ev_msec_list: to update E-scales
     ( 7-jul-98 aph) - sub_flag, ref_spectrum: to allow subtraction of ref. spectrum
     (14-may-99 aph) - tey_flag to prevent logarithm
     (25-jun-99 aph) - remove xx_color_index (in axis_com, part of ax_color)
     (29-jun-99 aph) - put color_index items back; axis_colr_common kept separate
     (31-dec-99 aph) - standard documentation
     (09-apr-00 aph) - add stack_analyze_par.sub_image, stack_analyze_par.sub_stack
     (08-may-00 aph) - add xpix_shift, ypix_shift - 2d arrays with mon/max shifts - separate common
     (22-feb-04 aph) - add disp_xmin, disp_xmax, disp_ymin, disp_ymax, ixl, ixh, iyl, iyh
     (26-mar-04 aph) - add disp_emin, disp_emax
     (02-may-04 aph) - add sa_debug
     (18-feb-06 aph) - add peak_img, bgnd_1, etc for mapping
     (23-apr-06 aph) - multi-region plotting - n_roi, i_roi becomes 2d
     (18-mar-07 aph) - add limits (for fitting stacks)
     (17-Sep-08 aph) - change name to stack_process_com to differentiate
                        from similar common block in jacobsen's stack_analyze

(See c:\axis2000\stack_process_com.pro)

## STACK_RB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      STACK_RB

    LAST CHANGED: ----------------------------------- 18-Sep-08

     PURPOSE:
    	This procedure reads in a whole stack (3d (E,x,y) array) from binary
     places data into image_stack (Common volume_data)
     Re-Scales data to restore a factor used to avoind integer loss of detail

     CATEGORY:
    	stack processing; stand alone operation

     CALLING SEQUENCE:
    	STACK_RB, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS: 	none

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     stack_process_com
     BSIF_com
     volume_data, image_stack

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (22-may-99 aph) first version
     (08-jun-99 aph) add group ID to get_num calls
     (06-jul-99 aph) free_lun !; reverses image_stack for -ve axes
     (27-oct-99 aph) print scale factor; preserve (x,y) axes
     (28-feb-02 aph) AXIS standard header added
     (02-may-04 aph) error recovery if file name error; fix header
     (19-feb-05 aph) close *.dat file to release it !
     (10-nov-06 aph) use axis_log
     (25-dec-07 aph) correct header
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_rb.pro)

## STACK_READLIST

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		STACK_READLIST

    LAST CHANGED: ----------------------------------- 	21-Feb-06

     PURPOSE:
    	This procedure reads in a stack
     set of files from a pre-made list (*.sl) or a listing of files of a specific type

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	STACK_READLIST, list_filename, filename_list

     INPUTS:
     list_filename	input list
     filename_list	output list

     KEYWORDS:  NONE

     OUTPUTS:
    filename_list

     COMMON BLOCKS: NONE

     MODIFICATION HISTORY:
     (10-aug-99 aph) revised to read either zimba or jacobsen format "*.sl" files
     (16-oct-99 aph) set up to handle *sl files with incorrect path information
     (21-feb-06 aph) AXIS standard header added

(See c:\axis2000\stack_readlist.pro)

## STACK_WB

[Previous Routine] [Next Routine] [List of Routines]

    NAME: STACK_WB

    LAST CHANGED: ----------------------------------- 17-Sep-08

     PURPOSE:
    	This procedure writes  a whole stack (3d (E,x,y) array) to a binary file
     with associated *.dat file to track paramaters
     assumes Common volume_data, image_stack exists and contains the data
     Scales data to within 1000 and 10000 of above 3e4 or below 1e3
     scale factor is stored, and reinstalled when using STACK_rb.pro

     CATEGORY:
    	stack processing; stand alone operation

     CALLING SEQUENCE:
    	WRITE_WB, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS:
    	*.ncb file

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     STACK_PROCESS_COM
     BSIF_COM
     volume_data, image_stack

     SIDE EFFECTS:

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (22-may-99 aph) first version
     (09-sep-99 aph) (x,y) scale reset to account for dimensions on nsls data
     (26-sep-99 aph) clean up name
     (27-oct-99 aph) leave (x,y) axes in original dimensions
     (28-feb-02 aph) adapt to handle 1-image stacks; AXIS standard header added
     (04-jun-04 aph) add free_lun; get to write more than 8-character filenames in list
     (17-Jun-05 aph) warning & switch re Unix format; print => axis_log
     (17-Sep-08 aph) replace analcom with stack_process_com

(See c:\axis2000\stack_wb.pro)

## STAG

[Previous Routine] [Next Routine] [List of Routines]

    2D Sructure procedures for Microscopy images
    Current Structure format:
       s = {D:data, X:xarr, Y:yarr, XL:xlabel, YL:ylabel, DL:title}

      fct STAG, s, tag(s)	-- checks existence of structure field(s)

     (11-nov-00 cgz) migrated from STRUCTURE.PRO

(See c:\axis2000\stag.pro)

## STRING2FILE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           STRING2FILE

     PURPOSE:
           This procedure writes the contents of a string array to a text
           file, one element per line.

     CATEGORY:
           Input / Output

     CALLING SEQUENCE:
           STRING2FILE, In_string, Filename

     INPUTS:
           In_string: The string array to write to the file.

           Filename:  The name of the text file to receive the string data.

     KEYWORD PARAMETERS:
           APPEND:    If set, and if the output file exists, the data is appended
                      to the output file. By default, the output file is
                      overwritten.

     OUTPUTS:
           None

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           May, 1997

(See c:\axis2000\string2file.pro)

## STRUCTURE

[Previous Routine] [Next Routine] [List of Routines]

    2D Sructure procedures for Microscopy images
    Current Structure format:
       s = {D:data, X:xarr, Y:yarr, XL:xlabel, YL:ylabel, DL:title}

      pro SETORIGIN, s [, x0, y0, /CENTER, /CORNER, /PLOT]
           -- reset origin of x & y axes;
              prompts for cursor input if location not specified
      pro SETSCALE, s [, opt,  /CENTER, /PLOT]
          -- reset x & y scale to image (assumes dx=dy) according to:
             WIDTH=width;   INCR=increment;  or
             LINE=length (place arbitrary line with cursors)
      fct SPROFILE, s		-- extract line profile from image structure
      fct SPROFILES, s [,opt]	-- interactive XYPROFILES
      fct SCROP, s [, xrange, yrange]
          -- crop image using box_cursor unless
             xrange=[x0,x1] and yrange=[y0,y1] are specified
      fct STAG, s, tag(s)	-- checks existence of structure field(s)
     -- Misc --
      fct ARR2STRUC, arr		-- convert 2D array to structure
      fct SCHECK, s
      fct SINTERP, s, xx, yy, MISSING=ms
         -- interpolate 2D structure to new X and Y arrays
      fct SCUTOUT, s, [x0,x1], [y0,y1], INC=inc, , _extra=e
         -- interpolate 2D structure to new X and Y ranges [min,max]
          default: uses original increment unless new INC specified
      pro CVTUNIT, s, TO='newunit'

      pro SUBST, s, new, /X, /Y, /UNIT 	-- substitute new item into structure
      fct SMOD, s, new, /X, /Y, /UNIT
      pro SSAVE, file, s		-- save 1D structure as columns in text file

     (11-nov-00 cgz)
    	NOTE : Nothing other than STAG is used in AXIS.
    		Created STAG.PRO.  STRUCTURE.PRO is obsolete and can be eliminated

(See c:\axis2000\structure.pro)

## STR_COLUMNS

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           STR_COLUMNS

     PURPOSE:
           This procedure takes a string array containing rows of text, and
           divides it into a 2-D array with each row divided into columns.

     CATEGORY:
           String processing.

     CALLING SEQUENCE:
           STR_COLUMNS, Input

     INPUTS:
           Input:     A 1-D string array. Each element is a row of text containing
                      columns of text separated by a delimiter. Each row must
                      have the same number of column elements. The input array
                      will be overwritten by the resulting 2-D string array.

     KEYWORD PARAMETERS:
           DELIMITER: A string containing the delimiter between columns. The
                      default delimiter is white space between columns. See
                      the documentation for SPLIT_STRING for details.

     OUTPUTS:
           The input parameter is overwritten with the output.

     ROUTINES USED BY THIS MODULE:
           SPLIT_STRING             (Bill Loo's IDL routine)

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           December, 1997

(See c:\axis2000\str_columns.pro)

## STXM4_NCB

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	STXM4_NCB

    LAST CHANGED: ----------------------------------- 30-sep-01

     PURPOSE:
    	This procedure converts a series of NSLS STXM IV image files
     into a binary stack file. The STXM IV files are those listed in a '*.sl' file

     CATEGORY:
    	AXIS: stack analysis

     CALLING SEQUENCE:
    	RESULT = STXM4_NCM(group_leader=axis_ID)

     INPUTS:
    	none

     KEYWORD PARAMETERS:
    	GROUP_LEADER - identification of caller for modal control

     OUTPUTS:
      FILE.NCB - stack binary file

     COMMON BLOCKS:
       @AXIS_COM - set of common blocks for AXIS

     SIDE EFFECTS:
    	many !

     RESTRICTIONS:
    	caveat emptor

     MODIFICATION HISTORY:
     (30-sep-01 aph) first developed

(See c:\axis2000\stxm4_ncb.pro)

## SXM_ACOMMON

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_ACOMMON.PRO
     It defines additional common blocks besides SXM_COMMON

(See c:\axis2000\sxm_acommon.pro)

## SXM_COMMON

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_COMMON.PRO
     It defines the common block SXM_COMMON, which
     just holds the stuff saved to file (should be known
     to the world).  There's also SXM_ACOMMON.PRO for more stuff.

(See c:\axis2000\sxm_common.pro)

## SXM_FILEEXISTS

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_FILEEXISTS
     It holds FUNCTION SXM_FILEEXISTS
     Returns 1 if the file exists, 0 otherwise.
     Need this because findfile() is broken on sxm at this moment...

(See c:\axis2000\sxm_fileexists.pro)

## SXM_IPAR

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_IPAR.PRO
     It sets up the data structure sxm_par

(See c:\axis2000\sxm_ipar.pro)

## SXM_READFILE

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_READFILE.PRO
     It holds FUNCTION SXM_READFILE
     Reads in a file in netCDF format.  It returns 0 on error,
     and 1 on success.

     Modified 04-APR-1998 to read in "now_nm"!!!

(See c:\axis2000\sxm_readfile.pro)

## SXM_STRCLEAN

[Previous Routine] [Next Routine] [List of Routines]

     This is the file SXM_STRCLEAN.PRO
     It holds FUNCTION SXM_STRCLEAN

(See c:\axis2000\sxm_strclean.pro)

## TEXT_READ.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	TEXT_READ.PRO

    LAST CHANGED: ----------------------------------- 11-nov-00

    PURPOSE:
    	TEXT_READ - multi-block file read-in

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = text_READ(FILNENAME)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function TEXT_READ, FNAME, block=b, blkInfo=bi
    	reads the bth block (starting from zero) in the file
     and returns the contents as a matrix
     KEYWORDS:
    	BLOCK - block number to read
    	BLKINFO - string array for header information for block

    COMMON BLOCKS: none

(See c:\axis2000\text_read.pro)

## TEXT_READ1.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	TEXT_READ1.PRO

    LAST CHANGED: ----------------------------------- 11-nov-00

    PURPOSE:
    	TEXT_READ1 - simple text file read-in (single block)

    CATEGORY:
    	STAND ALONE: utilities

    CALLING SEQUENCE:
    	Result = text_READ1(FILNENAME)

    CALLED FROM AXIS:
    	many procedures

    ROUTINES
    	function 	TEXT_READ1, FNAME, print=print
     reads simple text files consisting of 1 block plus a header
     KEYWORDS
    	PRINT - if set, then print header information

    COMMON BLOCKS: none

(See c:\axis2000\text_read1.pro)

## THUMBLBLS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	THUMBLBLS

    LAST CHANGED: ----------------------------------- 19-dec-00

    PURPOSE:
    	This set of three procedures (ThumbLbls, BLbl_upd, Thumb_plot)
     display the thumbnail sketches used for buffer identification

    CATEGORY:
    	AXIS:  utility (captive)

    CALLING SEQUENCE:
    	ThumbLbls, /ALL

    CALLED FROM AXIS:
    	whenever execute PlotBuf to display a new Buffer; clear; etc

    ROUTINES
    	BLBL_UPD  - update the labels (which displayed for multi, lable contents)
    	ThumbLbls, ALL = ALL  - display the current (CurBuf) or all 9 independent
    	    data buffers. Keyword ALL forces all 9 buffers to be re-displayed
    	  ThumbPlot,BufNum - replot Thumbnail for BufNum

    INPUTS:
    	BUFNUM (ThumbPlot) - number of buffer to update thumbnail

    KEYWORDS:
    	ALL (ThumbLbls) - force all 9 to be redsiplayed

    OUTPUTS:
    	revised AXIS display

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (   MAR-98 APH) split from axis_c to shrink file
     (14-jun-98 aph) axis_com
     (24-jun-99 aph) consistent color for image/spectra ; ADD zstack_color_common
     (26-jul-99 aph) if curBuf=0, only update labels
     (26-sep-99 aph) separated from THUMBS.PRO to have file name = run name
                    adapted to 9 separate windows
     (31-jan-00 aph) AXIS standard documentation; re-ordered to avoid loss of utility routines
     (11-mar-00 aph) remove comment on @axis_com line
     (16-apr-00 aph) handle 3d images which have 3-channel (3-d) data structure
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index

(See c:\axis2000\thumblbls.pro)

## THUMBZOOM

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	THUMBZOOM

    LAST CHANGED: ----------------------------------- 19-dec-00

    PURPOSE:
    	This procedure plots 4 or 9 buffers in the main image of AXIS

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE:
    	ThumbZoom [, NUM=num , BufChoice=Buf4, color=color, all_scale=all_scale]

    CALLED FROM AXIS:
    	->Zoom->Thumbnails->{4->{B/W,color},9->{B/W,color}}

    INPUTS:
    	All input parameters are passed as keywords or by AXIS_COM.

    KEYWORDS:
    	NUM = 4 - display four user-selected buffers ( =9 - all buffers)
    	BUFCHOICE - indices of the selected buffers
    	COLOR - display images with current color table, spectra with AXIS_COLORS
    	ALL_SCALE - scale images by min/max of all displayed images

    OUTPUTS:
    	The composite image is generated as an AXIS 2d structure in bufer = 10.
     All image options should execute on this composite image
     USE COPY to write multi-image display to a single buffer

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    MODIFICATION HISTORY:
     (xx-MAR-98 aph) split from axis_c
     (14-jun-98 aph) axis_com
     (24-jun-99 aph) go for consistent color !
     (29-jun-99 aph) correct name for axis_color_common variables
     (10-jul-99 aph) add B/W or color option to assist printing
     (26-sep-99 aph) split from Thumbs.pro to have filename = pro name
     (01-Jan-00 aph) generate mega-image for lineouts
     (01-jan-00 aph) AXIS standard documentation
     (30-nov-00 cgz) Replaced call of wdivide with explicit !p.multi statement
    			Replaced IF NUM EQ # staements with CASE structure
     (19-dec-00 cgz) substituted ax_white_color_index with ax_plot_axes_color_index
    			substituted ax_black_color_index with ax_plot_bkgd_color_index

(See c:\axis2000\thumbzoom.pro)

## TIF2NCDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	TIF2NCDF

    LAST CHANGED: ----------------------------------- 12-may-02

     PURPOSE:
    	This procedure converts one or a series of tif-format images
     into netCDF format FILES (nsls 'OLD' *.NC) using tifrd_im.pro
     Works for ALS PEEM-2 (12-bit and 16-bit via rd_peem.pro)
     and SRC Elmitech (De Stasio) 16-bit tif file formats
     optional binning, E-calibrate, dark-correction (using multiple files), gain-correction.
     Area of interest files from PEEM-2 camera can be used to select regions from
     full scale images (not working as of jul-01)

     CATEGORY:
    	Image readin
     called from stacks~convert format~TIF to netCDF~1 / many / file

     CALLING SEQUENCE:
    	TIF2NCDF [, file, list=list, bin=bin, outlist = outlist, $
                 delE=delE, fltr = fltr, delC=delC]

     INPUTS:
     	FILE	path&name of tif file - optional

     KEYWORDS:
    	LIST	name of file with list of set of names of {path&file} (*.lst format)
    	BIN		average pixels in bocks of n (bin = 2 cuts size x4; bin=3 by 9 etc)
    	OUTLIST	name of stack list file (*.sl) to write list of files for later analysis
    	AOI		[x0, y0, x1, y1] defining region of interest
    	delE	shift in energy scale (linear re-calibration)
    	fltr	allow call line selection of filter (default = '*.tif')
    	delC	constant background to apply to all pixels

     OUTPUTS:
    	file as path+name+'.nc' written for each input file or list element

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     SIDE EFFECTS:

     PROCEDURE:
     PEEM-2 and Elmitech formats are differentiated by
     convention in PEEM-2 of including a # to seperate sample name from sequence number
     The image and associated information are put into
     BSIF_COMMON variables:
       image_data (the array which holds the image - possible several
    		planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title

     MODIFICATION HISTORY:
     (13-May-99 aph) adapted from als2ncdf
     (08-jun-99 aph) add group to get_num calls
     (15-jun-99 aph) generalise to handle lists with no path or defective path
     (17-jul-99 aph) provision for dark count subtraction
     (18-jul-99 aph) improved checking for correct filenames (Get_path modified)
     (26-mar-00 aph) correct read in of ALS PEEM lists
     (24-oct-00 aph) option to use 12-bit or 16-bit PEEM data
     (03-oct-01 aph) allow subtraction of constant if needed (Mephisto PEEM)
     (30-mar-01 aph) set up for Elmitech stacks; bypass filename sorting
    				  default bgnd - 32768; different E read
     (19-apr-01 aph) changed sl format to match zimba (path/names)
     (22-apr-01 aph) AXIS standard header added; force extensions
     (08-may-01 aph) implement dark image for background correction; implement AOI
     (14-jul-01 aph) add option to subtract dark file (or a sum) from each image
     (31-jul-01 aph) add axis keyword to RD_PEEM call and to call to this routine
     (12-may-02 aph) correct invalid name format in header.

(See c:\axis2000\tif2ncdf.pro)

## TIFRD_IM

[Previous Routine] [Next Routine] [List of Routines]

    NAME: FILENAME_IN_CAPITALS

    LAST CHANGED: ----------------------------------- 31-jul-01

     PURPOSE:
    	This procedure reads a tif image file (*.tif) using RD_PEEM  and converts it to
     NetCDF format. This is used to process *.tif to *.nc files for use in stack_analyze

     CATEGORY:
    	Image format conversion.

     CALLING SEQUENCE:
     for procedures:
    	TIFRD_IM, [file, bin=bin, Energy=energy, white=white, CCD_bgnd=CCD_bgnd, $
            smth = smth, bits12 = bits12, region = region, scale=scale, $
    		 help=help, _extra=e]

     INPUTS:
    	FILE 	name of file to convert (user prompted if not supplied)

     KEYWORDS:
    	BIN		paramater for binning
    	BITS12 	if set to 12 this uses the 12-bit read routine in RD_PEEM
    	ENERGY	sets energy of PEEM image
    	CCD_bgnd CCD background image or average value that is subtracted
    	SCALE 	pixel size in microns
    	SMTH 	if set, applies a 3-point median smooth
    	WHITE 	if set, divides the image by an image in file white
               (response of CCD to uniform illumination)
    	AOI 	area of interest, defined by box, [x0,x1, y0, y1] acquired by PEEM-2
    			used to extract su-image from dark and white files
    	REGION 	a 4-number vector [x_start, x_stop, y_start, y_stop]
    			defining the region of the image to be selected
    			(if scale set, in real space units. Otherwise, in pixels)
    	NOFILTER if set, then pickfile dialog does not have filter set to '*.tif'
    	HELP	print information about this routine
    	_EXTRA	any other parameters to be passed on to other procedures

     COMMON
    	AXIS_COM general common blocks for AXIS
    	BSIF_COM - common for netCDF format

     OUTPUTS: data is set-up in image_data and with bsif_common variables set
    	 ready to write *.nc if desired (as is done from tif2ncdf)

     MODIFICATION HISTORY:
     (13-May-99 aph) adapted from ax_rd_im; then to using rd_peem
     (08-jun-99 aph) add group to get_num call
     (17-jul99 aph) CCD_bgnd introduced
     (24-oct-00 aph) allow 12-bit or 16-bit ALS PEEM readin
     (06-may-01 aph) AXIS standard header added; gain for dynamic range deleted;
    				format of image_data switched to float
     (12-jul-01 aph) correct for dark on read-in if aio_dark supplied
     (31-jul-01 aph) include /axis keyword in call to RD_PEEM (assumes only run from axis)

(See c:\axis2000\tifrd_im.pro)

## TIFRD_IM-TEST

[Previous Routine] [Next Routine] [List of Routines]

    NAME: FILENAME_IN_CAPITALS

    LAST CHANGED: ----------------------------------- 05-apr-07

     PURPOSE:
    	This procedure reads a tif image file (*.tif) using RD_PEEM  and converts it to
     NetCDF format. This is used to process *.tif to *.nc files for use in stack_analyze

     CATEGORY:
    	Image format conversion.

     CALLING SEQUENCE:
     for procedures:
    	TIFRD_IM, [file, bin=bin, Energy=energy, white=white, CCD_bgnd=CCD_bgnd, $
            smth = smth, bits12 = bits12, region = region, scale=scale, $
    		 help=help, _extra=e]

     INPUTS:
    	FILE 	name of file to convert (user prompted if not supplied)

     KEYWORDS:
    	BIN		paramater for binning
    	BITS12 	if set to 12 this uses the 12-bit read routine in RD_PEEM
    	ENERGY	sets energy of PEEM image
    	CCD_bgnd CCD background image or average value that is subtracted
    	SCALE 	pixel size in microns
    	SMTH 	if set, applies a 3-point median smooth
    	WHITE 	if set, divides the image by an image in file white
               (response of CCD to uniform illumination)
    	AOI 	area of interest, defined by box, [x0,x1, y0, y1] acquired by PEEM-2
    			used to extract su-image from dark and white files
    	REGION 	a 4-number vector [x_start, x_stop, y_start, y_stop]
    			defining the region of the image to be selected
    			(if scale set, in real space units. Otherwise, in pixels)
    	NOFILTER if set, then pickfile dialog does not have filter set to '*.tif'
    	HELP	print information about this routine
    	_EXTRA	any other parameters to be passed on to other procedures

     COMMON
    	AXIS_COM general common blocks for AXIS
    	BSIF_COM - common for netCDF format

     OUTPUTS: data is set-up in image_data and with bsif_common variables set
    	 ready to write *.nc if desired (as is done from tif2ncdf)

     MODIFICATION HISTORY:
     (13-May-99 aph) adapted from ax_rd_im; then to using rd_peem
     (08-jun-99 aph) add group to get_num call
     (17-jul99 aph) CCD_bgnd introduced
     (24-oct-00 aph) allow 12-bit or 16-bit ALS PEEM readin
     (06-may-01 aph) AXIS standard header added; gain for dynamic range deleted;
    				format of image_data switched to float
     (12-jul-01 aph) correct for dark on read-in if aio_dark supplied
     (31-jul-01 aph) include /axis keyword in call to RD_PEEM (assumes only run from axis)
     (05-apr-07 aph) troubleshhooting problem reading ALS PEEM 2 data

(See c:\axis2000\tifrd_im-test.pro)

## TIF_CONVERT

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		TIF_CONVERT

    LAST CHANGED: ----------------------------------- 	07-Aug-08 (aph)

     PURPOSE:
    	This file contains a set of procedures which are a widget to
     convert tif files to a set of NetCDF files or *.ncb file for use in aXis2000.
     Relative to the text-only approach of ax_peem_rd.pro, this widget
     has provision for graphical selection of the region of interest.
     Adapted to be called from axis2000

     CATEGORY:
    	Image conversion.

     CALLING SEQUENCE:
     read~images+peem TIF_CONVERT:

     PROCEDURES
     tif_convert_prep
     tif_convert_limits_get_prep
     tif_convert_limits_get_imgdisp
     tif_convert_gl_dialogue_event
     tif_convert_gl_dialogue
     tif_convert_limits_get
     tif_convert

     INPUTS: none required

     KEYWORDS: none

     OUTPUTS:
    	*.nc files are written as requested by user

     COMMON BLOCKS:
      @AXIS_COM	standard set of common blocks
      @BSIF_com
      @tif_convert_com
      @limits_get_common

     MODIFICATION HISTORY:
     (06-aug-02 aph) AXIS standard header added; integrated with axis2000
     (30-apr-03 aph) adapt for SRC, sphinx data
     (14-may-03 aph) add direct conversion to ncb; move to stack.convert menu; scale in nm/pixel
     (28-jul-03 aph) replaced 'label' names in setting up widget - conflict with Label array in axis.com
     (17-may-04 aph) adapt for Lox stacks
     (04-Jun-04 aph) modify name parsing to get all characters of filename in filename_ev_msec_list
                    make work with sub-sets of the list
     (26-may-05 aph) set up microscope default settings; rationalize parameter display & setting
     (13-jul-05 aph) continue adapting PEEM_general for auto-configure to specific microscopes
                     reconfigured switches to make value and button the same
    				  preserve values between read-ins (unless close IDL)
     (16-oct-05 aph) change read_lox to read_lox_spectra
     (20-jan-07 aph) add in processing for ALS PEEM-3 format files
     (05-apr-07 aph) correct pix_siz - was calling tif_rdim, rd_peem with scale in nm not microns
                     so image dimensions were wrong
     (12-Sep-07 aph) add group keyword to all calls ro Read_PEEM3
     (07-Aug-08 aph) add switch to select / de-select I-ring normalization

(See c:\axis2000\tif_convert.pro)

## TIF_CONVERT_COM.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	TIF_CONVERT_COM.PRO

    LAST CHANGED: ----------------------------------- 07-Aug-08 (aph)

    PURPOSE:
    	This INCLUDE file contains COMMON blocks for  TIF_CONVERT

    CATEGORY:
    	AXIS: utility

    CALLING SEQUENCE: @tif_convert_com

     NAMES AND MEANING OF COMMON VARIABLES
     *************************************************************************
     ***********         TIF_CONVERT COMMON PARAMETERS      ******************
     *************************************************************************

      COMMON tif_convert_common,	 $
    	tif_convert_par  - widget values
    	pathsep			-  path for files
    	bits12			-  1 = 12bit, 0 =16bit
    	ccd_bgnd		-  No of counts in average CCD background
    	smth			-  1 = median smooth
    	bin				-  nxn binning
    	white			- file for CCD pattern correction
    	start			-
    	ncb_switch		- 1= store as binary, 0 = store as separate *.nc files
    	pix_siz_nm		-  nm/pixel
    	tif_signed		- 1 = signed, 0 = unsigned
    	tif_region		- xmin, xmax, ymin, ymax - pixel limits o fregion of image to convert
    	gotalist		- flag indicating set of files have been selected (1) or not (0)
    	filename_list2	- list of output files
    	spectrum_path	- path to spectrum file
    	spectrum_file	- name of spectrum file
    	spectrum_flag	- spectrum 1 = read, 0 = not read
    	n_tif_files		- number of tif files
    	tif_path		- input path
    	nc_filebase		- output filename base
    	nc_path			- output path
    	lox_flag		- 1 = Lox, 0 = other (used in other programs)
    	microscope		- current type of microscope (string)
       microscope_num  - current type of microscope (number)

(See c:\axis2000\tif_convert_com.pro)

## TIF_LOAD

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION tif_load, NOF=nof, error=err, BMP=bmp, GIF=gif, _extra=e
     ------------------------------ last changed: 14-jun-98

    * tif, *.bmp, *.gif file read-in

(See c:\axis2000\tif_load.pro)

## TVIMAGE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
         TVIMAGE

     PURPOSE:
         This purpose of TVIMAGE is to enable the TV command in IDL
         to be a completely device-independent and color-decomposition-
         state independent command. On 24-bit displays color decomposition
         is always turned off for 8-bit images and on for 24-bit images.
         The color decomposition state is restored for those versions of
         IDL that support it (> 5.2). Moreover, TVIMAGE adds features
         that TV lacks. For example, images can be positioned in windows
         using the POSITION keyword like other IDL graphics commands.
         TVIMAGE also supports the !P.MULTI system variable, unlike the
         TV command. TVIMAGE was written to work especially well in
         resizeable graphics windows. Note that if you wish to preserve
         the aspect ratio of images in resizeable windows, you should set
         the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
         equally well on the display, in the PostScript device, and in
         the Printer and Z-Graphics Buffer devices. The TRUE keyword is
         set automatically to the correct value for 24-bit images, so you
         don't need to specify it when using TVIMAGE.

     AUTHOR:
           FANNING SOFTWARE CONSULTING:
           David Fanning, Ph.D.
           1645 Sheely Drive
           Fort Collins, CO 80526 USA
           Phone: 970-221-0438
           E-mail: davidf@dfanning.com
           Coyote's Guide to IDL Programming: http://www.dfanning.com/

     CATEGORY:
         Graphics display.

     CALLING SEQUENCE:

         TVIMAGE, image

     INPUTS:
         image:    A 2D or 3D image array. It should be byte data.

           x  :    The X position of the lower-left corner of the image.
                   This parameter is only recognized if the TV keyword is set.

           y  :    The Y position of the lower-left corner of the image.
                   This parameter is only recognized if the TV keyword is set.

     KEYWORD PARAMETERS:

         BACKGROUND:   This keyword specifies the background color. Note that
                   the keyword ONLY has effect if the ERASE keyword is also
                   set or !P.MULTI is set to multiple plots and TVIMAGE is
                   used to place the *first* plot.

         ERASE:    If this keyword is set an ERASE command is issued
                   before the image is displayed. Note that the ERASE
                   command puts the image on a new page in PostScript
                   output.

         _EXTRA:   This keyword picks up any TV keywords you wish to use.

         HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
                   and column on either side, rather than the default of
                   one full row/column at the ends of the array.  If you
                   are interpolating images with few rows, then the
                   output will be more consistent with this technique.
                   This keyword is intended as a replacement for
                   MINUS_ONE, and both keywords probably should not be
                   used in the same call to CONGRID.

         KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
                   specified position in the window. If you prefer, you can
                   force the image to maintain its aspect ratio in the window
                   (although not its natural size) by setting this keyword.
                   The image width is fitted first. If, after setting the
                   image width, the image height is too big for the window,
                   then the image height is fitted into the window. The
                   appropriate values of the POSITION keyword are honored
                   during this fitting process. Once a fit is made, the
                   POSITION coordiates are re-calculated to center the image
                   in the window. You can recover these new position coordinates
                   as the output from the POSITION keyword.

         MARGIN:   A single value, expressed as a normalized coordinate, that
                   can easily be used to calculate a position in the window.
                   The margin is used to calculate a POSITION that gives
                   the image an equal margin around the edge of the window.
                   The margin must be a number in the range 0.0 to 0.333. This
                   keyword is ignored if the POSITION keyword is used.

         MINUS_ONE: The value of this keyword is passed along to the CONGRID
                   command. It prevents CONGRID from adding an extra row and
                   column to the resulting array, which can be a problem with
                   small image arrays.

         NOINTERPOLATION: Setting this keyword disables the default bilinear
                   interpolation done to the image when it is resized. Nearest
                   neighbor interpolation is done instead. This is preferred
                   when you do not wish to change the pixel values of the image.
                   This keyword must be set, for example, when you are displaying
                   GIF files that come with their own non-IDL color table vectors.

         NORMAL:   Setting this keyword means image position coordinates x and y
                   are interpreted as being in normalized coordinates. This keyword
                   is only valid if the TV keyword is set.

         OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
                   and the image is positioned in the location established by the
                   last graphics command. For example:

                        Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
                        TVImage, image, /Overplot

         POSITION: The location of the image in the output window. This is
                   a four-element floating array of normalized coordinates of
                   the type given by !P.POSITION or the POSITION keyword to
                   other IDL graphics commands. The form is [x0, y0, x1, y1].
                   The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
                   be an output parameter if the KEEP_ASPECT_RATIO keyword is
                   used.

         TV:       Setting this keyword makes the TVIMAGE command work much
                   like the TV command, although better. That is to say, it
                   will still set the correct DECOMPOSED state depending upon
                   the kind of image to be displayed (8-bit or 24-bit). It will
                   also allow the image to be "positioned" in the window by
                   specifying the coordinates of the lower-left corner of the
                   image. The NORMAL keyword is activated when the TV keyword
                   is set, which will indicate that the position coordinates
                   are given in normalized coordinates rather than device
                   coordinates.

                   Setting this keyword will ensure that the keywords
                   KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
                   are ignored.

     OUTPUTS:
         None.

     SIDE EFFECTS:
         Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
         may not have the same aspect ratio as the input data set.

     RESTRICTIONS:
         If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
         used together, there is an excellent chance the POSITION
         parameters will change. If the POSITION is passed in as a
         variable, the new positions will be returned in the same variable
         as an output parameter.

         If a 24-bit image is displayed on an 8-bit display, the
         24-bit image must be converted to an 8-bit image and the
         appropriate color table vectors. This is done with the COLOR_QUAN
         function. The TVIMAGE command will load the color table vectors
         and set the NOINTERPOLATION keyword if this is done. Note that the
         resulting color table vectors are normally incompatible with other
         IDL-supplied color tables. Hence, other graphics windows open at
         the time the image is display are likely to look strange.

     EXAMPLE:
         To display an image with a contour plot on top of it, type:

            filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
            image = BYTARR(360,360)
            OPENR, lun, filename, /GET_LUN
            READU, lun, image
            FREE_LUN, lun

            TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
            CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
                YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10

     MODIFICATION HISTORY:
          Written by:     David Fanning, 20 NOV 1996.
          Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
          Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
             that this program should act more like TV and less like a "color
             aware" application. I leave "color awareness" to the program
             using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
          Fixed a small bug that prevented this program from working in the
              Z-buffer. 17 April 1997. DWF.
          Fixed a subtle bug that caused me to think I was going crazy!
              Lession learned: Be sure you know the *current* graphics
              window! 17 April 1997. DWF.
          Added support for the PRINTER device. 25 June 1997. DWF.
          Extensive modifications. 27 Oct 1997. DWF
              1) Removed PRINTER support, which didn't work as expected.
              2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
              3) Added check for window-able devices (!D.Flags AND 256).
              4) Modified PostScript color handling.
          Craig Markwart points out that Congrid adds an extra row and column
              onto an array. When viewing small images (e.g., 20x20) this can be
              a problem. Added a Minus_One keyword whose value can be passed
              along to the Congrid keyword of the same name. 28 Oct 1997. DWF
          Changed default POSITION to fill entire window. 30 July 1998. DWF.
          Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
          Added limited PRINTER portrait mode support. The correct aspect ratio
              of the image is always maintained when outputting to the
              PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
          Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
              they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
          Added a MARGIN keyword. 18 Oct 1998. DWF.
          Re-established Device, Decomposed=0 keyword for devices that
             support it. 18 Oct 1998. DWF.
          Added support for the !P.Multi system variable. 3 March 99. DWF
          Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
          Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
          Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
          Added the OVERPLOT keyword to allow plotting on POSITION coordinates
             estabished by the preceding graphics command. 11 Oct 99. DWF.
          Added automatic recognition of !P.Multi. Setting MULTI keyword is no
             longer required. 18 Nov 99. DWF.
          Added NOINTERPOLATION keyword so that nearest neighbor interpolation
             is performed rather than bilinear. 3 Dec 99. DWF
          Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
          Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
          Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
          Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
          Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
          Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
          Added BACKGROUND keyword. 20 April 2000. DWF.
          Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
          Rearranged the PLOT part of code to occur before decomposition state
             is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
          Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
          Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
          Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to display images. 8 June 2001. DWF.

(See c:\axis2000\TVimage.pro)

## WIN2LPR

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WIN2LR

    LAST CHANGED: ----------------------------------- 19-mar-02

     PURPOSE:
    	This procedure sends contents of the main screen to the PRINTER pseudo device.
     Earlier versions used approaches based on trasnfer to a disk file then copying to
     the printer device specified in the axis.ini file.

     CATEGORY:
      utility

     CALLING SEQUENCE:
     for procedures:
    	WIN2LPR, printer, SIZE=sz, XS=xs, YS=ys, SYS=sys, PR = pr, _extra=e

     INPUTS:
     	printer

     KEYWORDS:
    	SIZE 	pixels (for square windows)
    	XS		X-pixels (for rectangular windows)
    	YS		Y-pixels (for rectangular windows)
    	SYS		define as 'WIN' or 'X'
    	PR		printer device ('PCL' or 'PS')
    	LS		landscape

     OUTPUTS:
    	print out

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     PROCEDURE:
    	details where needed

     MODIFICATION HISTORY:
     (22-Jun-97 aph) ********  Win2LPR MODIFIED !!!!
     (21-jun-97 APH) ADAPTED to allow printing from Windows system by
          replacing the PRB command for WINsystems (PRB is UNIX operating system specific)
          if SYS='WIN' and PR is not set, default printer is 'PS' (postscript)
     (28-jun-98 aph) adapt win2lpr to print to nsls X1A spooler
     (14-apr-99 aph) adapt win2lpr to NT use of lpr command
     (11-may-99 aph) generalize printing using 'OTHER'
     (11-mAY-99 aph)  added PR_command keyword
     (30-nov-00 cgz) Migrated WIN2LPR to separate file
     (29-jan-02 sgu) modified to use 'PRINTER' device

(See c:\axis2000\win2lpr.pro)

## WIN2LPR-APH

[Previous Routine] [Next Routine] [List of Routines]

    FILE:  win2lpr
     ------------------------------------- LAST CHANGED: 30-Nov-00
       pro WIN2LPR [, printer, SIZE=sz, XS=xs, YS=ys, SYS=sys, PR = pr, _extra=e, /LS]
            -- print current window
               defaults: printer='BL7LJ4',  SIZE=3 (inches) for ALS
               options: SIZE (for square windows)
    				XS, YS = XSize, YSize (for rectangular windows)
    				SYS = define as 'WIN' or 'X'
    				PR = printer device ('PCL' or 'PS')
    				/LS (landscape)

(See c:\axis2000\win2lpr-aph.pro)

## WIN2LPR-SGU

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WIN2LR

    LAST CHANGED: ----------------------------------- 19-mar-02

     PURPOSE:
    	This procedure sends contents of the main screen to the PRINTER pseudo device.
     Earlier versions used approaches based on trasnfer to a disk file then copying to
     the printer device specified in the axis.ini file.

     CATEGORY:
      utility

     CALLING SEQUENCE:
     for procedures:
    	WIN2LPR, printer, SIZE=sz, XS=xs, YS=ys, SYS=sys, PR = pr, _extra=e

     INPUTS:
     	printer

     KEYWORDS:
    	SIZE 	pixels (for square windows)
    	XS		X-pixels (for rectangular windows)
    	YS		Y-pixels (for rectangular windows)
    	SYS		define as 'WIN' or 'X'
    	PR		printer device ('PCL' or 'PS')
    	LS		landscape

     OUTPUTS:
    	print out

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks

     PROCEDURE:
    	details where needed

     MODIFICATION HISTORY:
     (22-Jun-97 aph) ********  Win2LPR MODIFIED !!!!
     (21-jun-97 APH) ADAPTED to allow printing from Windows system by
          replacing the PRB command for WINsystems (PRB is UNIX operating system specific)
          if SYS='WIN' and PR is not set, default printer is 'PS' (postscript)
     (28-jun-98 aph) adapt win2lpr to print to nsls X1A spooler
     (14-apr-99 aph) adapt win2lpr to NT use of lpr command
     (11-may-99 aph) generalize printing using 'OTHER'
     (11-mAY-99 aph)  added PR_command keyword
     (30-nov-00 cgz) Migrated WIN2LPR to separate file
     (29-jan-02 sgu) modified to use 'PRINTER' device

(See c:\axis2000\win2lpr-sgu.pro)

## WIN2TIF

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WIN2TIF

    LAST CHANGED: ----------------------------------- 02-dec-05 (aph)

     PURPOSE:
       This function reads contents of WNUM graphics window
     into a TIFF file

     CATEGORY: graphics utility; standalone

     CALLING SEQUENCE:
       RESULT = WIN2TIF, FileName

     INPUTS:
     WNUM  number of window to read (optional; current window is default)
        wnum is specified either as number
        or as a 5-element array [num, x0, y0, xwid, ywid] for a subset of the window

     KEYWORDS: none

     OUTPUTS: none

     COMMON BLOCKS: none

     fct READWIN [, wnum]  -- read window into bytscal array

     MODIFICATION HISTORY:
     (30-nov-00 cgz) Separated from WINDOW.PRO
     (04-jan-01 cgz) Migrated READWIN from WINDOWS.PRO
     (12-mar-03 aph) get to read 3-color from true color display; tiff_write (IDL$) => write_tiff (idl5)
     (02-dec-05 aph) flip image for IDL after 6.0

(See c:\axis2000\win2tif.pro)

## WIN2TIFF

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WIN2TIF

    LAST CHANGED: ----------------------------------- 02-dec-05 (aph)

     PURPOSE:
       This function reads contents of WNUM graphics window
     into a TIFF file

     CATEGORY: graphics utility; standalone

     CALLING SEQUENCE:
       RESULT = WIN2TIF, FileName

     INPUTS:
     WNUM  number of window to read (optional; current window is default)
        wnum is specified either as number
        or as a 5-element array [num, x0, y0, xwid, ywid] for a subset of the window

     KEYWORDS: none

     OUTPUTS: none

     COMMON BLOCKS: none

     fct READWIN [, wnum]  -- read window into bytscal array

     MODIFICATION HISTORY:
     (30-nov-00 cgz) Separated from WINDOW.PRO
     (04-jan-01 cgz) Migrated READWIN from WINDOWS.PRO
     (12-mar-03 aph) get to read 3-color from true color display; tiff_write (IDL$) => write_tiff (idl5)
     (02-dec-05 aph) flip image for IDL after 6.0

(See c:\axis2000\win2tiff.pro)

## WRITE_MRC_FILE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WRITE_MRC_FILE

    LAST CHANGED: ----------------------------------- 06-Jul-06 (gaj)

     PURPOSE:
    	This procedure writes  a whole stack (3d (E,x,y) array) to a *.MRC binary file
     	It assumes Common volume_data, image_stack exists and contains the data

    	For definition of the MRC format see:
    	http://bio3d.colorado.edu/imod/doc/mrc_format.txt
       http://www.msg.ucsf.edu/IVE/IVE4_HTML/IM_ref2.html#Introduction

     CATEGORY:
    	stack processing

     CALLING SEQUENCE:
    	WRITE_MRC_FILE, FILE

     INPUTS:
     	FILE	name of the output file

     KEYWORDS: none

     OUTPUTS:
    	*.mrc file

     COMMON BLOCKS:
     AXIS_COM	standard set of common blocks
     ANAL_COM
     BSIF_COM
     volume_data, image_stack

     SIDE EFFECTS:

     RESTRICTIONS: none

     MODIFICATION HISTORY:
     (12-apr-06 gaj) first version based on WRITE_WB
     (01-may-06 aph) clean-up
     (06-jul-06 gaj) added extended header to store tilt angles. Fixed bug with scaling of min, max, mean

(See c:\axis2000\write_mrc_file.pro)

## WRITE_NCDF

[Previous Routine] [Next Routine] [List of Routines]

     pro write_ncdf, file, help=help

     Writes out an image in netCDFformat.

     It assumes that you have put the image and associated information
     into BSIF_COMMON variables:
       image_data (the array which holds the image - possible several
    		planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title

     Based on Mark Rivers stuff; Chris Jacobsen, June 1993.

(See c:\axis2000\write_ncdf.pro)

## WRITE_P3B

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		WRITE_P3B

    LAST CHANGED: ----------------------------------- 	20-Jan-07

     PURPOSE:
    	This function writes a 2-d array as an ALS PEEM3 image
     (IDL windows binary with a structure defining microscope parameters)

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  WRITE_P3B, Filename, Data, TAGS = tags

     INPUTS:
    	Filename	name of file (ext = '*.p3b')
    	Data		2-d array with image

     KEYWORDS:
    	TAGS	predefined structure of microscope parameters

     OUTPUTS:
    	RESULT	ALS PEEM3 format data file

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (20-Jan-07 aph) extracted from filetype_p3b.pro (20-jan-07 version of A. Scholl)

(See c:\axis2000\write_p3b.pro)

## WRITE_SDF

[Previous Routine] [Next Routine] [List of Routines]

    NAME: WRITE_SDF

    LAST CHANGED: ----------------------------------- 03-may-04

     PURPOSE:
    	This function writes a self-defining format ascii file
     as used in ALS Beamline 5.3.2 STXM. This is a tool as part of
     indexing VLM images to the sTXM gui.
     AXIS 2d format buffers are written as images
     Axis 1d format buffers are written as NEXAFS point (spectra)

     CATEGORY:
    	Input / output utilty; stand alone or from ax_sdf / axis2000

     CALLING SEQUENCE:
    	Result = WRITE_SDF(structure, file=file, group=group, _extra=e)

     INPUTS:
       STRUCTURE	axis format structure

     KEYWORDS:
     	FILE		optional file name
    	GROUP		group leader (Axis_ID if called from aXis2000 and axis)
    	HEADER_ONLY extract and return header contents only
    	_EXTRA		other passed through parameters

     OUTPUTS:
    	file written to disk
     1d (spectra) - *.hdr, *.xsp
     2d (image, linescan) - *.hdr, *.xim

     COMMON BLOCKS:
    	@ANALCOM	common for stack_analyze
    	@AXIS_COM	standard set of common blocks
    	@BSIF_COM	stack common
    	VOLUME_DATA	stack data set
    	SDFORMAT	reference number for naming muti-element arrays of structures

     MODIFICATION HISTORY:
     (18-oct-01 aph) first version
     (02-may-04 aph) add spectrum write-out

(See c:\axis2000\write_sdf.pro)

## WRITE_STXM

[Previous Routine] [Next Routine] [List of Routines]

     pro write_stxm, file, sd

     Writes out a STXM image in netCDFformat.

     It assumes that you have put the image and associated information
     into BSIF_COMMON variables:
       image_data (the array which holds the image - possible several
    		planes deep for I, IO, CLOCK)
       x_normal, y_normal, rotated, x_title, y_title,
       x_dist, and y_dist

     If "sd" is passed in the argument list, then the STXM scan data
     is assumed to reside in sd.  Otherwise, it is assumed that user_buffer
     contains sd. In the netCDF file, the scan data is written
     as scan data info and not as a user_buffer (since user_buffers
     are inherent to BSIF but are neither encouraged nor disallowed in netCDF).

     Based on Mark Rivers stuff; Chris Jacobsen, June 1993.

     CHANGES:
       the change from version 1.0 to version 1.1 involved simply
          changing the netCDF attribute "sd.operator" to "operator".
          Chris Jacobsen, August 27, 1993
       the change to version 1.2 forces x_title and y_title to
          be strings rather than byte arrays.  Chris Jacobsen,
          November 2, 1993

(See c:\axis2000\write_stxm.pro)

## WRITE_TAGS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		WRITE_TAGS

    LAST CHANGED: ----------------------------------- 	20-Jan-07

     PURPOSE:
    	This function writes parameters as a structure in the AL SPEEM3 data format

     CATEGORY:
    	utility

     CALLING SEQUENCE:
    	Result =  WRITE_P3B, UNIT,  tags

     INPUTS:
    	Unit	open file unit number
    	Tags	parameters with associated Tag names (IDL structure)

     KEYWORDS: none

     OUTPUTS: adds tags to data file

     COMMON BLOCKS: none

     MODIFICATION HISTORY:
     (20-Jan-07 aph) extracted from filetype_p3b.pro (20-jan-07 version of A. Scholl)

(See c:\axis2000\writetags.pro)

## WRITE_XAS[1]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	WRITE_XAS

    LAST CHANGED: ----------------------------------- 26-sep-00

    PURPOSE:
    	This procedure writes a spectrum into 'XAS' format, with
     optional guided writing of the header paramaters

    CATEGORY:
    	STAND ALONE:  spectral processing

    CALLING SEQUENCE:
     	WRITE_XAS_WRAP

    CALLED FROM AXIS:
    	Write-XAS spectrum

    ROUTINES
    	WRITE_XAS_WRAP
    	WRITE_XAS - routine that actually writes data (many keywords!)

    INPUTS:
    	lun		logical unit number
    	header	header array
    	info	request for information about routine
     for WRITE_XAS
    	filename - name of file
    	ev		energy array
    	data	intensity array
    	header	header

    KEYWORDS:
    	none for write_xas_wrap

    	for WRITE_XAS:
       formula		= chemical formula of sample
    	common_name	= common_name of sample
    	edge		= edge
    	acquisition_mode = acquisition_mode
    	source_purity = source_purity
    	comments 	= comments
    	delta_ev	= energy resolution
    	yaxis		= yaxis label
    	contact_person = contact_person
    	journal		= journal
    	authors		= authors
    	title		= title
    	volume		= volume
    	issue_number = issue_number
    	year		= year
    	pages		= pages
    	booktitle	= booktitle
    	editors		= editors
    	publisher	= publisher
    	address		= address
    	help		= help

    OUTPUTS:
    	File written in XAS format

    COMMON BLOCKS:
    	none

    MODIFICATION HISTORY:
     file obtained from Jacobsen Feb-98; developed from Mancini / Hitchcock format
     (26-sep-00 aph) AXIS standard documentation

(See c:\axis2000\write_xas-1col.pro)

## WRITE_XAS[2]

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	WRITE_XAS

    LAST CHANGED: ----------------------------------- 04-Jun-08

    PURPOSE:
    	This procedure writes a spectrum into 'XAS' format, with
     optional guided writing of the header paramaters

    CATEGORY:
    	STAND ALONE:  spectral processing

    CALLING SEQUENCE:
     	WRITE_XAS_WRAP

    CALLED FROM AXIS:
    	Write-XAS spectrum

    ROUTINES
    	WRITE_XAS_WRAP
    	WRITE_XAS - routine that actually writes data (many keywords!)

    INPUTS:
    	lun		logical unit number
    	header	header array
    	info	request for information about routine
     for WRITE_XAS
    	filename - name of file
    	ev		energy array
    	data	intensity array
    	header	header

    KEYWORDS:
    	none for write_xas_wrap

    	for WRITE_XAS:
       formula		= chemical formula of sample
    	common_name	= common_name of sample
    	edge		= edge
    	acquisition_mode = acquisition_mode
    	source_purity = source_purity
    	comments 	= comments 				; multiple lines
    	delta_ev	= energy resolution
    	yaxis		= yaxis label
    	contact_person = contact_person
    	journal		= journal
    	authors		= authors
    	title		= title
    	volume		= volume
    	issue_number = issue_number
    	year		= year
    	pages		= pages
    	booktitle	= booktitle
    	editors		= editors
    	publisher	= publisher
    	address		= address
    	help		= help

    OUTPUTS:
    	File written in XAS format

    COMMON BLOCKS:
    	none

    MODIFICATION HISTORY:
     file obtained from Jacobsen Feb-98; developed from Mancini / Hitchcock format
     (26-sep-00 aph) AXIS standard documentation
     (22-May-08 aph) add multi-column write for ISEELS & polymer database
     (04-jun-08 aph) add handling of ISEELS and NSLS headers

(See c:\axis2000\write_xas.pro)

## WVLEN2EN, EN2WVLEN[1]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           WVLEN2EN, EN2WVLEN

     PURPOSE:
           These functions convert between photon energy and wavelength.

     CATEGORY:
           Optics

     CALLING SEQUENCE:
           Wavelength = EN2WVLEN(Energy)

     INPUTS:
           Input:  The photon energy to convert.

     KEYWORD PARAMETERS:
           m:        If set, wavelength is in meters. This is the default.

           nm:       If set, wavelength is in nanometers.

           Angstrom: If set, wavelength is in Angstroms.

           J:        If set, photon energy is in Joules. This is the default.

           keV:      If set, photon energy is in kiloelectron Volts.

           eV:       If set, photon energy is in electron volts.

     OUTPUTS:
           Result:  The conversion of photon energy to wavelength.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           December, 1997

(See c:\axis2000\en2wvlen.pro)

## WVLEN2EN, EN2WVLEN[2]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           WVLEN2EN, EN2WVLEN

     PURPOSE:
           These functions convert between photon energy and wavelength.

     CATEGORY:
           Optics

     CALLING SEQUENCE:
           Energy = WVLEN2EN(Wavelength)
           Wavelength = EN2WVLEN(Energy)

     INPUTS:
           Input:  The wavelength or photon energy to convert.

     KEYWORD PARAMETERS:
           m:        If set, wavelength is in meters. This is the default.

           nm:       If set, wavelength is in nanometers.

           Angstrom: If set, wavelength is in Angstroms.

           J:        If set, photon energy is in Joules. This is the default.

           keV:      If set, photon energy is in kiloelectron Volts.

           eV:       If set, photon energy is in electron volts.

     OUTPUTS:
           Result:  The conversion to photon energy or wavelength.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           December, 1997

(See c:\axis2000\photon_conv.pro)

## WVLEN2EN, EN2WVLEN[3]

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           WVLEN2EN, EN2WVLEN

     PURPOSE:
           These functions convert between photon energy and wavelength.

     CATEGORY:
           Optics

     CALLING SEQUENCE:
           Energy = WVLEN2EN(Wavelength)

     INPUTS:
           Input:  The wavelength to convert.

     KEYWORD PARAMETERS:
           m:        If set, wavelength is in meters. This is the default.

           nm:       If set, wavelength is in nanometers.

           Angstrom: If set, wavelength is in Angstroms.

           J:        If set, photon energy is in Joules. This is the default.

           keV:      If set, photon energy is in kiloelectron Volts.

           eV:       If set, photon energy is in electron volts.

     OUTPUTS:
           Result:  The conversion of wavelength to photon energy.

     WRITTEN BY:
           Billy W. Loo, Jr.
           Bioengineering Graduate Group, UCSF / UCB
           School of Medicine, UCD
           Lawrence Berkeley National Lab
           December, 1997

(See c:\axis2000\wvlen2en.pro)

## XAS1

[Previous Routine] [Next Routine] [List of Routines]

      function xas1, file, /PLOT, DEFPATH=defpath, OPT=opt, _extra=e
       -- Reads Beamline 7 STXM X-ray absorption data from a text file
     default (no opt) is to read in E,col1,col2
     OPT = col1:   raw data - ASSUMES transmission detector in col(1); OSA in col(2)
     OPT = col2:  extract col(2)  - OSA (pre-98) or trans (after Dec-97; flipped here)
     OPT = col3;  extract col(3)  - TEY
     OPT = dark:  dark correct signals
     OPT = OSA;   use OSA signal for Io & convert to rel-O.D.  (no dark correct)
     OPT = OSA-dark; dark correct, then use OSA signal for Io & convert to rel-O.D.

(See c:\axis2000\xas1.pro)

## XAS2

[Previous Routine] [Next Routine] [List of Routines]

      fct xas2, file, /PLOT,  DEFPATH=defpath, OPT=opt, _extra=e
         -- Reads two Beamline 7 STXM XAS'S from two text files
         -- computes Beers- law absorption as ln(hole/DET)

     OPT = 'raw' (default) - do not use OSA normalisation or dark correct
     OPT = 'dark' - dark correct but no OSA normalisation
     OPT = 'OSA' - OSA normalise but no dark correction
     OPT = 'OSA-dark' - dark correct AND OSA normalize

      ASSUMES identical sampling in both files !!!!!!!!!

(See c:\axis2000\xas2.pro)

## XM1_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    	XM1_LOAD

    LAST CHANGED: ----------------------------------- 21-feb-01

    PURPOSE:
    	This function reads in XM-1 images from *.spe files

    CATEGORY:
    	images read in

    CALLING SEQUENCE:
    	Result = XM1_LOAD(file=file, _extra=e)

    CALLED FROM AXIS:
    	Read->Images->ALS-XM1

    INPUTS: none. All input parameters are passed as keywords.

    KEYWORDS:
    	FILE 	filename to read
    	NOF		no filter
    	GROUP 	name of parent group (Axis_ID)
    	_EXTRA	passed on parameters

    OUTPUTS:
    	RESULT = AXIS 2d structure

    COMMON BLOCKS:
    	@AXIS_COM	standard set of common blocks

    PROCEDURE:
    	XM1_LOAD uses xmload, nojunk,loadcmsa, flatbg (from Greg Denbaux)

    MODIFICATION HISTORY:
     (21-feb=01 aph) first version

(See c:\axis2000\xm1_load.pro)

## XMLOAD

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		XMLOAD

    LAST CHANGED: ----------------------------------- 12-may-02 (aph)

     PURPOSE:
     This function loads an XM-1 image, removes camera artifacts,
     and rotates the image to correspond with the Winview orientation.

     CONTENTS OF THIS FILE (in order)

    	LOADCMSA
    	COMPRESSPIXELS
    	NOJUNK
    	EXP_TIME
    	XMLOAD

     CATEGORY:
    	Image read in

     CALLING SEQUENCE:
    	Result = XMLOAD(FNAME)

     INPUTS:
     	FNAME - name of the file (optional)

     KEYWORDS:
    	ZOOM
    	NOSHOW		DO NOT DISPLAY (if not set, uses LOOK in standalone mode)
    	MZPSHIFT
    	MAG
    	BINX
    	BINY
    	ENERGY
    	WAVEL
    	NOPRINT
    	VERSION
    	IMTYPE

     OUTPUTS:
    	No explicit outputs.  In stand alone mode, displays corrected image

     COMMON BLOCKS:
    	AXIS_COM	standard set of common blocks; locked into running through AXIS
    	CMSA

     SIDE EFFECTS: none

     RESTRICTIONS:
    	LOOK - not yet functioning

     PROCEDURE:
    	Image is read in using loadcmsa.pro
    	Camera artefacts corrected etc using nojunk.pro
    	Display in stand alone mode using look.pro

     MODIFICATIONS
     8/4/95: John Heck first version
     1-9-98: modified to return 0 if file not found by loadcmsa, Angelic
     5-1-97: modified for filenames bigger than ymmdd999, Werner
     (21-feb-01 aph) adapting for windows environment & reading into AXIS
     (23-feb-01 aph) implement calibration and background corrections
     (12-may-02 aph) correct header name format

(See c:\axis2000\xmload.pro)

## ZIMBA_RUN

[Previous Routine] [Next Routine] [List of Routines]

     FILE
    		  ZIMBA_RUN.PRO

     LAST CHANGED: ---------------------- 18-jan-00

     PURPOSE
       execute Zstack_analyze to align stack data (nc format) and extract spectra
       with provision for loading from file (*.sl), with an alignment file

     KEYWORDS
    	AXIS - if set, indicates AXIS widget exists and the user prompt dialog is used

     COMMON
       @axis_com - common block for AXIS

     MODIFICATIONS
     (26-sep-99 aph) first version (simplifying axis_c)
     (18-jan-00 aph) adapt to new zstack code (Jan-00)

(See c:\axis2000\zimba_run.pro)

## ZSTACK_ALIGN.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	ZSTACK_ALIGN.PRO

     LAST CHANGED: ------------------  13-Apr-08  (form 03-Mar-08 (MJ))

     AUTHORS:
    	Carl G. Zimba (Photons UnLimited)
    	Chris Jacobsen (SUNY - Stonybrook)
       Adam Hitchcock (McMaster)
     PURPOSE:
    	Alignment of images abtained on an x-ray microscope.
    	Called by ZSTACK_ANALYZE.PRO
     CATEGORY:
    	Data analysis.
     CALLING SEQUENCE:
    	zstack_align
     INPUTS:
    	NONE
    	filename_list,ev_list,msec_list,filename_display_list, and image_stack of zstack_common
    		must be previously defined via ZSTACK_ANALYZE.PRO
     KEYWORD PARAMETERS:
    	filename_shift = name of file containing alignment shifts saved during a previous alignment
    	realign = set to redo alignment with existing dragbox
    	low_mem = set to reduce required memory allocation
     OUTPUTS:
    	NONE
    	x_shift, y_shift, corr_dim_stack, corr_stack, shifted_image_stack of zstack_align_common
    		are computed as output
     COMMON BLOCKS:
    	zstack_common	:
    		data_source				:	type of x-ray microscopy data: STXM:1, SXM:2, SM:3, ALS:4, POLY:5
    		data_directory				:	directory of data files
    		image_stack				:	3-D matrix of multiple x-ray microscope images
    		filename_list				:	list of filename corresponding to images in image_stack
    		ev_list					:	list of x-ray energies corresponding to images in image_stack
    		msec_list					:	list of dwell times corresponding to images in image_stack
    		filename_display_list			:	list of filename, x-ray energy, and dwell time corresponding to images in image_stack
    		displayed_file_index			:	index in image_stack, filename_list, msec_list, and filename_display_list currently being displayed or processed
    		n_files					:	number of images
    		list_filename				:	name of file to save or retrieve list of data files
    		shift_filename				:	filename of alignment shifts
    		x_shift					:	array of x-coordinate alignment shifts
    		y_shift					:	array of y-coordinate alignment shifts
    		data_shifted				:	0: data was not shifted and should not be clipped, 1: data was shifted and should be clipped, -1: denotes ZSTACK_PROFILE.PRO is being run as a stand-alone procedure
    		n_clipped_cols				:	number of columns in clipped image
    		n_clipped_rows				:	number of rows in clipped image
    		clipbox					:	vector of four points defining dimensions of region unclipped by alignment: [xleft,xright,ybot,ytop]
    	zstack_align_common
    		zstack_align_par			:	variables controlling ZSTACK Align dialog window
    		file_num					:	vector of file numbers of image files
    		dragbox					:	vector of four points defining dimensions of region selected for alignment: [xleft,xright,ybot,ytop]
    		edge_enhance				:	edge enhancement parameter: 0: none, 1: sobel, 2: roberts
    		edgegauss_pixels			:	number of pixels used for edgeguass smoothing in ZSTACK_ALIGN_IMAGES.PRO, default = 3
    		edgefill					:	type of filling to occur at edges of shifted images: mean, median, max, min, zero
    		image_match				:	Image to align to: -1: preceding image, 0: constant image, 1: following image
    		constant_file_index			:	image of index to use as reference when aligning to a constant image
    		corr_max					:	0: use 3-pt fitted maximum of correlation function, 1: use center of mass of correlation function
    		maxshift					:	2-point vector of minimum and maximum values of x-shift and y_shift, and temp_x_shift and temp_y_shift within ZSTACK_ALIGN_TUNE
    		doalign_complete			:	-1: alignment in progress, 0: alignment not started, 1: alignment finished, 2: using alignment from stored file
    		low_memory					:	Reflects keyword LOW_MEM: 0: use full memory allocation, 1: use reduced memory allocation
    		corr_stack					:	3-D matrix of correlation functions corresponding to image_stack
    		shifted_image_stack			:	3-D matrix of shifted images corresponding to image_stack
    		corr_dim_stack				:	3-D matrix (i,j,k) of maxima of correlation functions: i: x maximum, j: y maximum, k: image file
    		shift_threshold				:	mimimum shift required to actually shift the image
    	zstack_tune_common
    		zstack_tune_par				:	variables controlling ZSTACK Tune Alignment dialog window
    		temp_x_shift				:	vector of alignment shifts along x-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		temp_y_shift				:	vector of alignment shifts along y-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		init_x_shift				:	vector of initial alignment shifts along x-coordinate for images in image_stack
    		init_y_shift				:	vector of initial alignment shifts along y-coordinate for images in image_stack
    		image_center				:	array of pixel coordinates specifying the center (in pixels) of each image
    		corr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function image
    		shifted_center				:	array of pixel coordinates specifying the center (in pixels) of each shifted image
    		subimage_center				:	array of pixel coordinates specifying the center (in pixels) of each subimage
    		subcorr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function subimage
    		subshifted_center			:	array of pixel coordinates specifying the center (in pixels) of each shifted subimage
    		subimage_pixels				:	size of subimages in pixels
    		fid_pt					:	pixel coordinates of present fiducial point(s)
    		n_fid_pt					:	number of fiducial points
    		all_fid_pt					:	array of all fiducial points
    		fid_pt_index				:	index of fiducial point(s)
    	zstack_display_common
    		zstack_display_par			:	variables controlling ZSTACK Display dialog window
    		image_zoom					:	zoom factor for displaying images
    		subimage_zoom				:	zoom factor for subimages
    		movie_delay				:	delay used to display movie images of data stacks, dependent upon machine speed
    		disp_min					:	minimum percentage intensity for display of images
    		disp_max					:	maximum percentage intensity for display of images
    		disp_gamma					:	gamma factor for display of images
    		spectrum_display			:	Display spectra as: 1: Single Beam, 2: Percent Transmittance, 3: Absorbance
    		spectrum_offset				:	Offset used to plot spectra
    		init_zoom					:	initial zoom factor for displaying images (used in ZSTACK_SAVE and ZSTACK_TUNE)
    		movie_active				:	movie of images is active: 0: NO, 1: YES
    		profile_zoom				:	zoom factor for file number axis on profile images
    		image_range				:	scale images using: 0: intensity range of each image, 1: intensity range of full image stack
    		image_ratio				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		ratio_image_index			:	index of image to use when ratio images to a constant image
    		image_scale				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		image_invert				:	invert color bar: 0: NO, 1: YES
    		temp_old_display			:	initial array of display parameters, set at beginning of ZSTACK_DISPLAY
    		temp_new_display			:	array of display parameters updated as display options are changed
    		zstack_subroutine			:	subroutine from which ZSTACK_DISPLAY was called
    		spectra_x_min				:	mimimum x-ray energy value to plot spectra
    		spectra_x_max				:	maximum x-ray energy value to plot spectra
    		spectra_y_min				:	mimimum intensity value to plot spectra
    		spectra_y_max				:	maximum intensity value to plot spectra
    		x_autoscale				:	autoscale x-ray energy scale: 0: NO, 1: YES
    		y_autoscale				:	autoscale spectra intensity scale: 0: NO, 1: YES
    	zstack_color_common
    		bottom_color_index			:	index of lowermost color of gradient colorscale
    		top_color_index				:	index of uppermost color of gradient colorscale
    		black_color_index			:	index of black color
    		white_color_index			:	index of white color
    		plot_bkgd_color_index			:	color index for plot background, either black or white
    		plot_axes_color_index			:	color index for plot axes, either whilte or black
    		image_border_color_index		:	color index for image border in zstack_buildlist and zstack_profile dialog windows
    		dragbox_color_index			:	color index for dragbox used to define subregion for alignment
    		corr_ctr_color_index			:	color index for crosshair showing center of correlation function
    		corr_max_color_index			:	color index for crosshair showing maximum of correlation function
    		x_shift_color_index			:	color index for plotting of x-shift
    		y_shift_color_index			:	color index for plotting of y-shift
    		shift_cursor_color_index		:	color index for cursor in shift plot, indicating file number
    		tune_fiducial_color_index		:	color index for fiducial points in closeup of shifted image in zstack_tune dialog window
    		spectra_color_index			:	color indices (14) for plotting of spectra
    		spectra_cursor_color_index		:	color index for cursor in spectra plot, indicating x-ray energy
    		profile_color_index			:	color index for plotting of intensity profile and cursor in profile image indicating row or column
    		profile_cursor_color_index		:	color index for cursor in profile image, indicating x-ray energy
    		profile_spectrum_color_index	:	color index for plotting of profile spectrum
    		test1_color_index			:	color index #1 for testing
    		test2_color_index			:	color index #2 for testing
    		test3_color_index			:	color index #3 for testing
     SIDE EFFECTS:

     RESTRICTIONS:
    	Used as ZSTACK suite of routines
     PROCEDURE:
    	Called by ZSTACK_ANALYZE.PRO
     EXAMPLE:

     MODIFICATION HISTORY:
     Modified 25-mar-1998 to deal with 24 bit graphics, CJJ
     Modified July 11 and 13, 1998 to deal with changes to align.pro, CJJ
     Modified 28-aug-1998 to work with corrected 24 bit graphics. CJJ
     Modified 31-Aug-1998 to add x_shift, y_shift to argument list, and
       remove shift_filename!, CJJ

     Modified 20feb99, CGZ
     Extensively modified and rewritten STACK_ALIGN.PRO to form ZSTACK_ALIGN.PRO
     Changes and additions are numerous:

     All procedures and common variables starting with 'stack' were changed to 'zstack'
     so that the existing routine, STACK_ALIGN.PRO, can be run in parallel

     Added the following procedures:
    	zstack_align_prep		:	sets common variables, color table, and color indices
    	zstack_align_imgdisp		:	displays images and shift plot
    	zstack_align_save_shift	:	saves alignment shift into MAPPER file, *.aln
    	zstack_align_read_shift	:	reads alignment shifts from MAPPER file, *.aln

     Rewrote stack_align_sensitive to be two separate procedures with better control
    	zstack_align_sensitive	:	activate features on Stack Align dialog window
    	zstack_align_desensitive	:	deactivate features on Stack Align dialog window

     Pre-existing procedures
    	zstack_align_doalign		:	controls alignment of image stack with active display
    	zstack_align_event		:	event routine for zstack_align
    	zstack_align			:	main procedure for alignment of STXM images

     Modified user interface window to include
    	display and movie of image, correlation function, shifted image
    		dragbox is plotted on both image and shifted image
    		center of correlation function displayed as crosshair overlay (same as CJJ)
    		maximum of correlation function displayed as 1-pixel box overlay (same as CJJ)
    	modified plot of alignment shifts
    		- use actual file numbers instead of file sequence number (relative number)
     ***** APH (23-may-04) - undo this change ! ************************
    		- added plot_x_min and plot_x_max
    		? is it useful to plot vs x-ray energy instead - would require considerable work
    			might be able to plot both using upper and lower x-axes
    	movie can be played before and after alignment to inspect position of dragbox
    		and quality of alignment
    	cursor bar added to plot of alignment shifts highlighting shift and file
    		during movie or static display
    	displayed file can be selected either using file list or alignment plot
    		clicking on alignment plot, prints file info and alignment shift in Output Log
    	text fields added to display image and shift information during movie or static display
    	added "Load New Color Table" to change color table of image
    	saving and retrieving of file of alignment shifts
    	added ability to redo alignment
    		- can now do multiple alignments using different conditions, saving each

     Changed zstack_align_par.dragbox_label routine in zstack_align_event
    	Replaced getbox routine with box_cursor routine, more robust on multiple platforms, CGZ

     Adapted display routines to use zstack_align_imgdisp
    	One display algorithm which can be easily modified
    	Only exception is real-time plotting of alignment shift in zstack_align_doalign

     Changed the way the color table is specified: zstack_align_prep
    	- much simpler now, only executed once, allows multiple colors easily

     New variables:
    	corr_stack			:	stack of correlation functions
    	shift_image_stack	:	stack of shifted images
    	corr_dim_stack		:	array of dimensions specifying center and maxima of
    							correlation function
    							used for displaying correlation function
    	edgefill			:	type of filling to occur at edges of shifted images
    							(edges can contain no data due to shifting)
    							set within zstack_align_doalign
    		meanfill 		:	replace with mean of image
    		medianfill 	:	replace with median of image
    		maxfill 		:	replace with maximum of image
    		minfill 		:	replace with minimum of image
    		zero			:	replace with zero (default)
     	doalign_complete	:	specifies state of alignment
    							(modified from use in stack_align.pro)
    		-1			:	alignment in progress
    		 0			:	alignment not started
    		 1			:	alignment finished
    		 2			:	using alignment from stored file

    		-2			:	manual alignment in progress
    		-1			:	auto-alignment in progress
    		 0			:	alignment not started
    		 1			:	auto-alignment finished
    		 2			:	manual alignment finished
    		 3			:	using alignment from stored file

     Restored shift_filename to argument list

     Changed dragbox conditional from
    	IF ((dragbox(0) NE 0) AND (dragbox(1) NE 0) AND $
    		(dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    	to IF ((dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    	to accomodate dragbox = [0,0,*,*], i.e., lower left corner

     Save alignment / Do not save alignment choice wasn't working in CJJ version - fixed

     Stack_align would give non-zero shift for first image
    	This is fixed with modification of call to zstack_align_images (updated version of align.pro)

     Added dragbox coordinates to header of MAPPER file of alignment shifts

     Added zstack_align_tune to interactively adjust alignment shifts
    	essentially superceding stack_manalign.pro.
    	This can be improved upon to incorporate features of stack_manalign.pro

     Moved nearly all widget_control,var,sensitive = 0/1 statements to
    	zstack_align_sensitive and zstack_align_desensitive for more reliable operation
    	and better organization of code (instead of being widely dispersed)
    	zstack_align_sensitive has situation-dependent conditionals to control appearance of window

     Need to restore virtual memory allocation when working with large data arrays
     	so corr_stack, shift_image_stack, and corr_dim_stack) set to zero at end

     Added alignment to following image - useful if image quality is better at high energy
    	This is in addition to existing alignment to preceding image and to a constant image
    	Eliminated variable, zstack_align_par.constant_match
    	Added variable, image_match with valid values:
    		-1			:	alignment using preceding image
    		 0			:	alignment using constant image
    		 1			:	alignment using following image

     Added low_mem keyword to STACK_ANALYZE.PRO and STACK_ALIGN.PRO
    	If set, then shifted_image_stack is not formed with STACK_ALIGN.PRO
    	This reduces memory use by 1/3 and is useful when large arrays are being processed.
    		This comes at some reduction in speed for displaying new images,
    		most noticeable during playing of image movies
    	If set, display of shifted images within STACK_ALIGN.PRO is done by calculating
    		shifted image from x_shift, y_shift, and image_stack
    		every time an image is displayed.
    	With low_mem set, IDL partition should be approx. >9 times n_elements(image_stack)
    	With low_mem not set, IDL partition should be approx. >13 times n_elements(image_stack)
    		(based on tests on a Macintosh)

     Modified COMMON block structure so that common variables are shared with all zstack routines
    	i.e., zstack_common contains variables used by
    		ZSTACK_ANALYZE.PRO, ZSTACK_READLIST.PRO, ZSTACK_BUILDLIST.PRO, and ZSTACK_ALIGN.PRO
     Common variables are now defined only once in each file, not repetitively as before.
     Common variables for data are now determined within ZSTACK_BUILDLIST.PRO or ZSTACK_READLIST.PRO:
    	image_stack, filename_list, ev_list, msec_list, filename_display_list
    	This requires that files be read only once, eliminated time-intensive duplicate calls of
    		STXM_READ.PRO or SXM_READ.PRO

     Modified zstack_align_par, zstack_align_tune_par
    	so that they only contain only variables associated with dialog window.
    	All other variables have been moved to zstack_align_common

     Added n_files, list_filename, and shift_filename variables to zstack_common variable

     Divided align and tune functions into two separate procedures: ZSTACK_ALIGN.PRO and ZSTACK_TUNE.PRO
     ZSTACK_TUNE.PRO could be used as a replacement for ZSTACK_MANALIGN.PRO

     Modified so that zoom can be changed after alignment is complete
    	added /new_zoom option to ZSTACK_ALIGN.PRO and slightly altered button naming routine

     End of Modifications 20feb99, CGZ

     Fixed display of alignment shifts for alignment using following image.  CGZ 12aug99

     Added EXIT button to exit ZSTACK package directly from zstack_align dialog, CGZ 12aug99
     Removed CGZ, 12aug99

     Changed default value of image_match to -1, i.e., will use preceding image for aligment
    	CGZ, 09sep99

     Added optional sections to plot maximum of correlation function and
    	points used to determine center of mass,  commented out for routine use
    	Useful in troubleshooting
    	CGZ, 28sep99

     Changed header of file of alignment shifts (*.aln) to include alignment conditions
    	CGZ, 28sep99

     Modified to optimize use of memory
    	Each correlation function, corr_stack(*,*,i), is now only as large as region
    	defined by dragbox.  Formerly, each correlation function had the same dimensions
    	as the image.  So if a 50x50 pixel dragbox is used with 200x200 pixel images,
    	this uses only 7% of the memory used if the entire image is used for the alignment.

     (06oct00 cgz) Moved dragbox from zstack_align_common to zstack_common
    	so that it can be used in zstack_save to select subregion of interest

     (13oct00 cgz) Altered definition of dragbox so that it is now [xleft,xright,ybot,ytop]
    		This makes it consistent with definition of other cursor boxes
    		and eliminates need for min and max testing
    		Changed logic statement from:	IF ((dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    							to:	IF ((dragbox(1) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN

     (29oct00 cgz) Modified !version.os routines to use !version.os_family variable
     (31oct00 cgz)
    		Modified zstack_buildlist_savelist to include dialog_pickfile so directory can be selected
    		Replaced platform-dependent code with call to zstack_analyze_extract_filename
     (10nov00 cgz)
    		Fixed hourglass cursor problem with time-intensive alignments
     (28nov00 cgz) migrated zstack_profile_colorbar routine to zstack_analyze.pro
     (26-mar-01 aph) change BOX_CURSOR to BX_CURSOR
     (13-apr-01 aph) tried Zimba suggested fix
     (23-may-04 aph) get plot of alignment shifts to work
     (03-Mar-08 MJ)  Keyword /SCROLL in widget_base() needs X_SCROLL_SIZE.
                     Took out initial size and placement of base widget.
                     Put back in temporary filenumber array to get plot of shifts.
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS

(See c:\axis2000\zstack_align.pro)

## ZSTACK_COLOR.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	ZSTACK_COLOR.PRO

    LAST CHANGED: ----------------------------------- 23-feb-06

     AUTHORS:
    	Carl G. Zimba (Photons Unlimited)

     PURPOSE:
           A modal dialog widget allowing the user to specify
           the RGB color triple specifying the color. The return
           value of the function is the color triple.

     CATEGORY:
           Graphics, Color Specification.

     CALLING SEQUENCE:
           color = Zstack_PickColor(colorindex)

     INPUTS:
    	NONE

     KEYWORD PARAMETERS:
           GROUP_LEADER: The group leader for this widget program. This
                  keyword is required for MODAL operation. If not supplied
                  the program is a BLOCKING widget. Be adviced, however, that
                  the program will NOT work if called from a blocking widget
                  program, unless a GROUP_LEADER is supplied.
           STARTINDEX: Sixteen pre-determined colors are loaded The STARTINDEX
                  is the index in the color table where these 16 colors will
                  be loaded. By default, it is !D.Table_Size - 17.
           TITLE: The title on the program's top-level base. By default the
                  title is "Pick a Color".
           CANCEL: A keyword that is set to 1 if the CANCEL button is selected
                  and to 0 otherwise.
     OUTPUTS:
    	NONE
     COMMON BLOCKS:
    	zstack_color_common
    		bottom_color_index			:	index of lowermost color of gradient colorscale
    		top_color_index				:	index of uppermost color of gradient colorscale
    		black_color_index			:	index of black color
    		white_color_index			:	index of white color
    		plot_bkgd_color_index			:	color index for plot background, either black or white
    		plot_axes_color_index			:	color index for plot axes, either whilte or black
    		image_border_color_index		:	color index for image border in zstack_buildlist and zstack_profile dialog windows
    		dragbox_color_index			:	color index for dragbox used to define subregion for alignment
    		corr_ctr_color_index			:	color index for crosshair showing center of correlation function
    		corr_max_color_index			:	color index for crosshair showing maximum of correlation function
    		x_shift_color_index			:	color index for plotting of x-shift
    		y_shift_color_index			:	color index for plotting of y-shift
    		shift_cursor_color_index		:	color index for cursor in shift plot, indicating file number
    		tune_fiducial_color_index		:	color index for fiducial points in closeup of shifted image in zstack_tune dialog window
    		spectra_color_index			:	color indices (14) for plotting of spectra
    		spectra_cursor_color_index		:	color index for cursor in spectra plot, indicating x-ray energy
    		profile_color_index			:	color index for plotting of intensity profile and cursor in profile image indicating row or column
    		profile_cursor_color_index		:	color index for cursor in profile image, indicating x-ray energy
    		profile_spectrum_color_index	:	color index for plotting of profile spectrum
    		test1_color_index			:	color index #1 for testing
    		test2_color_index			:	color index #2 for testing
    		test3_color_index			:	color index #3 for testing
     SIDE EFFECTS:

     RESTRICTIONS:

     PROCEDURE:
    	Called by ZSTACK_ANALYZE.PRO (not true)
     EXAMPLE:

     MODIFICATION HISTORY:
    	Modified from PICKCOLOR.PRO written by David Fanning, http://www.dfanning.com
     (23-feb-06 aph) try to get working to allow selecting colors in axis

(See c:\axis2000\zstack_pickcolor.pro)

## ZSTACK_COLOR_COMMON

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		ZSTACK_COLOR_COMMON

    LAST CHANGED: ----------------------------------- 	03-Mar-08 (MJ)

     PURPOSE:
    	This file contians the common block, ZSTACK_COLOR_COMMON

     CATEGORY:
    	Image display.

     CALLING SEQUENCE: @zstack_coloR_Common to inclide in a file

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (21-feb-06 aph) isolated from header of zstack_color
     (03-Mar-08 MJ)  Last line was missing

(See c:\axis2000\zstack_color_common.pro)

## ZSTACK_COMMON

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		ZSTACK_COMMON

    LAST CHANGED: ----------------------------------- 	23-Feb-06

     PURPOSE:
    	This file contians the common block, ZSTACK_COMMON

     CATEGORY:
    	Image display.

     CALLING SEQUENCE: @zstack_common to inclide in a file

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (21-feb-06 aph) isolated from header of zstack_color

(See c:\axis2000\zstack_common.pro)

## ZSTACK_DISPLAY_COMMON

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    		ZSTACK_DISPLAY_COMMON

    LAST CHANGED: ----------------------------------- 	23-Feb-06

     PURPOSE:
    	This file contians the common block, ZSTACK_DISPLAY_common

     CATEGORY:
    	Image display.

     CALLING SEQUENCE: @zstack_display_common to inclide in a file

     INPUTS: none

     KEYWORDS: none

     OUTPUTS: none

     MODIFICATION HISTORY:
     (23-feb-06 aph) isolated from header of zstack_analyze

(See c:\axis2000\zstack_display_common.pro)

## ZSTACK_PLOT.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	ZSTACK_PLOT.PRO

     LAST CHANGED: --------------------------  13-Apr-08 (aph form 03-Mar-08 (MJ))

     AUTHORS:
    	Carl G. Zimba (Photons UnLimited)
    	Adam Hitchcock (McMaster)
     PURPOSE:
    	Modification of display parameters used for ZSTACK.
    	Called by ZSTACK suite of procedures
     CATEGORY:
    	Data analysis.
     CALLING SEQUENCE:
    	zstack_display, subroutine, new_zoom=new_zoom
     INPUTS:
    	subroutine = name of zstack procedure from which zstack_display was invoked
    	filename_list,ev_list,msec_list,filename_display_list, and image_stack of zstack_common
    		must be previously defined via ZSTACK_ANALYZE.PRO
     KEYWORD PARAMETERS:
    	new_zoom = set to indicate a new image_zoom factor
     OUTPUTS:
    	NONE
    	x_shift, y_shift, corr_dim_stack, corr_stack, shifted_image_stack of zstack_align_common
    		are computed as output
     COMMON BLOCKS:
    	zstack_common	:
    		data_source				:	type of x-ray microscopy data: STXM:1, SXM:2, SM:3, ALS:4, POLY:5
    		data_directory				:	directory of data files
    		image_stack				:	3-D matrix of multiple x-ray microscope images
    		filename_list				:	list of filename corresponding to images in image_stack
    		ev_list					:	list of x-ray energies corresponding to images in image_stack
    		msec_list					:	list of dwell times corresponding to images in image_stack
    		filename_display_list			:	list of filename, x-ray energy, and dwell time corresponding to images in image_stack
    		displayed_file_index			:	index in image_stack, filename_list, msec_list, and filename_display_list currently being displayed or processed
    		n_files					:	number of images
    		list_filename				:	name of file to save or retrieve list of data files
    		shift_filename				:	filename of alignment shifts
    		x_shift					:	array of x-coordinate alignment shifts
    		y_shift					:	array of y-coordinate alignment shifts
    		data_shifted				:	0: data was not shifted and should not be clipped, 1: data was shifted and should be clipped, -1: denotes ZSTACK_PROFILE.PRO is being run as a stand-alone procedure
    		n_clipped_cols				:	number of columns in clipped image
    		n_clipped_rows				:	number of rows in clipped image
    		clipbox					:	vector of four points defining dimensions of region unclipped by alignment: [xleft,xright,ybot,ytop]
    	zstack_analyze_common
    		zstack_analyze_par			:	variables controlling ZSTACK Analyze dialog window
    		do_edge_clip				:	Clip edges of null data created by image alignment:	0: NO, 1: YES
    		do_despike					:	Despike data before alignment:	0: NO, 1: YES
    		do_median_filter			:	Median filter data before alignment:	0: NO, 1: YES
    		do_save_memory				:	Conserve memory by not creating duplicate arrays: 0: NO, 1: YES
    	zstack_buildlist_common
    		zstack_buildlist_par			:	variables controlling ZSTACK Buildlist dialog window
    		data_filelist				:	List of all data file within data_directory
    		this_filename				:	Name of currently selected data file
    		first_filename				:	Name of data file selected as the first file in sequence
    		last_filename				:	Name of data file selected as the last file in sequence
    		this_ev					:	X-ray energy of currently selected file
    		first_ev					:	X-ray energy of data file selected as the first file in sequence
    		last_ev					:	X-ray energy of data file selected as the last file in sequence
    		got_first					:	Logic control parameter: O: don't have first file, 1: have first file
    		got_last					:	Logic control parameter: O: don't have last file, 1: have last file
    		got_a_file					:	Logic control parameter: O: don't have a file, 1: have a file
    		delete_file_index			:	index of file to be deleted from list
    	zstack_align_common
    		zstack_align_par			:	variables controlling ZSTACK Align dialog window
    		file_num					:	vector of file numbers of image files
    		dragbox					:	vector of four points defining dimensions of region selected for alignment: [xleft,xright,ybot,ytop]
    		edge_enhance				:	edge enhancement parameter: 0: none, 1: sobel, 2: roberts
    		edgegauss_pixels			:	number of pixels used for edgeguass smoothing in ZSTACK_ALIGN_IMAGES.PRO, default = 3
    		edgefill					:	type of filling to occur at edges of shifted images: mean, median, max, min, zero
    		image_match				:	Image to align to: -1: preceding image, 0: constant image, 1: following image
    		constant_file_index			:	image of index to use as reference when aligning to a constant image
    		corr_max					:	0: use 3-pt fitted maximum of correlation function, 1: use center of mass of correlation function
    		maxshift					:	2-point vector of minimum and maximum values of x-shift and y_shift, and temp_x_shift and temp_y_shift within ZSTACK_ALIGN_TUNE
    		doalign_complete			:	-1: alignment in progress, 0: alignment not started, 1: alignment finished, 2	: using alignment from stored file
    		low_memory					:	Reflects keyword LOW_MEM: 0: use full memory allocation, 1: use reduced memory allocation
    		corr_stack					:	3-D matrix of correlation functions corresponding to image_stack
    		shifted_image_stack			:	3-D matrix of shifted images corresponding to image_stack
    		corr_dim_stack				:	3-D matrix (i,j,k) of maxima of correlation functions: i: x maximum, j: y maximum, k: image file
    		shift_threshold				:	mimimum shift required to actually shift the image
    	zstack_tune_common
    		zstack_tune_par				:	variables controlling ZSTACK Tune Alignment dialog window
    		temp_x_shift				:	vector of alignment shifts along x-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		temp_y_shift				:	vector of alignment shifts along y-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		init_x_shift				:	vector of initial alignment shifts along x-coordinate for images in image_stack
    		init_y_shift				:	vector of initial alignment shifts along y-coordinate for images in image_stack
    		image_center				:	array of pixel coordinates specifying the center (in pixels) of each image
    		corr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function image
    		shifted_center				:	array of pixel coordinates specifying the center (in pixels) of each shifted image
    		subimage_center				:	array of pixel coordinates specifying the center (in pixels) of each subimage
    		subcorr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function subimage
    		subshifted_center			:	array of pixel coordinates specifying the center (in pixels) of each shifted subimage
    		subimage_pixels				:	size of subimages in pixels
    		fid_pt					:	pixel coordinates of present fiducial point(s)
    		n_fid_pt					:	number of fiducial points
    		all_fid_pt					:	array of all fiducial points
    		fid_pt_index				:	index of fiducial point(s)
    	zstack_spectra_common
    		zstack_spectra_par			:	variables controlling ZSTACK Spectra dialog window
    		zstack_save_par				:	variables controlling ZSTACK Save dialog window
    		roi_index					:	vector of pixels corresponding to regions of interest for all i spectra
    		i_roi						:	vector of pixels corresponding to region of interest for current i spectrum
    		n_roi						:	number of regions of interest defined for i spectra
    		i0_roi					:	vector of pixels defining region of interest for i0 spectrum
    		is_i0_roi					:	Type of region of interest: 0: i0, 1: i
    		spectrum					:	2-D matrix (j,k) of spectra corresponding to defined regions of interest, j=0: i0 spectrum, j=1-14: i spectra, k corresponds to x-ray energy of image
    		save_spectra_type			:	Type of file to save spectra as:
    		spectra_filename_header		:	base filename of spectra and regions of interest to be saved on ZSTACK Spectra dialog window
    		roi_filename				:	filename for storage and retrieval of regions of interest points
    		save_filename_header			:	base filename of images to be saved on ZSTACK Save dialog window
    		i0_filename				:	base filename of i0 spectrum to be retrieved
    		i0_filetype				:	Type of file of retrieved I0 spectrum:	RAW, XAS, CSV
    		i_roi_color_index			:	vector of indices of colors for display of regions of interest for i spectra
    		i0_roi_color_index			:	color index for display of region of interest for i0 spectrum
    		nonintegral_zoom_data			:	scaled byte image used when image_zoom is non-integral
    	zstack_profile_common
    		zstack_profile_par			:	variables controlling ZSTACK Profile dialog window
    		profile_direction			:	0: along the column direction, 1: along the row direction
    		profile_pixel				:	pixel actively used to generate profile image and plot
    		profile_x_pixel				:	x pixel used to construct profile image
    		profile_y_pixel				:	y pixel used to construct profile image
    		profile_win_pixels			:	number of pixels for profile image window
    		profile_image				:	image of profile intensity and image number
    		profile_spectrum			:	spectrum arising from single pixel at center of cursor crosshairs in profile image
    		profile_y_min				:	mimimum of all profile spectra
    		profile_y_max				:	maximum of all profile spectra
    		profile_filename_header		:	base filename of profile intensity plot to be saved on ZSTACK Profile dialog window
    		profile_filename			:	filename of profile intensity plot to be saved on ZSTACK Profile dialog window
    		spectrum_filename_header		:	base filename of profile spectrum to be saved on ZSTACK Profile dialog window
    		spectrum_filename			:	filename of profile spectrum to be saved on ZSTACK Profile dialog window
    		spectra_filename			:	filename of profile spectra to be saved on ZSTACK Profile dialog window
    		profile_use				:	0: ZSTACK_PROFILE used as a subroutine, 1: ZSTACK_PROFILE used as a stand-alone application
    	zstack_display_common
    		zstack_plot_par			:	variables controlling ZSTACK Display dialog window
    		image_zoom					:	zoom factor for displaying images
    		subimage_zoom				:	zoom factor for subimages
    		movie_delay				:	delay used to display movie images of data stacks, dependent upon machine speed
    		disp_min					:	minimum percentage intensity for display of images
    		disp_max					:	maximum percentage intensity for display of images
    		disp_gamma					:	gamma factor for display of images
    		spectrum_display			:	Display spectra as: 1: Single Beam, 2: Percent Transmittance, 3: Absorbance
    		spectrum_offset				:	Offset used to plot spectra
    		init_zoom					:	initial zoom factor for displaying images (used in ZSTACK_SAVE and ZSTACK_TUNE)
    		movie_active				:	movie of images is active: 0: NO, 1: YES
    		profile_zoom				:	zoom factor for file number axis on profile images
    		image_range				:	scale images using: 0: intensity range of each image, 1: intensity range of full image stack
    		image_ratio				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		ratio_image_index			:	index of image to use when ratio images to a constant image
    		image_scale				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		image_invert				:	invert color bar: 0: NO, 1: YES
    		temp_old_display			:	initial array of display parameters, set at beginning of ZSTACK_DISPLAY
    		temp_new_display			:	array of display parameters updated as display options are changed
    		zstack_subroutine			:	subroutine from which ZSTACK_DISPLAY was called
    		plot_x_min					:	mimimum x-value to plot shifts or spectra
    		plot_x_max					:	maximum x-value to plot shifts or spectra
    		plot_y_min					:	mimimum y-value to plot shifts or spectra
    		plot_y_max					:	maximum y-value to plot shifts or spectra
    		x_autoscale				:	autoscale x-values on plots of shifts or spectra: 0: NO, 1: YES
    		y_autoscale				:	autoscale y-values on plots of shifts or spectra: 0: NO, 1: YES
    	zstack_color_common
    		bottom_color_index			:	index of lowermost color of gradient colorscale
    		top_color_index				:	index of uppermost color of gradient colorscale
    		black_color_index			:	index of black color
    		white_color_index			:	index of white color
    		plot_bkgd_color_index			:	color index for plot background, either black or white
    		plot_axes_color_index			:	color index for plot axes, either whilte or black
    		image_border_color_index		:	color index for image border in zstack_buildlist and zstack_profile dialog windows
    		dragbox_color_index			:	color index for dragbox used to define subregion for alignment
    		corr_ctr_color_index			:	color index for crosshair showing center of correlation function
    		corr_max_color_index			:	color index for crosshair showing maximum of correlation function
    		x_shift_color_index			:	color index for plotting of x-shift
    		y_shift_color_index			:	color index for plotting of y-shift
    		shift_cursor_color_index		:	color index for cursor in shift plot, indicating file number
    		tune_fiducial_color_index		:	color index for fiducial points in closeup of shifted image in zstack_tune dialog window
    		spectra_color_index			:	color indices (14) for plotting of spectra
    		spectra_cursor_color_index		:	color index for cursor in spectra plot, indicating x-ray energy
    		profile_color_index			:	color index for plotting of intensity profile and cursor in profile image indicating row or column
    		profile_cursor_color_index		:	color index for cursor in profile image, indicating x-ray energy
    		profile_spectrum_color_index	:	color index for plotting of profile spectrum
    		test1_color_index			:	color index #1 for testing
    		test2_color_index			:	color index #2 for testing
    		test3_color_index			:	color index #3 for testing
     SIDE EFFECTS:

     RESTRICTIONS:
    	Used as ZSTACK suite of routines
     PROCEDURE:
    	Called by ZSTACK_ALIGN.PRO, ZSTACK_BUILDLIST.PRO, ZSTACK_PROFILE.PRO,
    			ZSTACK_SAVE.PRO, ZSTACK_SPECTRA.PRO, ZSTACK_TUNE.PRO
     EXAMPLE:

     MODIFICATION HISTORY:

     (13oct00 cgz) altered definition of dragbox so that it is now [xleft,xright,ybot,ytop]
    		this makes it consistent with definition of other cursor boxes
    		and eliminates need for min and max testing
    		Changed logic statement from:	IF ((dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    							to:	IF ((dragbox(1) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN

     (29oct00 cgz) several modifications to be compatible with new version of zstack_save
     (05nov00 cgz) modified widget to include more choices on control, added image, spectral, and stack subtraction, not fully implemented
    				will be able to use any image, any spectrum for normalization
    			modified names of image normalization variables
    			modified values of image_ratio
     (28nov00 cgz) migrated zstack_display_colorbar routine to zstack_analyze.pro
     (23-may-04 aph) force color scale, 0 when plotting
     (21-mar-08 MJ)  changed to work on unix (Xscroll_size)
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS

(See c:\axis2000\zstack_plot.pro)

## ZSTACK_SAVE.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	ZSTACK_SAVE.PRO

     LAST CHANGED: ----------------------------------- 13-Apr-08 (aph from 03-Mar-08 (MJ))

     PURPOSE:
    	Save images after alignment using ZSTACK_ANALYZE
     AUTHORS:
    	Carl G. Zimba (Photons UnLimited),
    	Partially derived from previous code by Chris Jacobsen (SUNY - Stonybrook)
     CATEGORY:
    	Data analysis.
     CALLING SEQUENCE:
    	zstack_save
     INPUTS:
    	NONE
     KEYWORD PARAMETERS:
    	NONE
     OUTPUTS:
    	NONE
     COMMON BLOCKS:
    	zstack_common	:
    		data_source				:	type of x-ray microscopy data: STXM:1, SXM:2, SM:3, ALS:4, POLY:5
    		data_directory				:	directory of data files
    		image_stack				:	3-D matrix of multiple x-ray microscope images
    		filename_list				:	list of filename corresponding to images in image_stack
    		ev_list					:	list of x-ray energies corresponding to images in image_stack
    		msec_list					:	list of dwell times corresponding to images in image_stack
    		filename_display_list			:	list of filename, x-ray energy, and dwell time corresponding to images in image_stack
    		displayed_file_index			:	index in image_stack, filename_list, msec_list, and filename_display_list currently being displayed or processed
    		n_files					:	number of images
    		list_filename				:	name of file to save or retrieve list of data files
    		shift_filename				:	filename of alignment shifts
    		x_shift					:	array of x-coordinate alignment shifts
    		y_shift					:	array of y-coordinate alignment shifts
    		data_shifted				:	0: data was not shifted and should not be clipped, 1: data was shifted and should be clipped, -1: denotes ZSTACK_PROFILE.PRO is being run as a stand-alone procedure
    		n_clipped_cols				:	number of columns in clipped image
    		n_clipped_rows				:	number of rows in clipped image
    		clipbox					:	vector of four points defining dimensions of region unclipped by alignment: [xleft,xright,ybot,ytop]
    		dragbox					:	vector of four points defining dimensions of region selected by box_cursor: [xleft,xright,ybot,ytop]
    	zstack_spectra_common
    		zstack_spectra_par			:	variables controlling ZSTACK Spectra dialog window
    		zstack_save_par				:	variables controlling ZSTACK Save dialog window
    		roi_index					:	vector of pixels corresponding to regions of interest for all i spectra
    		i_roi						:	vector of pixels corresponding to region of interest for current i spectrum
    		n_roi						:	number of regions of interest defined for i spectra
    		i0_roi					:	vector of pixels defining region of interest for i0 spectrum
    		is_i0_roi					:	Type of region of interest: 0: i0, 1: i
    		spectrum					:	2-D matrix (j,k) of spectra corresponding to defined regions of interest, j=0: i0 spectrum, j=1-14: i spectra, k corresponds to x-ray energy of image
    		save_spectra_type			:	Type of file to save spectra as:
    		spectra_filename_header		:	base filename of spectra and regions of interest to be saved on ZSTACK Spectra dialog window
    		roi_filename				:	filename for storage and retrieval of regions of interest points
    		save_filename_header			:	base filename of images to be saved on ZSTACK Save dialog window
    		i0_filename				:	base filename of i0 spectrum to be retrieved
    		i0_filetype				:	Type of file of retrieved I0 spectrum:	RAW, XAS, CSV
    		i_roi_color_index			:	vector of indices of colors for display of regions of interest for i spectra
    		i0_roi_color_index			:	color index for display of region of interest for i0 spectrum
    		nonintegral_zoom_data			:	scaled byte image used when image_zoom is non-integral
    	zstack_display_common
    		zstack_display_par			:	variables controlling ZSTACK Display dialog window
    		image_zoom					:	zoom factor for displaying images
    		subimage_zoom				:	zoom factor for subimages
    		movie_delay				:	delay used to display movie images of data stacks, dependent upon machine speed
    		disp_min					:	minimum percentage intensity for display of images
    		disp_max					:	maximum percentage intensity for display of images
    		disp_gamma					:	gamma factor for display of images
    		spectrum_display			:	Display spectra as: 1: Single Beam, 2: Percent Transmittance, 3: Absorbance
    		spectrum_offset				:	Offset used to plot spectra
    		init_zoom					:	initial zoom factor for displaying images (used in ZSTACK_SAVE and ZSTACK_TUNE)
    		movie_active				:	movie of images is active: 0: NO, 1: YES
    		profile_zoom				:	zoom factor for file number axis on profile images
    		image_range				:	scale images using: 0: intensity range of each image, 1: intensity range of full image stack
    		image_ratio				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		ratio_image_index			:	index of image to use when ratio images to a constant image
    		image_scale				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		image_invert				:	invert color bar: 0: NO, 1: YES
    		temp_old_display			:	initial array of display parameters, set at beginning of ZSTACK_DISPLAY
    		temp_new_display			:	array of display parameters updated as display options are changed
    		zstack_subroutine			:	subroutine from which ZSTACK_DISPLAY was called
    		plot_x_min					:	mimimum x-ray energy value to plot spectra
    		plot_x_max					:	maximum x-ray energy value to plot spectra
    		plot_y_min					:	mimimum intensity value to plot spectra
    		plot_y_max					:	maximum intensity value to plot spectra
    		x_autoscale				:	autoscale x-ray energy scale: 0: NO, 1: YES
    		y_autoscale				:	autoscale spectra intensity scale: 0: NO, 1: YES
    	zstack_color_common
    		bottom_color_index			:	index of lowermost color of gradient colorscale
    		top_color_index				:	index of uppermost color of gradient colorscale
    		black_color_index			:	index of black color
    		white_color_index			:	index of white color
    		plot_bkgd_color_index			:	color index for plot background, either black or white
    		plot_axes_color_index			:	color index for plot axes, either whilte or black
    		image_border_color_index		:	color index for image border in zstack_buildlist and zstack_profile dialog windows
    		dragbox_color_index			:	color index for dragbox used to define subregion for alignment
    		corr_ctr_color_index			:	color index for crosshair showing center of correlation function
    		corr_max_color_index			:	color index for crosshair showing maximum of correlation function
    		x_shift_color_index			:	color index for plotting of x-shift
    		y_shift_color_index			:	color index for plotting of y-shift
    		shift_cursor_color_index		:	color index for cursor in shift plot, indicating file number
    		tune_fiducial_color_index		:	color index for fiducial points in closeup of shifted image in zstack_tune dialog window
    		spectra_color_index			:	color indices (14) for plotting of spectra
    		spectra_cursor_color_index		:	color index for cursor in spectra plot, indicating x-ray energy
    		profile_color_index			:	color index for plotting of intensity profile and cursor in profile image indicating row or column
    		profile_cursor_color_index		:	color index for cursor in profile image, indicating x-ray energy
    		profile_spectrum_color_index	:	color index for plotting of profile spectrum
    		test1_color_index			:	color index #1 for testing
    		test2_color_index			:	color index #2 for testing
    		test3_color_index			:	color index #3 for testing
     SIDE EFFECTS:

     RESTRICTIONS:

     PROCEDURE:
       Called from within ZSTACK_SPECTRA.PRO.
     EXAMPLE:

     MODIFICATION HISTORY:
       25-Mar-1998 - now works with 24 bit graphics, CJJ
       24-Jul-1998 - two changes (based on suggestions by Adam
         Hitchcock, but the implementations here are my own) CJJ :
         1. allow user to read in i0 files from an ascii file of
            (line by line) values of ev, khz.  The file is used
            only if it spans a larger range of eV values than the
            images in the stack span.
         2. Click on the spectrum to change the file which is displayed
       14-Aug-1998 - now if there's an alignment file, read it in and
         apply it but STILL give the user the chance to align the stack.
         This allows one to (for example) first align a stack manually,
         and then do an automatic alignment over a restricted shift
         range to "refine" the alignment. CJJ
       28-Aug-1998: with IDL 5.1 the way 24 bit graphics is handled is
         now different - need to invoke device,decomposed=0, CJJ
       31-Aug-1998: Allow saving and reading of stack files as XDR data,
         don't read ROI file by default on startup, use zoom=1 unless
         explicitly told otherwise, have alignment shifts saved by
         this program rather than by alignment programs, allow clipping
         of data to exclude shift boundaries, CJJ
       27-sep-1998: but tvrd() works differently on different devices
         so need to write images for GIF files to Z buffer, CJJ
       13-oct-1998: Save many images at once, start to work on
         ratio image stuff, CJJ

     Modified 20feb99, CGZ
     Extensively modified and rewritten STACK_ANALYZE.PRO to form ZSTACK_ANALYZE.PRO
     Changes and additions are numerous:

     All procedures and common variables starting with 'stk' were changed to 'zstack'
     so that the existing routine, STACK_ANALYZE.PRO, can be run in parallel

     Reorganized STACK_ANALYZE.PRO so that
    	spectral analysis is done with ZSTACK_SPECTRA and zstack_spectra_* procedures
    		spectra and regions of interest are saved with ZSTACK_SPECTRA
    	saving of image data is done with ZSTACK_SAVE and ZSTACK_SAVE_* procedures

     Procedures have been modified, added, eliminated as below:
    	zstack_save_prep		:	formerly stk_anl_graphics
    	zstack_save_imgdisp		:	formerly stk_anl_imgdisp
    	zstack_save_plotspectrum	:	formerly stk_anl_plotspectrum
    	zstack_save_clip_data		:	formerly stk_anl_clipdata
    	zstack_save_desensitive	:	new, adapted from stk_anl_desensitive
    	zstack_save_sensitive		:	new, adapted from stk_anl_sensitive
    	zstack_save_gifimage		:	stk_anl_savegifimg
    	zstack_save_gifmovie		:	stk_anl_gifmovie
    	zstack_save_stack_data	:	formerly stk_dat_savefile
    	zstack_save_event		:	new, adapted from stk_anl_event
    	zstack_save			:	new, adapted from stack_analyze
    	stk_aln_savefile		:	eliminated, moved to ZSTACK_ALIGN.PRO (zstack_align_save_shift)
    	stk_dat_readfile		:	eliminated
    	stk_anl_readroi			:	eliminated
    	stk_anl_roi_event		:	eliminated, replace with CW_DEFROI.PRO
    	stk_anl_roi			:	eliminated, replace with CW_DEFROI.PRO

     Functions of procedures are now:
    	zstack_save_prep		:	sets color table and color indices and defines common variables
    	zstack_save_imgdisp		:	displays images and shift plot
    	zstack_save_plotspectrum	:	displays extracted spectra
    	zstack_save_clip_data		:	defines area of images not clipped by alignment shift
    	zstack_save_desensitive	:	deactivate features on Stack Save dialog window
    	zstack_save_sensitive		:	activate features on Stack Save dialog window
    	zstack_save_gifimage		:	save *.gif image of stack data
    	zstack_save_gifmovie		:	save *m.gif movie of stack data
    	zstack_save_stack_data	:	save stack data as file (for both clipped and unclipped)
    	zstack_save_event		:	event routine for zstack_save
    	zstack_save			:	main procedure for saving images and stack data sets

     Modified user interface window to include
    	display and movie of image and clipped image
    		regions of interest are plotted on both image and clipped image
    		cursor bar added to plot of spectra highlighting energy and intensity position
    			during movie or static display
    		eliminated text embedded in image, replaced it with text fields in dialog window
    	displayed file can be selected either using file list or spectral plot
    		clicking on spectral plot, prints file info and spectral intensity in Output Log
    	text fields added to display image information during movie or static display
    		this replaces text as part of image implemented in STACK_ANALYZE.PRO
    	eliminated "Add I Pixel" and "Add I0 Pixel" since it is embedded part of CW_DEFROI.PRO
    	eliminated ratio image feature - may restore later
    	eliminated IDL Slicer feature - may restore later
    	"Load New Color Table" option added
    		can change the color table in either ZSTACK_SPECTRA, ZSTACK_SAVE, or ZSTACK_PROFILE
    	saving of spectra in multiple formats: *.xas, *.spc, *.gif
    	added ability to extract spectra from multiple regions simultaneously (up to 14 spectra)

     Replaced stk_anl_roi and stk_anl_roi_event with CW_DEFROI.PRO
    	New routine is shipped with IDL and is more robust on multiple platforms
    	Allow selection of regions of interest as polygon, single point, rectangle, or circle

     Changed the way the color table is specified:
    	- calls ZSTACK_COLOR.PRO from within zstack_save_prep
    	- much simpler now, only executed once, allows multiple colors easily

     Deleted unused variables
    	char_ypix,charsize,textregion_nlines,textregion_ypix,
    	i_images_color_index,i0_images_color_index,i0_images_list,i_images_list

     Renamed ev to ev_list, and msec to msec_list

     Added option for data from Polymer STXM
    	/poly keyword and stxm1_sxm2_sm3_als4_poly5 variable
    	Made stxm1_sxm2_sm3_als4_poly5 part of zstack_common variable

     Modified Stack Save dialog window for 3 columns, including a long list of image files

     Modified COMMON block structure so that common variables are shared with all zstack routines
    	i.e., zstack_common contains variables used by
    		ZSTACK_ANALYZE.PRO, ZSTACK_READLIST.PRO, ZSTACK_BUILDLIST.PRO, and ZSTACK_ALIGN.PRO
     Common variables are now defined only once in each file (in zstack_save_prep), not repetitively as before.
     Common variables for data are now determined within ZSTACK_BUILDLIST.PRO or ZSTACK_READLIST.PRO:
    	image_stack, filename_list, ev_list, msec_list, filename_display_list
    	This requires that files be read only once, eliminated time-intensive duplicate calls of
    		STXM_READ.PRO or SXM_READ.PRO

     Modified zstack_save_par
    	so that they only contain only variables associated with dialog window.
    	All other variables have been moved to zstack_analyze_common

     Moved list_filename and shift_filename variables to zstack_common variable
     Added n_files variable to zstack_common variable
     Header with list_filename and shift_filename now wriiten as part of *.spc and *.roi files

     Ratio of image to I0 spectrum appears to be useless
    	Previously, some slight variation in image contrast was present
    	but was likely due to the way the percent_image was computed:
    	Former:	percent_image = 100. * image_stack(*,*,i_file) / max(image_stack(*,*,i_file))
    					(via obsolete invmax_image_stack variable)
    		which didn't scale image intensity accurately between 0 and 100
    	Now:		this_image = image_stack(*,*,i_file) / min(image_stack(*,*,i_file))
    			percent_image = 100. * this_image / max(this_image)
    		which forces image intensity to be accurately scaled between 0 and 100
    	So eliminate 'ratio image to i0 spectrum' option
    	Explore possibility of displaying image using log or exp scale, in addition to present linear scale

     Modified zstack_save_stack_data procedure to save image stack (*.stk)
    	Saved image stack has a format slightly different from CJJ code since it includes the filename_list
    		so the file structure of the two different file formats makes them incompatible

     (05oct00 cgz)
    	Modified dialog widget to include capability to select subregion,
    		better capability to select various formats to save data as image, movie, binary
    	Created zstack_save_common to include variables for saving various image and movie formats
    		Moved zstack_save_par and save_filename_header from zstack_spectra_common
    		Moved dragbox from zstack_align_common to zstack_common
    			so that it can be used in zstack_save to select subregion of interest
    		Modified other zstack procedures to conform

     (06oct00 cgz)
    	Added capability to specify a subregion using a dragbox routine

     (13oct00 cgz) altered definition of dragbox so that it is now [xleft,xright,ybot,ytop]
    		this makes it consistent with definition of other cursor boxes
    		and eliminates need for min and max testing
    		Changed logic statement from:	IF ((dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    							to:	IF ((dragbox(1) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
     (06nov00 cgz)
    	Added button to invoke IDL Slicer with full (unclipped) aligned image stack
     (28nov00 cgz) migrated zstack_profile_colorbar routine to zstack_analyze.pro
     ===============================================================================
     (22feb02 aph) replace cgz modified code with write_sb call for binary stack
     -------- DONE in the zstack_jan01 version (axis_dev)
     (11-jul-04 aph) try to get save images panel to work correctly
    	- mpeg and mgif do not work un der IDL 6.0 (license inhibit)
    	- replace write_gif with write_tiff - does not display image; inverted
     --------
     (16jul04 aph) fix 'invalid widget error' - needed to add CONDITIONAL: IF (data_shifted EQ 1)
    			 on zstack_save_par.clipped_image_label sensitive and desensitive lines
                    convert to write sequence of tif files for  movie generation
     (03-Mar-08 MJ) Keyword /SCROLL in widget_base() needs X_SCROLL_SIZE.
                    Use of /SCROLL and /MODAL at the same time not allowed.
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS

(See c:\axis2000\zstack_save.pro)

## ZSTACK_SPECTRA.PRO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	ZSTACK_SPECTRA.PRO

     LAST CHANGED: ----------------------------------- 13-Apr-08 (aph from 03-Mar-08 (MJ))

     AUTHORS:
    	Carl G. Zimba (NIST), Chris Jacobsen (SUNY - Stonybrook)
     PURPOSE:
    	Analysis of images and spectra abtained from a series of images from an x-ray microscope.
     CATEGORY:
    	Data analysis.
     CALLING SEQUENCE:
    	zstack_spectra
     INPUTS:
    	NONE
     KEYWORD PARAMETERS:
    	NONE
     OUTPUTS:
    	NONE
     COMMON BLOCKS:
    	zstack_common	:
    		image_stack			:	3-D matrix of multiple x-ray microscope images
    		filename_list			:	list of filename corresponding to images in image_stack
    		ev_list				:	list of x-ray energies corresponding to images in image_stack
    		msec_list				:	list of dwell times corresponding to images in image_stack
    		filename_display_list		:	list of filename, x-ray energy, and dwell time corresponding to images in image_stack
    		displayed_file_index		:	index in image_stack, filename_list, msec_list, and filename_display_list currently being displayed or processed
    		data_source			:	type of x-ray microscopy data: STXM:1, SXM:2, SM:3, ALS:4, POLY:5
    		image_zoom				:	zoom factor for displaying images
    		init_zoom				:	initial zoom factor for displaying images (used in ZSTACK_SAVE and ZSTACK_TUNE)
    		disp_min				:	minimum percentage intensity for display of images
    		disp_max				:	maximum percentage intensity for display of images
    		disp_gamma				:	gamma factor for display of images
    		movie_delay			:	delay used to display movie images of data stacks
    		n_files				:	number of images
    		list_filename			:	filename of image list
    		shift_filename			:	filename of alignment shifts
    		x_shift				:	array of x-coordinate alignment shifts
    		y_shift				:	array of y-coordinate alignment shifts
    	zstack_analyze_common			:
    		zstack_spectra_par			:	variables controlling ZSTACK Spectra dialog window
    		zstack_save_par			:	variables controlling ZSTACK Save dialog window
    		roi_index				:	vector of pixels corresponding to regions of interest for all i spectra
    		i_roi					:	vector of pixels corresponding to region of interest for current i spectrum
    		n_roi					:	number of regions of interest defined for i spectra
    		i0_roi				:	vector of pixels defining region of interest for i0 spectrum
    		is_i0_roi				:	Type of region of interest: 0: i0, 1: i
    		image_scale			:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		image_ratio			:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		ratio_image_index		:	index of image to use when ratio images to a constant image
    		spectrum				:	2-D matrix (j,k) of spectra corresponding to defined regions of interest, j=0: i0 spectrum, j=1-14: i spectra, k corresponds to x-ray energy of image
    		save_spectra_type		:	Type of file to save spectra as:
    		spectra_filename_header	:	base filename of spectra and regions of interest to be saved on ZSTACK Spectra dialog window
    		save_filename_header		:	base filename of images to be saved on ZSTACK Save dialog window
    		i0_filename			:	base filename of i0 spectrum tp be retrieved
    		i0_filetype			:	Type of file of retrieved I0 spectrum:	RAW, XAS, SPC
    		i_roi_color_index		:	vector of indices of colors for display of regions of interest for i spectra
    		i0_roi_color_index		:	color index for display of region of interest for i0 spectrum
    		data_shifted			:	0: data was not shifted and should not be clipped, 1: data was shifted and should be clipped, -1: denotes ZSTACK_PROFILE.PRO is being run as a stand-alone procedure
    		n_clipped_cols			:	number of columns in clipped image
    		n_clipped_rows			:	number of rows in clipped image
    		clipbox				:	vector of four points defining dimensions of region unclipped by alignment: [xleft,xright,ybot,ytop]
    		do_edge_clip			:	Clip edges of null data created by image alignment:	0: NO, 1: YES
    		init_zoom				:	intial value of image zoom factor
    	zstack_color_common
    		bottom_color_index		:	index of lowermost color of gradient colorscale
    		top_color_index			:	index of uppermost color of gradient colorscale
    		black_color_index		:	index of black color
    		white_color_index		:	index of white color
    		blue_color_index		:	index of blue color
    		red_color_index			:	index of red color
    		green_color_index		:	index of green color
    		cyan_color_index		:	index of cyan color
    		magenta_color_index		:	index of magenta color
    		yellow_color_index		:	index of yellow color
    		lime_color_index		:	index of lime green color
    		gold_color_index		:	index of gold color
    		rose_color_index		:	index of rose color
    		yelgrn_color_index		:	index of yellow-green color
    		purple_color_index		:	index of purple color
    		orange_color_index		:	index of orange color
    		sky_color_index			:	index of sky blue color
    		beige_color_index		:	index of beige color
     SIDE EFFECTS:

     RESTRICTIONS:

     PROCEDURE:
       Called from within ZSTACK_ANALYZE.PRO.
     EXAMPLE:

     MODIFICATION HISTORY:
       25-Mar-1998 - now works with 24 bit graphics, CJJ
       24-Jul-1998 - two changes (based on suggestions by Adam
         Hitchcock, but the implementations here are my own) CJJ :
         1. allow user to read in i0 files from an ascii file of
            (line by line) values of ev, khz.  The file is used
            only if it spans a larger range of eV values than the
            images in the stack span.
         2. Click on the spectrum to change the file which is displayed
       14-Aug-1998 - now if there's an alignment file, read it in and
         apply it but STILL give the user the chance to align the stack.
         This allows one to (for example) first align a stack manually,
         and then do an automatic alignment over a restricted shift
         range to "refine" the alignment. CJJ
       28-Aug-1998: with IDL 5.1 the way 24 bit graphics is handled is
         now different - need to invoke device,decomposed=0, CJJ
       31-Aug-1998: Allow saving and reading of stack files as XDR data,
         don't read ROI file by default on startup, use zoom=1 unless
         explicitly told otherwise, have alignment shifts saved by
         this program rather than by alignment programs, allow clipping
         of data to exclude shift boundaries, CJJ
       27-sep-1998: but tvrd() works differently on different devices
         so need to write images for GIF files to Z buffer, CJJ
       13-oct-1998: Save many images at once, start to work on
         ratio image stuff, CJJ

     Modified 20feb99, CGZ
     Extensively modified and rewritten STACK_ANALYZE.PRO to form ZSTACK_ANALYZE.PRO
     Changes and additions are numerous:

     All procedures and common variables starting with 'stk' were changed to 'zstack'
     so that the existing routine, STACK_ANALYZE.PRO, can be run in parallel

     Reorganized STACK_ANALYZE.PRO so that
    	spectral analysis is done with ZSTACK_SPECTRA and zstack_spectra_* procedures
    		spectra and regions of interest are saved with ZSTACK_SPECTRA
    	saving of image data is done with ZSTACK_SAVE and ZSTACK_SAVE_* procedures

     Procedures have been modified, added, eliminated as below:
    	zstack_spectra_prep			:	formerly stk_anl_graphics
    	zstack_spectra_imgdisp		:	formerly stk_anl_imgdisp
    	zstack_spectra_plotspectrum	:	formerly stk_anl_plotspectrum
    	zstack_spectra_makespectrum	:	formerly stk_anl_makespectrum
    	zstack_spectra_clip_data		:	formerly stk_anl_clipdata
    	zstack_spectra_desensitive		:	new, adapted from stk_anl_desensitive
    	zstack_spectra_sensitive		:	new, adapted from stk_anl_sensitive
    	zstack_spectra_save_spec		:	new, enhanced from stk_anl_savexas
    	zstack_spectra_save_roi		:	formerly stk_anl_writeroi
    	zstack_spectra_roi			:	formerly stk_anl_roi
    	zstack_spectra_get_i0_file		:	new, enhanced from stack_analyze_event subroutine
    	zstack_spectra_event			:	new, adapted from stk_anl_event
    	zstack_spectra				:	new, adapted from stack_analyze
    	stk_aln_savefile			:	eliminated, moved to ZSTACK_ALIGN.PRO (zstack_align_save_shift)
    	stk_dat_readfile			:	eliminated
    	stk_anl_readroi				:	eliminated
    	stk_anl_roi_event			:	eliminated, replace with CW_DEFROI.PRO
    	stk_anl_roi				:	eliminated, replace with CW_DEFROI.PRO

     Functions of procedures are now:
    	zstack_spectra_prep			:	sets color table and color indices and defines common variables
    	zstack_spectra_imgdisp		:	displays images and shift plot
    	zstack_spectra_plotspectrum	:	displays extracted spectra
    	zstack_spectra_makespectrum	:	computes spectra from image intensities within regions of interest
    	zstack_spectra_clip_data		:	defines area of images not clipped by alignment shift
    	zstack_spectra_desensitive		:	deactivate features on Stack Spectra dialog window
    	zstack_spectra_sensitive		:	activate features on Stack Spectra dialog window
    	zstack_spectra_save_spec		:	save extracted spectra in a variety of formats
    	zstack_spectra_save_roi		:	save regions of interest for spectral extraction
    	zstack_spectra_roi			:	define regions of interest for spectral extraction
    	zstack_spectra_get_i0_file		:	new, enhanced from stack_analyze_event subroutine
    	zstack_spectra_event			:	event routine for zstack_spectra
    	zstack_spectra				:	main procedure for extracting spectra from stack

     Modified user interface window to include
    	display and movie of image and clipped image
    		regions of interest are plotted on both image and clipped image
    		cursor bar added to plot of spectra highlighting energy and intensity position
    			during movie or static display
    		eliminated text embedded in image, replaced it with text fields in dialog window
    	displayed file can be selected either using file list or spectral plot
    		clicking on spectral plot, prints file info and spectral intensity in Output Log
    	text fields added to display image information during movie or static display
    		this replaces text as part of image implemented in STACK_ANALYZE.PRO
    	eliminated "Add I Pixel" and "Add I0 Pixel" since it is embedded part of CW_DEFROI.PRO
    	eliminated ratio image feature - may restore later
    	eliminated IDL Slicer feature - may restore later
    	"Load New Color Table" option added
    		can change the color table in either ZSTACK_SPECTRA, ZSTACK_SAVE, or ZSTACK_PROFILE
    	saving of spectra in multiple formats: *.xas, *.spc, *.gif
    	added ability to extract spectra from multiple regions simultaneously (up to 14 spectra)

     Replaced stk_anl_roi and stk_anl_roi_event with CW_DEFROI.PRO
    	New routine is shipped with IDL and is more robust on multiple platforms
    	Allow selection of regions of interest as polygon, single point, rectangle, or circle

     Changed the way the color table is specified:
    	- calls ZSTACK_COLOR.PRO from within zstack_spectra_prep
    	- much simpler now, only executed once, allows multiple colors easily

     Deleted unused variables
    	char_ypix,charsize,textregion_nlines,textregion_ypix,
    	i_images_color_index,i0_images_color_index,i0_images_list,i_images_list

     Renamed ev to ev_list, and msec to msec_list

     Added option for data from Polymer STXM
    	/poly keyword and stxm1_sxm2_sm3_als4_poly5 variable
    	Made stxm1_sxm2_sm3_als4_poly5 part of zstack_common variable

     Modified Stack Spectra dialog window for 3 columns, including a long list of image files

     Modified COMMON block structure so that common variables are shared with all zstack routines
    	i.e., zstack_common contains variables used by
    		ZSTACK_ANALYZE.PRO, ZSTACK_READLIST.PRO, ZSTACK_BUILDLIST.PRO, and ZSTACK_ALIGN.PRO
     Common variables are now defined only once in each file (in zstack_spectra_prep), not repetitively as before.
     Common variables for data are now determined within ZSTACK_BUILDLIST.PRO or ZSTACK_READLIST.PRO:
    	image_stack, filename_list, ev_list, msec_list, filename_display_list
    	This requires that files be read only once, eliminated time-intensive duplicate calls of
    		STXM_READ.PRO or SXM_READ.PRO

     Modified zstack_spectra_par, and zstack_save_par
    	so that they only contain only variables associated with dialog window.
    	All other variables have been moved to zstack_analyze_common

     Modified ZSTACK_SAVE_SPEC_SAVE to better utilize save_spectra_type variable
     Moved list_filename and shift_filename variables to zstack_common variable
     Added n_files variable to zstack_common variable
     Header with list_filename and shift_filename now wriiten as part of *.spc and *.roi files

     Ratio of image to I0 spectrum appears to be useless
    	Previously, some slight variation in image contrast was present
    	but was likely due to the way the percent_image was computed:
    	Former:	percent_image = 100. * image_stack(*,*,i_file) / max(image_stack(*,*,i_file))
    					(via obsolete invmax_image_stack variable)
    		which didn't scale image intensity accurately between 0 and 100
    	Now:		this_image = image_stack(*,*,i_file) / min(image_stack(*,*,i_file))
    			percent_image = 100. * this_image / max(this_image)
    		which forces image intensity to be accurately scaled between 0 and 100
    	So eliminate 'ratio image to i0 spectrum' option
    	Explore possibility of displaying image using log or exp scale, in addition to present linear scale

     Added x and y offsets to zstack_spectra dialog window
    		so that cw_defroi window will be apparent, 30sep99 CGZ
     Minor modifications of sensitive attribute of widget controls for better dialog window

     (06oct00 cgz)
    	Created zstack_save_common to include variables for saving various image and movie formats
    		Moved zstack_save_par and save_filename_header from zstack_spectra_common
    		Modified zstack_spectra.pro to conform
     (26oct00 cgz)
    	Added button to invoke IDL Slicer with full (unclipped) aligned image stack
     (31oct00 cgz)
    		Modified zstack_buildlist_savelist to include dialog_pickfile so directory can be selected
    		Replaced platform-dependent code with call to zstack_analyze_extract_filename
     (06nov00 cgz)
    	Moved button to invoke IDL Slicer to zstack_save widget
     (28nov00 cgz) migrated zstack_profile_colorbar routine to zstack_analyze.pro
     (24-feb-01 aph) add on_error,2 to each procedure
     (02-may-04 aph) commented out 'zstack_to_axis' ; added loadct, 0 to try to avoid color scale problems
     (06jul05 aph) add color-restore button
     (04-Sep-07 aph) track down why Zstack_spectra occasionally did not display spectra
          - due to ev_list being a string [in some cases ??] and the min / max not working properly on strings
     (03-Mar-08 MJ) Keyword /SCROLL in widget_base() needs X_SCROLL_SIZE.
                    Use of /SCROLL and /MODAL at the same time not allowed.
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS

(See c:\axis2000\zstack_spectra.pro)

## ZSTACK_TUNE.PRO

[Previous Routine] [List of Routines]

     NAME:
    	ZSTACK_TUNE.PRO

     LAST CHANGED: ----------------------------------- 13-Apr-08 (aph from 03-Mar-08 (MJ))

     AUTHORS:
    	Carl G. Zimba (NIST), Chris Jacobsen (SUNY - Stonybrook)
     PURPOSE:
    	Alignment of images abtained on an x-ray microscope.
    	Called by ZSTACK_ALIGN.PRO
     CATEGORY:
    	Data analysis.
     CALLING SEQUENCE:
    	zstack_tune
     INPUTS:
    	NONE
    	filename_list,ev_list,msec_list,filename_display_list, and image_stack of zstack_common
    		must be previously defined via ZSTACK_ANALYZE.PRO
     KEYWORD PARAMETERS:
    	NONE
     OUTPUTS:
    	x_shift, y_shift, corr_dim_stack, corr_stack, shifted_image_stack of zstack_align_common
    		are computed as output
     COMMON BLOCKS:
    	zstack_common	:
    		data_source				:	type of x-ray microscopy data: STXM:1, SXM:2, SM:3, ALS:4, POLY:5
    		data_directory				:	directory of data files
    		image_stack				:	3-D matrix of multiple x-ray microscope images
    		filename_list				:	list of filename corresponding to images in image_stack
    		ev_list					:	list of x-ray energies corresponding to images in image_stack
    		msec_list					:	list of dwell times corresponding to images in image_stack
    		filename_display_list			:	list of filename, x-ray energy, and dwell time corresponding to images in image_stack
    		displayed_file_index			:	index in image_stack, filename_list, msec_list, and filename_display_list currently being displayed or processed
    		n_files					:	number of images
    		list_filename				:	name of file to save or retrieve list of data files
    		shift_filename				:	filename of alignment shifts
    		x_shift					:	array of x-coordinate alignment shifts
    		y_shift					:	array of y-coordinate alignment shifts
    		data_shifted				:	0: data was not shifted and should not be clipped, 1: data was shifted and should be clipped, -1: denotes ZSTACK_PROFILE.PRO is being run as a stand-alone procedure
    		n_clipped_cols				:	number of columns in clipped image
    		n_clipped_rows				:	number of rows in clipped image
    		clipbox					:	vector of four points defining dimensions of region unclipped by alignment: [xleft,xright,ybot,ytop]
    	zstack_align_common
    		zstack_align_par			:	variables controlling ZSTACK Align dialog window
    		file_num					:	vector of file numbers of image files
    		dragbox					:	vector of four points defining dimensions of region selected for alignment: [xleft,xright,ybot,ytop]
    		edge_enhance				:	edge enhancement parameter: 0: none, 1: sobel, 2: roberts
    		edgegauss_pixels			:	number of pixels used for edgeguass smoothing in ZSTACK_ALIGN_IMAGES.PRO, default = 3
    		edgefill					:	type of filling to occur at edges of shifted images: mean, median, max, min, zero
    		image_match				:	Image to align to: -1: preceding image, 0: constant image, 1: following image
    		constant_file_index			:	image of index to use as reference when aligning to a constant image
    		corr_max					:	0: use 3-pt fitted maximum of correlation function, 1: use center of mass of correlation function
    		maxshift					:	2-point vector of minimum and maximum values of x-shift and y_shift, and temp_x_shift and temp_y_shift within ZSTACK_ALIGN_TUNE
    		doalign_complete			:	-1: alignment in progress, 0: alignment not started, 1: alignment finished, 2	: using alignment from stored file
    		low_memory					:	Reflects keyword LOW_MEM: 0: use full memory allocation, 1: use reduced memory allocation
    		corr_stack					:	3-D matrix of correlation functions corresponding to image_stack
    		shifted_image_stack			:	3-D matrix of shifted images corresponding to image_stack
    		corr_dim_stack				:	3-D matrix (i,j,k) of maxima of correlation functions: i: x maximum, j: y maximum, k: image file
    		shift_threshold				:	mimimum shift required to actually shift the image
    	zstack_tune_common
    		zstack_tune_par				:	variables controlling ZSTACK Tune Alignment dialog window
    		temp_x_shift				:	vector of alignment shifts along x-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		temp_y_shift				:	vector of alignment shifts along y-coordinate for images in image_stack, obtained within ZSTACK_ALIGN_TUNE
    		init_x_shift				:	vector of initial alignment shifts along x-coordinate for images in image_stack
    		init_y_shift				:	vector of initial alignment shifts along y-coordinate for images in image_stack
    		image_center				:	array of pixel coordinates specifying the center (in pixels) of each image
    		corr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function image
    		shifted_center				:	array of pixel coordinates specifying the center (in pixels) of each shifted image
    		subimage_center				:	array of pixel coordinates specifying the center (in pixels) of each subimage
    		subcorr_center				:	array of pixel coordinates specifying the center (in pixels) of each correlation function subimage
    		subshifted_center			:	array of pixel coordinates specifying the center (in pixels) of each shifted subimage
    		subimage_pixels				:	size of subimages in pixels
    		fid_pt					:	pixel coordinates of present fiducial point(s)
    		n_fid_pt					:	number of fiducial points
    		all_fid_pt					:	array of all fiducial points
    		fid_pt_index				:	index of fiducial point(s)
    	zstack_display_common
    		zstack_display_par			:	variables controlling ZSTACK Display dialog window
    		image_zoom					:	zoom factor for displaying images
    		subimage_zoom				:	zoom factor for subimages
    		movie_delay				:	delay used to display movie images of data stacks, dependent upon machine speed
    		disp_min					:	minimum percentage intensity for display of images
    		disp_max					:	maximum percentage intensity for display of images
    		disp_gamma					:	gamma factor for display of images
    		spectrum_display			:	Display spectra as: 1: Single Beam, 2: Percent Transmittance, 3: Absorbance
    		spectrum_offset				:	Offset used to plot spectra
    		init_zoom					:	initial zoom factor for displaying images (used in ZSTACK_SAVE and ZSTACK_TUNE)
    		movie_active				:	movie of images is active: 0: NO, 1: YES
    		profile_zoom				:	zoom factor for file number axis on profile images
    		image_range				:	scale images using: 0: intensity range of each image, 1: intensity range of full image stack
    		image_ratio				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		ratio_image_index			:	index of image to use when ratio images to a constant image
    		image_scale				:	Display images normalized by: 0: inv_image_stack, 1: i0 spectrum
    		image_invert				:	invert color bar: 0: NO, 1: YES
    		temp_old_display			:	initial array of display parameters, set at beginning of ZSTACK_DISPLAY
    		temp_new_display			:	array of display parameters updated as display options are changed
    		zstack_subroutine			:	subroutine from which ZSTACK_DISPLAY was called
    		spectra_x_min				:	mimimum x-ray energy value to plot spectra
    		spectra_x_max				:	maximum x-ray energy value to plot spectra
    		spectra_y_min				:	mimimum intensity value to plot spectra
    		spectra_y_max				:	maximum intensity value to plot spectra
    		x_autoscale				:	autoscale x-ray energy scale: 0: NO, 1: YES
    		y_autoscale				:	autoscale spectra intensity scale: 0: NO, 1: YES
    	zstack_color_common
    		bottom_color_index			:	index of lowermost color of gradient colorscale
    		top_color_index				:	index of uppermost color of gradient colorscale
    		black_color_index			:	index of black color
    		white_color_index			:	index of white color
    		plot_bkgd_color_index			:	color index for plot background, either black or white
    		plot_axes_color_index			:	color index for plot axes, either whilte or black
    		image_border_color_index		:	color index for image border in zstack_buildlist and zstack_profile dialog windows
    		dragbox_color_index			:	color index for dragbox used to define subregion for alignment
    		corr_ctr_color_index			:	color index for crosshair showing center of correlation function
    		corr_max_color_index			:	color index for crosshair showing maximum of correlation function
    		x_shift_color_index			:	color index for plotting of x-shift
    		y_shift_color_index			:	color index for plotting of y-shift
    		shift_cursor_color_index		:	color index for cursor in shift plot, indicating file number
    		tune_fiducial_color_index		:	color index for fiducial points in closeup of shifted image in zstack_tune dialog window
    		spectra_color_index			:	color indices (14) for plotting of spectra
    		spectra_cursor_color_index		:	color index for cursor in spectra plot, indicating x-ray energy
    		profile_color_index			:	color index for plotting of intensity profile and cursor in profile image indicating row or column
    		profile_cursor_color_index		:	color index for cursor in profile image, indicating x-ray energy
    		profile_spectrum_color_index	:	color index for plotting of profile spectrum
    		test1_color_index			:	color index #1 for testing
    		test2_color_index			:	color index #2 for testing
    		test3_color_index			:	color index #3 for testing
     SIDE EFFECTS:

     RESTRICTIONS:

     PROCEDURE:
    	Called by ZSTACK_ALIGN.PRO
     EXAMPLE:

     MODIFICATION HISTORY:
     Modified 25-mar-1998 to deal with 24 bit graphics, CJJ
     Modified July 11 and 13, 1998 to deal with changes to align.pro, CJJ
     Modified 28-aug-1998 to work with corrected 24 bit graphics. CJJ
     Modified 31-Aug-1998 to add x_shift, y_shift to argument list, and
       remove shift_filename!, CJJ

     Modified 20feb99, CGZ
     Extensively modified and rewritten STACK_ALIGN.PRO to form ZSTACK_ALIGN.PRO
     Changes and additions are numerous:

     All procedures and common variables starting with 'stack' were changed to 'zstack'
     so that the existing routine, STACK_ALIGN.PRO, can be run in parallel

     Added the following procedures:
    	zstack_align_prep		:	sets color table and color indices
    	zstack_tune_imgdisp		:	displays images and shift plot
    	zstack_align_save_shift	:	saves alignment shift into MAPPER file, *.aln
    	zstack_align_read_shift	:	reads alignment shifts from MAPPER file, *.aln
    	zstack_tune_event	:	event routine for zstack_tune
    	zstack_tune		:	interactive adjustment of individual alignment shifts

     Rewrote stack_align_sensitive to be two separate procedures with better control
    	zstack_align_sensitive	:	activate features on Stack Align dialog window
    	zstack_align_desensitive	:	deactivate features on Stack Align dialog window

     Pre-existing procedures
    	zstack_align_doalign		:	controls alignment of image stack with active display
    	zstack_align_event		:	event routine for zstack_align
    	zstack_align			:	main procedure for alignment of STXM images

     Modified user interface window to include
    	display and movie of image, correlation function, shifted image
    		dragbox is plotted on both image and shifted image
    		center of correlation function displayed as crosshair overlay (same as CJJ)
    		maximum of correlation function displayed as 1-pixel box overlay (same as CJJ)
    	modified plot of alignment shifts
    		- use actual file numbers instead of file sequence number (relative number)
    		- added plot_x_min and plot_x_max
    		? is it useful to plot vs x-ray energy instead - would require considerable work
    			might be able to plot both using upper and lower x-axes
    	movie can be played before and after alignment to inspect position of dragbox
    		and quality of alignment
    	cursor bar added to plot of alignment shifts highlighting shift and file
    		during movie or static display
    	displayed file can be selected either using file list or alignment plot
    		clicking on alignment plot, prints file info and alignment shift in Output Log
    	text fields added to display image and shift information during movie or static display
    	added "Load New Color Table" to change color table of image
    	saving and retrieving of file of alignment shifts
    	added ability to redo alignment
    		- can now do multiple alignments using different conditions, saving each

     Changed zstack_align_par.dragbox_label routine in zstack_align_event
    	Replaced getbox routine with box_cursor routine, more robust on multiple platforms, CGZ

     Adapted display routines to use zstack_tune_imgdisp
    	One display algorithm which can be easily modified
    	Only exception is real-time plotting of alignment shift in zstack_align_doalign

     Changed the way the color table is specified: zstack_align_prep
    	- much simpler now, only executed once, allows multiple colors easily

     New variables:
    	corr_stack			:	stack of correlation functions
    	shift_image_stack	:	stack of shifted images
    	corr_dim_stack		:	stack of dimensions specifying center and maxima of
    							correlation function
    							used for displaying correlation function
    	edgefill			:	 type of filling to occur at edges of shifted images
    							(edges can contain no data due to shifting)
    							set within zstack_align_doalign
    		meanfill 		:	replace with mean of image
    		medianfill 	:	replace with median of image
    		maxfill 		:	replace with maximum of image
    		minfill 		:	replace with minimum of image
    		zero			:	replace with zero (default)
     	doalign_complete	:	specifies state of alignment
    							(modified from use in stack_align.pro)
    		-1			:	alignment in progress
    		 0			:	alignment not started
    		 1			:	alignment finished
    		 2			:	using alignment from stored file

     Restored shift_filename to argument list

     Changed dragbox conditional from
    	IF ((dragbox(0) NE 0) AND (dragbox(1) NE 0) AND $
    		(dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    	to IF ((dragbox(2) NE 0) AND (dragbox(3) NE 0)) THEN BEGIN
    	to accomodate dragbox = [0,0,*,*], i.e., lower left corner

     Save alignment / Do not save alignment choice wasn't working before - fixed

     Stack_align would give non-zero shift for first image
    	This is fixed with modification of call to zstack_align_images (updated version of align.pro)

     Added dragbox coordinates to header of MAPPER file of alignment shifts

     Added zstack_align_tune to interactively adjust alignment shifts
    	essentially superceding stack_manalign.pro.
    	This can be improved upon to incorporate features of stack_manalign.pro

     Moved nearly all widget_control,var,sensitive = 0/1 statements to
    	zstack_align_sensitive and zstack_align_desensitive for more reliable operation
    	and better organization of code (instead of being widely dispersed)
    	zstack_align_sensitive has situation-dependent conditionals to control appearance of window

     Need to restore virtual memory allocation when working with large data arrays
     	so corr_stack, shift_image_stack, and corr_dim_stack) set to zero at end

     Added alignment to following image - useful if image quality is better at high energy
    	This is in addition to existing alignment to preceeding image and to a constant image
    	Eliminated variable, zstack_align_par.constant_match
    	Added variable, image_match with valid values:
    		-1			:	alignment using preceeding image
    		 0			:	alignment using constant image
    		 1			:	alignment using following image

     Added low_mem keyword to STACK_ANALYZE.PRO and STACK_ALIGN.PRO
    	If set, then shifted_image_stack is not formed with STACK_ALIGN.PRO
    	This reduces memory use by 1/3 and is useful when large arrays are being processed.
    		This comes at some reduction in speed for displaying new images,
    		most noticeable during playing of image movies
    	If set, display of shifted images within STACK_ALIGN.PRO is done by calculating
    		shifted image from x_shift, y_shift, and image_stack
    		every time an image is displayed.
    	With low_mem set, IDL partition should be approx. >9 times n_elements(image_stack)
    	With low_mem not set, IDL partition should be approx. >13 times n_elements(image_stack)
    		(based on tests on a Macintosh)

     Modified COMMON block structure so that common variables are shared with all zstack routines
    	i.e., zstack_common contains variables used by
    		ZSTACK_ANALYZE.PRO, ZSTACK_READLIST.PRO, ZSTACK_BUILDLIST.PRO, and ZSTACK_ALIGN.PRO
     Common variables are now defined only once in each file, not repetitively as before.
     Common variables for data are now determined within ZSTACK_BUILDLIST.PRO or ZSTACK_READLIST.PRO:
    	image_stack, filename_list, ev_list, msec_list, filename_display_list
    	This requires that files be read only once, eliminated time-intensive duplicate calls of
    		STXM_READ.PRO or SXM_READ.PRO

     Modified zstack_align_par, zstack_tune_par
    	so that they only contain only variables associated with dialog window.
    	All other variables have been moved to zstack_align_common

     Added n_files, list_filename, and shift_filename variables to zstack_common variable

     End of Modifications 20feb99, CGZ

     Divided align and tune functions into two separate procedures: ZSTACK_ALIGN.PRO and ZSTACK_TUNE.PRO
     ZSTACK_TUNE.PRO could be used as a replacement for ZSTACK_MANALIGN.PRO

     Fixed problem in zstack_tune_desensitive and zstack_tune_sensitive
    	if stored shift file was used, CGZ 27jun99

     Problem with returning to ZSTACK_ALIGN dialog if new zoom factor is selected
    	Images not properly displayed.  Fixed CGZ 12aug99

     (05oct00 cgz)
    	Created zstack_save_common to include variables for saving various image and movie formats
    		Moved zstack_save_par and save_filename_header from zstack_spectra_common
     (28nov00 cgz) migrated zstack_profile_colorbar routine to zstack_analyze.pro
     (04jan01 cgz) modified display routine of subimage of correlation function
    			wasn't working properly for alignments using an off-center subregion
    			still some issues here for selecting subregion for display
    			desensitized corr_win for now
     (22feb02 aph) correct transfer back from manual alignment to zstack_align
     (03-Mar-08 MJ) Keyword /SCROLL in widget_base() needs X_SCROLL_SIZE.
                    Use of /SCROLL and /MODAL at the same time not allowed.
     (13-apr-08 aph) turn on pre-set window size (X_Scroll_size, Y_Scroll_size) only for non-Windows OS

(See c:\axis2000\zstack_tune.pro)