WriteUtil.hpp

Go to the documentation of this file.

/**
 * MOAB, a Mesh-Oriented datABase, is a software component for creating,
 * storing and accessing finite element mesh data.
 *
 * Copyright 2004 Sandia Corporation.  Under the terms of Contract
 * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
 * retains certain rights in this software.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 */

#ifndef MB_WRITE_UTIL_HPP
#define MB_WRITE_UTIL_HPP

#ifndef IS_BUILDING_MB
#error "WriteUtil.hpp isn't supposed to be included into an application"
#endif

#include "moab/WriteUtilIface.hpp"

namespace moab
{

class Core;

class WriteUtil : public WriteUtilIface
{
  private:
    //! Pointer to the Core
    Core* mMB;

  public:
    //! Constructor takes Core pointer
    WriteUtil( Core* mdb );

    //! Destructor
    ~WriteUtil() {}

    //! Check if the specified file already exists.
    //! Returns MB_SUCCESS if file does not exist, MB_ALREADY_ALLOCATED
    //! if file does exist, or MB_FAILURE for some other error condition.
    virtual ErrorCode check_doesnt_exist( const char* file_name );

    //! Gather all entities in the mesh, or in the sets specified
    virtual ErrorCode gather_entities(
        Range& all_ents,                     /**< range in which entities are returned */
        const EntityHandle* ent_sets = NULL, /**< entity sets whose contents are to be gathered */
        const int num_sets           = 0 /**< number of sets in list */ );

    //! Gets arrays for coordinate data from the MB
    ErrorCode get_node_coords( const int num_arrays,
                               const int num_nodes,
                               const Range& entities,
                               Tag node_id_tag,
                               const int start_node_id,
                               std::vector< double* >& arrays );

    /** Get an array of coordinate values for nodes
     *
     * Given a range of node handles, retrieve a single or multiple coordinate
     * value(s) for each.
     *
     * Failure conditions:
     *  - invalid entity handles (not vertices, non-existent entity, etc.)
     *  - range is empty (<code>iter == end</code>)
     *  - <code>output_array</code> is null
     *  - insufficient space in <code>output_array</code>
     *
     *\param which_array  The coordinate to retrieve (0-&gt;X, 1-&gt;Y, 2-&gt;Z, -1-&gt;all)
     *\param begin        The first node handle.
     *\param end          One past the last node handle.
     *\param output_size  The size of <code>output_array</code>.
     *\param output_array The memory in which to write the node coordinates.
     *\author Jason Kraftcheck
     */
    ErrorCode get_node_coords( const int which_array,
                               Range::const_iterator begin,
                               const Range::const_iterator& end,
                               const size_t output_size,
                               double* const output_array );

    /** Get connectivity for elements
     *
     * Get the connectivity list for a range of elements.
     *
     *\param num_elements Number of elements for which connectivity is needed
     *\param vertices_per_elem Number of vertices to retrieve for each
     *                    element.
     *\param node_id_tag  A tag with integer values.
     *\param entities Entities being queried
     *\param element_id_tag If non-zero, elements are tagged with an id starting at start_element_id
     *\param start_element_id Starting id value for element_id_tag
     *\param add_sizes If true, writes size of connect array before connectivity in array
     */
    ErrorCode get_element_connect( const int num_elements,
                                   const int verts_per_element,
                                   Tag node_id_tag,
                                   const Range& entities,
                                   Tag element_id_tag,
                                   int start_element_id,
                                   int* array,
                                   bool add_sizes = false );

