// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2014 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_occ_utilities_h #define dealii_occ_utilities_h #include #ifdef DEAL_II_WITH_OPENCASCADE # include # include # include # include // opencascade needs "HAVE_CONFIG_H" to be exported... # define HAVE_CONFIG_H # include # include # include # include # include # include # include # include # include # include # include # undef HAVE_CONFIG_H DEAL_II_NAMESPACE_OPEN /** * We collect in this namespace all utilities which operate on OpenCASCADE * entities. OpenCASCADE splits every object into a topological description * and a geometrical entity. The basic topological description is a * TopoDS_Shape. TopoDS_Shapes are light objects, and can be copied around. * The closest deal.II analog is a TriaIterator. * * The OpenCASCADE topology is designed with reference to the STEP standard * ISO-10303-42. The structure is an oriented one-way graph, where parents * refer to their children, and there are no back references. Abstract * structure is implemented as C++ classes from the TopoDS package. A * TopoDS_Shape is manipulated by value and contains 3 fields: location, * orientation and a myTShape handle (of the TopoDS_TShape type). According to * OpenCASCADE documentation, myTShape and Location are used to share data * between various shapes to save memory. For example, an edge belonging to * two faces has equal Locations and myTShape fields but different * Orientations (Forward in context of one face and Reversed in one of the * other). * * Valid shapes include collection of other shapes, solids, faces, edges, * vertices, etc. * * Once a topological description is available, if a concrete geometrical * object can be created, the BRep classes allow one to extract the actual * geometrical information from a shape. * * This is done by inheriting abstract topology classes from the TopoDS * package by those implementing a boundary representation model (from the * BRep package). Only 3 types of topological objects have geometric * representations - vertex, edge, and face. * * Every TopoDS_Shape can be queried to figure out what type of shape it is, * and actual geometrical objects, like surfaces, curves or points, can be * extracted using BRepTools. * * In this namespace we provide readers and writers that read standard CAD * files, and return a TopoDS_Shape, or that write a CAD file, given a * TopoDS_Shape. Most of the functions in the OpenCASCADE namespace deal with * TopoDS_Shapes of one type or another, and provide interfaces to common * deal.II objects, like Triangulation, Manifold, and so on. * * Notice that most of these tools are only useful when spacedim is equal to * three, since OpenCASCADE only operates in three-dimensional mode. In some * cases they can be used in two dimensions as well, and the third dimension * will be set to zero. * * If you wish to use these tools when the dimension of the space is two, then * make sure your CAD files are actually flat and that all z coordinates are * equal to zero, as otherwise you will get many exceptions. */ namespace OpenCASCADE { /** * Count the subobjects of a shape. This function is useful to gather * information about the TopoDS_Shape passed as argument. It returns the * number of faces, edges and vertices (the only topological entities * associated with actual geometries) which are contained in the given * shape. */ std::tuple count_elements(const TopoDS_Shape &shape); /** * Read IGES files and translate their content into openCascade topological * entities. The option scale_factor is used to compensate for different * units being used in the IGES files and in the target application. The * standard unit for IGES files is millimeters. The return object is a * TopoDS_Shape which contains all objects from the file. */ TopoDS_Shape read_IGES(const std::string &filename, const double scale_factor = 1e-3); /** * Write the given topological shape into an IGES file. */ void write_IGES(const TopoDS_Shape &shape, const std::string &filename); /** * Read STL files and translate their content into openCascade topological * entities. The return object is a * TopoDS_Shape which contains all objects from the file. */ TopoDS_Shape read_STL(const std::string &filename); /** * Write the given topological shape into an STL file. In order to do so the * shape must contain a mesh structure, the function checks if all the faces * of the shape have an attached mesh, if this is not the case it proceeds to * mesh it automatically. We remark that the automatic mesh generation in * OpenCASCADE takes care only of the geometrical resemblance between the * shape and the mesh, to control the shape and regularity of the triangles * you should use other meshing software. The two arguments `deflection` and * `angular_deflection` select the accuracy of the created triangulation with * respect to the original topological shape. The argument * `sew_different_faces` gives the possibility to use a Sewer from OpenCASCADE * to create a watertight closed STL using the argument `sewer_tolerance`. The * argument `is_relative` specifies if distance are relative and `in_parallel` * if the execution should be in parallel. */ void write_STL(const TopoDS_Shape &shape, const std::string &filename, const double deflection, const bool sew_different_faces = false, const double sewer_tolerance = 1e-6, const bool is_relative = false, const double angular_deflection = 0.5, const bool in_parallel = false); /** * Read STEP files and translate their content into openCascade topological * entities. The option scale_factor is used to compensate for different * units being used in the STEP files and in the target application. The * standard unit for STEP files is millimeters. The return object is a * TopoDS_Shape which contains all objects from the file. */ TopoDS_Shape read_STEP(const std::string &filename, const double scale_factor = 1e-3); /** * Write the given topological shape into an STEP file. */ void write_STEP(const TopoDS_Shape &shape, const std::string &filename); /** * This function returns the tolerance associated with the shape. Each CAD * geometrical object is defined along with a tolerance, which indicates * possible inaccuracy of its placement. For instance, the tolerance of a * vertex indicates that it can be located in any point contained in a * sphere centered in the nominal position and having radius tol. While * carrying out an operation such as projecting a point onto a surface * (which will in turn have its tolerance) we must keep in mind that the * precision of the projection will be limited by the tolerance with which * the surface is built. The tolerance is computed taking the maximum * tolerance among the subshapes composing the shape. */ double get_shape_tolerance(const TopoDS_Shape &shape); /** * Perform the intersection of the given topological shape with the plane * $c_x x + c_y y + c_z z +c = 0$. The returned topological shape will * contain as few bsplines as possible. An exception is thrown if the * intersection produces an empty shape. */ TopoDS_Shape intersect_plane(const TopoDS_Shape &in_shape, const double c_x, const double c_y, const double c_z, const double c, const double tolerance = 1e-7); /** * Try to join all edges contained in the given TopoDS_Shape into a single * TopoDS_Edge, containing as few BSPlines as possible. If the input shape * contains faces, they will be ignored by this function. If the contained * edges cannot be joined into a single one, i.e., they form disconnected * curves, an exception will be thrown. */ TopoDS_Edge join_edges(const TopoDS_Shape &in_shape, const double tolerance = 1e-7); /** * Creates a smooth BSpline curve passing through the points in the assigned * vector, and store it in the returned TopoDS_Shape (which is of type * TopoDS_Edge). The points are reordered internally according to their * scalar product with the direction, if direction is different from zero, * otherwise they are used as passed. Notice that this function changes the * input points if required by the algorithm. * * This class is used to interpolate a BsplineCurve passing through an array * of points, with a C2 Continuity. If the optional parameter @p closed is * set to true, then the curve will be C2 at all points except the first * (where only C1 continuity will be given), and it will be a closed curve. * * The curve is guaranteed to be at distance @p tolerance from the input * points. If the algorithm fails in generating such a curve, an exception * is thrown. */ template TopoDS_Edge interpolation_curve(std::vector> &curve_points, const Tensor<1, dim> &direction = Tensor<1, dim>(), const bool closed = false, const double tolerance = 1e-7); /** * Extract all subshapes from a TopoDS_Shape, and store the results into * standard containers. If the shape does not contain a certain type of * shape, the respective container will be empty. */ void extract_geometrical_shapes(const TopoDS_Shape &shape, std::vector &faces, std::vector &edges, std::vector &vertices); /** * Create a triangulation from a single face. This class extracts the first u * and v parameter of the parametric surface making up this face, and creates * a Triangulation<2,spacedim> containing a single coarse cell reflecting * this face. If the surface is not a trimmed surface, the vertices of this * cell will coincide with the TopoDS_Vertex vertices of the original * TopoDS_Face. This, however, is often not the case, and the user should be * careful on how this mesh is used. * * If you call this function with a Triangulation<2,2>, make sure that the * input face has all z coordinates set to zero, or you'll get an exception. */ template void create_triangulation(const TopoDS_Face &face, Triangulation<2, spacedim> &tria); /** * Given a Triangulation and an optional Mapping, create a vector of smooth * curves that interpolate the connected parts of the boundary vertices of * the Triangulation and return them as a vector of TopoDS_Edge objects. * * This function constructs closed Bspline curve objects passing through all * vertices of the boundary of the triangulation, with $C^2$ Continuity on * each vertex except the first, where only $C^1$ continuity is guaranteed. * * The returned curves are ordered with respect to the indices of the faces * that make up the triangulation boundary, i.e., the first curve is the one * extracted starting from the face with the lowest index, and so on. * * @param[in] triangulation Input triangulation * @param[in] mapping Optional input mapping * @return An std::vector of TopoDS_Edge objects representing the smooth * interpolation of the boundary of the `triangulation` */ template std::vector create_curves_from_triangulation_boundary( const Triangulation<2, spacedim> &triangulation, const Mapping<2, spacedim> &mapping = StaticMappingQ1<2, spacedim>::mapping); /** * Extract all compound shapes from a TopoDS_Shape, and store the results * into standard containers. If the shape does not contain a certain type of * compound, the respective container will be empty. */ void extract_compound_shapes(const TopoDS_Shape &shape, std::vector &compounds, std::vector &compsolids, std::vector &solids, std::vector &shells, std::vector &wires); /** * Project the point @p origin on the topological shape given by @p * in_shape, and returns the projected point, the subshape which contains * the point and the parametric u and v coordinates of the point within the * resulting shape. If the shape is not elementary, all its subshapes are * iterated, faces first, then edges, and the returned shape is the closest * one to the point @p origin. If the returned shape is an edge, then only * the u coordinate is filled with sensible information, and the v * coordinate is set to zero. * * This function returns a tuple containing the projected point, the shape, * the u coordinate and the v coordinate (which is different from zero only * if the resulting shape is a face). */ template std::tuple, TopoDS_Shape, double, double> project_point_and_pull_back(const TopoDS_Shape &in_shape, const Point &origin, const double tolerance = 1e-7); /** * Return the projection of the point @p origin on the topological shape * given by @p in_shape. If the shape is not elementary, all its subshapes * are iterated, faces first, then edges, and the returned point is the * closest one to the @p in_shape, regardless of its type. */ template Point closest_point(const TopoDS_Shape &in_shape, const Point &origin, const double tolerance = 1e-7); /** * Given an elementary shape @p in_shape and the reference coordinates * within the shape, returns the corresponding point in real space. If the * shape is a TopoDS_Edge, the @p v coordinate is ignored. Only edges or * faces, as returned by the function project_point_and_pull_back(), can be * used as input to this function. If this is not the case, an Exception is * thrown. */ template Point push_forward(const TopoDS_Shape &in_shape, const double u, const double v); /** * Given a TopoDS_Face @p face and the reference coordinates within this * face, returns the corresponding point in real space, the normal to the * surface at that point and the min and max curvatures as a tuple. */ std::tuple, Tensor<1, 3>, double, double> push_forward_and_differential_forms(const TopoDS_Face &face, const double u, const double v, const double tolerance = 1e-7); /** * Get the closest point to the given topological shape, together with the * normal and the min and max curvatures at that point. If the shape is not * elementary, all its sub-faces (only the faces) are iterated, faces first, * and only the closest point is returned. This function will throw an * exception if the @p in_shape does not contain at least one face. */ std::tuple, Tensor<1, 3>, double, double> closest_point_and_differential_forms(const TopoDS_Shape &in_shape, const Point<3> &origin, const double tolerance = 1e-7); /** * Intersect a line passing through the given @p origin point along @p * direction and the given topological shape. If there is more than one * intersection, it will return the closest one. * * The optional @p tolerance parameter is used to compute distances. */ template Point line_intersection(const TopoDS_Shape &in_shape, const Point &origin, const Tensor<1, dim> &direction, const double tolerance = 1e-7); /** * Convert OpenCASCADE point into a Point. * * The tolerance argument is used to check if the non used components of the * OpenCASCADE point are close to zero. If this is not the case, an assertion * is thrown in debug mode. */ template Point point(const gp_Pnt &p, const double tolerance = 1e-10); /** * Convert Point<3> into OpenCASCADE point. */ template gp_Pnt point(const Point &p); /** * Sort two points according to their scalar product with direction. If the * norm of the direction is zero, then use lexicographical ordering. The * optional parameter is used as a relative tolerance when comparing * objects. */ template bool point_compare(const Point &p1, const Point &p2, const Tensor<1, dim> &direction = Tensor<1, dim>(), const double tolerance = 1e-10); /** * Exception thrown when the point specified as argument does not lie * between @p tolerance from the given TopoDS_Shape. */ template DeclException1(ExcPointNotOnManifold, Point, << "The point [ " << arg1 << " ] is not on the manifold."); /** * Exception thrown when the point specified as argument cannot be projected * to the manifold. */ template DeclException1(ExcProjectionFailed, Point, << "Projection of point [ " << arg1 << " ] failed."); /** * Thrown when internal OpenCASCADE utilities fail to return the OK status. */ DeclException1(ExcOCCError, IFSelect_ReturnStatus, << "An OpenCASCADE routine failed with return status " << arg1); /** * Trying to make curve operations on a degenerate edge. */ DeclException0(ExcEdgeIsDegenerate); /** * Trying to make operations on the wrong type of shapes. */ DeclException0(ExcUnsupportedShape); } // namespace OpenCASCADE DEAL_II_NAMESPACE_CLOSE #else // Make sure the scripts that create the C++20 module input files have // something to latch on if the preprocessor #ifdef above would // otherwise lead to an empty content of the file. DEAL_II_NAMESPACE_OPEN DEAL_II_NAMESPACE_CLOSE #endif // DEAL_II_WITH_OPENCASCADE #endif