Tree.hpp

Go to the documentation of this file.

/**\file Tree.hpp
 * \class moab::Tree
 * \brief Parent class of various tree types in MOAB
 */

#ifndef MOAB_TREE_HPP
#define MOAB_TREE_HPP

#include "moab/Interface.hpp"
#include "moab/BoundBox.hpp"
#include "moab/CartVect.hpp"
#include "moab/FileOptions.hpp"
#include "moab/TreeStats.hpp"

#include <string>
#include <vector>
#include <cmath>
#include <cassert>

namespace moab
{

class Interface;
class Range;
class ElemEvaluator;

class Tree
{
  public:
    /** \brief Constructor (bare)
     * \param iface MOAB instance
     */
    Tree( Interface* iface );

    /** \brief Destructor
     */
    virtual ~Tree();

    /** \brief Destroy the tree maintained by this object, optionally checking we have the right
     * root. \param root If non-NULL, check that this is the root, return failure if not
     */
    virtual ErrorCode reset_tree() = 0;

    /** \brief Delete the entity sets associated with the tree, starting with the root and
     * traversing children
     */
    ErrorCode delete_tree_sets();

    /** Build the tree
     * Build a tree with the entities input.  If a non-NULL tree_root_set pointer is input,
     * use the pointed-to set as the root of this tree (*tree_root_set!=0) otherwise construct
     * a new root set and pass its handle back in *tree_root_set.  Options vary by tree type,
     * with a few common to all types of trees.  Common options:
     * MAX_PER_LEAF: max entities per leaf; default = 6
     * MAX_DEPTH: max depth of the tree; default = 30
     * MIN_WIDTH: minimum width of box, used like a tolerance; default = 1.0e-10
     * MESHSET_FLAGS: flags passed into meshset creation for tree nodes; should be a value from
     *          ENTITY_SET_PROPERTY (see Types.hpp); default = MESHSET_SET
     * CLEAN_UP: if false, do not delete tree sets upon tree class destruction; default = true
     * TAG_NAME: tag name to store tree information on tree nodes; default determined by tree type
     * \param entities Entities with which to build the tree
     * \param tree_root Root set for tree (see function description)
     * \param opts Options for tree (see function description)
     * \return Error is returned only on build failure
     */
    virtual ErrorCode build_tree( const Range& entities, EntityHandle* tree_root_set = NULL,
                                  FileOptions* options = NULL ) = 0;

    /** \brief Get bounding box for tree below tree_node, or entire tree
     * If no tree has been built yet, returns +/- DBL_MAX for all dimensions.  Note for some tree
     * types, boxes are not available for non-root nodes, and this function will return failure if
     * non-root is passed in \param box The box for this tree \param tree_node If non-NULL, node for
     * which box is requested, tree root if NULL \return Only returns error on fatal condition
     */
    virtual ErrorCode get_bounding_box( BoundBox& box, EntityHandle* tree_node = NULL ) const;

    /** \brief Return some basic information about the tree
     * Stats are returned for tree starting from input node or tree root (root = 0)
     * \param root If non-0, give stats below and including root
     * \param min Minimum corner of bounding box
     * \param max Maximum corner of bounding box
     * \param max_dep Maximum depth of tree below root
     */
    virtual ErrorCode get_info( EntityHandle root, double min[3], double max[3], unsigned int& max_dep );

    /** \brief Find all trees, by bounding box tag
     */
    ErrorCode find_all_trees( Range& results );

    /** \brief Get leaf containing input position.
     *
     * Does not take into account global bounding box of tree.
     * - Therefore there is always one leaf containing the point.
     * - If caller wants to account for global bounding box, then
     * caller can test against that box and not call this method
     * at all if the point is outside the box, as there is no leaf
     * containing the point in that case.
     * \param point Point to be located in tree
     * \param leaf_out Leaf containing point
     * \param iter_tol Tolerance for convergence of point search
     * \param inside_tol Tolerance for inside element calculation
     * \param multiple_leaves Some tree types can have multiple leaves containing a point;
     *          if non-NULL, this parameter is returned true if multiple leaves contain
     *          the input point
     * \param start_node Start from this tree node (non-NULL) instead of tree root (NULL)
     * \return Non-success returned only in case of failure; not-found indicated by leaf_out=0
     */
    virtual ErrorCode point_search( const double* point, EntityHandle& leaf_out, const double iter_tol = 1.0e-10,
                                    const double inside_tol = 1.0e-6, bool* multiple_leaves = NULL,
                                    EntityHandle* start_node = NULL, CartVect* params = NULL ) = 0;

