source: GTP/trunk/Lib/Vis/Preprocessing/src/VspOspTree.h @ 1006

#ifndef _VspOspTree_H__
#define _VspOspTree_H__

#include "Mesh.h"
#include "Containers.h"
#include "Polygon3.h"
#include <stack>
#include "Statistics.h"
#include "VssRay.h"
#include "RayInfo.h"
#include "ViewCellBsp.h"



namespace GtpVisibilityPreprocessor {

class ViewCellLeaf;
//class BspViewCell;
class Plane3;
class VspBspTree;  
class BspInterior;
class BspNode;
class AxisAlignedBox3;
class Ray;
class ViewCellsStatistics;
class ViewCellsManager;
class MergeCandidate;
class Beam;
class ViewCellsTree;
class Environment;

/**
        This class implements a structure holding two different hierarchies,
        one for object space partitioning and one for view space partitioning.

        The object space and the view space are subdivided using a cost heuristics.
        If an object space split or a view space split is chosen is also evaluated
        based on the heuristics. 
        
        The view space heuristics is evaluated by weighting and adding the pvss of the back and
        front node of each specific split. unlike for the standalone method vspbsp tree,
        the pvs of an object would not be the pvs of single object but that of all objects
        which are contained in the same leaf of the object subdivision. This could be done
        by storing the pointer to the object space partition parent, which would allow access to all children.
        Another possibility is to include traced kd-cells in the ray casing process.

        Accordingly, the object space heuristics is evaluated by storing a pvs of view cells with each object.
        the contribution to an object to the pvs is the number of view cells it can be seen from.


        There is a potential efficiency problem involved in a sense that once a certain type
        of split is chosen for view space / object space, the candidates for the next split of 
        object space / view space must be reevaluated.
        
*/
class VspOspTree 
{
        friend class ViewCellsParseHandlers;
        friend class VspBspViewCellsManager;

public:
        
        /** A definition for an axis aligned plane.
        */
        struct AxisAlignedPlane
        {
        public:
                int mAxis;
                float mPosition;
        };

        /** Additional data which is passed down the BSP tree during traversal.
        */
        class VspOspTraversalData
        {  
        public:
                /// the current node
                BspNode *mNode;
                /// current depth
                int mDepth;
                /// rays piercing this node
                RayInfoContainer *mRays;
                /// the probability that this node contains view point
                float mProbability;
                /// the bounding box of the node
                AxisAlignedBox3 mBoundingBox;
                /// pvs size
                int mPvs;
                /// how often this branch has missed the max-cost ratio
                int mMaxCostMisses;
                // current axis
                int mAxis;
                // current priority
                float mPriority;

                
                /** Returns average ray contribution.
                */
                float GetAvgRayContribution() const
                {
                        return (float)mPvs / ((float)mRays->size() + Limits::Small);
                }


                VspOspTraversalData():
                mNode(NULL),
                mDepth(0),
                mRays(NULL),
                mPvs(0),
                mProbability(0.0),
                mMaxCostMisses(0), 
                mPriority(0),
                mAxis(0)
                {}
                
                VspOspTraversalData(BspNode *node, 
                                                        const int depth, 
                                                        RayInfoContainer *rays,
                                                        const int pvs,
                                                        const float p,
                                                        const AxisAlignedBox3 &box): 
                mNode(node), 
                mDepth(depth), 
                mRays(rays),
                mPvs(pvs),
                mProbability(p),
                mBoundingBox(box),
                mMaxCostMisses(0),
                mPriority(0),
                mAxis(0)
                {}

                VspOspTraversalData(PolygonContainer *polys, 
                                                        const int depth, 
                                                        RayInfoContainer *rays,
                                                        const AxisAlignedBox3 &box): 
                mNode(NULL), 
                mDepth(depth), 
                mRays(rays),
                mPvs(0),
                mProbability(0),
                mMaxCostMisses(0),
                mAxis(0),
                mBoundingBox(box)
                {}

                /** Returns cost of the traversal data.
                */
                float GetCost() const
                {
                        //cout << mPriority << endl;
                        return mPriority;
                }

                // deletes contents and sets them to NULL
                void Clear()
                {
                        DEL_PTR(mRays);
                }

                friend bool operator<(const VspOspTraversalData &a, const VspOspTraversalData &b)
                {
                        return a.GetCost() < b.GetCost();
                }
    };
        

        typedef std::priority_queue<VspOspTraversalData> VspOspTraversalQueue;
        
        
        struct VspOspSplitCandidate
        {  
                /// the current plane
                AxisAlignedPlane mSplitPlane;
                /// the number of misses of max cost ratio until this split
                int mMaxCostMisses;
                /// parent data
                VspOspTraversalData mParentData;
                /// cost of applying this split
                float mRenderCost;

