xsel > filter region <region>
This allows you to enter SAOIMAGE format region descriptor files. Multiple files are supported. The region parameter takes a list of files, which are added to the current list. If a file proceeded by a - in the list it is removed from the list. So to enter the regions reg1.flt, and reg2.flt, and remove the file reg.flt, give the command
xsel > filter region "reg1.flt reg2.flt -reg.flt"
Indirection with the @filename command is also allowed.
A very important point to note about the region filters is that they must either be in WCS or Physical coordinates. Regions created in Image coordinates will not work correctly if image binning is not 1.
Some care must be taken in entering multiple regions, if you wish to get the result you expect. First off, note that the extractor takes in only one region file, so Xselect cat's them all together before passing them to extract. Since the order of the regions is important, you need to know that Xselect cats them in the order that they appear in the input list, appending the second file to the first, and the third to the end of these two, ...
Each region specification is treated independently of the others. SAOimage has no syntax to specify AND/OR so each region stands on it's own. They are processed sequentially as the region file is read in, with the current region possibly overriding the previous selections. If the first region is an excluded region then the effect is to have an included region of the whole image inserted before any other region is processed.
Now, since that summary wasn't very understandable, let's do some examples with explanations.
Let's assume a 1000X1000 pixel image. 1 means the pixel is on, O means it is off.
An included box at 105,105 with a radius of 5,5. So, all the pixels
(110,100) 1111111111 1111111111 1111111111 1111111111 1111111111 1111111111 1111111111 1111111111 1111111111 1111111111 (100,100)
Now, if the same box was an excluded region then the exact opposite would happen.
(110,100) OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO OOOOOOOOOO (100,100)
with all the other pixels on.
An output from SISCLEAN is a collection of excluded points, so the image looks like...
1111111111111111111111111111111111111111111111111111111111111111111 1111111111111111111111111111111111111111111111111111111111111111111 1111111111111111111111111111111111111111111111111111111111111111111 111111111111111111111111O111111111111111111111111111111111111111111 11O1111111111111111111111111111111111111111111111111111111111111111 11111111111O1111111111111111111111111111111111111111111111111111111 1111111111111111111111111111111111111111111111111111111111111111111 1111111111111111111111111111111111111111111111111111111111111111111 1111111111111111111111111O11111111111111111111111111111111111111111 111111111111111111111111111111111111111O111111111111111111111111111 1111111111111111111111111111111111111111111111111111111111111111111 1111111111111111111111111111111111111111O11111111111111111111111111 11111111111111111111111111111111111111111O1111111111111111111111111
What happens when two regions overlap?
Two boxes with corners overlapping. If they are both included then...
0000000000000 0111100000000 0111111000000 0111111000000 0001111000000 0001111000000 0000000000000
The region file would look like
BOX( ) BOX( )
If they are both excluded then
1111111111111 1000011111111 1000000111111 1000000111111 1110000111111 1110000111111 1111111111111
The region file would look like
-BOX( ) -BOX( )
Now, if one is excluded and one is included, how should it look?
One way is
0000000000000 0111100000000 0110000000000 0110000000000 0000000000000 0000000000000 0000000000000
This means that the first box is the included box, and then there is an excluded box. The region file looks like
BOX( ) -BOX( )
The other way is
1111111111111 1000011111111 1001111111111 1001111111111 1111111111111 1111111111111 1111111111111
-BOX( ) BOX( )
So, the order is significant. The overall way of looking at region files is that if the first region is an excluded region then a dummy included region of the whole detector is inserted in the front. Then each region specification as it is processed overrides any selections inside of that region specified by previous regions. Another way of thinking about this is that if a previous excluded region is completely inside of a subsequent included region the excluded region is ignored.
HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public
Last modified: Tuesday, 10-Jan-2023 11:03:01 EST
The HEASARC welcomes your participation in a brief survey to capture how users access and utilize HEASARC data, software, and services. The outcome(s) of this survey will be used to guide, prioritize, and plan our activities and development in the coming years. It contains 20 questions, generally takes just a few minutes to complete, and your answers will remain totally anonymous. The survey is open until Dec 18, 2023. We thank you in advance for your valuable feedback.