Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
WriteUtil.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 MB_WRITE_UTIL_HPP
17 #define MB_WRITE_UTIL_HPP
18 
19 #ifndef IS_BUILDING_MB
20 #error "WriteUtil.hpp isn't supposed to be included into an application"
21 #endif
22 
23 #include "moab/WriteUtilIface.hpp"
24 
25 namespace moab
26 {
27 
28 class Core;
29 
30 class WriteUtil : public WriteUtilIface
31 {
32  private:
33  //! Pointer to the Core
34  Core* mMB;
35 
36  public:
37  //! Constructor takes Core pointer
38  WriteUtil( Core* mdb );
39 
40  //! Destructor
41  ~WriteUtil() {}
42 
43  //! Check if the specified file already exists.
44  //! Returns MB_SUCCESS if file does not exist, MB_ALREADY_ALLOCATED
45  //! if file does exist, or MB_FAILURE for some other error condition.
46  virtual ErrorCode check_doesnt_exist( const char* file_name );
47 
48  //! Gather all entities in the mesh, or in the sets specified
49  virtual ErrorCode gather_entities(
50  Range& all_ents, /**< range in which entities are returned */
51  const EntityHandle* ent_sets = NULL, /**< entity sets whose contents are to be gathered */
52  const int num_sets = 0 /**< number of sets in list */ );
53 
54  //! Gets arrays for coordinate data from the MB
55  ErrorCode get_node_coords( const int num_arrays,
56  const int num_nodes,
57  const Range& entities,
58  Tag node_id_tag,
59  const int start_node_id,
60  std::vector< double* >& arrays );
61 
62  /** Get an array of coordinate values for nodes
63  *
64  * Given a range of node handles, retrieve a single or multiple coordinate
65  * value(s) for each.
66  *
67  * Failure conditions:
68  * - invalid entity handles (not vertices, non-existent entity, etc.)
69  * - range is empty (<code>iter == end</code>)
70  * - <code>output_array</code> is null
71  * - insufficient space in <code>output_array</code>
72  *
73  *\param which_array The coordinate to retrieve (0-&gt;X, 1-&gt;Y, 2-&gt;Z, -1-&gt;all)
74  *\param begin The first node handle.
75  *\param end One past the last node handle.
76  *\param output_size The size of <code>output_array</code>.
77  *\param output_array The memory in which to write the node coordinates.
78  *\author Jason Kraftcheck
79  */
80  ErrorCode get_node_coords( const int which_array,
81  Range::const_iterator begin,
82  const Range::const_iterator& end,
83  const size_t output_size,
84  double* const output_array );
85 
86  /** Get connectivity for elements
87  *
88  * Get the connectivity list for a range of elements.
89  *
90  *\param num_elements Number of elements for which connectivity is needed
91  *\param vertices_per_elem Number of vertices to retrieve for each
92  * element.
93  *\param node_id_tag A tag with integer values.
94  *\param entities Entities being queried
95  *\param element_id_tag If non-zero, elements are tagged with an id starting at start_element_id
96  *\param start_element_id Starting id value for element_id_tag
97  *\param add_sizes If true, writes size of connect array before connectivity in array
98  */
99  ErrorCode get_element_connect( const int num_elements,
100  const int verts_per_element,
101  Tag node_id_tag,
102  const Range& entities,
103  Tag element_id_tag,
104  int start_element_id,
105  int* array,
106  bool add_sizes = false );
107 
108  /** Get connectivity for elements
109  *
110  * Get the connectivity list for a range of elements.
111  *
112  * Failure cases:
113  * - Passed range is empty (<code>begin == end</code>).
114  * - <code>vertices_per_elem</code> is less than one
115  * - <code>element_array</code> is null.
116  * - The range contains invalid handles (non-existent entities,
117  * not an element, etc.)
118  * - Retrieving ID tag for an entity failed.
119  * - Insufficient space in passed array.
120  *
121  *\param begin The first element handle
122  *\param end One past the last element handle
123  *\param vertices_per_elem Number of vertices to retrieve for each
124  * element. If the element has more vertices, the
125  * element connectivity will be truncated. If
126  * <code>vertices_per_elem</code> is greater than the
127  * number of nodes for an element, the data will be
128  * padded with zeros.
129  *\param node_id_tag A tag with integer values.
130  *\param array_size The length of <code>element_array</code>
131  *\param element_array The memory location at which to store the
132  * connectivity list.
133  *\param add_sizes If true, writes size of connect array before connectivity in array
134  *\author Jason Kraftcheck
135  */
136  ErrorCode get_element_connect( Range::const_iterator begin,
137  const Range::const_iterator& end,
138  const int vertices_per_elem,
139  Tag node_id_tag,
140  const size_t array_size,
141  int* const element_array,
142  bool add_sizes = false );
143 
144  /** Get connectivity for elements
145  *
146  * Get the connectivity list for a range of elements.
147  *
148  * Failure cases:
149  * - Passed range is empty (<code>begin == end</code>).
150  * - <code>vertices_per_elem</code> is less than one
151  * - <code>element_array</code> is null.
152  * - The range contains invalid handles (non-existent entities,
153  * not an element, etc.)
154  * - Insufficient space in passed array.
155  *
156  *\param begin The first element handle
157  *\param end One past the last element handle
158  *\param vertices_per_elem Number of vertices to retrieve for each
159  * element. If the element has more vertices, the
160  * element connectivity will be truncated. If
161  * <code>vertices_per_elem</code> is greater than the
162  * number of nodes for an element, the data will be
163  * padded with zeros.
164  *\param array_size The length of <code>element_array</code>
165  *\param element_array The memory location at which to store the
166  * connectivity list.
167  *\author Jason Kraftcheck
168  */
169  virtual ErrorCode get_element_connect( Range::const_iterator begin,
170  const Range::const_iterator& end,
171  const int vertices_per_elem,
172  const size_t array_size,
173  EntityHandle* const element_array );
174 
175  /** Get poly (polygon or polyhedron) connectivity size
176  *\param begin First iterator in range of poly
177  *\param end One past last in range of poly.
178  *\param connectivity_size The length of the connectivity list
179  * For the specified range of polyhedra.
180  *\author Jason Kraftcheck
181  */
182  virtual ErrorCode get_poly_connect_size( Range::const_iterator begin,
183  const Range::const_iterator& end,
184  int& connectivity_size );
185 
186  /** Get poly (polygon or polyhedron) connectivity.
187  *
188  * This function will add as many polys as possible to the
189  * passed arrays given the sizes of those arrays. It will
190  * then pass back position at which it stopped and the sizes
191  * of the data written to the arrays.
192  *
193  *\param iter As input, the first element handle.
194  * As output, one past the last element handle
195  * for which data was written to the arrays.
196  *\param end The iterator at which to stop.
197  *\param node_id_tag A tag with integer values.
198  *\param element_array_len As input, length of <code>element_array</code>.
199  * As output, the number of entries written in that
200  * array.
201  *\param element_array The memory location at which to store the
202  * connectivity list.
203  *\param index_array_len As input, the length of <code>index_array</code>.
204  * As output, the number of entries written in that
205  * array.
206  *\param index_array The memory location at which to store offsets.
207  *\param index_offset Value to offset (add to) index values. As output
208  * the input value plus the amount of data
209  * written to the element array. (The value you
210  * presumably want to pass to the next call.)
211  *\author Jason Kraftcheck
212  */
213  virtual ErrorCode get_poly_connect( Range::const_iterator& iter,
214  const Range::const_iterator& end,
215  const Tag node_id_tag,
216  size_t& handle_array_len,
217  int* const handle_array,
218  size_t& index_array_len,
219  int* const index_array,
220  int& index_offset );
221 
222  //! Get a set of nodes that represent a set of elements
223  ErrorCode gather_nodes_from_elements( const Range& elements, const Tag node_bit_mark_tag, Range& nodes );
224 
225  //! Assign ids to input elements starting with start_id, written to id_tag
226  //! if zero, assigns to GLOBAL_ID_TAG_NAME
227  ErrorCode assign_ids( Range& elements, Tag id_tag, const int start_id );
228 
229  /** Get explicit adjacencies
230  *
231  * Get explicit adjacences stored in database.
232  * Does not create any explicit adjacencies or search for
233  * implicit ones.
234  *
235  *\param entity The entity to retrieve adjacencies for.
236  *\param id_tag The global ID tag
237  *\param adj The output list of global IDs of adjacent entities.
238  */
239  ErrorCode get_adjacencies( EntityHandle entity, Tag id_tag, std::vector< int >& adj );
240 
241  ErrorCode get_adjacencies( EntityHandle entity, const EntityHandle*& adj_array, int& num_adj );
242 
243  /**\brief Get list of tags to write.
244  *
245  * Get the list of tags to write to the file, possibly using
246  * an optional user-specified tag list. This function consolidates
247  * some common code for file writers to use to figure out what
248  * tag data to write to the file. It provides the following features:
249  * o filter list based on user-specified array of tag handles
250  * o filter internal tags (those for which the name is prefixed with
251  * two underscore characters)
252  * o filter anonymous tags
253  * o optionally filter variable-length tags.
254  *
255  *\author Jason Kraftcheck
256  *\param result_list List of tag handles for which to write data
257  *\param user_tag_list Optional array of tag handles passed by user
258  * to write to file.
259  *\param include_variable_length_tags If false, return only fixed-length
260  * tags.
261  */
262  virtual ErrorCode get_tag_list( std::vector< Tag >& result_list,
263  const Tag* user_tag_list = 0,
264  int user_tag_list_length = 0,
265  bool include_variable_length_tags = true );
266 
267  /*\brief Get pointers to internal storage of entity data
268  *
269  * Get pointers to element connectivity or set content storage.
270  *\param query_begin Start of range of entities for which to return results
271  *\param query_end End of range of entities for which to return results.
272  *\param output_pointer_array Result list of pointers. Points to either
273  * element connectivity or set contents. Note: set contents
274  * may be in range-compacted format.
275  *\param lengths Optional per-entity length of list. If passed, then
276  * always set, for each entity, to the number of values in the
277  * array passed back in \c output_pointer_array
278  *\param relation If entity is entity set, which set data to return
279  * (contents array, parent array, or child array). If
280  * entity is an element, then CONTENTS for complete connectivity
281  * or TOPOLOGICAL for only corner vertices.
282  *\param flags Optional per-entity flag values. If passed, then
283  * always set to zero for elements and set to set creation
284  * flags for entity sets.
285  *\return MB_STRUCTURED_MESH if one or more input elements are stored as
286  * structured mesh and therefore do not have explicit storage.
287  * MB_TYPE_OUT_OF_RANGE if called for vertices.
288  */
289  virtual ErrorCode get_entity_list_pointers( Range::const_iterator query_begin,
290  Range::const_iterator query_end,
291  EntityHandle const** output_pointer_array,
292  EntityListType relation = CONTENTS,
293  int* lengths = 0,
294  unsigned char* flags = 0 );
295 
296  /*\brief Get pointers to internal storage of entity data
297  *
298  * Get pointers to element connectivity or set content storage.
299  *\param entities Pointer to list of entities for which to return results
300  *\param num_entities Number of entities in list
301  *\param output_pointer_array Result list of pointers. Points to either
302  * element connectivity or set contents. Note: set contents
303  * may be in range-compacted format.
304  *\param lengths Optional per-entity length of list. If passed, then
305  * always set, for each entity, to the number of values in the
306  * array passed back in \c output_pointer_array
307  *\param relation If entity is entity set, which set data to return
308  * (contents array, parent array, or child array). If
309  * entity is an element, then CONTENTS for complete connectivity
310  * or TOPOLOGICAL for only corner vertices.
311  *\param flags Optional per-entity flag values. If passed, then
312  * always set to zero for elements and set to set creation
313  * flags for entity sets.
314  *\return MB_STRUCTURED_MESH if one or more input elements are stored as
315  * structured mesh and therefore do not have explicit storage.
316  * MB_TYPE_OUT_OF_RANGE if called for vertices.
317  */
318  virtual ErrorCode get_entity_list_pointers( EntityHandle const* entities,
319  int num_entities,
320  EntityHandle const** output_pointer_array,
321  EntityListType relation = CONTENTS,
322  int* lengths = 0,
323  unsigned char* flags = 0 );
324 };
325 
326 } // namespace moab
327 
328 #endif