FOCAS - Faint Object Classification and Analysis System FOCAS is a suite of programs for automatic detection, photometry, matching, classification, and cataloging of astronomical digital images. It also provides tools for accessing the catalogs and doing analysis. RELEASE NOTES =============================================================================== 9/3/98: Fixes for Linux and Dec Alpha 1. The Makefile was adjusted for Linux to use ncurses package instead of curses. Fixed a bug that would cause REVIEW to hang on windows less than 100 characters wide. 2. The maximum pixel value, used mostly for initialization of the sky image, caused problems with Dec Alpha/IMFORT for unknown reasons. Made the number smaller. =============================================================================== 6/16/98: Bug fix for segmentation violation during display If after specifying a display range you get a segmentation violation this is caused by the string used to send information to the display overflowing. The fix is to make the string longer and limit the formating. You only need update if you encounter this problem. =============================================================================== 3/18/98: Dec Alpha changes The catalogs produced on Dec Alphas were not in the correct machine indepedent format because long integers are being stored as 64 bits. This release corrects this to produces the machine indepdendent catalogs on all machines. HOWEVER, IF YOU HAVE EXISTING CATALOGS THEY MUST BE CONVERTED WITH THE COMMAND "aconvert newcatalog". The new aconvert task is included in the binary distributions focas-bin.osf1a.Z. However if you build from source you must make this explicitly with "make aconvert" (after "make ALL" creates the libraries) and move the executable to the bin directory. =============================================================================== 2/15/97: Linux changes. =============================================================================== 8/9/96: The following are updates to REVIEW/MREVIEW. 1. Fixed bug in MREVIEW preventing use of 'k' mode on Solaris. 2. Increased REVIEW/MREVIEW to allow up to 4 catalogs (instead of 3). 3. Reworked the logic to better handle object ('k') mode. 4. Splitting is no longer allowed in REVIEW. =============================================================================== 7/23/96: FOCAS previously used the FITS coordinate keywords incorrectly. This could cause confusion between FOCAS and software that expects to use these keywords. In this release keywords which are never used by FOCAS are no longer read or written (ctype#, crval#, crota#, bunit). Those used for other purposes have been changed to different keywords names: crpix# -> [xy]offset, cdelt# -> [xy]step. This will have little effect on anyone but protect software from inappropriate values. =============================================================================== 5/13/96: The routine for reading the catalog entries did not have a return value for success but only for failure. On Solaris 2 this had the effect of sporadically terminating reading a catalog. =============================================================================== 3/11/96: Two changes for for Solaris. 1. Fixed MCATLIST for Solaris. 2. Fixed CLEAN for Solaris. =============================================================================== 3/4/96: These changes are minor and there is no need to update unless you want to build FOCAS on IBM or HP. 1. Fixed problems in building FOCAS on IBM/AIX and HP/UX. 2. Fixed problems in building the standalone FOCAS. 3. In the field mode of REVIEW the isphotes and crosshair were drawn off by one pixel. This is a visual problem and not a problem in the catalog. 4. The focas.cl file was not correct concerning filter and display whose names have changed to ffilter and fdisplay. =============================================================================== 2/7/96: Workaround for RESOLUTION and SPLITS problem with Solaris. =============================================================================== 1/24/96: 1. Fixed bug in RESOLUTION triggered with CRPIX1 or CRPIX2 are negative. 2. Changed the default threshold for objects below sky to 10. 3. Added an error check against a sky sigma less than or equal to zero when evaluation the sky. 4. Fixed a bug in TOTMAG that would fail to detect the end of the catalog if a catalog ended with a split object. =============================================================================== 9/19/95: Fixed typo in setpsf.s from previous update: "csh - f" --> "csh -f". There is no need to update as this can be easily fixed locally. 5/13/95: All CSH scripts now ignore the user's .cshrc file which causes problems if they alias basic commands such as rm. Minor changes to support IBM/RS6000 AIX. =============================================================================== 4/28/95: 1. Made modifications to support OSF/1. 2. New version of MKTRANFORM. 3. Fixed bug with object display mode in REVIEW/MREVIEW. 4. FOCASMAN now uses FOCAS environment variable. Executables: focas-bin.osf1.Z OSF/1 (DEC Alpha) =============================================================================== 1/19/95: Added support for specifying the display pipes and display size as environment variables FOCASPIPE and FOCASDISPLAY. 1/19/95: Modified to compile with Solaris. 1. Display annotation disabled becauses fonts are not universally available. 2. IIS devices commented out. This does not affect display servers IMTOOL, SAOIMAGE, XIMTOOL. Executables: focas-bin.sparc.Z Sparc SunOS Executables: focas-bin.ssun.Z Sparc Solaris =============================================================================== 10/20/94: Reorganized for simpler distribution. 1. Reorganized as a single distributions with Makefile entries to configure IRAF or standalone usage. 2. Merged previous patches. =============================================================================== DOCUMENTATION AND HELP Several papers which discuss FOCAS are available as compressed Postscript in the directory iraf/docs/focas. These files need to be transfered also in binary mode and then uncompressed. They may then be printed by any printer which can print Postscript. The frequently asked questions file, focas.faq, should also be consulted. If you have any questions, please contact the IRAF group at iraf@noao.edu, NOAO::IRAF (5355::IRAF) or call the IRAF HOTLINE at 520-323-4160. INSTALLATION INSTRUCTIONS FOR THE FOCAS 1. The package is distributed as a tar archive(s) via anonymous ftp. A special request is required for a tape distribution. For magnetic tape go to step 2 and when reading the tar archive simply mount the tape and use the tape device name for the archive name. To obtain the package via ftp: % ftp iraf.noao.edu (140.252.1.1) login: anonymous password: [your email address] ftp> cd iraf/extern/focas ftp> get focas.readme ftp> get focas.faq ftp> binary ftp> get focas.tar.Z ftp> quit % uncompress focas.tar The focas.readme file contains these instructions. In addition to this file you may get precompiled executables for particular platforms. focas-bin.sparc.Z # Sparc SunOS focas-bin.ssun.Z # Sparc Solaris focas-bin.dsux.Z # DECstation Ultrix 2. Read the source archive. % tar xf focas.tar After verifying that the source code has been extracted you can delete the tar file or unmount the tape. 3. Configure for IRAF or standalone usage. FOCAS can be used either with the IRAF image format or with it's own image format. In the former case FOCAS is then often defined within IRAF as a suit of foreign tasks as described below. To compile FOCAS to use the IRAF image format IRAF must be installed (or at least the IMFORT libraries). The standalone version depends only on standard Unix libraries. The only differences in the two configurations is the Makefile and a couple of image I/O subroutines. To configure for IRAF usage: % make iraffocas To configure for standalone usage: % make oldfocas 4. Make local changes There are a few parameters which may be need to be changed or set for a particular site. 4.1. Catalog format FOCAS is a system which detects objects in images and catalogs them. Most of the tools in the package interact with this cataloged data. The catalog is a binary file containing a general header keeping various parameters and a processing history and a, possibly large, number of records, one for each cataloged object. In earlier versions of FOCAS there was just one catalog format which was machine dependent. These catalogs contain complex structures and there was no way to move these files to a different type of machine even with FOCAS existing on both machines. To solve this problem the new FOCAS supports three catalog formats; the original machine dependent format, a short, packed, machine dependent format (used to save space when there are many large catalogs at the cost of losing some information), and a machine independent format. The FOCAS routines recognize all three formats and there is a new tool, "catformat", for converting between these formats. However, if one selects the machine independent format as the default for the creation of new catalogs then conversion is not necessary. If one intends possibly moving data between machines, even as a future possibility, then the machine independent format should be the default. For example this will allow FOCAS to be run on both VAXes and SUN workstations, a common situation in many academic sites. There is a small conversion penalty which is essentially unimportant and I see no need to use the old format. Therefore, this is the default configuration. This is documented, however, because a few existing sites may have FOCAS programs which do not support the new format and which would have to be recompiled with the new system (this is not a problem unless the source has been lost). The default catalog format is set by editing the macro definition of CATTYPE in the source file "setcat.c": /* Set default catalog format here */ /* 1 = machine dependent format (original format) */ /* 2 = machine dependent short format */ /* 3 = machine independent format */ #define CATTYPE 3 Note that this extension has not yet been made for "matched catalogs". 4.2. Area (isophote) file format In addition to the catalog, FOCAS creates and uses a area description file containing the isophotes. This file is also a binary file. In the new FOCAS this file has been made machine adaptable. This means that FOCAS detects the byte order used in creating the file and corrects for the machine which is reading it. This is done by adding a two byte header to the original format. Thus, these files may be transfered simply between machines and read transparently. There is, of course, some inefficiency when the format must be adjusted but it is minor and is nonexistent on the machine which created it, which is where most of the work is likely to take place. There is nothing the installer need do. This section is included to point out to sites with older area files lacking the header used to determine the byte order, that a new program has been added, called "arswap", which swaps the byte order of the old area file for transport to a machine with the opposite byte order. [Warning: do not attempt to double swap on the same machine because the program needs to interprete the contents of the file and after the first swap it cannot do this. Also do not attempt to add the simple header since the catalogs contain absolute offsets into this file.] 4.3. Byte order In order for the FITS reader/writer and the machine independent catalog routines to function they must be advised whether to swap bytes and words to the standard order for a particular machine. The standard byte order is that defined by FITS with the least significant byte first. Thus, on VAX computers the swap flag must be set and on SUN computers the swap flag should not be set. The default is no swap. The swap flag is defined in the file "miformat.h" and has the value 0 for no swap and 1 for swap. The following shows the line from the include file: #define MISWAP 0 /* Swap bytes on this machine? */ 4.4. The image display Most of FOCAS can be used without an image display. However, FOCAS is much nicer to use with an image display to visually examine the objects detected and cataloged. In the previous version of FOCAS there was support only for the IIS model 70 and a separately maintained version modified for the IIS model 75. In the new version the driver source for these two displays has been merged and a number of bugs fixed and enhancements made. The most important change, however, is the added support for the IMTOOL display server for SUN workstations. IMTOOL is a display task which emulates a subset of the IIS model 70 command interface written and supported by the IRAF group at NOAO (author Doug Tody). In addition it has many other nice features including hardcopies through a Postscript printer. IMTOOL is not supplied with the FOCAS tape and must be obtained separately. It is automatically supplied to SUN/IRAF sites, however. Sites with SUN workstations are much more common than those with IIS devices so this development makes FOCAS of wider usefulness. There are three FOCAS tasks which use an image display. These are "display", "review", and "mreview". The default in the source is for the IMTOOL display server. To select either of the IIS devices the source files "display.c", "review.c", and "mreview.c" must be edited to change the defining macro at the beginning of the file. The example line is: #define IISDEV 3 /* Display: 1=IISM70, 2=IISM75, 3=IMTOOL*/ A quick note about IMTOOL and FOCAS. Because IMTOOL is a prototype display server which either does not emulate some of the IIS functions or is incapable of efficiently emulating some functions provided by the IIS hardware some of the functions used in FOCAS with the IIS will not work. However, all the important ones have been included either by FOCAS or IMTOOL. For example, overlayed graphics is available but not in color and erasing or turning off overlays requires reloading the image. 4.4.1 Image display environment variables for size and pipes There are also two environment variables that allow changing the default behavior. The environment variable FOCASDISPLAY can be used to define the display size. The value is three whitespace separated numbers giving the frame buffer number, the x size, and the y size. These values must match those given in the imtoolrc file (see /usr/local/lib or $iraf/dev). When used with IRAF one should also use the same stdimage display configuration. The default is an 800x800 display. As an example to get a 1024x1024 define in your login files or before running FOCAS and CL: setenv FOCASDISPLAY "3 1024 1024" The FOCAS display programs connect to the display server through pipes. For the display server XImtool socket type connections can also be used. The default is connection is the pipe /dev/imt1 (the trailing i and o are automatically added). You may set the environment variable FOCASPIPE to some other name where you are responsible for creating the pipes or to make a socket connection. For example to have pipes in your home directory: setenv FOCASPIPE /home/valdes/imt1 This change of pipe names is often done to allow multiple users on the same machine to display to their own saoimage or ximtool process in which the pipes are also specified. Note that when used with IRAF you also need a personalized version of the "graphcap" file. For more information about this consult the IRAF or FOCAS FAQ or send mail to iraf@noao.edu. With XImtool the socket connections are more flexible. This can be achived by setting the variable to null; i.e. a defined but empty environment variable: setenv FOCASPIPE Again see the FAQ for more information. 5. Compiling and maintaining the executable tasks The package is maintained using the UNIX "make" utility. This is controled by the file "Makefile". There are numerous entry points used to compile the entire system, parts of it, or just single tasks. The FOCAS Makefile has one user defined variable specifying the directory for the executables. This might be the same as the source directory, as subdirectory, or a local system directory. The variable is called BIN as in the line below: BIN=./bin It is only used with the INSTALL entry in Makefile. You must make the directory if it does not exist. For multiple architectures sharing an NFS disk you could define bin.sparc, bin.ssol, etc. The various machines on which FOCAS has been compiled sometimes have differences. The source code has been made to be common to all platforms. However there are differences in the way code is compiled. Therefore in the Makefile you must uncomment the block of statements for a particular machine and comment out the others (the Makefile comes defined for SunOS). For the IRAF version on Sun platforms it is necessary at this point to set a UNIX environment variable to define the software environment for XC. Set the variable "IRAFARCH" to the output of the UNIX command "mach". For example, % setenv IRAFARCH `mach` % echo $IRAFARCH sparc To compile and install the entire system use the entry ALL as in the example: % make ALL >& make.log& For the more technically inclined the object code is all contained in libraries. Some tricks are used to delete all object code not in libraries except when needed. This reduces disk space since two copies of each object are not kept and makes the directory listing more compact. This is all handled nicely by the IRAF "mkpkg" utility but is more difficult with "make" unless there is some trick I am not aware of. For more detail consult the "Makefile". Note that one may get precompiled executables as noted below. focas-bin.sparc.Z # Sparc SunOS focas-bin.ssun.Z # Sparc Solaris focas-bin.dsux.Z # DECstation Ultrix focas-bin.osf1.Z # OSF/1 (DEC Alpha) [older release] focas-bin.osf1s.Z # OSF/1 (DEC Alpha) [March 18, 1998 release] Create, if needed, a directory for the executables. Typically this is bin under the source directory. In this directory uncompress and untar the tar file: % zcat focas.bin.???? | tar xf - 6. Running FOCAS In order to run FOCAS commands you must make the bin directory known to UNIX through the "path" variable; usually set in the .login file. This is also required when calling FOCAS commands from IRAF (below). The on-line documentation directory On-line documentation is available for most of the tasks. The documentation has not kept up with changes and so some of it is slightly incorrect and some of the recent additions (for example "mktransform") are missing. The FOCAS command "focasman" displays the on-line help. In order to get the help you must define an environment variable pointing to the FOCAS source directory: setenv FOCAS [path] Note that to set this for all users so they don't need to define this variable themselves the file focasman in the bin directory may be edited to place an explicit path. 6.1. Interfacing with IRAF as a foreign package FOCAS may be run independently of IRAF since it is simply a suite of C programs and UNIX shell scripts. However, it is a nice complement to run FOCAS programs from the IRAF command language, the CL. This is especially useful when the disk image format is the IRAF format. An IRAF foreign task is simply a definition to the command language to have the host operating system run a job. IRAF organizes tasks by logical function into packages. A package is defined by a simple command language script file. A copy of an IRAF script defining all the FOCAS commands as foreign is included in the file "focas.cl". To use this file individually one needs to type the following, or add it to your "loginuser.cl" file. cl> task $unixfocas = [path]/focas.cl where [path] is the directory path to the file. The package name is "unixfocas" to differentiate it from the unimplemented package "focas". To install the package globally modify the file hlib$extern.pkg which contains all the external package definitions. AFTER the noao package definition (the first two lines shown) add the three lines which load the package and then rest the focas directory path and the package definition. reset noao = iraf$noao/ task noao.pkg = noao$noao.cl noao reset focas = [path] redefine $focas = focas$focas.cl The [path] must end with a '/'; for example /ursa/iraf/extern/focas/. Also the first '$' in the redefine statement is needed otherwise an error about "no parameter file" will occur. After adding these statements you may start the CL and load the FOCAS package. Note that this does not eliminate the requirement set your Unix path in order to find the executables. When run as a foreign task the FOCAS commands are seen by the command language. Thus, pipes and file redirection are handled by the CL which is slightly different than UNIX. One current IRAF bug to watch out for is that the append ">>" does not append but clobbers the file when used with a foreign task (fixed with V2.10.4). Another reservation is that "opstrm", which uses arithmetic characters in its arguments, will have these characters interpreted by the command language (when run as an interpreter, i.e. with no arguments, this is not a problem).