Merge pull request #51 from GalSim-developers/#21_DOxygen_documentation

#21 DOxygen documentation - merged to incorporate changes to centroid() handling ASAP

docs/SBProfile.tex

@@ -62,7 +62,7 @@ \subsection{Evaluation methods}
 \begin{itemize}
 \item {\tt DComplex kValue(Position$<$double$>$ p)} returns the value of the \sbp\ transform at a specified position in $k$ space.
 \item {\tt double xValue(Position$<$double$>$ p)} returns the value of the \sbp\ at a specified position in real space.  Some derived classes, {\it e.g.} {\tt SBConvolve}, throw an exception for this method because real-space values are only obtainable via FFT, as indicated by a {\tt false} return from {\tt isAnalyticX()}.
-\item {\tt  double centroidX(), centroidY()} return the centroid of the \sbp.\footnote{Will fail if flux is zero.  Currently will throw an exception for {\tt SBLaguerre} because I have been too lazy to code the calculation.}
+\item {\tt  Position<double> centroid()} returns the (x, y) centroid of the \sbp.\footnote{Will fail if flux is zero.  Currently will throw an exception for {\tt SBLaguerre} because I have been too lazy to code the calculation.}
 \item {\tt  Position$<$double$>$ centroid()} simply returns both coordinates of the centroid in a {\tt Position} object.
 \item {\tt double getFlux()} returns the object flux $f$.
 \end{itemize}

include/galsim/SBDeconvolve.h

@@ -1,6 +1,7 @@
-
-// SBProfile adapter which inverts its subject in k space to
-// effecta  deconvolution
+/** 
+ * @file SBDeconvolve.h @brief SBProfile adapter which inverts its subject in k space to effect a
+ * deconvolution.
+ */
 
 #ifndef SBDECONVOLVE_H
 #define SBDECONVOLVE_H
