SpatialCell.h

Go to the documentation of this file.

// -*- lsst-c++ -*-

/* 
 * LSST Data Management System
 * Copyright 2008, 2009, 2010 LSST Corporation.
 * 
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the LSST License Statement and 
 * the GNU General Public License along with this program.  If not, 
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */
 
#ifndef LSST_AFW_MATH_SPATIALCELL_H
#define LSST_AFW_MATH_SPATIALCELL_H

#include <limits>
#include <vector>
#include <string>

#include "boost/shared_ptr.hpp"
#include "lsst/base.h"
#include "lsst/pex/exceptions.h"
#include "lsst/afw/geom.h"
#include "lsst/afw/image/LsstImageTypes.h"

namespace lsst {
namespace afw {

// forward declarations    
namespace image {
    template<typename ImagePixelT> class Image;
    template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT> class MaskedImage;
}

namespace math {

    /********************************************************************************************************/
    class SpatialCellCandidate;

    class CandidateVisitor {
    public:
        CandidateVisitor() {}
        virtual ~CandidateVisitor() {}

        virtual void reset() {}
        virtual void processCandidate(SpatialCellCandidate *) {}
    };

    /************************************************************************************************************/
    class SpatialCellCandidate {
    public:
        typedef boost::shared_ptr<SpatialCellCandidate> Ptr;
        typedef boost::shared_ptr<const SpatialCellCandidate> ConstPtr;

        enum Status {BAD = 0, GOOD = 1, UNKNOWN = 2};

        SpatialCellCandidate(float const xCenter, 
                             float const yCenter  
                    ) :
            _id(++_CandidateId),
            _status(UNKNOWN),
            _xCenter(xCenter), _yCenter(yCenter) {
        }

        virtual ~SpatialCellCandidate() {}

        float getXCenter() const { return _xCenter; }

        float getYCenter() const { return _yCenter; }

        virtual bool instantiate() { return true; }

        virtual double getCandidateRating() const = 0;
        virtual void setCandidateRating(double) {}

        int getId() const { return _id; }
        Status getStatus() const { return _status; }
        void setStatus(Status status);
        virtual bool isBad() const {
            return (_status == BAD);
        }
    private:
        int _id;                        // Unique ID for object
        Status _status;                 // Is this Candidate good?
        float const _xCenter;           // The object's column-centre
        float const _yCenter;           // The object's row-centre

        static int _CandidateId;        // Unique identifier for candidates; useful for preserving current candidate
                                        // following insertion
    };

    /************************************************************************************************************/
    template<typename PixelT>
    class SpatialCellImageCandidate : public SpatialCellCandidate {
    public:
        typedef boost::shared_ptr<SpatialCellImageCandidate> Ptr;
        typedef boost::shared_ptr<const SpatialCellImageCandidate> ConstPtr;

        SpatialCellImageCandidate(float const xCenter, 
                                  float const yCenter  
                                 ) : SpatialCellCandidate(xCenter, yCenter),
                                     _image(PTR(lsst::afw::image::Image<PixelT>)()),
                                     _chi2(std::numeric_limits<double>::max()) {
        }
        virtual ~SpatialCellImageCandidate() {}

        virtual CONST_PTR(lsst::afw::image::Image<PixelT>) getImage() const = 0;

        static void setWidth(int width) {
            _width = width;
        }
        static int getWidth() { return _width; }

        static void setHeight(int height) { _height = height; }
        static int getHeight() { return _height; }

        double getChi2() const { return _chi2; }
        void setChi2(double chi2) { _chi2 = chi2; }

    protected:
        PTR(lsst::afw::image::Image<PixelT>) mutable _image; 
    private:
        static int _width;              // the width of images to return; may be ignored by subclasses
        static int _height;             // the height of images to return; may be ignored by subclasses
        double _chi2;                   // chi^2 for fit
    };

    template<typename PixelT>
    int SpatialCellImageCandidate<PixelT>::_width = 0;

    template<typename PixelT>
    int SpatialCellImageCandidate<PixelT>::_height = 0;

    /************************************************************************************************************/
    template<typename PixelT>
    class SpatialCellMaskedImageCandidate : public SpatialCellCandidate {
    public:
        typedef boost::shared_ptr<SpatialCellMaskedImageCandidate> Ptr;
        typedef boost::shared_ptr<const SpatialCellMaskedImageCandidate> ConstPtr;

        SpatialCellMaskedImageCandidate(float const xCenter, 
                                        float const yCenter  
                                       ) : SpatialCellCandidate(xCenter, yCenter),
                                           _image(PTR(lsst::afw::image::MaskedImage<PixelT,
                                                      lsst::afw::image::MaskPixel,
                                                      lsst::afw::image::VariancePixel>)()),
                                           _chi2(std::numeric_limits<double>::max()) {
        }
        virtual ~SpatialCellMaskedImageCandidate() {}

        virtual CONST_PTR(lsst::afw::image::MaskedImage<PixelT,lsst::afw::image::MaskPixel,
                          lsst::afw::image::VariancePixel>) getMaskedImage() const = 0;

        static void setWidth(int width) {
            _width = width;
        }
        static int getWidth() { return _width; }

        static void setHeight(int height) { _height = height; }
        static int getHeight() { return _height; }

        double getChi2() const { return _chi2; }
        void setChi2(double chi2) { _chi2 = chi2; }

    protected:
        PTR(lsst::afw::image::MaskedImage<PixelT,lsst::afw::image::MaskPixel,
            lsst::afw::image::VariancePixel>) mutable _image; 
    private:
        static int _width;              // the width of images to return; may be ignored by subclasses
        static int _height;             // the height of images to return; may be ignored by subclasses
        double _chi2;                   // chi^2 for fit
    };

