SAOImage DS9

Smoothing and contouring

Smoothing

DS9's smoothing algorithms use a kernel with two parameters, radius r and kernel size k. The kernel width is 2k+1, and r must be less than or equal to k.

Kernels supported are the boxcar (width 2r+1), tophat (width 2r+1) and gaussian with σ = r/2, f(x,y) = 1 / 2 π sigma^2 exp(-x^2 + y^2/ 2 σ^2 )

Tiled frames showing unsmoothed and smoothed data

Command: smooth yes|no

Menu: Analysis - Smooth

Description: Smooths the data. Deselecting this removes the smoothing.

Command: smooth open

Menu: Analysis - Smooth Parameters

Description: Open Smooth Parameters dialog

Smooth Parameters dialog

Command: smooth close

Menu: Analysis - Smooth Parameters - Close

Description: Close the dialog

Command: -

Menu: Analysis - Smooth Parameters - Apply

Description: smooths the data, according to parameters which depend on the smoothing function type.

Command: smooth function boxcar|tophat|gaussian

Menu: Analysis - Smooth Parameters - Function

GUI Default: Edit - Preferences - Smooth - Function

Description: can be Boxcar, Tophat, Gaussian or Elliptical Gaussian.

Command: smooth radius [value]

Menu: Analysis - Smooth Parameters - Boxcar - Radius

Description: define the diameter (2r+1) of the square boxcar smoothing kernel.

Command: smooth radius [value]

Menu: Analysis - Smooth Parameters - Tophat - Radius

Description: define the diameter (2r+1) of the circular tophat smoothing kernel.

Command: -

Menu: Analysis - Smooth Parameters - Gaussian - Radius, Sigma

Description: define the diameter (2r+1) of the region smoothed, and the sigma of the gaussian to use.

Command: smooth angle|radius|radiusminor|sigma|sigmaminor [value]

Menu: Analysis - Smooth Parameters - Elliptical Gaussian - Angle, Major Radius, Minor Radios, Major Sigma, Minor Sigma

Description: define the equivalentparameters for an elliptical gaussian, including the angle of the major axis to the X axis.

Command: smooth no

Menu: Analysis - Smooth Parameters - Clear

Description: removes the smoothing

Contours

DS9 can create and display contours as an overlay on an image. The Analysis Contours menu is used to display contours. To create, copy, paste, and configure contours, use the Analysis Contour Parameters menu.

Contouring applied to smoothed data from earlier example

DS9's contour algorithm was taken from HEASOFT FV; the author is unknown.

Command: contour yes|no

Menu: Analysis - Contours

Description: Draws contours on the main image.

Command: contour open|close

Menu: Analysis - Contour Parameters

Description: Control the contour generation from the contour parameters dialog.When creating a new contour, a dialog box appears, in which the user selects the number of contour levels, smoothness, and the distribution of the contours.

Appearance of the contours is controlled with

Command: contour color [value]

Menu: Analysis - Contour Parameters - Color

GUI Default: Edit - Preferences - Contours - Color

Description: Controls the color of the contour lines. The menu version requires Apply.

Command: contour width [value]

Menu: Analysis - Contour Parameters - Width

GUI Default: Edit - Preferences - Contours - Width

Description: Controls the width of the contour lines.The menu version requires Apply

Command: contour dash yes|no

Menu: Analysis - Contour Parameters -Dash

Description: Controls whether the contour lines are dashed.The menu version requires Apply.

Command: -

Menu: Analysis - Contour Parameters - Apply

Description: Used to actually apply the changes. specified in Analysis - Contour Parameters.

Generation of the contours is affected by

Command: contour smooth [value]

Menu: Analysis - Contour Parameters - Contour - Smoothness

Description: Determines the densityof sampling (each pixel, each 2nd pixel, etc) for contour evaluation.

Command: contour nlevels [value]

Menu: Analysis - Contour Parameters - Contour - Levels

Description: Defines the number of contourlevels. A number from 1 to 10 is recommended; larger numbers will take longer to generate.

Command: contour scale [function]

Menu: Analysis - Contour Parameters - Scale

