פונקציות מספריות

atan2

ארק טנגנס של Y/X בטווח ‎-π‎ עד π.

atan2 הוא הארק־טנגנס בעל שני הארגומנטים — ההופכי של הטנגנס השומר על מספיק מידע על הקלטים שלו כדי להחזיר את הרביע הנכון. בשונה מ־atan חד־ארגומנטי, המכווץ את שני הסימנים של Y ו־X ליחס אחד ואינו יכול להבחין בין חצי המישור העליון לתחתון, atan2 מסתכל על שני הארגומנטים ומחזיר זווית המכסה את המעגל המלא: ‎(-π, π]‎ רדיאנים. זוהי הדרך הקנונית ב־Perl להמיר קואורדינטות קרטזיות (X, Y) לזווית הקוטבית θ.

תקציר

atan2 Y, X

מה מוחזר

מספר בנקודה צפה, הזווית ברדיאנים בין ציר ה־x החיובי לנקודה (X, Y), נמדדת נגד כיוון השעון. טווח: -π < result ≤ π. הסימן עוקב אחר Y: Y חיובי מניב זווית חיובית (חצי המישור העליון), Y שלילי מניב זווית שלילית (חצי המישור התחתון). להמרה למעלות יש להכפיל ב־180 / π:

my $deg = atan2($y, $x) * 180 / 3.14159265358979;

דוגמאות

חישוב π בדיוק המכונה. הזווית מהראשית ל־(0, 1) היא בדיוק π/2, ולכן atan2(1, 0) * 2 מניב π:

my $pi = atan2(1, 0) * 2;
printf "%.15f\n", $pi;          # 3.141592653589793

טיפול ברביעים. ארבעת הכיוונים העיקריים נופלים על כפולות מדויקות של π/2, כאשר (−1, 0) נמצא בגבול +π, לא -π:

print atan2( 1,  0), "\n";      #  1.5707963267949   (+π/2, up)
print atan2( 0,  1), "\n";      #  0                 (right)
print atan2(-1,  0), "\n";      # -1.5707963267949   (-π/2, down)
print atan2( 0, -1), "\n";      #  3.14159265358979  (+π, left)

המרה קוטבית. בהינתן נקודה (X, Y), יש לשחזר רדיוס וזווית:

my ($x, $y) = (3, 4);
my $r     = sqrt($x*$x + $y*$y);    # 5
my $theta = atan2($y, $x);          # 0.927295218001612 rad ≈ 53.13°

טנגנס באמצעות הזהות הסטנדרטית. ל־Perl אין tan מובנה, אך sin ו־cos מספקים אותו ישירות — ו־atan2 הופך את התוצאה ללא דו־משמעות:

sub tan { sin($_[0]) / cos($_[0]) }
my $angle = 0.7;
print atan2(tan($angle), 1), "\n";  # 0.7  (recovers the input)

סריקת מעגל מלא. איטרציה של Y סביב מעגל היחידה מראה שהטווח מכסה ‎(-π, π]‎:

for my $deg (0, 45, 90, 135, 180, -135, -90, -45) {
    my $rad = $deg * 3.14159265358979 / 180;
    printf "%4d°  ->  %+.4f rad\n",
        $deg, atan2(sin($rad), cos($rad));
}

מקרי קצה

• שני הארגומנטים אפס: atan2(0, 0) אינו מוגדר מתמטית. הערך ש־Perl מחזיר הוא מה שה־atan2(3) של C בפלטפורמה מחזיר עבור מקרה זה — ב־glibc וב־musl זהו 0, ו־POSIX מאפשר כל ערך ב־[-π, π]. אין להסתמך על תוצאה ספציפית; יש לבדוק ($x == 0 && $y == 0) לפני הקריאה אם אפס הוא אפשרות אמיתית בקלטים.

• אפסים עם סימן: בפלטפורמות IEEE-754 atan2(+0, -0) מחזיר +π ו־atan2(-0, -0) מחזיר -π. זה משנה רק בקוד שעוקב במכוון אחר סימני אפס; רוב קוד ה־Perl לעולם אינו מבחין ביניהם.

• אינסופים: atan2(Inf, Inf) == π/4, atan2(Inf, -Inf) == 3π/4, atan2(-Inf, Inf) == -π/4, atan2(-Inf, -Inf) == -3π/4. הכיוון ”לעבר (±Inf, ±Inf)“ עדיין מהווה זווית מוגדרת היטב החוצה את הרביע המתאים.

• קלטי NaN: אם Y או X הם NaN, התוצאה היא NaN. מתפשט דרך כל אריתמטיקה נוספת — יש להגן באמצעות בדיקת Scalar::Util::looks_like_number על קלטים ממקורות לא־אמינים.

• ארגומנטים לא־מספריים: מחרוזות מומרות למספרים לפי כללי Perl הרגילים. atan2("3", "4") עובד; atan2("abc", 1) שווה־ערך ל־atan2(0, 1) ופולט אזהרת Argument "abc" isn't numeric תחת use warnings.

• סדר הארגומנטים הוא Y, X, לא X, Y: זה תואם את atan2(3) של C, את ATAN2 של FORTRAN, ואת הארק־טנגנס בעל שני הארגומנטים בכל שפה אחרת. היפוך הארגומנטים מניב את הזווית המשלימה — באג עדין שבדיקות ברביע אחד בלבד יחמיצו.

• atan2 אינו atan: אין צורה חד־ארגומנטית. atan2($ratio) הוא שגיאת תחביר באתר הקריאה. עבור הארק־טנגנס החד־ארגומנטי, יש להשתמש ב־Math::Trig::atan או POSIX::atan, או לכתוב אותו כ־atan2($ratio, 1).

הבדלים מן ה-upstream

תואם מלא ל־Perl 5.42 upstream.

ראו גם

• sin — סינוס; משתלב עם cos לשחזור הקואורדינטות של זווית לאחר ש־atan2 חילץ אותה

• cos — קוסינוס; הרכיב X בעת המרת רדיוס וזווית בחזרה לקואורדינטות קרטזיות

• sqrt — שורש ריבועי; בשימוש עם atan2 בהמרה הקרטזית → הקוטבית ($r, $theta) = (sqrt($x**2+$y**2), atan2($y,$x))

• Math::Trig_ext — מספק את tan, atan, asin, acos ואת המשפחה ההיפרבולית; גם מייצא את pi כקבוע כך שלא צריך לכתוב atan2(1,0)*2