******************************************************************************* * Text: Read Me for GetImage Version 1.1 * * * * File: * * readme.txt * * * * Description: * * This file describes how to use the GetImage Version 1.1 program for * * accessing data from the CD-ROM set of the Digitized Sky Survey. * * * * History: * * Created : 30-NOV-93 by J. Doggett * * for the Association of Universities for Research in Astronomy, Inc. * * at the Space Telescope Science Institute, * * to facilitate the accessing of data from the CD-ROM set of the * * Digitized Sky Survey. * * Delivered : 01-MAR-94 by J. Doggett * * * * Updated : 01-JUN-94 by J. Doggett * * Added description of new -m/-M option to override environment * * variable specification of the UNIX mount point for the CD-ROM. * * Updated : 09-NOV-94 by J. Doggett * * Updated report of failure mode using DEC C under OpenVMS. * * Updated : 21-NOV-94 by J. Doggett * * Added problems associated with UNIX platforms (text provided by F. * * Romelfanger) to Section V. * * Redelivered: 30-NOV-94 by J. Doggett * * GetImage Version 1.1. * * * * Copyright (c) 1993, 1994, Association of Universities for Research in * * Astronomy, Inc. All Rights Reserved. * * Produced under National Aeronautics and Space Administration grant * * NAG W-2166. * ******************************************************************************* I. OVERVIEW AND INSTALLATION ---------------------------- GetImage is a program for accessing the compressed image data from the CD-ROM set of the Digitized Sky Survey. Given the center coordinates and size of a field, GetImage will extract the corresponding data from the CD-ROM discs, uncompress the data, and write them to an image file. The input may be either interactive or read from a file. The output images may be written as FITS files or GEIS (hhh/hhd) images. Procedures for installing the software are provided in the files "install.unx" for UNIX systems and "install.vms" for OpenVMS systems. To be able to run GetImage on UNIX systems, the C-Shell script "getimage" must be in your path. On OpenVMS systems, you must define the global symbol "GETIMAGE" as follows: GETIMAGE == "@device:[directory]GETIMAGE.COM" where "device:[directory]" is the directory where the GetImage software resides. ******************************* * Read Me for GetImage page 2 * ******************************* II. RUNNING GETIMAGE -------------------- To run GetImage, enter "getimage" at the command line. The default behavior is then to take input interactively for each field, and to create a FITS file for each extracted image. The details for the options used to change the behavior of GetImage are given in Section III below. When GetImage is invoked with no options, you will be prompted with the following message: ---------------------------------------------------------------- For each field, enter in free format: * Field name of four characters valid for a filename, * Center coordinates (J2000): Right ascension: hh mm ss.sss in free format, Declination : Sdd mm ss.ss in free format, (where S is an optional sign), * Width and Height of field in arcminutes. eg, "Obj1 1 2 3.4 -0 1 2.3 4.5 6.7" Terminate the input list with EOF signal (^d UNIX; ^z OpenVMS). Enter data for first field: ------------------------------------------------------------- Enter the requested information, in free format, and GetImage will create a FITS image for each of your fields. The filenames for the output images will be "ffffpppp.fits" where ffff is the name you provided for the field, and pppp is the designation for the plate from which the field was extracted. For example, the filename of the image extracted for the field Obj1 in the prompt above would be "Obj1023a.fits", field Obj1 extracted from plate 023a. III. GETIMAGE OPTIONS --------------------- The usage for GetImage is: Usage: getimage [-abcefghjnqsuwzABCEFGHJNQSUWZ] [-[d,D] cd-rom_device] [-[i,I] input_file_of_fields] [-[m,M] cd-rom_mount_point] [-[o,O] output_file_of_extractions] [-[x,X] input_file_of_extractions] Note that the option flags are case INsensitive. -- -a,-c: Specify if all available images for a field are extracted (-a), or if only the image closest to a plate center (-c) is extracted. -c is the default. -b,-j: Set the equinox for the input coordinates: -b for B1950, and ******************************* * Read Me for GetImage page 3 * ******************************* -j for J2000. Only coordinates in equinox B1950 or J2000 are accepted. -j is the default. -d DEVICE: Specifies the device name for the CD-ROM drive. The name given by the environment variable (logical name) DSS_DEV will be overridden with the value DEVICE. -e,-n: Specify if images are actually extracted (-e) or not (-n). If -n is selected, then no images will be extracted. However, information about the extractions for the requested fields, including plate designation and (x,y) pixel position on the plate, will be output according to the -o option. -e is the default. -f,-g: Specify the format of the extracted images. -f directs GetImage to create FITS images (single files with the extension "fits"). -g directs GetImage to create GEIS images (pairs of files with the extensions "hhh" and "hhd"). -f is the default. -h: A brief description of all available options will be printed to the screen. -i FILE: By default, GetImage inputs field information interactively. The -i option directs GetImage to take input from a file named FILE, instead. The input file must have one record for each field. Each record is white-space delimited with the following format: ffff hh mm ss.sss Sdd mm ss.ss ww.ww hh.hh. where ffff is the name for the field, limited to 4 characters which must be valid for use in a file name, hh mm ss.sss Sdd mm ss.ss are the right ascension and declination for the field center at the equinox indicated by the -j or -b option, and ww.ww hh.hh are the width and height of the field in arcminutes. All quantities may be given in free format. -m MOUNTPOINT: Specifies the mount point for the CD-ROM on UNIX systems. The mount point given by the environment variable DSS_MTPT will be overridden with the value MOUNTPOINT. The -m option is ignored on OpenVMS systems. -o FILE: By default, GetImage outputs information about the extractions for each field to the terminal. The -o option directs GetImage to write the output to a file named FILE, instead. A file created with the -o option may be used as input with the -x option. -q,-s,-z: For use when running in batch mode (i.e., -i or -x with a file). The options indicate the action to take if the data needed for an extraction are not on the currently mounted CD-ROM disc. -q indicates to query the user. You would then have the option to mount the correct disc, skip the ******************************* * Read Me for GetImage page 4 * ****************************** extraction, or abort GetImage. -s indicates to always skip the extraction. -z indicates to abort GetImage. -q is the default. -u: By default, GetImage attempts to unmount (dismount) the CD-ROM disc upon exiting. The -u option overrides the unmounting (dismounting). If a CD-ROM disc was mounted before exiting, it is left mounted. -w: If the -w option is present with the -g option (create GEIS images), then the creation of the image files of GEIS images is overriden. Only the header files are created. -x FILE: Directs GetImage to extract images using extraction information from a file named FILE previously created by GetImage with the -o option. See Section IV below on how to create files for use with the -x option. Here is an example of using the options with GetImage: getimage -bgu -d /dev/sr1 -i object.coords -o object.extractions This command will invoke GetImage to take its input from the file object.coords (-i), write information about the extractions to the file object.extractions (-o), mount the CD-ROM discs on the device /dev/sr1 (-d) and create GEIS (hhh/hhd) images (g in -bgu). The options bu in -bgu will direct GetImage to assume the input coordinates are equinox B1950.0 (b), and upon exiting, not to unmount (dismount) the last mounted CD-ROM disc (u). IV. SELECTIVE IMAGE EXTRACTION ------------------------------ Because there is overlap among the plates of the Digitized Sky Survey, the fields you request may lie on more than one plate. By default, GetImage will extract the image for each of your requested fields which lies closest to a plate center. By specifying the -a option, you can direct GetImage to extract images from all plates which contain your field. To direct GetImage to extract images for your fields from specific plates, you must create an extraction file for input to GetImage with the -x option. An extraction file tells GetImage specifically what images to extract from which plates. You can create an extraction file with GetImage by specifying a file name with the -o option. The extraction file created by GetImage will contain extraction information for all the fields you request from GetImage. To perform selective image extraction, first create an extraction file with extraction information for your fields and all the plates on which they lie. Do this by running GetImage with the -a option (to list extractions from all relevant plates), the -n option (to suppress actual image extraction), and the -o option with a file name (to create the ******************************* * Read Me for GetImage page 5 * ******************************* extraction file for your fields). The created extraction file will contain extraction information for your fields grouped by the CD-ROM discs from which they would be extracted. Second, edit the extraction file to include only the extractions for which you wish to create images. Finally, run GetImage with the -x option specifying the name of your edited extraction file. GetImage will then perform your selected extractions, prompting you to mount CD-ROM discs as required. V. BUGS AND OPERATING SYSTEM PROBLEMS ------------------------------------- V.a. Bugs --------- When a request by GetImage to dismount a CD-ROM disc fails, GetImage will proceed with instructions to the user to mount the next CD-ROM disc rather than query the user for the appropriate action to handle the dismount failure. V.b. DEC OpenVMS ---------------- On OpenVMS systems, it is more efficient to link programs against the appropriate C RTL shareable image rather than to link against the C RTL object library. However, GetImage is linked against the C RTL library because of the difficulty in determining the version of C being used in order to identify the appropriate C RTL shareable image to link against. On DEC Alpha AXP or VAX platforms using version V4.0-000 or earlier of the DEC C compiler, and the OpenVMS (AXP or VAX) operating system version 6.1 or earlier, an access violation will occur when exiting GetImage after attempting to request an image extraction that is too large for the available memory. Under OpenVMS (AXP or VAX) version 6.1, VOLPRO privilege is required to mount an ISO 9660 volume. DEC has acknowledged that this behavior is incorrect and that no privilege should normally be required. There is currently no patch available, and no workaround that does not impact system security. V.c. SGI IRIX ------------- The readdir function in the C runtime library is broken under IRIX 5.2. It prevents commands such as ls and operations such as shell expansions of wildcard characters from working properly in some cases. Unfortunately one of the cases is the headers directory on the ******************************* * Read Me for GetImage page 6 * ******************************* Digitized Sky Survey CD-ROM. The files are accessible, but you have to know ahead of time what the file identifiers are. We have reported the problem to SGI, but have not yet received a response. V.d. Sun Solaris ---------------- Under Solaris 1.x (SunOS 4.1.x) and Solaris 2.x, the hsfs driver must be patched in order to access the files on CD-ROM discs. See the software installation notes that accompany Part II of the Digitized Sky Survey for more information. Under Solaris 2.3, there is a bug in the hsfs driver that replicates file contents. Sun does not seem to want to acknowledge the problem. A service order has been open since mid october 1994, and we cannot find out whether Sun will fix the problem in 2.3, whether Sun will insist that people use Solaris 2.4 (where it seems to be fixed), or any timescale on making a decision. The problem is not easy to work around since you have to copy the files individually and dismount and remount the disk about 50 times to get all of the files. There seems to be a compiler bug in Sun C 3.0.1 that misplaces the tiles on large extractions (of order 80 arcminutes square). The nature of this problem is not understood, but is actively being investigated. VI. PROBLEMS ------------ If you have any problems, suggestions or comments about GetImage, please send e-mail to getimage@stsci.edu. A. PLEASE NOTE -------------- ************************************************************************** ASTROMETRY FROM THE STScI DIGITIZED SKY SURVEY CD-ROM SET All plates used for the northern part of the Digitized Sky Survey (the 1950 epoch POSS E plates) and a limited number of plates from the southern part were NOT used to construct the Guide Star Catalog. As a consequence, coordinates derived for targets from these digitized images will NOT be in the Guide Star reference frame. HST users are requested not to use coordinates derived from the Digitized Sky Survey CD-ROMs in preparing their phase II documents. **************************************************************************