lsst.display.ds9.ds9 Namespace Reference

Classes
class	Buffer
class	DisplayImpl
class	Ds9Error
class	Ds9Event

Functions
	getXpaAccessPoint ()
	ds9Version ()
	selectFrame (frame)
	ds9Cmd (cmd=None, trap=True, flush=False, silent=True, frame=None, get=False)
	initDS9 (execDs9=True)
	_i_mtv (data, wcs, title, isMask)

Variables
	file
bool	needShow = True
	_maskTransparency = None
int	XPA_SZ_LINE = 4096 - 100
	cmdBuffer
	haveGzip = not os.system("gzip < /dev/null > /dev/null 2>&1")

Function Documentation

_i_mtv()

lsst.display.ds9.ds9._i_mtv ( data, wcs, title, isMask )

protected

Internal routine to display an image or a mask on a DS9 display.

Parameters
----------
data : Subclass of `lsst.afw.image.Image` or `lsst.afw.image.Mask`
    Data to display.
wcs : `lsst.afw.geom.SkyWcs`
    WCS of data.
title : `str`
    Title of display.
isMask : `bool`
    Is ``data`` a mask?

Definition at line 641 of file ds9.py.

def _i_mtv(data, wcs, title, isMask):
    """Internal routine to display an image or a mask on a DS9 display.
 
    Parameters
    ----------
    data : Subclass of `lsst.afw.image.Image` or `lsst.afw.image.Mask`
        Data to display.
    wcs : `lsst.afw.geom.SkyWcs`
        WCS of data.
    title : `str`
        Title of display.
    isMask : `bool`
        Is ``data`` a mask?
    """
    title = str(title) if title else ""
 
    if isMask:
        xpa_cmd = f"xpaset {getXpaAccessPoint()} fits mask"
        # ds9 mis-handles BZERO/BSCALE in uint16 data.
        # The following hack works around this.
        # This is a copy we're modifying
        if data.getArray().dtype == np.uint16:
            data |= 0x8000
    else:
        xpa_cmd = f"xpaset {getXpaAccessPoint()} fits"
 
    if haveGzip:
        xpa_cmd = "gzip | " + xpa_cmd
 
    pfd = os.popen(xpa_cmd, "w")
 
    ds9Cmd(flush=True, silent=True)
 
    try:
        afwDisplay.writeFitsImage(pfd.fileno(), data, wcs, title)
    except Exception as e:
        try:
            pfd.close()
        except Exception:
            pass
 
        raise e
 
    try:
        pfd.close()
    except Exception:
        pass

ds9Cmd()

lsst.display.ds9.ds9.ds9Cmd	(		cmd = None,
			trap = True,
			flush = False,
			silent = True,
			frame = None,
			get = False )

Issue a DS9 command, raising errors as appropriate.

Parameters
----------
cmd : `str`, optional
    Command to execute.
trap : `bool`, optional
    Trap errors.
flush : `bool`, optional
    Flush the output.
silent : `bool`, optional
    Do not print trapped error messages.
frame : `int`, optional
    Frame number on which to execute command.
get : `bool`, optional
    Return xpa response.

Definition at line 226 of file ds9.py.

def ds9Cmd(cmd=None, trap=True, flush=False, silent=True, frame=None, get=False):
    """Issue a DS9 command, raising errors as appropriate.
 
    Parameters
    ----------
    cmd : `str`, optional
        Command to execute.
    trap : `bool`, optional
        Trap errors.
    flush : `bool`, optional
        Flush the output.
    silent : `bool`, optional
        Do not print trapped error messages.
    frame : `int`, optional
        Frame number on which to execute command.
    get : `bool`, optional
        Return xpa response.
    """
 
    global cmdBuffer
    if cmd:
        if frame is not None:
            cmd = f"{selectFrame(frame)};{cmd}"
 
        if get:
            return xpa.get(None, getXpaAccessPoint(), cmd, "").strip()
 
        # Work around xpa's habit of silently truncating long lines; the value
        # ``5`` provides some margin to handle new lines and the like.
        if cmdBuffer._lenCommands + len(cmd) > XPA_SZ_LINE - 5:
            ds9Cmd(flush=True, silent=silent)
 
        cmdBuffer._commands += ";" + cmd
        cmdBuffer._lenCommands += 1 + len(cmd)
 
    if flush or cmdBuffer._lenCommands >= cmdBuffer._getSize():
        cmd = (cmdBuffer._commands + "\n")
        cmdBuffer._commands = ""
        cmdBuffer._lenCommands = 0
    else:
        return
 
    cmd = cmd.rstrip()
    if not cmd:
        return
 
    try:
        ret = xpa.set(None, getXpaAccessPoint(), cmd, "", "", 0)
        if ret:
            raise OSError(ret)
    except OSError as e:
        if not trap:
            raise Ds9Error(f"XPA: {e}, ({cmd})")
        elif not silent:
            print(f"Caught ds9 exception processing command \"{cmd}\": {e}", file=sys.stderr)
 
 