                VspOspSplitCandidate(): mRenderCost(0) 
                {};

                VspOspSplitCandidate(const AxisAlignedPlane &plane, const VspOspTraversalData &tData): 
                mSplitPlane(plane), mParentData(tData), mRenderCost(0)
                {}

                /** Returns cost of the traversal data.
                */
                float GetCost() const
                {
#if 1
                        return mRenderCost;
#endif
#if 0
                        return (float) (-mDepth); // for kd tree
#endif
                }

                friend bool operator<(const VspOspSplitCandidate &a, const VspOspSplitCandidate &b)
                {
                        return a.GetCost() < b.GetCost();
                }
    };

        typedef std::priority_queue<VspOspSplitCandidate> VspOspSplitQueue;

        /** Default constructor creating an empty tree.
        */ 
        VspOspTree();

        /** Default destructor.
        */
        ~VspOspTree();

        /** Returns BSP Tree statistics.
        */
        const BspTreeStatistics &GetStatistics() const; 
  

        /** Constructs the tree from a given set of rays.
                @param sampleRays the set of sample rays the construction is based on
                @param viewCells if not NULL, new view cells are 
                created in the leafs and stored in the container
        */
        void Construct(const VssRayContainer &sampleRays,
                                   AxisAlignedBox3 *forcedBoundingBox);

        /** Returns list of BSP leaves with pvs smaller than
                a certain threshold.
                @param onlyUnmailed if only the unmailed leaves should be considered
                @param maxPvs the maximal pvs (-1 means unlimited)
        */
        void CollectLeaves(vector<BspLeaf *> &leaves, 
                                           const bool onlyUnmailed = false,
                                           const int maxPvs = -1) const;

        /** Returns box which bounds the whole tree.
        */
        AxisAlignedBox3 GetBoundingBox()const;

        /** Returns root of BSP tree.
        */
        BspNode *GetRoot() const;

        /** Collects the leaf view cells of the tree
                @param viewCells returns the view cells 
        */
        void CollectViewCells(ViewCellContainer &viewCells, bool onlyValid) const;

        /** A ray is cast possible intersecting the tree.
                @param the ray that is cast.
                @returns the number of intersections with objects stored in the tree.
        */
        int CastRay(Ray &ray);


        /** finds neighbouring leaves of this tree node.
        */
        int FindNeighbors(BspNode *n, 
                                          vector<BspLeaf *> &neighbors, 
                                          const bool onlyUnmailed) const;

        /** Returns random leaf of BSP tree.
                @param halfspace defines the halfspace from which the leaf is taken.
        */
        BspLeaf *GetRandomLeaf(const Plane3 &halfspace);

        /** Returns random leaf of BSP tree.
                @param onlyUnmailed if only unmailed leaves should be returned.
        */
        BspLeaf *GetRandomLeaf(const bool onlyUnmailed = false);

        /** Returns epsilon of this tree.
        */
        float GetEpsilon() const;

        /** Casts line segment into the tree.
                @param origin the origin of the line segment
                @param termination the end point of the line segment
                @returns view cells intersecting the line segment.
        */
    int CastLineSegment(const Vector3 &origin,
                                                const Vector3 &termination,
                                                ViewCellContainer &viewcells);

                
        /** Sets pointer to view cells manager.
        */
        void SetViewCellsManager(ViewCellsManager *vcm);

        /** Returns distance from node 1 to node 2.
        */
        int TreeDistance(BspNode *n1, BspNode *n2) const;

        /** Collapses the tree with respect to the view cell partition.
                @returns number of collapsed nodes
        */
        int CollapseTree();

        /** Returns view cell the current point is located in.
                @param point the current view point
                @param active if currently active view cells should be returned or
                elementary view cell
        */
        ViewCell *GetViewCell(const Vector3 &point, const bool active = false);


        /** Returns true if this view point is in a valid view space,
                false otherwise.
        */
        bool ViewPointValid(const Vector3 &viewPoint) const;

        /** Returns view cell corresponding to 
                the invalid view space.
        */
        BspViewCell *GetOutOfBoundsCell();

        /** Writes tree to output stream
        */
#if ZIPPED_VIEWCELLS
        bool Export(ogzstream &stream);
#else
        bool Export(ofstream &stream);
#endif

        /** Casts beam, i.e. a 5D frustum of rays, into tree.
                Tests conservative using the bounding box of the nodes.
                @returns number of view cells it intersected
        */
        int CastBeam(Beam &beam);

        /** Finds approximate neighbours, i.e., finds correct neighbors
                in most cases but sometimes more.
        */
        int FindApproximateNeighbors(BspNode *n, 
                                                             vector<BspLeaf *> &neighbors,
                                                                 const bool onlyUnmailed) const;

        /** Checks if tree validity-flags are right 
                with respect to view cell valitiy.
                If not, marks subtree as invalid.
        */
        void ValidateTree();

