astropy:docs

- Index
- Modules

### Navigation

- imexam v0.5 »

# ds9

class `imexam.ds9_viewer.``ds9`(target=None, path=None, wait_time=5, quit_ds9_on_del=True)

  Bases: `object`

  A class which controls all interactions between the user and the ds9 window

  The ds9() contructor takes a ds9 target as its main argument. If none is given, then a new window will be opened.

  DS9’s xpa access points are documented in the reference manual, but the can also be returned to the user with a call to xpaset.

  http://hea-www.harvard.edu/saord/ds9/ref/xpa.html

  Parameters:

  target: string, optional

  > the ds9 target name or id (default is to start a new instance)

  path : string, optional

  > path of the ds9

  wait_time : float, optional

  > waiting time before error is raised

  quit_ds9_on_del : boolean, optional

  > If True, try to quit ds9 when this instance is deleted.

  Attributes

  wait_time: float | The waiting time before error is raised
  path: string | The path to the DS9 executable
  _xpa_name: string | The value in XPA_METHOD, the name of the DS9 window
  _quit_ds9_on_del: boolean | Determine whether to quit ds9 when object goes out of scope.
  _ds9_unix_name: string | The full path filename to the unix socket, only if unix sockets are being used with local
  _need_to_purge: boolean | whenever there are unix socket directories which need to be purged when the object goes out of scope
  _tmpd_name: string | The full path name to the unix socket file on the local system
  _filename: string | The name of the image that’s currently loaded into DS9
  _ext: int | Extension of the current image that is loaded. If one extension of an MEF file is loaded this will be 1 regarless of the extension that was specified (because DS9 and the XPA now see it as a single image and header)
  _extname: string | If available, the EXTNAME of the MEF extension that is loaded, taken from the current data header
  _extver: int | If available, the EXTVER of the MEF extension that is loaded, taken from the current data header
  _ds9_process: pointer | Points to the ds9 process id on the system, returned by Popen, whenever this module starts DS9
  _mef_file: boolean | The file is a multi-extension fits file
  _iscube: bookean | The file is a multiextension fits file, and one of the extensions contains at least 1 additional extension (3D or more)
  _numaxis: int | number of image planes, this is NAXIS
  _naxis: tuple | specific image plane displayed, defaulted to 1 image plane, most relevant to cube fits files

  Notes

  I think this is a quirk in the XPA communication. The xpans, and XPA prefer to have all connections be of the same type. DS9 defaults to creating an INET connection. In some cases, if no IP address can be found for the computer, the startup can hang. In these cases, a local connection is preferred, which uses a unix filename for the socket.

  The problem arises that if the user already has DS9 windows running, that were started by default, the nameserver is only listening for the default socket type (inet) and not local. There are also cases where the machine running this code does not have xpa installed, so there is no xpans (nameserver) to run and keep track of the open connections. In that case, the user needs to provide this init with the name of the socket in their window (in XPA_METHOD) in order to create the connection.

  Methods Summary

  `alignwcs`([on]) | align wcs
  `blink`([blink, interval]) | Blink frames
  `clear_contour`() | clear contours from the screen
  `close`() | close the window and end connection
  `cmap`([color, load, invert, save, filename]) | Set the color map table to something else, using a defined list of options
  `colorbar`([on]) | turn the colorbar on the bottom of the window on and off
  `contour`([on, construct]) | show contours on the window
  `contour_load`(filename) | load a contour file into the window
  `crosshair`([x, y, coordsys, skyframe, ...]) | Control the position of the crosshair in the current frame, crosshair mode is turned on automatically
  `cursor`([x, y]) | move the cursor in the current frame to the specified image pixel; selected regions will also be moved
  `disp_header`() | Display the header of the current image to a DS9 window
  `frame`([n]) | convenience function to change or report frames
  `get`(param) | XPA get method to ds9 instance which returns received string
  `get_data`() | return a numpy array of the data displayed in the current frame
  `get_filename`() | return the filename currently on display
  `get_frame_info`() | return more explicit information about the data displayed in the current frame
  `get_header`() | return the current fits header as a string or None if there’s a problem
  `get_slice_info`() | return the slice tuple that is currently displayed
  `get_viewer_info`() | Return a dictionary of information about all frames which are loaded with data
  `grid`([on, param]) | convenience to turn the grid on and off, grid can be flushed with many more options
  `hideme`() | lower the ds9 window
  `iscube`() | return information on whether a cube image is displayed in the current frame
  `load_fits`([fname, extver, extname]) | convenience function to load fits image to current frame
  `load_mef_as_cube`([filename]) | Load a Mult-Extension-Fits image into one frame as an image cube
  `load_mef_as_multi`([filename]) | Load a Mult-Extension-Fits image into multiple frames
  `load_region`(filename) | Load regions from a file which uses ds9 standard formatting
  `load_rgb`(red, green, blue[, scale, lockwcs]) | load 3 images into an RGBimage frame
  `make_region`(infile[, labels, header, ...]) | make an input reg file with [x,y,comment] to a DS9 reg file, the input file should contains lines with x,y,comment
  `mark_region_from_array`(input_points[, ...]) | mark ds9 regions regions given an input list of tuples, a convienence function, you can also use set_region
  `match`([coordsys, frame, crop, fslice, ...]) | match all other frames to the current frame
  `nancolor`([color]) | set the not-a-number color, default is red
  `panto_image`(x, y) | convenience function to change to x,y physical image coordinates
  `panto_wcs`(x, y[, system]) | pan to wcs location coordinates in image
  `readcursor`() | returns image coordinate postion and key pressed,
  `rotate`([value, to]) | rotate the current frame (in degrees), the current rotation is printed with no params
  `run_inet_ds9`() | start a new ds9 window using an inet socket connection
  `save_regions`([filename]) | save the regions in the current window to a DS9 style regions file
  `save_rgb`([filename]) | save an rgbimage frame as an MEF fits file
  `scale`([scale]) | The default zscale is the most widely used option
  `set`(param[, buf]) | XPA set method to ds9 instance
  `set_iraf_display`() | Set the environemnt variable IMTDEV to the socket address of the current imexam.ds9 instance.
  `set_region`([region_string]) | display a region using the specifications in region_string
  `show_commands`() | print the available XPA commands
  `showme`() | raise the ds9 window
  `showpix`([close]) | display the pixel value table, close window when done
  `snapsave`([filename, format, resolution]) | create a snap shot of the current window and save in specified format.
  `valid_data_in_viewer`() | return bool if valid file or array is loaded into the viewer
  `view`(img) | Display numpy image array to current frame
  `zoom`([par]) | zoom using the specified command in par
  `zoomtofit`() | convenience function for zoom

  Methods Documentation

  `alignwcs`(on=True)

    align wcs

    Parameters:

    on: bool

    > Align the images using the WCS in their headers

  `blink`(blink=True, interval=None)

    Blink frames

    Parameters:

    blink: bool, optional

    > Set to True to start blinking the frames which are open

    interval: int

    > Set interval equal to the length of pause for blinking

    Notes

    blink_syntax=
      Syntax: blink [true|false] [interval <value>]
  `clear_contour`()

    clear contours from the screen

  `close`()

    close the window and end connection

  `cmap`(color=None, load=None, invert=False, save=False, filename='colormap.ds9')

    Set the color map table to something else, using a defined list of options

    Parameters:

    color: string

    > color must be set to one of the available DS9 color map names

    load: string, optional

    > set to the filename which is a valid colormap lookup table valid contrast values are from 0 to 10, and valid bias values are from 0 to 1

    invert: bool, optional

    > invert the colormap

    save: bool, optional

    > save the current colormap as a file

    filename: string, optional

    > the name of the file to save the colormap to

  `colorbar`(on=True)

    turn the colorbar on the bottom of the window on and off

    Parameters:

    on: bool

    > Set to True to turn on the colorbar, False to turn it off

  `contour`(on=True, construct=True)

    show contours on the window

    Parameters:

    on: bool

    > Set to true to turn on contours

    construct: bool, optional

    > Will open the contour dialog box which has more options

  `contour_load`(filename)

    load a contour file into the window

    Parameters:

    filename: string

    > The name of the file with the contour level defined

  `crosshair`(x=None, y=None, coordsys='physical', skyframe='wcs', skyformat='fk5', match=False, lock=False)

    Control the position of the crosshair in the current frame, crosshair mode is turned on automatically

    Parameters:

    x: string or int

    > The value of x is converted to a string for the call to XPA, use a value here appropriate for the skyformat you choose

    y: string or int

    > The value of y is converted to a string for the call to XPA, use a value here appropriate for the skyformat you choose

    coordsys: string, optional

    > The coordinate system your x and y are defined in

    skyframe: string, optional

    > If skyframe has “wcs” in it then skyformat is also sent to the XPA

    skyformat: string, optional

    > Used with skyframe, specifies the format of the coordinate which were given in x and y

    match: bool, optional

    > If set to True, then the wcs is matched for the frames

    lock: bool, optional

    > If set to True, then the frame is locked in wcs

  `cursor`(x=None, y=None)

    move the cursor in the current frame to the specified image pixel; selected regions will also be moved

    Parameters:

    x: int

    > pixel location x coordinate to move to

    y: int

    > pixel location y coordinate to move to

    x and y are converted to strings for the call

  `disp_header`()

    Display the header of the current image to a DS9 window

  `frame`(n=None)

    convenience function to change or report frames

    Parameters:

    n: int, string, optional

    > The frame number to open or change to. If the number specified doesn’t exist, a new frame will be opened If nothing is specified, then the current frame number will be returned. The value of n is converted to a string before passing to the XPA

    Examples

    frame(1) sets the current frame to 1 frame(“last”) set the current frame to the last frame frame() returns the number of the current frame frame(“new”) opens a new frame frame(3) opens frame 3 if it doesn’t exist already, otherwise goes to frame 3

  `get`(param)

    XPA get method to ds9 instance which returns received string

    Parameters: | param : parameter string (eg. “fits” “regions”)

    Notes

    This function is linked with the Cython implementation get(param)

  `get_data`()

    return a numpy array of the data displayed in the current frame

    Notes

    This is the data array that the imexam() function from connect() uses for analysis

    astropy.io.fits stores data in row-major format. So a 4d image would be [NAXIS4, NAXIS3, NAXIS2, NAXIS1] just the one image is retured in the case of multidimensional data, not the cube

  `get_filename`()

    return the filename currently on display

    This function will check if there is already a filename saved. It’s possible that the user can connect to a ds9 window with no file loaded and then ask for the data file name after loading one through the ds9 menu options. This will poll the private filename and then try and set one if it’s empty.

  `get_frame_info`()

    return more explicit information about the data displayed in the current frame

  `get_header`()

    return the current fits header as a string or None if there’s a problem

  `get_slice_info`()

    return the slice tuple that is currently displayed

  `get_viewer_info`()

    Return a dictionary of information about all frames which are loaded with data

    Notes

    Consider adding a loop to verify that all the frames still exist and the user has not deleted any through the gui.

  `grid`(on=True, param=False)

    convenience to turn the grid on and off, grid can be flushed with many more options

    Parameters:

    on: bool, optional

    > Will turn the grid overlay on in the current frame

    param: bool, optional

    > Will open the parameter dialog in DS9

  `hideme`()

    lower the ds9 window

  `iscube`()

    return information on whether a cube image is displayed in the current frame

  `load_fits`(fname='', extver=1, extname=None)

    convenience function to load fits image to current frame

    Parameters:

    fname: string, optional

    > The name of the file to be loaded. You can specify the full extension in the name, such as filename_flt.fits[sci,1] or filename_flt.fits[1]

    extver: int, optional

    > The extension to load (EXTVER in the header)

    extname: string, optional

    > The name (EXTNAME in the header) of the image to load

    Notes

    To tell ds9 to open a file whose name or path includes spaces, surround the path with “{...}”, e.g.

    % xpaset -p ds9 file “{foo bar/my image.fits}”

    This is assuming that the image loads into the current or next new frame, watch the internal file and ext values because the user can switch frames through DS9 app itself

    XPA needs to have the absolute path to the filename so that if the DS9 window was started in another directory it can still find the file to load. arg.

  `load_mef_as_cube`(filename=None)

    Load a Mult-Extension-Fits image into one frame as an image cube

  `load_mef_as_multi`(filename=None)

    Load a Mult-Extension-Fits image into multiple frames

  `load_region`(filename)

    Load regions from a file which uses ds9 standard formatting

    Parameters:

    filename: string

    > The file containing the DS9 style region description

  `load_rgb`(red, green, blue, scale=False, lockwcs=False)

    load 3 images into an RGBimage frame

    Parameters:

    red: string

    > The name of the fits file which will be loaded into the red channel

    green: string

    > The name of the fits file which will be loaded into the green channel

    blue: string

    > The name of the fits file which will be loaded into the blue channel

    scale: bool

    > If True, then each image will be scale with zscale() after loading

    lockwcs: bool

    > If True, then the image positions will be locked to each other using the WCS information in their headers

  `make_region`(infile, labels=False, header=0, textoff=10, size=5)

    make an input reg file with [x,y,comment] to a DS9 reg file, the input file should contains lines with x,y,comment

    Parameters:

    infile: str

    > input filename

    labels: bool

    > add labels to the regions

    header: int

    > number of header lines in text file to skip

    textoff: int

    > offset in pixels for labels

    size: int

    > size of the region type

    Notes

    only circular regions are supported currently

  `mark_region_from_array`(input_points, ptype='image', textoff=10, size=5)

    mark ds9 regions regions given an input list of tuples, a convienence function, you can also use set_region

    Parameters:

    input_points: a tuple, or list of tuples, or a string: (x,y,comment),

    ptype: string

    > the reference system for the point locations, image|physical|fk5

    size: int

    > the size of the region marker

    textoff: string

    > the offset for the comment text, if comment is empty it will not show

    Notes

    only circular regions are supported currently

  `match`(coordsys='wcs', frame=True, crop=False, fslice=False, scale=False, bin=False, colorbar=False, smooth=False, crosshair=False)

    match all other frames to the current frame

    Parameters:

    coordsys: string, optional

    > The coordinate system to use

    frame: bool, optional

    > Match all other frames to the current frame, using the set coordsys

    crop: bool, optional

    > Set the current image display area, using the set coordsys

    fslice: bool, optional

    > Match current slice in all frames

    scale: bool, optional

    > Match to the current scale for all frames

    bin: bool, optional

    > Match to the current binning for all frames

    colorbar: bool, optional

    > Match to the current colorbar for all frames

    smooth: bool, optional

    > Match to the current smoothing for all frames

    crosshair: bool, optional

    > Match the crosshair in all frames, using the current coordsys

    Notes

    You can only choose one of the options at a time, and the logic will select the first True option so set frame=False and something else in addition to your choice if you don’t want the default option.

  `nancolor`(color='red')

    set the not-a-number color, default is red

    Parameters:

    color: string

    > The color to use for NAN pixels

  `panto_image`(x, y)

    convenience function to change to x,y physical image coordinates

    Parameters:

    x: float

    > X location in physical coords to pan to

    y: float

    > Y location in physical coords to pan to

  `panto_wcs`(x, y, system='fk5')

    pan to wcs location coordinates in image

    Parameters:

    x: string

    > The x location to move to, specified using the given system

    y: string

    > The y location to move to

    system: string

    > The reference system that x and y were specified in, they should be understood by DS9

  `readcursor`()

    returns image coordinate postion and key pressed,

    Notes

    XPA returns strings of the form: u a 257.5 239

  `rotate`(value=None, to=False)

    rotate the current frame (in degrees), the current rotation is printed with no params

    Parameters:

    value: float [degrees]

    > Rotate the current frame {value} degrees If value is 0, then the current rotation is printed

    to: bool

    > Rotate the current frame to the specified value

  `run_inet_ds9`()

    start a new ds9 window using an inet socket connection

    Notes

    It is given a unique title so it can be identified later.

  `save_regions`(filename=None)

    save the regions in the current window to a DS9 style regions file

    Parameters:

    filename: string

    > The nameof th file to which the regions displayed in the current window are saved If no filename is provided then it will try and save the regions to the name of the file in the current display with _regions.txt appended

    > If a file of that name already exists on disk it will no attempt to overwrite it

  `save_rgb`(filename=None)

    save an rgbimage frame as an MEF fits file

    Parameters:

    filename: string

    > The name of the output fits image

  `scale`(scale='zscale')

    The default zscale is the most widely used option

    Parameters:

    scale: string

    > The scale for ds9 to use, these are set strings of [linear|log|pow|sqrt|squared|asinh|sinh|histequ]

    Notes

    The xpa doesn’t return an error if you set an unknown scale, it just doesn’t do anything, this is true for all the xpa calls

  `set`(param, buf=None)

    XPA set method to ds9 instance

    Notes

    This function is linked with the Cython implementation

    set(param, buf=None) param : parameter string (eg. “fits” “regions”) buf : aux data string (sometime string needed to be ended with CR)

  `set_iraf_display`()

    Set the environemnt variable IMTDEV to the socket address of the current imexam.ds9 instance.

    Notes

    For example, your pyraf commands will use this ds9 for display.

    TODO: Not sure this is still needed.

  `set_region`(region_string='')

    display a region using the specifications in region_string

    Parameters:

    region_string: string

    > Should take the form of a region string that DS9 is expecting

    Examples

    set_region(“physical ruler 200 300 200 400”) set_region(“line 0 400 3 400 #color=red”)

  `show_commands`()

    print the available XPA commands

  `showme`()

    raise the ds9 window

  `showpix`(close=False)

    display the pixel value table, close window when done

    Parameters:

    close: bool, optional

    > If set to True, then the pixel table dialog window is closed

  `snapsave`(filename=None, format=None, resolution=100)

    create a snap shot of the current window and save in specified format.

    Parameters:

    filename: str, optional

    > filename of output image, the extension in the filename can also be used to specify the format If no filename is specified, then the filename will be constructed from the name of the currently displayed image with _snap.jpg appended.

    format: str, optional

    > available formats are fits, eps, gif, tiff, jpeg, png If no format is specified the filename extension is used

    resolution: int, optional

    > 1 to 100, for jpeg images

  `valid_data_in_viewer`()

    return bool if valid file or array is loaded into the viewer

  `view`(img)

    Display numpy image array to current frame

    Parameters:

    img: numpy array

    > The array containing data, it will be forced to numpy.array()

  `zoom`(par='to fit')

    zoom using the specified command in par

    Parameters:

    par: string

    > it can be a number (ranging 0 to 8 effectively), and successive calls continue zooming in the same direction it can be two numbers ‘4 2’, which specify zoom on different axis if can be to a specific value ‘to 8’ or ‘to fit’ it can be ‘open’ to open the dialog box it can be ‘close’ to close the dialog box (only valid if the box is already open)

    Examples

    zoom(“0.1”)

  `zoomtofit`()

    convenience function for zoom