Python 中的 atan2() 函式

Python 的 math.atan2() 函式會根據點的座標計算方向角。給定 y 和 x，它會回傳點 (x, y) 相對於正 x 軸的角度。函式會同時考慮兩個座標，因此能判斷該點所在的象限；它計算的並非單純的比值 y / x 的反正切。

math.atan2() 的計算內容

可以把 (x, y) 想成直角座標平面上的一個點。math.atan2(y, x) 會回傳正 x 軸與從原點連到該點的直線之間的角度。呼叫時的參數順序很重要：先傳入垂直座標 y，再傳入水平座標 x。如果順序顛倒，代表的就是另一個點，通常也會得到不同的角度。

與 math.atan(y / x) 不同，math.atan2(y, x) 會利用兩個座標的正負號，辨別四個象限中的方向。這也省去自行計算比值的步驟，避免在 x 為零時發生問題。

語法與參數

匯入 Python 的 math 模組後，以 math.atan2(y, x) 呼叫函式。兩個引數都必須是實數純量，例如整數或浮點數。函式不接受以座標清單代替任一個單獨的數值。若要處理多個點，請針對每個點分別傳入純量 y 和 x 值呼叫函式。

回傳值與角度範圍

函式會回傳以弧度表示的 float 角度。結果介於 [-π, π]，且包含兩個端點：負角度表示方向位於正 x 軸下方，正角度則表示方向位於其上方。例如，位於負 x 軸上的點，其角度會落在這個範圍的一端。若使用角度制較方便，可呼叫 math.degrees()；等價的作法是將弧度乘以 180 / math.pi。

Python 官方 math 模組文件說明了此函式及其數值行為。

範例

下方每個 tuple 都先存放 x，再存放 y。迴圈會依照這個順序拆解數值，接著依函式的參數順序先傳入 y、再傳入 x。格式化為小數點後三位，方便比較四個象限中的弧度值。最後一次呼叫使用相同的座標組合，並將回傳的弧度值轉換成角度制顯示。執行以下範例：

本節中的程式碼以及顯示的標籤或輸出仍為英文。

import math

points = [(1, 1), (-1, 1), (-1, -1), (1, -1)]
for x, y in points:
    angle = math.atan2(y, x)
    print(f"Point ({x}, {y}): {angle:.3f} radians")

angle = math.atan2(1, 1)
print(f"In degrees: {math.degrees(angle):.1f}")

Point (1, 1): 0.785 radians
Point (-1, 1): 2.356 radians
Point (-1, -1): -2.356 radians
Point (1, -1): -0.785 radians
In degrees: 45.0

這段程式會逐一處理座標組合，但每次呼叫都傳入兩個個別數值。x 和 y 的正負號決定回傳角度代表的方向。單位轉換只改變顯示方式，不會改變方向。

常見的型別錯誤

直接傳入座標清單會造成 TypeError，因為 math.atan2() 的每個引數都必須是實數，而不是集合。先為清單取索引，就能取得純量值，如下方範例所示。try 區塊會讓程式顯示例外類別名稱 TypeError，並接著執行修正後的呼叫。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

import math

coordinates_y = [2, 4]
coordinates_x = [1, -4]

try:
    math.atan2(coordinates_y, coordinates_x)
except TypeError as error:
    print(type(error).__name__)

angle = math.atan2(coordinates_y[0], coordinates_x[0])
print(f"Corrected angle: {angle:.3f} radians")

TypeError
Corrected angle: 1.107 radians