4 UIMAGE This chapter describes the UIMAGE package, which was specially designed for the COBE mission. In the first two sections, you will find out how UIMAGE works with the COBE data as well as how to move around in the package. Section 4.3 presents important information about reading and writing data into or out of UIMAGE, including the released data products. Section 4.4 contains a description of and menu paths to the each UIMAGE function. The UIMAGE menu tree is shown in Appendix A for quick reference. 4.1 WHAT IS UIMAGE? UIMAGE is COBE's IDL-based image analysis tool. It is menu-driven, has online help, and affords a modest set of standard image analyses such as image arithmetic, smoothing, zooming, reprojection, contour plotting, and modeling. It can read all available COBE skymaps, and can read and write both FITS files and IDL save sets. Perhaps most importantly, it allows the user to conveniently switch to the IDL command line in order to perform any custom-written analyses that are not a part of the UIMAGE menus. UIMAGE operates on the standard projection for COBE data, i.e., the quadrilateralized spherical cube, referred to as the skycube. A typical COBE skymap is an unfolded skycube, based upon ecliptic coordinates with skyward- looking orientation. The faces of the unfolded cube are aligned as shown in Figure 4.1. +----+ | 0 | +----+----+----+----+ | 4 | 3 | 2 | 1 | +----+----+----+----+ | 5 | +----+ Figure 4.1 A right T, or unfolded skycube. The center of face 0 corresponds to the North Ecliptic Pole and the center of face 5 is the South Ecliptic Pole. The ecliptic plane runs horizontally through the middle of faces 1 through 4 with 0 degrees at the right side of face 1 and 360 degrees at the left side of face 4. These maps have resolution N which each face has 4^(N-1) pixels. UIMAGE lets you work with whole maps, individual faces, or zoomed sections. To conserve space, disk files of the rasterized skycube are often stored in a packed cube format, the sixpack with the faces aligned in this manner: +----+-----+----+ | 4 | 5 | 0 | +----+-----+----+ | 3 | 2 | 1 | +----+-----+----+ Figure 4.2 A compact unfolded skycube, commonly called a sixpack. It is of course possible to reproject a COBE skymap into a more aesthetically pleasing display, such as an Aitoff map. Since the data were originally pixelized into the skycube, however, reprojections carry a certain cost in photometric accuracy in each of the reprojected pixels; COBE's extreme photometric accuracy requirements make this an important consideration. UIMAGE is optimized to work with skycube data with the original photometric integrity. It permits you to form other projections and perform some operations on them, but you should be aware that in such cases UIMAGE is actually performing the operation on the original skycube for photometric accuracy. UIMAGE also accommodates remote users who might be logged on to a non-X Windows terminal with only VT240 or Tektronix graphics capabilities. From such a terminal you will still be able to perform data I/O, make contour maps, crosscuts, histograms, and even crude grey scale plots. You can also do image algebra and perform certain statistical studies. (It is occasionally surprising to rediscover how much can be done without actually viewing a glitzy color image.) Some of those tools allow for transfer of data between UIMAGE and UIDL to give the user the best of both worlds. 4.2 NAVIGATING THROUGH UIMAGE UIMAGE is menu-driven, with the exception of occasional prompts for specialized information. On a workstation you choose your menu selection by moving the mouse and pressing the left button to make a selection; on a text terminal, use the arrow keys to highlight your choice and a carriage return to enter it. As mentioned in section 1.2, we will represent a carriage return with a and the left, center, and right mouse buttons respectively as , , and . Control characters will be indicated with a carat, such as ^Z (which means press and hold the control key and then press Z). Users should be aware that occasionally UIMAGE will not respond to a mouse button click or the striking of an arrow key. Mouse users can try holding the mouse button down for a slightly longer time; UIMAGE has received the message when the current menu disappears. If at any time you want to refresh a terminal display or DECterm window, type ^W. =============================================================================== WARNING! DO NOT TYPE ^Y! This will eject you from the CGIS Executive as well as UIMAGE, and you will lose all of your data! =============================================================================== Also, note that on the menu screens, the cursor has been terminal disabled. This means that if you are a VT240 user and you switch to another session, the cursor is also disabled in that session. You will have to reset your terminal to get the cursor back. (Since each terminal is different, consult your terminal setup to determine how to do this.) 4.2.1 Starting Up UIMAGE From the CGIS Main Menu, choose COBE Data and Analysis Menus (UIMAGE)... If you are not working at an X Windows terminal, you will be prompted for your terminal type: +------------------------+ | Identify terminal type | +------------------------+ | REGIS | | TEK | | Other | +------------------------+ Choose REGIS if your terminal is set for REGis graphics emulation (e.g., a VT240 or Micro-Term), or TEK if you are using a Tektronix, GraphOn, or other Tektronix emulator. Other is the appropriate choice for VT100 and other terminals that do not support graphics. Use the down arrow key to highlight your choice, then press . Users on all terminal types are then presented with the UIMAGE Main Menu: +--------------------------------+ | UIMAGE [MAIN MENU] | +--------------------------------+ | Data I/O and Management... | | | | Display Manipulation... | | Image Enhancement... | | Algebraic Operations... | | Spectrum Operations... | | Line Plots and Statistics... | | Modeling and Fitting... | | | | Journal Enable/Disable ON | | Report Problems or Comments | | | | HELP | | Exit UIMAGE | +--------------------------------+ As in the Executive, selecting a menu item containing an ellipsis produces another menu level. The UIMAGE Main Menu consists of seven submenus (see Appendix A for the UIMAGE menu tree). On all but the main menu, the last menu item is a Return or Exit which, when selected, will return to the previous menu page. Choosing Exit UIMAGE returns the user to the environment in which UIMAGE was started (CGIS or UIDL). 4.2.2 Journaling The Journal Enable/Disable menu line toggles the creation of an ASCII history file that keeps track of your UIMAGE session, including its numerical output. Journaling is ON by default; the journal file is called UIMAGE.JNL and is created in your login directory. You may change the name of the file by turning the journaling off and back on again. You will then be prompted for a journal file name. A typical journal file for reading an object using the Data I/O and Management option would look like this: ------------------------------------------------------------------------ DATAIO subsystem input format: FITS (used READFITS) data set contains FIRAS data file name: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHSS.FITS;1 field name: REAL_SPE (9) entire cube selected output format: UIMAGE internal format data object title: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHSS [1] ------------------------------------------------------------------------ If you choose Report object attributes from the Data I/O and Management menu, you would get a journal file like this: ------------------------------------------------------------------------ Report object attributes Attributes of CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHSS [1] Array dimensions: 128 x 96 Associated 3-D object: Associated weights: Hidden object: Bad pixel value: 0.000000 Band number: 0 Band width: 0.000000 Coordinate-system: ECLIPTIC Data minimum: 0.746848 Data maximum: 221.898 Frequency: 1.00000 Instrument: FIRAS Orientation: R Projection: SKY-CUBE Resolution Index: 6 Scaling minimum: 0.746848 Scaling maximum: 221.898 Units: MJy/sr ------------------------------------------------------------------------ If you changed the title of an object or graph, you would see the old title and the new title separated by an arrow. ------------------------------------------------------------------------ Change a title operand: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHSS [1] new title: Low Freq ------------------------------------------------------------------------ The next excerpt journals the process of taking a cross section. It indicates which object was used to mark the cut and then the name of the output graph. Note that the name of the output graph also contains the coordinates of the endpoints of the cross section. ------------------------------------------------------------------------ Cross sections, Sky cuts operand: Low Freq output graph: SC (298.7,30.7) to (238.3,-32.8) E [1] ------------------------------------------------------------------------ If you performed an edge enhancement on an object, the journal entry would resemble the following, showing the bad pixel value, the type of filter used, and the name of the edge enhanced object. ------------------------------------------------------------------------ Edge enhancement operand: Low Freq the following statement was executed: result = ENHANMAP(MAP6(0).data, bad = badpixval, type = type) where: MAP6(0) is the name of the operand's structure bad = 0.000000 type = ROBERTS result --> ROBERTS("Low Freq") ------------------------------------------------------------------------ The journal entry for a scatter plot shows the two objects used and the name of the resulting scatter plot. ------------------------------------------------------------------------ Scatter plot 1st image: ROBERTS("Low Freq") 2nd image: Low Freq resulting graph: Scatter plot [1] ------------------------------------------------------------------------ The journal file for the statistics and histogram option in UIMAGE lists the statistics of the chosen object and the bin size used to make the histogram. ------------------------------------------------------------------------ Statistics & Histogram operand: ROBERTS("Low Freq") an area of the image was selected minimum = 5.000000 maximum = 1091.00 mean = 308.479 median = 220.000 standard deviation = 284.919 # of pixels = 25 the following command was executed: result =HISTOGRAM(image(gooddata), binsize=binsz, min=minimum, max=maximum) where: image is the data in the operand's structure gooddata is the good pixels binsz = 43.4400 hist --> Histogram of user defined area [1] ------------------------------------------------------------------------ UIMAGE's journal option is an easy way to keep a useful and complete log of an analysis session. 4.2.3 Reporting Problems or Comments In the event that you encounter difficulties or you just wish to make a suggestion, select the Report Problems or Comments item on the main menu. (See section 2.2.9 for more details about reporting comments or problems.) You will be presented with a short, helpful form in a text editor; your message will automatically be sent to the appropriate person. ALL MESSAGES WILL RECEIVE A RESPONSE! We are interested in your feedback. 4.2.4 Getting into and back from UIDL UIMAGE is layered on top of UIDL, which is simply IDL with a library of useful tools -- some COBE-specific, some not -- written variously in C and IDL. This explains why certain severe errors expel a UIMAGE user into UIDL. If this should happen to you, simply type UIDL> UIMAGE Fear not -- your UIMAGE data will remain intact as UIMAGE restarts itself. (You will, however, lose graphical overlays such as contour plots.) The Exit UIMAGE item on the UIMAGE main menu puts you back at the CGIS Main Menu (unless you last invoked UIMAGE from UIDL). From this menu, choose Go to Command Line (UIDL). You will see Type EXIT to return to VMS or type CGIS to return to the main menu... UIDL> From here, you can execute any IDL or UIDL command, and you can also pull your maps and graphs out of UIMAGE to operate on them in this environment with tools of your own devising. See chapter 5 for an explanation of some commonly-used UIDL tools. You can return to UIMAGE from UIDL directly simply by typing UIMAGE at the UIDL> prompt. UIMAGE will then restart, and will bring forth all of the maps you were working with before you went into UIDL, plus any that you've brought in via UIDL. 4.2.5 Exiting The EXIT UIMAGE item on the UIMAGE main menu returns you to your environment prior to invoking UIMAGE. For example, if you called UIMAGE from the CGIS software, you will be returned to the CGIS Main Menu or if you called UIMAGE from the UIDL command line, you'll be returned to the UIDL environment. If you entered UIMAGE directly from the operating system, you will be returned to UIDL. To exit a menu other than the main menu, choose the bottom menu item which is either Return to previous menu or Return to MAIN MENU. Note: If you called UIMAGE from the CGIS Main Menu but are returned unexpectedly to the UIDL> prompt upon exiting UIMAGE, you probably suffered an error at one point in your UIMAGE session and crashed into UIDL. Just type CGIS, UIMAGE, or EXIT at the UIDL> prompt to return to the CGIS Main Menu, UIMAGE, or the operating system, respectively. (See the previous section for more details.) 4.2.6 Getting Help Every UIMAGE menu page has a help option that provides detailed information about that page. Appendix A of this document shows the help text for each of the menus in the two top levels of UIMAGE. Help information appears in a text window of its own through which you can scroll. Figure 4.3 illustrates a typical VT240 help screen. VT240 users can scroll through the text either by using the arrow keys or by following the instructions at the bottom of the window (spacebar to move forward one screen, B to move back one screen). Press H for additional scrolling information (or see Appendix C). Pressing TAB will terminate the help screen. Pressing Q returns you to the UIMAGE Main Menu. +----------------------------------------------------------------------------+ | Help for "DATA I/O AND MANAGEMENT" | +----------------------------------------------------------------------------+ | | | Read a data set... invokes a submenu describing the kind of data | | sets that are available. These are: the COBE initial product | | : | | (more text) | | : | | Removing objects for which you no longer have any use is good | | practice, as it frees up machine memory. | | | +----------------------------------------------------------------------------+ | Next Scrn=(Space) Prev Scrn=(B) Help=(H) Exit=(Tab) | +----------------------------------------------------------------------------+ Figure 4.3 A typical VT240 UIMAGE help screen. X Window users will instead see help screens like the one shown in Figure 4.4. Workstation users can use the vertical and horizontal scroll bars to move through the text. A single click in the line of the scroll bar (but not directly on the scroll bar) moves the text up/down (vertical bar) or left/right (horizontal bar) part of one screenful. clicks on the small arrows at the ends of the scroll bars will move the text up or down one line at a time or left or right one character at a time. Users may also press and hold on a scroll bar, slide it up/down or left/right, and then release ; the text will update. End the help session by clicking on the Done button. ++---+--------------------------------------------------------------+---+---+ || - | Help for "DATA I/O AND MANAGEMENT" | o | O | |+---+--+-----------+-----------------------------------------------+---+---+ || Done | File Dump | | |+------+-----------+---------------------------------------------------+---+ || | ^ | || Read a data set... invokes a submenu describing the kind of data |+-+| || sets that are available. These are: the COBE initial product || || || : || || || (more text) || || || : || || || confirmed, then the "dependent" objects will also disappear. || || || |+-+| || | v | ++----------------------------------------------------------------------+---+ || +-------------------------------------------------------------+ | | || < | | > | | || +-------------------------------------------------------------+ | | ++----------------------------------------------------------------------+---+ Figure 4.4 A typical X Window help screen. For help with general IDL questions, users should consult RSI's IDL manuals, or see section 5.4.2 for information on using the online help. 4.2.7 A Word on Terminology Anything that can be manipulated by UIMAGE is known as an object. Objects can be graphs, 2-D images (i.e., skymaps at a single frequency), or 3-D spectral cubes. Every object has a title and (on a workstation) resides in a UIMAGE window. Every object is also associated with a set of ancillary data called attributes such as its projection type, coordinate system, skycube resolution, and minimum and maximum values. The set of attributes depends upon whether the object is a graph, 2-D image, or spectral cube. Because references to 2-D and 3-D objects will be made often, an object type list follows, showing the breakdown used in this chapter. (See also Figures D.1 and D.2 in Appendix D for examples of the objects listed below.) Graphs Histograms spectra from individual pixels Intensity along the arc of a spatial cut 2-D Objects Unfolded skycube of intensity for a single frequency Reprojections of skycubes 3-D Objects A spectral cube (frequency stack) for a skycube Users should be aware that the terms skycube and spectral cube are frequently used throughout this guide; therefore, it is important to be able to differentiate between them. Note that a skycube refers to the COBE pixelization format (see figure 4.1), and a spectral cube is a data set consisting of several skycubes at different frequencies. 4.3 GETTING DATA INTO AND OUT OF UIMAGE NOTE: UIMAGE has limitations on the amount of data that can be handled in one session. Users should be aware that different machines (VMS, ULTRIX, and PC) have different capacities for data storage. However, on ALL machines, UIMAGE will retain only three 3- D objects (spectral cubes) in its memory at any given time. 4.3.1 Reading in COBE Data Sets The first option on the UIMAGE main menu is Data I/O and Management... Select it! You will now find yourself in the Data I/O and Management submenu, which looks like this: +-----------------------------------+ | DATA I/O AND MANAGEMENT | +-----------------------------------+ | Read a data set... | | Write a data file... | | Create a PostScript file | | Associate weight with an object | | Extract Face from skymap | | Combine 2D objects into 3D object | | | | Report object attributes | | Remove an object | | Display/hide an object | | Remove ALL objects | | | | HELP | | Return to MAIN MENU | +-----------------------------------+ Choose Read a data set. Now you'll get a menu that looks like this: +--------------------------+ | Select Input Format | +--------------------------+ | FITS Files | | COBE IDL Save Sets | | COBE Sky Maps | | | | HELP | | Return to previous menu | +--------------------------+ The first item, FITS Files, is the format of the released COBE skymap products. Select it. Now you will see the following prompt. Enter the directory to search for your data. Press Return to use the default directory: CGIS_FITS. Enter "back"to return to the previous menu. CGIS_FITS is defined as ADBDISK:[PDS_FITS]. > To read in any of the COBE products, simply press . This accesses the files in the default directory ADBDISK:[PDS_FITS] which contains the Project Data Sets for DIRBE, DMR, and FIRAS. The file names are relatively explanatory of their contents. For example, suppose you're interested in the FIRAS's Right High Fast channel (RHF). To read in this data set, you would choose the file FIRAS_ALL_SKY_SPECTRA_RHFA.FITS;1. Note: The UIMAGE default directory may change to point to the more complete Project Data Sets once they have been released. After you have selected the file, you may read its primary FITS header by answering Yes at the prompt: +-------------------------------------------+ | Would you like to review the FITS header? | +-------------------------------------------+ | Yes | | No | +-------------------------------------------+ If you choose to review the header, you will be placed in a text screen containing the header information. The status bar at the bottom of the text window (VT240 terminals only) reveals how to move through the screen. (See section 4.2.6 for more details on moving through these text screens.) After you have reviewed the standard FITS header, UIMAGE asks if this is in fact the file you would like to use: +---------------------+ | Use this FITS file? | +---------------------+ | Yes | | No | +---------------------+ If you choose No, UIMAGE returns you to the list of input format types. If you choose Yes, you are given the option of reviewing the extended header: +------------------------------------------------+ | Would you like to review the Extension header? | +------------------------------------------------+ | Yes | | No | +------------------------------------------------+ Whether or not you review the header, UIMAGE will then read in the specified file. Now UIMAGE presents a listing of the fields to choose from. UIMAGE's data utility knows what fields are present for the released products, so you will be given a list specific to the COBE instrument you have chosen. For the FIRAS Right High Fast PDS, for example, the Field List looks like this: +-----------------------------+ | Field List | +-----------------------------+ | PIXEL | | ECLON | | ECLAT | | REAL_SPE | | SIGNAL+WEIGHTS(DETECTOR) | | IMAG_SPE | | SIGMAS | | GLITCH_R | | NUM_IFGS | | NUM_TEMP | | TIME | | CHANSCAN | | DATATYPE | | DESTRIPE | | CALIBRAT | | NU_ZERO | | DELTA_NU | | NUM_FREQ | | BOLOM_BI | | BOLOM_VO | | DC_RESPO | | TIME_CON | | PHASE_CO | | XCAL_TEM | | ICAL_TEM | | SKYHORN_ | | REFHORN_ | | DIHEDRAL | | MIRROR_T | | BOLOM_TE | | BATH_TEM | | GALACTIC | | GALON | | GALAT | | RA | | DEC | | MOON_ANG | | GALATEXC | | | | HELP | | Return to previous menu | +-----------------------------+ The Explanatory Supplement for each instrument contains a description of data field names. The REAL_SPE is of primary interest at the moment so select it. You will see the following on your screen: You have selected field REAL_SPE . This field has an array of values for each pixel, so you should now select a range of elements or the retrieve the entire field. Dimensions of REAL_SPE : (1:168) For a range, use a colon to separate the upper and lower bounds. Type "ALL" if you want the data for the entire field REAL_SPE . Specify units with the range using one of the following: Valid Ranges IDX (default) - indices (1,168) GHZ - gigahertz (67.913,2903.27) ICM - wave numbers (2.265,96.84) Examples: ---> 1:50 IDX (gets the first 50 channels.) ---> 60:80 ICM (gets all channels within the range of wave numbers 60 and 80.) ---> 1:5 IDX Here we chose the first five channels. You may also type BACK to go back to the Field List menu. Your last task is to choose which faces of the skycube you want to extract. Do so from this menu: +---------------------------------+ | Select Map Face | +---------------------------------+ | All - Right-handed T | | Zero - North Ecliptic Pole | | One - South Galactic Pole | | Two - Galactic Anti-Center | | Three - North Galactic Pole | | Four - Galactic Center | | Five - South Ecliptic Pole | | | | HELP | | Return to previous menu | +---------------------------------+ The locations listed for each face are given to help you to orient yourself to the skycube projection so that you may choose an appropriate section of the sky. Various informational messages will appear to update you on the progress of the ingest. Since a range of frequencies was read in, i.e., a 3-D object, no skymap appears because (lacking a three dimensional screen) there is no way to display the whole data object. On the workstation (or other X Window configuration), you will see a dummy data object window that shows (1) the object's title, (2) the notation 3-D Object; and (3) two postage stamp-sized icons that show the frequency slices from the first and last subscripts in the range. This window serves mainly as a reminder that the object is resident in memory and available for use. VT240 users will not see a graphical display, but will find that the object has been entered into the list of available 3-D objects. The title of the object will be the name of the data set that you chose, followed by a number in square brackets, e.g., CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA [1] This allows you to differentiate between objects from different fields of the same data set. Those users who have access only to the released data products may wish to skip the next four sections, which pertain to other forms of data input, for now. Sections 4.3.6 through 4.3.8 describe various forms of data output. Section 4.3.9 discusses how to associate a weight with a data object, section 4.3.10 shows how to combine single frequency skymaps into a spectral cube, and section 4.3.11 details how to create a hardcopy of an image. Skip to section 4.4 for instructions on using UIMAGE's analysis tools. 4.3.2 Reading in Arbitrary Archive Data Sets UIMAGE is not restricted to the COBE released data products. You can read in any archive data set, though you must know its location and valid field names. You must also have read access privilege to the file. (This option works only on the COBECL cluster and is not available to guest investigators.) To read in an archive data set, first follow this sequence through the menus: +------------------+ +-------------------------+ | UIMAGE Main Menu |----->| Data I/O and Management | +------------------+ +-----------+-------------+ | +-----<-----------+ | | +--------------------+ +---------------+ +---->| Read a data set... |----->| COBE Sky Maps | +--------------------+ +---------------+ When the instrument menu comes up, select User Defined. You will be prompted on the command line for the following items: Archive or directory name of your skymap file File name Cube face number Field name For example, a typical data input exchange looks like this (UIMAGE prompts in bold fixed-width font, user response in fixed-width plain font): Skymap Directory or Archive : DIRBE_PDS1:[DIRBE_EDIT] File Name ( to exit BUILDMAP): B_IP_GS.INIT_PROD_931741607 Getting Resolution of Skymap This last message is just to let you know that UIMAGE is looking for the file. From the next menu, direct UIMAGE to read in the entire skycube or to read in one particular face: +-----------------------------------+ | Cube/Face Selection | +-----------------------------------+ | Entire Cube | | Face 0 - North Ecliptic Pole | | Face 1 - South Galactic Pole | | Face 2 - Galactic Anti-Center | | Face 3 - North Galactic Pole | | Face 4 - Galactic Center | | Face 5 - South Ecliptic Pole | +-----------------------------------+ Now type in a field name. The DIRBE data in this file are stored in the array PHOTOMETRY, from which you can retrieve one frequency point for a 2-D object or a range of frequencies for a 3-D object. The exchange looks like this: Field Name 1 ( to exit BUILDMAP): PHOTOMETRY(1) Field Name 2 ( to proceed) : This will retrieve the photometry data from all pixel records in the file within the selected portion of the skycube. To read in a range of frequencies, separate the starting and ending indices by a colon, e.g., PHOTOMETRY(1:3), remembering that UIMAGE will only allow three 3-D objects in memory. (Array indices here begin with 1.) You must give a after the prompt for Field Name 2 in order to continue. You will then receive some status messages as UIMAGE gets the data: Reading Data From Skymap File 100% read [Updates as data are read in.] Fetched 24108 records [...or whatever the number is] Rasterizing Data Build Completed NOTE: If you read in a 3-D object, you'll need to proceed through these next steps. If, however, you read in a 2-D object, skip down to the ancillary data prompts. Unlike the case of released products, UIMAGE will not have picked up any frequency information since it has no idea where to find it in this arbitrary data set. (Note that FIRAS frequencies are equally spaced; DIRBE and DMR frequencies are not.) UIMAGE will prompt you for the missing information like this: FREQUENCY was not passed in. (A 1-D array of frequencies/wavelengths must be supplied for 3-D data objects.) +-----------------------------------------+ | Use indices as frequencies/wavelengths? | +-----------------------------------------+ | Yes | | No | +-----------------------------------------+ Note that you must supply a 1-D array of frequencies or wavelengths for a 3-D data object. If you choose Yes then UIMAGE will simply use the array index numbers themselves as an arbitrary frequency/wavelength designation. Choosing No implies that you have some real information about what the frequencies or wavelengths are, so UIMAGE will ask you for it: +----------------------------------------------------+ | Enter a start_freq./wave. and a delta_freq./wave.? | +----------------------------------------------------+ | Yes | | No | +----------------------------------------------------+ This is a good option if the data points are equally spaced in frequency. Select Yes only if you know both the starting point and the frequency interval; UIMAGE will then prompt you for the two numbers. The units are arbitrary: they can be wavelengths rather than frequencies, for example. If you say No, UIMAGE assumes that you have detailed information about the frequency or wavelength vector. You will be asked another question: +-------------------------------------------------+ | Manually enter frequencies/wavelengths or quit? | +-------------------------------------------------+ | Enter freq./wave. | | Quit | +-------------------------------------------------+ Selecting the former will cause UIMAGE to prompt you for the frequencies, one array index at a time. Obviously, this is not such a hot idea for big spectra. If you select Quit, UIMAGE will NOT retain the object in memory! You will be returned to the Data I/O menu. Table 4.1 below lists several FIRAS frequencies and the DIRBE wavelengths. Note that FIRAS frequencies are evenly incremented at intervals of 16.978 Ghz. For example, the FIRAS frequency associated with a subscript of 6 would be: Frequency(6) = Frequency(1) + ((6-1) * 16.978) = 152.803 +--------------------------+------------------------+ | High-frequency | | | FIRAS DATA | DIRBE DATA | +--------------------------+------------------------+ | Subscript Frequency | Subscript Wavelength | | (Ghz) | (um) | +--------------------------+------------------------+ | 1 67.9128 | 1 1.25 | | 11 237.695 | 2 2.20 | | 21 407.477 | 3 3.50 | | 31 577.259 | 4 4.90 | | 41 747.041 | 5 12.0 | | 51 916.823 | 6 25.0 | | 61 1086.60 | 7 60.0 | | 71 1256.39 | 8 100.0 | | 81 1426.17 | 9 140.0 | | 91 1595.95 | 10 240.0 | | 101 1765.73 | | | 111 1935.51 | | | 121 2105.30 | | | 131 2275.08 | | | 141 2444.86 | | | 151 2614.64 | | | 161 2784.43 | | +--------------------------+------------------------+ Table 4.1 Frequencies and their corresponding UIMAGE subscripts. When reading in either 2-D or 3-D objects, UIMAGE will now prompt you for the ancillary data about the data object. The prompts will look like this: BADPIXVAL = bad pixel value (float, default = 0.): BANDNO = band number (integer, default = 0):* BANDWIDTH = band width (float, default = 0.):* COORDINATE_SYST = coordinate system (string, default = "ECLIPTIC"): FACENO = cube face number (integer, default = -1): FREQUENCY = frequency (float, default = 0.):* FREQUNITS = frequency description (string, default = "Frequency (MHz)"):** INSTRUME = instrument name (string, default = "UNKNOWN"): ORIENT = cube orientation (string, default = "R"): PROJECTION = projection (string, default = "SKY-CUBE"): TITLE = image title (string, default = "Object"): UNITS = data description/units (string, default="Pixel value (unknown units)"): * 2-D objects only ** 3-D objects only In general, the defaults will be acceptable or the answers will be obvious (as in the prompt for INSTRUMENT), but be sure to give a descriptive title, especially if you intend to read in more than one data set. After you've answered all the questions and if you're on a workstation, a UIMAGE window will appear with your object's title (and the image itself if it's a 2-D object), and you can treat it like any other UIMAGE object. Users of terminals will not see a display, but the object has been stored in memory and will appear on future object lists. 4.3.3 Reading in IDL Save Sets The fastest way to get a map into UIMAGE is via a previously created IDL save set. Suppose that you have already created a save set in your home directory via UIMAGE (see section 4.3.6) called MYMAP.SAV from a skymap that you were using in some other analysis. It can be a skycube face (i.e., a square array), a fully unfolded map with a 4:3 x:y aspect ratio, or a compressed (sixpack) map with a 3:2 aspect ratio (see figures 4.1 and 4.2). This means that the DATA variable must have array dimensions that are the same as array dimensions for COBE skycubes, individual faces, or sixpacks at resolutions 6 through 9, that is: Resolution Skycubes Single Face Sixpack ---------- -------- ----------- ------- 6 128 x 96 32 x 32 96 x 64 7 256 x 192 64 x 64 192 x 128 8 512 x 384 128 x 128 384 x 256 9 1024 x 768 256 x 256 768 x 512 Spectral cubes may also be read in if the first two dimensions are found in the table above. For example, a resolution 6 single face spectral cube containing three frequencies will have dimensions of 32 x 32 x 3. If these criteria are satisfied, select these menu choices: +------------------+ +-------------------------+ | UIMAGE Main Menu |----->| Data I/O and Management | +------------------+ +--------+----------------+ | +----------<-----+ | +--------------------+ +--------------------+ +--->| Read a data set... |---->| COBE IDL Save Sets | +--------------------+ +--------------------+ You will now be prompted for a directory and file name: Enter the directory to search for your data. Press Return to use the default directory: CGIS_CISS. Enter "back" to return to the previous menu. CGIS_CISS is defined as ADBDISK:[CGIS_CISS]. > Type in the name of the directory, or give a at the last prompt, and UIMAGE will choose the displayed default directory. Once a directory has been specified, you must choose which save set to read in via a menu that will look like this: +--------------------------+ | Select Data Set | +--------------------------+ | Save_set_1 | | Save_set_2 | | ... | | Save_set_n | | | | Help | | Return to previous menu | +--------------------------+ Select a save set to be read in. A verification message appears, followed by the next prompt: Data variable name (default = "DATA"): Type in the name of the variable holding your data. If the name is DATA or if you aren't sure of the name, just press . Depending on the contents of your save set, you will then see all or some of the following informational messages: % Identifiers can only be added or deleted at the main level: unrecognized_var1 : % RESTORE: VMS only SAVE/RESTORE file. % RESTORE: Save file written by jouser@blahblahblah, date time. % RESTORE: Restored variable: recognized_var1. : % RESTORE: Restored variable: recognized_varn. If UIMAGE cannot find the specified variable, it will prompt you again: The specified variable was not in the saveset. Which of the variables listed above contains the desired data? Variable name (enter "E" to exit): Enter the appropriate variable name from the list at the prompt, or type E to exit. If you are restoring a spectral cube, you will need to specify a frequency or wavelength array. If the array is named FREQUENCY, it will be automatically restored from the save set. If the array has another name, you will be prompted for it. If there is no frequency information in the save set, you will be prompted with the choices described in section 4.3.2. Once UIMAGE has the data, it will lead you through the series of prompts for ancillary data, just as it did for archive save sets (described in 4.3.2). You can forestall all of the prompting if your save set contains those ancillary variables with the names as listed in the prompts. UIMAGE will always check to see which of the variables occurs in the save set and will prompt you for the values of the missing ones. It is also smart enough to check the x:y aspect ratio of the data array to determine whether it is looking at a full skymap (either unfolded or in sixpack form) or a single face. If the latter, UIMAGE will look for a variable (called FACENO) identifying the face number, and include it in the prompts if it is not found. If the data is a sixpack, UIMAGE automatically unpacks it and makes it a 4:3 aspect ratio skycube. 4.3.4 Reading in Data Sets from UIDL Data objects can be transferred easily between UIMAGE and UIDL. Suppose you have a variable called F20SMOOTH in UIDL. You may copy it into UIMAGE using the UIDL routine UPUTDATA. UPUTDATA will read in any variables with array dimensions equal to array dimensions for COBE skycubes, individual faces, or sixpacks at resolutions 6 through 9 (see section 4.1 for further explanations on sixpacks and skycube resolution). See the list of compatible array sizes in section 4.3.3. To use UPUTDATA, simply type UIDL> UPUTDATA, F20SMOOTH You will then be prompted for all of the ancillary variables (see section 4.3.2). Answer the prompts appropriately and, as ever, be sure to give the object some informative title. You may also avoid all of the prompting by supplying the keywords on the command line. This is the only way to pass in a specific array of frequency values. Type UHELP, 'UPUTDATA' for the extended calling sequence. You can repeat this process with as many variables as you like. When you are ready to go back into UIMAGE to work with them, just type UIDL> UIMAGE and UIMAGE will reactivate with your newly-transferred objects included in the menus. All of the objects that were present when you moved into UIDL will remain. However, the color tables have been reinitialized, and you have lost any graphics overlays such as coordinate grids or contour overlays. 4.3.5 Reading in FITS Files The FITS input capabilities in UIMAGE are currently limited to reading in the released product skymaps and user FITS files that have been previously written out by UIMAGE. Users who would like to read in rasterized FITS files should see section 5.5.5.1 on the READFITS routine, which provides details on reading in FITS files through UIDL. If you have previously written a FITS file with UIMAGE and want to retrieve it, choose +------------------+ +-------------------------+ | UIMAGE Main Menu |--->| Data I/O and Management | +------------------+ +----+--------------------+ | +----<---------------+ | | +--------------------+ +------------+ +--->| Read a data set... |---->| FITS Files | +--------------------+ +------------+ At the prompt, enter the directory name where UIMAGE can find your data set. NOTE: File names must have a .FITS file name extension for UIMAGE to find them. Also, in the unlikely event that a file has either the string _MOD or PIXPERM in its name, it will be filtered out and not seen in the list of available files. From the list of files found in the specified directory, choose which object to read in. You may now review the FITS header if you desire to do so. If you review the header, the next question inquires whether or not to continue on with this data set. Choose Yes to continue. If this data object was previously associated with a weight array, you can have that array read in as well by answering yes to the next prompt: The file that you have selected has a weighting array +------------------------------------------------+ | Would you like to read in the weighting array? | +------------------------------------------------+ | yes | | no | +------------------------------------------------+ The object is now available as a UIMAGE object, complete with its weight (if previously associated). 4.3.6 Writing IDL Save Sets To write a data set to an IDL saveset, select +-----------------+ +-------------------------+ +---------------------+ |UIMAGE Main Menu |--->| Data I/O and Management |--->| Write a data file...| +-----------------+ +-------------------------+ +---------------------+ From the object list, Select Image to Export, choose an object to save. Now you will be dropped into a submenu analogous to the one used for reading data. It looks like this: +-----------------------------+ | Select Output Format | +-----------------------------+ | COBE IDL Save Sets | | FITS Files | | | | HELP | | Return to previous menu | +-----------------------------+ Note that there is no COBE Sky Maps option since you can't write a COBE archive file. Select the first item, and you will see the prompt: The file will be written to current_default_directory or a directory that you specify in the file specification. Include an appropriate file name extension, e.g. FITS, or CISS. Data set name ? [directory]filename The save set will contain not only the data array (in a variable called DATA) but all of the appropriately named ancillary variables as well (as listed in section 4.3.2). Therefore, when you read this data set back into UIMAGE, it will have all of the necessary information. 4.3.7 Transporting Data into UIDL You may want to work with one or more data objects from the UIDL command line, using the various IDL and UIDL tools. You can easily do so with the following steps. Go to the UIMAGE Main Menu and select Exit UIMAGE. Now, from the CGIS Main Menu (if you return there), choose Go to Command Line (UIDL). This sends you to the UIDL environment and gives you a UIDL> prompt. On the command line, type UIDL> UGETDATA, varname where varname is a variable name of your choice. UGETDATA will present a list of data objects created in your UIMAGE session. If, for example, you have a graph titled Spectrum Plot, a 2-D object called FIRAS_LLSS--SIGNAL(5), and a 3-D called FIRAS_IP--SIGNAL(1:141), you would see this menu: +---------------------------+ | Select Object | +---------------------------+ | Spectrum plot | | FIRAS_LLSS--SIGNAL(5) | | FIRAS_IP--SIGNAL(1:141) | +---------------------------+ If you decide to retrieve your graph ( i.e., Spectrum Plot) into UIDL, highlight it using the arrow keys (or mouse) and then select it by pressing (or ). UIDL then displays this message: A 2-D array is being returned which contains the data that was used to make the selected graph. Please index the array by "(*,0)" to access the X data, and index it by "(*,1)" to access the Y data. Your graph has been successfully pulled into UIDL. Type HELP, varname at the UIDL prompt to display the dimensions of the object. If you would like to read in the 2-D object FIRAS_LLSS -- SIGNAL(5), select the 2-D object in the menu, and you're done! By typing HELP, varname, you will get a listing showing your new variable with its proper dimensions. You can repeat the process as many times as you want (with different variables names of your choosing) in order to bring in your other data objects as well (including the reprojected maps). The ancillary variables (BADPIXVAL, etc.) are NOT brought along in this process of reading in 2-D or 3-D objects, so when it comes time to return to UIMAGE, you will have to reenter that information. The routine UGETDATA is also equipped to handle 3-D objects. Simply select the spectral cube from the object menu listing. You will then be prompted with: +--------------------------+ | Select appropriate array | +--------------------------+ | data | | freq/wave | | weights | +--------------------------+ UIMAGE then places the array into the specified variable name. 4.3.8 Writing FITS Files UIMAGE will write any COBE data set to a FITS file. To write a FITS file, first choose +------------------+ +-------------------------+ +----------------------+ | UIMAGE Main Menu |--->| Data I/O and Management |-->| Write a data file... | +------------------+ +-------------------------+ +----------------------+ Now select an object to output from the next menu titled Select Image to Export. From the next menu, +------------------------+ | Select Output Format | +------------------------+ | COBE IDL Save Sets | | FITS Files | | | | Help | | Return to previous menu| +------------------------+ choose FITS Files as the desired output format. The next prompt requires that you type in a name for the FITS file. The file will be saved to your default directory unless you include a different directory name when entering the file name. File names must have a .FITS file name extension for UIMAGE to find them later. Also, do not use either the character sequence _MOD or PIXPERM in its name, as it will be filtered out and not seen in the list of available files when you try to read it back into UIMAGE. The file will be written to current_default_directory or a directory that you specify in the file specification. Include an appropriate file name extension, e.g. FITS, or CISS. Data set name ? [directory_name]file_name.FITS Type in a descriptive file name and press . If the object has a weight associated with it, UIMAGE gives the option of writing the weight array to a file: The object that you have selected has a weighting array associated with it. +-----------------------------------------+ | Would you like to write it out as well? | +-----------------------------------------+ | yes | | no | +-----------------------------------------+ If you choose to write the weight array to a file as well, type in a file name for the weights array at the next prompt. UIMAGE produces the file(s) and then displays a message confirming the selected object(s) and reiterates the file name(s). 4.3.9 Associating a Weight with an Object UIMAGE will associate a weight with a data object so that for any function involving the use of weights, the specified weight array will automatically be used. To link a data object to a weight array, choose the following menu options: +------------------+ +-------------------------+ | UIMAGE Main Menu |---->| Data I/O and Management | +------------------+ +---+---------------------+ | | +---------------------------------+ +----->| Associate weight with an object | +---------------------------------+ Choose the data object from the first list of objects and then choose the weight array from the second list. From this point on, that data object will be connected to that weight array and will be used in all functions that involve weighting. =============================================================================== WARNING! If the weight is a 3-D object, it is deleted from memory after it has been associated with an object! You cannot retrieve this object again, except by reading it in through UIMAGE data I/O. =============================================================================== Weight arrays that are 2-D objects are NOT deleted after an association. To change the associated weight array, simply repeat the above process. UIMAGE writes the new array over the old array to create the new association. To disassociate an object with a weight array, choose the No weight option from the Choose Weight Object menu. 4.3.10 Combining 2-D Objects into a 3-D Object If you have several 2-D objects, you may want to combine them into a single 3-D object for spectral operations. Follow the following menu path: +------------------+ +-------------------------+ | UIMAGE Main Menu |-->| Data I/O and Management |--+ +------------------+ +-------------------------+ | +--------------+ | +-----------------------------------+ +-->| Combine 2D objects into 3D object | +-----------------------------------+ You will then see the following prompt: Enter the number of 2-D objects to merge into a 3-D object.n We'll use an n of 3 for this example. The next prompt to appear is: +------------------------------------------+ | Use weights associated with 2-D objects? | +------------------------------------------+ | Yes | | No | +------------------------------------------+ Choose the default, No, since we haven't read any weights in. The Select 2D object to combine menu appears next. Choose the name of your first item, say Slice #1 from "CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA [1]". The DECterm window will show the following response: X1: Slice #1 from "CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA [1]" The menu reappears so that you may choose another of the remaining n-1 items. The items are echoed on the screen as above. Once you have chosen all of the 2-D objects you want, a screen prompt appears: Enter a title for the 3D image your_title The new 3-D object then appears. 4.3.11 Making Hardcopies UIMAGE offers a variety of hardcopy options, including image content, color, and orientation. Here are a few general characteristics of UIMAGE plots: * The object name appears as a title. The exceptions here are landscape-mode graphs. * Portrait plots of 2-D objects display the ancillary information as well as the title and image. * "Overlays" include everything within the object window, such as labels and color bars, in addition to grid and contour lines. * Colors may in general be somewhat different between what you see on the screen and what comes out on your plot. In particular, overlay colors will be their original values. * Landscape color plots of full skymaps contain an automatically generated colorbar; you are prompted for a bar title. To get a hardcopy of a display in UIMAGE, select these choices from subsequent menus: +-----------------+ +-------------------------+ +------------------------+ |UIMAGE Main Menu |-->| Data I/O and Management |-->|Create a PostScript file| +-----------------+ +-------------------------+ +------------------------+ Now from the object list, choose which object you would like to print. X Window users see this question next: Select one of the two display methods shown below: +----------------------------------+ | idl | +----------------------------------+ | Data alone (no overlays) | | Data + overlays (screen capture) | +----------------------------------+ If you choose Data alone (no overlays), only the data itself will be written to a file. If, however, you choose Data + overlays (screen capture), any overlays that have been created, such as coordinate grids or contour plots, will also be written to the file. This latter option is equivalent to performing a screen capture. All users now encounter these prompts: +-----------------------+ | Color or Black&White? | +-----------------------+ | Color | | Black&White | +-----------------------+ +------------------------+ | Portrait or Landscape? | +------------------------+ | Portrait | | Landscape | +------------------------+ Choose to have your image oriented in a portrait (x-axis of figure parallel to the short side of the paper) or a landscape orientation (x-axis of figure parallel to the long side of the paper). Once all of the options have been entered, you'll see the following message: The PostScript output will be sent to SYS$LOGIN:IDL.PS +--------------------------+ | Output filename | +--------------------------+ | Use default | | Specify a different name | +--------------------------+ The default filename is IDL.PS in your login directory. If you wish to send it to another directory or filename, choose Specify a different name. (For particularly large files, you may want to send it to a scratch disk, for example, scratch$disk, where the disk and directory would be specified as scratch$disk:[scratch.username]. You must have the directory set up beforehand.) If you wish to assign a new file name, you will encounter two prompts: Enter directory name: [dirname] Enter filename: filename After entering those, you will see the message The PostScript output has been sent to [dirname]filename to confirm your inputs. You may immediately send your files to a laser printer by returning to the UIMAGE Main Menu and selecting Exit UIMAGE. From the CGIS Main Menu, choose Shell to Operating System, then type the appropriate print command at the system prompt. 4.4 UIMAGE IMAGING AND ANALYSIS CAPABILITIES In this section, we illustrate some of the options available in UIMAGE. UIMAGE's main menu looks like this: +--------------------------------+ | UIMAGE [MAIN MENU] | +--------------------------------+ | Data I/O and Management... | | | | Display Manipulation... | | Image Enhancement... | | Algebraic Operations... | | Spectrum Operations... | | Line Plots and Statistics... | | Modeling and Fitting... | | | | Journal Enable/Disable ON | | Report Problems or Comments | | | | HELP | | Exit UIMAGE | +--------------------------------+ All of the instructions in this section begin at this menu. 4.4.1 VT240 or TEK emulation Users: Read This! In order to easily differentiate between options available only to X Window users and those available to both X Window and VT240 users (all non-imaging terminal users will hereafter be referred to as VT240 users), we have adopted the following convention. Menu choices available ONLY to X Window workstations are marked with [X] in the section title. This makes it easy to identify what is and is not available to you. Also, some routines involve marking pixels or locations on the images. For X Window users, this can be done in two ways: (1) by mouse clicks on the image, or (2) by entering sets of coordinates from the keyboard. For VT240 users, only the latter method is available. VT240 users must produce pseudo-grey scale plots or contour plots to see their objects. To find out how to make a contour plot, see section 4.4.4.2. To obtain a grey scale plot, choose: +------------------+ | UIMAGE Main Menu | +--------+---------+ | +---------------------------+ +------->| Line Plots and Statistics | +------------+--------------+ | +------------------------------+ +------->| Tek or VT200 grey scale plot | +------------------------------+ A menu with all of your available 2-D objects is displayed. Choose the object you want to view. You'll then get the prompt: Selected image: FIRAS_LLSS -- SIGNAL(12) The valid data min and max are: 1.108678e-4, 1.135178e-4 The current scaling min and max are: 1.108678e-4, 1.135178e-4 +------------------------------------------+ | Do you want to change the scaling range? | +------------------------------------------+ | Yes | | No | +------------------------------------------+ (DIRBE users and others with large images may see an additional message: The image will be temporarily reduced in size by a factor of 2 in order to be displayed.) Choose No from the menu above to use the scaling defaults. If you choose Yes you'll see: Enter new scaling min: new_min_value Enter new scaling max: new_max_value Now a grey scale plot is built. You are then returned to the Tek or VT200 grey scale plot menu, although on some terminals you must press when finished with the image. From the menu you can either make a grey scale plot of another object or return to the Line Plots and Statistics menu. Finally, please note that the cursor has been terminal-disabled on the menu screens. This means that if you are a VT240 user and you switch to another session, the cursor will also be disabled in that session. You will have to reset your terminal to get the cursor back. (Since each terminal is different, consult your terminal setup to determine how to do this.) 4.4.2 General Display Manipulations 4.4.2.1 Removing an Object Before you start working, you should know how to rid your screens of any extraneous objects, images, or graphs. After following this menu chain, +------------------+ +-------------------------+ +------------------+ | UIMAGE Main Menu |---->| Data I/O and Management |--->| Remove an Object | +------------------+ +-------------------------+ +------------------+ select the objects that you want to delete, and they will immediately be removed from the screen and from the list of available objects. 4.4.2.2 Removing ALL Objects UIMAGE also has the capability of wiping out all data objects at once. To do this, choose +------------------+ +-------------------------+ +--------------------+ | UIMAGE Main Menu |-->| Data I/O and Management |--->| Remove ALL objects | +------------------+ +-------------------------+ +--------------------+ Because this is a relatively dramatic operation, another prompt inquires for confirmation before all the data objects are deleted. 4.4.2.3 Displaying/hiding an Object [X] If your work area is getting crowded with objects, it is possible to remove an object from the X Windows display but keep it in UIMAGE's memory. To do this, choose +------------------+ +-------------------------+ +------------------------+ | UIMAGE Main Menu |->| Data I/O and Management |->| Display/hide an object | +------------------+ +-------------------------+ +------------------------+ A list of available objects is presented. From this list, choose which object you would like to hide. After you have picked an object, you'll see the following menu: +----------------------------------------------+ | Do you want data-object displayed or hidden? | +----------------------------------------------+ | Display | | Hide | +----------------------------------------------+ If you choose Hide, the object is removed from the display but is maintained in memory. To re-display the object, follow these directions, choosing Display instead of Hide. Since the object still exists, it may be used as an operand in any UIMAGE function, i.e., it will still be listed in data object lists. 4.4.2.4 Extracting a Face from a Skycube To extract a face from an existing skycube and place it in its own data array, choose these options: +-----------------+ +-------------------------+ +-------------------------+ |UIMAGE Main Menu |->| Data I/O and Management |->| Extract face from skymap| +-----------------+ +-------------------------+ +-------------------------+ Now choose an object from the object list. Note that this operation is valid for both 2-D and 3-D objects. At the following prompt, type in which face you would like to have grabbed from the data object: Which face would you like extracted (0-5) ? (See figures 4.1 and 4.2 if you are unsure of which face to extract.) The single face is placed in its own data object, and the list of objects returns. Corresponding UIDL routine: GRABFACE 4.4.2.5 Refreshing an Image [X] If a 2-D image has been altered, e.g., by overplotting coordinate grids or contour maps, you can redraw it at any time. To do so, follow these steps: +------------------+ +----------------------+ +------------------+ | UIMAGE Main Menu |-----> | Display Manipulation |-----> | Refresh an image | +------------------+ +----------------------+ +------------------+ A list of objects appears. Choose the one you would like to have displayed in its original form, and it will be redrawn without the overlays. This option also returns a 3-D surface plot back from its 3-D mesh appearance to its original form. 4.4.2.6 Stretching the Image Contrast [X] The Stretch contrast option allows you to change the scaling range for an object. To do this, choose +------------------+ +----------------------+ +------------------+ | UIMAGE Main Menu |-----> | Display Manipulation |-----> | Stretch contrast | +------------------+ +----------------------+ +------------------+ Now choose an object, FIRAS_LLSS -- SIGNAL(5), for example. The following will appear: Selected image: FIRAS_LLSS -- Signal(5) The valid data min and max are: 5.962050e-05 6.166555e-05 The current scaling min and max are: 5.96205e-05 6.166555e-05 If these ranges are not the same (e.g., if you have changed them once), you will see the following menu: +----------------------------------------------------------+ | Set the scaling min & max to the full range of the data? | +----------------------------------------------------------+ | Yes | | No | +----------------------------------------------------------+ Choosing Yes brings up the next two prompts: Enter new scaling min: new_min Enter new scaling max: new_max The result of this is to enhance the contrasting colors of your image by scaling the available colors over a smaller range. You may now select another object to rescale, or you may exit the menu. Corresponding UIDL routine: BYTSCL 4.4.2.7 Changing Image Colors [X] There are four ways to change the colors in which objects are displayed. To access any one of them, choose +-----------------+ +----------------------+ +--------------------+ |UIMAGE Main Menu |----> | Display Manipulation |----> | Change color table | +-----------------+ +----------------------+ +--------------------+ NOTE: To change just the background and line colors, use the XPalette option described below. CONVENTIONAL COLOR TABLES To use a conventional color table while still preserving the colors which have been reserved by UIMAGE for graphs, select Standard IDL color table. There are 16 different combinations to choose from; click on one. The colors in all of the images are altered and the color table menu returns. When you have found a color scheme that you like, select Return to previous menu. All future images will be constructed in these colors. ("Red Temperature" is the default.) VT240 users were instructed previously on how to make grey scale images (section 4.4.1) Workstation users who would like to do the same can choose the color table named B-W Linear under the Standard IDL color table option. XPALETTE You can also create your own color table. To do this, choose XPalette from the Change color table menu. This option could be very time consuming because you have the ability to change any of the nearly 250 colors. The XPalette widget is split into three sections. The left section shows the current red, green, and blue color vectors. The right section of the widget displays the color cells. The boxes are numbered beginning with zero in the upper left hand corner and increase left to right and top to bottom (e.g., color value 240 is in the lower left corner). Select a color cell by 1) moving the mouse and clicking on the desired box, 2) moving the top slide bar labeled By Index to the correct index number, or 3) using the Row slide bar (at the right side of the widget's center section) to move the marker vertically and the Column bar (at the bottom of the section) to move the marker horizontally in order to locate a color box. When a color box has been selected, move the three slide bars labeled R, G, and B located in the lower end of the center section. The color in the Current Color box updates as the levels of red, green, and blue are changed, as do the image displays. The center section of the XPalette widget displays the currently selected index (Current Index:) and the current color of that cell (Current Color:). There are also several function buttons which are described in detail via IDL's Help button. Because the instructions in the help are quite detailed, they will not be reiterated here; users should read this help screen for further information on the center section functions. To change the background color of the image itself, choose color value zero, located in the upper left hand color box; its default is black. To change the color of lines in graphs, labels inside displays, and the frame around the image, choose color value 241, near the bottom of the display; its default depends on the color table chosen. Note: Although you may change the grid color on the screen using XPalette, hardcopies may still show the original table's grid color. To exit XPALETTE, click on the Done button located in the center section. LOADCT Another color manipulation option is IDL's LOADCT function. To use this, choose +------------------+ +-----------------------+ +--------------------+ | UIMAGE Main Menu |--->| Display Manipulations |--->| Change color table | +------------------+ +-----------------------+ +--------------------+ Choose XLOADCT from the next menu, and a new widget is brought up. Notice the Help button located underneath the color bar. This Help option is quite informative and contains details on each of the controls in the widget. Users should read this help page for complete information, as only fundamentals will be discussed below. The top of the widget shows the current colors in the form of a color bar. This bar, as well as any current images you have up, will update as you alter the color table. The Options and Transfer Function buttons underneath the color bar offer several different ways to change the color scheme, including reversing the color table, restoring the original color table, or changing the color by setting up a new transfer function. See the Help option for details on these and other options. The three slider bars in the middle of the widget change the contrast of the colors. To change these values, click and hold on the slide bar, move the mouse across the bar to the new value, and release . The colors change as the slide bar moves so the effects can be seen immediately. Choose the Help button on the XLOADCT widget for more detailed information on Stretch Bottom, Stretch Top, and Gamma Correction. Below the three sliders, there is a list of 37 different color tables. Use the side scroll bar to scroll through the list. To choose a new color table, click on the name of the table; the color bar and images are re-displayed in the new colors. Note that when one of these color tables is selected, the colors that UIMAGE has reserved are overwritten. To exit XLOADCT, click on the Done button located below the color bar. ADJCT This option lets the user adjust the color table by changing the color intensity graph. To do this, choose ADJCT from the Change Color table menu. A graph of the current color intensity transformation is shown. There are four options at the extreme bottom of this window: Ramp, Segments, Draw, and Help. IDL supplies a very informative help page that users should read, as only the basics will be discussed here. To use one of these options, click on desired function name; when active, the name is displayed in reverse video and brief instructions for that function are given at the top of the ADJCT window. As a brief overview: * Ramp defines two endpoints and draws a straight line between them. * Segments allows you to adjust any segment of the line. * Draw lets you to draw the graph freehand while holding down . The instructions for each option are listed at the top of the widget when that function is active. Use to exit the option and another to exit. Corresponding UIDL routines: XPALETTE, LOADCT, ADJCT 4.4.2.8 Putting a Label in a Window [X] To place a label anywhere on a displayed graph or map, follow these options: +------------------+ +-----------------------+ +---------------------+ | UIMAGE Main Menu |--->| Display Manipulations |--->| Put label in window | +------------------+ +-----------------------+ +---------------------+ Select the object that you want to label. Once you have picked an object, the Map Label window appears (see Figure 4.5). +----------------------------------------------------------------------------+ | +-----------------------------------------+ | | Enter text then : | | | | +-----------------------------------------+ | | 10 | | +-||----------+ +------+ | | +-||----------+ Text Align | Test | | | Font size (units of 0.1) o Left +------+ | | o Center | OK | | | 10 o Right +------+ | | +-||----------+ |Erase | | | +-||----------+ +------+ | | Font Thickness (units of 0.1) | Done | | | +------+ | | 0 | | ||------------+ | | ||------------+ | | Orientation (degrees) | | | | 255 | | +------------|| | | +------------|| | | Label Color | | | | | +----------------------------------------------------------------------------+ Figure 4.5 Map Label window used to place labels on graphs or maps. First, click on the box next to the words Enter text then : and type in the desired label. Be sure to press a carriage return () when you have finished entering the text! To edit the text inside this box, use the arrow keys to move to the left and right. You can delete text by highlighting it using the mouse and then pressing the key. (Double clicking in the box highlights everything inside. You can be more selective by pressing and holding the mouse button and dragging to highlight portions of the text, then deleting just those.) Remember, whenever you have changed the text in the box, be sure to press another to enter the new text into memory. Once the text has been entered in the text box, click on the Test button. A small window appears displaying the label, horizontal and centered. This shows you how the label will appear on the object display (excluding the orientation setting since the label will always appear horizontal in the test window). Use the four slider bars at the left side of the Map Label window to change the size of the letters (Font size), their thickness (Font Thickness), the label's orientation, and the label's color. Move the bars by pressing and holding on the bar, sliding it to the left or right, and then releasing at the desired number. Set the different options and then click on Test to display the changes in the small test window. The orientation has a range from 0 to 359 degrees. Therefore, if you would like a label to be vertical and facing to the right, you would set the orientation to 90. To have a label vertical and facing left, you would set the orientation to 270. Once the four label options are set, choose one of the options under Text Align. The positions Left, Center, and Right, refer to the position of the label relative to the cursor when you place the label in the display window. Once you have chosen an alignment, click on the OK button, move the cursor to the display window, and click at the desired location. If the label does not land where you expected it to be, click on the Erase button in the Map Label window and try again. Remember that before you can click in the display window, you click must on OK in the Map Label window. Click the Done button to exit this labeling option. Corresponding UIDL routine: WINLABEL 4.4.2.9 Changing a Title When an image or graph is displayed, its default title is the name of the object, e.g., FIRAS_LLSS -- SIGNAL(5). If you want to change the title of a display, select: +------------------+ +----------------------+ +-----------------------+ | UIMAGE Main Menu |--> | Display Manipulation |--> | Change a window title | +------------------+ +----------------------+ +-----------------------+ Now choose the object you would like to rename. You will see Enter new title: Enter the new title. Titles can have blank spaces and may be up to 40 characters in length. (Do not leave the entire title blank, or the object will no longer be accessible.) The title on the display will be changed immediately, and the list of objects will return. Choose Return to previous menu to quit. 4.4.2.10 Resizing ALL Display Windows [X] To change the size of ALL of your images and graphs, +-----------------+ +----------------------+ +--------------------------+ |UIMAGE Main Menu |-->| Display Manipulation |-->|Resize/redraw all windows | +-----------------+ +----------------------+ +--------------------------+ Now you may choose one of the four available magnification factors, where magnification factor 2 is the default (except for resolution 9 full skymap images, where the default magnification factor is 1.) Upon choosing a magnification factor, UIMAGE redraws the displays at the new magnification and redisplays the magnification menu. Exit this menu via Return to previous menu. Note that all future images will be displayed at the chosen magnification factor and not at the default. If a magnified image would be too large for the screen at the requested magnification, UIMAGE will deny the request to display the images at that magnification factor. Images too large for the screen will not be displayed. Choose a smaller magnification factor, or exit the option. 4.4.3 Displays and Manipulations for 3-D Objects 4.4.3.1 Displaying a Frequency Table UIMAGE uses indices, not the actual frequencies or wavelengths, to read in data sets and perform operations on spectral cubes. Therefore, the users must know which frequencies correspond to the different indices. A quick way to view a frequency-index table for a data object is to choose +------------------+ +---------------------+ | UIMAGE Main Menu |--->| Spectrum Operations | +------------------+ +---+-----------------+ | +--------------------------------------+ +--->| Display a frequency/wavelength table | +--------------------------------------+ Select the object of interest from the list of your available 3-D objects and a table of UIMAGE indices and the corresponding frequency or wavelength is displayed in the session window. If you have only one 3-D object in memory, the table is automatically displayed and you are returned to the Spectrum Operations menu. Frequencies are given in GHz and wavelengths are given in microns. A sample FIRAS table looks like Title of 3-D object: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA Index Frequency/Wavelength ------------------------------------ 1 67.9128 2 84.891 3 101.869 4 118.847 5 135.826 The numbers listed in the Index column are used when specifying slices to extract or frequencies over which to integrate. These indices are only labels, with no intrinsic connection to the data. Table 4.1 (section 4.3.2) lists these indices for several FIRAS frequencies and for DIRBE data. 4.4.3.2 Extracting Frequency/Wavelength Slices To get a frequency or wavelength slice of a 3-D object, select +-----------------+ +---------------------+ |UIMAGE Main Menu |-->| Spectrum Operations | +-----------------+ +---+-----------------+ | +--------------------------------------+ +---->| Extract a frequency/wavelength slice | +--------------------------------------+ If more than one 3-D object exists in your data sets, you will need to select one from the list and then you will be prompted for an index number to determine which skycube to extract. If you have only one 3-D object available, you are immediately asked for an index number via the following prompt: Title of 3-D Object: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA Please indicate the index number of the desired slice. (This number should be between 1 and 168.) index: 1 These indices and their corresponding frequencies are listed in Table 4.1, or use the Display Frequency/Wavelength Table option described in the previous section. If, as in the above example, you enter 1, you would extract the 2-D skycube corresponding to the lowest frequency of CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHSS. The selected frequency slice is then displayed. UIMAGE will return you to the Extract a frequency/wavelength slice menu, in case you would like to make another slice. Choosing No brings you back to the Spectrum Operations menu. Note that from now on, any 2-D object lists will include these slices. 4.4.3.3 Displaying the Spectrum of a Single Pixel In the case of 3-D objects, UIMAGE can display the spectrum of a single pixel. To accomplish this, select +-----------------+ +---------------------+ +------------------------------+ |UIMAGE Main Menu |->| Spectrum Operations |->|Extract spectrum from a pixel | +-----------------+ +---------------------+ +------------------------------+ If you have more than one 3-D object, choose which object to use. X Window users will see +-------------------------------+ | Choose a pixel-selection mode | +-------------------------------+ | Mouse | | Keyboard | +-------------------------------+ To use the Mouse option, you must have a 2-D representation of the 3-D object, i.e., a frequency slice or perhaps an integrated map. If you do have such an object, choose Mouse and then pick an object from the list upon which you will mark the pixels. As indicated in the session window, use to identify pixels. After each mouse click, the spectrum of the pixel is displayed, and you have the option of resizing the graph. Then you can write the spectrum to a file if desired. To quit, press on the image. It is also possible to specify pixels by coordinates. Choose Keyboard as the pixel-selection entry mode. (VT240 users default to this entry mode.) Now select a coordinate system, and then enter a coordinate pair separated by a space or a comma. The spectrum is displayed, and you have the option of resizing the graph. The final option is whether or not to output the spectrum to a file. NOTE: There may be some confusion as to why a 2-D object (i.e., a slice) is selected when wanting to do a 3-D operation. Although the pixel is chosen on a 2-D object, UIMAGE is actually returning to the 3-D object to find the data values at that pixel for all the frequencies of the 3-D object. The 2-D image just serves as a way to identify the desired pixel. 4.4.3.4 Integrating over Frequencies/Wavelengths Besides extracting a slice, a 2-D object can be created from a 3-D object in another way, that is, by integrating over frequencies or wavelengths and creating a new integrated 2-D object. To do this, select +------------------+ +---------------------+ | UIMAGE Main Menu |-->| Spectrum Operations | +------------------+ +--+------------------+ | +---------------------------------------+ +--->| Integrate over frequencies/wavelength | +---------------------------------------+ If you have more than one 3-D object, pick a 3-D object from the list. Then input the indices over which to integrate at the following prompts: Title of 3-D Object: CGIS_FITS:FIRAS_ALL_SKY_SPECTRA_RHFA Please enter numbers to indicate the desired range of indices. The start index should be >=1 and the stop index should be <=168 start index: 1 stop index: 168 Typing in a start index of 1 and a stop index of 168 selects the integration to be performed over our entire example 3-D object. X Window users see the integrated 2-D skycube displayed; for all users, the integrated object is added to the list of available 2-D objects. You are then given the option of performing further integrations. 4.4.3.5 Averaging Spectra in an Area [X] To find the average spectrum of an area, you must have a 2-D representation of the 3-D object, i.e., a frequency slice or perhaps an integrated map. If you do, then choose +-----------------+ +---------------------+ +----------------------------+ |UIMAGE Main Menu |-->| Spectrum Operations |-->| Average spectra in an area | +-----------------+ +---------------------+ +----------------------------+ Select the slice and mark off the desired area with clicks on the vertices; closes the polygon and does NOT mark a point. Again, UIMAGE actually returns to the 3-D object to gather the information and then displays an average spectrum of the region. The frequencies used in the plot correspond to the frequencies that would appear in a displayed frequency table (see section 4.4.3.1). Flagged or empty pixels are not included in this calculation. The number of good pixels in the area is printed on the screen or session window. If you're using an X Windows workstation, a Resize graph? menu will appear. Upon choosing No/Exit this menu you will be presented with the option of removing the polygon from the image. You can then write the spectrum to a file if you so desire and may construct another area on the same slice or return to the previous menu. 4.4.4 Displays and Manipulations for 2-D Objects Many UIMAGE operations are restricted to 2-D objects. However, it is faster to read in a spectral cube (3-D object) and then take frequency slices. This also makes the spectral cube available for spectral operations, which can be done only with 3-D objects. 4.4.4.1 Zooming [X] To zoom in on an object, choose +------------------+ +-------------------+ +---------------+ | UIMAGE Main Menu |-----> | Image Enhancement |-----> | Zoom an image | +------------------+ +-------------------+ +---------------+ Select a 2-D object from the list. Upon choosing an object, UIMAGE displays an empty Zoom window of the default size. A message in the session window appears, informing that you need to... Use LEFT button for zoom CENTER, MIDDLE for zoom MENU, RIGHT to quit. To change the size of the zoom window, put the cursor on the image that you selected and click . The following menu appears: +---------------------------+ | Zoom options | +---------------------------+ | Set Zoom Factor | | Resize Zoom Window | | | | HELP | | Return to previous menu | +---------------------------+ Choose Resize Zoom Window. This menu appears: +--------------------+ | Select X size | +--------------------+ | 4 | | 5 | | 6 | | 7 | | 8 | | 9 | | 10 | | 11 | | 12 | | | | HELP | | Exit this menu | +--------------------+ These numbers indicate the factor by which the 58 x 47 pixel boxes are multiplied (58 pixels in the x direction, 47 in the y direction). The default size is 5 pixel boxes by 5 pixel boxes, that is, 280 x 235 screen pixels. (Note: These are screen pixels, not skymap pixels.) Select the x and y window sizes accordingly to define the size window that you want. Then, resize again or quit by choosing Exit this menu. To change the magnification factor of the zoom, click in the image window. You again get the Zoom Options menu shown above. This time choose Set Zoom Factor. You can choose magnification factors from 1-14; the default is 4. Mark the center of the zoom on the image by pressing . A box is drawn around the portion of the full image that appears in the zoom window, and the center pixel number is given in the session window. (See Figure D.4 in Appendix D for an example.) If you move to another center position and click , the previous zoom image is erased, and the current zoom is displayed. In other words, only one zoom window is used in one zooming session; new boxes are not constructed for each zoom -- the old zoom images are just replaced. To keep a zoomed image and get another window, you must exit () and begin the Zoom an image menu again. Be aware that if you zoom again on the same image, you will create two zoomed objects with the same name; you may therefore wish to rename the first before you start the second. To quit the zoom option, press on the original image. This returns you to the Zoom an image menu with the list of 2-D objects. Note that a new object has been created; it does not appear on the list because zoomed images cannot be used to zoom. 4.4.4.2 Making Contour Maps To make a contour map in UIMAGE, choose +------------------+ +---------------------------+ +---------------+ | UIMAGE Main Menu |----->| Line Plots and Statistics |----->| Contour Plots | +------------------+ +---------------------------+ +---------------+ Select a 2-D object from the list. A few questions now need to be answered. For most of them, the default will NOT be chosen in our example so that other choices can be explored. The first is: The minimum and maximum values of the image are : 5.96e-5 6.17e-5 +---------------------------+ | Enter the Contour levels? | +---------------------------+ | Yes | | No | +---------------------------+ If you choose Yes, you will then get the prompt: Enter number of contour levels: 3 We have entered 3 in the line above. Now you'll see: +----------------------------------------------+ | Do you want the levels to be equally spaced? | +----------------------------------------------+ | Yes | | No | +----------------------------------------------+ If you choose No to the question asking if you want the contour levels equally spaced, you will then be prompted for the levels. Enter level 1: 6.00e-5 Enter level 2: 6.08e-5 Enter level 3: 6.10e-5 You may now choose to have the contours plotted in different colors. At this point, VT240 users will see their contour plot. If you are working on an X Windows terminal, UIMAGE allows you to overlay the contours on any non- zoomed object of the same size. The contour is automatically overlaid on the image of the same object unless you choose a different one. If you choose to overlay the contour map over another object, UIMAGE presents you with a list of possible objects (i.e., objects of the same size). Once the contour map is finished and displayed, you will be asked if you desire to create a PostScript file. If you choose Yes, you will be informed The PostScript file will ONLY contain the contours (not the image also). The PostScript output will by default be sent to SYS$LOGIN:IDL.PS +--------------------------+ | Output filename: | +--------------------------+ | Use default | | Specify a different name | +--------------------------+ If you choose to call your file another name, you will be prompted: Enter directory name: [dirname] Enter filename: filename The PS output of the contour plot was sent to [dirname]filename. Note: Only the contours and not the image itself are written to the file; to obtain a printed output of the contours and the image, see sections 4.3.11 and 5.6.8. X Window users who did not create a PostScript file now have to choose whether or not to remove the contours from the image. Corresponding UIDL routine: CONTOUR 4.4.4.3 Making 3-D Surface Plots of 2-D objects [X] For a 3-D surface plot of a 2-D object, choose +------------------+ +-------------------+ +------------------+ | UIMAGE Main Menu |----->| Image Enhancement |----->| 3-D surface plot | +------------------+ +-------------------+ +------------------+ Select an object. UIMAGE replaces the existing 2-D image of the object with a 3-D surface plot. (See Figure D.2 for an example.) Note that a new object has not been created; this is only a different way to display an existing one. To get the image back to its original appearance, choose Display Manipulation from the UIMAGE Main Menu and then choose Refresh an image. This will return the object to its original appearance, but without any of the labels or overlays it may have had. Corresponding IDL routine: SHOW3 4.4.4.4 Changing the Skycube to Another Projection UIMAGE has the ability to produce three types of reprojections of the COBE skymap: Aitoff, Global Sinusoidal, and Mollweide. Aitoff projections are equal area projections with curved parallels. Global Sinusoidal projections are equal area and have straight parallels. Mollweide projections are equal area and also have straight parallels. (See Figures D.2 and D.5 in Appendix D for examples of Aitoff and Mollweide reprojections.) To make one, follow this chain: +------------------+ +-------------------+ +--------------+ | UIMAGE Main Menu |------>| Image Enhancement |------>| Reprojection | +------------------+ +-------------------+ +--------------+ Now choose from the unzoomed 2-D objects in the memory. The procedure for the three reprojections is similar, so we give only one example here. The menu you see now should look like the following: +----------------------------+ | New projection | +----------------------------+ | Aitoff | | Global Sinusoidal | | Mollweide | | HELP | | Return to previous menu | +----------------------------+ Choose a projection. The next menu requires that you choose a coordinate system; do this. Next choose the size of the reprojection: +-----------------------+ | Enter Projection Size | +-----------------------+ | Small (512 x 256) | | Large (1024 x 512) | +-----------------------+ For DIRBE and other resolution 9 images, we recommend using the larger projection size. If your object is a single face with no face number given in the ancillary data, you may be prompted for it: Enter Face Number: (See figures 4.1 and 4.2 for unfolded skycube and sixpack layouts, respectively.) You will now see a message like one of the following: Restoring AIT_GAL Lookup Table Restoring GS_GAL Lookup Table Restoring MWD_GAL Lookup Table after choosing an Aitoff, Global Sinusoidal, or Mollweide projection, respectively, using the Galactic coordinate system. (This message appears only if it is the first time that you have chosen a particular projection-coordinate combination.) Following this you will see: Building Projection on your screen, so you are assured that your input was received. The reprojection will appear if you are working on an X Windows terminal. For those users working on a VT240 terminal, the reprojection is placed in the UIMAGE object list, but it is not immediately displayed (see section 4.4.1 to get a grey scale display of the reprojection). Corresponding UIDL routine: REPROJ 4.4.4.5 Overlaying a Coordinate Grid [X] To overlay a coordinate grid on any 2-D image, choose +------------------+ +-------------------+ +----------------------+ | UIMAGE Main Menu |----->| Image Enhancement |----->| Plot coordinate grid | +------------------+ +-------------------+ +----------------------+ Now select an object for a grid, then select a coordinate system. The default parallels are drawn at 0, +/-30, and +/-60 degrees; the default meridians are drawn at 0, +/-60, +/-120, and +/-180 degrees. You may instead enter any number of parallels and meridians where you like, by either entering the specific values or giving the incremental difference for a set of evenly spaced lines. Enter only the positive value for the parallel or meridian; its negative is automatically included. After the lines have been selected, they are plotted on top of the chosen image. (See section 4.4.2.7 to change the color of the grid.) Note that if you choose to overlay a different coordinate grid, the previous grid is not erased. See section 4.4.2.5 to find out how to refresh an image. Corresponding UIDL routine: PROJGRID, DRAW_PM 4.4.4.6 Creating a Cross Section To obtain a spatial cross section, i.e., a section of a great circle, of a 2-D object, choose +-----------------+ +-------------------------+ +------------------------+ | UIMAGE Main Menu|->|Line Plots and Statistics|->|Cross sections, Sky cuts| +-----------------+ +-------------------------+ +------------------------+ Select a 2-D object (excluding zoomed objects) for a cross section. The cross section may be marked one of two ways. The Cursor entry mode allows you to use the mouse to click on two points on the object. The Longitude/latitude entry mode prompts you to enter two sets of coordinates from the keyboard. (VT240 users only have the latter entry mode available.) If you select the Cursor entry mode, you will be instructed to mark the two points by following message: Mark first point with cursor Mark second point with cursor If you select Longitude/latitude entry mode, choose a coordinate system from this menu: +--------------------+ | Coordinate System | +--------------------+ | Ecliptic | | Galactic | | Equatorial | +--------------------+ Then, enter the coordinates at this prompt: Enter longitude & latitude of first point (Ex. 30, 25): long, lat Enter longitude & latitude of second point: long, lat Separate the values of the longitude and latitude by a space or comma. After the points have been specified, X Window users will see the shorter arc connecting the points drawn on the object. UIMAGE then displays a plot of intensity vs. position for the cross section. X Window users may resize the graph or exit leaving the graph at the default size. There are now four choices available to you, as shown by the current menu: +--------------------------------------+ | Next action for C.S. plot | +--------------------------------------+ | Specify new cross-section | | View "complementary" cross-section | | Change entry mode | | | | HELP | | Return to previous menu | +--------------------------------------+ You may choose a new cross section of the same object by choosing Specify new cross section and following the same steps as above using two new points to define the cross section. The option View "complementary" cross-section uses the same two points previously specified for the initial cross section but this time uses the longer arc of the great circle connecting the two. (See Figure D.3 for an example.) You will see this longer arc drawn on the object and its intensity plot displayed. This graph will be the same size as the first one. You are not given the option to resize here, although you may later do so as described in section 4.4.5.3. NOTE: This option does not work on single faces. The third selection, Change entry mode, allows you to switch the manner in which you enter coordinates of an object from cursor entry to keyboard entry or vice versa. After choosing your new mode of coordinate entry, the process of marking the points, drawing the arc, and displaying the graph repeats itself. This option is not applicable to VT240 users who have only the keyboard entry mode available. If at any time you would like to perform these operations on a different object, choose Return to previous menu and select another object. 4.4.4.7 Obtaining Single Pixel Information Information about a single pixel of a 2-D object may be obtained via this chain of menus: +-----------------+ +---------------------------+ +------------------------+ |UIMAGE Main Menu |->| Line Plots and Statistics |->|Single Pixel Information| +-----------------+ +---------------------------+ +------------------------+ You will then be asked to choose an entry input format, either Mouse or Keyboard, and then to select one of the available 2-D objects. Mouse entry: Next select a coordinate system from this menu: +---------------------------------+ | Select output coordinate system | +---------------------------------+ | Ecliptic | | Equatorial | | Galactic | | | | HELP | | Return to previous menu | +---------------------------------+ (Your choice of coordinate system has no influence on anything except the output values of the latitude and longitude.) You are now ready to select your pixels using the mouse. The session window offers these instructions: ECLIPTIC coordinates have been selected. Select points on the image labeled: Name_of_object_you_chose Hit LEFT mouse button to select points, RIGHT mouse button to exit. After clicking on a point on the object, the point will be marked with a dot on its image and then its corresponding information (pixel number, latitude, longitude, and data value) will be displayed on the screen. You may choose as many points as you like with individual clicks or by holding down and dragging the pointer around the image to select a trail of points. When you are finished, strike to exit the Single Pixel Information procedure. Choose whether to remove or keep the pixel markings on the image. Keyboard entry: After choosing an object, you will be prompted for an input format from the menu below: +-------------------------+ | Select input format | +-------------------------+ | Pixel | | Decimal hr/dec | | Lon-lat | | | | Return to previous menu | +-------------------------+ If you choose Pixel, you will be prompted for the pixel number. If you choose Decimal hr/dec or Lon-lat, you must first select an input coordinate system (Ecliptic, Equatorial, or Galactic), and then enter the coordinates. Now select an output format (Pixel, etc.) and an output coordinate system (if appropriate) from the menus. The program will then display the pixel number, data value, and coordinates (if requested) on the screen before returning you to the Line Plots and Statistics menu. 4.4.4.8 Calculating Statistics and Plotting Histograms To find the statistics or plot a histogram of a 2-D object, do this: +-----------------+ +---------------------------+ +----------------------+ |UIMAGE Main Menu |-->| Line Plots and Statistics |-->|Statistics & Histogram| +-----------------+ +---------------------------+ +----------------------+ Choose an object. You can either find the statistics of the whole object or of a selected region. X Window users who choose A section draw a polygon with clicks on the vertices of the region; clicking closes the area and does NOT mark a vertex. If you are working on a VT240 terminal and choose A Section, first specify a coordinate system and then enter the coordinates of the vertices from the keyboard. The prompt looks like this: You will be prompted for points that define the vertices of an area. You need to define at least 3 points. Enter the Longitude & Latitude in degrees followed by a . After entering all the points, hit a . Please identify the coordinate system you will use. +--------------------+ | Coordinate system: | +--------------------+ | Ecliptic | | Equatorial | | Galactic | +--------------------+ Now enter the lon/lat pair in degrees (example: 20. -30.). [ to exit] lon lat: After the region has been specified, UIMAGE presents you with the minimum and maximum values in the region, the mean and median, the standard deviation, and the number of pixels in your selected area. Bad pixels are excluded in these calculations. Now you can plot a histogram of your area by answering Yes to +----------------------------------+ | Do you want to make a Histogram? | +----------------------------------+ | Yes | | No | +----------------------------------+ If you choose to create a histogram, the next question is +-------------------------------------------------+ | Define a special MIN and MAX for the Histogram? | +-------------------------------------------------+ | Yes | | No | +-------------------------------------------------+ Answer Yes to enter a minimum and maximum for the histogram or answer No to use those given by its previous statistics calculation. Next, enter the number of bins for the plot and then choose either a linear or logarithmic scale. (The logarithmic scale option actually produces a semi-log plot where the logarithm of the y axis values only are taken.) Once the histogram has been displayed, X Window users have the option of resizing it and then erasing any region boundary lines that have been drawn on the object. VT240 users press when finished with the graph to restore the Statistics & Histogram menu. Corresponding UIDL routines: HISTOGRAM, MIN, MAX, MEDIAN, STDEV 4.4.4.9 Getting Pixel Information from Graphs To obtain data information straight from a graph, choose the following options: +----------------+ +-------------------------+ +----------------------------+ |UIMAGE Main Menu|>|Line Plots and Statistics|->|Pixel information for graphs| +----------------+ +-------------------------+ +----------------------------+ Choose a graph from the list of those available. You'll see the message: Click left mouse button (mb1) on desired point or rightmost (mb3) to exit As directed, press at a point of interest on the graph. Note that the cursor need NOT be positioned exactly on the graph line. UIMAGE reports the X value, the Y value, and the IDL array index of that point. Use to choose as many points as you need and then use to quit. ( does NOT mark a point.) 4.4.4.10 Making Scatter Plots To produce a scatter plot of the intensities of two 2-D objects, +-----------------+ +---------------------------+ +----------------------+ |UIMAGE Main Menu |-->| Line Plots and Statistics |-->| Scatter plot (2 maps)| +-----------------+ +---------------------------+ +----------------------+ Choose two objects from the object lists presented to you. The second list includes only those objects that are the same size as the first. UIMAGE makes and displays the scatter plot, and then X Window users have the option of resizing the plot. 4.4.4.11 Changing Image Resolution The resolution of 2-D objects may either be increased or decreased using UIMAGE. The range of possible resolutions is 6 to 9, where the dimensions of sky-looking unfolded cubes are as follows: Resolution 6 : 128 x 96 Resolution 7 : 256 x 192 Resolution 8 : 512 x 384 Resolution 9 : 1024 x 768 In the example below, the resolution of the 2 x 2 image on the left is increased by 1, resulting in the 4 x 4 image on the right: 1 1 2 2 1 2 converts 1 1 2 2 3 4 to 3 3 4 4 3 3 4 4 When decreasing resolution by one, the average of 4 data values is taken as the value for the single representative data element. UIMAGE does not include bad pixels in the resolution reduction calculations. This insures that the new, reduced arrays are not contaminated by flagged pixel data values. To change the resolution of an object, select +------------------+ +-------------------+ +-------------------------+ | UIMAGE Main Menu |---->| Image Enhancement |---->| Change array resolution | +------------------+ +-------------------+ +-------------------------+ Now pick the object whose resolution you desire to change, and then select the new resolution (note that the object's current resolution is not listed). X Window users see the new object displayed. You are now presented with the option of changing the resolution of another object. Corresponding UIDL routines: CONGRID, DOWNRES 4.4.4.12 Smoothing an Image To smooth an image, first do the following: +------------------+ +-------------------+ +-----------------+ | UIMAGE Main Menu | ----> | Image Enhancement | ----> | Smooth an image | +------------------+ +-------------------+ +-----------------+ Pick the object that you want to smooth from the list of all the 2-D objects available, say, FIRAS_ALL_SKY_SPECTRA_RHFA. In your session window, you'll see Selected image: FIRAS_ALL_SKY_SPECTRA_RHFA +-------------------------------+ | How should kernel be defined? | +-------------------------------+ | Keyboard entry | | Read from a file | +-------------------------------+ If you choose to read the kernel from a file, the file must be an IDL saveset and it must contain the variable KERNEL. If these criteria are met, select Read from a file and enter the filename at the following prompt: Enter file name of an IDL saveset containing a 2-D floating point array named KERNEL, or else enter "E" to exit. (Note - program blowup will occur if the indicated file is not an IDL saveset.) File name: saveset_filename If you choose Keyboard entry, first select the dimensions of the kernel. +--------------------------------------+ | Select dimension for a square kernel | +--------------------------------------+ | 3 | | 5 | | 7 | +--------------------------------------+ UIMAGE then shows the arrangement of the kernel elements. For example, if you chose a 5 x 5 kernel, the matrix would look like the following: F E D E F E C B C E D B A B D E C B C E F E D E F Enter values for A,B,C,D,E,F below. A: NOTE: The kernels are assumed to be symmetric, hence the arrangement. Non- symmetric kernels may be used by calling the kernel from an IDL saveset. Kernels that are not square may also be used, but you are should be warned that the results could be faulty. Enter the values of the kernel elements, pressing after each entry. When you have finished, UIMAGE redisplays the kernel with its numerical elements (as above except with numbers). If you have entered something incorrectly from the keyboard, you can go back and change it via the next question. +---------------------------------------+ | Do you want to re-enter those values? | +---------------------------------------+ | Yes | | No | +---------------------------------------+ Upon choosing No, X Window users see the smoothed image. The smoothed object is then listed in the Smooth an image menu that has returned to the screen. If you decide to smooth any other objects during this UIMAGE session, UIMAGE remembers your kernel and asks you if you want to use the same one again. If you choose not to, follow the same procedure described above. When you smooth a reprojection, UIMAGE smooths and displays the smoothed skycube first and builds the new smoothed reprojection from that image. X Window users will see the new reprojection immediately. Corresponding UIDL routine: SMOOTH_CUBE 4.4.4.13 Displaying Images Using Histogram Equalization Histogram equalizations are useful in increasing the color contrasts of an image, especially those images dominated by one color or shade. The output images are scaled from 0 to 255, and a new UIMAGE object is created. NOTE: The resulting intensities are no longer simply related to each other and should be used for display purposes only. In order to perform a histogram equalization on an object, choose +-----------------+ +-------------------+ +------------------------+ |UIMAGE Main Menu |----> | Image Enhancement |----> | Histogram equalization | +-----------------+ +-------------------+ +------------------------+ Pick a 2-D object for histogram equalization. UIMAGE does the equalization, and X Window users see the display of the equalized object. The new object is added to the object list. Corresponding UIDL routine: HISEQMAP 4.4.4.14 Displaying Images Using Edge Enhancement Edge enhancements are often used to uncover small variations in data that are difficult to detect. You should note that when UIMAGE performs an edge enhancement, bad pixels and any parts which have been contaminated by a neighboring bad pixel are designated as bad pixels in the output image. Edge enhanced objects are new objects that will appear on the object lists. To do an edge enhancement on a 2-D object, choose +------------------+ +-------------------+ +------------------+ | UIMAGE Main Menu |-----> | Image Enhancement |-----> | Edge Enhancement | +------------------+ +-------------------+ +------------------+ Now pick your 2-D object. From the next menu, +--------------------------+ | Edge En. type | +--------------------------+ | ROBERTS | | SOBEL | | | | HELP | | Return to previous menu | +--------------------------+ choose a high pass filter. The Roberts filter uses an approximation to the Roberts edge enhancement operator and the Sobel filter uses an approximation of a 3 x 3 non-linear edge enhancement operator. (See the entries for ROBERTS and SOBEL in IDL Reference Guide for further explanation.) After you have picked a filter, UIMAGE performs the operation and, if you are on a workstation, displays the edge enhanced image. Corresponding UIDL routine: ENHANMAP 4.4.4.15 Marking Positions on a Map [X] This option provides three ways to put labels on a displayed map. You may use the mouse to point and click on a point and then type in a label, or you can enter coordinates and labels from the keyboard. Alternatively, this routine can read a file of coordinates and labels and place the labels on the map. The menu path is the following: +-----------------+ +-----------------------+ +-------------------------+ |UIMAGE Main Menu |-->| Display Manipulations |-->| Mark positions on a map | +-----------------+ +-----------------------+ +-------------------------+ Choose an object. Now select an entry mode from the menu in the session window: File (to read labels and coordinate from a file), Keyboard (to enter labels and coordinates from the keyboard), or Cursor (to type in a label and then point and click with the mouse). Regardless of which entry mode you choose, the next menu allows you to change the color of the labels (the default is 255), the IDL plot symbol used, the size and thickness of the letters, and the position of the label relative to the plotting symbol. These settings are not saved from one run to the next. When you have set all of the plot characteristics, choose DONE. If you are working with a single face, you will be prompted for the face number here. FILE entry mode: If you choose File as the entry mode, answer the following prompt: Enter filename (enter for keyboard entry): diskname:[directory_name]filename The file must be in one of these two forms: (1) seven columns for coordinates in Equatorial (RA/Dec) Sexigesimal coordinate format, i.e., HR MIN SEC DEG DEC_MIN DEC_SEC LABEL, or (2) three columns for coordinates in longitude latitude format, i.e., LONG LAT LABEL. Longitudes and latitudes may be specified in ecliptic, Galactic, or equatorial coordinates. Labels cannot have spaces in them if they are read in from a file (although labels entered from the keyboard may contain spaces). Acceptable values for label coordinates are latitudes between (-90, +90), decimal longitudes between (-360, +360), and RA hours between (0, 24). If the program finds coordinates that do not match one of these criteria, that point will not be plotted; the others, however, will still be displayed. You are prompted for the type of file coordinates: +-------------------------------+ | File Coordinates | +-------------------------------+ | Ecliptic | | Galactic | | Equatorial-Sexigesimal Format | | Equatorial-Decimal Format | +-------------------------------+ KEYBOARD entry mode: If you choose Keyboard as the entry mode, press a carriage return at the filename prompt (shown above). Type in the number of entries at the next prompt followed by . Now enter the coordinate system of the coordinates that you will input for the label positions (E for Ecliptic, G for Galactic, and Q for eQuatorial). For each point, enter the longitude and latitude of the point separated by a space or a comma at the prompt Lon,Lat of Point n: followed by a . Enter the text that you would like placed at that point at the prompt Label for Point n:. When you have entered the previously specified number of labels and coordinate pairs, you will be returned to the Markmap menu. CURSOR entry mode: If you choose Cursor as the entry mode, you will first be asked to type in a label (the label may contain spaces) and then choose the position with the mouse. Type in the label at the Enter label: prompt and then find the desired location on the map and click there. Click with at the last position. Corresponding UIDL Routine: MARKMAP 4.4.4.16 Adding a Colorbar to an Image [X] To add a color bar to a display, choose +------------------+ +-----------------------+ +------------------------+ | UIMAGE Main Menu |-->| Display Manipulations |-->| Add colorbar to window | +------------------+ +-----------------------+ +------------------------+ Select an object and then answer the following questions. +------------------------------------------------+ | Do you want the default bar (else custom bar)? | +------------------------------------------------+ | Yes | | No | +------------------------------------------------+ If you answer Yes and wish to use the default color bar, you are now given the option of adding a label to the bar. The standard color bar is placed on the image, centered on the bottom edge of the image window and stretching nearly the full length of the window. If you answer No and wish to create your own customized color bar, you'll encounter these options: +----------------------------------------+ | Do you want to add text to the window? | +----------------------------------------+ | Yes | | No | +----------------------------------------+ If you answer Yes to this question, you will later be dropped into the Map Label routine (see section 4.4.2.8). +---------------------------------------+ | Do you want to reverse the color bar? | +---------------------------------------+ | Yes | | No | +---------------------------------------+ +---------------------------------------+ | Do you want to use default color MIN? | +---------------------------------------+ | Yes | | No | +---------------------------------------+ +---------------------------------------+ | Do you want to use default color MAX? | +---------------------------------------+ | Yes | | No | +---------------------------------------+ If you answer No to either of the last two questions, you will be prompted for the minimum and/or maximum values to use in place of the defaults. Now use the mouse to mark the boundaries of the color bar. As directed in the session DECterm window, first click where the center of the color bar should be. Now press at the left end of the bar. (The distance between the center position and the left end will represent half of the bar length.) Finally, mark where the top of the bar should be with . (The distance between the center mark and the top mark will represent half of the bar width.) Once these three points have been marked, the color bar is drawn. The widget for Map Label appears next if you have asked to add text to the window. Corresponding UIDL routine: COLORBAR 4.4.5 Graph Display Manipulations 4.4.5.1 Changing Axis Ranges You can select new ranges for the axes by choosing +-----------------+ +----------------------+ +----------------------------+ |UIMAGE Main Menu |->| Display Manipulation |->| Change X and Y axis ranges | +-----------------+ +----------------------+ +----------------------------+ UIMAGE now lists the graphs from which you can choose. After you have selected a graph, confirmation of the chosen graph and the current X and Y ranges are shown in the following format: Selected graph: name_of_graph The X data ranges from 0.00 to 400.0 +-----------------------------------------+ | Do you wish to set the X display range? | +-----------------------------------------+ | Yes | | No | +-----------------------------------------+ If you choose Yes, you will then be prompted for the minimum and maximum X data values. The process will be repeated for the Y range. The graph is then replotted with the new axis ranges. 4.4.5.2 Changing Axis Titles To change axis labels, choose +-----------------+ +----------------------+ +-------------------------+ |UIMAGE Main Menu |--->| Display Manipulation |--->| Change graph axis labels| +-----------------+ +----------------------+ +-------------------------+ From the list you see now, pick the graph that you want to change. On your screen, you will see: Selected graph: Name_of_graph X-axis label: Current_label +-----------------------------------------+ | Do you wish to change the X-axis label? | +-----------------------------------------+ | Yes | | No | +-----------------------------------------+ If you choose Yes you will be shown the current title and given an Enter X-axis label: prompt; enter your new label. The same procedure is repeated for a Y-axis title change. The graph is then replotted. 4.4.5.3 Resizing a Graph [X] To change the size of a graph (e.g., a spectrum or intensity plot), choose +------------------+ +----------------------+ +----------------+ | UIMAGE Main Menu |-----> | Display Manipulation |-----> | Resize a graph | +------------------+ +----------------------+ +----------------+ Now choose which graph you would like to be resized. Once chosen, UIMAGE prints the title of your choice on the screen. The choices for dimensions of the graph axes presented in the next menu are 6, 8, 10, 12, and 14. These numbers indicate the factor by which the 58 x 47 UIMAGE pixel boxes are multiplied (58 pixels in the X direction, 47 in the Y direction). Your first dimension selection corresponds to the X-axis (menu title: Select X size); now choose the Y-axis dimension (menu title: Select Y size). The resized graph will be displayed, and you have the option of resizing the graph again. The default size for a graph depends upon the magnification factor as well as the resizing parameters, so no hard and fast rule for choosing appropriate sizes can be given here. 4.4.5.4 Changing Plot Colors [X] When overlaying graphs, it is helpful to first change the color of the graphs so it is easy to differentiate the lines. To do this, choose +------------------+ +-----------------------+ +-----------------------+ | UIMAGE Main Menu |--->| Display Manipulations |--->| Change a graph's color| +------------------+ +-----------------------+ +-----------------------+ A list of the existing graphs is presented; pick one. Now UIMAGE displays the Select a color value menu, which shows the nine available colors. The colors are 1 grey 2 red 3 green 4 blue 5 fuchsia 6 yellow 7 burgundy 8 tan 9 white Select one of the colors for the graph and the graph will be redrawn. The list of available graphs is returned so that you may either change the color of another graph or return to the Display Manipulations menu. 4.4.5.5 Overlaying Graphs UIMAGE has the ability to overlay up to ten graphs. When using this option, it is often beneficial to have the graphs plotted in different colors before overlaying them (see section 4.4.5.4). (Different plot line styles are also available.) To overlay two or more graphs, choose +------------------+ +-----------------------+ +----------------+ | UIMAGE Main Menu |---->| Display Manipulations |---->| Overlay graphs | +------------------+ +-----------------------+ +----------------+ A list of available graphs is presented in the Overlay graphs menu. As you choose selections from the menu, the list of object titles is updated in the session window: List of graphs to be overlaid: ------------------------------ Object 1 Object 2 Users may select up to ten graphs to overlay. When you have finished selecting graphs, choose Finished selecting - overlay the graphs. If you are overlaying graphs with different axis label(s), you will be prompted for the label(s) of the composite graph. The selected graphs have different X-axis labels. Please enter below the X-axis label for the composite graph. If the labels are the same on all of the individual graphs, the same axis title will automatically appear on the resulting plot. Note: When overlaying graphs created by the Statistics & Histogram option, UIMAGE matches up bin numbers, not the physical units given at the top of the histogram. You may select different line styles for the different graphs. If, for example, you are overplotting three graphs, you will see this prompt three times: Enter below the plotting linestyle (0-5) for graph # : (# is the graph number, beginning with 0.) Enter one of the following IDL linestyles for each line: 0 Solid 1 Dotted 2 Dashed 3 Dash Dot 4 Dash Dot Dot Dot 5 Long Dashes After the composite graph is displayed, users have the option of resizing the graph (see section 4.4.5.3). To exit the overlay graph mode at any time, choose Abort - return to previous menu. 4.4.5.6 Changing a Graph's Scaling For any existing graph, UIMAGE can change the scaling of either or both axes from linear to log or vice versa. To do this, choose +-----------------+ +---------------------+ +-----------------------------+ |UIMAGE Main Menu |->|Display Manipulations|->| Change Log Scaling of Graph | +-----------------+ +---------------------+ +-----------------------------+ From the next menu, choose which graph to alter. The options in the next menu refer to the scaling of the X and Y axes, respectively. +--------------------------+ | Choose Type of Scaling | +--------------------------+ | Linear-Linear | | Linear-Log | | Log-Linear | | Log-Log | +--------------------------+ For example, to maintain a linear scale on the X axis but change the Y axis to a log scale, the correct menu choice would be Linear-Log. After you have selected the scaling, the new graph is displayed, and you are returned to the list of available graphs. 4.4.6 Algebraic Operations UIMAGE has the ability to do algebraic operations on one 2-D object or line plot (hereafter called unary operations), on two objects or plots (binary operations), and on multiple objects or plots (n-ary operations). These capabilities are located under: +------------------+ +----------------------+ | UIMAGE Main Menu |------>| Algebraic Operations | +------------------+ +----------------------+ The Algebraic Operations menu looks like this: +--------------------------------------------------+ | ALGEBRAIC OPERATIONS | +--------------------------------------------------+ | X1 + X2 | | X1 - X2 | | X1 * X2 | | X1 / X2 | | | | (X1*wt1+X2*wt2)/(wt1+wt2) | | (X1*wt1-X2*wt2)/(wt1+wt2) | | | | SQRT(X) | | LOG10(X) | | ABS(X) | | 1./X | | | | C0 + C1*X1 + C2*X2 +...+ Cn*Xn | | Average (X1, X2, X3,..., Xn) | | Weighted Avg((X1*wt1,..., Xn*Wtn)/Sum(wt1-n)) | | | | HELP | | Return to MAIN MENU | +--------------------------------------------------+ The operations are described in detail below. 4.4.6.1 Using Binary Operations UIMAGE's algebraic operations on two graphs or two 2-D data objects include: addition subtraction multiplication division weighted average normalized difference These operations may be performed on any two graphs or 2-D objects whose array sizes are the same. Flagged pixels are not included in the operations, and they remain flagged in the new object. In the case of graphs, if the X-axis ranges of the two initial objects differ, the operations are performed only over the range common to both objects. From the Algebraic Operations menu choose an operation, e.g., addition. This will appear on the screen: Selected operation: X1 + X2 Now choose your two objects. After you have chosen your first object, the choices for the second object are appropriately narrowed by UIMAGE to include only those objects which are of the same dimension (i.e., graph or 2-D) and size. UIMAGE displays your selections in this format: X1: name_of_object_1 X2: name_of_object_2 The new object is constructed and X Window users see it displayed on the screen. (In the case of displaying the result of a multiplication or a division, the contrast range is narrowed to two sigma instead of being stretched over the entire range to avoid a darkened image caused by the many near-zero divides.) The following message indicates that the calculation is complete. result: Title_of_result Corresponding UIDL routines: MULTIPLY, DIVIDE, WEIGHTEDSUM 4.4.6.2 Using Unary Operations UIMAGE's operations on single data objects include: square root logarithm (base 10) absolute value reciprocal These operations may be performed on any graphs or 2-D data objects. Bad pixels in the chosen object remain flagged in the new objects. In the cases of SQRT(X) and LOG10(X), pixels in the original object with negative values are considered to be bad pixels in the new object. After you have chosen which unary operation you want from the Algebraic Operations menu, you will see your choice reiterated on the screen. For example, if you choose the absolute value operation, UIMAGE displays Selected operation: ABS(X) Choose an object from the object list now facing you, for instance FIRAS_LLSS - - SIGNAL(5). You will see X: FIRAS_LLSS -- SIGNAL(5) After the new object has been displayed, result: ABS("FIRAS_LLSS -- SIGNAL(5)") appears and the Algebraic Operations menu reappears. In the case of operating on a reprojection, UIMAGE first creates a new skycube and produces the new reprojection from the new skycube. Corresponding UIDL routines: ABSVALUE, LOGBASE10, SQUAREROOT 4.4.6.3 Using N-ary Operations UIMAGE's n-ary operations consist of finding weighted sums, averages, and weighted averages. Bad pixels remain flagged in the generated objects. To find a weighted sum, choose C0 + C1*X1 + C2*X2 +...+ Cn*Xn from the Algebraic Operations menu. First, you'll see Selected operation: C0 + C1*X1 + C2*X2 +...+ Cn*Xn +--------------------------+ | Select number of objects | +--------------------------+ | 1 | | 2 | | 3 | | 4 | | 5 | | 6 | | 7 | | 8 | | 9 | | 10 | +--------------------------+ Choose how many objects you want to include in the sum. Suppose you choose to average 3 objects. The values for the coefficients are entered in from the keyboard, and the objects are selected from the object list menus, alternating between the two. (As with the binary operations, the first object that you choose will narrow down the following object lists to include only those with compatible object type and size.) This is illustrated below. Please enter values for coefficients when prompted for below. C0: (keyboard entry) X1: (chosen from object list) C1: (keyboard entry) X2: (chosen from object list) C2: (keyboard entry) X3: (chosen from object list) C3: (keyboard entry) When this is complete and UIMAGE has displayed the result, the title of the result is shown in your window. To find a straight average, choose Average (X1, X2, X3,...,Xn). You will be prompted as you would for the weighted sum described above except there will be no prompts for coefficient input. To use the weighted average option, all of the objects in the calculation must have a weight associated with them. UIMAGE does NOT prompt you for object and weight arrays separately. (See section 4.3.9 on associating a weight with an object.) To perform this operation, simply choose Weighted Avg((X1*wt1,...,Xn*Wtn)/Sum(wt1-n)), select the number of objects you will be using, and then pick them off of the object lists. (Again, UIMAGE will not allow you to select an object that has no weight association.) The new image is displayed. Corresponding UIDL routine: WEIGHTEDSUM 4.4.7 Modeling and Fitting The UIMAGE fitting routines allow you to: * subtract a dipole * subtract a dipole plus quadrupole * fit spectra with a 3 blackbody model * fit spectra with a Bose-Einstein plus blackbody model * model a 2-D background * fit a polynomial to a graph * fit a Gaussian to a graph These capabilities are discussed below. 4.4.7.1 Subtracting a Dipole UIMAGE has the ability to subtract a dipole from a 2-D skymap. (See Figure D.5 in Appendix D to see the effect of dipole subtraction.) To do this, choose +------------------+ +----------------------+ +-------------------+ | UIMAGE Main Menu |----->| Modeling and Fitting |----->| Subtract a Dipole | +------------------+ +----------------------+ +-------------------+ Now pick the object you would like to manipulate, and then enter an angle between (0 and 90 degrees) in response to the following prompt: Enter a galactic exclusion angle below in degrees (default = 20). angle: If a weight array has been associated with the selected data object, the title of the weight array is indicated in the session window, and it will be used in the calculation. Otherwise, the operation does not apply any weights. (See section 4.3.9 for instructions on linking weight arrays to data arrays.) After finishing the operation, UIMAGE gives you the following information: Mean CMBR intensity: Sigma of CMBR inten.: Dipole amplitude: Sigma of Dipole amp.: Galactic lon & lat of dipole pole (degrees): Sigma of Dipole dir.: Corresponding UIDL routine: DIPOLE 4.4.7.2 Subtracting a Dipole + Quadrupole UIMAGE has the ability to subtract a dipole plus a quadrupole from a 2-D skymap. (See Figure D.5 in Appendix D to see the effect of dipole subtraction.) To do this, choose +------------------+ +----------------------+ +-------------------+ | UIMAGE Main Menu |--->| Modeling and Fitting |---->| Subtract a Dipole | +------------------+ +----------------------+ | + Quadrupole | +-------------------+ Now pick the object you would like to manipulate and then enter an angle between (0 and 90 degrees) in response to the following prompt: Enter a galactic exclusion angle below in degrees (default = 20). angle: If a weight array has been associated with the selected data object, the title of the weight array is indicated in the session window, and it will be used in the calculation. Otherwise, the operation does not apply any weights. (See section 4.3.9 for instructions on linking weight arrays to data arrays.) X Window users see the display of the new skymap (which is equal to the original map minus the dipole + quadrupole) upon completion. To create a map of the quadrupole model, answer Yes to the next prompt, which inquires whether or not to return the quadrupole map. If you choose to do so, the quadrupole coefficients are printed in the session window. Corresponding UIDL routine: MULTIPOLE 4.4.7.3 Fitting to a Multiple Blackbody Model This option enables users to fit spectra to a three blackbody model, with one blackbody corresponding to the cosmic background and the other two corresponding to the residual dust. There are seven fitting parameters but they may not all be fitted at once; we recommend varying fewer than four parameters at a time. To begin, choose +------------------+ +----------------------+ +--------------------+ | UIMAGE Main Menu |--->| Modeling and Fitting |---->| Fit Spectra with a | +------------------+ +----------------------+ | 3 B-Body Model | +--------------------+ Select the operand, which may be the spectrum of a single pixel or a 3-D object (see sections 4.4.3.3 and 4.4.3.5 to create a spectrum). At this point, UIMAGE will indicate whether or not the chosen object has a weight associated with it. If no weight has been associated with the object, UIMAGE prints a message to this effect, and you will be asked to enter an estimate for sigma. After entering a value, the input parameter menu is presented. If you have selected a 3-D object as an operand, it looks like this: +-------------------------------------------+ | Define Input Parameters | +-------------------------------------------+ | CMB Temperature value array | | BB 1 Temperature array | | Optical Depth 1 value array | | Emissivity 1 value array | | BB 2 Temperature value array | | Optical Depth 2 value array | | Emissivity 2 value array | | Mask (def=no masking) | | Tolerance (def=1e-4) | | Input Frequency Units (def=icm) | | Input/Output Spectral units (def=MJy/sr) | | Abort | | HELP | | Done Defining Inputs | +-------------------------------------------+ The first seven parameters are used in the fitting equation: fit = P(T_0,nu) + op_depth1 * (nu/nu_c)^emiss1 * P(T_1,nu) + op_depth2 * (nu/nu_c)^emiss2 * P(T_2,nu) where P(T,nu) is a Planck blackbody spectrum, emiss is more accurately called the spectral index, and op_depth is the ratio between the input spectrum I(nu) and a Planck spectrum at the characteristic frequency: op_depth = I(nu_c) / [P(T,nu_c)*nu^emiss] Since the first seven choices in the above menu are not applicable when fitting the spectrum of a single pixel, they are not presented at all if the operand is a single spectrum. However, when performing fits to many spectra, these seven options allow you to enter arrays containing fixed values for the various parameters. Choices for these arrays must be 2-D with the same dimensions as the first two dimensions of the object to be fit. For example, when fitting all of the spectra in a high frequency FIRAS face, the data object would have dimensions of 32 x 32 x 168 so any parameter arrays must have dimensions of 32 x 32. If no arrays are entered, you will be prompted later for a single fixed value of sigma for UIMAGE to use on all of the pixels. The last four parameters can be used when fitting any number of spectra. The Mask option allows specified frequencies to be excluded from the fit. When this option is selected, the prompt looks like this: The range of the frequency/wavelength array is m - n Enter the masked element array values At this prompt, enter the frequency array indices of the channels to exclude. (See section 4.4.3.1 on displaying frequency tables if you are unsure of the correspondence between array index and frequency.) Multiple indices may be separated by a space or a comma, and ranges of indices may be specified using a colon (:) to separate the first and last index. Press to enter the numbers. The Tolerance is the minimum relative change in the chi^2 for the fit that must be reached for convergence. Select this menu option if you would like to set a value other than the default value of 1.0 x 10^(-4); enter the new tolerance at the prompt followed by a . Note that a maximum of 20 iterations is allowed. If the units of the frequency or wavelength are not inverse centimeters (icm), then choose the Input Frequency Units (def=icm) option from the list of input parameters. From the menu, select the proper units of frequency or wavelength. Possible units are inverse centimeters (icm), microns, or GHz. The default unit for a spectrum is the COBE-coined "eplee," or erg/s/cm^2/sr/icm. This is the default unit for the blackbody fitting routine (1 eplee = 2.9979 x 10^(-7) MJy/sr). Other possibilities are MJy/sr or W/cm^2/sr/K. To use a unit other than the eplee, choose the Input/Output Spectral units (def=eplees) option. From the menu, choose wcms for W/cm^2/sr/K or mjy for MJy/sr. When you have finished with this menu, choose Done Defining Inputs. You will be prompted for any of the seven parameters discussed above which do not yet have initial values set for them (the cosmic background temperature and the temperature, optical depth parameter, and emissivity spectral index of the other two blackbodies). The next round of prompts inquires which values will be varied and which will remain fixed. As mentioned above, it is recommended that you vary fewer than four parameters in any single fit. At this point you will be prompted with the following message: A characteristic frequency for which the optical depth coefficients give the ratio of the fit to a Planck at the fit temperature is needed. Enter the characteristic frequency (eg. 60.): Enter a value, and press . Finally, from the next six prompts, select any additional information that you would like to have returned: * Final fit parameter sigmas * Final fit residuals * Spectrum with the dust fit subtracted * Spectrum with the cosmic background fit subtracted * Fit chi^2 per degree of freedom * Number of iterations for the fit UIMAGE reiterates all of the initial input parameters and then begins the fit. If many fits are being performed, UIMAGE gives updates indicating the number of spectra that have been processed. Depending on how the fit was performed, newly created arrays may be in the object lists and available for use in future fits. Corresponding UIDL routine: FITSPEC 4.4.7.4 Fitting to a Bose-Einstein + Blackbody Model This routine fits spectra to a Bose-Einstein spectrum added to a residual Planck spectrum. There are five fitting parameters in all, but we recommended keeping at least two of them fixed in each fit. To begin, choose +----------------+ +--------------------+ +----------------------------+ |UIMAGE Main Menu|--->|Modeling and Fitting|--->|Fit Spectra with a Bose-Ein.| +----------------+ +--------------------+ | plus BB Model | +----------------------------+ Select an operand from the object list. Available objects will include spectrum of single pixels or 3-D objects (see sections 4.4.3.3 and 4.4.3.5 to create a spectrum). If the object is not associated with a weight array, UIMAGE indicates this now. If you have selected a 3-D object, you will see this menu: +--------------------------------------------+ | Define Input Parameters | +--------------------------------------------+ | BE Temperature value array | | BE Chemical Pot. value array | | BB Temperature value array | | Optical Depth value array | | Emissivity value array | | Mask (def=no masking) | | Tolerance (def=1e-4) | | Input Frequency Units (def=icm) | | Input/Output Spectral units (def=eplees) | | Abort | | HELP | | Done Defining Inputs | +--------------------------------------------+ The first five parameters are used in the fitting equation: fit = BE(T_0,mu,nu) + op_depth1 * (nu)^emiss1 * P(T_1,nu) where BE(T_0,mu,nu) is a Bose-Einstein spectrum with mu representing the chemical potential, P(T,nu) is a Planck blackbody spectrum, emiss is the emissivity spectral index, and op_depth is an optical depth parameter defined as op_depth = I(nu) / [P(T,nu)*nu^emiss] where I(nu) is the input spectrum. When performing fits to many spectra, the first five options allow you to enter arrays containing fixed values for the various parameters. Choices for these arrays must be 2-D arrays with the same dimensions as the first two dimensions of the object to be fit. For example, when fitting all of the spectra in a high frequency face of the FIRAS data set, the data object has dimensions of 32 x 32 x 168, so any parameter arrays must have dimensions of 32 x 32. If no arrays are entered, you will be prompted later for a single value for UIMAGE to use on all of the pixels. If you selected a single spectrum, the first five choices in the menu shown above will not be presented since they are not applicable when fitting the spectrum of only one pixel. You will be prompted for single values of the parameters. The last four parameters can be used when fitting any number of spectra. The Mask option allows specified frequencies to be excluded from the fit. When this option is selected, the prompt looks like this: The range of the frequency/wavelength array is m - n Enter the masked element array values At this prompt, enter the frequency array indices of the channels to exclude. (See section 4.4.3.1 on displaying frequency tables if you are unsure of the correspondence between array index and frequency.) Multiple indices may be separated by a space or a comma, and ranges of indices may be specified using a colon (:) to separate the first and last index. Press to enter the numbers. The Tolerance is the minimum relative change in the chi^2 for the fit that must be reached for convergence. Select this menu option if you would like to set a value other than the default value of 1.0 x 10^(-4); enter the new tolerance at the prompt followed by a . Note that a maximum of 20 iterations is allowed. If the units of the frequency or wavelength are not inverse centimeters (icm), then choose the Input Frequency Units (def=icm) option from the list of input parameters. From the menu, select the proper units of frequency or wavelength. Possible units are inverse centimeters (icm), microns, or GHz. The default unit for the spectra is the COBE-coined "eplee," or erg/s/cm^2/sr/icm. This is the default unit for the blackbody fitting routine (1 eplee = 2.9979 x 10^(-7) MJy/sr). Other possibilities are MJy/sr or W/cm^2/sr/K. To use a unit other than the eplee, choose the Input/Output Spectral units (def=eplees) option. From the menu, choose wcms for W/cm^2/sr/K or mjy for MJy/sr. When you have finished with this menu, choose Done Defining Inputs. You will now be prompted for any of the five parameters discussed above (Bose-Einstein temperature, Bose-Einstein chemical potential, blackbody temperature, blackbody optical depth parameter, and blackbody emissivity spectral index). Once all of the initial parameters have been defined, you must choose which parameters to fix and which to vary. As mentioned above, we suggest that you vary fewer than four parameters in any single fit. From the next six prompts, select any additional information that you would like returned: * Final fit parameter sigmas * Final fit residuals * Spectrum with the dust fit subtracted * Spectrum with the cosmic background fit subtracted * Fit chi^2 per degree of freedom * Number of iterations for the fit The initial input parameters are reiterated and the fitting begins. If multiple fits are being performed, UIMAGE gives updates indicating the number of spectra that it has already processed. Depending on how the fit was performed, newly created arrays may be in the object lists and available for use in future fits. Corresponding UIDL routine: FITMU 4.4.7.5 Modeling General Backgrounds Through this modeling option, UIMAGE provides a general background fitting routine in which different models can be created by various combinations of input parameters. Using a 2-D skymap as input, a 2-D background model is built. To use this fitting routine, choose +----------------+ +--------------------+ +----------------------------+ |UIMAGE Main Menu|--->|Modeling and Fitting|--->|2-D Background Modeling Tool| +----------------+ +--------------------+ +----------------------------+ Select a 2-D object from the list. You'll now encounter this menu: +-----------------------------------------------------------+ | Define Input Parameters | +-----------------------------------------------------------+ | Order of polynomial surface fit (per dimension) | | Size of Spatial Filter in Pixels | | Number of standard deviations used to ID a source (cut) | | Size of pixel patch removed when source is ID (def=3) | | Name of filter function (def='min'==lower envelope) | | Include map corners, selecting points w/mouse (def=yes) | | Suppress plotting (not valid if interactive) | | Create a final source subtracted map (must specify cut) | | HELP | | DONE | +-----------------------------------------------------------+ From this menu, define the input parameters by selecting the menu option(s) and entering a new value. Options that have defaults listed in the menu (def=) will use these defaults unless they are changed. Options without defaults listed are not used at all unless the user selects the option. As stated before, this program is quite versatile, and many different models may be created by combining input parameters. The table below gives examples of different types of models and how to create them. MODEL INPUT PARAMETERS TO DEFINE ---------------------------------------------------------------------- Quintic Interpolation using the None mouse to specify pixels to be used in the fit Quintic Interpolation with an Order of poly. surface fit: n nth-order polynomial surface fit to the interpolated background Lower envelope modeling using an Size of Spatial Filter: N N x N spatial minimum filter Lower envelope modeling using an Order of poly. surface fit: n N x N median filter with an nth- Size of Spatial Filter: N order polynomial surface fit to Name of filter function: 'median' the lower envelope Iterative surface fitting with Order of poly. surface fit: n source subtraction. At each Number of standard deviations: M iteration, the routine first Size of pixel patch: P calculates an intermediate background model using a surface fit. The background model is then subtracted from the original map, and the standard deviation of the residuals is determined. All pixels greater than M standard deviations above the background are located, a P x P pixel patch centered on each deviant pixel is sentinelized, and the next iteration begins. Iterations stop when no more sources are found. Iterative surface fitting with Order of poly. surface fit: n source subtraction (described Size of spatial filter: N above) where the surface fit is Number of standard deviations: M done to the N x N lower envelope Size of pixel patch: P Iterative surface fitting with Size of spatial filter: N source subtraction using an Number of standard deviations: M averaging filter with no surface Size of pixel patch: P fitting Name of filter function: 'avg' NOTES: * If you choose to have a final source subtracted map created (last option), then you must also specify the cut (option 3: Number of standard deviations used to ID a source). * Valid inputs for these options are: Order of polynomial surface fit n > 0 Size of spatial filter in pixels N > 1 Number of standard deviations used to ID a source M > 0 Size of pixel patch removed when source is ID P > 1 Name of filter function Any function that takes an array as input and returns a scalar * Functions entered for the filter name MUST be enclosed in quotation marks. * The Supress (sic) plotting option will be automatically set for non-X Window users. For further information on this fitting routine, see the COBE Software Catalog or type UHELP, 'MKBGRMOD' at the UIDL prompt. Once the type of fit has been determined and the parameters have been entered, a copy of the original map is displayed in a new window. Another window follows showing the fit. Note, however, that neither of these two images are UIMAGE objects; they have been created by the fitting routine but do not enter UIMAGE's memory as objects and therefore cannot be operated upon or controlled by UIMAGE in any way. A final window is displayed that contains the new UIMAGE object, with the title Background Model [#]. This is the result of the fit, which UIMAGE retains in memory. Corresponding UIDL routine: MKBGRMOD 4.4.7.6 Fitting Polynomials to Graphs To fit a polynomial to a graph, choose these options: +------------------+ +----------------------+ +------------------------+ | UIMAGE Main Menu |--->| Modeling and Fitting |--->| 1-D Polynomial Fitting | +------------------+ +----------------------+ +------------------------+ From the list of available graphs, choose an operand. If this object is not associated with a weight array, answer this prompt: There are no weights associated with the chosen object. Enter an estimate for the Sigma: The weights will be defined as 1./sigma^2; therefore, if no weighting is desired, enter 1. The next menu allows the user to define the input parameters and choose which output parameters to return: +-------------------------------------------------------------+ | Define Input/Output Parameters | +-------------------------------------------------------------+ | Degree of polynomial (mandatory) | | Overlay fit (mandatory for scatter plots)? | | Output residual of fit (not appropriate for scatter plots)? | | Output chisq? | | Output Covariance? | | Output Sigma? | | Output singular points? | | Mask any frequencies? | | HELP | | DONE | +-------------------------------------------------------------+ As indicated, the first option must be defined in all cases. Choose Degree of polynomial and enter the appropriate number at the following prompt. The second option must be chosen if you are working with a scatter plot. To create a UIMAGE data object with the residuals of the fit, choose the third option. If you would like the value of the final chi^2, the elements of the covariance matrix, the errors (sigma), or a count of singular points to be printed out, choose the corresponding menu option, and that value will be returned. To exclude some frequencies or wavelengths from the fit, choose Mask any frequencies?; UIMAGE lists the range of the array. Enter the frequency array indices of the channels to exclude. (See section 4.4.3.1 on displaying frequency tables if you are unsure of the correspondence between array index and frequency.) Multiple indices may be separated by a space or a comma, and ranges of indices may be specified using a colon (:) to separate the first and last index. Press to enter the numbers. When finished with this menu, select DONE. UIMAGE proceeds with the fitting and returns the requested parameters. 4.4.7.7 Fitting to a Gaussian You may fit an existing graph or section of a graph with a function of the form y = A_0*exp[-(x-A_1)^2/(2*A_2^2)] + [A_3+A_4*x+A_5*x^2] Follow this menu chain: +------------------+ +----------------------+ +----------------------+ | UIMAGE Main Menu |->| Modeling and Fitting |->| 1-D Gaussian Fitting | +------------------+ +----------------------+ +----------------------+ Choose the appropriate graph from the next list. If your graph has weights associated with it, the message Weights will be taken from Weights for your_object_name will appear in your terminal session window. Next follows a menu of your fitting options: +-------------------------------------------------------------+ | Define Input/Output Parameters | +-------------------------------------------------------------+ | Remove a first order baseline? | | Remove a second order baseline? | | Overlay fit (mandatory for scatter plots)? | | Output residual of fit (not appropriate for scatter plots)? | | Output sigma? | | Mask any points? | | HELP | | DONE | +-------------------------------------------------------------+ As you choose parameters, they will be acknowledged on your terminal. For example, choosing Remove a first order baseline? prints A linear fit will be made to the baseline to the screen. The menu will then reappear to allow you to make further choices. The Remove a first order baseline? option fits a straight line plus a Gaussian to the graph, setting A_5 to 0 in the equation above. Similarly, Remove a second order baseline? fits a quadratic polynomial plus a Gaussian line to the graph. Overlay fit? draws the fit function as a dotted line over your graph. Output residual of fit? produces a second graph of the initial graph minus the fit. Output sigma? lists the standard deviations corresponding to the output parameter values. Mask any points? allows you to restrict the range of the fit, instructing the fit to ignore other lines, for example. (You can determine which bins to ignore or include by using the Pixel information for graphs feature described in section 4.4.4.9.) After choosing the masking option, the following appears on your screen: The range of the frequency/wavelength array is first_channel - last_channel Enter the masked element array values start_ignoring:stop_ignoring Once you have entered the values, the parameter menu returns. You may enter individual channels as well, and combine several channels and ranges by using commas to separate each one. (Use 1:5, 65:70 to mask off channels 1-5 and 65-70, for example.) HELP displays a general information screen about the Gaussian fitting routine. It is also possible to dump this information into a file for printing later. DONE indicates that you have completed your choice of I/O parameters. The program responds with the terminal message: Parameters are defined, proceeding..