ds9Version()

lsst.display.ds9.ds9.ds9Version

(

)

Get the version of DS9 in use.

Returns
-------
version : `str`
    Version of DS9 in use.

Definition at line 90 of file ds9.py.

def ds9Version():
    """Get the version of DS9 in use.
 
    Returns
    -------
    version : `str`
        Version of DS9 in use.
    """
    try:
        v = ds9Cmd("about", get=True)
        return v.splitlines()[1].split()[1]
    except Exception as e:
        print(f"Error reading version: {e}", file=sys.stderr)
        return "0.0.0"
 
 

getXpaAccessPoint()

lsst.display.ds9.ds9.getXpaAccessPoint

(

)

Parse XPA_PORT if set and return an identifier to send DS9 commands.

Returns
-------

xpaAccessPoint : `str`
    Either a reference to the local host with the configured port, or the
    string ``"ds9"``.

Notes
-----
If you don't have XPA_PORT set, the usual xpans tricks will be played
when we return ``"ds9"``.

Definition at line 62 of file ds9.py.

def getXpaAccessPoint():
    """Parse XPA_PORT if set and return an identifier to send DS9 commands.
 
    Returns
    -------
 
    xpaAccessPoint : `str`
        Either a reference to the local host with the configured port, or the
        string ``"ds9"``.
 
    Notes
    -----
    If you don't have XPA_PORT set, the usual xpans tricks will be played
    when we return ``"ds9"``.
    """
    xpa_port = os.environ.get("XPA_PORT")
    if xpa_port:
        mat = re.search(r"^DS9:ds9\s+(\d+)\s+(\d+)", xpa_port)
        if mat:
            port1, port2 = mat.groups()
 
            return f"127.0.0.1:{port1}"
        else:
            print(f"Failed to parse XPA_PORT={xpa_port}", file=sys.stderr)
 
    return "ds9"
 
 

initDS9()

lsst.display.ds9.ds9.initDS9

(

execDs9 = True

)

Initialize DS9.

Parameters
----------
execDs9 : `bool`, optional
    If DS9 is not running, attempt to execute it.

Definition at line 283 of file ds9.py.

def initDS9(execDs9=True):
    """Initialize DS9.
 
    Parameters
    ----------
    execDs9 : `bool`, optional
        If DS9 is not running, attempt to execute it.
    """
    try:
        xpa.reset()
        ds9Cmd("iconify no; raise", False)
        ds9Cmd("wcs wcsa", False)         # include the pixel coordinates WCS (WCSA)
 
        v0, v1 = ds9Version().split('.')[0:2]
        global needShow
        needShow = False
        try:
            if int(v0) == 5:
                needShow = (int(v1) <= 4)
        except Exception:
            pass
    except Ds9Error as e:
        if not re.search('xpa', os.environ['PATH']):
            raise Ds9Error('You need the xpa binaries in your path to use ds9 with python')
 
        if not execDs9:
            raise Ds9Error
 
        if not shutil.which("ds9"):
            raise NameError("ds9 doesn't appear to be on your path")
        if "DISPLAY" not in os.environ:
            raise RuntimeError("$DISPLAY isn't set, so I won't be able to start ds9 for you")
 
        print(f"ds9 doesn't appear to be running ({e}), I'll try to exec it for you")
 
        os.system('ds9 &')
        for i in range(10):
            try:
                ds9Cmd(selectFrame(1), False)
                break
            except Ds9Error:
                print("waiting for ds9...\r", end="")
                sys.stdout.flush()
                time.sleep(0.5)
            else:
                print("                  \r", end="")
                break
 
        sys.stdout.flush()
 
        raise Ds9Error
 
 

selectFrame()

lsst.display.ds9.ds9.selectFrame

(

frame

)

Convert integer frame number to DS9 command syntax.

Parameters
----------
frame : `int`
    Frame number

Returns
-------
frameString : `str`

Definition at line 211 of file ds9.py.

def selectFrame(frame):
    """Convert integer frame number to DS9 command syntax.
 
    Parameters
    ----------
    frame : `int`
        Frame number
 
    Returns
    -------
    frameString : `str`
    """
    return f"frame {frame}"
 
 

Variable Documentation

_maskTransparency

lsst.display.ds9.ds9._maskTransparency = None

protected

Definition at line 59 of file ds9.py.

cmdBuffer

lsst.display.ds9.ds9.cmdBuffer

Definition at line 208 of file ds9.py.

file

lsst.display.ds9.ds9.file

Definition at line 40 of file ds9.py.

haveGzip

lsst.display.ds9.ds9.haveGzip = not os.system("gzip < /dev/null > /dev/null 2>&1")

Definition at line 638 of file ds9.py.

needShow

bool lsst.display.ds9.ds9.needShow = True

Definition at line 48 of file ds9.py.

XPA_SZ_LINE

int lsst.display.ds9.ds9.XPA_SZ_LINE = 4096 - 100

Definition at line 110 of file ds9.py.