Installation and Use of the MOSAIC Image Processing Software Package -------------------------------------------------------------------- by Frank Varosi, June, 1995. E-mail: varosi@idlastro.gsfc.nasa.gov *1. New Installation: --------------------- ftp idlastro.gsfc.nasa.gov user: ftp (or anonymous) pass: (your name@address or whatever) ftp> bin ftp> cd pub/contrib/varosi ftp> get mosaic-install.tar % tar xvf mosaic-install.tar # creates files in new sub-dir. % cd install.mosaic # change to newly created dir. (keep) % install_mosaic # execute install shell script. Above install creates directories: ~/idl (if not existing) ~/idl/vlib (with subdirs) ~/idl/vlibm (with subdirs) ~/mosaic (with many subdirs) and in particular the files: ~/mosaic/idl_setup ~/mosaic/setup_user.pro ~/idl/vlib/idl_startup.pro ~/idl/idl_startup.pro (a link) Edit the file ~/mosaic/idl_setup to have the IDL_PATH you need. Add the line: source ~/mosaic/idl_setup to your .cshrc file, which sets the environment variable IDL_STARTUP and the alias "mosaic" (also go ahead and source ~/mosaic/idl_setup manually). The alias command "mosaic" should then run IDL and the MOSAIC software. Make site specific changes for MOSAIC in ~/mosaic/setup_user.pro (see ~/mosaic/setup.pro for the things that you can change). The IDL Astronomy Library should also be installed and recognized in IDL_PATH. If you make your own version of ~/idl/idl_startup.pro it must include the contents of ~/idl/vlib/idl_startup.pro Other users can run MOSAIC without having to install or copy the code: see the file "link_all_code" in the directory where you untar'd. *2. Upgrade: ------------ Upgrade to new version of MOSAIC/IDL code: cd ~/install.mosaic # created by original install. ftp idlastro.gsfc.nasa.gov user: ftp (or anonymous) pass: (your address or whatever) ftp> bin ftp> cd pub/contrib/varosi ftp> get mosaic.tar.Z ftp> get vlib.tar.Z ftp> get vlibm.tar.Z % untar # execute shell script to install updates. These upgrades overwrite existing code with newer code (*.pro files). See section #7 "Modifying MOSAIC" for how to keep site specific mods. *3. About MOSAIC: ----------------- MOSAIC is used by Dan Gezari and myself to process infrared images from a camera system with 62x58 detector (5-20um) operated at telescopes such as IRTF and NSO. Since our images are small we can easily handle hundreds of them. The software has also been used to mosaic larger images, such as 512x512 images (9 at once) on a Sparc-2 with 32 MB of memory, with no problems. The software was developed first on a Sun386i with SunView, before the X-windows version of IDL existed, and therefore uses the "wmenu" instrinsic IDL function to query the user about what to do. There are many levels of menus with many options, and it is usually clear how to use the menu driven software. There are a couple of X-window widgets that are used occasionally, but it would require rewriting all the interactive parts to fully use event driven X-widgets. Since IDL runs on VMS and UNIX machines, the operating system type and CPU architecture are checked in the MOSAIC code whenever necessary, such as when dealing with the disk file system. But MOSAIC has been used only a few times on VMS systems. Latex files mosaic.tex and deconv.tex (with paspconf.sty) give a description of capabilities. These files are with the new install or can be retrieved from pub/contrib/varosi on idlastro. MOSAIC runs as a "main" program, from which other image processing functions are then called, as chosen by the user from menus. The four major processing functions are: 1. PreProcess images: read observational data files, create collections of images (all the same size), and process them (flat fielding etc.). 2. MOSAIC creation: manipulate collections of images (all the same size), perform further processing and adjustments on images, and average the raw mosaic to create an averaged mosaic image. 3. DISPLAY mosaics: display and print the averaged mosaics (or any images), with options to overlay contours, coordinates, marks & labels, set pixel scale, image rotation, ... 4. ANALYZE mosaics (also called Mosaic-Math): manipulate collections of images (of arbitrary sizes, pixel scales, or rotations), perform computations on a stack of images, deconvolve images. Each of these processing modules presents the user with an extensive set of functions which can be applied to the images. Observational data file access is presently tailored to our own formats and no attempt at generalizing the methods has been made. However, since IDL is flexible there are many ways to load data, such as reading FITS files, and once images are in MOSAIC they can be saved as IDL-XDR files so that all information is again available upon restoring them, or written as FITS files. First we discuss how to load images for MOSAIC creation (function #2). *4. Loading images to Create a Mosaic: -------------------------------------- If you have an array of images (all same size), you can easily load them into MOSAIC by the following steps: a) Start IDL when in the ~/mosaic directory, or simply start "mosaic" and exit back to IDL. b) get your images into a 3-D array of 2-D images, that is, an array with dimensions: ( nx, ny, Nimage ). For example: IDL> images = fltarr( 256, 256, 7 ) IDL> for i=0,6 do images(0,0,i) = readfits( files(i), header ) c) then enter: raw_mosaic = make_raw_mosaic( images, MAGF=magf, NAMES=names ) where: images = 3-D array of 2-D images, magf = display magnification you desire (0.5, 1, 2, 3, 4), default=1, and you can change it later. names = string array, name identifying each image, such as the filenames. Note: the created structure variable "raw_mosaic" must be called exactly by that name, for use by MOSAIC. d) then IDL> .run mosaic_main select the "MOSAIC creation" menu option, then "resize window" or "reorganize images" menu option. The function make_raw_mosaic has other keywords to set more fields, or you can set other fields in the structure raw_mosaic at any time. When you "save Raw Mosaic", the variable "raw_mosaic" is passed to a procedure where it saves the structure variable with the new name of "image_List", to a file with name extension ".iml". Upon selecting "restore Raw Mosaic" you will get back everything exactly as it was. (If you restore the file manually in IDL you will get back the variable "image_List" which is exactly the same). The option "average mosaic" will compute a single image, averaging overlayed pixels (also called coadding), and the result is displayed ("splice mosaic" is similar except no averaging). The display of the averaged mosaic image can be further tailored in the "DISPLAY mosaics" module by the "contour mosaic" function, and the result can be output to a PostScript graphics file. Back at the main IDL level, the averaged mosaic image is in the variable called "mosaic", generic name used by the software for an image formed from a collection of images, but an image just the same. When "save averaged mosaic" is selected, the variable "mosaic", and structures "mosaic_spec" and "mosaic_info" are saved to a file with extension ".mosaic". All the display specifications applied in "contour mosaic" are saved, when restored and displayed again it will be exactly as specified. *5. Loading arbitrary size images for mosaicing and analysis: ------------------------------------------------------------- Collections of images of arbitray sizes are handled in the "ANALYZE mosaics" function, also called "Mosaic Math". Averaged mosaic results from the "MOSAIC creation" function can be selected, or images can be read from FITS/SDAS files. The default subdirectory for FITS/SDAS files is "data/fits/", and this can be changed by entering new definition in "setup_user.pro" if desired. The collection of images can then be manipulated into an even larger mosaic, or into a multi-wavelength stack on which computations can be performed. If images of point sources, such as stars, are available, they can be used with the deconvolution menu option to attempt restoration of data, improving the image resolution. First get into the "ANALYZE mosaics" module, and then to load images choose the "select mosaics" option. If there are none in the list then choose "RESTORE mosaic" (if you had saved some already) or "Load image from FITS file" if you have data in FITS or SDAS format. After you have read some data from files, returning to previous menu should give a list of mosaic images to select from. Choose some or all from this list, and then "No more" when finished. The images should then be automatically scaled and displayed in a new window. You can then continue to manipulate/analyze them with the options available in this module. You can also "Load image from FITS file" in the "DISPLAY mosaics" module, as well as "Store image to FITS file". If the FITS header contains astronomical coordinates and pixel size, they are used when the image is displayed in the "contour mosaic" function. Select the "relative arcseconds" or "absolute coordinates" option and press the middle button on mouse, to use current definition of coordinates (as read from FITS file). The pixel scale can be set with the "plate scale" menu option in "contour mosaic" function. The "set contour defaults" option will allow setting the rotation of images in 90 increments and also continuous angles. The rotation angles are then also used when image is selected for "ANALYZE mosaics". The image data is stored in a pooled memory arrays, one pool-array call "mosaics" for "DISPLAY mosaics" and the pool-array called "math_images" for "ANALYZE mosaics". Thus, there is some overhead associated with using the software, but the gain is flexibility. Data is always first read and stored in the "mosaics" pool-array and never modified. Then when selected for "ANALYZE mosaics", data is copied into the "math_images" pool-array, where it can be modified, such as with the "set source fluxes" option for calibration. When adding images to a pool-array, the first image inserted determines the variable type of the pool-array, and subsequent images are inserted with no conversion (just straight memory copy). When images are extracted from pool-array there are recast to original variable type. Note that the "save Math Mosaic" option saves just the array of structures describing the collection of mosaic-images, the actual image data must be saved seperately to files using the "save mosaic" option in the "DISPLAY mosaics" module. Then "restore Math mosaic" will automatically restore each seperate "*.mosaic" file needed to recreate the collection of images. You can also "contour mosaic" any of these mosaic-images at any time (in "DISPLAY mosaics" module). *6. Reading Observational Data Files for Preprocessing: ------------------------------------------------------- The observational data is read from FITS files (numbered in observed sequence) or our own instrument data file format. The main level common block variable "dir_obs" points to the data directory, and the data is read within the "PreProcess images" option. (Note that in defining string variable dir_obs a final "/" is needed). Adapting the software to read data files from other instruments requires modifying: ~/mosaic/code/prep/read_images.pro ~/mosaic/code/prep/sig_ref.pro ~/mosaic/code/lib/struct/headinfo.pro and to change the method of selecting data files, modify: ~/mosaic/code/prep/select_files.pro ~/mosaic/code/prep/select_files_1.pro (sequenced FITS files) ~/mosaic/code/prep/select_files_2.pro (for our own format) In the near future, I plan to add more general options for reading and writing FITS files to make it easier for other users, so any suggestions or comments about the software are welcome. *7. Modifying MOSAIC: --------------------- Since MOSAIC runs as an IDL main program, it has many IDL variables at the main level which control execution. You should add site specific setups of these variables into ~/mosaic/setup_user.pro which is executed by ~/mosaic/setup.pro, and will not be overwritten when you upgrade to new versions of the software. See ~/mosaic/mosaic_main.pro and ~/mosaic/setup.pro for info about main level IDL variables. If you want to change some of the software (all in ~/mosaic/code) it is recommended that you copy the original routines into a new subdirectory, make the changes, then add the new subdirectory to the IDL path by a statement in ~/mosaic/setup_user.pro, such as: !PATH = "~/mosaic/code/site_specific:" + !PATH in order to compile your versions of the changed routines first. Then installing new versions of MOSAIC will not overwrite your changes. If you want to browse through the MOSAIC code, there is a handy widget included in the distribution (in ~/vlib/xdoc) for doing so, courtesy of Dominic Zarro (also at GSFC in Solar Physics branch). Just type "doc" at the IDL> prompt and you can browse through all the code in current IDL path. --------------------------------------------------------------------------------