Description: Controls the spacing of the contour levels with the same options(linear, log, pow, squared, srt, asinh, sinh, histequ) as for the pixel intensity scaling.

Command: contour log exp [value]

Menu: Analysis - Contour Parameters - Scale - Log Exponent

Description: Controls the log exponent parameter in the contour scaling functions.

Command: contour limits [min] [max]

Menu: Analysis - Contour Parameters - Limits

Description: Controls the rangeof the contour levels with the same options (Min Max, ZScale, 99%,etc.) as for the pixel intensity scaling. By default the range of the data is used.

Command: contour mode minmax|zscale|zmax|[value]

Menu: Analysis - Contour Parameters - Limits -ZScale

Description: Controls the rangeof the contour levels with the same options (ZScale, 99%, etc.) as for the pixel intensity scaling.

Command: contour method smooth|block

Menu: Analysis - Contour Parameters - Method - Smooth/Block

GUI Default: Edit - Preferences - Contours - Method

Description: Chooses whether the smoothing (default) or blocking method is used togenerate the contours. Block blocks down the image by the smoothness factorbefore calculating the contours; Smooth smooths the image with a gaussian before calculating the contours.'block' mode is faster as the smoothing parameter increases. Conversely, 'smooth' mode is much slower as the smoothing parameter increases.

Command: contour scope global|local

Menu: Analysis - Contour Parameters - Scope - Global/Local

Description: Determines whether the range limitalgorithm is applied to all the data in memory or just the displayed region, as for the pixel intensity scaling.

Command: contour generate

Menu: Analysis - Contour Parameters - Generate

Description: Recalculate the contour levels with the current parameters

Command: contour levels [x1 x2 x3 ...]

Menu: Analysis - Contour Parameters - Levels

Description: Directly enter or edit the numerical contour levels.In the GUI, follow this with Apply (not Generate).

In the GUI, these generation options must be followed by

Command: -

Menu: Analysis - Contour Parameters - Apply

Description: Calculate the contours and actually apply the changes.

The following two options are used in conjunction with Frame - Go to Frame and Frame - Match Frames - WCS to copy contours from one frame to another - for example, to put X-ray contours on top of an optical image:

Command: -

Menu: Analysis - Contour Parameters - File - Copy Contours

Description: Puts a copy of the contour data from the current frame in a buffer.

Command: -

Menu: Analysis - Contour Parameters - File - Paste Contours

Description: Takes the buffered contour data and applies it to the current frame.

An example case:

File - Open loads an event file in Frame 1; adjust the scale and color etc.
Analysis - Contour Parameters - Apply to generate the contours, after adjusting Contour Parameters appropriately
Analysis - Imager Servers - SAO-DSS - Retrieve to get a matching optical image, which opens in Frame 2. Adjust scale and color as desired.
Frame - Go to Frame 1 to select the X-ray frame.
Frame - Match Frames - WCS to align the optical frame to the X-ray one.
Analysis - Contour Parameters - File - Copy Contours to select the contours from the X-ray image
Frame - Go to Frame 2 to select the optical frame.
Analysis - Contour Parameters - File - Paste Contours to overlay the X-ray contours on the optical image.

Command: contour clear

Menu: Analysis - Contour Parameters - Clear

Description: Will clear and reset any pasted contours in the current frame.

Command: contour save levels [filename]

Menu: Analysis - Contour Parameters - File - Save Contour Levels

Description: Writes a .lev file contaning the contour levels (not the contours themselves).

Command: contour load levels [filename]

Menu: Analysis - Contour Parameters - File - Load Contour Levels

Description: Reads a .lev file in and sets the contour levels accordingly (youstill need a Generate command to remake the contours).

Contour files

Command: contour save [filename] [coordsys] [skyframe]

Menu: Analysis - Contour Parameters - File - Save

Description: Writes a .ctr file contaningthe contours (the contours themselves, not just the levels).A contour file is an ASCII file containing a header, global properties, coordinate system, contour levels, and contour points.The Save dialog has an option to change the coordinate system of the saved contours. Example: 'contour save ds9.ctr wcs fk5'.

Command: contour load [filename]