    /** \brief Find all leaves within a given distance from point
     * If dists_out input non-NULL, also returns distances from each leaf; if
     * point i is inside leaf, 0 is given as dists_out[i].
     * If params_out is non-NULL and myEval is non-NULL, will evaluate individual entities
     * in tree nodes and return containing entities in leaves_out.  In those cases, if params_out
     * is also non-NULL, will return parameters in those elements in that vector.
     * \param point Point to be located in tree
     * \param distance Distance within which to query
     * \param leaves_out Leaves within distance or containing point
     * \param iter_tol Tolerance for convergence of point search
     * \param inside_tol Tolerance for inside element calculation
     * \param dists_out If non-NULL, will contain distsances to leaves
     * \param params_out If non-NULL, will contain parameters of the point in the ents in leaves_out
     * \param start_node Start from this tree node (non-NULL) instead of tree root (NULL)
     */
    virtual ErrorCode distance_search( const double* point, const double distance,
                                       std::vector< EntityHandle >& leaves_out, const double iter_tol = 1.0e-10,
                                       const double inside_tol = 1.0e-6, std::vector< double >* dists_out = NULL,
                                       std::vector< CartVect >* params_out = NULL,
                                       EntityHandle* start_node            = NULL ) = 0;

    /** \brief Return the MOAB interface associated with this tree
     */
    Interface* moab()
    {
        return mbImpl;
    }

    /** \brief Return the MOAB interface associated with this tree
     */
    const Interface* moab() const
    {
        return mbImpl;
    }

    /** \brief Get max depth set on tree */
    double get_max_depth()
    {
        return maxDepth;
    }

    /** \brief Get max entities per leaf set on tree */
    double get_max_per_leaf()
    {
        return maxPerLeaf;
    }

    /** \brief Get tree traversal stats object */
    TreeStats& tree_stats()
    {
        return treeStats;
    }

    /** \brief Get tree traversal stats object */
    const TreeStats& tree_stats() const
    {
        return treeStats;
    }

    /** \brief Create tree root and tag with bounding box
     */
    ErrorCode create_root( const double box_min[3], const double box_max[3], EntityHandle& root_handle );

    //! print various things about this tree
    virtual ErrorCode print() = 0;

    //! get/set the ElemEvaluator
    inline ElemEvaluator* get_eval()
    {
        return myEval;
    }

    //! get/set the ElemEvaluator
    inline void set_eval( ElemEvaluator* eval )
    {
        myEval = eval;
    }

    /** \brief Parse options for this tree, including common options for all trees
     * \param opts Options
     */
    virtual ErrorCode parse_options( FileOptions& opts ) = 0;

  protected:
    /** \brief Parse options common to all trees
     * \param options Options for representing tree; see Tree::build_tree() and subclass
     * build_tree() functions for allowed options \return Non-success returned from base class
     * function only under catastrophic circumstances; derived classes also can recognize
     * subclass-specific options
     */
    ErrorCode parse_common_options( FileOptions& options );

    /** \brief Get the box tag, possibly constructing it first
     * \param create_if_missing If true and it has not been made yet, make it
     */
    Tag get_box_tag( bool create_if_missing = true );

    // moab instance
    Interface* mbImpl;

    // bounding box for entire tree
    BoundBox boundBox;

    // max entities per leaf
    int maxPerLeaf;

    // max depth of tree
    int maxDepth;

    // tree depth, set by build_tree
    int treeDepth;

    // min width of box, handled like tolerance
    double minWidth;

    // meshset creation flags
    unsigned int meshsetFlags;

    // clean up flag
    bool cleanUp;

    // tree root
    EntityHandle myRoot;

    // tag used to mark bounding box of nodes
    Tag boxTag;

    // tag name used for boxTag
    std::string boxTagName;

    // tree traversal stats
    TreeStats treeStats;

    // element evaluator
    ElemEvaluator* myEval;
};

inline Tree::Tree( Interface* iface )
    : mbImpl( iface ), maxPerLeaf( 6 ), maxDepth( 30 ), treeDepth( -1 ), minWidth( 1.0e-10 ), meshsetFlags( 0 ),
      cleanUp( true ), myRoot( 0 ), boxTag( 0 ), myEval( 0 )
{
}

inline Tree::~Tree() {}

inline ErrorCode Tree::get_bounding_box( BoundBox& box, EntityHandle* tree_node ) const
{
    if( ( tree_node && *tree_node == myRoot ) || !tree_node )
    {
        box = boundBox;
        return MB_SUCCESS;
    }
    else
        return MB_FAILURE;
}

inline ErrorCode Tree::get_info( EntityHandle /* root */, double* /*min[3]*/, double* /* max[3]*/,
                                 unsigned int& /*dep*/ )
{
    return MB_NOT_IMPLEMENTED;
}

inline Tag Tree::get_box_tag( bool create_if_missing )
{
    if( !boxTag && create_if_missing )
    {
        assert( boxTagName.length() > 0 );
        ErrorCode rval =
            moab()->tag_get_handle( boxTagName.c_str(), 6, MB_TYPE_DOUBLE, boxTag, MB_TAG_CREAT | MB_TAG_SPARSE );
        if( MB_INVALID_SIZE == rval )
        {
            // delete the tag and get it again, legacy file...
            rval = moab()->tag_delete( boxTag );
            if( MB_SUCCESS != rval ) return 0;
            boxTag = 0;
            return get_box_tag( true );
        }

        if( MB_SUCCESS != rval ) return 0;
    }

    return boxTag;
}

}  // namespace moab

#endif