Package library

ds9get([apt,] args...; kwds...) -> r::AbstractString
ds9get(T::Type, [apt,] args...; kwds...) -> r::T

Send a single XPA get command to SAOImage/DS9.

The command is made of arguments args... converted into strings and concatenated with separating spaces.

Optional argument T is to specify the type of value to extract from the answer of the command:

• If T is eltype(XPA.Reply), r is the un-processed answer of the command. The caller may use properties r.data, r.message, r.has_message, r.has_error etc. to deal with it. In all other cases, the answer is interpreted as an ASCII string, the so-called textual answer.

• If T is unspecified, the textual answer is returned without its trailing newline ('\n' character).

• If T is String, the textual answer is returned (without discarding any characters).

• If T is a scalar type, a value of this type is parsed in the textual answer and returned.

• If T is a tuple or vector type, the textual answer is split into words which are scanned for 0, 1, or more values according to the type(s) of the entries of T.

Optional argument apt is to specify another access-point to a SAOImage/DS9 server than the default one.

If T and apt are both specified, their order is irrelevant.

For example:

julia> ds9get(Tuple{Float64,Float64,Float64}, "iexam {$x $y $value}")
(693.0, 627.0, 64.0)

julia> ds9get(Tuple{Int,Int}, "fits size")
(1024, 1024)

julia> ds9get(Bool, "frame has amplifier")
false

julia> ds9get(Tuple{String,VersionNumber}, "version")
("ds9-8.7b1", v"8.7.0-b1")

See also

ds9connect and ds9set.

The page https://ds9.si.edu/doc/ref/xpa.html for a list of XPA commands implemented by SAOImage/DS9. This documentation is also available via the menu Help > Reference Manual > XPA Access Points of SAOImage/DS9.

ds9get(A::Type{<:Array} [, apt]; kwds...) -> arr::A

Returns the contents of current SAOImage/DS9 frame as an array.

Result type A may be Array, Array{T}, Array{T,N}, etc. depending on which type parameters are known (or imposed). Having a more qualified array type A reduces the uncertainty of the result.

ds9get(VersionNumber [, apt]; kwds...)

Retrieve the version of SAOImage/DS9.

ds9set([apt,] args...; data=nothing, throwerrors=true, quiet=false, kwds...)

Send a single XPA set command to SAOImage/DS9.

The command is made of arguments args... converted into strings and concatenated with separating spaces.

Optional argument apt is to specify another access-point to a SAOImage/DS9 server than the default one.

Keywords

• data is to specify the data to send.

• throwerrors is to specify whether to throw an exception in case of error(s) in the XPA reply.

• quiet is to specify whether to not warn about any errors in the XPA reply.

• kwds... are other keywords for XPA.set.

See also

ds9connect and ds9get.

The page https://ds9.si.edu/doc/ref/xpa.html for a list of XPA commands implemented by SAOImage/DS9. This documentation is also available via the menu Help > Reference Manual > XPA Access Points of SAOImage/DS9.

ds9set([apt,] arr; mask=false, frame=nothing, endian=:native, kwds...)

set the contents of an SAOImage/DS9 frame to be array arr. Optional apt is to specify another access-point to a SAOImage/DS9 server than the default one.

Keywords

• mask is true to control the DS9 mask parameters.

• frame specifies a frame number or is :new to create a new frame.

• endian specifies the byte order of arr (see SAOImageDS9.byte_order).

• kwds... are other keywords for ds9set.

ds9accesspoint() -> apt

Yield the current default XPA access-point to SAOImage/DS9.

See also

ds9connect and ds9disconnect.

ds9connect(apt::XPA.AccessPoint) -> apt
ds9connect(addr::AbstractString) -> apt
ds9connect(; kwds...) -> apt
ds9connect(f; kwds...) -> apt

Set the default XPA access-point to SAOImage/DS9 and return it. The access-point may be fully specified (1st example), specified by its address (2nd example), or found among a list of running SAOImage/DS9 (3rd and 4th examples) by calling XPA.find with filter function f and keywords kwds.... If not specified (3rd example), the default filter function is:

apt -> apt.class == "DS9" && apt.user == ENV["USER"]

When calling XPA.find, the default value of the select keyword is :interact if Julia is running an interactive session.

See also

ds9accesspoint and ds9disconnect.

ds9disconnect()

Forget the default XPA access-point to SAOImage/DS9.

See also

ds9accesspoint and ds9connect.

ds9launch([name]; method="local", exe="ds9", timeout=30, quiet=false)

Launch the SAOImage/DS9 application and connect to it. Optional argument name is the name (and title) of the SAOImage/DS9 server to identity it. By default, the name is the given by the current PID. The default access-point is set to that of the new server.

Keywords

• method is the type of connection to use. The default method is ENV["XPA_METHOD"] if this environment variable is set and "local" otherwise.

• exe is the path to SAOImage/DS9 executable.

• timeout is the maximum number of seconds to wait for connecting.

• quiet specifies whether to print information and warning messages.

See also

ds9connect and ds9quit.

ds9quit()
ds9quit(apt::XPA.Accesspoint)
ds9quit(addr::AbstractString)

Require SAOImage/DS9 application to quit. With no argument, the default SAOImage/DS9 application is closed. Otherwise, a specific SAOImage/DS9 application may be targeted by specifying its access-point apt or the address addr of its access-point.

