Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
GeomTopoTool.hpp
Go to the documentation of this file.
1 /**
2  * MOAB, a Mesh-Oriented datABase, is a software component for creating,
3  * storing and accessing finite element mesh data.
4  *
5  * Copyright 2004 Sandia Corporation. Under the terms of Contract
6  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
7  * retains certain rights in this software.
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public
11  * License as published by the Free Software Foundation; either
12  * version 2.1 of the License, or (at your option) any later version.
13  *
14  */
15 
16 #ifndef MOAB_GEOM_TOPO_TOOL_HPP
17 #define MOAB_GEOM_TOPO_TOOL_HPP
18 
19 #include "moab/Forward.hpp"
20 #include "moab/Range.hpp"
21 
22 #include <map>
23 #include <cassert>
24 
25 namespace moab
26 {
27 
28 // forward declare this class to avoid the header leaking in here
29 class OrientedBoxTreeTool;
30 class GeomQueryTool;
31 
32 /** \class GeomTopoTool
33  * \brief Tool for interpreting geometric topology sets in MOAB database
34  * Tool for interpreting geometric topology sets in MOAB database; see MOAB metadata_info
35  * document for information on how geometric topology sets are read and represented.
36  */
38 {
39  public:
40  /** \brief Constructor (creates a GTT object) \
41  * Construct a GeomTopoTool object and search for geometric EntitySets if they
42  * exist in the provided moab instance.
43  * \param impl MOAB instance the GeomTopoTool will operate on.
44  * \param find_geoments if specified as True, geometric objects in the provided MOAB instance
45  will be searched for and added to the GTT.
46  \param modelRootSet the GTT will operate only on geometric EntitySets contained by this
47  EntitySet. If unprovided, the default value for the modelRootSet is the MOAB instance's root
48  set, which contains everything in the instance. \param p_rootSets_vector determines the storage
49  datastructure used to relate geometric EntitySets to their OrientedBoundingBox (OBB) Tree
50  roots. If set to true (default) a vector will be used to store the root sets along with an
51  EntityHandle offset for fast lookup of the root sets. If set to false, then a map will be used
52  to link geometric EntitySets (keys) to the OBB Tree root sets (values). \param restore_rootSets
53  determines whether or not to restore the internal index that links geomSets to their
54  corresponding OBB Root. Only relevant if find_geoments is true. (default = true)
55  */
56  GeomTopoTool( Interface* impl,
57  bool find_geoments = false,
58  EntityHandle modelRootSet = 0,
59  bool p_rootSets_vector = true,
60  bool restore_rootSets = true );
61 
62  ~GeomTopoTool();
63 
64  //! Restore parent/child links between GEOM_TOPO mesh sets
66  //! Store sense of entity relative to wrt_entity.
67  //!\return MB_MULTIPLE_ENTITIES_FOUND if surface already has a forward volume.
68  //! MB_SUCCESS if successful
69  //! otherwise whatever internal error code occured.
70  ErrorCode set_sense( EntityHandle entity, EntityHandle wrt_entity, int sense );
71  //! Get the sense of entity with respect to wrt_entity
72  //! Returns MB_ENTITY_NOT_FOUND if no relationship found
73  ErrorCode get_sense( EntityHandle entity, EntityHandle wrt_entity, int& sense );
74  //! Get the sense of the surface(s) with respect to the volume
75  ErrorCode get_surface_senses( EntityHandle volume, int num_surfs, const EntityHandle* surfs, int* senses_out );
76  //! Get the senses of a surface with respect to its volumes
77  ErrorCode get_surface_senses( EntityHandle surface_ent, EntityHandle& forward_vol, EntityHandle& reverse_vol );
78 
79  //! Set the senses of a surface with respect to its volumes
80  ErrorCode set_surface_senses( EntityHandle surface_ent, EntityHandle forward_vol, EntityHandle reverse_vol );
81  //! Get the senses of the lower dimension entity handle wrt the higher dimension entities
82  ErrorCode get_senses( EntityHandle entity, std::vector< EntityHandle >& wrt_entities, std::vector< int >& senses );
83  //! Set the senses of the entity wrt multiple higher dimension entities
84  ErrorCode set_senses( EntityHandle entity, std::vector< EntityHandle >& wrt_entities, std::vector< int >& senses );
85 
86  /** \brief Get the volume on the other side of a surface
87  *
88  * @param A surface to query
89  * @param old_volume A volume on one side of surface
90  * @param new_volume Output parameter for volume on the other side of surface
91  * @return MB_SUCCESS if new_volume was set successfully, error if not.
92  */
93  ErrorCode next_vol( EntityHandle surface, EntityHandle old_volume, EntityHandle& new_volume );
94 
95  //! Retrieve geometry sets of desired dimension from model set
96  // 0 = verts, 1 = curves, 2 = surfs, 3 = vols
98 
99  /** \brief Build obb tree for the entity set given; entity can be surface or volume
100  *
101  * @param eh EntityHandle of the volume or surface to construct the OBB tree around
102  */
104 
105  /** \brief Get the bouding points from a bounding box
106  *
107  * @param volume The volume for which the bounding coordinates are requested
108  * @param minPt Location of the min xyz corner of the volume's axis-aligned bounding box
109  * @param maxPt Location of the max xyz corner of the volume's axis-aligned bounding box
110  */
111  ErrorCode get_bounding_coords( EntityHandle volume, double minPt[3], double maxPt[3] );
112 
113  /** \brief Get the center point and three vectors for the OBB of a given volume
114  *
115  * @param volume The volume for which the OBB axes will be returned
116  * @param center coordinates of the oriented bounding box's center point
117  * @param axis1 scaled axis one of the oriented bounding box
118  * @param axis2 scaled axis two of the oriented bounding box
119  * @param axis3 scaled axis three of the oriented bounding box
120  */
121  ErrorCode get_obb( EntityHandle volume, double center[3], double axis1[3], double axis2[3], double axis3[3] );
122 
123  /** \brief Get the other (d-1)-dimensional entity bounding a set across a (d-2)-dimensional
124  * entity
125  *
126  * Given a d-dimensional entity and one (d-1)-dimensional entity, return the (d-1) dimensional
127  * entity across a specified (d-2)-dimensional entity. For example, given a surface, edge, and
128  * vertex, returns the other edge bounding the surface sharing the vertex. In the case of
129  * degenerate results, e.g. two loops bounding a surface and sharing a vertex, tries to step in
130  * positively-oriented direction. This won't always work; in those cases, will return
131  * MB_MULTIPLE_ENTITIES_FOUND.
132  *
133  * In the special case where bounded is a curve, then not_this can be a vertex and across zero.
134  * This function returns the other vertex on the curve.
135  */
136  ErrorCode other_entity( EntityHandle bounded, EntityHandle not_this, EntityHandle across, EntityHandle& other );
137 
138  /** \brief Return the dimension of the set, or -1 if it's not a geom_dimension set
139  */
140  int dimension( EntityHandle this_set );
141 
142  /** \brief Return the global ID of a given entity set
143  *
144  * @param this_set EntitySet for which the global ID will be returned
145  */
146  int global_id( EntityHandle this_set );
147 
148  //! Map from dimension & global ID to EntityHandle
149  EntityHandle entity_by_id( int dimension, int id );
150 
151  ErrorCode find_geomsets( Range* ranges = NULL );
152 
153  //! Restore the internal cross-referencing of geometry sets and OBB roots
154  // The EntityHandle of an OBB Root can be tagged onto the geoemtry EntitySet
155  // that it represents so that this relationship can be recovered across
156  // write to/read from file. Since finding the OBB Root for a given geomset
157  // is frequent, a faster lookup capability is enabled through data structures
158  // in GeomTopoTool (i.e. rootSets or mapRootSets). This data structure
159  // needs to be populated upon file read.
161 
162  //! Build obb trees for all surfaces and volumes in model set.
163  // If make_one_vol true, joins trees from all surfaces in model into single
164  // volume obb tree.
165  ErrorCode construct_obb_trees( bool make_one_vol = false );
166 
167  //! Delete the OBB tree of a volume or surface.
168  // If the passed entity is a volume, and the bool 'vol_only'
169  // is True, function will delete the volume OBB tree, but
170  // OBB trees of the surfaces that compose (are children of)
171  // the volume will remain in tact. If the entity is a volume and
172  // 'vol_only' is False, function will delete the volume OBB tree
173  // along with all child surface OBB trees.
174  ErrorCode delete_obb_tree( EntityHandle gset, bool vol_only = false );
175 
177 
178  //! Delete the root of the obb tree from the set of all roots
179  ErrorCode remove_root( EntityHandle vol_or_surf );
180 
181  //! Get the root of the obbtree for a given entity
182  ErrorCode get_root( EntityHandle vol_or_surf, EntityHandle& root );
183 
184  //! If constructing one volume obb tree by joining all surface trees,
185  // get the root of that tree
187 
188  //! Pointer to Oriented Box Tree Tool class
190  {
191  return obbTree;
192  }
193 
194  //! Adds a geometry set to the range of all geometry sets, the model set, and root set
195  // Make sure the set has the proper geometry dimension tag
196  // This could make the obb tree out of date
198 
199  //! Will assume no geo sets are defined for this surface
200  // Will output a mesh_set that contains everything (all sets of interest), for proper output
202 
203  //! Checks to see if the entity is part of the model set
205 
206  //! This would be a deep copy, into a new geom topo tool
207  // sets will be duplicated, but entities not
208  // modelSet will be a new one;
209  // will take as input a pointer to a std::vector of gents (surfaces and volumes, usually),
210  // which will serve to filter the gents from modelSet (only dependents will be part of the new
211  // gtt) if the pointer is null, all gsets in the original modelSet are duplicated
212  ErrorCode duplicate_model( GeomTopoTool*& duplicate, std::vector< EntityHandle >* pvGEnts = NULL );
213 
214  //! Return the model set handle (this is the full geometry)
216  {
217  return modelSet;
218  }
219 
220  //! Checks that all geometric entities were created properly
221  bool check_model();
222 
223  //! Should be used instead of keeping multiple ranges, for example in FBEngine
224  const Range* geoRanges()
225  {
226  return geomRanges;
227  }
228 
229  //! Return pointer to moab instance
231  {
232  return mdbImpl;
233  }
234 
235  //! Returns the sense tag (sense2Tag) from check_face_sense_tag
236  Tag get_sense_tag();
237 
238  //! Returns the global ID tag (gidTag) from check_gid_tag
239  Tag get_gid_tag();
240 
241  //! Returns the geometry dimension tag (geomTag) from check_geom_tag
242  Tag get_geom_tag();
243 
244  //! Returns true if obb trees have been added to the rootset
245  bool have_obb_tree();
246 
247  //! returns the number of entities in the modelSet with specified geometric dimension
248  int num_ents_of_dim( int dim );
249 
250  //! sets the implicit complement handle for this tool
252 
253  //! Get (or optionally, create) the implicit complement handle
254  ErrorCode get_implicit_complement( EntityHandle& implicit_complement );
255 
256  //! detection method for the implicit complement
257  bool is_implicit_complement( EntityHandle volume );
258 
259  /** \brief Discover and store the topological relationships among a set of volumes
260  * This method may be used to discover the hierarchy that exists in a range of
261  * volumes, that have no previous sense of hierarchy, and store it according
262  * to the conventions of GeomTopoTool.
263  * The following requirements about the range of flat_volumes must be met:
264  * 1. Each volume must be represented by a single, closed surface
265  * a. The surface meshsets have triangles and vertices as members.
266  * b. For each "flat volume", there must be two meshsets: one for the
267  * volume and another for the surface that encloses it. These must be
268  * linked by a parent-child relationship.
269  * c. The SENSE_FORWARD tag on the surface meshset must be set to be
270  * the volume meshset it encloses.
271  * 2. The surfaces must not touch or overlap
272  *
273  * After the hierarchy is established, the topological relationships between
274  * surfaces and the volumes that enclose them are set. This involves:
275  * 1. Setting parent-child relationship between surfaces and the volumes that
276  * enclose them.
277  * 2. Setting the SENSE_REVERSE tag on the surfaces to be the volume that
278  * encloses them.
279  *
280  */
282 
283  private:
292  // the model set encompasses a full topological model
294  // implicit complement handle cache
296 
297  Range geomRanges[5]; // add one more dimension, for set of gentities; by default, they will
298  // have geom_dimension 4
299  int maxGlobalId[5]; // one max global id for each dimension
300  bool updated;
301 
304  std::vector< EntityHandle > rootSets;
305 
307  std::map< EntityHandle, EntityHandle > mapRootSets;
309 
310  //! Creates a volume for undefined space in the model
311  // The implicit complement is composed of all surfaces that only
312  // have one parent volume, i.e. surfaces that are in contact with the outside
313  // world
314  ErrorCode generate_implicit_complement( EntityHandle& implicit_complement_set );
315 
316  //! Compute vertices inclusive and put on tag on sets in geom_sets
317  ErrorCode construct_vertex_ranges( const Range& geom_sets, const Tag verts_tag );
318 
319  //! Given a range of geom topology sets, separate by dimension
320  ErrorCode separate_by_dimension( const Range& geom_sets );
321 
322  //! Verify global id tag
323  ErrorCode check_gid_tag( bool create = false );
324 
325  //! Verify geometry tag
326  ErrorCode check_geom_tag( bool create = false );
327 
328  //! Verify sense face tag
329  ErrorCode check_face_sense_tag( bool create = false );
330 
331  //! Verify sense edge tags
332  ErrorCode check_edge_sense_tags( bool create = false );
333 
335 
336  ErrorCode set_root_set( EntityHandle vol_or_surf, EntityHandle root );
337 
338  //! Return a range of children of a desired geometric dimension
339  Range get_ct_children_by_dimension( const EntityHandle parent, const int desired_dimension );
340 
341  //! Test if volume A is enclosed by volume B
342  // This will only produce the correct result if the conventions about
343  // volumes listed in the restore_topology_from_geometric_inclusion are
344  // upheld
345  bool A_is_in_B( const EntityHandle volume_A, const EntityHandle volume_B, GeomQueryTool* GQT );
346 
347  //! Used by restore_topology_from_geometric_inclusion to generate the
348  // hierarchical tree of volumes
349  ErrorCode insert_in_tree( const EntityHandle ct_root, const EntityHandle volume, GeomQueryTool* GQT );
350 };
351 
353 {
354  assert( 0 <= dim && 3 >= dim );
355  return geomRanges[dim].size();
356 }
357 
358 // get the root of the obbtree for a given entity
360 {
361  if( m_rootSets_vector )
362  {
363  unsigned int index = vol_or_surf - setOffset;
364  root = ( index < rootSets.size() ? rootSets[index] : 0 );
365  }
366  else
367  root = mapRootSets[vol_or_surf];
368  return ( root ? MB_SUCCESS : MB_INDEX_OUT_OF_RANGE );
369 }
370 
372 {
373  return oneVolRootSet;
374 }
375 
377 {
378  check_face_sense_tag( true );
379  return sense2Tag;
380 }
381 
383 {
384  check_gid_tag( true );
385  return gidTag;
386 }
387 
389 {
390  check_geom_tag( true );
391  return geomTag;
392 }
393 
395 {
396  return volume == impl_compl_handle;
397 }
398 
399 } // namespace moab
400 
401 #endif