DM-5192 Implement Python API to support Firefly actions.

[cwang2016]

• move 'python' and 'test/python' from fftools to be under firefly and firefly/test.
• implement functions to dispatch actions for showing fits, showing table, and adding extension, operating the image (zoom, stretch, and pan), creating/deleting region layer, adding/removing region entries.
• More functions for adding/removing mask and showing XYPlot will be implemented further.

Fixed some region/footprint related issues in Javascript implementation,

• per DS9 document, the default system is implicitly set to be 'PHYSICAL' if no coordinate system is explicitly specified in the region file or region data.
• fixed the footprint/marker display in case the target is represented in various world coordinate systems.

[cwang2016]

• some footprint data is updated, please build and deploy firefly first.
  (gradle :firefly:war :firefly:deploy, and gradle :wise:war)

[cwang2016]

The test file, firefly/test/python/demo-notebook.ipynb, can be run by setting PYTHONPATH = where firefly/python/display/FireflyClient.py is located.

[robyww]

Clean up firefly/src/fftools/python/display/FireflyClient.pyc needs to be removed from git.

[robyww]

in the test files you should use relative paths to the data. The put come documentation at the top saying which directly to expect to start notebook in.

[robyww]

Review Complete. Code looks good. Good Job.

[stargaser]

Copied from DM-5192 (I couldn't put all of these in comments on code diffs since many are legacy issues):

Here are some style comments on the FireflyClient.py module, drawn in part from the DM Python Style Guide. I'm still thinking about the method signatures in detail and will comment a little later on those.

• The methods you don't intend users to use should be prefixed with a single underscore (handleEvent, sendURLAsGet, sendURLAsPost, isPageConnected, createRV, makePidParam)
• Static methods which use other attributes or methods of the class should be class methods instead. See this discussion on Stack Overflow. The methods in this case include createRV, createRangeValuesStandard, createRangeValuesZScale, genItemId, createImageURL.
• Instead of if type(var) is list , should use if isinstance(var, list)

[stargaser]

This is another comment not on the specific diffs in this pull request:

As far as the API goes: I know that the Javascript API is organized around Actions. Python users will want to get information back from Firefly. So a simple zoom or pan does not indicate by itself whether the user is setting the zoom in Firefly or getting the currently set value back. If a getZoom or getPan is doable with the Javascript API, then I'd want to have setZoom and setPan. Astronomers will also want to be able to use world coordinates (ra, dec) for specifying the panning, in addition to pixel units.

[stargaser]

I like the naming of showFits, showTable, and showXYPlot as they clearly indicate that something is going to happen in the Firefly window, and they are in keeping with e.g. the APLpy methods.

Similarly, addRegionData, deleteRegion, removeRegionData indicate actions though I would expect deleteRegion to delete a single region marker and not an entire layer. I suggest to change to deleteRegionLayer and overlayRegionLayer to make it clearer.

[stargaser]

Please use from FireflyClient import FireflyClient. I also wonder if the module should be named fireflyClient.py -- I couldn't tell for sure from reading the DM Python Style guide.

[robyww]

Also they may be trying to get away from camel casing. At one time they decided they wanted to do it like they but I remember some discussion. Might be worth asking Tim Jenness

[robyww]

As far as the API goes: I know that the Javascript API is organized around Actions. Python users will want to get information back from Firefly. So a simple zoom or pan does not indicate by itself whether the user is setting the zoom in Firefly or getting the currently set value back. If a getZoom or getPan is doable with the Javascript API, then I'd want to have setZoom and setPan. Astronomers will also want to be able to use world coordinates (ra, dec) for specifying the panning, in addition to pixel units.

I think you are right about the naming. However, the names where made to be similar to the afw.display api. We should probably make better name and be aware they they will be different. Maybe down the road we can improve the afw.display names.

[stargaser]

make this a @classmethod since it references the class

[stargaser]

Another comment on legacy code:

The methods for specifying the stretch of the image look very forbidding to the astronomer, especially createRV, createRangeValuesStandard and createRangeValuesZScale. It would be better to hide a lot of this under the hood in a setStretch method that would allow for either Zscale, MinMax, Percentile, or absolute levels for the stretch.

[stargaser]

The user might be using standalone firefly-exec.war so please use a relative path: .data/wise-1b-1.fits

[stargaser]

Review complete. The region functionality is very nice!
Apologies for so many comments that were on legacy code predating this pull request.

[stargaser]

An extra note. Tim Jenness confirmed that LSST will move towards more Pythonic lowercase_and_underscores instead of camelCase. The DM Python style guide needs updating. So we should rename removeRegionData to remove_region_data, etc. In general, the style guide will follow Python's PEP8 per RFC-162.