See also ds9accesspoint and ds9disconnect.

ds9cursor([apt]; event=:button, text="", cancel=false) -> (key, x, y, val)

returns the position of the mouse cursor in SAOImage/DS9 interactively chosen by the user as a 4-tuple (key, x, y, val) where key is the key pressed or button clicked, (x, y) are the image coordinates of the selected position, and val the corresponding pixel value. Coordinates x and y may be 0 and val may be NaN if user selects a position outside the image area or in an empty frame.

In SAOImage/DS9 image coordinates are similar to Julia fractional indices in ordinary arrays. Hence, if the image pixels are also stored by A (an Array) in Julia, the nearest position corresponds to A[i,j] with (i,j) = round.(Int,(x,y)).

Optional argument apt is to specify another access-point to a SAOImage/DS9 server than the default one.

Keywords

• event is the type of event to capture the cursor position, one of :button, :key, or :any.

• text, if non-empty, specifies a message to be displayed in a message dialog first.

• cancel specifies whether the user may cancel the operation in the dialog message, in which case this function returns nothing.

See also

ds9iexam to retrieve the coordinate in another system than image.

ds9get and ds9message.

ds9iexam([apt], coordsys=:image; event=:button, text="", cancel=false) -> (key, x, y)
ds9iexam([apt], :value;          event=:button, text="", cancel=false) -> (key, val)

return the position or value at the mouse cursor in SAOImage/DS9 interactively chosen by the user.

If argument coordsys is :value or "value", this function returns (key, val) with key the key pressed or button clicked and val the pixel value (NaN if selected position is outside image area). Otherwise, this function returns (key, x, y) with (x, y) the coordinates of the selected position in coordinate system specified by coordsys.

Optional argument apt is to specify another access-point to a SAOImage/DS9 server than the default one.

Keywords

• event is the type of event to capture the cursor position, one of :button, :key, or :any.

• text, if non-empty, specifies a message to be displayed in a message dialog first.

• cancel specifies whether the user may cancel the operation in the dialog message, in which case this function returns nothing.

See also

ds9cursor to retrieve (key, x, y, val) in image coordinate system.

ds9get and ds9message.

ds9draw([apt,] args...; kwds...)

draws something in SAOImage/DS9 application.

The specific operation depends on the type of the arguments.

ds9draw([apt,] img::AbstractMatrix; kwds...)

displays image img (a 2-dimensional Julia array) in SAOImage/DS9.

Keywords

• frame: to select a given frame number, or :new to draw image in a new frame;
• cmap: uses the named colormap;
• zoom: fixes the zoom factor;
• min & max: fix the scale limits.

ds9draw([apt,] pnt; kwds...)

Draw pnt as point(s) in SAOImage/DS9.

pnt can be a Point, an array, or a tuple of Point's.

ds9draw([apt,] box; kwds...)

Draws box as rectangle(s) in SAOImage/DS9.

boxcan be aBoundingBox, an array, or a tuple ofBoundingBox`'es.

ds9message([apt,] text; cancel=false)

Display a dialog with a message given by text.

If cancel=true, a Cancel button is added to the dialog: in that case, the return value is true or false depending on the button pressed by the user.

ds9getregions([apt,] name=""; coords=:image, selected=false)

returns the regions defined in SAOImage/DS9 frame.

The optional argument name is the name of the group of regions to extract. All regions are extracted if name is an empty string.

Keywords

• coords: the type of coordinates to return: can be :image, :physical, :fk5, :galactic

The return value is a vector of 3-tuples (shape, coordinates, properties), where shape is a symbol indicating shape of the region, coordinates is an array of coordinates, and properties is a dictionary with the properties of the region. Note that the code parses as much as possible the properties: therefore, the returned dictionary can include a variety of different value types, depending on the keyword. The following rules applies

• the global properties are always merged to the more specific region properties;
• properties with boolean meaning, such as :select, :edit, or :rotate are suitably converted to true or false;
• properties enclosed within single quotes ('...'), double quotes ("..."), or braces ({...}) are returned as strings with the boundary markers removed;
• since a region can contain multiple tag specifications, the :tag property is always returned as an array of strings;
• properties consisting of multiple elements, such as :dash, :line, and :point are returned as tuples.

ds9wcs([apt]; useheader=true)

returns the FITS header cards defining the WCS transformation in SAOImage/DS9 frame.

Keywords

• useheader specifies whether to extract WCS transformation from the FITS header. Otherwise, the WCS transformation is extracted from the result of the "wcs save" command.

bitpix_of(x) -> bp

yields FITS bits-per-pixel (BITPIX) value for x which can be an array or a type. A value of 0 is returned if x is not of a supported type.

See also SAOImageDS9.bitpix_to_type.

bitpix_to_type(bpp) -> T

Return the Julia type corresponding to FITS BITPIX (bits-per-pixel) value bpp.

See also

SAOImageDS9.bitpix_of.

byte_order(endian)

yields the byte order for retrieving the elements of a SAOImage/DS9 array. Argument can be one of the strings (or the equivalent symbol): "big" for most significant byte first, "little" for least significant byte first or "native" to yield the byte order of the machine.

See also

ds9get, ds9set.