NAME

ahmkregion - Create region files showing the field of view of all Hitomi instruments

USAGE

ahmkregion instrume ra dec roll

DESCRIPTION

The ahmkregion task creates special region files showing the field of view of each of the Hitomi instruments in each of the standard coordinate systems described in the telescope definition (teldef) calibration files. The standard coordinate systems are referred to as ACT (ACTive), DET (DETector), FOC (FOCal plane), and SKY. This task creates region files for a single instrument, or one region file containing the field of view of all instruments. These region files may be used for event filtering, or in programs such as ds9 or ximage.

The ahmkregion task also creates region files containing labels for the instrument and instrument segments (e.g., CCD units for the SXI), and a script for reading the region files into ximage.

Note that SXS region files made by ahmkregion should not be used as input to aharfgen (or ahsxtarfgen). This is because ahmkregion creates DET coordinate regions for SXS that have overlapping pixel regions.

PARAMETERS

instrume = SXS [string SXS|SXI|HXI1|HXI2|SGD1|SGD2|ALL]
Name of instrument to be used. If set to a single instrument, only the region file for that instrument is created. When 'instrume=ALL', the script creates individual instrument region files that are concatenated to make a unified region file; the individual instrument region files are then deleted. To save separate instrument region files, use the 'outroot' parameter (see below).

ra = 50 [double]
The right ascension [decimal degrees] of the nominal pointing. This must be within the range 0 <= ra <= 360 degrees.

dec = 50 [double]
The declination [decimal degrees] of the nominal pointing. This must be within the range -90 <= dec <= +90 degrees.

roll = 90 [double]
The roll angle [decimal degrees] between the SKY and FOC coordinate systems. The roll angle is defined to correspond to a rotation about the center of the SKY system and is measured counterclockwise from the positive SKY Y axis to the positive FOC Y axis.

(teldeffile = CALDB) [string CALDB|file name]
Name of the teldef calibration file, which specifies the coordinate systems and transformation properties. If the parameter is set to CALDB, the file is read from the calibration database, CalDB. If a file name is provided, the TELESCOP keyword in the file must be HITOMI and the INSTRUME keyword in the file must match exactly the values of the 'instrume' parameter(s). Note: if 'instrume=ALL', then the only acceptable value for 'teldeffile' is CALDB, since multiple teldef files are read.

(inregion = NONE) [string]
By default, ahmkregion starts from a standard region file matched to the field of view of the instrument. The 'inregion' parameter allows for user-defined region files.

(outroot = NONE) [string]
Default names for the output region files are INST.SYS.box.reg, where INST is the instrument name and SYS is the three-letter coordinate system name. The 'outroot' parameter allows for user-defined output region file names. This option is used when there is a need to preserve individual instrument region files when running ahmkregion with 'instrume=ALL'.

(pixlist = 0-35) [string]
List of SXS pixels to be included in the output region files. This is a comma-separated list for which the user can specify either single pixel numbers or a range of pixel numbers. This parameter is ignored if 'instrume' is not set to SXS.

(outtextregion = yes) [boolean yes|no]
By default, ahmkregion outputs two sets of region files: simple box-style regions with no text labels (INST.SYS.box.reg) and box-style regions with text labels (INST.SYS.text.reg). Setting 'outtextregion=no' suppresses the output of second set.

(outxco = yes) [boolean yes|no]
By default, ahmkregion creates several instruction scripts (INST.SYS.xco) to read the region files into the program ximage. Setting 'outxco=no' suppresses the production of these scripts.

(cleanup = yes) [boolean yes|no]
Delete temporary files if 'cleanup=yes'.

(clobber = yes) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]
Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]
Records task parameters in HISTORY.

EXAMPLES

  1. Run ahmkregion for a single instrument with default settings.
    2.    ahmkregion instrume=SXI ra=185.0 dec=-42.1 roll=35.0 teldeffile=CALDB
  2. Run ahmkregion with 'instrume=ALL' and suppress creation of text region files and xco scripts. 
    3.    ahmkregion instrume=ALL ra=185.0 dec=-42.1 roll=35.0  outtextregion=no outxco=no

  3. Run ahmkregion with 'instrume=SXS' and a range of pixel values. In this example, the user chooses pixel 0, pixel 2, and pixels 4, 5, 6, and 7. 
    4.    ahmkregion instrume=SXS ra=25.0 dec=-42.1 roll=35.0 pixlist="0,2,4-7"

SEE ALSO

coordpnt

LAST MODIFIED

August 14, 2023