mkregmap.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cxchelptopics SYSTEM "CXCHelp.dtd">
<cxchelptopics>
<ENTRY 
        context="tools" 
        key="mkregmap" 
        refkeywords="region map mask bin group stack" 
        seealsogroups="dmimgtools"
        displayseealsogroups="regiontools"
    >
    <SYNOPSIS>
       Create map from stack of input regions.
    </SYNOPSIS>
    <DESC>
        <PARA>
        The tool take an image and a stack of region descriptions.
        The regions can be multiple files, multiple rows in a single
        file, or a list individual shapes.
        The output image pixel values indicate which region each pixel is inside.
        If a pixel is inside more than one region, the last region number is
        used.        
        </PARA>
    </DESC>

     <QEXAMPLELIST>
        <QEXAMPLE>
          <SYNTAX>
            <LINE>
                % mkregmap img.fits "region1.fits,region2.fits,region3.fits" reg.map                 
            </LINE>
          </SYNTAX>
          <DESC>
            <PARA>
              Three region files are supplied as input using
              commas (",") to separate them.  The output
              map file will contain values 1, 2, or 3 if the pixels
              in the input image, img.fits, are inside any of those
              regions.  The outfile, reg.map, stores this information,
              and will have pixels equal to zero (0) if they are
              not included in any of the regions, or if the 
              input pixels were NaN.  We could also use the 
              "region(filename)" syntax
            </PARA>

<VERBATIM>
"region(region1.fits),region(region2.fits),region(region3.fits)"
</VERBATIM>

<PARA>
or use the "@stack_filename" syntax
</PARA>

<VERBATIM>
% cat my_region.lis
region1.fits
region2.fits
region3.fits
circle(3288,6778,100)
% mkregmap region=@my_region.lis
</VERBATIM>

 <PARA>
 Note: Users should be careful when using the "@" syntax with
 list files located in different directories.  The "@-" syntax
 may be need to suppress appending the directory name to the 
 stack elements.
 </PARA>


          </DESC>
        </QEXAMPLE>

        <QEXAMPLE>
          <SYNTAX>
            <LINE>
                % mkregmap img.fits "pgrid(4096,4096,0:1000:100,0:360:360)" pgrid.map
            </LINE>
          </SYNTAX>
          <DESC>
            <PARA>
              Here we use the polar-grid, "pgrid", stack syntax to create
              a set of 10 annuli, all centered at (4096,4096), with
              radii that go from 0 to 1000 pixels in 100 pixel steps.
            </PARA>
          </DESC>
        </QEXAMPLE>


        <QEXAMPLE>
          <SYNTAX>
            <LINE>% dmellipse img.fits out=ellipse.out fraction="lgrid(0.05:1.0:0.025)"</LINE>
            <LINE>% dmsort ellipse.out ellipse_sort.fits key=-component</LINE>
            <LINE>% mkregmap img.fits "ellipse_sort.fits[#row=igrid(1:100:1)]" ellipse.map</LINE>
          </SYNTAX>
          <DESC>
            <PARA>
    Here we start by using dmellipse to generate a set of ellipses which
    enclose from 5% to 100% of the flux in the input image.  We then
    reverse sort these based on the COMPONENT column value (ie in 
    descending order).  These are then fed 
    into mkregmap to create an elliptical-annulus map.  We sorted
    the values since the inner most region (5%) is typically fully enclosed
    by the larger fractions and since mkregmap uses the last region
    when regions overlap, we need it to be at the end of the stack.
            </PARA>
          </DESC>
        </QEXAMPLE>


        <QEXAMPLE>
          <SYNTAX>
            <LINE>% mkregmap xmm.fits @region.lis xmm.map coord="pos"</LINE>
          </SYNTAX>
          <DESC>
            <PARA>
            Not all images have a "sky" coordinate system that 
            the scripts can understand.  Some images likes those from
            XMM data products contain a "pos" coordinate system.
            </PARA>
            <PARA>
            Users can use dmlist with the "cols" option to see the
            coordinate axis name needed to use the script.
            </PARA>
          </DESC>
        </QEXAMPLE>


     </QEXAMPLELIST>

     <PARAMLIST>
        <PARAM name="infile" type="file" filetype="input" reqd="yes">
            <SYNOPSIS>
            Input image.
            </SYNOPSIS>
            <DESC>
           <PARA>
            Null and NaN pixels, as well as those pixels outside the
            image subspace will not be grouped.  Otherwise the
            pixel values are ignored, just the size and dimensions 
            of the image are used.
            </PARA>

          </DESC>
        </PARAM>

        <PARAM name="regions" type="string" reqd="yes" stacks="yes">
          <SYNOPSIS>
          Stack of regions
          </SYNOPSIS>
          <DESC>
            <PARA>
            Each region in the stack is assigned an ID, from 1 to N.
            The output image is set to the region ID if the pixel
            is inside the region.
            If multiple regions overlap, the last region in the stack
            will be used to set the group ID (highest region ID).            
            </PARA>          
          </DESC>

        </PARAM>


        <PARAM name="outfile" type="file" filetype="output" reqd="yes">
          <SYNOPSIS>
            Output map file
          </SYNOPSIS>
          <DESC>
            <PARA>
              The outfile is a map file containing integer pixel values.
              The pixel values indicate which pixels are grouped
              together by the algorithm.  A pixel value of 0 are pixels
              which are ungrouped (ie outside the image subspace).            
            </PARA>
          </DESC>
        </PARAM>


        <PARAM name="binimg" type="file" filetype="output">
          <SYNOPSIS>Optional, output binned image</SYNOPSIS>
          <DESC>
            <PARA>
                If the binimg file is specified, the script
                will use the input image and the output map file to
                create a binned version of the input image.
            </PARA>          
          </DESC>
        </PARAM>
        
        <PARAM name="coord" type="string" def="sky">
          <SYNOPSIS>Axis name to filter input image</SYNOPSIS>
            <DESC>
              <PARA>
              Not all images have a "sky" coordinate system.  For example
              XMM images typically have a  "pos" coordinate system.
              Users can use the dmlist command with the "cols" option
              to determine the column name to filter on.
              </PARA>            
            </DESC>
        </PARAM>

        <PARAM name="verbose" type="integer" def="1" min="0" max="5">
            <SYNOPSIS>
            Amount of chatter from the tool.
            </SYNOPSIS>
        </PARAM>
        <PARAM name="clobber" type="boolean" def="no">
            <SYNOPSIS>
            Delete outfile if it already exists?
            </SYNOPSIS>
        </PARAM>
    </PARAMLIST>

    <ADESC title="About Contributed Software">
      <PARA>
        This script is not an official part of the CIAO release but is
        made available as "contributed" software via the
        <HREF link="https://cxc.harvard.edu/ciao/download/scripts/">CIAO scripts page</HREF>.
        Please see this page for installation instructions.
      </PARA>
    </ADESC>

    <BUGS>
        <PARA>
            See the
            <HREF link="http://cxc.harvard.edu/ciao/bugs/index.html">CIAO
            website</HREF> for an up-to-date listing of known bugs.
        </PARA>
    </BUGS>
    <LASTMODIFIED>August 2023</LASTMODIFIED>
</ENTRY>
</cxchelptopics>