Debian Codegraph @

include/deal.II/opencascade/utilities.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2014 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_occ_utilities_h
17 #define dealii_occ_utilities_h
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_OPENCASCADE
22
23 # include <deal.II/base/point.h>
24
25 # include <deal.II/fe/mapping_q1.h>
26
27 # include <deal.II/grid/tria.h>
28
29 # include <string>
30
31 // opencascade needs "HAVE_CONFIG_H" to be exported...
32 # define HAVE_CONFIG_H
33 # include <IFSelect_ReturnStatus.hxx>
34 # include <TopoDS_CompSolid.hxx>
35 # include <TopoDS_Compound.hxx>
36 # include <TopoDS_Edge.hxx>
37 # include <TopoDS_Face.hxx>
38 # include <TopoDS_Shape.hxx>
39 # include <TopoDS_Shell.hxx>
40 # include <TopoDS_Solid.hxx>
41 # include <TopoDS_Vertex.hxx>
42 # include <TopoDS_Wire.hxx>
43 # include <gp_Pnt.hxx>
44 # undef HAVE_CONFIG_H
45
46
47
48 DEAL_II_NAMESPACE_OPEN
49
50 /**
51 * We collect in this namespace all utilities which operate on OpenCASCADE
52 * entities. OpenCASCADE splits every object into a topological description
53 * and a geometrical entity. The basic topological description is a
54 * TopoDS_Shape. TopoDS_Shapes are light objects, and can be copied around.
55 * The closest deal.II analog is a TriaIterator.
56 *
57 * The OpenCASCADE topology is designed with reference to the STEP standard
58 * ISO-10303-42. The structure is an oriented one-way graph, where parents
59 * refer to their children, and there are no back references. Abstract
60 * structure is implemented as C++ classes from the TopoDS package. A
61 * TopoDS_Shape is manipulated by value and contains 3 fields: location,
62 * orientation and a myTShape handle (of the TopoDS_TShape type). According to
63 * OpenCASCADE documentation, myTShape and Location are used to share data
64 * between various shapes to save memory. For example, an edge belonging to
65 * two faces has equal Locations and myTShape fields but different
66 * Orientations (Forward in context of one face and Reversed in one of the
67 * other).
68 *
69 * Valid shapes include collection of other shapes, solids, faces, edges,
70 * vertices, etc.
71 *
72 * Once a topological description is available, if a concrete geometrical
73 * object can be created, the BRep classes allow one to extract the actual
74 * geometrical information from a shape.
75 *
76 * This is done by inheriting abstract topology classes from the TopoDS
77 * package by those implementing a boundary representation model (from the
78 * BRep package). Only 3 types of topological objects have geometric
79 * representations - vertex, edge, and face.
80 *
81 * Every TopoDS_Shape can be queried to figure out what type of shape it is,
82 * and actual geometrical objects, like surfaces, curves or points, can be
83 * extracted using BRepTools.
84 *
85 * In this namespace we provide readers and writers that read standard CAD
86 * files, and return a TopoDS_Shape, or that write a CAD file, given a
87 * TopoDS_Shape. Most of the functions in the OpenCASCADE namespace deal with
88 * TopoDS_Shapes of one type or another, and provide interfaces to common
89 * deal.II objects, like Triangulation, Manifold, and so on.
90 *
91 * Notice that most of these tools are only useful when spacedim is equal to
92 * three, since OpenCASCADE only operates in three-dimensional mode. In some
93 * cases they can be used in two dimensions as well, and the third dimension
94 * will be set to zero.
95 *
96 * If you wish to use these tools when the dimension of the space is two, then
97 * make sure your CAD files are actually flat and that all z coordinates are
98 * equal to zero, as otherwise you will get many exceptions.
99 */
100 namespace OpenCASCADE
101 {
102 /**
103 * Count the subobjects of a shape. This function is useful to gather
104 * information about the TopoDS_Shape passed as argument. It returns the
105 * number of faces, edges and vertices (the only topological entities
106 * associated with actual geometries) which are contained in the given
107 * shape.
108 */
109 std::tuple<unsigned int, unsigned int, unsigned int>
110 count_elements(const TopoDS_Shape &shape);
111
112 /**
113 * Read IGES files and translate their content into openCascade topological
114 * entities. The option scale_factor is used to compensate for different
115 * units being used in the IGES files and in the target application. The
116 * standard unit for IGES files is millimeters. The return object is a
117 * TopoDS_Shape which contains all objects from the file.
118 */
119 TopoDS_Shape
120 read_IGES(const std::string &filename, const double scale_factor = 1e-3);
121
122 /**
123 * Write the given topological shape into an IGES file.
124 */
125 void
126 write_IGES(const TopoDS_Shape &shape, const std::string &filename);
127
128
129 /**
130 * Read STL files and translate their content into openCascade topological
131 * entities. The return object is a
132 * TopoDS_Shape which contains all objects from the file.
133 */
134 TopoDS_Shape
135 read_STL(const std::string &filename);
136
137 /**
138 * Write the given topological shape into an STL file. In order to do so the
139 * shape must contain a mesh structure, the function checks if all the faces
140 * of the shape have an attached mesh, if this is not the case it proceeds to
141 * mesh it automatically. We remark that the automatic mesh generation in
142 * OpenCASCADE takes care only of the geometrical resemblance between the
143 * shape and the mesh, to control the shape and regularity of the triangles
144 * you should use other meshing software. The two arguments `deflection` and
145 * `angular_deflection` select the accuracy of the created triangulation with
146 * respect to the original topological shape. The argument
147 * `sew_different_faces` gives the possibility to use a Sewer from OpenCASCADE
148 * to create a watertight closed STL using the argument `sewer_tolerance`. The
149 * argument `is_relative` specifies if distance are relative and `in_parallel`
150 * if the execution should be in parallel.
151 */
152 void
153 write_STL(const TopoDS_Shape &shape,
154 const std::string &filename,
155 const double deflection,
156 const bool sew_different_faces = false,
157 const double sewer_tolerance = 1e-6,
158 const bool is_relative = false,
159 const double angular_deflection = 0.5,
160 const bool in_parallel = false);
161
162
163 /**
164 * Read STEP files and translate their content into openCascade topological
165 * entities. The option scale_factor is used to compensate for different
166 * units being used in the STEP files and in the target application. The
167 * standard unit for STEP files is millimeters. The return object is a
168 * TopoDS_Shape which contains all objects from the file.
169 */
170 TopoDS_Shape
171 read_STEP(const std::string &filename, const double scale_factor = 1e-3);
172
173
174 /**
175 * Write the given topological shape into an STEP file.
176 */
177 void
178 write_STEP(const TopoDS_Shape &shape, const std::string &filename);
179
180 /**
181 * This function returns the tolerance associated with the shape. Each CAD
182 * geometrical object is defined along with a tolerance, which indicates
183 * possible inaccuracy of its placement. For instance, the tolerance of a
184 * vertex indicates that it can be located in any point contained in a
185 * sphere centered in the nominal position and having radius tol. While
186 * carrying out an operation such as projecting a point onto a surface
187 * (which will in turn have its tolerance) we must keep in mind that the
188 * precision of the projection will be limited by the tolerance with which
189 * the surface is built. The tolerance is computed taking the maximum
190 * tolerance among the subshapes composing the shape.
191 */
192 double
193 get_shape_tolerance(const TopoDS_Shape &shape);
194
195 /**
196 * Perform the intersection of the given topological shape with the plane
197 * $c_x x + c_y y + c_z z +c = 0$. The returned topological shape will
198 * contain as few bsplines as possible. An exception is thrown if the
199 * intersection produces an empty shape.
200 */
201 TopoDS_Shape
202 intersect_plane(const TopoDS_Shape &in_shape,
203 const double c_x,
204 const double c_y,
205 const double c_z,
206 const double c,
207 const double tolerance = 1e-7);
208
209 /**
210 * Try to join all edges contained in the given TopoDS_Shape into a single
211 * TopoDS_Edge, containing as few BSPlines as possible. If the input shape
212 * contains faces, they will be ignored by this function. If the contained
213 * edges cannot be joined into a single one, i.e., they form disconnected
214 * curves, an exception will be thrown.
215 */
216 TopoDS_Edge
217 join_edges(const TopoDS_Shape &in_shape, const double tolerance = 1e-7);
218
219 /**
220 * Creates a smooth BSpline curve passing through the points in the assigned
221 * vector, and store it in the returned TopoDS_Shape (which is of type
222 * TopoDS_Edge). The points are reordered internally according to their
223 * scalar product with the direction, if direction is different from zero,
224 * otherwise they are used as passed. Notice that this function changes the
225 * input points if required by the algorithm.
226 *
227 * This class is used to interpolate a BsplineCurve passing through an array
228 * of points, with a C2 Continuity. If the optional parameter @p closed is
229 * set to true, then the curve will be C2 at all points except the first
230 * (where only C1 continuity will be given), and it will be a closed curve.
231 *
232 * The curve is guaranteed to be at distance @p tolerance from the input
233 * points. If the algorithm fails in generating such a curve, an exception
234 * is thrown.
235 */
236 template <int dim>
237 TopoDS_Edge
238 interpolation_curve(std::vector<Point<dim>> &curve_points,
239 const Tensor<1, dim> &direction = Tensor<1, dim>(),
240 const bool closed = false,
241 const double tolerance = 1e-7);
242
243 /**
244 * Extract all subshapes from a TopoDS_Shape, and store the results into
245 * standard containers. If the shape does not contain a certain type of
246 * shape, the respective container will be empty.
247 */
248 void
249 extract_geometrical_shapes(const TopoDS_Shape &shape,
250 std::vector<TopoDS_Face> &faces,
251 std::vector<TopoDS_Edge> &edges,
252 std::vector<TopoDS_Vertex> &vertices);
253
254 /**
255 * Create a triangulation from a single face. This class extracts the first u
256 * and v parameter of the parametric surface making up this face, and creates
257 * a Triangulation<2,spacedim> containing a single coarse cell reflecting
258 * this face. If the surface is not a trimmed surface, the vertices of this
259 * cell will coincide with the TopoDS_Vertex vertices of the original
260 * TopoDS_Face. This, however, is often not the case, and the user should be
261 * careful on how this mesh is used.
262 *
263 * If you call this function with a Triangulation<2,2>, make sure that the
264 * input face has all z coordinates set to zero, or you'll get an exception.
265 */
266 template <int spacedim>
267 void
268 create_triangulation(const TopoDS_Face &face,
269 Triangulation<2, spacedim> &tria);
270
271
272 /**
273 * Given a Triangulation and an optional Mapping, create a vector of smooth
274 * curves that interpolate the connected parts of the boundary vertices of
275 * the Triangulation and return them as a vector of TopoDS_Edge objects.
276 *
277 * This function constructs closed Bspline curve objects passing through all
278 * vertices of the boundary of the triangulation, with $C^2$ Continuity on
279 * each vertex except the first, where only $C^1$ continuity is guaranteed.
280 *
281 * The returned curves are ordered with respect to the indices of the faces
282 * that make up the triangulation boundary, i.e., the first curve is the one
283 * extracted starting from the face with the lowest index, and so on.
284 *
285 * @param[in] triangulation Input triangulation
286 * @param[in] mapping Optional input mapping
287 * @return An std::vector of TopoDS_Edge objects representing the smooth
288 * interpolation of the boundary of the `triangulation`
289 */
290 template <int spacedim>
291 std::vector<TopoDS_Edge>
292 create_curves_from_triangulation_boundary(
293 const Triangulation<2, spacedim> &triangulation,
294 const Mapping<2, spacedim> &mapping =
295 StaticMappingQ1<2, spacedim>::mapping);
296
297 /**
298 * Extract all compound shapes from a TopoDS_Shape, and store the results
299 * into standard containers. If the shape does not contain a certain type of
300 * compound, the respective container will be empty.
301 */
302 void
303 extract_compound_shapes(const TopoDS_Shape &shape,
304 std::vector<TopoDS_Compound> &compounds,
305 std::vector<TopoDS_CompSolid> &compsolids,
306 std::vector<TopoDS_Solid> &solids,
307 std::vector<TopoDS_Shell> &shells,
308 std::vector<TopoDS_Wire> &wires);
309
310 /**
311 * Project the point @p origin on the topological shape given by @p
312 * in_shape, and returns the projected point, the subshape which contains
313 * the point and the parametric u and v coordinates of the point within the
314 * resulting shape. If the shape is not elementary, all its subshapes are
315 * iterated, faces first, then edges, and the returned shape is the closest
316 * one to the point @p origin. If the returned shape is an edge, then only
317 * the u coordinate is filled with sensible information, and the v
318 * coordinate is set to zero.
319 *
320 * This function returns a tuple containing the projected point, the shape,
321 * the u coordinate and the v coordinate (which is different from zero only
322 * if the resulting shape is a face).
323 */
324 template <int dim>
325 std::tuple<Point<dim>, TopoDS_Shape, double, double>
326 project_point_and_pull_back(const TopoDS_Shape &in_shape,
327 const Point<dim> &origin,
328 const double tolerance = 1e-7);
329
330 /**
331 * Return the projection of the point @p origin on the topological shape
332 * given by @p in_shape. If the shape is not elementary, all its subshapes
333 * are iterated, faces first, then edges, and the returned point is the
334 * closest one to the @p in_shape, regardless of its type.
335 */
336 template <int dim>
337 Point<dim>
338 closest_point(const TopoDS_Shape &in_shape,
339 const Point<dim> &origin,
340 const double tolerance = 1e-7);
341
342 /**
343 * Given an elementary shape @p in_shape and the reference coordinates
344 * within the shape, returns the corresponding point in real space. If the
345 * shape is a TopoDS_Edge, the @p v coordinate is ignored. Only edges or
346 * faces, as returned by the function project_point_and_pull_back(), can be
347 * used as input to this function. If this is not the case, an Exception is
348 * thrown.
349 */
350 template <int dim>
351 Point<dim>
352 push_forward(const TopoDS_Shape &in_shape, const double u, const double v);
353
354
355 /**
356 * Given a TopoDS_Face @p face and the reference coordinates within this
357 * face, returns the corresponding point in real space, the normal to the
358 * surface at that point and the min and max curvatures as a tuple.
359 */
360 std::tuple<Point<3>, Tensor<1, 3>, double, double>
361 push_forward_and_differential_forms(const TopoDS_Face &face,
362 const double u,
363 const double v,
364 const double tolerance = 1e-7);
365
366
367 /**
368 * Get the closest point to the given topological shape, together with the
369 * normal and the min and max curvatures at that point. If the shape is not
370 * elementary, all its sub-faces (only the faces) are iterated, faces first,
371 * and only the closest point is returned. This function will throw an
372 * exception if the @p in_shape does not contain at least one face.
373 */
374 std::tuple<Point<3>, Tensor<1, 3>, double, double>
375 closest_point_and_differential_forms(const TopoDS_Shape &in_shape,
376 const Point<3> &origin,
377 const double tolerance = 1e-7);
378
379
380 /**
381 * Intersect a line passing through the given @p origin point along @p
382 * direction and the given topological shape. If there is more than one
383 * intersection, it will return the closest one.
384 *
385 * The optional @p tolerance parameter is used to compute distances.
386 */
387 template <int dim>
388 Point<dim>
389 line_intersection(const TopoDS_Shape &in_shape,
390 const Point<dim> &origin,
391 const Tensor<1, dim> &direction,
392 const double tolerance = 1e-7);
393
394
395 /**
396 * Convert OpenCASCADE point into a Point<spacedim>.
397 *
398 * The tolerance argument is used to check if the non used components of the
399 * OpenCASCADE point are close to zero. If this is not the case, an assertion
400 * is thrown in debug mode.
401 */
402 template <int spacedim>
403 Point<spacedim>
404 point(const gp_Pnt &p, const double tolerance = 1e-10);
405
406
407 /**
408 * Convert Point<3> into OpenCASCADE point.
409 */
410 template <int spacedim>
411 gp_Pnt
412 point(const Point<spacedim> &p);
413
414
415 /**
416 * Sort two points according to their scalar product with direction. If the
417 * norm of the direction is zero, then use lexicographical ordering. The
418 * optional parameter is used as a relative tolerance when comparing
419 * objects.
420 */
421 template <int dim>
422 bool
423 point_compare(const Point<dim> &p1,
424 const Point<dim> &p2,
425 const Tensor<1, dim> &direction = Tensor<1, dim>(),
426 const double tolerance = 1e-10);
427
428
429 /**
430 * Exception thrown when the point specified as argument does not lie
431 * between @p tolerance from the given TopoDS_Shape.
432 */
433 template <int dim>
434 DeclException1(ExcPointNotOnManifold,
435 Point<dim>,
436 << "The point [ " << arg1 << " ] is not on the manifold.");
437
438 /**
439 * Exception thrown when the point specified as argument cannot be projected
440 * to the manifold.
441 */
442 template <int dim>
443 DeclException1(ExcProjectionFailed,
444 Point<dim>,
445 << "Projection of point [ " << arg1 << " ] failed.");
446
447 /**
448 * Thrown when internal OpenCASCADE utilities fail to return the OK status.
449 */
450 DeclException1(ExcOCCError,
451 IFSelect_ReturnStatus,
452 << "An OpenCASCADE routine failed with return status "
453 << arg1);
454
455 /**
456 * Trying to make curve operations on a degenerate edge.
457 */
458 DeclException0(ExcEdgeIsDegenerate);
459
460 /**
461 * Trying to make operations on the wrong type of shapes.
462 */
463 DeclException0(ExcUnsupportedShape);
464 } // namespace OpenCASCADE
465
466
467 DEAL_II_NAMESPACE_CLOSE
468
469 #else
470
471 // Make sure the scripts that create the C++20 module input files have
472 // something to latch on if the preprocessor #ifdef above would
473 // otherwise lead to an empty content of the file.
474 DEAL_II_NAMESPACE_OPEN
475 DEAL_II_NAMESPACE_CLOSE
476
477 #endif // DEAL_II_WITH_OPENCASCADE
478
479 #endif