    /** Get connectivity for elements
     *
     * Get the connectivity list for a range of elements.
     *
     * Failure cases:
     *  - Passed range is empty (<code>begin == end</code>).
     *  - <code>vertices_per_elem</code> is less than one
     *  - <code>element_array</code> is null.
     *  - The range contains invalid handles (non-existent entities,
     *      not an element, etc.)
     *  - Retrieving ID tag for an entity failed.
     *  - Insufficient space in passed array.
     *
     *\param begin        The first element handle
     *\param end          One past the last element handle
     *\param vertices_per_elem Number of vertices to retrieve for each
     *                    element. If the element has more vertices, the
     *                    element connectivity will be truncated. If
     *                    <code>vertices_per_elem</code> is greater than the
     *                    number of nodes for an element, the data will be
     *                    padded with zeros.
     *\param node_id_tag  A tag with integer values.
     *\param array_size   The length of <code>element_array</code>
     *\param element_array The memory location at which to store the
     *                    connectivity list.
     *\param add_sizes If true, writes size of connect array before connectivity in array
     *\author Jason Kraftcheck
     */
    ErrorCode get_element_connect( Range::const_iterator begin,
                                   const Range::const_iterator& end,
                                   const int vertices_per_elem,
                                   Tag node_id_tag,
                                   const size_t array_size,
                                   int* const element_array,
                                   bool add_sizes = false );

    /** Get connectivity for elements
     *
     * Get the connectivity list for a range of elements.
     *
     * Failure cases:
     *  - Passed range is empty (<code>begin == end</code>).
     *  - <code>vertices_per_elem</code> is less than one
     *  - <code>element_array</code> is null.
     *  - The range contains invalid handles (non-existent entities,
     *      not an element, etc.)
     *  - Insufficient space in passed array.
     *
     *\param begin        The first element handle
     *\param end          One past the last element handle
     *\param vertices_per_elem Number of vertices to retrieve for each
     *                    element. If the element has more vertices, the
     *                    element connectivity will be truncated. If
     *                    <code>vertices_per_elem</code> is greater than the
     *                    number of nodes for an element, the data will be
     *                    padded with zeros.
     *\param array_size   The length of <code>element_array</code>
     *\param element_array The memory location at which to store the
     *                    connectivity list.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_element_connect( Range::const_iterator begin,
                                           const Range::const_iterator& end,
                                           const int vertices_per_elem,
                                           const size_t array_size,
                                           EntityHandle* const element_array );

    /** Get poly (polygon or polyhedron) connectivity size
     *\param begin  First iterator in range of poly
     *\param end    One past last in range of poly.
     *\param connectivity_size  The length of the connectivity list
     *              For the specified range of polyhedra.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_poly_connect_size( Range::const_iterator begin,
                                             const Range::const_iterator& end,
                                             int& connectivity_size );

    /** Get poly (polygon or polyhedron) connectivity.
     *
     * This function will add as many polys as possible to the
     * passed arrays given the sizes of those arrays. It will
     * then pass back position at which it stopped and the sizes
     * of the data written to the arrays.
     *
     *\param iter               As input, the first element handle.
     *                          As output, one past the last element handle
     *                          for which data was written to the arrays.
     *\param end                The iterator at which to stop.
     *\param node_id_tag        A tag with integer values.
     *\param element_array_len  As input, length of <code>element_array</code>.
     *                          As output, the number of entries written in that
     *                          array.
     *\param element_array      The memory location at which to store the
     *                          connectivity list.
     *\param index_array_len    As input, the length of <code>index_array</code>.
     *                          As output, the number of entries written in that
     *                          array.
     *\param index_array        The memory location at which to store offsets.
     *\param index_offset       Value to offset (add to) index values. As output
     *                          the input value plus the amount of data
     *                          written to the element array. (The value you
     *                          presumably want to pass to the next call.)
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_poly_connect( Range::const_iterator& iter,
                                        const Range::const_iterator& end,
                                        const Tag node_id_tag,
                                        size_t& handle_array_len,
                                        int* const handle_array,
                                        size_t& index_array_len,
                                        int* const index_array,
                                        int& index_offset );

    //! Get a set of nodes that represent a set of elements
    ErrorCode gather_nodes_from_elements( const Range& elements, const Tag node_bit_mark_tag, Range& nodes );

    //! Assign ids to input elements starting with start_id, written to id_tag
    //! if zero, assigns to GLOBAL_ID_TAG_NAME
    ErrorCode assign_ids( Range& elements, Tag id_tag, const int start_id );

    /** Get explicit adjacencies
     *
     * Get explicit adjacences stored in database.
     * Does not create any explicit adjacencies or search for
     * implicit ones.
     *
     *\param entity  The entity to retrieve adjacencies for.
     *\param id_tag  The global ID tag
     *\param adj     The output list of global IDs of adjacent entities.
     */
    ErrorCode get_adjacencies( EntityHandle entity, Tag id_tag, std::vector< int >& adj );

