diff --git a/python/lsst/afw/display/interface.py b/python/lsst/afw/display/interface.py index fd9a85b83..66399c9ef 100644 --- a/python/lsst/afw/display/interface.py +++ b/python/lsst/afw/display/interface.py @@ -124,16 +124,16 @@ def _makeDisplayImpl(display, backend, *args, **kwargs): class Display: - """Create an object able to display images and overplot glyphs + """Create an object able to display images and overplot glyphs. Parameters ---------- frame - An identifier for the display + An identifier for the display. backend : `str` - The backend to use (defaults to value set by setDefaultBackend()) + The backend to use (defaults to value set by setDefaultBackend()). **kwargs - Arguments to pass to the backend + Arguments to pass to the backend. """ _displays = {} _defaultBackend = None @@ -203,12 +203,12 @@ def _h_callback(k, x, y): Display._displays[frame] = self def __enter__(self): - """Support for python's with statement + """Support for python's with statement. """ return self def __exit__(self, *args): - """Support for python's with statement + """Support for python's with statement. """ self.close() @@ -216,17 +216,18 @@ def __del__(self): self.close() def __getattr__(self, name): - """Return the attribute of ``self._impl``, or ``._impl`` if it is requested + """Return the attribute of ``self._impl``, or ``._impl`` if it is + requested. Parameters: ----------- name : `str` - name of the attribute requested + name of the attribute requested. Returns: -------- attribute : `object` - the attribute of self._impl for the requested name + the attribute of self._impl for the requested name. """ if name == '_impl': @@ -252,7 +253,7 @@ def close(self): @property def verbose(self): - """The backend's verbosity + """The backend's verbosity. """ return self._impl.verbose @@ -282,19 +283,19 @@ def getDefaultBackend(): @staticmethod def setDefaultFrame(frame=0): - """Set the default frame for display + """Set the default frame for display. """ Display._defaultFrame = frame @staticmethod def getDefaultFrame(): - """Get the default frame for display + """Get the default frame for display. """ return Display._defaultFrame @staticmethod def incrDefaultFrame(): - """Increment the default frame for display + """Increment the default frame for display. """ Display._defaultFrame += 1 return Display._defaultFrame @@ -308,15 +309,15 @@ def setDefaultMaskTransparency(maskPlaneTransparency={}): @staticmethod def setDefaultMaskPlaneColor(name=None, color=None): - """Set the default mapping from mask plane names to colors + """Set the default mapping from mask plane names to colors. Parameters ---------- name : `str` or `dict` - name of mask plane, or a dict mapping names to colors - If name is `None`, use the hard-coded default dictionary + Name of mask plane, or a dict mapping names to colors + If name is `None`, use the hard-coded default dictionary. color - Desired color, or `None` if name is a dict + Desired color, or `None` if name is a dict. """ if name is None: @@ -332,33 +333,33 @@ def setDefaultMaskPlaneColor(name=None, color=None): @staticmethod def setDefaultImageColormap(cmap): - """Set the default colormap for images + """Set the default colormap for images. Parameters ---------- cmap : `str` - Name of colormap, as interpreted by the backend + Name of colormap, as interpreted by the backend. Notes ----- The only colormaps that all backends are required to honor - (if they pay any attention to setImageColormap) are "gray" and "grey" + (if they pay any attention to setImageColormap) are "gray" and "grey". """ Display._defaultImageColormap = cmap def setImageColormap(self, cmap): - """Set the colormap to use for images + """Set the colormap to use for images. Parameters ---------- cmap : `str` - Name of colormap, as interpreted by the backend + Name of colormap, as interpreted by the backend. Notes ----- The only colormaps that all backends are required to honor - (if they pay any attention to setImageColormap) are "gray" and "grey" + (if they pay any attention to setImageColormap) are "gray" and "grey". """ self._impl._setImageColormap(cmap) @@ -370,7 +371,8 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): Parameters ---------- frame - The desired frame (`None` => use defaultFrame (see `~Display.setDefaultFrame`)) + The desired frame (`None` => use defaultFrame + (see `~Display.setDefaultFrame`)). backend : `str` create the specified frame using this backend (or the default if `None`) if it doesn't already exist. If ``backend == ""``, it's an @@ -378,9 +380,9 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): create : `bool` create the display if it doesn't already exist. verbose : `bool` - Allow backend to be chatty + Allow backend to be chatty. **kwargs - keyword arguments passed to `Display` constructor + keyword arguments passed to `Display` constructor. """ if frame is None: @@ -398,19 +400,19 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): @staticmethod def delAllDisplays(): - """Delete and close all known displays + """Delete and close all known displays. """ for disp in list(Display._displays.values()): disp.close() Display._displays = {} def maskColorGenerator(self, omitBW=True): - """A generator for "standard" colors + """A generator for "standard" colors. Parameters ---------- omitBW : `bool` - Don't include `BLACK` and `WHITE` + Don't include `BLACK` and `WHITE`. Examples -------- @@ -434,22 +436,26 @@ def maskColorGenerator(self, omitBW=True): yield color def setMaskPlaneColor(self, name, color=None): - """Request that mask plane name be displayed as color + """Request that mask plane name be displayed as color. Parameters ---------- name : `str` or `dict` - Name of mask plane or a dictionary of name -> colorName + Name of mask plane or a dictionary of name -> colorName. color : `str` - The name of the color to use (must be `None` if ``name`` is a `dict`) + The name of the color to use (must be `None` if ``name`` is a + `dict`). - Colors may be specified as any X11-compliant string (e.g. `"orchid"`), or by one - of the following constants in `lsst.afw.display` : `BLACK`, `WHITE`, `RED`, `BLUE`, + Colors may be specified as any X11-compliant string (e.g. + `"orchid"`), or by one of the following constants in + `lsst.afw.display` : `BLACK`, `WHITE`, `RED`, `BLUE`, `GREEN`, `CYAN`, `MAGENTA`, `YELLOW`. - If the color is "ignore" (or `IGNORE`) then that mask plane is not displayed + If the color is "ignore" (or `IGNORE`) then that mask plane is not + displayed. - The advantage of using the symbolic names is that the python interpreter can detect typos. + The advantage of using the symbolic names is that the python + interpreter can detect typos. """ if isinstance(name, dict): assert color is None @@ -460,12 +466,12 @@ def setMaskPlaneColor(self, name, color=None): self._maskPlaneColors[name] = color def getMaskPlaneColor(self, name=None): - """Return the color associated with the specified mask plane name + """Return the color associated with the specified mask plane name. Parameters ---------- name : `str` - Desired mask plane; if `None`, return entire dict + Desired mask plane; if `None`, return entire dict. """ if name is None: return self._maskPlaneColors @@ -478,7 +484,8 @@ def getMaskPlaneColor(self, name=None): return color def setMaskTransparency(self, transparency=None, name=None): - """Specify display's mask transparency (percent); or `None` to not set it when loading masks + """Specify display's mask transparency (percent); or `None` to not set + it when loading masks. """ if isinstance(transparency, dict): assert name is None @@ -498,7 +505,7 @@ def setMaskTransparency(self, transparency=None, name=None): self._impl._setMaskTransparency(transparency, name) def getMaskTransparency(self, name=None): - """Return the current display's mask transparency + """Return the current display's mask transparency. """ return self._impl._getMaskTransparency(name) @@ -507,13 +514,13 @@ def show(self): Notes ----- - Throws an exception if frame doesn't exit + Throws an exception if frame doesn't exit. """ return self._impl._show() def __addMissingMaskPlanes(self, mask): - """Assign colours to any missing mask planes found in mask""" - + """Assign colours to any missing mask planes found in mask. + """ maskPlanes = mask.getMaskPlaneDict() nMaskPlanes = max(maskPlanes.values()) + 1 @@ -600,7 +607,7 @@ def mtv(self, data, title="", wcs=None): self.image(self, data, title="", wcs=None) class _Buffering: - """A class intended to be used with python's with statement + """Context manager for buffering repeated display commands. """ def __init__(self, _impl): self._impl = _impl @@ -613,7 +620,8 @@ def __exit__(self, *args): self._impl._flush() def Buffering(self): - """Return a class intended to be used with python's with statement + """Return a context manager that will buffer repeated display + commands, to e.g. speed up displaying points. Examples -------- @@ -625,12 +633,12 @@ def Buffering(self): return self._Buffering(self._impl) def flush(self): - """Flush the buffers + """Flush the buffers. """ self._impl._flush() def erase(self): - """Erase the specified display frame + """Erase the specified display frame. """ self._impl._erase() @@ -679,15 +687,15 @@ def dot(self, symb, c, r, size=2, ctype=None, origin=afwImage.PARENT, **kwargs): Any other value Interpreted as a string to be drawn. c, r - The column and row where the symbol is drawn [0-based coordinates] + The column and row where the symbol is drawn [0-based coordinates]. size : `int` - Size of symbol, in pixels + Size of symbol, in pixels. ctype : `str` The desired color, either e.g. `lsst.afw.display.RED` or a color name known to X11 origin : `lsst.afw.image.ImageOrigin` Coordinate system for the given positions. **kwargs - Extra keyword arguments to backend + Extra keyword arguments to backend. """ if isinstance(symb, int): symb = f"{symb:d}" @@ -717,18 +725,19 @@ def line(self, points, origin=afwImage.PARENT, symbs=False, ctype=None, size=0.5 Parameters ---------- points : `list` - a list of (col, row) + A list of (col, row) origin : `lsst.afw.image.ImageOrigin` Coordinate system for the given positions. symbs : `bool` or sequence - If ``symbs`` is `True`, draw points at the specified points using the desired symbol, - otherwise connect the dots. + If ``symbs`` is `True`, draw points at the specified points using + the desired symbol, otherwise connect the dots. - If ``symbs`` supports indexing (which includes a string -- caveat emptor) the - elements are used to label the points + If ``symbs`` supports indexing (which includes a string -- caveat + emptor) the elements are used to label the points. ctype : `str` - ``ctype`` is the name of a color (e.g. 'red') + ``ctype`` is the name of a color (e.g. 'red'). size : `float` + Size of points to create if `symbs` is passed. """ if symbs: try: @@ -756,15 +765,16 @@ def scale(self, algorithm, min, max=None, unit=None, **kwargs): Parameters ---------- algorithm : `str` - Desired scaling (e.g. "linear" or "asinh") + Desired scaling (e.g. "linear" or "asinh"). min - Minimum value, or "minmax" or "zscale" + Minimum value, or "minmax" or "zscale". max - Maximum value (must be `None` for minmax|zscale) + Maximum value (must be `None` for minmax|zscale). unit - Units for min and max (e.g. Percent, Absolute, Sigma; `None` if min==minmax|zscale) + Units for min and max (e.g. Percent, Absolute, Sigma; `None` if + min==minmax|zscale). **kwargs - Optional keyword arguments to the backend + Optional keyword arguments to the backend. """ if min in ("minmax", "zscale"): assert max is None, f"You may not specify \"{min}\" and max" @@ -796,12 +806,12 @@ def zoom(self, zoomfac=None, colc=None, rowc=None, origin=afwImage.PARENT): self._impl._zoom(zoomfac) def pan(self, colc=None, rowc=None, origin=afwImage.PARENT): - """Pan to a location + """Pan to a location. Parameters ---------- colc, rowc - the coordinates to pan to + Coordinates to pan to. origin : `lsst.afw.image.ImageOrigin` Coordinate system for the given positions. @@ -812,9 +822,11 @@ def pan(self, colc=None, rowc=None, origin=afwImage.PARENT): self.zoom(None, colc, rowc, origin) def interact(self): - """Enter an interactive loop, listening for key presses in display and firing callbacks. + """Enter an interactive loop, listening for key presses in display and + firing callbacks. - Exit with ``q``, ``CR``, ``ESC``, or any other callback function that returns a `True` value. + Exit with ``q``, ``CR``, ``ESC``, or any other callback function that + returns a `True` value. """ interactFinished = False @@ -834,15 +846,16 @@ def interact(self): "Display._callbacks['{0}']({0},{1},{2}) failed: {3}".format(k, x, y, e)) def setCallback(self, k, func=None, noRaise=False): - """Set the callback for a key + """Set the callback for a key. Parameters ---------- k - The key to assign the callback to + The key to assign the callback to. func : callable - The callback assigned to ``k`` + The callback assigned to ``k``. noRaise : `bool` + Do not raise if ``k`` is already in use. Returns ------- @@ -879,7 +892,7 @@ def getActiveCallbackKeys(self, onlyActive=True): class Event: - """A class to handle events such as key presses in image display windows + """A class to handle events such as key presses in image display windows. """ def __init__(self, k, x=float('nan'), y=float('nan')): @@ -927,13 +940,13 @@ def setDefaultFrame(frame=0): def getDefaultFrame(): - """Get the default frame for display + """Get the default frame for display. """ return Display.getDefaultFrame() def incrDefaultFrame(): - """Increment the default frame for display + """Increment the default frame for display. """ return Display.incrDefaultFrame() @@ -943,15 +956,15 @@ def setDefaultMaskTransparency(maskPlaneTransparency={}): def setDefaultMaskPlaneColor(name=None, color=None): - """Set the default mapping from mask plane names to colors + """Set the default mapping from mask plane names to colors. Parameters ---------- name : `str` or `dict` - name of mask plane, or a dict mapping names to colors. - If ``name`` is `None`, use the hard-coded default dictionary + Name of mask plane, or a dict mapping names to colors. + If ``name`` is `None`, use the hard-coded default dictionary. color : `str` - Desired color, or `None` if ``name`` is a dict + Desired color, or `None` if ``name`` is a dict. """ return Display.setDefaultMaskPlaneColor(name, color) @@ -963,7 +976,7 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): Parameters ---------- frame - The desired frame (`None` => use defaultFrame (see `setDefaultFrame`)) + Desired frame (`None` => use defaultFrame (see `setDefaultFrame`)). backend : `str` Create the specified frame using this backend (or the default if `None`) if it doesn't already exist. If ``backend == ""``, it's an @@ -971,9 +984,9 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): create : `bool` Create the display if it doesn't already exist. verbose : `bool` - Allow backend to be chatty + Allow backend to be chatty. **kwargs - keyword arguments passed to `Display` constructor + Keyword arguments passed to `Display` constructor. See also -------- @@ -984,6 +997,6 @@ def getDisplay(frame=None, backend=None, create=True, verbose=False, **kwargs): def delAllDisplays(): - """Delete and close all known displays + """Delete and close all known displays. """ return Display.delAllDisplays()