STScI Logo

fixsaoreg xray.xspatial


NAME · USAGE · DESCRIPTION · PARAMETERS · FULL_DESCRIPTION
EXAMPLES_ · TIME_REQUIREMENTS · RESTRICTIONS · BUGS · SEE_ALSO

NAME

fixsaoreg -- convert SAOimage cursor file to PROS region descriptor file, or convert PROS region descriptor file to SAOimage cursor file

USAGE

fixsaoreg regions_input regions_output

DESCRIPTION

This task converts an SAOimage cursor file to a form suitable for use in PROS tasks. It converts the logical coordinates put out by SAOimage into physical coordinates. (See help regcoords for descriptions of logical and physical coordinates.) The task can also be used in the reverse direction, to convert physical coordinates into logical coordinates for use in SAOimage.

PARAMETERS

regions_input = "" prompt = regions file to convert

The name of the input regions file. See below under FULL DESCRIPTION for detailed information about supported file formats.

regions_output = "" prompt = output regions file, coords converted

The name of the output file. It will contain descriptors of the same regions as the input file, with the coordinates and measures transformed from logical to physical or from physical to logical units. Each transformed line is preceded by a comment line showing the descriptor before conversion.

(clobber = no) [boolean]

If set to yes this will silently overwrite any existing output file. If set to no it will refuse to overwrite.

(display = 1) [0-5]

If greater than 0, this will display additional information about the progress of the conversion.

FULL DESCRIPTION

The input file may be a file generated by SAOimage, such as this one, which fixsaoreg will convert to physical coordinates:


# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:38:12 1994
# shape x, y, [x dimension, y dimension], [angle]
 CIRCLE(291,549,7.81)

Or the input file may be a PROS region descriptor file in SAOimage format but in physical coordinates. This file will be converted to logical coordinates for input to SAOimage:

# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:43:46 1994
# shape x, y, [x dimension, y dimension], [angle]
 PHYSICAL
 CIRCLE(2328,4392,62.48)

Either form of input file is a region descriptor file, but there are certain restrictions on it:

	- The file must contain the specification of a reference 
	  image or QPOE file. The reference file specification must 
	  begin in the third position in a comment line that begins 
	  the file.  (To be able to run fixsaoreg from a directory 
	  other than the one that contains the reference image, you 
	  should use a full path specification when telling SAOimage 
	  what image to display; then cursors that you save will 
	  contain the full path of the reference file specification.)

	- The file must contain only descriptors that SAOimage 
	  supports (no pie slices, e.g.; see User Manual for 
	  SAOimage, chapters 6 and 7, for complete information).

	- The descriptors must be in the format that SAOimage uses 
	  (capitals, parentheses, commas, no extra spaces).

	- Each descriptor must begin in the second position of its 
	  line; the first position must be either blank or '-' (the 
	  latter indicating an exclude region).

	- If the input file is in physical coordinates, the first 
	  non-comment line must specify "PHYSICAL", beginning in the 
	  second position on the line.

If the input file is an SAOimage cursor file, SAOimage will satisfy all of these requirements automatically.

EXAMPLES

1) Convert the logical coordinates of an SAOimage cursor file into physical coordinates, for use in PROS.


xs> fixsaoreg
regions file to convert: arlac
output regions file with coordinates transformed: 
Writing regions output file: arlac_phy.reg

The input file, arlac.reg, is the SAOimage cursor file illustrated above, shown again here:

# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:38:12 1994
# shape x, y, [x dimension, y dimension], [angle]
 CIRCLE(291,549,7.81)

The output file is arlac_phy.reg:

# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:43:46 1994
# shape x, y, [x dimension, y dimension], [angle]
 PHYSICAL
## converted from LOGICAL, for export from SAOimage
## CIRCLE(291,549,7.81)
 CIRCLE(2328.00,4392.00,62.480)


2) Convert the physical coordinates of a specially prepared PROS region descriptor file into logical coordinates for input into SAOimage.

xs> fixsaoreg
regions file to convert: p_arlac
output regions file with coordinates transformed: arlac_sao.reg
Writing regions output file: arlac_sao.reg

The input file, p_arlac.reg, is the other one illustrated in the FULL DESCRIPTION above (and is equivalent to the output of Example 1):

# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:43:46 1994
# shape x, y, [x dimension, y dimension], [angle]
 PHYSICAL
 CIRCLE(2328,4392,62.48)

The output file, arlac_sao.reg, is this:

# xdata$rh110267n00.qp[bl=8] - XRT/HRI PSF AR LAC
# Fri Jun  3 21:43:46 1994
# shape x, y, [x dimension, y dimension], [angle]
#* LOGICAL
##   converted from PHYSICAL, for input to SAOimage
## CIRCLE(2328.00,4392.00,62.480)
 CIRCLE(291.00,549.00,7.810)

TIME REQUIREMENTS

For simple regions, the conversion takes a few seconds.

RESTRICTIONS

Only a subset of the region descriptor language is accepted, and the syntax is less permissive than that of the full language.

BUGS

The default extension on the output file is _phy.reg, even if the output file is in logical coordinates.

SEE ALSO

User Manual for SAOimage, Chapter 6 (Graphics cursors and cursor mode in SAOimage) and Chapter 7 (SAOimage cursor regions)

Documentation on region filtering (help regions ) for a description of the spatial filter user interface.

Documentation on coordinates (help coords , help regcoords ) for a description of PROS coordinate systems and conventions.


Source Code · Search Form · STSDAS