diff --git a/.gitignore b/.gitignore index bf6a22fc6..2c10f84a4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ *.sw[a-z] *.patch _build +xml *.pt +.DS_store diff --git a/alg/teca_2d_component_area.h b/alg/teca_2d_component_area.h index 5a9d57e6a..61253cae6 100644 --- a/alg/teca_2d_component_area.h +++ b/alg/teca_2d_component_area.h @@ -12,38 +12,38 @@ TECA_SHARED_OBJECT_FORWARD_DECL(teca_2d_component_area) /// an algorithm that computes the area of labeled regions /** -Given a set of labels on a Cartesian mesh, the algorithm computes the area of -each region. Regions are identified by assigning a unique integer value to each -mesh point that belongs in the region. The component_variable property names -the variable containing the region labels. - -if the region labels start at 0 and are contiguous then an optimization can be -used. Set contiguous_component_ids property to enable the optimization. Note that -TECA's connected component labeler assigns the background (i.e. cells not inside -the segmentation) the label 0. One can identify the background region and area -via this label. When processing data generated outside of TECA it might be -necessary to supply the background label. Use -2 if there is no background. - -the input dataset is passed through and the results of the calculations are -stored in the output dataset metadata in the following keys: - - number_of_components - number of component ids for which area was - computed. Note that this can include a background - component i.e. for cells outside of the segmentation. - - component_ids - a vector containing the label of each component. This is - always starts with 0, where the label 0 identifies cells - out side of the segmentation, and ranges up to - number_of_components - 1, where the labels from 1 up to - number_of_components - 1 identify connected regions of - cells inside the segmentation. - - component_area - a vector containing the area for the corresponding entry - in the component_ids array. - - background_id - the label used for cells outside of the segmentation, - i.e. the background. This can be used to skip processing - of the background when desirable. + Given a set of labels on a Cartesian mesh, the algorithm computes the area of + each region. Regions are identified by assigning a unique integer value to each + mesh point that belongs in the region. The component_variable property names + the variable containing the region labels. + + if the region labels start at 0 and are contiguous then an optimization can be + used. Set contiguous_component_ids property to enable the optimization. Note that + TECA's connected component labeler assigns the background (i.e. cells not inside + the segmentation) the label 0. One can identify the background region and area + via this label. When processing data generated outside of TECA it might be + necessary to supply the background label. Use -2 if there is no background. + + the input dataset is passed through and the results of the calculations are + stored in the output dataset metadata in the following keys: + + number_of_components - number of component ids for which area was + computed. Note that this can include a background + component i.e. for cells outside of the segmentation. + + component_ids - a vector containing the label of each component. This is + always starts with 0, where the label 0 identifies cells + out side of the segmentation, and ranges up to + number_of_components - 1, where the labels from 1 up to + number_of_components - 1 identify connected regions of + cells inside the segmentation. + + component_area - a vector containing the area for the corresponding entry + in the component_ids array. + + background_id - the label used for cells outside of the segmentation, + i.e. the background. This can be used to skip processing + of the background when desirable. */ class teca_2d_component_area : public teca_algorithm { @@ -58,17 +58,41 @@ class teca_2d_component_area : public teca_algorithm TECA_SET_ALGORITHM_PROPERTIES() // set the name of the input array + /*! \fn set_component_variable(const std::string &v) + + set the name of the input array. + */ + /*! \fn get_component_variable() const + + get the name of the input array. + */ TECA_ALGORITHM_PROPERTY(std::string, component_variable) - // set this only if you know for certain that label ids are contiguous and - // start at 0. this enables use of a faster implementation. + /*! \fn set_contiguous_component_ids(const long &v) + + set the label used for cells inside the segmentation. + + \warning set this only if you know for certain that label ids are contiguous and + start at 0. this enables use of a faster implementation. + */ + /*! \fn get_contiguous_component_ids() const + + get the label used for cells inside the segmentation. + */ TECA_ALGORITHM_PROPERTY(int, contiguous_component_ids) - // set this to override the component label used for background. By default - // this is set to -1 to indicate that the value should be obtained from the - // metadata key `background_id`. Note that TECA's connected component - // labeler uses the id 0 for the background and passes this in a metadata - // key and as a result no action is required. + /*! \fn set_background_id(const long &v) + + set the label used for cells outside of the segmentation, + i.e. the background. This can be used to skip processing + of the background when desirable. + */ + /*! \fn get_background_id() const + + get the label used for cells outside of the segmentation, + i.e. the background. This can be used to skip processing + of the background when desirable. + */ TECA_ALGORITHM_PROPERTY(long, background_id) protected: diff --git a/core/teca_algorithm_fwd.h b/core/teca_algorithm_fwd.h index ee0a58b21..fbfc4c404 100644 --- a/core/teca_algorithm_fwd.h +++ b/core/teca_algorithm_fwd.h @@ -32,6 +32,7 @@ std::shared_ptr shared_from_this() const \ } #define TECA_ALGORITHM_CLASS_NAME(T) \ +/*! returns the string value "T" */ \ const char *get_class_name() const override \ { \ return #T; \ @@ -50,6 +51,12 @@ const char *get_class_name() const override \ // convenience macro to declare standard set_X/get_X methods // where X is the name of a class member. will manage the // algorithm's modified state for the user. +/* + \def TECA_ALGORITHM_PROPERTY(T, NAME) + convenience macro to declare standard set_X/get_X methods + where X is the name of a class member. will manage the + algorithm's modified state for the user. +*/ #define TECA_ALGORITHM_PROPERTY(T, NAME) \ \ void set_##NAME(const T &v) \ diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index 5471b926f..cff7b063e 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "My Project" +PROJECT_NAME = "TECA" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -483,6 +483,7 @@ NUM_PROC_THREADS = 1 # The default value is: NO. EXTRACT_ALL = NO +#EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -844,8 +845,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -#INPUT = ../../alg/teca_bayesian_ar_detect.h -INPUT = ../.. +INPUT = ../../alg/teca_2d_component_area.h +#INPUT = ../.. #INPUT = # This tag can be used to specify the character encoding of the source files @@ -1128,7 +1129,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -2147,7 +2148,8 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = +#INCLUDE_PATH = +INCLUDE_PATH = ../../core # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -2155,7 +2157,8 @@ INCLUDE_PATH = # used. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -INCLUDE_FILE_PATTERNS = +#INCLUDE_FILE_PATTERNS = +INCLUDE_FILE_PATTERNS = *.h # The PREDEFINED tag can be used to specify one or more macro names that are # defined before the preprocessor is started (similar to the -D option of e.g. @@ -2185,6 +2188,7 @@ EXPAND_AS_DEFINED = # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. SKIP_FUNCTION_MACROS = YES +#SKIP_FUNCTION_MACROS = NO #--------------------------------------------------------------------------- # Configuration options related to external references diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 9bccbd53d..993eb8fb2 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -30,7 +30,7 @@ read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' if read_the_docs_build: - subprocess.call('cd ../doxygen; doxygen', shell=True) + subprocess.call('cd ../doxygen; doxygen -d Preprocessor', shell=True) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom diff --git a/doc/rtd/framework/alg.rst b/doc/rtd/framework/alg.rst index 7d6ba177d..836b7b382 100644 --- a/doc/rtd/framework/alg.rst +++ b/doc/rtd/framework/alg.rst @@ -6,8 +6,6 @@ Classes .. doxygenclass:: teca_2d_component_area :members: - :protected-members: - :private-members: :undoc-members: .. doxygenclass:: teca_bayesian_ar_detect diff --git a/doc/rtd/framework/framework.rst b/doc/rtd/framework/framework.rst index a48f9b3dc..f30fc68e3 100644 --- a/doc/rtd/framework/framework.rst +++ b/doc/rtd/framework/framework.rst @@ -2,11 +2,10 @@ Framework ========= TECA provides an extensive suite of algorithms and software utilities -to build Climage Data Analysis pipelines -for climate data analysis. +to build Climage Data Analysis/Transformation pipelines. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: alg