align op• 資料種類:image2d × image2d → matrix
• 呼叫: import fullseye as fs; fs.ledger.frame_align(reference, frame, model='similarity', threshold_sigma=5.0, max_stars=60, tolerance_px=2.0, max_shift_px=None, ransac_iters=500, seed=0, min_inliers=3)(要直接呼叫實作,import astrostack; astrostack.frame_align(reference, frame, model='similarity', threshold_sigma=5.0, max_stars=60, tolerance_px=2.0, max_shift_px=None, ransac_iters=500, seed=0, min_inliers=3);從台帳取用則 opsastrostack.get("frame_align"))
• 經台帳呼叫的回傳值: fullseye.ledger.frame_align(...) 只回傳宣告的 out 型別 matrix 的值(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.frame_align.raw(...),或直接呼叫 astrostack.frame_align。
• 底層回傳: (matrix, info) -> matrix
由恆星對應估計 frame → reference 的 2-D 變換。
流程分 3 步，各步估計的主體都是既有 op：
1. 以 star_detect 取出兩幅影像中的星。
2. 以偏移投票求出粗略平移(_vote_translation)。
這裡不用 features.match_keypoints 是基於實測的判斷：
星場的 9x9 小塊彼此幾乎形狀相同，因此 Lowe 的比值檢定
(預設 ratio=0.8)幾乎會全部捨棄。128x128 中 40 顆星、真實偏移為
(+0.590, -0.540) px 的幀對上的實測：match_keypoints
回傳的對應為 4 個，其中距真值 1 px 以內的為 0 個(= 可用的
1 個也沒有)。同一對上投票法為 26 票 → 26 對應 → 26 內點，估計誤差
0.0155 px。星場不是「沒有特徵」，而是「特徵全都一樣」，因此
正確做法是用排列的幾何而非描述子。
3. 以粗略移動建立最近鄰對應，
以 mosaic.proj_match_points_ransac 剔除誤對應，
以 fit_transform.vector_to_similarity(依 model 而定為
vector_to_rigid / vector_to_hom_mat2d)擬合。
這裡既沒有寫 RANSAC 迴圈也沒有寫 Umeyama。
★不能用於重複結構(2026-09-08，由 poc_print_registration 發現)。inlier_ratio 是「贊成同一答案的對應所佔比例」，而不是「答案正確的機率」。在網點、織物、網格這類同一形狀週期性排列的影像中，偏移一個格向量的對應關係也會獲得全員贊成，因此贊成率維持 1.00，只有答案偏移了 1 個格週期(甚至好幾個)。
實測：256x256、相當於 133 lpi、15 度的網點，僅偏移 (0.00, +1.30) px 的影像對，回傳 inlier_ratio 1.00 / rms_px 0.78，而估計卻是 (+54.24, +30.12) px。星場(128x128、40 顆星、真值(+0.59, -0.54))上 inlier_ratio 同為 1.00，估計正確。僅憑贊成率無法區分這 2 者。
能區分它們的是 vote_margin —— 投票第 2 高峰的高度除以第 1 高峰的值，0 表示只有 1 個峰，越接近 1 越表示「還有同樣可信的其他答案」。同樣 2 個例子中 網點 0.857 / 星場 0.143。在可能傳入週期結構的路徑上，請看它而不是 inlier_ratio。
若只需要平移本身，看 piv_cross_correlate 的相關面較直接，那裡可以自己數出有幾個峰。
*model* "translation" 只用對應差的中位數(即使只有 1 顆星也能運作)。"rigid" = 旋轉 + 平移，"similarity" = + 等向縮放，"affine" = 6 自由度。只要視野不寬，"similarity" 就夠了 (赤道儀的追蹤誤差是旋轉與平移，大氣折射以一階形式進入縮放)。
Returns (matrix, info):
• matrix —— (3, 3) float64。從左乘 (row, col, 1) 得到 reference 的座標(與 fit_transform 相同的約定)。
• info —— dict。n_stars_ref / n_stars_src / n_pairs / n_inliers / inlier_ratio / shift_row / shift_col / rotation_deg / scale / rms_px(內點的殘差 RMS)/ model。
fail-closed：內點少於 *min_inliers* 時擲出 ValueError。不默默回傳恆等變換 —— 把對位失敗的幀當作「偏移 0」混入合成，會在既無例外也無警告的情況下產生雙像。
Raises ValueError：非 2-D / 形狀不同 / *model* 不在 ALIGN_MODELS 中 / 任一幅影像中 1 顆星也找不到 / 無法建立對應 / 內點不足時。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• astro_stacking — py -3.11 examples/astro_stacking.py
• poc_exoplanet_transit — py -3.11 examples/poc_exoplanet_transit.py
• poc_print_registration — py -3.11 examples/poc_print_registration.py
matrix 作為輸入)—
align)*Provenance: astrostack.py — ASTROSTACK 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.