;--------------------------------------------------------------------------- ; Document name: image_tool.hlp ; Created by: Liyun Wang, GSFC/ARC, February 14, 1995 ; ; Last Modified: Mon Sep 29 17:47:51 1997 (lwang@achilles.nascom.nasa.gov) ;--------------------------------------------------------------------------- ; ; This is the help file for IMAGE_TOOL. It can be read and ; displayed by WIDG_HELP, version 2 and up and can be read ; MK_HELP_STC and displayed by XSHOW_HELP. When WIDG_HELP or ; MK_HELP_STC is called, the keyword SEP_CHAR should be set ; to '~'. ; ;--------------------------------------------------------------------------- ~Overview SOHO Image Tool The SOHO Image Tool is an IDL widget program originally designed as a pointing tool for SOHO CDS/SUMER instruments. Other SOHO instruments can also use this tool as their pointing tool as long as they supply from their planning tool a predefined pointing structure to it. Image Tool can be also used to display ground-based and spacecraft solar images. ~File File Button ~~Make Hard Copy Make Hard Copy The displayed image can be saved in PS and GIF formats as a file or be sent directly to the printer for printing via this option. When running under a UNIX system, the whole Image Tool window can be saved in PS or GIF format. ~~Save Image in FITS Format Save Image in FITS Format The displayed image can also be saved in FITS format, as long as the image contains coordinate and scaling related information. You can use this feature to save a zoomed in image in FITS format. Please note that this option only writes minimum information into the FITS header. Information contained in original FITS header is not included. ~~Update FITS Header Update FITS Header If you have the privilege to change the original FITS file, you can use this option to update the FITS header, especially after you obtained corrected position and scaling information via limb-fitting. ~~Quit Quit Image Tool You have the choice of whether to retain the displayed image when you quit Image Tool. ~Tools Built-in tools in Image Tool include Image Picker, Limb Fitter, Pointing Tool, Magnifier, Profiler, Overlayer, and others. ~~Image Picker Image Picker Different type of images from different sources can be loaded into Image Tool. Depending on the set up of your system, Image Tool may have access to the SOHO Synoptic Database, Summary Database, and Private Database. Image files located in elsewhere can be loaded in as personal data. This version of Image Tool supports primarily solar images in FITS format because FITS files usually contain necessary information in the FITS header needed by Image Tool. Images in GIF format are also supported as personal data, but the user needs to supply image related information such as observation time and scaling factor (if not full-disc image). To select images from one of SOHO databases, click the first pull-down menu button in the Image Picker and select one of SOHO databases. You then select an image source from the pull-down menu button labeled "Source:". Press the "List file" button to get a list of images from that source observed in the period indicated by the "Start" and "Stop" dates. This start or stop date can be changed by editing the the content of the appropriate box. You can also turn on the "Auto list files" option so that images can be listed automatically each time when you select a new source from the same database. (This option is always turned off when you change to a new database.) If you are loading in a FITS file that has several images buried in binary tables (such as CDS image files), you will see a pop-up widget that allows you to choose which image in the binary table you want to load. The specified image will then be loaded in. Also, a new button in the top button row will appear which shows the number of image currently being displayed, and another image can be selected and load in from this button. When a new image is loaded in, the current displayed image will be saved onto the image stack and displayed as an icon on the left side of the image window. Images saved in the stack can be loaded into the main image window via a left-click of mouse button over the image. Up to 12 images can be saved on to the image stack. ~~Limb Fitter Limb Fitter The Limb Fitter Tool allows one to interactively choose a certain number of points around the solar limb and uses a non-linear least square fit algorithm to do a circular or ecliptical fitting. The number of points to be used for limb-fitting can be adjusted by moving the indicated slider bar. Theoretically, the more points you use, the more accurate the result can be. By default, this number is set to 10. Once the number of points to be used is determined, you can start selecting those points by moving the cursor to the desired point (presumely on the limb, of course) and click the mouse button. A magnified window should give you a better precision in choosing the limb point. The point number, its position you just selected and number of remaining points needed are shown in the tree text widgets near the bottom. You have to complete ALL required points before the limb fitting process can be proceed. As a result of this fitting process, the coordinates of the solar disc center (X0, Y0) in arc seconds, semi-diameters of the major- and minor-axes of the solar disc in X and Y directions (RX0, RY0), also in arc seconds, and the image scaling factors (arc seconds per image pixel) in X and Y directions (SRX, SRY) are all given. Pressing the "Accept" button will take any result you have obtained and exit from the Limb Fitter. You can quit the Limb Fitter without taking any results by pressing the "Cancel" button at any time. The "Reset" button will set all parameters to its original status, and any result you get will be lost. ~~Pointing Tool Pointing Tool Pointing Tool is usually used as part of a planning tool of a SOHO instrument. It allows the planner to view or determine the pointing of the instrument at the time of observation based on an image obtained earlier. When doing so interactively, the planner can drag around a graphic box representing the field of view (FOV) of the instrument to a desired location on the solar disc. Value of the pointing of a given area is always the center of the area. Before the Pointing Tool is used, you should make sure that the currently displayed image is properly oriented (through options under the pull-down menu "Options") such that the north solar pole is straight up (positive Y direction) and the west limb of the solar disc is on your right side (i.e., the positive X direction). This tool gives the user a choice whether or not the solar differential rotation should be taken into account when the pointing is done. If the option "Allow Time Projection" is chosen and the pointing area is not supposed to be off the limb (as indicated in the "ZONE" widget), the resultant pointing values will reflect those when the actual observation begins (indicated by "Starting Time" widget). If the pointing center is "rotated" off the limb by the time the observation begins, the time projection option will be turned off automatically, and no rotation will be applied. If a pointing area is required to be put off limb, no rotation will be applied to this pointing area and the criteria will be tested to make sure it is met. Before you determine the pointing of an area, you should first select the pointing areas from the list. The pointing values can be directly edited manually in the widgets that show the current pointing values. A carriage return is required to take the manual editing into effect. To do it interactively, you can press the "Go" button; A box representing the FOV of the current selected pointing area should appear in the image. You can then press and drag the right mouse button to move the pointing box around. Once you have put the pointing area to the desired place, press the "Ok" button to accept the result. Up to this point, the button "Pointed" should be checked, meaning that the pointing of the current selected area has been determined. You can abort the interactive pointing process by pressing the "Cancel" button. You can undo what you have done by pressing the "Undo" button; the lasted saved pointing values will be restored. You can restore all pointing values of all areas to their original values by pressing the "Undo All" button. You will be reminded when you leave the Pointing Tool if you have any pointing area left undetermined. If you don't want to change values of a pointing area, you can check on the "Pointed" button. Positions of all pointing areas or all rasters for the current selected pointing area against the current displayed image can be displayed against the image through the pull-down menu button "Plot". The current pointing area, if pointed, can be identified through the "Identify" button. You can quit the Pointing Tool by pressing the "Exit" button which will take you back to Image Picker. ~~Image Magnifier Image Magnifier The Image Magnifier displays, on the left side of the main image window, interactively an enlarged portion of image centered at the cursor when you move the cursor around over the image. To quit this tool and back to previous tool, you must press the *right* mouse button. Please note that this Image Magnifier does not increase the resolution of the displayed image; instead, it simply magnifies what is displayed in the main image window. In other words, the resolution of the magnified image is limited to that of the displayed image. To view enlarged image in its original image resolutoin, use the Fancy Magnifoer. ~~Image Profiler Image Profiler The Image Profiler draws interactively row or column profiles, at the mouse cursor location, of the image displayed in the main window. Pressing the left mouse button toggles between row and column profiles. The right mouse button quits the tool and back to previous tool. ~~Overlayer Overlayer Overlayer is a tool that is used to overlay an image, partial or whole, to the base image, with or without align with the base image in observation time. Only images saved in image stack (shown on the right side of the main image window) can be selected and loaded into the overlayer. To do so, you move the mouse cursor over an icon of the interested image and click the right mouse button. A box will be plotted around the selected image icon, and the image (referred to as the secondary image) will be loaded into the Overlayer. Usually, you would just want to overlay region of the secondary image to the base image. To select a region, press and drag the left mouse button to get a desired size and shape of a box for the region. The box can be moved around by pressing and dragging the right mouse button. Once the region is selected, all region related overlaying functions under the pull-down menu button "Overlay" will become available and ready to be revoked. The region on the secondary image can be overlayed to the base image in different ways. It can be overlayed as a contour map. It can also be overlayed transparently (so that you can see through both base and seconday images), or as a composite image; in the later case, you will have the choice of using two different color tables to represent both base and secondary images respectively. You can also take addition or average on both images in the overlay region, and you can replace overlayed region on the base image with the secondary image. You can turn on/off the option of "Align with Base Image". When this option is on, the selected region in seconday image will be differentially rotated to the observation time of the base image (unless the difference of the observation times of both base and secondary images is within 10 minutes) before it is overlayed to the base image. Initially this can take a while, but the differential rotation is done only once and won't repeat unless you select a new region or the base image is changed. Since differentially rotating a whole image takes lots of time, overlaying the whole secondary image to the base image is restricted to when the "Align with Base Image" option is turned off. ~~Fancy Magnifier Fancy Magnifier This is another way of seeing the image closely. A new widget with nicer interface will give you more options to see the image closely. The resolution of the magnified image is limited only to that of the original image. ~~Colar Table Color Table Manipulator Allows you to load a variety of predefined color tables and manipulate the color table. ~~XDOC X D O C XDOC is an excellent IDL widget program, written by Dominic Zarro of NASA/GSFC, that is used to browse IDL programs available to your current IDL session. ~Options ~~Image Manupilation Image Manupilation Image Tool provides variety of functions for one to manipulate the displayed image. Click the subtopic for details. ~~~Lock Orientation Lock/Unlock image Orientation Make the solar coordinates to be attached to or detached from the image. Generally, the image manipulation operations such as flip, reverse, and rotate can be performed to make sure that the image is oriented such that the solar north pole is straight up and the west limb is toward the right side of the image. Once the image orientation is correctly set and locked, the image's orientation can be locked so that the solar coordinate system will follow any further operations. One can unlock the image orientation if desired. Once the image orientation is locked, there will be an indicator plotted near the upper-right corner of the image indicating north and west directions. ~~~Flip N/S Flip N/S This option flips the image upside down. Good for turning an image, in which the solar north pole is straight down, to the proper orientation. ~~~Reverse W/E Reverse W/E This option reverse the image left side right, or vice versa. Useful to turn the west/east limb leftward or rightward. ~~~Rotate 90 deg counter-clockwise Rotate 90 degrees counter-clockwise This option rotates the image 90 degrees counter clockwise. Available only when image orientation is not locked. ~~~Rotate 45 deg counter-clockwise Rotate 45 degrees counter-clockwise This option rotates the image 45 degrees counter clockwise. Available only when image orientation is not locked. ~~~Rotate 45 deg clockwise Rotate 45 degrees clockwise This option rotates the image 45 degrees clockwise. Available only when image orientation is not locked. ~~~Rotate 180 degrees Rotate 180 degrees This is a combination of the "Flip" and "Reverse" options. It rotates the image 180 degrees. ~~~Log Scaling Log Scaling This option rescale the image by taking logarithm to the image array. You will be asked wether to permanently rescale the image logarithmically. If you choose not to apply the option permanently, next time when the image is redisplayed, the original scaling will be restored. This option cannot be applied to images that have been already scaled logarithmically. ~~~Histogram Equalize Histogram Equalize Make the displayed image histogram-equalized. ~~~SigRange SigRange Select and display the most significant data range in the image. ~~~Smooth Smooth This option smooths the base image by taking average over neighboring points. ~~~Show Edge Show Edge This option enhances the edge of the displayed image. ~~~Plot Contour Plot Contour This option makes a contour plot over the displayed image. You can change number of contour levels from the "Set Contour Level" option under "Options". ~~Set Minimum Value Set Minimum Value Set the minimum value of image to be considered when scaling the image for display; useful when display images with "bad" pixels. ~~Set Maximum Value Set Maximum Value Set the maximum value of image to be considered when scaling the image for display; useful when display images with "bad" pixels. ~~Reset Image Limits Reset Image Limits This option resets the limits of the displayed image back to its original values. ~~Set System Variable Set System Variable This is a pull down menu to allow you to change the following IDL system variables which are graphic related: !P.Color, !P.Backgroud, !P.CharSize, !P.CharThick, and !P.TickLen. ~~Set Contour Level Set Contour Level ~~Change Cursor Color Change Cursor Color By default, the cursor is plotted with the highest available color (usually white), but you can change it to use other color through this option. ~~Use Boxed Cursor Use Boxed (or Cross-hair) Cursor By default, when you click the left mouse button over the displayed image, a cross-hair cursor is plotted over the image. You can choose to plot the cursor in either boxed or cross-hair shape through this option. When you choose the boxed cursor, you can change its size through the "Set Boxed Cursor Size" option in units of device pixels, image pixcels, or arc seconds (if the solar graphic system has been established). ~~Remove Image from Stack Remove Image from Stack Whenever a new image is loaded in, the previous image will be saved onto an image stack, in which the saved images are displayed as icons in a narrow window in the right of the main image window. Image Tool can currently save up to 12 images in the stack. Once this limit is reached, the image at the top of the stack will be popped off when a new image is loaded in. You may want to remove a specific image from the stack to free up some space. To do so, you need to select the image to be removed by clicking the *right* mouse button over the image icon (this image will be loaded into the Image Overlayer at the same time). You then choose this option to remove the selected image from the image stack. ~~Show Image Info Show Image Info This button displays some basic information on size and location of the displayed image. ~~Display FITS Header Display FITS Header This button displays the header information extracted from the current image FITS file. ~~Show CSI Show CSI This button displays the Coordinate System Information (CSI) structure of the displayed image. This structure is used internally by Image Tool to establish necessary solar coordinate system and to conduct conversion among different coordinate systems involved. ~Refresh Refresh Button Use this button to redraw the displayed image. It is sometimes necessary to do so, especially when the image is "messed" up by wanted boxes or cursors or contore curves are overplotted on the image. Note that images resulted from overlaying functions and contour curves are not replotted when the image window is refreshed. When necessary, those functions have to be repeated after the image window is refreshed. ~Zoom In/Out Zoom In/Out The zoom in/out feature alows you to zoom in any part of the image for a closer look. This is useful when you need to examine or deal with a small portion in the image. To select the portion of an image to zoom in, 1) move the cursor to the corner of desired region; 2) press and drag the left mouse button till you get a satisfied size and shape of a box representing the selected region. This process can be repeated till you are satisfied. 3) The position of the selected region (box) can be changed by pressing and dragging the *right* mouse button. Once the desired region is selected, you can press the "Zoom In" button on the left side of the image; the selected portion of the image will be displayed. To Zoom out, simply press the "Zoom Out" button. Note that you cannot zoom in the image when you are already looking at a zoomed in image. ~Differential Rotation Differential Rotation Image Tool supports several differential rotation functions, mainly for the purpose of predicting where a specific feature on the solar surface will move. Direction of differential rotation can be set either eastward or westward by selecting the "West" or "East" button. The time interval over which the rotation is done can be changed in the interval box (a carriage return required), or can be set to the the current observation start time. Points on east or west limb, or on central meridian longitude can be rotated at any time. You can select a point or a region for rotation. To select a point, simply move the cursor to its target point and click the left button; a cross-hair or boxed cursor will appear at the point. To select a region, press and drag the left button to draw a box representing the region. You can move the box by pressing and dragging the right button. Once a point is selected, you can select via the pull-down menu button "Diff. Rotate" a function to rotate 1) the selected point; 2) all points that have the same longitude value; or 3) all points that have the same Solar-X value. When doing differential rotation to a region, you have the choice of rotating the region with or without relevent image pixels remapped. Remapping the image pixels takes some time, depending on how big the selected region is. Finally, the whole image can be differentially rotated. This operation is usually very time consuming, so before you start it, you will be asked whether you really want to proceed. Please note that any differential rotation indicator or remapped image pixels are not saved and they will disappear whenever the main image window is refreshed. ~Image Display Image Display The loaded-in image is displayed on the right side of the Image Tool widget. Image source or type and date/time at which the image was taken are shown on the top of displayed image. If the image contains necessary information (usually extracted from the header of FITS file) to establish a solar coordinate system, the coordinates of the current cursor position can be displayed in one of the following coordinate systems: device coordinate system, data coordinate system, solar disc coordinate system, and heliographic coordinate system. For a full-disc solar image, if it does not have enough information to establish a solar coordinate system, you can use the Limb Fitter to calculate such information. Images can be displayed with different color table. You can select any color table from the pull-down menu button "Select color table" under the main image window. Pressing and dragging the left, middle, and right mouse button Usually, moving the mouse cursor into the display window does not do any thing except that the cursor position is reported in the "Cursor Position" widget. Clicking the left button will plot the cursor (its shape and size can be set through a button under "Options") at the current position and erase the previous cursor. You can select a region in the image, for zoomming in or for differential rotation, by pressing and dragging the left button till the size and shape of a box representing the selected region are obtained. You can move the region box by pressing and dragging the right mouse button. ~Grid Image Grid Heliographic grid lines can be plotted over the displayed image by selecting the "Grid" button. Line intervals in latitude and longitude can be changed by editing the contents of "LAT" and "LONG" area (a carriage return is required for the editing to take effect). ~Set Cursor Set Cursor Shape/Size Cursor shape can be set to cross-hair or boxed. The size of a boxed cursor can be further set through the "Set Boxed Cursor Size" button in units of device pixels, image data pixcels, or arc seconds. ~Set Image Size Set Image Size The relative image size can be set through a pop up widget to a value between 0.1 and 1. This is useful when the displayed image is too big such that image annotation is squeezed off the display window. ~Coordinates Cursor Position When the mouse cursor is in the display window, its position is reported in this "Cursor Position" widget in one of the following coordinate systems: 1) Device coordinate system, 2) Image pixel system, 3) Solar disc system, and 4) Heliographic system. If the pointing information of the image is not available, the later 2 systems will not be available. ~Time Setting Time Setting The start date/time and image observation date/time can be set to an arbitrary value or reset to their original value.