fpm op• Data kinds: table → table
• Call: import fullseye as fs; fs.ledger.fp_reconstruct(stack, upsample=None, n_iter=200, pupil_update=True, pupil_start=2, alpha=1.0, beta=1.0, led_correction=False, led_start=3, stall_tol=0.01, stall_window=10, agree_tol=0.08, starts=2, margin_px=None, intensity_correction=False, pupil_degree=4, on_fail='raise') (implementation को सीधे call करना हो तो import fourierptycho; fourierptycho.fp_reconstruct(stack, upsample=None, n_iter=200, pupil_update=True, pupil_start=2, alpha=1.0, beta=1.0, led_correction=False, led_start=3, stall_tol=0.01, stall_window=10, agree_tol=0.08, starts=2, margin_px=None, intensity_correction=False, pupil_degree=4, on_fail='raise'), registry से लेना हो तो opsoptics.get("fp_reconstruct"))
• GPU: नहीं (केवल CPU reference implementation)
कम-resolution images के समूह से उच्च-resolution amplitude और phase वापस पाना (table, kind="fp_result")। converge न हो तो मना करता है।
क्रमिक phase retrieval (Ou आदि 2014 का EPRY, ePIE जैसा ही रूप): illumination NA के छोटे से बड़े क्रम में एक-एक image लेकर, अनुमानित low-resolution field के amplitude को मापे गए amplitude से बदला जाता है, और उस अंतर से object spectrum को alpha और pupil को beta के step से सुधारा जाता है (pupil को pupil_startवें iteration से; circle के बाहर इसे 0 रखा जाता है)।
• pupil_degree (default 4): pupil phase के update को circle पर orthogonalize किए गए 2–4 order के polynomials (12; defocus, astigmatism, coma, spherical जैसे low-order aberrations) पर project किया जाता है, और amplitude 1 रखा जाता है। None हर pixel पर free EPRY है (मूल paper का रूप) —— ★free pupil noise को सोख लेता है, residual घटता ही रहता है और स्थिर नहीं होता (32 pixel, 25 images के synthetic डेटा में 200 iterations के बाद भी हर 10 पर 1 % से अधिक)।
• upsample: high-resolution grid का गुणक। None हो तो वह सबसे छोटा integer जिसमें illumination NA समा जाए और pixel λ/(2 NA_syn) से अधिक न हो।
• led_correction: led_startवें iteration से, हर image के लिए pupil center को ±1 pixel की 9 स्थितियों पर आज़माकर न्यूनतम residual लिया जाता है (बराबरी पर rounded मानों से तुलना, और candidates के declaration क्रम में पहले वाला), फिर table के led_xyz_mm पर LED array की geometry (shift x, y, rotation, ऊँचाई) को least squares से fit करके centers को उस prediction पर फिर से रखा जाता है (Sun आदि 2016 के simulated annealing को deterministic local search से बदला गया रूप)।
• intensity_correction: तीसरे iteration से हर image के brightness ratio को अनुमान के औसत से मिलाया जाता है (उस real data के लिए जहाँ LED की चमक ज्ञात नहीं)। सबसे छोटे illumination NA वाली image को reference मानकर नहीं हिलाया जाता —— ★सबको हिलाने पर, अनुमान चमकीला होते ही मापी गई images को भी फिर से चमकीला करने वाला positive feedback बनता है; real data पर residual 200 iterations में 20,000 गुना तक diverge हुआ (जब pupil को polynomials पर project किया गया)।
• Convergence: amplitude के relative residual का fixed point और अलग initial values वाले 2 runs (starts=2) का agree_tol के भीतर मेल। Residual न घटे, iterations ख़त्म हो जाएँ, या 2 runs अलग उत्तरों पर पहुँचें — इनमें से कोई भी हो तो "converge नहीं हुआ"। on_fail="raise" (default) FPNotConvergedError देता है (MetricContractError, record में दर्ज), "record" record लौटाता है (converged=False)।
• starts=1 अद्वितीयता के गेट से नहीं गुज़रता (केवल ठहराव से converged=True हो सकता है): uniqueness_checked False होता है, और reason में "uniqueness not checked" जोड़ा जाता है।
• Residual की ऊपरी सीमा: अभिसरण की जाँच केवल residual के बदलाव को देखती है। यदि अंतिम residual RESIDUAL_WARN (0.1) से अधिक हो तो residual_warning=True किया जाता है और reason में चेतावनी जोड़ी जाती है (निर्णय नहीं बदलता)। संश्लेषित डेटा पर मापा गया: अभिसरित पुनर्निर्माण 0.004–0.03 (rms 0.12 तरंग के aberration सहित); प्रदीपन k से असंबद्ध यादृच्छिक छवियाँ एक प्रारंभिक मान के साथ 0.17 पर ठहर जाती हैं।
Return value: dict(kind="fp_result", converged, reason, n_iter, residual, residual_history, residual_history_starts, step_history (हर चक्कर में object spectrum का relative बदलाव), start_disagreement, field_second_start, amplitude, phase, field, pupil, pupil_support, na_synthetic (= NA_obj + उपयोग किए गए illumination NA का अधिकतम, diagonal LED सहित), na_synthetic_axis (x, y direction cosine के अधिकतम से लिया गया मान = axis के साथ वाले bars का resolution तय करने वाला मान), pixel_um, upsample, margin_px, led_centres, led_geometry, intensity_scale, uniqueness_checked, residual_warning, residual_ceiling)।
Raises: ValueError (तालिका अधूरी है या कोई मान सीमा से बाहर है, छवियों में ऊर्जा 0 है (exposure से भाग देने के बाद, किनारों को छोड़कर सभी छवियों का योग), LED सुधार द्वारा बैठाई गई ज्यामिति ने pupil के केंद्र को उच्च-विभेदन ग्रिड के बाहर रख दिया)।
optics के सभी ops गणना से पहले input की जाँच करते हैं (कुछ भी चुपचाप पास नहीं होता):
• Unit argument के नाम में ही लिखी होती है — _mm / _um / _deg / _mrad। mm और µm की गड़बड़ी crash नहीं करती, बल्कि "सही दिखने वाला पर गलत उत्तर" देती है, इसलिए नाम से इसे रोका जाता है। मान के आकार से unit का अनुमान बिल्कुल नहीं लगाया जाता।
• String से ValueError — float('50') सफल हो जाता है, इसलिए बिना parse किया config value length के रूप में निकल जाता (मापा गया: thin_lens('50', '200') सही दिखने वाला 66.667 mm लौटा रहा था)। bool को भी True == 1 वाले implicit promotion के रूप में अस्वीकार किया जाता है।
• complex / masked array से ValueError (केवल real-valued slots; imaginary part को चुपचाप छोड़ना या mask हटाना अस्वीकार)। हर input पर NaN/Inf से ValueError।
• शून्य से भाग और उससे जुड़े मामलों को नाम लेकर अस्वीकार किया जाता है: focal length 0, radius of curvature 0, refractive index <= 0, पूरी तरह opaque aperture (सब 0, इसलिए normalisation 0/0), ऐसा PSF जिसका योग <= 0 हो, S0 = 0 वाला Stokes vector, और front focal point पर रखा object (image अनंत पर)।
• केवल 2 ops non-finite value लौटाते हैं, और वह भी contract के रूप में लिखा हुआ: depth_of_field hyperfocal distance से आगे far_mm = inf (hyperfocal distance की परिभाषा यही है) और gaussian_beam waist पर wavefront_radius_mm = inf (plane wavefront की radius of curvature)। दोनों साथ में एक finite साथी (far_is_infinite / curvature_per_mm) भी लौटाते हैं। इसके अलावा कोई भी चुपचाप आया NaN/Inf अंदर ही पकड़ा जाता है और ValueError देता है — "float64 overflow हुआ" और "उत्तर अनंत है" अलग-अलग दावे हैं, इसलिए पहले को दूसरे का चेहरा पहनाकर नहीं लौटाया जाता।
• Size की सीमा: generate होने वाले grid के लिए optics.MAX_GRID (4096), दिए गए field/PSF/aperture के लिए optics.MAX_FIELD_ELEMENTS (2^24), ABCD element chain के लिए optics.MAX_SYSTEM_ELEMENTS (1024), Zernike के लिए MAX_ZERNIKE_TERMS (512) / MAX_ZERNIKE_ORDER (40) / MAX_ZERNIKE_BASIS (2^25)। छोटे argument से बहुत बड़ा internal allocation होने वाले रास्तों (मापा गया: n_max=40 × 4096² पर 108 GB) को fail-closed ढंग से बंद किया गया है।
• भौतिक रूप से असंभव states भी अस्वीकार: degree of polarisation > 1 वाला Stokes vector, ऋणात्मक transmittance, ऋणात्मक intensity, और n-|m| odd जैसे अमान्य Zernike indices।
• Sample data catalog (DL URL / license) — 2-D के लिए skimage.data (BSD/public) + synthetic, 3-D के लिए real data sources (Stanford/PDS आदि) के DL URL।
• Operators का स्रोत और संदर्भ — इस op family के मूल research/methods के स्रोत।
• Algorithm का मानक स्रोत (लेखक, वर्ष) और उपयोग ऊपर की family usage guide में दिए गए हैं।
• poc_fourier_ptychography — py -3.11 examples/poc_fourier_ptychography.py
table को input के रूप में लेते हैं)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
fpm)fp_design · fp_usaf_target · fp_capture · fp_stack_from_images · fp_element_contrast
*Provenance: fourierptycho.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.