Synopsis
Create a region file to visualize cross match results
Syntax
xmatch_viz infile refsrcfile outfile legend [radius] [clobber] [verbose]
Description
'xmatch_viz' creates a DS9 region file to help users visually inspect astrometric cross-match results.
In the resulting output region file: Input sources are green colored circles and reference sources are magenta colored squares. A line is drawn between matching pairs to show the astrometric shift. Sources included in the final transformation solution are shown as filled, while unused sources are hollow.
The tool also generates a legend in the format of a DS9 illustrate mode save file that can be loaded into DS9 to identify the different symbols used in the visualization.
Example
$ wcs_match infile=src.fits refsrc=ref_src.fits wcsfile=acis.img outfile=out.xform logfile=out.log verbose=1 clob+ $ parse_wcs_match_log infile=src.fits refsrc=ref_src.fits logfile=out.log outfile=out.stats $ xmatch_viz infile=out.stats refsrc=ref_src.fits outfile=ds9.reg legend=ds9.seg $ ds9 acis.img -region format ds9 -region ds9.reg -illustrate load ds9.seg -catalog import fits out.stats
This example shows the 4 commands to run wcs_match, parse the log output, generate the crossmatch regions, and display the results.
Parameters
| name | type | ftype | def | min | max | units | reqd |
|---|---|---|---|---|---|---|---|
| infile | file | input | yes | ||||
| refsrcfile | file | input | yes | ||||
| outfile | file | output | yes | ||||
| legend | file | output | yes | ||||
| radius | real | 0.5 | 0 | arcsec | |||
| clobber | boolean | no | |||||
| verbose | integer | 1 | 0 | 5 |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
Input crossmatch table
The table containing match results (e.g., from parse_wcs_match_log).
Parameter=refsrcfile (file required filetype=input)
Input reference source list
Parameter=outfile (file required filetype=output)
Output DS9 region file name
Parameter=legend (file required filetype=output)
Output legend illustration
The legend file is a DS9 illustrate mode save file. It must be loaded using the
-illustrate load
command.
Parameter=radius (real default=0.5 min=0 units=arcsec)
The radius for the output regions
Parameter=clobber (boolean default=no)
Overwrite existing files?
Parameter=verbose (integer default=1 min=0 max=5)
Tool verbosity.
Helpful Hints
Regions are Locked
The region file has been setup so that the regions cannot be resized, repositioned, nor rotated. This is to prevent accidental edits. Regions can still be deleted.
Legend
The legend is provided in Illustrate mode and will remain fixed in the upper left corner of the display. To disable the legend, go to Edit → Illustrate. Then uncheck Illustrate → Show.
Groups
The regions have had "tags" applied to them to group them together into the following categories:
- All_Input: This group includes all the input sources.
- All_Reference: This group include all the reference sources.
- Input_Matched: This group includes all the input sources that are matched to a reference source but were not included in the final transform solution.
- Input_Unmatched: This group includes all the input sources that were not matched to reference sources.
- Input_Used: This group includes all the input sources that are matched to a reference source and were included in the final transform solution.
- Reference_Matched: This group includes all the reference sources that are matched to an input source but were not included in the final transform solution.
- Reference_Unmatched: This group includes all the reference sources that were not matched to input sources.
- Reference_Used: This group includes all the references sources that are matched to an input source and were included in the final transform solution.
Users can access the list of region groups by going to Region → Groups. Selecting a group from the list will select all the sources with that tag applied. This can be especially helpful to do something like delete all the unmatched reference sources. Simply select the "Reference_Unmatch" group and press the Delete key.
Changing source Properties
Region groups also make it easy to adjust the properties of regions. For example to change the font size simply select the region group (e.g. All_Input) and then go to Region → Font and select the desired font size/properties. The same technique can be use to change the color of the regions (Region → Color)
Multimatch
If wcs_match was run with multimatch=yes, there may be multiple matches between input sources and reference sources.
Catalog
Loading the cross match table (i.e. the output from the parse_wcs_match_log tool) into ds9 together with the regions makes it easier to inspect the cross matches. Clicking on the sources in the Catalog table will pan the image display to the location of the source.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.
Bugs
See the bug pages on the CIAO website for an up-to-date listing of known bugs.
Refer to the CIAO bug pages for an up-to-date listing of known issues.
See Also
- tools::coordinates
- fine_astro, reproject_aspect, reproject_events, sso_freeze, wcs_match, wcs_update