stack op• 資料種類:images → image2d
• 呼叫: import fullseye as fs; fs.ledger.drizzle_resample(frames, shifts=None, scale=2.0, pixfrac=1.0)(要直接呼叫實作,import astrostack; astrostack.drizzle_resample(frames, shifts=None, scale=2.0, pixfrac=1.0);從台帳取用則 opsastrostack.get("drizzle_resample"))
• 經台帳呼叫的回傳值: fullseye.ledger.drizzle_resample(...) 只回傳宣告的 out 型別 image2d 的值(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.drizzle_resample.raw(...),或直接呼叫 astrostack.drizzle_resample。
• 底層回傳: (sci, wht) -> image2d
Drizzle —— 由若干次像素錯位的影格構建更細的網格(保面積)。
Fruchter & Hook, *Drizzle: A Method for the Linear Reconstruction of Undersampled Images*, PASP 114, 144 (2002)。把輸入像素視為縮小一圈的「液滴(drop，邊長 pixfrac)」，依其與輸出網格像素的重疊面積 按比例分配通量。由於不做內插，
• 總通量守恆。 只要液滴落在輸出網格內部，sci.sum() 就與各輸入幀總和的平均值嚴格一致(實測：shifts=0、scale=2、pixfrac=0.7 時相對誤差 0.0)。這就是把它做成僅憑回傳值即可驗算之形式的理由。
• pixfrac 越小，液滴落在單一輸出像素內部的比例越大，解析度提高，但會出現未被覆蓋的輸出像素(wht 在那裡變小)。這種拉鋸是 drizzle 唯一的調整點。
只有在取樣不足時才有效，這是實測的結論。48x48 中 10 顆星、抖動 1.5 px、16 幀的量測(數值為換算到輸入像素的 FWHM)::
真實 FWHM 單幀 直接平均 drizzle x2 (pixfrac=0.5)
1.0 1.773 2.249 1.312
1.3 1.929 2.876 1.572
1.8 2.262 2.648 3.086
2.5 4.057 4.295 3.586
只有在 FWHM 低於 2 像素(違反奈奎斯特)之處 drizzle 才勝出。抖動後的幀直接平均反而會使像變鈍(1.773 → 2.249) —— 因為偏移被平均掉了，而 drizzle 把同樣的偏移轉為解析度。在 1.8 px 以上已充分取樣，drizzle 得不到好處，只會損失液滴摺積的那一部分。
看兩顆星能否分開最直觀。將 σ=0.55 px 的 2 顆星以不同間隔抖動拍攝 16 幀，分別以平均合成與 drizzle x3 (pixfrac=0.4) 後做 star_detect 的實測：間隔 1.6 輸入像素時，平均合成找到 1 顆，drizzle 找到 2 顆(2.0 px 以上兩者都是 2 顆)。
*shifts* 是 (N, 2) 的 (dr, dc)，表示幀 i 相對基準偏移多少(synth_frame_series 的 truth["shifts"] 就是這個方向)。None 則全部為 0。
★ 注意符號 —— frame_align / align_frames 回傳之矩陣的平移是「把幀拉回基準」的方向，亦即與這裡需要的 (dr, dc) 符號相反。若直接傳入估計值，偏移不會被抵消反而加倍，也不擲出例外地產生雙像(實測：6 幀 96x96 時 est + truth ≈ 0，直接傳入殘差為 2 倍)。要從矩陣得到方向正確的 shifts，請使用 drizzle_shifts。不接受旋轉 —— 一旦有旋轉，各軸不再可分離，重疊面積無法寫成閉合式，
所以請先用 align_frames 還原(在那裡付出內插誤差，讓這筆交易可見較為誠實)。
★ 輸入像素落到輸出的哪裡(先前沒有寫明這一約定)。依像素中心彼此的對應::
out = in * scale + (scale - 1) / 2
scale=2 時，輸入 (8, 8) 的星位於輸出 (16.5, 16.5)。輸入像素 in 所佔區間 [in, in+1) 映射到輸出的 [in*scale, (in+1)*scale)，其中心就是上式 —— 而不是單純的 in*scale。若丟掉半個像素，scale=4 時會產生 1.5 個輸出像素、換算輸入為 0.375 像素的系統偏移，對位後的測光與雙星間距都會因此悄悄出錯。
實測(24x24、單像素星、pixfrac=1、以質心量測)：scale 為 2 / 3 / 4 時與上式之差嚴格為 0。scale=2.5 時偏移 0.05 個輸出像素，但這不是公式錯誤，而是因為邊緣輸出像素只被部分覆蓋，索引的質心與連續量的質心之間產生偏差(整數倍時不會出現這個零頭)。需要嚴格處理位置時請使用整數 scale。
Returns (sci, wht):
• sci —— (round(H*scale), round(W*scale)) float64，總通量單位(與輸入相同的電子數)。落到網格外的液滴會使總和減少，因此 sci.sum() 與輸入總和之差正是「邊緣損失的量」。
• wht —— 同形狀的權重圖，表示輸出像素被多少份液滴覆蓋(輸出像素面積記為 1)。pixfrac=1 且 shifts=0 時內部嚴格為 1.0。
★ 觀看 / 量測時請使用 sci / wht。 sci 為了守恆總通量，原樣保存「分配的量」，覆蓋的不均勻會殘留在影像中。pixfrac 較小時覆蓋呈網格狀不均，對原始 sci 做偵測，這個網格就會變成星 —— 實測(scale=3、pixfrac=0.4、1 對雙星 24 幀)中，star_detect 對原始 sci 回傳了 200 個(頂到上限)，對 sci / wht 則正確回傳 2 個。守恆量(sci)與外觀(sci / wht)是不同的量，以其一代替另一個毫無例外地會出錯。
Raises ValueError：*frames* 不是 list / tuple / 形狀不一致 / *scale* 小於 1 / *pixfrac* 不在 (0, 1] 內 / *shifts* 的形狀不是 (N, 2) / 輸出超過 MAX_OUTPUT_ELEMENTS 時。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• astro_stacking — py -3.11 examples/astro_stacking.py
• poc_astro_photometry — py -3.11 examples/poc_astro_photometry.py
• poc_superresolution_limits — py -3.11 examples/poc_superresolution_limits.py
image2d 作為輸入)frame_quality · noise_sigma · cosmic_ray_reject · star_detect · psf_fit · aperture_photometry · frame_align
stack)*Provenance: astrostack.py — ASTROSTACK 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.