最后同步日期：2026-04-15 | Godot 官方原文 — atanh

atanh

定义

反双曲正切函数（inverse hyperbolic tangent）。给定一个值 x，返回一个角度，使得 tanh(角度) = x。

用数学公式表示就是：atanh(x) = 0.5 * ln((1 + x) / (1 - x))。

继续用"双曲函数是三角函数的远房亲戚"这个比喻——普通的 tan 描述圆上的运动，而 tanh 描述的是和悬链线相关的运动。tanh 有一个有趣的特点：它的输出永远在 (-1, 1) 之间，就像一个被"压缩"过的函数。而 atanh 就是反过来——把一个被压缩到 (-1, 1) 之间的值，还原成原来的双曲角。

在游戏开发中，atanh 常用于：

• 需要把一个被归一化（压缩到 -1 到 1 之间）的值还原成原始范围
• 某些特殊的缓动曲线和插值计算
• 物理模拟中的速率映射

要求：输入值 x 必须严格在 -1 和 1 之间（即 -1 < x < 1），不能等于 -1 或 1。

函数签名

C#

// 方式一：使用 Godot 的 Mathf（推荐，返回 float）
public static float Atanh(float x)

// 方式二：使用 .NET 标准库（返回 double）
public static double Atanh(double x)

GDScript

func atanh(x: float) -> float

参数说明

参数	类型	必需	说明
x	float / double	是	要计算反双曲正切的值，必须 严格在 -1 和 1 之间（不含端点）

返回值

返回 x 的反双曲正切值，类型为 float（GDScript 和 Mathf）或 double（.NET Math）。

• 当 x == 0 时，返回 0.0
• 当 x 接近 1 时，返回值趋向正无穷大
• 当 x 接近 -1 时，返回值趋向负无穷大
• 函数关于原点对称：atanh(-x) = -atanh(x)

代码示例

C#

using Godot;
using System;

public partial class MathExample : Node
{
    public override void _Ready()
    {
        // 基本用法：计算反双曲正切
        float result1 = Mathf.Atanh(0.0f);     // 输出: 0
        float result2 = Mathf.Atanh(0.5f);     // 输出: 约 0.54931
        float result3 = Mathf.Atanh(-0.5f);    // 输出: 约 -0.54931
        float result4 = Mathf.Atanh(0.9f);     // 输出: 约 1.47222

        GD.Print("atanh(0) = ", result1);
        GD.Print("atanh(0.5) = ", result2);
        GD.Print("atanh(-0.5) = ", result3);
        GD.Print("atanh(0.9) = ", result4);

        // 也可以用 .NET 的 Math.Atanh（返回 double，精度更高）
        double precise = Math.Atanh(0.5);
        GD.Print("Math.Atanh(0.5) = ", precise);
    }
}

GDScript

extends Node

func _ready():
    # 基本用法：计算反双曲正切
    var result1 = atanh(0.0)     # 输出: 0
    var result2 = atanh(0.5)     # 输出: 约 0.54931
    var result3 = atanh(-0.5)    # 输出: 约 -0.54931
    var result4 = atanh(0.9)     # 输出: 约 1.47222

    print("atanh(0) = ", result1)
    print("atanh(0.5) = ", result2)
    print("atanh(-0.5) = ", result3)
    print("atanh(0.9) = ", result4)

注意事项

1. 输入范围严格限制：atanh(x) 只对 -1 < x < 1 有定义。如果传入 1 或 -1，结果为正/负无穷大；如果传入超出 [-1, 1] 范围的值，会返回 NaN。使用前建议先做范围检查。
2. 与普通反正切的区别：atan 是普通三角函数的反正切，接受任意实数输入，返回弧度角；atanh 是双曲函数的反函数，只接受 (-1, 1) 范围内的输入。
3. "爆炸"行为：当输入值接近 1 或 -1 时，输出值会急速增大（趋向无穷）。这在某些归一化还原场景中可能正是你想要的，但也可能导致数值不稳定，需要注意。
4. 精度选择：C# 中 Mathf.Atanh() 返回 float（单精度），Math.Atanh() 返回 double（双精度）。游戏开发中一般 float 就够用了。