@@ -13,15 +14,23 @@
 
 namespace galsim {
 
+    /**
+     * @brief SBProfile adapter which inverts its subject in k space to effect a deconvolvution.
+     *
+     * (TODO: Add more docs here!)
+     */
     class SBDeconvolve : public SBProfile 
     {
     public:
+        /// @brief Constructor.
         SBDeconvolve(const SBProfile& adaptee_) : adaptee(adaptee_.duplicate()) 
             { maxksq = pow(maxK(),2.); }
 
+        /// @brief Copy constructor.
         SBDeconvolve(const SBDeconvolve& rhs) : adaptee(rhs.adaptee->duplicate()) 
             { maxksq = pow(maxK(),2.); }
 
+        /// @brief Operator (TODO: ask Gary about this bit...)
         SBDeconvolve& operator=(const SBDeconvolve& rhs)
             {
                 if (&rhs == this) return *this;
@@ -34,11 +43,14 @@ namespace galsim {
                 return *this;
             }
 
+        /// @brief Destructor.
         ~SBDeconvolve() { delete adaptee; }
 
         SBProfile* duplicate() const { return new SBDeconvolve(*this); }
 
         // These are all the base class members that must be implemented:
+
+        /// @brief xValue() not implemented for SBDeconvolve.
         double xValue(Position<double> p) const 
         { throw SBError("SBDeconvolve::xValue() not implemented"); }
 
@@ -58,8 +70,9 @@ namespace galsim {
         bool isAnalyticX() const { return false; }
         bool isAnalyticK() const { return true; }
 
-        double centroidX() const { return -adaptee->centroidX(); }
-        double centroidY() const { return -adaptee->centroidY(); }
+        Position<double> centroid() const { return -adaptee->centroid(); }
+
+        /// @brief setCentroid() not implemented for SBDeconvolve.
         void setCentroid(Position<double> _p) 
         { throw SBError("setCentroid not allowed for SBDeconvolve"); }
 

include/galsim/SBPixel.h

@@ -89,8 +89,7 @@ namespace galsim {
         bool isAnalyticX() const { return true; }
         bool isAnalyticK() const { return true; }
 
-        double centroidX() const;
-        double centroidY() const;
+        Position<double> centroid() const;
 
         double getFlux() const;
         void setFlux(double flux=1.);  // This will scale the weights vector

include/galsim/SBProfile.h

@@ -150,13 +150,8 @@ namespace galsim {
          */
         virtual bool isAnalyticK() const =0; 
 
-        virtual double centroidX() const =0; ///<Centroid of SBProfile in x.
-        virtual double centroidY() const =0; ///<Centroid of SBProfile in y.
-
         /// @brief Returns (X, Y) centroid of SBProfile.
-        Position<double> centroid() const 
-        { Position<double> p(centroidX(),centroidY());  return p; }
-
+        virtual Position<double> centroid() const = 0;
 
         virtual double getFlux() const =0; ///< Get the total flux of the SBProfile.
 
@@ -225,6 +220,8 @@ namespace galsim {
          * image  may be calculated internally on a larger grid to avoid folding.
          * The default draw() routines decide internally whether image can be drawn directly
          * in real space or needs to be done via FFT from k space.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in] dx    grid on which SBProfile is drawn has pitch `dx`; given `dx=0.` default, 
          *                  routine will choose `dx` to be at least fine enough for Nyquist sampling
@@ -247,6 +244,8 @@ namespace galsim {
          * image may be calculated internally on a larger grid to avoid folding.
          * The default draw() routines decide internally whether image can be drawn directly
          * in real space or needs to be done via FFT from k space.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   image
          * @param[in] dx    grid on which SBProfile is drawn has pitch `dx`; given `dx=0.` default, 
@@ -268,6 +267,8 @@ namespace galsim {
          * drawn which is big enough to avoid "folding." 
          * If input image has finite dimensions then these will be used, although in an FFT the 
          * image may be calculated internally on a larger grid to avoid folding.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   image
          * @param[in] dx    grid on which SBProfile is drawn has pitch `dx`; given `dx=0.` default, 
@@ -290,6 +291,8 @@ namespace galsim {
          * and the image will be scaled up to a power of 2, or 3x2^n, whicher fits.
          * If input image has finite dimensions then these will be used, although in an FFT the 
          * image may be calculated internally on a larger grid to avoid folding.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   image
          * @param[in] dx    grid on which SBProfile is drawn has pitch `dx`; given `dx=0.` default, 
@@ -313,6 +316,8 @@ namespace galsim {
          * FFT, they will be scaled up to a power of 2, or 3x2^n, whicher fits.
          * If input image has finite dimensions then these will be used, although in an FFT the 
          * image may be calculated internally on a larger grid to avoid folding in real space.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   re image of real argument of SBProfile in k space.
          * @param[in,out]   im image of imaginary argument of SBProfile in k space.
@@ -332,6 +337,8 @@ namespace galsim {
          * needed since the SBProfile is complex.  If on input either image `Re` or `Im` is not 
          * specified or has null dimension, square images will be drawn which are big enough to 
          * avoid "folding."
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   re image of real argument of SBProfile in k space.
          * @param[in,out]   im image of imaginary argument of SBProfile in k space.
@@ -356,6 +363,8 @@ namespace galsim {
          * and the images will be scaled up to a power of 2, or 3x2^n, whicher fits.
          * If input image has finite dimensions then these will be used, although in an FFT the 
          * image may be calculated internally on a larger grid to avoid folding in real space.
+         * Note that if you give an input image, its origin may be redefined by the time it comes 
+         * back.
          *
          * @param[in,out]   re image of real argument of SBProfile in k space.
          * @param[in,out]   im image of imaginary argument of SBProfile in k space.
@@ -530,8 +539,8 @@ namespace galsim {
         bool isAnalyticX() const { return allAnalyticX; }
         bool isAnalyticK() const { return allAnalyticK; }
 
-        virtual double centroidX() const { return sumfx / sumflux; }
-        virtual double centroidY() const { return sumfy / sumflux; }
+        virtual Position<double> centroid() const 
+        {Position<double> p(sumfx / sumflux, sumfy / sumflux); return p; }
 
         virtual double getFlux() const { return sumflux; }
         virtual void setFlux(double flux_=1.);
@@ -548,8 +557,7 @@ namespace galsim {
      * Origin of original shape will now appear at `x0`.
      * Flux is NOT conserved in transformation - surface brightness is preserved.
      * We keep track of all distortions in a 2x2 matrix `M = [(A B), (C D)]` = [row1, row2] 
-     * (det`M`=1), with an additional determinant multiplier `absdet`, plus a 2-element `x0` for
-     * the shift.
+     * plus a 2-element Positon object `x0` for the shift.
      */
     class SBDistort : public SBProfile 
     {
@@ -688,8 +696,7 @@ namespace galsim {
         double maxK() const { return adaptee->maxK() / minor; }
         double stepK() const { return adaptee->stepK() / major; }
 
-        double centroidX() const { return (x0+fwd(adaptee->centroid())).x; }
-        double centroidY() const { return (x0+fwd(adaptee->centroid())).y; }
+        Position<double> centroid() const { return x0+fwd(adaptee->centroid()); }
 
         double getFlux() const { return adaptee->getFlux()*absdet; }
         void setFlux(double flux_=1.) { adaptee->setFlux(flux_/absdet); }
@@ -850,8 +857,10 @@ namespace galsim {
         bool isAnalyticK() const { return true; }    // convolvees must all meet this
         double maxK() const { return minMaxK; }
         double stepK() const { return minStepK; }
-        double centroidX() const { return x0; }
-        double centroidY() const { return y0; }
+
+        Position<double> centroid() const 
+        { Position<double> p(x0, y0); return p; }
+
         double getFlux() const { return fluxScale * fluxProduct; }
         void setFlux(double flux_=1.) { fluxScale = flux_/fluxProduct; }
 
@@ -900,8 +909,9 @@ namespace galsim {
         double maxK() const { return std::max(4., std::sqrt(-2.*log(ALIAS_THRESHOLD))) / sigma; }
         double stepK() const { return M_PI/std::max(4., 
                                                     std::sqrt(-2.*log(ALIAS_THRESHOLD))) / sigma; }
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
+
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
         SBProfile* duplicate() const { return new SBGaussian(*this); }
@@ -1041,8 +1051,8 @@ namespace galsim {
         double maxK() const { return info->maxK / re; }
         double stepK() const { return info->stepK / re; }
 
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
 
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
@@ -1092,8 +1102,8 @@ namespace galsim {
         double maxK() const { return std::max(10., pow(ALIAS_THRESHOLD, -1./3.))/r0; }
         double stepK() const;
 
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
 
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
@@ -1158,8 +1168,9 @@ namespace galsim {
                 ALIAS_THRESHOLD * 0.5 * D * pow(M_PI,3.) * (1-obscuration) ,
                 M_PI * D / 5.);
         }
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
 
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
@@ -1228,8 +1239,8 @@ namespace galsim {
         double maxK() const { return 2. / ALIAS_THRESHOLD / std::max(xw,yw); }  
         double stepK() const { return M_PI/std::max(xw,yw)/2; } 
 
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
 
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
@@ -1282,9 +1293,7 @@ namespace galsim {
         bool isAnalyticX() const { return true; }
         bool isAnalyticK() const { return true; }
 
-        double centroidX() const 
-        { throw SBError("SBLaguerre::centroid calculations not yet implemented"); }
-        double centroidY() const 
+        Position<double> centroid() const 
         { throw SBError("SBLaguerre::centroid calculations not yet implemented"); }
 
         double getFlux() const;
@@ -1350,8 +1359,9 @@ namespace galsim {
         double maxK() const { return maxKrD / rD; }   
         double stepK() const { return stepKrD / rD; } 
 
-        double centroidX() const { return 0.; } 
-        double centroidY() const { return 0.; } 
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
+
 
         double getFlux() const { return flux; }
         void setFlux(double flux_=1.) { flux=flux_; }
@@ -1409,6 +1419,11 @@ namespace galsim {
 
         /// @brief Copy constructor.
         SBProfile* duplicate() const { return new SBDeVaucouleurs(*this); }
+
+        Position<double> centroid() const 
+        { Position<double> p(0., 0.); return p; }
+
+
     };
 
 

pysrc/SBProfile.cpp

@@ -67,8 +67,6 @@ struct PySBProfile {
             .def("isAxisymmetric", &SBProfile::isAxisymmetric)
             .def("isAnalyticX", &SBProfile::isAnalyticX,
                  "True if real-space values can be determined immediately at any position with FT")
-            .def("centroidX", &SBProfile::centroidX)
-            .def("centroidY", &SBProfile::centroidY)
             .def("centroid", &SBProfile::centroid)
             .def("getFlux", &SBProfile::getFlux)
             .def("setFlux", &SBProfile::setFlux)

src/SBPixel.cpp

@@ -105,16 +105,12 @@ namespace galsim {
         if (ksumValid) *ksum *= factor;
     }
 
-    double SBPixel::centroidX() const 
+    Position<double> SBPixel::centroid() const 
     {
         checkReady();
-        return (wts * xFluxes) / (wts*fluxes);
-    }
-
-    double SBPixel::centroidY() const 
-    {
-        checkReady();
-        return (wts * yFluxes) / (wts*fluxes);
+        double wtsfluxes = wts * fluxes;
+        Position<double> p((wts * xFluxes) / wtsfluxes, (wts * yFluxes) / wtsfluxes);
+        return p;
     }
 
     void SBPixel::setPixel(double value, int ix, int iy, int iz) 

src/SBProfile.cpp

@@ -445,8 +445,8 @@ namespace galsim {
         // Accumulate properties of all summands
         while (newptr != plist.end()) {
             sumflux += (*newptr)->getFlux();
-            sumfx += (*newptr)->getFlux() * (*newptr)->centroidX();
-            sumfy += (*newptr)->getFlux() * (*newptr)->centroidY();
+            sumfx += (*newptr)->getFlux() * (*newptr)->centroid().x;
+            sumfy += (*newptr)->getFlux() * (*newptr)->centroid().x;
             if ( (*newptr)->maxK() > maxMaxK) maxMaxK = (*newptr)->maxK();
             if ( minStepK<=0. || ((*newptr)->stepK() < minStepK)) minStepK = (*newptr)->stepK();
             allAxisymmetric = allAxisymmetric && (*newptr)->isAxisymmetric();
@@ -679,8 +679,8 @@ namespace galsim {
         // Accumulate properties of all terms
         while (newptr != plist.end()) {
             fluxProduct *= (*newptr)->getFlux();
-            x0 += (*newptr)->centroidX();
-            y0 += (*newptr)->centroidY();
+            x0 += (*newptr)->centroid().x;
+            y0 += (*newptr)->centroid().y;
             if ( minMaxK<=0. || (*newptr)->maxK() < minMaxK) minMaxK = (*newptr)->maxK();
             if ( minStepK<=0. || ((*newptr)->stepK() < minStepK)) minStepK = (*newptr)->stepK();
             isStillAxisymmetric = isStillAxisymmetric && (*newptr)->isAxisymmetric();