include/geometry/ssUniformAnalyzer.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2005 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: ssUniformAnalyzer.h,v $ $Revision: 1.7 $ $State: Exp $
*******************************************************************************/
#ifndef ssUniformAnalyzer_H_
#define ssUniformAnalyzer_H_

#include "geometry/spatialSubdivision.h"
#include "geometry/simpleStats.h"
#include <vlutil/vlConfig.h>
#include <map>
#include <vector>



template<typename T>
class DtSsUniformAnalyzer
{
public:

   typedef unsigned int DtNumElementsInCell;
   typedef unsigned int DtNumCells;
   typedef std::map<DtNumElementsInCell, DtNumCells> DtNumCellsWithNumElementsContainer;

   typedef unsigned int DtElementFillRate;
   typedef unsigned int DtNumElementsWithFillRate;
   typedef std::map<DtElementFillRate, DtNumElementsWithFillRate> DtElementFillRatesContainer;

   typedef std::vector<unsigned int> DtFillDistributionContainer;

   typedef std::list<unsigned int>   DtFillModeContainer;
   

   DtSsUniformAnalyzer(const DtSpatialSubdivision<T>& spatialSubdivision);

   // This object requires none of the big three to be defined.  It *is* copyable,
   // assignable, and destroyable. - The compiler will generate these.
//   virtual ~DtSsUniformAnalyzer();
//   DtSsUniformAnalyzer(const DtSsUniformAnalyzer& original);
//   DtSsUniformAnalyzer& operator=(const DtSsUniformAnalyzer& original);

public:

   // @returns The number of empty cells in the SS.
   unsigned int numEmptyCells() const;

   // @returns The number of non-empty cells in the SS.
   unsigned int numNonEmptyCells();
   
   // @returns The largest number of elements contained in a single SS cell.
   unsigned int maxFill() const;

   // @returns The smallest number of elements contained in a single SS cell.  
   // @note This is almost always zero, but for highly and/or evenly filled 
   // subdivisions, it may not be.
   unsigned int minFill() const;
   
   // @returns The median fill rate for the spatial subdivision.
   unsigned int medianFill() const;

   // @returns The average fill rate for the spatial subdivision.
   float averageFill() const;

   // Determines the fill rate mode for the spatial subdivision.
   // @returns A container of cell sizes that are most common.
   // For example, a spatial subdivision with 9 cells, with the fill values of:
   // 3, 6, 4, 2, 0, 2, 6, 0, 0
   // would have a single mode of 0.  If, instead the values were:
   // 6, 6, 4, 2, 0, 2, 6, 0, 0
   // the SS would have two modes, 0 and 6.
   // 
   DtFillModeContainer fillMode() const;

   // @returns The fill rate statistical range for the SS.
   unsigned int fillRange() const;

   // Determines the fill distribution for the spatial subdivision.  This can be 
   // used to get the relative efficiency of the spatial subdivision, as
   // it can point to areas of higher and lower utilization.
   //
   // @returns A container of the fill rates for each cell, where the index into the
   // returned container is the same as the associated cell in the spatial subdivision,
   // and the value is that cell's fill amount.
   // For example, if the spatial subdivision contained 1000 cells, then the 
   // returned container's 500th element would contain the 500th cell's fill amount.
   const DtFillDistributionContainer& fillDistribution() const;

   // Determines the number of cells with the same number of elements.  For example,
   // the first entry in the returned container may be 17, 12.  This would mean that
   // there are 12 cells in the SS that have 17 elements referenced in them.  
   //
   // @returns A container values, where the index into the container is the number 
   // of referenced elements, and the value at that index in the container is the number
   // of cells that reference <index> numbers of elements.  
   const DtNumCellsWithNumElementsContainer& numCellsWithNumElements() const;

   // Determines the number of cells that the elements are individually referenced in.
   // For example, in the returned container, the index is equal to the number of 
   // cells and the value at that index is the number of elements that are stored 
   // in that many cells.
   //
   // @returns A container of pairs of data:  the number of cells used to store 
   // the elements, and the number of elements stored individually in that many 
   // cells.
   //
   // For instance, if 100 items total are sorted spatially in the spatial 
   // subdivision, and 20 of those items happen to be referenced in 10 cells
   // each, then the container would contain an entry with key 10 and value 20.
   const DtElementFillRatesContainer& elementFillRates() const;


   // Notify the SS analyzer that its spatial subdivision has changed.
   void spatialSubdivisionChanged() const;

protected:

   // @returns A boolean indicating whether or not the statistics need to be
   // generated or not.
   bool isStatsClean() const;

   // Sets the state of the statistics to be clean or unclean.  When unclean,
   // they need to be recalculated before they are valid.
   void setStatsClean(bool yesOrNo) const;

   // Analyzes the spatial subdivision, and calculates all statistics.
   // @note When this is finished, the statistics are considered clean.
   void analyzeSs() const;

private:

   // The spatial subdivision to reference.
   const DtSpatialSubdivision<T>& mySpatialSubdivision;

   // Holds the min, max, sum, and average of all cell size counts
   mutable DtSimpleStats<unsigned int> mySimpleStats;

   // The number of empty cells in the spatial subdivision
   mutable unsigned int myNumEmptyCells;
   // The number of cells referencing at least one element.
   mutable unsigned int myNumNonEmptyCells;

   // Fill stats.
   // For these statistics, fill is defined as the number of elements in a 
   // spatial subdivision cell.

   // Essentially a container with numCells elements that contains the fill 
   // amount of each cell in the spatial subdivision.  
   // @note If this data was plotted, it might give an idea of the efficiency 
   // graphically.  (You could see areas of higher and lower cell fill rates.)
   mutable DtFillDistributionContainer myFillDistribution;

   // The median fill amount.  
   mutable unsigned int myFillMedian;

   // A container of the fill modes (most commonly occurring cell sizes).
   mutable DtFillModeContainer myFillMode;

   // A container that maps the number of cells referencing N elements to the 
   // number of elements.  For example, if 10 cells reference 5 elements, and 
   // 15 reference 1, and 20 reference 0, the this container would have 3 
   // entries, of those three pairs.
   mutable DtNumCellsWithNumElementsContainer myNumCellsWithNumElements;

   // This container maps between the number of elements referenced in N cells,
   // and the number of elements.  It's essentially the opposite of the previous
   // container, as it is concerned with how many elements are stored over 
   // how many cells.  The higher the number of elements that are stored in more
   // cells, the more likely that the subdivision is an overly high resolution.
   mutable DtElementFillRatesContainer myNumElementsReferencedInNumCells;    

   // This group of statistics is not trivial to calculate, especially for very 
   // large datasets.  As a result, don't calculate the values until requested,
   // and then not again until the spatial subdivision has changed.  
   mutable bool myStatsClean;
};

//------------------------------------------------------
//  INLINE METHODS
//------------------------------------------------------
// include the inline code
#define SSUNIFORMANALYZER_HEADER
#include "geometry/ssUniformAnalyzer.inl"
#undef  SSUNIFORMANALYZER_HEADER

#endif