Mesh Oriented datABase  (version 5.4.1)
Array-based unstructured mesh datastructure
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,
00056                                const int num_nodes,
00057                                const Range& entities,
00058                                Tag node_id_tag,
00059                                const int start_node_id,
00060                                std::vector< double* >& arrays );
00061 
00062     /** Get an array of coordinate values for nodes
00063      *
00064      * Given a range of node handles, retrieve a single or multiple coordinate
00065      * value(s) for each.
00066      *
00067      * Failure conditions:
00068      *  - invalid entity handles (not vertices, non-existent entity, etc.)
00069      *  - range is empty (<code>iter == end</code>)
00070      *  - <code>output_array</code> is null
00071      *  - insufficient space in <code>output_array</code>
00072      *
00073      *\param which_array  The coordinate to retrieve (0-&gt;X, 1-&gt;Y, 2-&gt;Z, -1-&gt;all)
00074      *\param begin        The first node handle.
00075      *\param end          One past the last node handle.
00076      *\param output_size  The size of <code>output_array</code>.
00077      *\param output_array The memory in which to write the node coordinates.
00078      *\author Jason Kraftcheck
00079      */
00080     ErrorCode get_node_coords( const int which_array,
00081                                Range::const_iterator begin,
00082                                const Range::const_iterator& end,
00083                                const size_t output_size,
00084                                double* const output_array );
00085 
00086     /** Get connectivity for elements
00087      *
00088      * Get the connectivity list for a range of elements.
00089      *
00090      *\param num_elements Number of elements for which connectivity is needed
00091      *\param vertices_per_elem Number of vertices to retrieve for each
00092      *                    element.
00093      *\param node_id_tag  A tag with integer values.
00094      *\param entities Entities being queried
00095      *\param element_id_tag If non-zero, elements are tagged with an id starting at start_element_id
00096      *\param start_element_id Starting id value for element_id_tag
00097      *\param add_sizes If true, writes size of connect array before connectivity in array
00098      */
00099     ErrorCode get_element_connect( const int num_elements,
00100                                    const int verts_per_element,
00101                                    Tag node_id_tag,
00102                                    const Range& entities,
00103                                    Tag element_id_tag,
00104                                    int start_element_id,
00105                                    int* array,
00106                                    bool add_sizes = false );
00107 
00108     /** Get connectivity for elements
00109      *
00110      * Get the connectivity list for a range of elements.
00111      *
00112      * Failure cases:
00113      *  - Passed range is empty (<code>begin == end</code>).
00114      *  - <code>vertices_per_elem</code> is less than one
00115      *  - <code>element_array</code> is null.
00116      *  - The range contains invalid handles (non-existent entities,
00117      *      not an element, etc.)
00118      *  - Retrieving ID tag for an entity failed.
00119      *  - Insufficient space in passed array.
00120      *
00121      *\param begin        The first element handle
00122      *\param end          One past the last element handle
00123      *\param vertices_per_elem Number of vertices to retrieve for each
00124      *                    element. If the element has more vertices, the
00125      *                    element connectivity will be truncated. If
00126      *                    <code>vertices_per_elem</code> is greater than the
00127      *                    number of nodes for an element, the data will be
00128      *                    padded with zeros.
00129      *\param node_id_tag  A tag with integer values.
00130      *\param array_size   The length of <code>element_array</code>
00131      *\param element_array The memory location at which to store the
00132      *                    connectivity list.
00133      *\param add_sizes If true, writes size of connect array before connectivity in array
00134      *\author Jason Kraftcheck
00135      */
00136     ErrorCode get_element_connect( Range::const_iterator begin,
00137                                    const Range::const_iterator& end,
00138                                    const int vertices_per_elem,
00139                                    Tag node_id_tag,
00140                                    const size_t array_size,
00141                                    int* const element_array,
00142                                    bool add_sizes = false );
00143 
00144     /** Get connectivity for elements
00145      *
00146      * Get the connectivity list for a range of elements.
00147      *
00148      * Failure cases:
00149      *  - Passed range is empty (<code>begin == end</code>).
00150      *  - <code>vertices_per_elem</code> is less than one
00151      *  - <code>element_array</code> is null.
00152      *  - The range contains invalid handles (non-existent entities,
00153      *      not an element, etc.)
00154      *  - Insufficient space in passed array.
00155      *
00156      *\param begin        The first element handle
00157      *\param end          One past the last element handle
00158      *\param vertices_per_elem Number of vertices to retrieve for each
00159      *                    element. If the element has more vertices, the
00160      *                    element connectivity will be truncated. If
00161      *                    <code>vertices_per_elem</code> is greater than the
00162      *                    number of nodes for an element, the data will be
00163      *                    padded with zeros.
00164      *\param array_size   The length of <code>element_array</code>
00165      *\param element_array The memory location at which to store the
00166      *                    connectivity list.
00167      *\author Jason Kraftcheck
00168      */
00169     virtual ErrorCode get_element_connect( Range::const_iterator begin,
00170                                            const Range::const_iterator& end,
00171                                            const int vertices_per_elem,
00172                                            const size_t array_size,
00173                                            EntityHandle* const element_array );
00174 
00175     /** Get poly (polygon or polyhedron) connectivity size
00176      *\param begin  First iterator in range of poly
00177      *\param end    One past last in range of poly.
00178      *\param connectivity_size  The length of the connectivity list
00179      *              For the specified range of polyhedra.
00180      *\author Jason Kraftcheck
00181      */
00182     virtual ErrorCode get_poly_connect_size( Range::const_iterator begin,
00183                                              const Range::const_iterator& end,
00184                                              int& connectivity_size );
00185 
00186     /** Get poly (polygon or polyhedron) connectivity.
00187      *
00188      * This function will add as many polys as possible to the
00189      * passed arrays given the sizes of those arrays. It will
00190      * then pass back position at which it stopped and the sizes
00191      * of the data written to the arrays.
00192      *
00193      *\param iter               As input, the first element handle.
00194      *                          As output, one past the last element handle
00195      *                          for which data was written to the arrays.
00196      *\param end                The iterator at which to stop.
00197      *\param node_id_tag        A tag with integer values.
00198      *\param element_array_len  As input, length of <code>element_array</code>.
00199      *                          As output, the number of entries written in that
00200      *                          array.
00201      *\param element_array      The memory location at which to store the
00202      *                          connectivity list.
00203      *\param index_array_len    As input, the length of <code>index_array</code>.
00204      *                          As output, the number of entries written in that
00205      *                          array.
00206      *\param index_array        The memory location at which to store offsets.
00207      *\param index_offset       Value to offset (add to) index values. As output
00208      *                          the input value plus the amount of data
00209      *                          written to the element array. (The value you
00210      *                          presumably want to pass to the next call.)
00211      *\author Jason Kraftcheck
00212      */
00213     virtual ErrorCode get_poly_connect( Range::const_iterator& iter,
00214                                         const Range::const_iterator& end,
00215                                         const Tag node_id_tag,
00216                                         size_t& handle_array_len,
00217                                         int* const handle_array,
00218                                         size_t& index_array_len,
00219                                         int* const index_array,
00220                                         int& index_offset );
00221 
00222     //! Get a set of nodes that represent a set of elements
00223     ErrorCode gather_nodes_from_elements( const Range& elements, const Tag node_bit_mark_tag, Range& nodes );
00224 
00225     //! Assign ids to input elements starting with start_id, written to id_tag
00226     //! if zero, assigns to GLOBAL_ID_TAG_NAME
00227     ErrorCode assign_ids( Range& elements, Tag id_tag, const int start_id );
00228 
00229     /** Get explicit adjacencies
00230      *
00231      * Get explicit adjacences stored in database.
00232      * Does not create any explicit adjacencies or search for
00233      * implicit ones.
00234      *
00235      *\param entity  The entity to retrieve adjacencies for.
00236      *\param id_tag  The global ID tag
00237      *\param adj     The output list of global IDs of adjacent entities.
00238      */
00239     ErrorCode get_adjacencies( EntityHandle entity, Tag id_tag, std::vector< int >& adj );
00240 
00241     ErrorCode get_adjacencies( EntityHandle entity, const EntityHandle*& adj_array, int& num_adj );
00242 
00243     /**\brief Get list of tags to write.
00244      *
00245      * Get the list of tags to write to the file, possibly using
00246      * an optional user-specified tag list. This function consolidates
00247      * some common code for file writers to use to figure out what
00248      * tag data to write to the file. It provides the following features:
00249      *  o filter list based on user-specified array of tag handles
00250      *  o filter internal tags (those for which the name is prefixed with
00251      *    two underscore characters)
00252      *  o filter anonymous tags
00253      *  o optionally filter variable-length tags.
00254      *
00255      *\author Jason Kraftcheck
00256      *\param result_list List of tag handles for which to write data
00257      *\param user_tag_list Optional array of tag handles passed by user
00258      *                     to write to file.
00259      *\param include_variable_length_tags If false, return only fixed-length
00260      *                                    tags.
00261      */
00262     virtual ErrorCode get_tag_list( std::vector< Tag >& result_list,
00263                                     const Tag* user_tag_list          = 0,
00264                                     int user_tag_list_length          = 0,
00265                                     bool include_variable_length_tags = true );
00266 
00267     /*\brief Get pointers to internal storage of entity data
00268      *
00269      * Get pointers to element connectivity or set content storage.
00270      *\param query_begin Start of range of entities for which to return results
00271      *\param query_end   End of range of entities for which to return results.
00272      *\param output_pointer_array Result list of pointers. Points to either
00273      *          element connectivity or set contents. Note: set contents
00274      *          may be in range-compacted format.
00275      *\param lengths Optional per-entity length of list. If passed, then
00276      *          always set, for each entity, to the number of values in the
00277      *          array passed back in \c output_pointer_array
00278      *\param relation If entity is entity set, which set data to return
00279      *          (contents array, parent array, or child array). If
00280      *          entity is an element, then CONTENTS for complete connectivity
00281      *          or TOPOLOGICAL for only corner vertices.
00282      *\param flags Optional per-entity flag values. If passed, then
00283      *          always set to zero for elements and set to set creation
00284      *          flags for entity sets.
00285      *\return MB_STRUCTURED_MESH if one or more input elements are stored as
00286      *          structured mesh and therefore do not have explicit storage.
00287      *        MB_TYPE_OUT_OF_RANGE if called for vertices.
00288      */
00289     virtual ErrorCode get_entity_list_pointers( Range::const_iterator query_begin,
00290                                                 Range::const_iterator query_end,
00291                                                 EntityHandle const** output_pointer_array,
00292                                                 EntityListType relation = CONTENTS,
00293                                                 int* lengths            = 0,
00294                                                 unsigned char* flags    = 0 );
00295 
00296     /*\brief Get pointers to internal storage of entity data
00297      *
00298      * Get pointers to element connectivity or set content storage.
00299      *\param entities Pointer to list of entities for which to return results
00300      *\param num_entities Number of entities in list
00301      *\param output_pointer_array Result list of pointers. Points to either
00302      *          element connectivity or set contents. Note: set contents
00303      *          may be in range-compacted format.
00304      *\param lengths Optional per-entity length of list. If passed, then
00305      *          always set, for each entity, to the number of values in the
00306      *          array passed back in \c output_pointer_array
00307      *\param relation If entity is entity set, which set data to return
00308      *          (contents array, parent array, or child array). If
00309      *          entity is an element, then CONTENTS for complete connectivity
00310      *          or TOPOLOGICAL for only corner vertices.
00311      *\param flags Optional per-entity flag values. If passed, then
00312      *          always set to zero for elements and set to set creation
00313      *          flags for entity sets.
00314      *\return MB_STRUCTURED_MESH if one or more input elements are stored as
00315      *          structured mesh and therefore do not have explicit storage.
00316      *        MB_TYPE_OUT_OF_RANGE if called for vertices.
00317      */
00318     virtual ErrorCode get_entity_list_pointers( EntityHandle const* entities,
00319                                                 int num_entities,
00320                                                 EntityHandle const** output_pointer_array,
00321                                                 EntityListType relation = CONTENTS,
00322                                                 int* lengths            = 0,
00323                                                 unsigned char* flags    = 0 );
00324 };
00325 
00326 }  // namespace moab
00327 
00328 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines