NAME

USAGE

DESCRIPTION

'ahmkregion' 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: ACTive, DETector, FOCal plane and SKY. The tool creates region files for a single instrument or one region file containing the field of view of all instruments. These files may be used for event filtering or in programs such as 'DS9' or 'ximage'.

'ahmkregion' may also create region files containing labels for the instrument and instrument segments and a script for reading the region files into 'ximage'

PARAMETERS

instrume [string]

Name of Hitomi instrument to be used. This must be one of SXS, SXI, HXI1, HXI2, SGD1, SGD2, or ALL. If set to one of the instrument, only the region file for that instrument is created. When 'instrume=ALL', the script creates individual instrument region files which are concatenated to make the unified region file and then deleted. To save separate instrument region files, use the 'outroot' parameter (see below).

ra [real]

The Right Ascension in decimal degrees of the nominal pointing. This must be in the range 0 <= ra <= 360 degrees.

dec [real]

The declination in decimal degrees of the nominal pointing, This must be in the range -90 <= dec <= +90 degrees.

roll [real]

The roll angle in decimal degrees between the SKY coordinate system and the FOC coordinate system. The roll angle is 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]

Name of the Telescope Definition (TelDef) calibration data base (CALDB) file, which specifies the coordinate systems and transformation properties. If the parameter is set to CALDB, the default, the file is read from the calibration database. 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 parameters. Note that if 'instrume=ALL', then the only acceptable value for 'teldeffile' is CALDB, since multiple Hitomi 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. 'inregion' 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 the three-letter coordinate system name. 'outroot' 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 with a script with 'instrume=ALL'.

(pixlist = 0-35) [string]

List of SXS pixels to be included in 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 SXS.

(outtextegion = yes) [boolean]

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]

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]

Delete temporary files ([yes]/no)

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

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]

Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]

Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]

Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string]

Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

1. Run ahmkregion for a single instrument with default settings

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.

ahmkregion instrume=ALL ra=185.0 dec=-42.1 roll=35.0  outtextegion=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.

ahmkregion instrume=SXS ra=25.0 dec=-42.1 roll=35.0 pixlist=0,2,4-7

SEE ALSO

LAST MODIFIED