LSST Applications g013ef56533+d2224463a4,g199a45376c+0ba108daf9,g19c4beb06c+9f335b2115,g1fd858c14a+2459ca3e43,g210f2d0738+2d3d333a78,g262e1987ae+abbb004f04,g2825c19fe3+eedc38578d,g29ae962dfc+0cb55f06ef,g2cef7863aa+aef1011c0b,g35bb328faa+8c5ae1fdc5,g3fd5ace14f+19c3a54948,g47891489e3+501a489530,g4cdb532a89+a047e97985,g511e8cfd20+ce1f47b6d6,g53246c7159+8c5ae1fdc5,g54cd7ddccb+890c8e1e5d,g5fd55ab2c7+951cc3f256,g64539dfbff+2d3d333a78,g67b6fd64d1+501a489530,g67fd3c3899+2d3d333a78,g74acd417e5+0ea5dee12c,g786e29fd12+668abc6043,g87389fa792+8856018cbb,g89139ef638+501a489530,g8d7436a09f+5ea4c44d25,g8ea07a8fe4+81eaaadc04,g90f42f885a+34c0557caf,g9486f8a5af+165c016931,g97be763408+d5e351dcc8,gbf99507273+8c5ae1fdc5,gc2a301910b+2d3d333a78,gca7fc764a6+501a489530,gce8aa8abaa+8c5ae1fdc5,gd7ef33dd92+501a489530,gdab6d2f7ff+0ea5dee12c,ge410e46f29+501a489530,geaed405ab2+e3b4b2a692,gf9a733ac38+8c5ae1fdc5,w.2025.41
LSST Data Management Base Package
Loading...
Searching...
No Matches
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, metadata)
 

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,
metadata )
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?
metadata : `lsst.daf.base.PropertySet`
    Additional metadata.

Definition at line 643 of file ds9.py.

643def _i_mtv(data, wcs, title, isMask, metadata):
644 """Internal routine to display an image or a mask on a DS9 display.
645
646 Parameters
647 ----------
648 data : Subclass of `lsst.afw.image.Image` or `lsst.afw.image.Mask`
649 Data to display.
650 wcs : `lsst.afw.geom.SkyWcs`
651 WCS of data.
652 title : `str`
653 Title of display.
654 isMask : `bool`
655 Is ``data`` a mask?
656 metadata : `lsst.daf.base.PropertySet`
657 Additional metadata.
658 """
659 title = str(title) if title else ""
660
661 if isMask:
662 xpa_cmd = f"xpaset {getXpaAccessPoint()} fits mask"
663 # ds9 mis-handles BZERO/BSCALE in uint16 data.
664 # The following hack works around this.
665 # This is a copy we're modifying
666 if data.getArray().dtype == np.uint16:
667 data |= 0x8000
668 else:
669 xpa_cmd = f"xpaset {getXpaAccessPoint()} fits"
670
671 if haveGzip:
672 xpa_cmd = "gzip | " + xpa_cmd
673
674 with subprocess.Popen(xpa_cmd, stdin=subprocess.PIPE, shell=True) as pfd:
675 ds9Cmd(flush=True, silent=True)
676 afwDisplay.writeFitsImage(pfd, data, wcs, title, metadata)

◆ 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 227 of file ds9.py.

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

◆ ds9Version()

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

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

Definition at line 91 of file ds9.py.

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

◆ 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 63 of file ds9.py.

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

◆ 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.

283def initDS9(execDs9=True):
284 """Initialize DS9.
285
286 Parameters
287 ----------
288 execDs9 : `bool`, optional
289 If DS9 is not running, attempt to execute it.
290 """
291 try:
292 xpa.reset()
293 ds9Cmd("iconify no; raise", False)
294 ds9Cmd("wcs wcsa", False) # include the pixel coordinates WCS (WCSA)
295
296 v0, v1 = ds9Version().split('.')[0:2]
297 global needShow
298 needShow = False
299 try:
300 if int(v0) == 5:
301 needShow = (int(v1) <= 4)
302 except Exception:
303 pass
304 except Ds9Error as e:
305 if not re.search('xpa', os.environ['PATH']):
306 raise Ds9Error('You need the xpa binaries in your path to use ds9 with python')
307
308 if not execDs9:
309 raise Ds9Error
310
311 if not shutil.which("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(f"ds9 doesn't appear to be running ({e}), I'll try to exec it for you")
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

◆ 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 212 of file ds9.py.

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

Variable Documentation

◆ _maskTransparency

lsst.display.ds9.ds9._maskTransparency = None
protected

Definition at line 60 of file ds9.py.

◆ cmdBuffer

lsst.display.ds9.ds9.cmdBuffer

Definition at line 209 of file ds9.py.

◆ file

lsst.display.ds9.ds9.file

Definition at line 41 of file ds9.py.

◆ haveGzip

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

Definition at line 640 of file ds9.py.

◆ needShow

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

Definition at line 49 of file ds9.py.

◆ XPA_SZ_LINE

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

Definition at line 111 of file ds9.py.