LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Classes | Functions | Variables
lsst.display.ds9.ds9 Namespace Reference

Classes

class  Ds9Error
 
class  Buffer
 
class  Ds9Event
 
class  DisplayImpl
 

Functions

def getXpaAccessPoint ()
 
def ds9Version ()
 
def selectFrame (frame)
 
def ds9Cmd (cmd=None, trap=True, flush=False, silent=True, frame=None, get=False)
 
def initDS9 (execDs9=True)
 

Variables

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

Function Documentation

◆ ds9Cmd()

def 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 225 of file ds9.py.

225 def ds9Cmd(cmd=None, trap=True, flush=False, silent=True, frame=None, get=False):
226  """Issue a DS9 command, raising errors as appropriate.
227 
228  Parameters
229  ----------
230  cmd : `str`, optional
231  Command to execute.
232  trap : `bool`, optional
233  Trap errors.
234  flush : `bool`, optional
235  Flush the output.
236  silent : `bool`, optional
237  Do not print trapped error messages.
238  frame : `int`, optional
239  Frame number on which to execute command.
240  get : `bool`, optional
241  Return xpa response.
242  """
243 
244  global cmdBuffer
245  if cmd:
246  if frame is not None:
247  cmd = "%s;" % selectFrame(frame) + cmd
248 
249  if get:
250  return xpa.get(None, getXpaAccessPoint(), cmd, "").strip()
251 
252  # Work around xpa's habit of silently truncating long lines; the value
253  # ``5`` provides some margin to handle new lines and the like.
254  if cmdBuffer._lenCommands + len(cmd) > XPA_SZ_LINE - 5:
255  ds9Cmd(flush=True, silent=silent)
256 
257  cmdBuffer._commands += ";" + cmd
258  cmdBuffer._lenCommands += 1 + len(cmd)
259 
260  if flush or cmdBuffer._lenCommands >= cmdBuffer._getSize():
261  cmd = (cmdBuffer._commands + "\n")
262  cmdBuffer._commands = ""
263  cmdBuffer._lenCommands = 0
264  else:
265  return
266 
267  cmd = cmd.rstrip()
268  if not cmd:
269  return
270 
271  try:
272  ret = xpa.set(None, getXpaAccessPoint(), cmd, "", "", 0)
273  if ret:
274  raise IOError(ret)
275  except IOError as e:
276  if not trap:
277  raise Ds9Error("XPA: %s, (%s)" % (e, cmd))
278  elif not silent:
279  print("Caught ds9 exception processing command \"%s\": %s" % (cmd, e), file=sys.stderr)
280 
281 
bool strip
Definition: fits.cc:911
def selectFrame(frame)
Definition: ds9.py:210
def getXpaAccessPoint()
Definition: ds9.py:61
def ds9Cmd(cmd=None, trap=True, flush=False, silent=True, frame=None, get=False)
Definition: ds9.py:225

◆ ds9Version()

def lsst.display.ds9.ds9.ds9Version ( )
Get the version of DS9 in use.

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

Definition at line 89 of file ds9.py.

89 def ds9Version():
90  """Get the version of DS9 in use.
91 
92  Returns
93  -------
94  version : `str`
95  Version of DS9 in use.
96  """
97  try:
98  v = ds9Cmd("about", get=True)
99  return v.splitlines()[1].split()[1]
100  except Exception as e:
101  print("Error reading version: %s" % e, file=sys.stderr)
102  return "0.0.0"
103 
104 
105 try:
106  cmdBuffer
def ds9Version()
Definition: ds9.py:89

◆ getXpaAccessPoint()

def 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 61 of file ds9.py.

61 def getXpaAccessPoint():
62  """Parse XPA_PORT if set and return an identifier to send DS9 commands.
63 
64  Returns
65  -------
66 
67  xpaAccessPoint : `str`
68  Either a reference to the local host with the configured port, or the
69  string ``"ds9"``.
70 
71  Notes
72  -----
73  If you don't have XPA_PORT set, the usual xpans tricks will be played
74  when we return ``"ds9"``.
75  """
76  xpa_port = os.environ.get("XPA_PORT")
77  if xpa_port:
78  mat = re.search(r"^DS9:ds9\s+(\d+)\s+(\d+)", xpa_port)
79  if mat:
80  port1, port2 = mat.groups()
81 
82  return "127.0.0.1:%s" % (port1)
83  else:
84  print("Failed to parse XPA_PORT=%s" % xpa_port, file=sys.stderr)
85 
86  return "ds9"
87 
88 

◆ initDS9()

def 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 282 of file ds9.py.

282 def initDS9(execDs9=True):
283  """Initialize DS9.
284 
285  Parameters
286  ----------
287  execDs9 : `bool`, optional
288  If DS9 is not running, attempt to execute it.
289  """
290  try:
291  xpa.reset()
292  ds9Cmd("iconify no; raise", False)
293  ds9Cmd("wcs wcsa", False) # include the pixel coordinates WCS (WCSA)
294 
295  v0, v1 = ds9Version().split('.')[0:2]
296  global needShow
297  needShow = False
298  try:
299  if int(v0) == 5:
300  needShow = (int(v1) <= 4)
301  except Exception:
302  pass
303  except Ds9Error as e:
304  if not re.search('xpa', os.environ['PATH']):
305  raise Ds9Error('You need the xpa binaries in your path to use ds9 with python')
306 
307  if not execDs9:
308  raise Ds9Error
309 
310  import distutils.spawn
311  if not distutils.spawn.find_executable("ds9"):
312  raise NameError("ds9 doesn't appear to be on your path")
313  if "DISPLAY" not in os.environ:
314  raise RuntimeError("$DISPLAY isn't set, so I won't be able to start ds9 for you")
315 
316  print("ds9 doesn't appear to be running (%s), I'll try to exec it for you" % e)
317 
318  os.system('ds9 &')
319  for i in range(10):
320  try:
321  ds9Cmd(selectFrame(1), False)
322  break
323  except Ds9Error:
324  print("waiting for ds9...\r", end="")
325  sys.stdout.flush()
326  time.sleep(0.5)
327  else:
328  print(" \r", end="")
329  break
330 
331  sys.stdout.flush()
332 
333  raise Ds9Error
334 
335 
def initDS9(execDs9=True)
Definition: ds9.py:282

◆ selectFrame()

def 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 210 of file ds9.py.

210 def selectFrame(frame):
211  """Convert integer frame number to DS9 command syntax.
212 
213  Parameters
214  ----------
215  frame : `int`
216  Frame number
217 
218  Returns
219  -------
220  frameString : `str`
221  """
222  return "frame %d" % (frame)
223 
224 

Variable Documentation

◆ cmdBuffer

lsst.display.ds9.ds9.cmdBuffer

Definition at line 207 of file ds9.py.

◆ definedCallbacks

bool lsst.display.ds9.ds9.definedCallbacks = True

Definition at line 697 of file ds9.py.

◆ file

lsst.display.ds9.ds9.file

Definition at line 39 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 47 of file ds9.py.

◆ XPA_SZ_LINE

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

Definition at line 109 of file ds9.py.