Refactor scale_image module

[larrybradley]

This PR refactors the scale_image module, including combining the scale_* functions into a single function (https://github.com/astropy/imageutils/pull/11#issuecomment-51109051, https://github.com/astropy/imageutils/issues/16).

@astrofrog I have no equivalent to APLpy's vmid keyword for log scaling (log scaling in APLpy is a bit different). For asinh scaling, noise_level here is equivalent to vmid (but the defaults are not the same).

Can someone review this?

[cdeil]

@ejeschke - I think you have implemented image scaling functions similar or identical to the ones in ds9 as well for ginga? Can you point out where those are for comparison or maybe you even have time to review and comment on this pull request?

The idea is that this becomes available in astropy.image soon, exactly to avoid having duplication of image utility functions between astro packages.

[astrofrog]

I plan to review this in more detail and compare some of the results to what I use in APLpy.

[ejeschke]

@cdeil, I'll take a look at the module and review. The color distribution algorithms in ginga (I prefer this term to "scaling", since image scaling has a long history of referring to resampling in traditional computer graphics) can be found here (https://github.com/ejeschke/ginga/blob/master/ginga/ColorDist.py). The docstring for each of the distributions (linear, log, power, sqrt, squared, asinh, sinh and histeq) describe the distribution function mapping y = f(x) to a range of 0..1. In ginga, this is coupled with mapping the distribution to a table of color entries (the color map), as well as providing an inverse for plotting the values to a color bar, which makes the program logic slightly more complicated than in this module being reviewed (small classes instead of methods).

From a cursory glance, it looks as if there are also auto cut levels calculations in this module. In ginga, these are found here (https://github.com/ejeschke/ginga/blob/master/ginga/AutoCuts.py), which implements minmax, histogram, stddev, median filtering, and zscale algorithms. I was never able to get satisfactorily close to IRAFs zscale results for the levels, and finally found a nice implementation by the stsci folks, which I think does a pretty close approximation.

[astrofrog]

@ejeschke - interesting, it sounds like what you do in ginga is very similar to what we do in APLpy (see e.g. the Normalize class in https://github.com/aplpy/aplpy/blob/master/aplpy/normalize.py).

[ejeschke]

@astrofrog, yes, this looks similar to what ginga does, although it looks like your class combines the cuts with the distribution. In ginga these are done as separate steps with two different classes (i.e. coming into the distribution the data has already been redistributed to the boundaries of the cuts. But I see the inverse method, which I can guess must be used by matplotlib to create the color bar. Probably the astropy module should provide this same kind of inverse, if possible.

[astrofrog]

Maybe it would be a good idea to have something similar to ginga and then have a single high-level wrapper function for users who want to use it directly?

[larrybradley]

I added a command-line script to convert FITS images to bitmap files.

[astrofrog]

I just noticed @ChrisBeaumont also has code available!

https://github.com/glue-viz/ds9norm

So... we should merge all this up into a single solution! :)

[ChrisBeaumont]

haha that didn't take long :) +1 on merging these efforts. My approach more-or-less directly wraps the logic I found in ds9 into a Matplotlib normalize class. The main difference with APLpy is (I think) the ability to set bias and contrast in addition to vmin/vmax.

[astrofrog]

As @larrybradley mentioned in astropy/photutils#132 this is already an improvement over what is currently in imageutils (since it fixes actual mistakes in the docstrings for example), so we should merge this now and then one of us can work on refactoring the scaling infrastructure again to try and generalize it to be suitable for all our different tools.