filter region

Syntax:

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.

Case 1:

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

This means that there is an excluded box, followed by an included box. The region file looks like

   -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