MOAB: Mesh Oriented datABase  (version 5.3.0)
WriteUtil.hpp
Go to the documentation of this file.
00001 /**
00002  * MOAB, a Mesh-Oriented datABase, is a software component for creating,
00003  * storing and accessing finite element mesh data.
00004  *
00005  * Copyright 2004 Sandia Corporation.  Under the terms of Contract
00006  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
00007  * retains certain rights in this software.
00008  *
00009  * This library is free software; you can redistribute it and/or
00010  * modify it under the terms of the GNU Lesser General Public
00011  * License as published by the Free Software Foundation; either
00012  * version 2.1 of the License, or (at your option) any later version.
00013  *
00014  */
00015 
00016 #ifndef MB_WRITE_UTIL_HPP
00017 #define MB_WRITE_UTIL_HPP
00018 
00019 #ifndef IS_BUILDING_MB
00020 #error "WriteUtil.hpp isn't supposed to be included into an application"
00021 #endif
00022 
00023 #include "moab/WriteUtilIface.hpp"
00024 
00025 namespace moab
00026 {
00027 
00028 class Core;
00029 
00030 class WriteUtil : public WriteUtilIface
00031 {
00032   private:
00033     //! Pointer to the Core
00034     Core* mMB;
00035 
00036   public:
00037     //! Constructor takes Core pointer
00038     WriteUtil( Core* mdb );
00039 
00040     //! Destructor
00041     ~WriteUtil() {}
00042 
00043     //! Check if the specified file already exists.
00044     //! Returns MB_SUCCESS if file does not exist, MB_ALREADY_ALLOCATED
00045     //! if file does exist, or MB_FAILURE for some other error condition.
00046     virtual ErrorCode check_doesnt_exist( const char* file_name );
00047 
00048     //! Gather all entities in the mesh, or in the sets specified
00049     virtual ErrorCode gather_entities(
00050         Range& all_ents,                     /**< range in which entities are returned */
00051         const EntityHandle* ent_sets = NULL, /**< entity sets whose contents are to be gathered */
00052         const int num_sets           = 0 /**< number of sets in list */ );
00053 
00054     //! Gets arrays for coordinate data from the MB
00055     ErrorCode get_node_coords( const int num_arrays, const int num_nodes, const Range& entities, Tag node_id_tag,
00056                                const int start_node_id, std::vector< double* >& arrays );
00057 
00058     /** Get an array of coordinate values for nodes
00059      *
00060      * Given a range of node handles, retrieve a single or multiple coordinate
00061      * value(s) for each.
00062      *
00063      * Failure conditions:
00064      *  - invalid entity handles (not vertices, non-existent entity, etc.)
00065      *  - range is empty (<code>iter == end</code>)
00066      *  - <code>output_array</code> is null
00067      *  - insufficient space in <code>output_array</code>
00068      *
00069      *\param which_array  The coordinate to retrieve (0-&gt;X, 1-&gt;Y, 2-&gt;Z, -1-&gt;all)
00070      *\param begin        The first node handle.
00071      *\param end          One past the last node handle.
00072      *\param output_size  The size of <code>output_array</code>.
00073      *\param output_array The memory in which to write the node coordinates.
00074      *\author Jason Kraftcheck
00075      */
00076     ErrorCode get_node_coords( const int which_array, Range::const_iterator begin, const Range::const_iterator& end,
00077                                const size_t output_size, double* const output_array );
00078 
00079     /** Get connectivity for elements
00080      *
00081      * Get the connectivity list for a range of elements.
00082      *
00083      *\param num_elements Number of elements for which connectivity is needed
00084      *\param vertices_per_elem Number of vertices to retrieve for each
00085      *                    element.
00086      *\param node_id_tag  A tag with integer values.
00087      *\param entities Entities being queried
00088      *\param element_id_tag If non-zero, elements are tagged with an id starting at start_element_id
00089      *\param start_element_id Starting id value for element_id_tag
00090      *\param add_sizes If true, writes size of connect array before connectivity in array
00091      */
00092     ErrorCode get_element_connect( const int num_elements, const int verts_per_element, Tag node_id_tag,
00093                                    const Range& entities, Tag element_id_tag, int start_element_id, int* array,
00094                                    bool add_sizes = false );
00095 
00096     /** Get connectivity for elements
00097      *
00098      * Get the connectivity list for a range of elements.
00099      *
00100      * Failure cases:
00101      *  - Passed range is empty (<code>begin == end</code>).
00102      *  - <code>vertices_per_elem</code> is less than one
00103      *  - <code>element_array</code> is null.
00104      *  - The range contains invalid handles (non-existent entities,
00105      *      not an element, etc.)
00106      *  - Retrieving ID tag for an entity failed.
00107      *  - Insufficient space in passed array.
00108      *
00109      *\param begin        The first element handle
00110      *\param end          One past the last element handle
00111      *\param vertices_per_elem Number of vertices to retrieve for each
00112      *                    element. If the element has more vertices, the
00113      *                    element connectivity will be truncated. If
00114      *                    <code>vertices_per_elem</code> is greater than the
00115      *                    number of nodes for an element, the data will be
00116      *                    padded with zeros.
00117      *\param node_id_tag  A tag with integer values.
00118      *\param array_size   The length of <code>element_array</code>
00119      *\param element_array The memory location at which to store the
00120      *                    connectivity list.
00121      *\param add_sizes If true, writes size of connect array before connectivity in array
00122      *\author Jason Kraftcheck
00123      */
00124     ErrorCode get_element_connect( Range::const_iterator begin, const Range::const_iterator& end,
00125                                    const int vertices_per_elem, Tag node_id_tag, const size_t array_size,
00126                                    int* const element_array, bool add_sizes = false );
00127 
00128     /** Get connectivity for elements
00129      *
00130      * Get the connectivity list for a range of elements.
00131      *
00132      * Failure cases:
00133      *  - Passed range is empty (<code>begin == end</code>).
00134      *  - <code>vertices_per_elem</code> is less than one
00135      *  - <code>element_array</code> is null.
00136      *  - The range contains invalid handles (non-existent entities,
00137      *      not an element, etc.)
00138      *  - Insufficient space in passed array.
00139      *
00140      *\param begin        The first element handle
00141      *\param end          One past the last element handle
00142      *\param vertices_per_elem Number of vertices to retrieve for each
00143      *                    element. If the element has more vertices, the
00144      *                    element connectivity will be truncated. If
00145      *                    <code>vertices_per_elem</code> is greater than the
00146      *                    number of nodes for an element, the data will be
00147      *                    padded with zeros.
00148      *\param array_size   The length of <code>element_array</code>
00149      *\param element_array The memory location at which to store the
00150      *                    connectivity list.
00151      *\author Jason Kraftcheck
00152      */
00153     virtual ErrorCode get_element_connect( Range::const_iterator begin, const Range::const_iterator& end,
00154                                            const int vertices_per_elem, const size_t array_size,
00155                                            EntityHandle* const element_array );
00156 
00157     /** Get poly (polygon or polyhedron) connectivity size
00158      *\param begin  First iterator in range of poly
00159      *\param end    One past last in range of poly.
00160      *\param connectivity_size  The length of the connectivity list
00161      *              For the specified range of polyhedra.
00162      *\author Jason Kraftcheck
00163      */
00164     virtual ErrorCode get_poly_connect_size( Range::const_iterator begin, const Range::const_iterator& end,
00165                                              int& connectivity_size );
00166 
00167     /** Get poly (polygon or polyhedron) connectivity.
00168      *
00169      * This function will add as many polys as possible to the
00170      * passed arrays given the sizes of those arrays. It will
00171      * then pass back position at which it stopped and the sizes
00172      * of the data written to the arrays.
00173      *
00174      *\param iter               As input, the first element handle.
00175      *                          As output, one past the last element handle
00176      *                          for which data was written to the arrays.
00177      *\param end                The iterator at which to stop.
00178      *\param node_id_tag        A tag with integer values.
00179      *\param element_array_len  As input, length of <code>element_array</code>.
00180      *                          As output, the number of entries written in that
00181      *                          array.
00182      *\param element_array      The memory location at which to store the
00183      *                          connectivity list.
00184      *\param index_array_len    As input, the length of <code>index_array</code>.
00185      *                          As output, the number of entries written in that
00186      *                          array.
00187      *\param index_array        The memory location at which to store offsets.
00188      *\param index_offset       Value to offset (add to) index values. As output
00189      *                          the input value plus the amount of data
00190      *                          written to the element array. (The value you
00191      *                          presumably want to pass to the next call.)
00192      *\author Jason Kraftcheck
00193      */
00194     virtual ErrorCode get_poly_connect( Range::const_iterator& iter, const Range::const_iterator& end,
00195                                         const Tag node_id_tag, size_t& handle_array_len, int* const handle_array,
00196                                         size_t& index_array_len, int* const index_array, int& index_offset );
00197 
00198     //! Get a set of nodes that represent a set of elements
00199     ErrorCode gather_nodes_from_elements( const Range& elements, const Tag node_bit_mark_tag, Range& nodes );
00200 
00201     //! Assign ids to input elements starting with start_id, written to id_tag
00202     //! if zero, assigns to GLOBAL_ID_TAG_NAME
00203     ErrorCode assign_ids( Range& elements, Tag id_tag, const int start_id );
00204 
00205     /** Get explicit adjacencies
00206      *
00207      * Get explicit adjacences stored in database.
00208      * Does not create any explicit adjacencies or search for
00209      * implicit ones.
00210      *
00211      *\param entity  The entity to retrieve adjacencies for.
00212      *\param id_tag  The global ID tag
00213      *\param adj     The output list of global IDs of adjacent entities.
00214      */
00215     ErrorCode get_adjacencies( EntityHandle entity, Tag id_tag, std::vector< int >& adj );
00216 
00217     ErrorCode get_adjacencies( EntityHandle entity, const EntityHandle*& adj_array, int& num_adj );
00218 
00219     /**\brief Get list of tags to write.
00220      *
00221      * Get the list of tags to write to the file, possibly using
00222      * an optional user-specified tag list. This function consolidates
00223      * some common code for file writers to use to figure out what
00224      * tag data to write to the file. It provides the following features:
00225      *  o filter list based on user-specified array of tag handles
00226      *  o filter internal tags (those for which the name is prefixed with
00227      *    two underscore characters)
00228      *  o filter anonymous tags
00229      *  o optionally filter variable-length tags.
00230      *
00231      *\author Jason Kraftcheck
00232      *\param result_list List of tag handles for which to write data
00233      *\param user_tag_list Optional array of tag handles passed by user
00234      *                     to write to file.
00235      *\param include_variable_length_tags If false, return only fixed-length
00236      *                                    tags.
00237      */
00238     virtual ErrorCode get_tag_list( std::vector< Tag >& result_list, const Tag* user_tag_list = 0,
00239                                     int user_tag_list_length = 0, bool include_variable_length_tags = true );
00240 
00241     /*\brief Get pointers to internal storage of entity data
00242      *
00243      * Get pointers to element connectivity or set content storage.
00244      *\param query_begin Start of range of entities for which to return results
00245      *\param query_end   End of range of entities for which to return results.
00246      *\param output_pointer_array Result list of pointers. Points to either
00247      *          element connectivity or set contents. Note: set contents
00248      *          may be in range-compacted format.
00249      *\param lengths Optional per-entity length of list. If passed, then
00250      *          always set, for each entity, to the number of values in the
00251      *          array passed back in \c output_pointer_array
00252      *\param relation If entity is entity set, which set data to return
00253      *          (contents array, parent array, or child array). If
00254      *          entity is an element, then CONTENTS for complete connectivity
00255      *          or TOPOLOGICAL for only corner vertices.
00256      *\param flags Optional per-entity flag values. If passed, then
00257      *          always set to zero for elements and set to set creation
00258      *          flags for entity sets.
00259      *\return MB_STRUCTURED_MESH if one or more input elements are stored as
00260      *          structured mesh and therefore do not have explicit storage.
00261      *        MB_TYPE_OUT_OF_RANGE if called for vertices.
00262      */
00263     virtual ErrorCode get_entity_list_pointers( Range::const_iterator query_begin, Range::const_iterator query_end,
00264                                                 EntityHandle const** output_pointer_array,
00265                                                 EntityListType relation = CONTENTS, int* lengths = 0,
00266                                                 unsigned char* flags = 0 );
00267 
00268     /*\brief Get pointers to internal storage of entity data
00269      *
00270      * Get pointers to element connectivity or set content storage.
00271      *\param entities Pointer to list of entities for which to return results
00272      *\param num_entities Number of entities in list
00273      *\param output_pointer_array Result list of pointers. Points to either
00274      *          element connectivity or set contents. Note: set contents
00275      *          may be in range-compacted format.
00276      *\param lengths Optional per-entity length of list. If passed, then
00277      *          always set, for each entity, to the number of values in the
00278      *          array passed back in \c output_pointer_array
00279      *\param relation If entity is entity set, which set data to return
00280      *          (contents array, parent array, or child array). If
00281      *          entity is an element, then CONTENTS for complete connectivity
00282      *          or TOPOLOGICAL for only corner vertices.
00283      *\param flags Optional per-entity flag values. If passed, then
00284      *          always set to zero for elements and set to set creation
00285      *          flags for entity sets.
00286      *\return MB_STRUCTURED_MESH if one or more input elements are stored as
00287      *          structured mesh and therefore do not have explicit storage.
00288      *        MB_TYPE_OUT_OF_RANGE if called for vertices.
00289      */
00290     virtual ErrorCode get_entity_list_pointers( EntityHandle const* entities, int num_entities,
00291                                                 EntityHandle const** output_pointer_array,
00292                                                 EntityListType relation = CONTENTS, int* lengths = 0,
00293                                                 unsigned char* flags = 0 );
00294 };
00295 
00296 }  // namespace moab
00297 
00298 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines