home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / software / unix / saoimage / sao1_07.tar / doc / region.txt < prev    next >
Text File  |  1992-05-07  |  6KB  |  139 lines
  1.  
  2. SAOimage cursor regions
  3.  
  4. A region is a cursor which has been stored.  SAOimage cursors can be
  5. stored, recalled, written to disk, and read from disk using the
  6. "region" features.  Region controls work only when SAOimage is in
  7. "cursor mode".  Regions were designed for use with SAO's PROS/IRAF
  8. image analysis software, but they can be generally useful.
  9.  
  10. There are two classes of regions; include and exclude.  When used by
  11. the PROS software, an include region indicates an area of interest
  12. for analysis (e.g. for counts within a region).  An exclude region
  13. indicates areas or pixels to be excluded from analysis (e.g. bad
  14. pixels or areas affected by other phenomena such as an adjacent source).
  15.  
  16. saving and unsaving
  17.  
  18. To save the current cursor as a region, type the "S" key for in include
  19. region or the "E" key for an exclude region.  To unsave the most
  20. recently saved region, type the "Delete" key.  To unsave an arbitrary
  21. region, place the mouse within that region and type the "D" key.  If
  22. the mouse is within two regions when the "D" key is typed, the smaller
  23. region is deleted.  When a point cursor is the active cursor, the three
  24. mouse keys are mapped to perform the same functions as the "S" key (left
  25. mouse button), the "E" key (middle mouse button) and the "D" key (right
  26. mouse button).  Only point regions can be deleted with the right mouse
  27. button.  For purposes of deleting, the area of a point region is defined
  28. to be the area of the first character of its label.
  29.  
  30. Saved regions are normally drawn and labeled.  On color workstations,
  31. include regions are drawn in yellow, while exclude regions are drawn in
  32. red.  The label usually has three parts: the coordinates of the center,
  33. a line from the center to the edge along the region's positive Y axis,
  34. and the length of the radius along that line.  The radius is followed by
  35. a "+" for include regions or a "-" to indicate an exlude region.  Only
  36. the center coordinate is given for a point (followed by a "+" or "-").
  37. The point is at the left edge of the label and on a line along the
  38. bottom of the label characters.  Polygons have no labels.
  39.  
  40. menu controls
  41.  
  42. In the cursor submenu, the "Region" button toggles the cursor control
  43. page with the region submenu page.  In the region submenu, the "Cursor"
  44. button restores the cursor submenu page.
  45.  
  46. In the region submenu, the "label" button suppresses labeling of the
  47. regions.  The "view" button completely suppresses display of the
  48. regions.  These buttons are both toggle buttons which are turned on or
  49. off when pressed.
  50.  
  51. The "cycle" button makes the cursor an exact copy of a region (recalling
  52. the cursor).  The center of that region and its sequence number are
  53. displayed in the magnifier window.  Repeatedly pressing "cycle", copies
  54. each region in turn (cycles through the regions).  The cycled cursor is
  55. a normal cursor and can be manipulated.  The copied region is unaffected
  56. by "cycle", however, the just copied region can be deleted by pressing
  57. the "omit" button.  The "omit" button only works if the cursor has just
  58. been cycled to that region.  Once you alter the cursor "omit" is disabled.
  59. To adjust a region, "cycle" the cursor to that region, "omit" the original
  60. region, adjust the cursor, and then save the cursor as a new region.
  61.  
  62. The "reset" button clears the memory of all regions (deletes all regions).
  63.  
  64. The "read" and "write" buttons read and write ascii descriptions of regions
  65. to or from a disk file.
  66.  
  67. regions as ascii disk files
  68.  
  69. After saving one or more regions, the stored regions can be written to a
  70. disk file.  Normally the regions are written in a format which can be
  71. parsed by the PROS/IRAF software.  If SAOimage is in -imtool mode, it
  72. mimics IRAF's Imtool output, which is simply a list of cordinates for
  73. the centers of cursors.  Either type of file can be read at any time,
  74. regardless of the mode.
  75.  
  76. A PROS region consists of a leading space (include) or "-" sign (exclude)
  77. followed by the name of the region type, its center coordinates in file
  78. pixels, and then its radius on its X axis, its radius on its Y axis, and
  79. its angle in degrees (counter clockwise from straight up as per
  80. astronomical convention).  Some regions don't have angles (or the angle 0
  81. is not given), circles have only 1 radius, and points have no radii.
  82. Polygons are represented by pairs of coordinates (X,Y,X,Y,...).  See the
  83. PROS region documentation for a full explanation.
  84.  
  85. # images/m51.fits
  86. # Mon Jan 16 16:09:43 1989
  87. # shape x, y, [x dimension, y dimension], [angle]
  88.  BOX(135.67,213.00,18.00,10.67)
  89.  BOX(504.00,538.00,16.96,106.53,290.714)
  90.  CIRCLE(129.00,306.67,9.89)
  91. -ELLIPSE(486.00,468.00,36.53,44.08,329.036)
  92. -POINT(83.00,349.00)
  93.  POLYGON(131.00,245.00,120.67,280.33,165.00,245.00,140.00,234.67)
  94.  
  95.  
  96. Annuli of boxes and ellipses are not supported basic PROS region types.
  97. They are implemented as logical combinations of the basic PROS types.
  98.  
  99.  BOX(149.67,205.00,10.00,4.00)
  100.  BOX(149.67,205.00,20.00,8.00) & !BOX(149.67,205.00,10.00,4.00)
  101.  BOX(149.67,205.00,30.00,12.00) & !BOX(149.67,205.00,20.00,8.00)
  102.  
  103. The above example has two concentric rings and the center area.
  104.  
  105. When "write" is pressed, a popup window appears to prompt the user for
  106. the file name.  The window may be initialized to a default, or the
  107. previously given file name.  To select a different name name, edit the
  108. name in the window (see the Keyboard section).  If the named file already
  109. exists, another popup window appears with the options to overwrite the
  110. existing file ('o'), append to the existing file ('a'), or quit without
  111. writing anything ('q').
  112.  
  113. PROS format files which were previously written can be read back in.
  114. Press the "read" button and give the name of the file.  Reading does
  115. not support the full PROS region syntax (i.e. PIE slices are not
  116. supported), but much of the syntax is supported, including any syntax
  117. used by the "write".  Regions read from disk are added to any regions
  118. already stored.
  119.  
  120. The output as an Imtool list, equivalent to the first example, would
  121. look like the following:
  122.  
  123. # images/m51.fits
  124. # Fri Jan 20 13:35:36 1989
  125. # (x, y)
  126. 136 213
  127. 504 538
  128. 129 307
  129. 486 468
  130. 83 349
  131. 131 245
  132. 149 205
  133.  
  134. If your environment has been properly initialized as for an IRAF
  135. Imtool user, the default list output filename will follow standard
  136. IRAF conventions.  When read, the list coordinates are all read as
  137. exclude points.
  138.  
  139.