Menu: Analysis - Contour Parameters - File - Load

Description: Reads a previously saved .ctr fileand displays it in the current frame. The Load GUI dialog has options to change the color, and line weight used to draw the contours.

Command: contour convert

Menu: Analysis - Contour Parameters - File - Convert to Polygons

Description: Creates a polygon region set from the current contours.There are now no DS9 contours defined (so Contour Parameters - File - Save will notdo anything) but instead Regions - List will list a set of polygon regionsand Regions - Save will save them as a DS9 region file.

The contour file format has a header:

# Contour file format: DS9 version 7.5

followed by one or more global properties lines, as in region files:

global color=green width=1 dash=1 dashlist=8 3

Global properties affect all contour levels unless a line level attribute is specified. The global keyword is first, followed by a list of keyword = value pairs. Multiple global property lines may be used.

For each contour file, it is important to specify the coordinate system used to interpret the contour points, i.e., to set the context in which the positions are interpreted. For this purpose, the following keywords are recognized:

        PHYSICAL                # pixel coords of original file using LTM/LTV
        IMAGE                   # pixel coords of current file
        FK4,B1950               # sky coordinate systems
        FK5,J2000               # sky coordinate systems
        ICRS                    # sky coordinate systems
        GALACTIC                # sky coordinate systems
        ECLIPTIC                # sky coordinate systems
        WCS                     # primary WCS
        WCSA                    # secondary WCS
        LINEAR                  # linear primary WCS

Each contour level is composed of a line value, line attributes and one or more contours. Line attributes are specified at the start of a new level and only affect contours within that level .

level=15.78775 color=pink width=2 dash=yes dashlist=2 2

Each contour is composed of one or more X,Y coordinates, with a deliminator of space or comma, starting with "(" and ending with ")". Contours are not closed.

        (202.4836468 47.22380226
         202.4833538 47.2239185
         202.4831634 47.22409874
         202.4829883 47.22428858)

Command:	smooth yes\|no
Menu:	Analysis - Smooth
Description:	Smooths the data. Deselecting this removes the smoothing.

Command:	smooth open
Menu:	Analysis - Smooth Parameters
Description:	Open Smooth Parameters dialog

Command:	smooth close
Menu:	Analysis - Smooth Parameters - Close
Description:	Close the dialog

Command:	-
Menu:	Analysis - Smooth Parameters - Apply
Description:	smooths the data, according to parameters which depend on the smoothing function type.

Command:	smooth function boxcar\|tophat\|gaussian
Menu:	Analysis - Smooth Parameters - Function
GUI Default:	Edit - Preferences - Smooth - Function
Description:	can be Boxcar, Tophat, Gaussian or Elliptical Gaussian.

Command:	smooth radius [value]
Menu:	Analysis - Smooth Parameters - Boxcar - Radius
Description:	define the diameter (2r+1) of the square boxcar smoothing kernel.

Command:	-
Menu:	Analysis - Smooth Parameters - Gaussian - Radius, Sigma
Description:	define the diameter (2r+1) of the region smoothed, and the sigma of the gaussian to use.

Command:	smooth angle\|radius\|radiusminor\|sigma\|sigmaminor [value]
Menu:	Analysis - Smooth Parameters - Elliptical Gaussian - Angle, Major Radius, Minor Radios, Major Sigma, Minor Sigma
Description:	define the equivalentparameters for an elliptical gaussian, including the angle of the major axis to the X axis.

Command:	smooth no
Menu:	Analysis - Smooth Parameters - Clear
Description:	removes the smoothing

Command:	contour yes\|no
Menu:	Analysis - Contours
Description:	Draws contours on the main image.

Command:	contour open\|close
Menu:	Analysis - Contour Parameters
Description:	Control the contour generation from the contour parameters dialog.When creating a new contour, a dialog box appears, in which the user selects the number of contour levels, smoothness, and the distribution of the contours.

Command:	contour color [value]
Menu:	Analysis - Contour Parameters - Color
GUI Default:	Edit - Preferences - Contours - Color
Description:	Controls the color of the contour lines. The menu version requires Apply.

