From 9a266c544bfddba71bfc35c4e6d484c33bc9ea39 Mon Sep 17 00:00:00 2001 From: Owen Arnold Date: Wed, 2 Apr 2014 10:40:44 +0100 Subject: [PATCH] refs #9194. Document code better. --- .../ConnectedComponentLabeling.h | 155 ++++++++++-------- .../src/ConnectedComponentLabeling.cpp | 59 ++++++- 2 files changed, 137 insertions(+), 77 deletions(-) diff --git a/Code/Mantid/Framework/Crystal/inc/MantidCrystal/ConnectedComponentLabeling.h b/Code/Mantid/Framework/Crystal/inc/MantidCrystal/ConnectedComponentLabeling.h index db10392f9a8e..39efdadb9cf9 100644 --- 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 SignalErrorSQPair; - typedef std::map LabelIdIntensityMap; - typedef std::map PositionToLabelIdMap; - typedef std::vector VecIndexes; - typedef std::vector VecElements; - typedef std::set SetIds; + class Progress; } - class BackgroundStrategy; + namespace Crystal + { + /** + * Namespace containing useful typedefs + */ + namespace ConnectedComponentMappingTypes + { + typedef boost::tuple SignalErrorSQPair; + typedef std::map LabelIdIntensityMap; + typedef std::map PositionToLabelIdMap; + typedef std::vector VecIndexes; + typedef std::vector VecElements; + typedef std::set SetIds; + } - /** ConnectedComponentLabelling : Implements connected component labeling on MDHistoWorkspaces. - - Copyright © 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 © 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 . + 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: - Code Documentation is available at: - */ - 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 . + + File change history is stored at: + Code Documentation is available at: + */ + 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 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 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& 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 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 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& 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 index 4c3f1e0cb203..5260141d4a87 100644 --- a/Code/Mantid/Framework/Crystal/src/ConnectedComponentLabeling.cpp +++ b/Code/Mantid/Framework/Crystal/src/ConnectedComponentLabeling.cpp @@ -16,8 +16,6 @@ #include #include - - 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 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 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 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 ConnectedComponentLabeling::executeAndIntegrate( IMDHistoWorkspace_sptr ws, BackgroundStrategy * const strategy, LabelIdIntensityMap& labelMap, PositionToLabelIdMap& positionLabelMap, Progress& progress) const