Debian Codegraph @

include/deal.II/base/function_signed_distance.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2023 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 #ifndef dealii_function_signed_distance_h
16 #define dealii_function_signed_distance_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/bounding_box.h>
21 #include <deal.II/base/function.h>
22
23 #include <array>
24
25 DEAL_II_NAMESPACE_OPEN
26
27 namespace Functions
28 {
29 namespace SignedDistance
30 {
31 /**
32 * Signed-distance level set function of a sphere:
33 * $\psi(x) = \| x - x^c \| - R$.
34 * Here, $x^c$ is the center of the sphere and $R$ is its radius. This
35 * function is thus zero on the sphere, negative "inside" the ball having
36 * the sphere as its boundary, and positive in the rest of
37 * $\mathbb{R}^{dim}$.
38 *
39 * This function has gradient and Hessian equal to
40 * $\partial_i \psi(x) = (x - x^c)/\| x - x^c \|$,
41 * $\partial_i \partial_j \psi =
42 * \delta_{ij}/\| x - x^c \| - (x_i - x_i^c)(x_j - x_j^c)/\| x - x^c \|^3$,
43 * where $\delta_{ij}$ is the Kronecker delta function.
44 *
45 * @ingroup functions
46 */
47 template <int dim>
48 class Sphere : public Function<dim>
49 {
50 public:
51 /**
52 * Constructor, takes the center and radius of the sphere.
53 */
54 Sphere(const Point<dim> &center = Point<dim>(), const double radius = 1);
55
56 double
57 value(const Point<dim> &point,
58 const unsigned int component = 0) const override;
59
60 /**
61 * @copydoc Function::gradient()
62 *
63 * @note The gradient is singular at the center of the sphere. If the
64 * incoming @p point is too close to the center, a floating-point
65 * exception may be thrown or entries in the gradient may be +inf/-inf
66 * or +nan/-nan, depending on how the point is located relative to the
67 * singularity.
68 */
69 Tensor<1, dim>
70 gradient(const Point<dim> &point,
71 const unsigned int component = 0) const override;
72
73 /**
74 * @copydoc Function::hessian()
75 *
76 * @note The Hessian is singular at the center of the sphere. If the
77 * incoming @p point is too close to the center, a floating-point
78 * exception may be thrown or entries in the Hessian may be +inf/-inf
79 * or +nan/-nan, depending on how the point is located relative to the
80 * singularity.
81 */
82 SymmetricTensor<2, dim>
83 hessian(const Point<dim> &point,
84 const unsigned int component = 0) const override;
85
86 private:
87 const Point<dim> center;
88 const double radius;
89 };
90
91
92 /**
93 * Signed level set function of a plane in $\mathbb{R}^{dim}$:
94 * $\psi(x) = n \cdot (x - x_p)$.
95 * Here, $n$ is the plane normal and $x_p$ is a point in the plane.
96 * Thus, with respect to the direction of the normal, this function is
97 * positive above the plane, zero in the plane, and negative below the
98 * plane. If the normal is normalized, $\psi$ will be the signed distance to
99 * the closest point in the plane.
100 *
101 * @ingroup functions
102 */
103 template <int dim>
104 class Plane : public Function<dim>
105 {
106 public:
107 /**
108 * Constructor, takes a point in the plane and the plane normal.
109 */
110 Plane(const Point<dim> &point, const Tensor<1, dim> &normal);
111
112 double
113 value(const Point<dim> &point,
114 const unsigned int component = 0) const override;
115
116 Tensor<1, dim>
117 gradient(const Point<dim> &,
118 const unsigned int component = 0) const override;
119
120 SymmetricTensor<2, dim>
121 hessian(const Point<dim> &,
122 const unsigned int component = 0) const override;
123
124 private:
125 const Point<dim> point_in_plane;
126 const Tensor<1, dim> normal;
127 };
128
129
130 /**
131 * Signed-distance level set function to an ellipsoid defined by:
132 *
133 * @f[
134 * \sum_{i=1}^{dim} \frac{(x_i - c_i)^2}{R_i^2} = 1
135 * @f]
136 *
137 * Here, $c_i$ are the coordinates of the center of the ellipsoid and $R_i$
138 * are the elliptic radii. This function is zero on the ellipsoid, negative
139 * inside the ellipsoid and positive outside the ellipsoid.
140 *
141 * @ingroup functions
142 */
143 template <int dim>
144 class Ellipsoid : public Function<dim>
145 {
146 public:
147 /**
148 * Constructor, takes the center and radii of the ellipsoid.
149 *
150 * @param center Center of the ellipsoid.
151 * @param radii Array of radii of the ellipsoid.
152 * @param tolerance Tolerance of the distance computation.
153 * @param max_iter Max. number of iteration of the distance computation algorithm.
154 */
155 Ellipsoid(const Point<dim> &center,
156 const std::array<double, dim> &radii,
157 const double tolerance = 1e-14,
158 const unsigned int max_iter = 10);
159
160 double
161 value(const Point<dim> &point,
162 const unsigned int component = 0) const override;
163
164 /**
165 * Calculates the gradient of the signed distance function via the normal
166 * of the closest point on the ellipsoid.
167 */
168 Tensor<1, dim>
169 gradient(const Point<dim> &,
170 const unsigned int component = 0) const override;
171
172 private:
173 /**
174 * Evaluates the ellipsoid function:
175 *
176 * @f[
177 * f(\vec{x}) = \sum_{i=1}^{dim} \frac{(x_i - c_i)^2}{R_i^2} - 1
178 * @f]
179 */
180 double
181 evaluate_ellipsoid(const Point<dim> &point) const;
182
183 /**
184 * Computes the closest point on the given ellipse for an arbitrary point.
185 */
186 Point<dim>
187 compute_closest_point_ellipse(const Point<dim> &point) const;
188
189 /**
190 * Computes the analytical normal vector of a origin centred ellipse at a
191 * given @p point according to:
192 *
193 * / \ / b x a y \
194 * | n_x , n_y | = | ----- , ----- |
195 * \ / \ a b /
196 *
197 *
198 * @param point [x, y]
199 * @return [n_x , n_y]
200 */
201 Tensor<1, dim, double>
202 compute_analyical_normal_vector_on_ellipse(const Point<dim> &point) const;
203
204 /**
205 * Compute the signed distance to a 2d ellipsoid i.e. ellipse.
206 */
207 double
208 compute_signed_distance_ellipse(const Point<dim> &point) const;
209
210 const Point<dim> center;
211 const std::array<double, dim> radii;
212 const double tolerance;
213 const unsigned int max_iter;
214 };
215
216
217 /**
218 * Signed-distance level set function of a rectangle.
219 *
220 * This function is zero on the rectangle, negative "inside" and positive
221 * in the rest of $\mathbb{R}^{dim}$.
222 *
223 * Contour surfaces of the signed distance function of a 3D rectangle are
224 * illustrated below:
225 *
226 * @image html signed_distance_hyper_rectangle.png
227 *
228 * @ingroup functions
229 */
230 template <int dim>
231 class Rectangle : public Function<dim>
232 {
233 public:
234 /**
235 * Constructor, takes the bottom left point and the top right
236 * point of the rectangle.
237 *
238 * @param bottom_left Bottom left point of the rectangle.
239 * @param top_right Top right point of the rectangle.
240 */
241 Rectangle(const Point<dim> &bottom_left, const Point<dim> &top_right);
242 /**
243 * Constructor, takes a bounding box.
244 *
245 * @param bounding_box Bounding box.
246 */
247 Rectangle(const BoundingBox<dim> bounding_box);
248
249 /**
250 * Calculates the signed distance from a given point @p p to the rectangle.
251 * The signed distance is negative for points inside the rectangle, zero
252 * for points on the rectangle and positive for points outside the
253 * rectangle.
254 */
255 double
256 value(const Point<dim> &p,
257 const unsigned int component = 0) const override;
258
259 private:
260 const BoundingBox<dim> bounding_box;
261 };
262
263
264 /**
265 * Signed-distance level set function of Zalesak's disk proposed in
266 * @cite zalesak1979fully.
267 *
268 * It is calculated by the set difference $\psi(x) = \max(\psi_{S}(x),
269 * -\psi_{N}(x))$ of the level set functions of a sphere $\psi_{S}$ and a
270 * rectangle $\psi_{N}$. This function is zero on the surface of the disk,
271 * negative "inside" and positive in the rest of $\mathbb{R}^{dim}$.
272 *
273 * Contour surfaces of the signed distance function of a 3D Zalesak's disk
274 * are illustrated below:
275 *
276 * @image html https://www.dealii.org/images/grids/signed_distance_zalesak_disk.png
277 *
278 * @ingroup functions
279 */
280 template <int dim>
281 class ZalesakDisk : public Function<dim>
282 {
283 public:
284 /**
285 * Constructor, takes the radius and center of the disk together
286 * with the width and the height of the notch.
287 *
288 * @param radius Radius of the disk.
289 * @param center Center of the disk.
290 * @param notch_width Width of the notch of the disk.
291 * @param notch_height Height of the notch of the disk.
292 */
293 ZalesakDisk(const Point<dim> &center,
294 const double radius,
295 const double notch_width,
296 const double notch_height);
297
298 /**
299 * Calculates the signed distance from a given point @p p to the disk.
300 * The signed distance is negative for points inside the disk, zero
301 * for points on the disk and positive for points outside the
302 * disk.
303 */
304 double
305 value(const Point<dim> &p,
306 const unsigned int component = 0) const override;
307
308 private:
309 /**
310 * Disk described by a sphere.
311 */
312 const Functions::SignedDistance::Sphere<dim> sphere;
313
314 /**
315 * Notch described by a rectangle.
316 */
317 const Functions::SignedDistance::Rectangle<dim> notch;
318 };
319 } // namespace SignedDistance
320 } // namespace Functions
321
322 DEAL_II_NAMESPACE_CLOSE
323
324 #endif