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
path : string, optional
wait_time : float, optional
quit_ds9_on_del : boolean, optional
|
---|
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
align wcs
Parameters: | on: bool
|
---|
Blink frames
Parameters: | blink: bool, optional
interval: int
|
---|
Notes
Set the color map table to something else, using a defined list of options
Parameters: | color: string
load: string, optional
invert: bool, optional
save: bool, optional
filename: string, optional
|
---|
turn the colorbar on the bottom of the window on and off
Parameters: | on: bool
|
---|
show contours on the window
Parameters: | on: bool
construct: bool, optional
|
---|
load a contour file into the window
Parameters: | filename: string
|
---|
Control the position of the crosshair in the current frame, crosshair mode is turned on automatically
Parameters: | x: string or int
y: string or int
coordsys: string, optional
skyframe: string, optional
skyformat: string, optional
match: bool, optional
lock: bool, optional
|
---|
move the cursor in the current frame to the specified image pixel; selected regions will also be moved
Parameters: | x: int
y: int
x and y are converted to strings for the call |
---|
convenience function to change or report frames
Parameters: | n: int, string, optional
|
---|
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
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)
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
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.
return more explicit information about the data displayed in the current frame
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.
convenience to turn the grid on and off, grid can be flushed with many more options
Parameters: | on: bool, optional
param: bool, optional
|
---|
convenience function to load fits image to current frame
Parameters: | fname: string, optional
extver: int, optional
extname: string, optional
|
---|
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 a Mult-Extension-Fits image into one frame as an image cube
Load regions from a file which uses ds9 standard formatting
Parameters: | filename: string
|
---|
load 3 images into an RGBimage frame
Parameters: | red: string
green: string
blue: string
scale: bool
lockwcs: bool
|
---|
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
labels: bool
header: int
textoff: int
size: int
|
---|
Notes
only circular regions are supported currently
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
size: int
textoff: string
|
---|
Notes
only circular regions are supported currently
match all other frames to the current frame
Parameters: | coordsys: string, optional
frame: bool, optional
crop: bool, optional
fslice: bool, optional
scale: bool, optional
bin: bool, optional
colorbar: bool, optional
smooth: bool, optional
crosshair: bool, optional
|
---|
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.
set the not-a-number color, default is red
Parameters: | color: string
|
---|
convenience function to change to x,y physical image coordinates
Parameters: | x: float
y: float
|
---|
pan to wcs location coordinates in image
Parameters: | x: string
y: string
system: string
|
---|
returns image coordinate postion and key pressed,
Notes
XPA returns strings of the form: u a 257.5 239
rotate the current frame (in degrees), the current rotation is printed with no params
Parameters: | value: float [degrees]
to: bool
|
---|
start a new ds9 window using an inet socket connection
Notes
It is given a unique title so it can be identified later.
save the regions in the current window to a DS9 style regions file
Parameters: | filename: string
|
---|
save an rgbimage frame as an MEF fits file
Parameters: | filename: string
|
---|
The default zscale is the most widely used option
Parameters: | scale: string
|
---|
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
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 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.
display a region using the specifications in region_string
Parameters: | region_string: string
|
---|
Examples
set_region(“physical ruler 200 300 200 400”) set_region(“line 0 400 3 400 #color=red”)
display the pixel value table, close window when done
Parameters: | close: bool, optional
|
---|
create a snap shot of the current window and save in specified format.
Parameters: | filename: str, optional
format: str, optional
resolution: int, optional
|
---|
Display numpy image array to current frame
Parameters: | img: numpy array
|
---|
zoom using the specified command in par
Parameters: | par: string
|
---|
Examples
zoom(“0.1”)