Command:	contour width [value]
Menu:	Analysis - Contour Parameters - Width
GUI Default:	Edit - Preferences - Contours - Width
Description:	Controls the width of the contour lines.The menu version requires Apply

Command:	contour dash yes\|no
Menu:	Analysis - Contour Parameters -Dash
Description:	Controls whether the contour lines are dashed.The menu version requires Apply.

Command:	-
Menu:	Analysis - Contour Parameters - Apply
Description:	Used to actually apply the changes. specified in Analysis - Contour Parameters.

Command:	contour smooth [value]
Menu:	Analysis - Contour Parameters - Contour - Smoothness
Description:	Determines the densityof sampling (each pixel, each 2nd pixel, etc) for contour evaluation.

Command:	contour nlevels [value]
Menu:	Analysis - Contour Parameters - Contour - Levels
Description:	Defines the number of contourlevels. A number from 1 to 10 is recommended; larger numbers will take longer to generate.

Command:	contour scale [function]
Menu:	Analysis - Contour Parameters - Scale
Description:	Controls the spacing of the contour levels with the same options(linear, log, pow, squared, srt, asinh, sinh, histequ) as for the pixel intensity scaling.

Command:	contour log exp [value]
Menu:	Analysis - Contour Parameters - Scale - Log Exponent
Description:	Controls the log exponent parameter in the contour scaling functions.

Command:	contour limits [min] [max]
Menu:	Analysis - Contour Parameters - Limits
Description:	Controls the rangeof the contour levels with the same options (Min Max, ZScale, 99%,etc.) as for the pixel intensity scaling. By default the range of the data is used.

Command:	contour mode minmax\|zscale\|zmax\|[value]
Menu:	Analysis - Contour Parameters - Limits -ZScale
Description:	Controls the rangeof the contour levels with the same options (ZScale, 99%, etc.) as for the pixel intensity scaling.

Command:	contour method smooth\|block
Menu:	Analysis - Contour Parameters - Method - Smooth/Block
GUI Default:	Edit - Preferences - Contours - Method
Description:	Chooses whether the smoothing (default) or blocking method is used togenerate the contours. Block blocks down the image by the smoothness factorbefore calculating the contours; Smooth smooths the image with a gaussian before calculating the contours.'block' mode is faster as the smoothing parameter increases. Conversely, 'smooth' mode is much slower as the smoothing parameter increases.

Command:	contour scope global\|local
Menu:	Analysis - Contour Parameters - Scope - Global/Local
Description:	Determines whether the range limitalgorithm is applied to all the data in memory or just the displayed region, as for the pixel intensity scaling.

Command:	contour generate
Menu:	Analysis - Contour Parameters - Generate
Description:	Recalculate the contour levels with the current parameters

Command:	contour levels [x1 x2 x3 ...]
Menu:	Analysis - Contour Parameters - Levels
Description:	Directly enter or edit the numerical contour levels.In the GUI, follow this with Apply (not Generate).

Command:	contour clear
Menu:	Analysis - Contour Parameters - Clear
Description:	Will clear and reset any pasted contours in the current frame.

Command:	contour save levels [filename]
Menu:	Analysis - Contour Parameters - File - Save Contour Levels
Description:	Writes a .lev file contaning the contour levels (not the contours themselves).

Command:	contour load levels [filename]
Menu:	Analysis - Contour Parameters - File - Load Contour Levels
Description:	Reads a .lev file in and sets the contour levels accordingly (youstill need a Generate command to remake the contours).

Command:	contour save [filename] [coordsys] [skyframe]
Menu:	Analysis - Contour Parameters - File - Save
Description:	Writes a .ctr file contaningthe contours (the contours themselves, not just the levels).A contour file is an ASCII file containing a header, global properties, coordinate system, contour levels, and contour points.The Save dialog has an option to change the coordinate system of the saved contours. Example: 'contour save ds9.ctr wcs fk5'.

Command:	contour load [filename]
Menu:	Analysis - Contour Parameters - File - Load
Description:	Reads a previously saved .ctr fileand displays it in the current frame. The Load GUI dialog has options to change the color, and line weight used to draw the contours.