There has been a long history of interest in providing catalog-on-image-overlay to afw.display as a directly supported interface.  (It has always been possible to perform a loop over the dot() interface.) There are essentially two rationales:

  • It's such a common operation that it just seems natural to provide a simple interface.
  • Because the use of dot() in bulk more or less requires the use of a context manager for buffering, in order to achieve acceptable performance, it's fairly unintuitive for non-experts to remember how to use.
  • Specific back-ends to afw.display may be capable of providing a better user interface if a catalog is sent to the back end as a unit.  Among the possibilities:
    • A catalog can be given a name and an identity in the context of a back end and then be manipulated as a whole in the UI, so that multiple overlays can be managed, with UI control of which to display/suppress, color/symbol changes, etc.
    • A catalog can carry along additional attributes beyond just the image-pixel coordinates (IDs, sky coordinates, measurements) that a UI may be able to display or even allow a user to interact with.
    • Display performance may be better than for the display of the DS9-regions drawing commands that are used for the dot() implementations.

Original work

The ticket  DM-6391 - Getting issue details... STATUS was created in 2016 for this.  The initial proposal envisioned a capability for displaying catalogs based on either pixel coordinates or sky coordinates, depending on the user's interests, e.g.:

  • display.showCatalog(sourceCat, coords='radec') or
  • display.showCatalog(sourceCat, coords='cartesian')

The suggested use of sky coordinates stirred up some concern because of the implication that the visualization back end would have to process the WCS, something that might not always be possible (e.g., if the WCS were to be difficult or impossible to represent in a form understood by the back end) and also because in some cases the image array sent to the display might not come with a WCS at all.  Largely (gpdf thinks) because of this objection, the 2016-era efforts were abandoned, and the never-merged PR on afw was eventually closed without merging.

The ticket  DM-10870 - Getting issue details... STATUS was created to encourage devising a solution to the impasse, but it was never successfully acted on and remains open.

The original design envisioned deferring the actual image-overlay work to the DisplayImpl subclass for the specific back end, because of the significant differences in back ends' interfaces for catalog overlays.  A simple default implementation that should work for any back end that supports dot() was envisioned, with overrides for back ends for which that can be improved upon.

Current work: initial step

We are reviving work on this now, at first still under DM-6391 - Getting issue details... STATUS .

At this time we are not going beyond the use of pixel coordinates in specifying the actual overlaid symbol positions.  Note that Firefly does support this for uploaded tables – it's possible to mark them with metadata stating that they should be overlaid by pixel coordinates instead of the default of using sky coordinates and directly interpreting the image's WCS in the client.

John Parejko has provided a version of this in a PR on afw, but implemented as a "convenience wrapper", centroids(), in the afw.display front end that just extracts centroids as x/y and performs the appropriate buffered loop over dot().  This should work with all back ends but does not allow for back-end-specific optimizations.

I'm comfortable with that approach being deployed now without completion of the original plan, but I'd like to at least briefly think about where we might be going next, before merging, in case it affects things like the name of the new method, or its signature.

Next step

In order to allow back-end-specific work to take place, the basic idea I'd like to promote (see DM-42428 - Getting issue details... STATUS ) is to add a new method – let's call it _displayTable() for now – to the DisplayImpl  base class in virtualDevice .  Instead of just the usual no-op implementation, something like 

if self.verbose:
          print("virtual[%s]._displayTable(...)" % (self.frame, ...))

instead we would move John's implementation from centroids() to here, providing a basic default implementation in terms of calling back to DisplayImpl's _dot(), with buffering, that should work for any back end.  In the DS9 back end we would leave that alone.  In the Firefly back end, for instance, we would override the _displayTable() method to use a more Firefly-specific approach to sending the table to the display as a whole.

centroids() would now just call through to self._impl._displayTable() .

Choosing additional columns to display

The intent would be to allow the back end's DisplayImpl to transmit more of the table than just the x and y values.  Some discussion is necessary to figure out how to deal with this in the interface and to provide useful defaults.

Handling XY0

Since afw.display supports "XY0" offsetting for dot(), but applies it in the front end, a little thought would need to go in to what a UI like Firefly that would like to actually display  the X,Y values from the table should do in the catalog implementation, as in this case subtracting XY0 on the front end might be the wrong thing to do.

  • No labels