pmSubtractSky()

[gusciora@…]

What does it mean to clip a pixel (last paragraph)? Do we mask it? What do
we do with clipped pixels for?

Fitting the polynomial.
Subtracting the binned image.

What should we do if the fitSpec is PM_FIT_SPLINE? Splines are currently
defined in one dimension only. Images are two dimensional.

[Paul Price]

Binned pixels that are clipped before the polynomial is fit are not included in
the fit. The fit should still be subtracted from them. (Such clipped pixels
are likely stars in the images --- we want to remove the background from them,
but we don't want to include them in the fit, because they will make it bad.)

I fixed up the fitSpec bit in the SDRS:

The fit specification, \code{fitSpec}, specifies the order of the
polynomial or spline to be used in fitting the background.
\code{fitSpec} shall be interpreted as a polynomial, Chebyshev or
spline on the basis of \code{fit} (in the same manner as for bias
subtraction; \S\ref{sec:bias}). If \code{fitSpec} is \code{NULL} or
\code{fit} is \code{PM_FIT_NONE} or \code{PM_FIT_SPLINE}, then no fit
shall be performed, and the function shall generate a warning and
return.

[gusciora@…]

I assume we are to use psImageFitPolynomial() for fitting the Chebyshev
polynomials to the binned image. However, psImageFitPolynomial() fits the
polynomial to the entire image: pixels can not be masked, or clipped.

[gusciora@…]

Also, I'm not sure it makes sense to have a "fit" argument. It seems that there
is only a single acceptable type of fit: PM_FIT_POLYNOMIAL.

[Paul Price]

OK, let's remove the fitSpec from pmSubtractSky.

Shall we add a masking capability to psImageFitPolynomial? It shouldn't be too
hard --- a single "if" statement in the accumulation.

[Paul Price]

Updated the SDRS:

The polynomial, \code{poly}, specifies the order of the polynomial,
and on return shall contain the coefficients of the fit. If
\code{poly} is \code{NULL}, then no fit shall be performed, and the
function shall generate a warning and return.

[gusciora@…]

I'm not so sure that a simple if-statement will work. The algorithm for
determining Chebyshev polynomials requires that the function which we are
approximating (in our case, a set of data points) be evaluated at specific
points. It's not clear to me if it will work should some of those points be
masked.

[Paul Price]

The pmSubtractSky module requires the ability to mask deviant pixels. If
psImageFitPolynomial does not allow masked pixels, then we must use something
else. I suggest the old method of accumulating the matrix and finding the inverse.

[Paul Price]

Updated the definition of pmSubtractSky slightly. I had specified that the
image was to be binned before fitting, but I left out the mask (which is likely
an object mask). In addition, I have specified that clipped pixels in the
binned image may be either interpolated over, or ignored.

Updated text:

Given an input image, a polynomial or spline specifying the order of a
desired fit, a binning factor and statistics to use for the binning,
along with a clipping level, \code{pmSubtractSky} shall fit and
subtract a model for the background of the image. The API shall be
the following:
\begin{verbatim}
psReadout *pmSubtractSky(psReadout *in, psPolynomial2D *poly, psImage *mask,
psU8 maskVal,

int binFactor, psStats *stats, float clipSD);

\end{verbatim}

Note that the input image, \code{in}, shall be subtracted in-place.
The function shall return the subtracted image, and also update the
polynomial, Chebyshev or spline specified by \code{fitSpec}, to hold
the coefficients used in the subtraction.

The polynomial, \code{poly}, specifies the order of the polynomial,
and on return shall contain the coefficients of the fit. If
\code{poly} is \code{NULL}, then no fit shall be performed, and the
function shall generate a warning and return.

When fitting the polynomial, the function shall first bin the input
image by \code{binFactor} in order to reduce the required processing
time. In the binning, pixels in the \code{mask} (if non-\code{NULL})
which satisfy the \code{maskVal} shall be excluded. The statistic to
use in this binning is specified by \code{stat}. \code{stat} is of
type \code{psStats} instead of simply \code{psStatsOptions} so that
clipping levels may be specified, if desired. In the event that
multiple options are specified by \code{stats}, a warning shall be
generated, and the option with the highest priority shall be used,
according to the following priority order: \code{PS_STAT_SAMPLE_MEAN},
\code{PS_STAT_SAMPLE_MEDIAN}, \code{PS_STAT_CLIPPED_MEAN},
\code{PS_STAT_ROBUST_MEAN}, \code{PS_STAT_ROBUST_MEDIAN},
\code{PS_STAT_ROBUST_MODE}. If the \code{binFactor} is non-positive,
or \code{stats} is \code{NULL} or fails to specify an option, a
warning shall be generated, and the fit shall be performed on the
entire image.

Binned pixels deviating more than \code{clipSD} standard deviations
from the mean of the binned pixels shall be clipped in a single
clipping iteration before polynomial fitting. These pixels may be
interpolated over, or may be simply ignored in the fitting, according
to the choice of algorithm. If the \code{clipSD} is non-positive,
then the function shall generate a warning and not perform any
clipping.

The \code{mask} shall be of type \code{psU8}, and the input image,
\code{in}, shall be of type \code{psF32}.