    template<typename PixelT>
    int SpatialCellMaskedImageCandidate<PixelT>::_width = 0;

    template<typename PixelT>
    int SpatialCellMaskedImageCandidate<PixelT>::_height = 0;

    /************************************************************************************************************/
    class SpatialCellCandidateIterator {
        friend class SpatialCell;
        typedef std::vector<PTR(SpatialCellCandidate)> CandidateList;

    public:
        // ctors are protected
        void operator++();
        size_t operator-(SpatialCellCandidateIterator const& rhs) const;

        CONST_PTR(SpatialCellCandidate) operator*() const;
        PTR(SpatialCellCandidate)       operator*();

        bool operator==(SpatialCellCandidateIterator const& rhs) const {
            return _iterator == rhs._iterator;
        }
        bool operator!=(SpatialCellCandidateIterator const& rhs) const {
            return _iterator != rhs._iterator;
        }

    protected:
        SpatialCellCandidateIterator(CandidateList::iterator iterator, CandidateList::iterator end, bool ignoreBad);
        SpatialCellCandidateIterator(CandidateList::iterator iterator, CandidateList::iterator end, bool ignoreBad, bool);

    private:
        CandidateList::iterator _iterator;
        CandidateList::iterator _end;
        bool _ignoreBad;
    };

    /************************************************************************************************************/
    class SpatialCell {
    public:
        typedef boost::shared_ptr<SpatialCell> Ptr;
        typedef boost::shared_ptr<const SpatialCell> ConstPtr;
        typedef std::vector<PTR(SpatialCellCandidate)> CandidateList;
        typedef SpatialCellCandidateIterator iterator;
        SpatialCell(std::string const& label,
                    lsst::afw::geom::Box2I const& bbox=lsst::afw::geom::Box2I(),
                    CandidateList const& candidateList=CandidateList());
        
        virtual ~SpatialCell() {;};

        bool empty() const;
        size_t size() const;

        void sortCandidates();
        SpatialCellCandidateIterator begin() {
            return SpatialCellCandidateIterator(_candidateList.begin(), _candidateList.end(), _ignoreBad);
        }
        SpatialCellCandidateIterator begin(bool ignoreBad 
                                          ) {
            return SpatialCellCandidateIterator(_candidateList.begin(), _candidateList.end(), ignoreBad);
        }
        SpatialCellCandidateIterator end() {
            return SpatialCellCandidateIterator(_candidateList.begin(), _candidateList.end(), _ignoreBad, true);
        }
        SpatialCellCandidateIterator end(bool ignoreBad 
                                        ) {
            return SpatialCellCandidateIterator(_candidateList.begin(), _candidateList.end(), ignoreBad, true);
        }
        //
        void insertCandidate(PTR(SpatialCellCandidate) candidate);

        void removeCandidate(PTR(SpatialCellCandidate) candidate);

        void setIgnoreBad(bool ignoreBad) { _ignoreBad = ignoreBad; }
        bool getIgnoreBad() const { return _ignoreBad; }

        PTR(SpatialCellCandidate) getCandidateById(int id, bool noThrow=false);
        std::string const& getLabel() const { return _label; }
        lsst::afw::geom::Box2I const& getBBox() const { return _bbox; }
        /*
         * Visit our candidates
         */
        void visitCandidates(CandidateVisitor * visitor, int const nMaxPerCell=-1,
                             bool const ignoreExceptions=false, bool const reset=true);
        void visitCandidates(CandidateVisitor * visitor, int const nMaxPerCell=-1,
                             bool const ignoreExceptions=false, bool const reset=true) const;
        void visitAllCandidates(CandidateVisitor * visitor,
                                bool const ignoreExceptions=false, bool const reset=true);
        void visitAllCandidates(CandidateVisitor * visitor,
                                bool const ignoreExceptions=false, bool const reset=true) const;

    private:
        std::string _label;             // Name of cell for logging/trace
        lsst::afw::geom::Box2I _bbox;   // Bounding box of cell in overall image
        CandidateList _candidateList;   // List of all candidates in the cell
        bool _ignoreBad;                // Don't include BAD candidates when traversing the list
    };
    
    class SpatialCellSet {
    public:
        typedef boost::shared_ptr<SpatialCellSet> Ptr;
        typedef boost::shared_ptr<const SpatialCellSet> ConstPtr;
        
        typedef std::vector<PTR(SpatialCell)> CellList;

        SpatialCellSet(lsst::afw::geom::Box2I const& region, int xSize, int ySize=0);
        
        virtual ~SpatialCellSet() {;};

        CellList& getCellList() { return _cellList; }
        
        lsst::afw::geom::Box2I getBBox() const { return _region; };

        void insertCandidate(PTR(SpatialCellCandidate) candidate);

        void sortCandidates();

        void visitCandidates(CandidateVisitor * visitor, int const nMaxPerCell=-1,
                             bool const ignoreExceptions=false);
        void visitCandidates(CandidateVisitor * visitor, int const nMaxPerCell=-1,
                             bool const ignoreExceptions=false) const;
        void visitAllCandidates(CandidateVisitor * visitor, bool const ignoreExceptions=false);
        void visitAllCandidates(CandidateVisitor * visitor, bool const ignoreExceptions=false) const;

        PTR(SpatialCellCandidate) getCandidateById(int id, bool noThrow=false);

        void setIgnoreBad(bool ignoreBad);

    private:
        lsst::afw::geom::Box2I _region;   // Bounding box of overall image
        CellList _cellList;               // List of SpatialCells
    };
}}}

#endif