LSST Applications  21.0.0-1-g8760c09+3ec9fa6d59,21.0.0-1-ga51b5d4+1a3c9f8315,21.0.0-13-g5daad6e+0252c796d2,21.0.0-14-g07a2928+6d2a161833,21.0.0-15-g543e7c3+e1f44b4e8b,21.0.0-15-g5a7caf0+22a63f14ab,21.0.0-15-ge3888ae+e70bf517f6,21.0.0-17-g8839fe5+10be924b4e,21.0.0-2-g103fe59+bd743ba87f,21.0.0-2-g45278ab+3ec9fa6d59,21.0.0-2-g5242d73+8a658b4ab3,21.0.0-2-g7f82c8f+82148d848c,21.0.0-2-g8faa9b5+a13d88a6a5,21.0.0-2-ga326454+82148d848c,21.0.0-2-gde069b7+135055f2fa,21.0.0-2-gecfae73+e9d3d7b02c,21.0.0-2-gfc62afb+8a658b4ab3,21.0.0-20-g35aa1e9+9ea05e3f8d,21.0.0-20-g8cd22d88+4d45a66d02,21.0.0-3-g357aad2+262bd63c8d,21.0.0-3-g4a4ce7f+8a658b4ab3,21.0.0-3-g4be5c26+8a658b4ab3,21.0.0-3-g65f322c+de03c300eb,21.0.0-3-ge02ed75+6d2a161833,21.0.0-30-gf21da11f8+33ac405c47,21.0.0-4-g591bb35+6d2a161833,21.0.0-4-g65b4814+10be924b4e,21.0.0-4-ge8a399c+4af7134804,21.0.0-5-g8c1d971+75b22be884,21.0.0-5-gcb07a25+7075ac2890,21.0.0-5-gcc89fd6+a13d88a6a5,21.0.0-5-gd00fb1e+2d6d6ce00a,21.0.0-6-gc675373+8a658b4ab3,21.0.0-7-gdf92d54+3ec9fa6d59,21.0.0-72-gffa78901+7884a7f5e9,21.0.0-8-g5674e7b+3979a46207,21.0.0-8-g72414d6+74174446e7,master-gac4afde19b+6d2a161833,w.2021.16
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.