    ErrorCode get_adjacencies( EntityHandle entity, const EntityHandle*& adj_array, int& num_adj );

    /**\brief Get list of tags to write.
     *
     * Get the list of tags to write to the file, possibly using
     * an optional user-specified tag list. This function consolidates
     * some common code for file writers to use to figure out what
     * tag data to write to the file. It provides the following features:
     *  o filter list based on user-specified array of tag handles
     *  o filter internal tags (those for which the name is prefixed with
     *    two underscore characters)
     *  o filter anonymous tags
     *  o optionally filter variable-length tags.
     *
     *\author Jason Kraftcheck
     *\param result_list List of tag handles for which to write data
     *\param user_tag_list Optional array of tag handles passed by user
     *                     to write to file.
     *\param include_variable_length_tags If false, return only fixed-length
     *                                    tags.
     */
    virtual ErrorCode get_tag_list( std::vector< Tag >& result_list,
                                    const Tag* user_tag_list          = 0,
                                    int user_tag_list_length          = 0,
                                    bool include_variable_length_tags = true );

    /*\brief Get pointers to internal storage of entity data
     *
     * Get pointers to element connectivity or set content storage.
     *\param query_begin Start of range of entities for which to return results
     *\param query_end   End of range of entities for which to return results.
     *\param output_pointer_array Result list of pointers. Points to either
     *          element connectivity or set contents. Note: set contents
     *          may be in range-compacted format.
     *\param lengths Optional per-entity length of list. If passed, then
     *          always set, for each entity, to the number of values in the
     *          array passed back in \c output_pointer_array
     *\param relation If entity is entity set, which set data to return
     *          (contents array, parent array, or child array). If
     *          entity is an element, then CONTENTS for complete connectivity
     *          or TOPOLOGICAL for only corner vertices.
     *\param flags Optional per-entity flag values. If passed, then
     *          always set to zero for elements and set to set creation
     *          flags for entity sets.
     *\return MB_STRUCTURED_MESH if one or more input elements are stored as
     *          structured mesh and therefore do not have explicit storage.
     *        MB_TYPE_OUT_OF_RANGE if called for vertices.
     */
    virtual ErrorCode get_entity_list_pointers( Range::const_iterator query_begin,
                                                Range::const_iterator query_end,
                                                EntityHandle const** output_pointer_array,
                                                EntityListType relation = CONTENTS,
                                                int* lengths            = 0,
                                                unsigned char* flags    = 0 );

    /*\brief Get pointers to internal storage of entity data
     *
     * Get pointers to element connectivity or set content storage.
     *\param entities Pointer to list of entities for which to return results
     *\param num_entities Number of entities in list
     *\param output_pointer_array Result list of pointers. Points to either
     *          element connectivity or set contents. Note: set contents
     *          may be in range-compacted format.
     *\param lengths Optional per-entity length of list. If passed, then
     *          always set, for each entity, to the number of values in the
     *          array passed back in \c output_pointer_array
     *\param relation If entity is entity set, which set data to return
     *          (contents array, parent array, or child array). If
     *          entity is an element, then CONTENTS for complete connectivity
     *          or TOPOLOGICAL for only corner vertices.
     *\param flags Optional per-entity flag values. If passed, then
     *          always set to zero for elements and set to set creation
     *          flags for entity sets.
     *\return MB_STRUCTURED_MESH if one or more input elements are stored as
     *          structured mesh and therefore do not have explicit storage.
     *        MB_TYPE_OUT_OF_RANGE if called for vertices.
     */
    virtual ErrorCode get_entity_list_pointers( EntityHandle const* entities,
                                                int num_entities,
                                                EntityHandle const** output_pointer_array,
                                                EntityListType relation = CONTENTS,
                                                int* lengths            = 0,
                                                unsigned char* flags    = 0 );
};

}  // namespace moab

#endif