        /** Invalid view cells are added to the unbounded space
        */
        void CollapseViewCells();

        /** Collects rays stored in the leaves.
        */
        void CollectRays(VssRayContainer &rays);

        /** Intersects box with the tree and returns the number of intersected boxes.
                @returns number of view cells found
        */
        int ComputeBoxIntersections(const AxisAlignedBox3 &box, ViewCellContainer &viewCells) const;

        // pointer to the hierarchy of view cells
        ViewCellsTree *mViewCellsTree;


protected:

        // --------------------------------------------------------------
        // For sorting objects
        // --------------------------------------------------------------
        struct SortableEntry
        {
                enum EType 
                {
                        ERayMin,
                        ERayMax
                };

                int type;
                float value;
                VssRay *ray;
  
                SortableEntry() {}
                SortableEntry(const int t, const float v, VssRay *r):type(t),
                                          value(v), ray(r) 
                {
                }
                
                friend bool operator<(const SortableEntry &a, const SortableEntry &b) 
                {
                        return a.value < b.value;
                }
        };

        /** faster evaluation of split plane cost for kd axis aligned cells.
        */
        float EvalSplitCost(const VspOspTraversalData &data,
                                                const AxisAlignedBox3 &box,
                                                const int axis,
                                                const float &position,
                                                float &pFront,
                                                float &pBack) const;

        /** Evaluates candidate for splitting.
        */
        void EvalSplitCandidate(VspOspTraversalData &tData, VspOspSplitCandidate &splitData);

        /** Computes priority of the traversal data and stores it in tData.
        */
        void EvalPriority(VspOspTraversalData &tData) const;

        /** Evaluates render cost decrease of next split.
        */
        float EvalRenderCostDecrease(const Plane3 &candidatePlane,
                                                                 const VspOspTraversalData &data) const;

        /** Constructs tree using the split priority queue.
        */
        void Construct(RayInfoContainer *rays);

        /** Collects view cells in the subtree under root.
        */
        void CollectViewCells(BspNode *root, 
                                                  bool onlyValid, 
                                                  ViewCellContainer &viewCells,
                                                  bool onlyUnmailed = false) const;

        /** Returns view cell corresponding to 
                the invalid view space. If it does not exist, it is created.
        */
        BspViewCell *GetOrCreateOutOfBoundsCell();

        /** Collapses the tree with respect to the view cell partition,
                i.e. leaves having the same view cell are collapsed.
                @param node the root of the subtree to be collapsed
                @param collapsed returns the number of collapsed nodes
                @returns node of type leaf if the node could be collapsed, 
                this node otherwise
        */
        BspNode *CollapseTree(BspNode *node, int &collapsed);

        /** Helper function revalidating the view cell leaf list after merge.
        */
        void RepairViewCellsLeafLists();

        /** Evaluates tree stats in the BSP tree leafs.
        */
        void EvaluateLeafStats(const VspOspTraversalData &data);

        /** Subdivides node with respect to the traversal data.
            @param tStack current traversal stack
                @param tData traversal data also holding node to be subdivided
                @returns new root of the subtree
        */
        BspNode *Subdivide(VspOspSplitQueue &tQueue,
                                           VspOspSplitCandidate &splitCandidate);

        
        /** Subdivides leaf.
                @param leaf the leaf to be subdivided
                
                @param polys the polygons to be split
                @param frontPolys returns the polygons in front of the split plane
                @param backPolys returns the polygons in the back of the split plane
                
                @param rays the polygons to be filtered
                @param frontRays returns the polygons in front of the split plane
                @param backRays returns the polygons in the back of the split plane

                @returns the root of the subdivision
        */

        BspInterior *SubdivideNode(const Plane3 &splitPlane,
                                                           VspOspTraversalData &tData,
                                                           VspOspTraversalData &frontData,
                               VspOspTraversalData &backData);

        /** Selects an axis aligned for the next split.
                @returns cost for this split
        */
        float SelectPlane(const VspOspTraversalData &tData,
                                          AxisAlignedPlane &plane,
                                          float &pFront,
                                          float &pBack);

        /** Sorts split candidates for surface area heuristics for axis aligned splits.
                @param polys the input for choosing split candidates
                @param axis the current split axis
                @param splitCandidates returns sorted list of split candidates
        */
        void SortSplitCandidates(const RayInfoContainer &rays, 
                                                         const int axis, 
                                                         float minBand, 
                                                         float maxBand);

        /** Computes best cost for axis aligned planes.
        */
        float BestCostRatioHeuristics(const RayInfoContainer &rays,
                                                                  const AxisAlignedBox3 &box,
                                                                  const int pvsSize,
                                                                  const int axis,
                                                                  float &position);

