Math::ClampAngle 追加

[sashi0034]

Discord 文脈: https://discord.com/channels/443310697397354506/999983621408567326/1305003589588226211

最小値と最大値の範囲にクランプした角度を返す Math::ClampAngle を実装しました。

検索エンジンで ClampAngle を検索したとき上位に出てくる以下の実装を参考にしています。 https://gist.github.com/johnsoncodehk/2ecb0136304d4badbb92bd0c1dbd8bae

以下の Main.cpp で動作を確認できます。

# include <Siv3D.hpp> // Siv3D v0.6.15

namespace
{
    void Test_ClampAngle(double angleDeg, double minDeg, double maxDeg)
    {
        const double angleRad = ToRadians(angleDeg);
        const double minRad = ToRadians(minDeg);
        const double maxRad = ToRadians(maxDeg);

        Print << U"ClampAngle({}_deg, {}_deg, {}_deg) = {:.4f} (= {:.4f}_deg)"_fmt(
            angleDeg, minDeg, maxDeg,
            Math::ClampAngle(angleRad, minRad, maxRad),
            ToDegrees(Math::ClampAngle(angleRad, minRad, maxRad)));
    }
}

void Main()
{
    Window::Resize(1280, 720);

    Print << U"360_deg - 15_deg = {:.04f}"_fmt(360_deg - 15_deg);
    Print << U"720_deg - 15_deg = {:.04f}"_fmt(720_deg - 15_deg);

    Print << U"-----------------------------------------------";

    Test_ClampAngle(10, -15, 15);
    Test_ClampAngle(20, -15, 15);

    Print << U"-----------------------------------------------";

    Test_ClampAngle(350, -15, 15);
    Test_ClampAngle(340, -15, 15);
    Test_ClampAngle(700, -15, 15);

    while (System::Update())
    {
    }
}

実行結果

[sashi0034]

失礼しました、先程の実装に誤りがあったので修正しました (上の動作確認用のコードは偶然 Clamp が成功していたようでした) 修正確認を兼ねて、GUI で動作を確認できる Main.cpp を作成しました。

# include <Siv3D.hpp> // Siv3D v0.6.15

void Main()
{
    double angleRad{};
    double minRad{};
    double maxRad{Math::HalfPi};

    while (System::Update())
    {
        constexpr double range = Math::TwoPi * 2;
        SimpleGUI::Headline(U"angleRad: {:.4f}"_fmt(angleRad), {20, 20});
        SimpleGUI::Slider(angleRad, -range, range, {200, 20}, 280);

        SimpleGUI::Headline(U"minRad: {:.4f}"_fmt(minRad), {20, 60});
        SimpleGUI::Slider(minRad, -range, range, {200, 60}, 280);

        SimpleGUI::Headline(U"maxRad: {:.4f}"_fmt(maxRad), {20, 100});
        SimpleGUI::Slider(maxRad, -range, range, {200, 100}, 280);

        const double clampedRad = Math::ClampAngle(angleRad, minRad, maxRad);
        SimpleGUI::Headline(U"ClampAngle(angleRad, minRad, maxRad) -> {:.4f}"_fmt(clampedRad), {20, 140});

        Circle(Scene::Center(), 100)
            .drawPie(minRad, maxRad - minRad, Palette::Gray)
            .drawFrame(1.0, Palette::White);

        Line{Scene::Center(), Circular{100, clampedRad}.toVec2() + Scene::Center()}.draw(5.0, Palette::Yellow);

        Line{Scene::Center(), Circular{100, angleRad}.toVec2() + Scene::Center()}.draw(2.0, Palette::Red);

        Line{Scene::Center(), Circular{100, minRad}.toVec2() + Scene::Center()}.draw(2.0, Palette::Green);

        Line{Scene::Center(), Circular{100, maxRad}.toVec2() + Scene::Center()}.draw(2.0, Palette::Blue);
    }
}

[Reputeless]

ありがとうございます。近日中に確認します。

[Reputeless]

追加の計算コストが発生しますが、

    double ClampAngle2(const double angle, const double min, double max) noexcept
    {
        const auto start = (min + max) * 0.5 - Pi;
        const auto floor = Floor((angle - start) / TwoPi) * TwoPi;
        return NormalizeAngle(Clamp(angle, min + floor, max + floor), (min + max) * 0.5);
    }

のように NormalizeAngle して、戻り値が必ず min 以上 max 以下になるようにするのはどうでしょう。戻り値に対する驚きが少なくなるような気がします。

一方で失われる情報もあるので、そうしたい場合はユーザが自前で NoarmalizeAngle() を書くのも選択肢です。

    Print << Math::ToDegrees(Math::ClampAngle(-3610_deg, -60_deg, 60_deg)); // -3610
    Print << Math::ToDegrees(Math::ClampAngle2(-3610_deg, -60_deg, 60_deg)); // -10

    Print << Math::ToDegrees(Math::ClampAngle(-350_deg, -60_deg, 60_deg)); // -350
    Print << Math::ToDegrees(Math::ClampAngle2(-350_deg, -60_deg, 60_deg)); // 10

    Print << Math::ToDegrees(Math::ClampAngle(10_deg, 340_deg, 380_deg)); // 10
    Print << Math::ToDegrees(Math::ClampAngle2(10_deg, 340_deg, 380_deg)); // 370

    Print << Math::ToDegrees(Math::ClampAngle(90_deg, 340_deg, 380_deg)); // 20
    Print << Math::ToDegrees(Math::ClampAngle2(90_deg, 340_deg, 380_deg)); // 380

↓ クランプ範囲が 2 π 以上のとき ClampAngle2 の結果が直感的でなくなるのは欠点です。

    Print << Math::ToDegrees(Math::ClampAngle(10_deg, 380_deg, 3580_deg)); // 10
    Print << Math::ToDegrees(Math::ClampAngle2(10_deg, 380_deg, 3580_deg)); // 1810

[Reputeless]

• 11/17 実装会で NormalizeAngle() は含めないことを決定。

[Reputeless]

Merged. Thank you!