refs #9194. Document code better.

mantidproject · Apr 2, 2014 · 9a266c5 · 9a266c5
1 parent 84de4be
commit 9a266c5
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 77 deletions.
diff --git a/Code/Mantid/Framework/Crystal/inc/MantidCrystal/ConnectedComponentLabeling.h b/Code/Mantid/Framework/Crystal/inc/MantidCrystal/ConnectedComponentLabeling.h
@@ -11,88 +11,99 @@
 namespace Mantid
 {
 
-namespace API
-{
-  class Progress;
-}
-
-namespace Crystal
-{
-  namespace ConnectedComponentMappingTypes
+  namespace API
   {
-    typedef boost::tuple<double, double> SignalErrorSQPair;
-    typedef std::map<size_t, SignalErrorSQPair > LabelIdIntensityMap;
-    typedef std::map<Mantid::Kernel::V3D, size_t> PositionToLabelIdMap;
-    typedef std::vector<size_t> VecIndexes;
-    typedef std::vector<DisjointElement> VecElements;
-    typedef std::set<size_t> SetIds;
+    class Progress;
   }
 
-  class BackgroundStrategy;
+  namespace Crystal
+  {
+    /**
+     * Namespace containing useful typedefs
+     */
+    namespace ConnectedComponentMappingTypes
+    {
+      typedef boost::tuple<double, double> SignalErrorSQPair;
+      typedef std::map<size_t, SignalErrorSQPair> LabelIdIntensityMap;
+      typedef std::map<Mantid::Kernel::V3D, size_t> PositionToLabelIdMap;
+      typedef std::vector<size_t> VecIndexes;
+      typedef std::vector<DisjointElement> VecElements;
+      typedef std::set<size_t> SetIds;
+    }
 
-  /** ConnectedComponentLabelling : Implements connected component labeling on MDHistoWorkspaces.
-    
-    Copyright &copy; 2014 ISIS Rutherford Appleton Laboratory & NScD Oak Ridge National Laboratory
+    class BackgroundStrategy;
 
-    This file is part of Mantid.
+    /** ConnectedComponentLabelling : Implements connected component labeling on MDHistoWorkspaces.
 
-    Mantid 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.
+     Copyright &copy; 2014 ISIS Rutherford Appleton Laboratory & NScD Oak Ridge National Laboratory
 
-    Mantid 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.
+     This file is part of Mantid.
 
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+     Mantid 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.
 
-    File change history is stored at: <https://github.com/mantidproject/mantid>
-    Code Documentation is available at: <http://doxygen.mantidproject.org>
-  */
-  class DLLExport ConnectedComponentLabeling
-  {
+     Mantid 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 GNU General Public License
+     along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+     File change history is stored at: <https://github.com/mantidproject/mantid>
+     Code Documentation is available at: <http://doxygen.mantidproject.org>
+     */
+    class DLLExport ConnectedComponentLabeling
+    {
+
+    public:
+
+      /// Constructor
+      ConnectedComponentLabeling(const size_t&id = 1, const bool runMultiThreaded = true);
+
+      /// Getter for the start label id
+      size_t getStartLabelId() const;
+
+      /// Setter for the label id
+      void startLabelingId(const size_t& id);
+
+      /// Execute and return clusters
+      boost::shared_ptr<Mantid::API::IMDHistoWorkspace> execute(Mantid::API::IMDHistoWorkspace_sptr ws,
+          BackgroundStrategy * const strategy, Mantid::API::Progress& progress) const;
+
+      /// Execute and return clusters, as well as maps to integrated label values
+      boost::shared_ptr<Mantid::API::IMDHistoWorkspace> executeAndIntegrate(
+          Mantid::API::IMDHistoWorkspace_sptr ws, BackgroundStrategy * const strategy,
+          ConnectedComponentMappingTypes::LabelIdIntensityMap& labelMap,
+          ConnectedComponentMappingTypes::PositionToLabelIdMap& positionLabelMap,
+          Mantid::API::Progress& progress) const;
+
+      /// Destructor
+      virtual ~ConnectedComponentLabeling();
+
+    private:
+
+      /// Get the number of threads to use.
+      int getNThreads() const;
+
+      /// Calculate the disjoint element tree across the image.
+      void calculateDisjointTree(Mantid::API::IMDHistoWorkspace_sptr ws,
+          BackgroundStrategy * const strategy, std::vector<DisjointElement>& neighbourElements,
+          ConnectedComponentMappingTypes::LabelIdIntensityMap& labelMap,
+          ConnectedComponentMappingTypes::PositionToLabelIdMap& positionLabelMap,
+          Mantid::API::Progress& progress) const;
+
+      /// Start labeling index
+      size_t m_startId;
+
+      /// Run multithreaded
+      const bool m_runMultiThreaded;
+
+    };
 
-  public:
-    /// Constructor
-    ConnectedComponentLabeling(const size_t&id = 1, const bool runMultiThreaded=true);
-    /// Getter for the start label id
-    size_t getStartLabelId() const;
-    /// Setter for the label id
-    void startLabelingId(const size_t& id);
-
-    /// Execute and return clusters
-    boost::shared_ptr<Mantid::API::IMDHistoWorkspace> execute(Mantid::API::IMDHistoWorkspace_sptr ws, 
-      BackgroundStrategy * const strategy, Mantid::API::Progress& progress) const;
-
-    /// Execute and return clusters, as well as maps to integrated label values
-    boost::shared_ptr<Mantid::API::IMDHistoWorkspace> executeAndIntegrate(
-      Mantid::API::IMDHistoWorkspace_sptr ws, BackgroundStrategy * const strategy, ConnectedComponentMappingTypes::LabelIdIntensityMap& labelMap,
-      ConnectedComponentMappingTypes::PositionToLabelIdMap& positionLabelMap, Mantid::API::Progress& progress) const;
-
-    /// Destructor
-    virtual ~ConnectedComponentLabeling();
-  private:
-    /// Get the number of threads to use.
-    int getNThreads() const;
-    /// Calculate the disjoint element tree across the image.
-    void calculateDisjointTree(Mantid::API::IMDHistoWorkspace_sptr ws, 
-      BackgroundStrategy * const strategy, std::vector<DisjointElement>& neighbourElements,
-      ConnectedComponentMappingTypes::LabelIdIntensityMap& labelMap,
-      ConnectedComponentMappingTypes::PositionToLabelIdMap& positionLabelMap, 
-      Mantid::API::Progress& progress) const;
-
-    /// Start labeling index
-    size_t m_startId;
-    /// Run multithreaded
-    const bool m_runMultiThreaded;
-
-  };
-
-
-} // namespace Crystal
+  } // namespace Crystal
 } // namespace Mantid
 
 #endif  /* MANTID_CRYSTAL_CONNECTEDCOMPONENTLABELING_H_ */
