Reading data

Routines for parsing surface grid from files into EBGeometry’s DCEL grids are given in the namespace EBGeometry::Parser. The source code is implemented in Source/EBGeometry_Parser.hpp.

Warning

EBGeometry is currently limited to reading binary and ASCII STL files and reconstructing DCEL grids from those. However, it is also possible to build DCEL grids from polygon soups read using third-party codes (see Using third-party sources).

Quickstart

If you have one or multiple STL files, you can quickly turn them into signed distance fields using

std::vector<std::string> files; // <---- List of file names.

const auto distanceFields = EBGeometry::Parser::readIntoLinearBVH<float>(files);

This will build DCEL meshes for each input file, and wrap the meshes in BVHs. See DCEL mesh SDF with compact BVH for further details.

Reading STL files

EBGeometry supports a native parser for binary and ASCII STL files, which can be read into a few different representations:

Into a DCEL mesh, see DCEL.
Into a signed distance function representation of a DCEL mesh, see Geometry representation.
Into a signed distance function representation of a DCEL mesh, but using a BVH accelerator in full representation.
Into a signed distance function representation of a DCEL mesh, but using a BVH accelerator in compact representation.

DCEL representation

To read one or multiple STL files and turn it into DCEL meshes, use

  /*!
    @brief Read a file containing a single watertight object and return it as a DCEL mesh
    @param[in] a_filename File name
  */
  template <typename T, typename Meta = DCEL::DefaultMetaData>
  inline static std::shared_ptr<EBGeometry::DCEL::MeshT<T, Meta>>
  readIntoDCEL(const std::string a_filename) noexcept;

  /*!
    @brief Read multiple files containing single watertight objects and return them as DCEL meshes
    @param[in] a_files File names
  */
  template <typename T, typename Meta = DCEL::DefaultMetaData>
  inline static std::vector<std::shared_ptr<EBGeometry::DCEL::MeshT<T, Meta>>>
  readIntoDCEL(const std::vector<std::string> a_files) noexcept;

Note that this will only expose the DCEL mesh, but not include any signed distance functionality.

DCEL mesh SDF

To read one or multiple STL files and also turn it into signed distance representations, use

  /*!
    @brief Read a file containing a single watertight object and return it as an implicit function.
    @param[in] a_filename File name
  */
  template <typename T, typename Meta = DCEL::DefaultMetaData>
  inline static std::shared_ptr<MeshSDF<T, Meta>>
  readIntoMesh(const std::string a_filename) noexcept;

  /*!
    @brief Read multiple files containing single watertight objects and return them as an implicit functions.
    @param[in] a_files File names
  */
  template <typename T, typename Meta = DCEL::DefaultMetaData>
  inline static std::vector<std::shared_ptr<MeshSDF<T, Meta>>>
  readIntoMesh(const std::vector<std::string> a_files) noexcept;

DCEL mesh SDF with full BVH

To read one or multiple STL files and turn it into signed distance representations using a full BVH representation, use

  /*!
    @brief Read a file containing a single watertight object and return it as a DCEL mesh enclosed in a full BVH.
    @param[in] a_filename File name
  */
  template <typename T,
            typename Meta = DCEL::DefaultMetaData,
            typename BV   = EBGeometry::BoundingVolumes::AABBT<T>,
            size_t K      = 4>
  inline static std::shared_ptr<FastMeshSDF<T, Meta, BV, K>>
  readIntoFullBVH(const std::string a_filename) noexcept;

  /*!
    @brief Read multiple files containing single watertight objects and return them as DCEL meshes enclosed in BVHs.
    @param[in] a_files File names
  */
  template <typename T,
            typename Meta = DCEL::DefaultMetaData,
            typename BV   = EBGeometry::BoundingVolumes::AABBT<T>,
            size_t K      = 4>
  inline static std::vector<std::shared_ptr<FastMeshSDF<T, Meta, BV, K>>>
  readIntoFullBVH(const std::vector<std::string> a_files) noexcept;

DCEL mesh SDF with compact BVH

To read one or multiple STL files and turn it into signed distance representations using a compact BVH representation, use

  /*!
    @brief Read a file containing a single watertight object and return it as a DCEL mesh enclosed in a linearized BVH
    @param[in] a_filename File name
  */
  template <typename T,
            typename Meta = DCEL::DefaultMetaData,
            typename BV   = EBGeometry::BoundingVolumes::AABBT<T>,
            size_t K      = 4>
  inline static std::shared_ptr<FastCompactMeshSDF<T, Meta, BV, K>>
  readIntoLinearBVH(const std::string a_filename) noexcept;

  /*!
    @brief Read multiple files containing single watertight objects and return them as DCEL meshes enclosed in linearized BVHs.
    @param[in] a_files File names
  */
  template <typename T,
            typename Meta = DCEL::DefaultMetaData,
            typename BV   = EBGeometry::BoundingVolumes::AABBT<T>,
            size_t K      = 4>
  inline static std::vector<std::shared_ptr<FastCompactMeshSDF<T, Meta, BV, K>>>
  readIntoLinearBVH(const std::vector<std::string> a_files) noexcept;

From soups to DCEL

EBGeometry also supports the creation of DCEL grids from polygon soups, which can then later be turned into an SDF representation. A triangle soup is represented as

std::vector<Vec3T<T>> vertices;
std::vector<std::vector<size_t>> faces;

Here, vertices contains the \(x,y,z\) coordinates of each vertex, while each entry faces contains a list of vertices for the face.

To turn this into a DCEL mesh, one should compress the triangle soup (get rid of duplicate vertices) and then construct the DCEL mesh:

  /*!
    @brief Compress triangle soup (removes duplicate vertices)
    @param[out] a_vertices   Vertices
    @param[out] a_facets     STL facets
  */
  template <typename T>
  inline static void
  compress(std::vector<EBGeometry::Vec3T<T>>& a_vertices, std::vector<std::vector<size_t>>& a_facets) noexcept;

  /*!
    @brief Turn raw vertices into DCEL vertices. 
    @param[out] a_mesh Output DCEL mesh.
    @param[in]  a_verticesRaw  Raw vertices
    @param[in]  a_facets       Facets
  */
  template <typename T, typename Meta>
  inline static void
  soupToDCEL(EBGeometry::DCEL::MeshT<T, Meta>&        a_mesh,
             const std::vector<EBGeometry::Vec3T<T>>& a_vertices,
             const std::vector<std::vector<size_t>>&  a_facets) noexcept;

The compress function will discard duplicate vertices from the soup, while the soupToDCEL will tie the remaining polygons into a DCEL mesh. This function will also compute the vertex and edge normal vectors.

Warning

soupToDCEL will issue plenty of warnings if the polygon soup is not watertight and orientable.

Using third-party sources

By design, EBGeometry does not include much functionality for parsing files into polygon soups. There are many open source third-party codes for achieving this (and we have tested several of them):

happly or miniply for Stanford PLY files.
stl_reader for STL files.
tinyobjloader for OBJ files.

In almost every case, the above codes can be read into polygon soups, and one can then turn the soup into a DCEL mesh as described in From soups to DCEL.