茂之钳
579 lines
20 KiB
C++
579 lines
20 KiB
C++
#pragma once
|
||
/**
|
||
* @file sdf_primitives.h
|
||
* @brief 有符号距离函数（SDF）基础图元
|
||
*
|
||
* 提供常见几何体到三维空间中各点的有符号距离计算。
|
||
* 所有图元定义在 vde::sdf 命名空间下，使用 vde::core::Point3D 作为输入。
|
||
*
|
||
* ## SDF 约定
|
||
*
|
||
* - f(p) < 0: 点 p 在几何体**内部**
|
||
* - f(p) = 0: 点 p 在几何体**表面**上
|
||
* - f(p) > 0: 点 p 在几何体**外部**
|
||
* - |f(p)| 的绝对值近似为 p 到最近表面的欧几里得距离
|
||
*
|
||
* ## 数值特性
|
||
*
|
||
* - 所有内联函数标记为 `[[nodiscard]]`，强制调用方使用返回值
|
||
* - 距离函数在表面附近满足 |∇f| ≈ 1（Lipschitz 连续，步进可靠）
|
||
* - 部分复杂图元（cone, triangular_prism, link, infinite_cone）为非内联实现，定义在 src/sdf/ 中
|
||
*
|
||
* @note 所有图元假设未施加变换——坐标系原点即图元中心/基点。
|
||
* 需要平移/旋转/缩放时，使用 sdf_operations.h 中的域变形算子对采样点预先变换。
|
||
*
|
||
* @ingroup sdf
|
||
*/
|
||
#include "vde/core/point.h"
|
||
#include <cmath>
|
||
#include <algorithm>
|
||
|
||
namespace vde::sdf {
|
||
using core::Point3D;
|
||
using core::Vector3D;
|
||
|
||
// ═══════════════════════════════════════════════
|
||
// Basic Primitives
|
||
// ═══════════════════════════════════════════════
|
||
|
||
/**
|
||
* @brief 球体的 SDF
|
||
*
|
||
* 计算三维空间中一点到球面的有符号距离。
|
||
*
|
||
* **数学公式:** f(p) = |p| - r
|
||
*
|
||
* ```
|
||
* f < 0: 点在球内
|
||
* f = 0: 点在球面上
|
||
* f > 0: 点在球外
|
||
* ```
|
||
*
|
||
* |∇f| = 1 在球外和球面上严格成立，球内在原点处退化（梯度为零）。
|
||
*
|
||
* @param p 采样点（三维坐标）
|
||
* @param radius 球半径，必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @note 球位于原点。如需其他位置，使用 op_translate 对采样点做反向平移。
|
||
*
|
||
* @code{.cpp}
|
||
* double d = sphere(Point3D(1.0, 0.0, 0.0), 0.5); // d = 0.5 (外部)
|
||
* double inside = sphere(Point3D(0.0, 0.0, 0.0), 1.0); // d = -1.0 (球心)
|
||
* @endcode
|
||
*
|
||
* @see ellipsoid 各轴半径不同的椭球
|
||
* @see cylinder 沿 Y 轴的圆柱
|
||
*/
|
||
[[nodiscard]] inline double sphere(const Point3D& p, double radius) {
|
||
return p.norm() - radius;
|
||
}
|
||
|
||
/**
|
||
* @brief 轴对齐立方体的 SDF
|
||
*
|
||
* 计算点到以原点为中心的轴对齐长方体表面的有符号距离。
|
||
*
|
||
* **算法概要:**
|
||
* 1. 将点的各分量取绝对值，得到第一卦限对称映射
|
||
* 2. 减去半边长得到相对于面的距离 qᵢ = |pᵢ| - halfExtentᵢ
|
||
* 3. 外部距离 = ||max(q,0)||，内部惩罚 = min(max(qₓ,q_y,q_z), 0)
|
||
*
|
||
* 结果在面外为真实欧氏距离，边/角区域使用 L2 距离组合保证连续性。
|
||
*
|
||
* @param p 采样点
|
||
* @param half_extents 半边长 (hx, hy, hz)，均必须 ≥ 0
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 2×3×4 的盒子
|
||
* double d = box(Point3D(0.0, 0.0, 0.0), Point3D(1.0, 1.5, 2.0));
|
||
* @endcode
|
||
*
|
||
* @see round_box 带圆角的盒子
|
||
* @see wedge 对角切割的半盒子
|
||
*/
|
||
[[nodiscard]] inline double box(const Point3D& p, const Point3D& half_extents) {
|
||
Point3D q = p.cwiseAbs() - half_extents;
|
||
return q.cwiseMax(0.0).norm()
|
||
+ std::min(std::max({q.x(), q.y(), q.z()}), 0.0);
|
||
}
|
||
|
||
/**
|
||
* @brief 圆角立方体的 SDF
|
||
*
|
||
* 与 box() 使用相同的核心算法，但在最后减去圆角半径 r。
|
||
* 相当于先对 box SDF 做膨胀（offset），再缩回，等价于对边角做半径为 r 的倒圆处理。
|
||
*
|
||
* **数学公式:** f(p) = box(p, half_extents) - r
|
||
*
|
||
* @param p 采样点
|
||
* @param half_extents 半边长 (hx, hy, hz)
|
||
* @param r 圆角半径，必须 < min(half_extents) 否则整体形态改变
|
||
* @return 有符号距离
|
||
*
|
||
* @warning 当 r 超过某轴半边长时，该维度的边会被完全圆化，表面不再平坦。
|
||
* 实际应用中限制 r ≤ 0.5 * min(hx, hy, hz) 可保证形态可控。
|
||
*
|
||
* @code{.cpp}
|
||
* // 带 0.2 圆角的 2×2×2 立方体
|
||
* double d = round_box(p, Point3D(1, 1, 1), 0.2);
|
||
* @endcode
|
||
*
|
||
* @see box 无圆角的长方体
|
||
* @see op_round 对任意 SDF 做圆角偏移
|
||
*/
|
||
[[nodiscard]] inline double round_box(const Point3D& p, const Point3D& half_extents, double r) {
|
||
Point3D q = p.cwiseAbs() - half_extents;
|
||
return q.cwiseMax(0.0).norm()
|
||
+ std::min(std::max({q.x(), q.y(), q.z()}), 0.0)
|
||
- r;
|
||
}
|
||
|
||
/**
|
||
* @brief 圆环面的 SDF
|
||
*
|
||
* 圆环位于 XZ 平面内，绕 Y 轴对称。
|
||
*
|
||
* **数学公式:**
|
||
* 1. 计算环向半径: q = √(pₓ² + p𝓏²) - R_major
|
||
* 2. 管向距离: f = √(q² + p_y²) - R_minor
|
||
*
|
||
* R_major = 环心到管心的距离（主半径）
|
||
* R_minor = 管的截面半径（副半径）
|
||
*
|
||
* @param p 采样点
|
||
* @param major_radius 主半径（环的半径），必须 > 0
|
||
* @param minor_radius 副半径（管的粗细），必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @warning 当 major_radius ≤ minor_radius 时，环孔消失形成苹果状（self-intersecting torus）。
|
||
*
|
||
* @code{.cpp}
|
||
* // 主半径 2.0、管半径 0.5 的圆环
|
||
* double d = torus(Point3D(2.0, 0.0, 0.0), 2.0, 0.5); // d ≈ 0.0（表面上）
|
||
* @endcode
|
||
*
|
||
* @see link 双环连接体（两个并行圆环的组合）
|
||
*/
|
||
[[nodiscard]] inline double torus(const Point3D& p, double major_radius, double minor_radius) {
|
||
double qx = std::sqrt(p.x() * p.x() + p.z() * p.z()) - major_radius;
|
||
return std::sqrt(qx * qx + p.y() * p.y()) - minor_radius;
|
||
}
|
||
|
||
/**
|
||
* @brief 胶囊体的 SDF
|
||
*
|
||
* 以线段 ab 为骨架、半径为 radius 的扫掠球体。
|
||
* 等价于线段上最近的点到 p 的距离减去 radius。
|
||
*
|
||
* **算法概要:**
|
||
* 1. 将 p 投影到线段 ab 上，投影参数 h = clamp(pa·ba / ba·ba, 0, 1)
|
||
* 2. 计算 p 到投影点的距离减去 radius
|
||
*
|
||
* 退化情况: 当 |ba| ≈ 0（a ≈ b），退化为以 a 为球心的球体。
|
||
*
|
||
* @param p 采样点
|
||
* @param a 线段起点
|
||
* @param b 线段终点
|
||
* @param radius 扫掠球半径，必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 从 (0,-2,0) 到 (0,2,0) 的胶囊、半径 0.5
|
||
* double d = capsule(p, Point3D(0,-2,0), Point3D(0,2,0), 0.5);
|
||
* @endcode
|
||
*
|
||
* @see cylinder 两端平头的圆柱（非球形端盖）
|
||
*/
|
||
[[nodiscard]] inline double capsule(const Point3D& p, const Point3D& a, const Point3D& b, double radius) {
|
||
Point3D pa = p - a;
|
||
Point3D ba = b - a;
|
||
double ba_sq = ba.squaredNorm();
|
||
if (ba_sq < 1e-30) {
|
||
// Degenerate to sphere
|
||
return pa.norm() - radius;
|
||
}
|
||
double h = std::clamp(pa.dot(ba) / ba_sq, 0.0, 1.0);
|
||
return (pa - ba * h).norm() - radius;
|
||
}
|
||
|
||
/**
|
||
* @brief 带平端盖的圆柱体 SDF
|
||
*
|
||
* 沿 Y 轴、以原点为中心的有限长圆柱体。两端为平切面（非球形端盖）。
|
||
*
|
||
* **算法概要:**
|
||
* 1. 水平距离: d_xz = √(pₓ² + p𝓏²) - radius
|
||
* 2. 垂直距离: d_y = |p_y| - height/2
|
||
* 3. 用二维 min/max L2 组合计算矩形区域到圆角的 SDF
|
||
*
|
||
* 结果在柱面上为真实距离，在端盖边缘有连续过渡。
|
||
*
|
||
* @param p 采样点
|
||
* @param radius 圆柱截面半径，必须 > 0
|
||
* @param height 圆柱总高度（从 -h/2 到 +h/2），必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 半径 1.0、高度 3.0 的圆柱
|
||
* double d = cylinder(Point3D(1.0, 0.0, 0.0), 1.0, 3.0);
|
||
* @endcode
|
||
*
|
||
* @see capsule 两端球形端盖的圆柱
|
||
* @see infinite_cylinder 无限长圆柱
|
||
* @see cone 圆锥台
|
||
*/
|
||
[[nodiscard]] inline double cylinder(const Point3D& p, double radius, double height) {
|
||
double d_xz = std::sqrt(p.x() * p.x() + p.z() * p.z()) - radius;
|
||
double d_y = std::abs(p.y()) - height * 0.5;
|
||
return std::min(std::max(d_xz, d_y), 0.0)
|
||
+ std::sqrt(std::max(d_xz, 0.0) * std::max(d_xz, 0.0)
|
||
+ std::max(d_y, 0.0) * std::max(d_y, 0.0));
|
||
}
|
||
|
||
/**
|
||
* @brief 平面的 SDF
|
||
*
|
||
* 通过原点的平面，法向量为 normal，偏移量为 offset。
|
||
*
|
||
* **数学公式:** f(p) = p·n - offset
|
||
*
|
||
* 其中 n 为单位法向量。f > 0 表示点在法向量指向的一侧。
|
||
* 偏移量沿法向量正方向移动平面。
|
||
*
|
||
* @param p 采样点
|
||
* @param normal 单位法向量（必须已归一化）
|
||
* @param offset 沿法向量正方向的偏移量
|
||
* @return 有符号距离
|
||
*
|
||
* @pre normal.norm() ≈ 1.0（调用方负责归一化）
|
||
*
|
||
* @code{.cpp}
|
||
* // 通过原点、法向量朝上的平面
|
||
* double d = plane(p, Vector3D(0,1,0), 0.0);
|
||
* // 向上偏移 2 个单位的平面
|
||
* double d2 = plane(p, Vector3D(0,1,0), 2.0);
|
||
* @endcode
|
||
*
|
||
* @see wedge 两个平面+盒子的组合（对角切割）
|
||
*/
|
||
[[nodiscard]] inline double plane(const Point3D& p, const Vector3D& normal, double offset) {
|
||
return p.dot(normal) - offset;
|
||
}
|
||
|
||
/**
|
||
* @brief 椭球体的 SDF（有界梯度近似）
|
||
*
|
||
* 以原点为中心的椭球，半轴长为 radii = (rx, ry, rz)。
|
||
*
|
||
* **算法概要:**
|
||
*
|
||
* 使用 bound-normalized 近似方法：
|
||
* 1. 缩放坐标: pr = p / radii
|
||
* 2. k0 = |pr|，k1 = |p / radii²|
|
||
* 3. f = k0 * (k0 - 1) / k1
|
||
*
|
||
* 该方法保证在表面上 f = 0，但内部/远处的距离为近似值。
|
||
* 相比精确椭球距离，避开了六次方程的昂贵求根。
|
||
*
|
||
* @param p 采样点
|
||
* @param radii 半轴长 (rx, ry, rz)，均必须 > 0
|
||
* @return 有符号距离（近似）
|
||
*
|
||
* @note 当三个半径相等时退化为球体，此时使用 sphere() 更精确高效。
|
||
* @note 当点到原点距离远大于最大半径时，近似精度下降。
|
||
*
|
||
* @code{.cpp}
|
||
* // 扁椭球: rx=2, ry=1, rz=1
|
||
* double d = ellipsoid(Point3D(2.0, 0.0, 0.0), Point3D(2, 1, 1));
|
||
* @endcode
|
||
*
|
||
* @see sphere 精确球体（rx=ry=rz 时的特例）
|
||
*/
|
||
[[nodiscard]] inline double ellipsoid(const Point3D& p, const Point3D& radii) {
|
||
Point3D pr(p.x() / radii.x(), p.y() / radii.y(), p.z() / radii.z());
|
||
double k0 = pr.norm();
|
||
double k1 = Point3D(p.x() / (radii.x() * radii.x()),
|
||
p.y() / (radii.y() * radii.y()),
|
||
p.z() / (radii.z() * radii.z())).norm();
|
||
if (k1 < 1e-30) {
|
||
// Degenerate: point at origin → distance = -min(radii)
|
||
return -std::min({radii.x(), radii.y(), radii.z()});
|
||
}
|
||
return k0 * (k0 - 1.0) / k1;
|
||
}
|
||
|
||
// ═══════════════════════════════════════════════
|
||
// Parametric Primitives
|
||
// ═══════════════════════════════════════════════
|
||
|
||
/**
|
||
* @brief 正六棱柱的 SDF
|
||
*
|
||
* 六边形位于 XZ 平面，尖顶沿 X 轴方向，沿 Y 轴挤出的正六棱柱。
|
||
*
|
||
* **算法概要:**
|
||
* 1. 将点对称映射到第一象限后，计算二维六边形的 SDF
|
||
* 2. 六边形 SDF 通过两组约束平面表示: max(px + 0.577*pz, 1.155*pz) - radius
|
||
* 3. 沿 Y 轴做 bounded extrusion
|
||
*
|
||
* @param p 采样点
|
||
* @param radius 六边形外接圆半径（中心到顶点），必须 > 0
|
||
* @param height 挤出总高度（±h/2 沿 Y 轴），必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 外接圆半径 1.0、高度 2.0 的六棱柱
|
||
* double d = hex_prism(Point3D(0.0, 0.0, 0.0), 1.0, 2.0);
|
||
* @endcode
|
||
*
|
||
* @see extrusion_bounded 通用 bounded extrusion 算子
|
||
*/
|
||
[[nodiscard]] inline double hex_prism(const Point3D& p, double radius, double height) {
|
||
double px = std::abs(p.x());
|
||
double pz = std::abs(p.z());
|
||
// 2D hexagon SDF (pointy-top in XZ plane)
|
||
double d_hex = std::max(px + pz * 0.577350269189626, pz * 1.154700538379252) - radius;
|
||
// Extrude along Y
|
||
return std::max(d_hex, std::abs(p.y()) - height * 0.5);
|
||
}
|
||
|
||
/**
|
||
* @brief 无限长圆柱的 SDF
|
||
*
|
||
* 沿任意方向的无限长圆柱（无端盖），轴线过原点。
|
||
*
|
||
* **数学公式:** f(p) = |p × axis| - radius
|
||
*
|
||
* 叉积给出点到轴线的垂直距离。
|
||
*
|
||
* @param p 采样点
|
||
* @param axis 圆柱轴线方向（必须归一化，|axis| = 1）
|
||
* @param radius 截面半径，必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @pre axis.norm() ≈ 1.0
|
||
*
|
||
* @code{.cpp}
|
||
* // 沿 Z 轴的无限圆柱
|
||
* double d = infinite_cylinder(p, Vector3D(0,0,1), 0.5);
|
||
* @endcode
|
||
*
|
||
* @see cylinder 有限长圆柱（带平端盖）
|
||
*/
|
||
[[nodiscard]] inline double infinite_cylinder(const Point3D& p, const Vector3D& axis, double radius) {
|
||
return p.cross(axis).norm() - radius;
|
||
}
|
||
|
||
/**
|
||
* @brief 楔形体的 SDF
|
||
*
|
||
* 立方体沿 XZ 平面对角线切割的一半。切割面为 z = x。
|
||
* 楔形体占据盒子内 z ≥ x 的区域。
|
||
*
|
||
* **几何形状:**
|
||
* - 盒子: [-w/2, w/2] × [-h/2, h/2] × [-d/2, d/2]
|
||
* - 保留区域: 盒子内 z ≥ x 的半空间
|
||
*
|
||
* @param p 采样点
|
||
* @param w 宽度（X 方向）
|
||
* @param h 高度（Y 方向）
|
||
* @param d 深度（Z 方向）
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 2×2×2 的楔形体（保留 z ≥ x 的一半）
|
||
* double d = wedge(Point3D(-0.5, 0.0, 0.5), 2.0, 2.0, 2.0);
|
||
* @endcode
|
||
*
|
||
* @see box 完整立方体
|
||
* @see plane 独立平面 SDF
|
||
*/
|
||
[[nodiscard]] inline double wedge(const Point3D& p, double w, double h, double d) {
|
||
Point3D q = p.cwiseAbs() - Point3D(w * 0.5, h * 0.5, d * 0.5);
|
||
double d_box = q.cwiseMax(0.0).norm()
|
||
+ std::min(std::max({q.x(), q.y(), q.z()}), 0.0);
|
||
// Diagonal plane x - z ≤ 0 (i.e., z ≥ x)
|
||
double d_cut = (p.x() - p.z()) * 0.707106781186548; // 1/√2
|
||
return std::max(d_box, d_cut);
|
||
}
|
||
|
||
// ═══════════════════════════════════════════════
|
||
// 2D Extrusions & Revolution
|
||
// ═══════════════════════════════════════════════
|
||
|
||
/**
|
||
* @brief 二维 SDF 沿 Z 轴的无限挤出
|
||
*
|
||
* 将二维 SDF 沿 Z 轴无限延伸。三维点的 SDF 值等于其 (x,y) 投影处的二维 SDF 值。
|
||
*
|
||
* **使用模式:** 先计算二维 SDF 值，再传入此函数:
|
||
*
|
||
* @code{.cpp}
|
||
* double sdf_2d = circle_sdf(p.x(), p.y()); // 用户自定义二维 SDF
|
||
* double sdf_3d = extrusion(p, sdf_2d);
|
||
* @endcode
|
||
*
|
||
* @param p 三维采样点（仅 x,y 分量被隐式使用——通过 sdf_2d 参数间接）
|
||
* @param sdf_2d 预计算的二维 SDF 值（在 (p.x, p.y) 处求值）
|
||
* @return 三维有符号距离（等于 sdf_2d）
|
||
*
|
||
* @note p 参数仅保持接口一致，实际不影响结果。
|
||
* @note 对于有限长度的挤出，使用 extrusion_bounded()。
|
||
*
|
||
* @see extrusion_bounded 有限长度的挤出
|
||
* @see revolution 二维轮廓绕 Y 轴旋转
|
||
*/
|
||
[[nodiscard]] inline double extrusion(const Point3D& /*p*/, double sdf_2d) {
|
||
return sdf_2d;
|
||
}
|
||
|
||
/**
|
||
* @brief 二维 SDF 的有限长度挤出
|
||
*
|
||
* 将二维 SDF 沿 Z 轴挤出并通过 |pz| ≤ half_height 做 bounded 限制。
|
||
* 相当于对二维 SDF 与 Z 轴平板做交集。
|
||
*
|
||
* @param p 三维采样点
|
||
* @param sdf_2d 预计算的二维 SDF 值（在 (p.x, p.y) 处求值）
|
||
* @param half_height 挤出半高度（Z 方向），必须 ≥ 0
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 圆形截面、总高 4.0 的短柱
|
||
* double d2d = std::sqrt(p.x()*p.x() + p.y()*p.y()) - 1.0;
|
||
* double d3d = extrusion_bounded(p, d2d, 2.0);
|
||
* @endcode
|
||
*
|
||
* @see extrusion 无限挤出
|
||
* @see hex_prism 六棱柱（特例化 bounded extrusion 实现）
|
||
*/
|
||
[[nodiscard]] inline double extrusion_bounded(const Point3D& p, double sdf_2d, double half_height) {
|
||
return std::max(sdf_2d, std::abs(p.z()) - half_height);
|
||
}
|
||
|
||
/**
|
||
* @brief 二维轮廓绕 Y 轴的旋转体 SDF
|
||
*
|
||
* 将二维 SDF 绕 Y 轴旋转，生成旋转体的三维 SDF。
|
||
*
|
||
* **使用模式:**
|
||
* 二维 SDF 定义在 (r, y) 坐标中，其中 r 为水平距离 = √(pₓ² + p𝓏²) - offset。
|
||
* 用户需要在调用前将 (r, y) 转换为二维采样并计算 SDF 值。
|
||
*
|
||
* @param p 三维采样点（接口保留，不直接使用）
|
||
* @param sdf_2d 预计算的二维 SDF（在 (√(pₓ²+p𝓏²)-offset, p.y) 处求值）
|
||
* @param offset 径向偏移量（从 Y 轴的起点距离）
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 在距 Y 轴 2.0 处、截面半径 0.5 的圆环
|
||
* double r = std::sqrt(p.x()*p.x() + p.z()*p.z()) - 2.0;
|
||
* double sdf_2d = std::sqrt(r*r + p.y()*p.y()) - 0.5;
|
||
* double d3d = revolution(p, sdf_2d, 2.0);
|
||
* @endcode
|
||
*
|
||
* @see torus 圆环（revolution 的特例：截面为圆）
|
||
*/
|
||
[[nodiscard]] inline double revolution(const Point3D& /*p*/, double sdf_2d, double /*offset*/) {
|
||
return sdf_2d;
|
||
}
|
||
|
||
// ═══════════════════════════════════════════════
|
||
// Complex Primitives (implemented in src/sdf/)
|
||
// ═══════════════════════════════════════════════
|
||
|
||
/**
|
||
* @brief 圆锥台的 SDF（非内联实现）
|
||
*
|
||
* 沿 Y 轴、以原点为中心的有限长圆锥台。
|
||
* 顶点在 y = +height/2（半径 0），底面在 y = -height/2（半径 height·tan(angle_rad)）。
|
||
*
|
||
* **算法概要:**
|
||
* 将三维问题分解为二维 (r, y) 平面内点到三角形区域的距离计算，
|
||
* 其中 r = √(pₓ² + p𝓏²)，三角形由底边和高决定。
|
||
*
|
||
* @param p 采样点
|
||
* @param angle_rad 半锥角（弧度），决定底面半径
|
||
* @param height 锥体总高度，必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @warning 当 angle_rad 接近 π/2 时底面半径极大，可能导致数值不稳定。
|
||
*
|
||
* @see cylinder 半锥角为 0 时的退化情况
|
||
* @see infinite_cone 无限圆锥
|
||
*/
|
||
[[nodiscard]] double cone(const Point3D& p, double angle_rad, double height);
|
||
|
||
/**
|
||
* @brief 三角棱柱的 SDF（非内联实现）
|
||
*
|
||
* 以 XY 平面中任意三角形为截面、沿 Z 轴 ±height/2 挤出的棱柱。
|
||
*
|
||
* @param p 采样点
|
||
* @param a 三角形顶点 A（XY 平面内）
|
||
* @param b 三角形顶点 B（XY 平面内）
|
||
* @param c 三角形顶点 C（XY 平面内）
|
||
* @param height 挤出总高度（沿 Z 轴），必须 > 0
|
||
* @return 有符号距离
|
||
*
|
||
* @pre a, b, c 三点不共线（构成有效三角形）
|
||
*
|
||
* @code{.cpp}
|
||
* // 顶点为 (0,0), (2,0), (0,2)、高度 1.0 的三棱柱
|
||
* double d = triangular_prism(p, Point3D(0,0,0), Point3D(2,0,0), Point3D(0,2,0), 1.0);
|
||
* @endcode
|
||
*
|
||
* @see wedge 直角三角形楔形体
|
||
*/
|
||
[[nodiscard]] double triangular_prism(const Point3D& p, const Point3D& a, const Point3D& b,
|
||
const Point3D& c, double height);
|
||
|
||
/**
|
||
* @brief 双环链接体的 SDF（非内联实现）
|
||
*
|
||
* 两个并列的圆环面沿 X 轴排列，等效于经典链环结构。
|
||
* 常用于链条、连杆等机械连接件的快速建模。
|
||
*
|
||
* @param p 采样点
|
||
* @param length 两个环心沿 X 轴的距离
|
||
* @param major_r 每个环的主半径（环的半径）
|
||
* @param minor_r 每个环的管半径（截面的粗细）
|
||
* @return 有符号距离
|
||
*
|
||
* @code{.cpp}
|
||
* // 环间距 2.0、主半径 1.0、管半径 0.2 的双环
|
||
* double d = link(Point3D(1.0, 0.0, 0.0), 2.0, 1.0, 0.2);
|
||
* @endcode
|
||
*
|
||
* @see torus 单个圆环
|
||
*/
|
||
[[nodiscard]] double link(const Point3D& p, double length, double major_r, double minor_r);
|
||
|
||
/**
|
||
* @brief 无限圆锥的 SDF（非内联实现）
|
||
*
|
||
* 从顶点出发沿轴方向无限延伸的圆锥，半锥角为 angle_rad。
|
||
* 与 cone() 不同，本函数无高度限制，锥体向轴的正方向无限扩展。
|
||
*
|
||
* @param p 采样点
|
||
* @param apex 锥顶位置
|
||
* @param axis 锥轴方向（必须归一化），锥体沿此方向扩展
|
||
* @param angle_rad 半锥角（弧度）
|
||
* @return 有符号距离
|
||
*
|
||
* @pre axis.norm() ≈ 1.0
|
||
*
|
||
* @code{.cpp}
|
||
* // 顶点在原点、沿 Y 轴、半锥角 30° 的无限锥
|
||
* double d = infinite_cone(p, Point3D(0,0,0), Vector3D(0,1,0), M_PI/6);
|
||
* @endcode
|
||
*
|
||
* @see cone 有限高圆锥台
|
||
*/
|
||
[[nodiscard]] double infinite_cone(const Point3D& p, const Point3D& apex,
|
||
const Vector3D& axis, double angle_rad);
|
||
|
||
} // namespace vde::sdf
|