diff --git a/Code/Mantid/Framework/Crystal/src/ConnectedComponentLabeling.cpp b/Code/Mantid/Framework/Crystal/src/ConnectedComponentLabeling.cpp
@@ -16,8 +16,6 @@
 #include <algorithm>
 #include <iterator>
 
-
-
 using namespace Mantid::API;
 using namespace Mantid::Kernel;
 using namespace Mantid::Crystal::ConnectedComponentMappingTypes;
@@ -28,6 +26,12 @@ namespace Mantid
   {
     namespace
     {
+      /**
+       * Perform integer power to determine the maximum number of face and edge connected
+       * neighbours for a given dimensionality
+       * @param ws : Workspace with dimensionality
+       * @return : Maximum number of possible neighbours
+       */
       size_t calculateMaxNeighbours(IMDHistoWorkspace const * const ws)
       {
         const size_t ndims = ws->getNumDims();
@@ -40,6 +44,11 @@ namespace Mantid
         return maxNeighbours;
       }
 
+      /**
+       * Helper non-member to clone the input workspace
+       * @param inWS: To clone
+       * @return : Cloned MDHistoWorkspace
+       */
       boost::shared_ptr<Mantid::API::IMDHistoWorkspace> cloneInputWorkspace(IMDHistoWorkspace_sptr& inWS)
       {
         auto alg = AlgorithmManager::Instance().createUnmanaged("CloneWorkspace");
@@ -56,6 +65,12 @@ namespace Mantid
         return outWS;
       }
 
+      /**
+       * Helper function to calculate report frequecny
+       * @param maxReports : Maximum number of reports wanted
+       * @param maxIterations : Maximum number of possible iterations
+       * @return
+       */
       template<typename T>
       T reportEvery(const T& maxReports, const T& maxIterations)
       {
@@ -68,9 +83,11 @@ namespace Mantid
       }
     }
 
-    //----------------------------------------------------------------------------------------------
-    /** Constructor
-    */
+    /**
+     * Constructor
+     * @param startId : Start Id to use for labeling
+     * @param runMultiThreaded : Run multi threaded. Defaults to true.
+     */
     ConnectedComponentLabeling::ConnectedComponentLabeling(const size_t& startId, const bool runMultiThreaded) 
       : m_startId(startId), m_runMultiThreaded(runMultiThreaded)
     {
@@ -101,11 +118,27 @@ namespace Mantid
     {
     }
 
+    /**
+     * Get the number of threads available
+     * @return : Number of available threads
+     */
     int ConnectedComponentLabeling::getNThreads() const
     {
       return m_runMultiThreaded ? API::FrameworkManager::Instance().getNumOMPThreads() : 1;
     }
 
+    /**
+     * Perform the work of the CCL algorithm
+     * - Pre filtering of background
+     * - Labeling using DisjointElements
+     *
+     * @param ws : MDHistoWorkspace to run CCL algorithm on
+     * @param strategy : Background strategy
+     * @param neighbourElements : Neighbour elements containing DisjointElements
+     * @param labelMap : Map of label id to signal, error_sq pair for integration purposes to fill
+     * @param positionLabelMap : Map of label ids to position in workspace coordinates to fill
+     * @param progress : Progress object
+     */
     void ConnectedComponentLabeling::calculateDisjointTree(IMDHistoWorkspace_sptr ws, 
       BackgroundStrategy * const strategy, VecElements& neighbourElements,
       LabelIdIntensityMap& labelMap,
@@ -243,6 +276,13 @@ namespace Mantid
 
     }
 
+    /**
+     * Execute CCL to produce a cluster output workspace containing labels
+     * @param ws : Workspace to perform CCL on
+     * @param strategy : Background strategy
+     * @param progress : Progress object
+     * @return Cluster output workspace of results
+     */
     boost::shared_ptr<Mantid::API::IMDHistoWorkspace> ConnectedComponentLabeling::execute(
       IMDHistoWorkspace_sptr ws, BackgroundStrategy * const strategy, Progress& progress) const
     {
@@ -279,6 +319,15 @@ namespace Mantid
       return outWS;
     }
 
+    /**
+     * Execute and integrate
+     * @param ws : Image workspace to integrate
+     * @param strategy : Background strategy
+     * @param labelMap : Label map to fill. Label ids to integrated signal and errorsq for that label
+     * @param positionLabelMap : Label ids to position in workspace coordinates. This is filled as part of the work.
+     * @param progress : Progress object
+     * @return Image Workspace containing clusters.
+     */
     boost::shared_ptr<Mantid::API::IMDHistoWorkspace> ConnectedComponentLabeling::executeAndIntegrate(
       IMDHistoWorkspace_sptr ws, BackgroundStrategy * const strategy, LabelIdIntensityMap& labelMap,
       PositionToLabelIdMap& positionLabelMap, Progress& progress) const