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()
|
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 644 of file ds9.py.
644def _i_mtv(data, wcs, title, isMask, metadata):
645 """Internal routine to display an image or a mask on a DS9 display.
646
647 Parameters
648 ----------
649 data : Subclass of `lsst.afw.image.Image` or `lsst.afw.image.Mask`
650 Data to display.
651 wcs : `lsst.afw.geom.SkyWcs`
652 WCS of data.
653 title : `str`
654 Title of display.
655 isMask : `bool`
656 Is ``data`` a mask?
657 metadata : `lsst.daf.base.PropertySet`
658 Additional metadata.
659 """
660 title = str(title) if title else ""
661
662 if isMask:
663 xpa_cmd = f"xpaset {getXpaAccessPoint()} fits mask"
664 # ds9 mis-handles BZERO/BSCALE in uint16 data.
665 # The following hack works around this.
666 # This is a copy we're modifying
667 if data.getArray().dtype == np.uint16:
668 data |= 0x8000
669 else:
670 xpa_cmd = f"xpaset {getXpaAccessPoint()} fits"
671
672 if haveGzip:
673 xpa_cmd = "gzip | " + xpa_cmd
674
675 with subprocess.Popen(xpa_cmd, stdin=subprocess.PIPE, shell=True) as pfd:
676 ds9Cmd(flush=True, silent=True)
677 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 global cmdBuffer
247 if cmd:
248 if frame is not None:
249 cmd = f"{selectFrame(frame)};{cmd}"
250
251 if get:
252 return xpa.get(None, getXpaAccessPoint(), cmd, "").strip()
253
254 # Work around xpa's habit of silently truncating long lines; the value
255 # ``5`` provides some margin to handle new lines and the like.
256 if cmdBuffer._lenCommands + len(cmd) > XPA_SZ_LINE - 5:
257 ds9Cmd(flush=True, silent=silent)
258
259 cmdBuffer._commands += ";" + cmd
260 cmdBuffer._lenCommands += 1 + len(cmd)
261
262 if flush or cmdBuffer._lenCommands >= cmdBuffer._getSize():
263 cmd = (cmdBuffer._commands + "\n")
264 cmdBuffer._commands = ""
265 cmdBuffer._lenCommands = 0
266 else:
267 return
268
269 cmd = cmd.rstrip()
270 if not cmd:
271 return
272
273 try:
274 ret = xpa.set(None, getXpaAccessPoint(), cmd, "", "", 0)
275 if ret:
276 raise OSError(ret)
277 except OSError as e:
278 if not trap:
279 raise Ds9Error(f"XPA: {e}, ({cmd})")
280 elif not silent:
281 print(f"Caught ds9 exception processing command \"{cmd}\": {e}", file=sys.stderr)
282
283
◆ 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 284 of file ds9.py.
284def initDS9(execDs9=True):
285 """Initialize DS9.
286
287 Parameters
288 ----------
289 execDs9 : `bool`, optional
290 If DS9 is not running, attempt to execute it.
291 """
292 try:
293 xpa.reset()
294 ds9Cmd("iconify no; raise", False)
295 ds9Cmd("wcs wcsa", False) # include the pixel coordinates WCS (WCSA)
296
297 v0, v1 = ds9Version().split('.')[0:2]
298 global needShow
299 needShow = False
300 try:
301 if int(v0) == 5:
302 needShow = (int(v1) <= 4)
303 except Exception:
304 pass
305 except Ds9Error as e:
306 if not re.search('xpa', os.environ['PATH']):
307 raise Ds9Error('You need the xpa binaries in your path to use ds9 with python')
308
309 if not execDs9:
310 raise Ds9Error
311
312 if not shutil.which("ds9"):
313 raise NameError("ds9 doesn't appear to be on your path")
314 if "DISPLAY" not in os.environ:
315 raise RuntimeError("$DISPLAY isn't set, so I won't be able to start ds9 for you")
316
317 print(f"ds9 doesn't appear to be running ({e}), I'll try to exec it for you")
318
319 os.system('ds9 &')
320 for i in range(10):
321 try:
322 ds9Cmd(selectFrame(1), False)
323 break
324 except Ds9Error:
325 print("waiting for ds9...\r", end="")
326 sys.stdout.flush()
327 time.sleep(0.5)
328 else:
329 print(" \r", end="")
330 break
331
332 sys.stdout.flush()
333
334 raise Ds9Error
335
336
◆ 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
◆ cmdBuffer
◆ file
◆ haveGzip
| lsst.display.ds9.ds9.haveGzip = not os.system("gzip < /dev/null > /dev/null 2>&1") |
◆ needShow
◆ XPA_SZ_LINE
Generated on Thu Apr 17 2025 08:22:28 for LSST Applications by
1.13.2