        /** Subdivides the rays into front and back rays according to the split plane.
                
                @param plane the split plane
                @param rays contains the rays to be split. The rays are 
                           distributed into front and back rays.
                @param frontRays returns rays on the front side of the plane
                @param backRays returns rays on the back side of the plane
                
                @returns the number of splits
        */
        int SplitRays(const Plane3 &plane,
                                  RayInfoContainer &rays, 
                              RayInfoContainer &frontRays, 
                                  RayInfoContainer &backRays) const;

        /** Adds the object to the pvs of the front and back leaf with a given classification.

                @param obj the object to be added
                @param cf the ray classification regarding the split plane
                @param frontPvs returns the PVS of the front partition
                @param backPvs returns the PVS of the back partition
        
        */
        void AddObjToPvs(Intersectable *obj, 
                                         const int cf, 
                                         float &frontPvs, 
                                         float &backPvs, 
                                         float &totalPvs) const;
        
        /** Computes PVS size induced by the rays.
        */
        int ComputePvsSize(const RayInfoContainer &rays) const;

        /** Returns true if tree can be terminated.
        */
        inline bool LocalTerminationCriteriaMet(const VspOspTraversalData &data) const;

        /** Returns true if global tree can be terminated.
        */
        inline bool GlobalTerminationCriteriaMet(const VspOspTraversalData &data) const;

        /** Adds ray sample contributions to the PVS.
                @param sampleContributions the number contributions of the samples
                @param contributingSampels the number of contributing rays
                
        */
        void AddToPvs(BspLeaf *leaf,
                                  const RayInfoContainer &rays, 
                                  float &sampleContributions,
                                  int &contributingSamples);

        /** Propagates valid flag up the tree.
        */
        void PropagateUpValidity(BspNode *node);

        /** Writes the node to disk
                @note: should be implemented as visitor.
        */
#if ZIPPED_VIEWCELLS
        void ExportNode(BspNode *node, ogzstream &stream);
#else
        void ExportNode(BspNode *node, ofstream &stream);
#endif

        /** Returns estimated memory usage of tree.
        */
        float GetMemUsage() const;


protected:

        ViewCellsManager *mViewCellsManager;
        vector<SortableEntry> *mSplitCandidates;

        /// Pointer to the root of the tree
        BspNode *mRoot;
                
        BspTreeStatistics mBspStats;
        
        /// View cell corresponding to the space outside the valid view space
        BspViewCell *mOutOfBoundsCell;

        /// box around the whole view domain
        AxisAlignedBox3 mBox;



        //-- local termination

        /// minimal number of rays before subdivision termination
        int mTermMinRays;
        /// maximal possible depth
        int mTermMaxDepth;
        /// mininum probability
        float mTermMinProbability;
        /// mininum PVS
        int mTermMinPvs;
        /// maximal contribution per ray
        float mTermMaxRayContribution;
        /// maximal acceptable cost ratio
        float mTermMaxCostRatio;
        /// tolerance value indicating how often the max cost ratio can be failed
        int mTermMissTolerance;


        //-- global criteria
        float mTermMinGlobalCostRatio;
        int mTermGlobalCostMissTolerance;
        int mGlobalCostMisses;

        /// maximal number of view cells
        int mMaxViewCells;
        /// maximal tree memory
        float mMaxMemory;
        /// the tree is out of memory
        bool mOutOfMemory;



        //-- split heuristics based parameters
        
        bool mUseCostHeuristics;
        /// balancing factor for PVS criterium
        float mCtDivCi; 
        /// if only driving axis should be used for split
        bool mOnlyDrivingAxis;
        /// if random split axis should be used
        bool mUseRandomAxis;
        /// if vsp bsp tree should simulate octree
        bool mCirculatingAxis;
        /// minimal relative position where the split axis can be placed
        float mMinBand;
        /// maximal relative position where the split axis can be placed
        float mMaxBand;


        /// current time stamp (used for keeping split history)
        int mTimeStamp;
        // if rays should be stored in leaves
        bool mStoreRays;

        /// epsilon for geometric comparisons
        float mEpsilon;

        /// if we should use breath first priority for the splits
        int mNodePriorityQueueType;

        // priority queue strategy
        enum {BREATH_FIRST, DEPTH_FIRST, COST_BASED};


        /// subdivision stats output file
        ofstream  mSubdivisionStats;
        /// keeps track of cost during subdivision
        float mTotalCost;
        /// keeps track of overall pvs size during subdivision
        int mTotalPvsSize;
        /// number of currenly generated view cells
        int mCreatedViewCells;

private:

        /// Generates unique ids for PVS criterium
        static void GenerateUniqueIdsForPvs();

        //-- unique ids for PVS criterium
        static int sFrontId; 
        static int sBackId;
        static int sFrontAndBackId;
};

}


#endif