fpm op• Datenarten: table → table
• Aufruf: 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') (die Implementierung direkt: 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'); aus dem Register: opsoptics.get("fp_reconstruct"))
• GPU: nein (nur CPU-Referenzimplementierung)
Gewinnt hochaufgelöste Amplitude und Phase aus dem Satz niedrig aufgelöster Bilder zurück (table, kind="fp_result"). Lehnt ab, wenn die Iteration nicht konvergiert.
Sequentielle Phasenrückgewinnung (EPRY nach Ou et al. 2014, gleiche Form wie ePIE): Bild für Bild in aufsteigender Beleuchtungs-NA wird die Amplitude des geschätzten niedrig aufgelösten Felds durch die gemessene Amplitude ersetzt, und mit der Differenz werden das Objektspektrum mit Schrittweite alpha und die Pupille mit Schrittweite beta korrigiert (die Pupille ab Iteration pupil_start; außerhalb des Kreises bleibt sie 0).
• pupil_degree (Standard 4): die Aktualisierung der Pupillenphase wird auf über dem Kreis orthogonalisierte Polynome 2.–4. Ordnung projiziert (12 Terme; Aberrationen niedriger Ordnung wie Defokus, Astigmatismus, Koma und sphärische Aberration), die Amplitude bleibt 1. None ergibt pixelweise freies EPRY (Form der Originalarbeit) —— ★eine freie Pupille absorbiert Rauschen, sodass das Residuum weiter fällt und nie stationär wird (bei einer Synthese mit 32 Pixeln und 25 Bildern auch nach 200 Iterationen noch über 1 % pro 10 Iterationen).
• upsample: Vergrößerungsfaktor des hochaufgelösten Rasters. Bei None die kleinste ganze Zahl, bei der die Beleuchtungs-NA hineinpasst und das Pixel höchstens λ/(2 NA_syn) ist.
• led_correction: ab Iteration led_start wird für jedes Bild der Pupillenmittelpunkt an den 9 Positionen innerhalb ±1 Pixel getestet und das minimale Residuum genommen (Gleichstände werden anhand gerundeter Werte verglichen, es gewinnt der frühere in der Deklarationsreihenfolge der Kandidaten); anschließend wird die Geometrie des LED-Arrays (Versatz x, y, Drehung, Höhe) per kleinster Quadrate an led_xyz_mm der Tabelle angepasst und die Mittelpunkte auf diese Vorhersage zurückgesetzt (das Simulated Annealing von Sun et al. 2016 ersetzt durch eine deterministische lokale Suche).
• intensity_correction: ab Iteration 3 wird das Helligkeitsverhältnis pro Bild an den Mittelwert der Schätzung angeglichen (für reale Daten, bei denen die LED-Helligkeit unbekannt ist). Das Bild mit der kleinsten Beleuchtungs-NA bleibt als Referenz fest —— ★werden alle bewegt, macht eine hellere Schätzung auch die gemessenen Bilder wieder heller, eine positive Rückkopplung; bei realen Daten divergierte das Residuum in 200 Iterationen um das 20.000-Fache (mit auf Polynome projizierter Pupille).
• Konvergenz: Fixpunkt des relativen Amplitudenresiduums und Übereinstimmung zweier Läufe mit unterschiedlichen Startwerten (starts=2) innerhalb agree_tol. Fällt das Residuum nicht, sind die Iterationen erschöpft oder landen die 2 Läufe bei verschiedenen Lösungen, gilt dies jeweils als "nicht konvergiert". on_fail="raise" (Standard) löst FPNotConvergedError aus (MetricContractError, in record protokolliert), "record" gibt das Protokoll zurück (converged=False).
• starts=1 durchläuft das Eindeutigkeits-Tor nicht (Stillstand allein kann converged=True ergeben): uniqueness_checked wird False, und an reason wird „uniqueness not checked“ angehängt.
• Obergrenze des Residuums: der Konvergenztest betrachtet nur die Änderung des Residuums. Übersteigt das letzte Residuum RESIDUAL_WARN (0,1), wird residual_warning=True gesetzt und an reason eine Warnung angehängt (das Urteil bleibt). Gemessen an synthetischen Daten: konvergierte Rekonstruktionen 0,004–0,03 (einschließlich einer Aberration von rms 0,12 Wellen); Bilder ohne Bezug zum Beleuchtungs-k stagnieren mit einem Startwert bei 0,17.
Rückgabe: dict(kind="fp_result", converged, reason, n_iter, residual, residual_history, residual_history_starts, step_history (relative Änderung des Objektspektrums pro Durchlauf), start_disagreement, field_second_start, amplitude, phase, field, pupil, pupil_support, na_synthetic (= NA_obj + größte verwendete Beleuchtungs-NA, einschließlich diagonaler LEDs), na_synthetic_axis (aus dem größten Richtungskosinus in x, y gewonnener Wert = der Wert, der die Auflösung achsparalleler Balken bestimmt), pixel_um, upsample, margin_px, led_centres, led_geometry, intensity_scale, uniqueness_checked, residual_warning, residual_ceiling).
Raises: ValueError (Tabelle unvollständig oder ein Wert außerhalb des Bereichs, die Bilder tragen keine Energie (Summe über alle Bilder nach Division durch die Belichtung, ohne Ränder), die von der LED-Korrektur angepasste Geometrie legt ein Pupillenzentrum außerhalb des hochaufgelösten Gitters).
Jeder optics-Operator prüft seine Eingabe vor der Berechnung (nichts rutscht stillschweigend durch):
• Einheiten stecken im Argumentnamen — _mm / _um / _deg / _mrad. Eine Verwechslung von mm und µm stürzt nicht ab, sondern liefert eine plausibel aussehende falsche Antwort; der Name verhindert das. Aus der Größenordnung wird nie auf die Einheit geschlossen.
• Strings lösen ValueError aus — float('50') gelingt, sodass ein ungeparster Konfigurationswert als Länge durchrutschen würde (gemessen: thin_lens('50', '200') lieferte plausible 66,667 mm). bool wird als implizite Hochstufung True == 1 ebenfalls abgelehnt.
• complex / Masked Arrays lösen ValueError aus (nur reelle Slots; das stille Verwerfen des Imaginärteils bzw. Abstreifen der Maske wird abgelehnt). NaN/Inf löst bei jeder Eingabe ValueError aus.
• Division durch null und Verwandtes wird namentlich abgelehnt: Brennweite 0, Krümmungsradius 0, Brechzahl <= 0, undurchlässige Blende (alles 0, die Normierung wird 0/0), PSF mit Summe <= 0, Stokes-Vektor mit S0 = 0 und ein Objekt im vorderen Brennpunkt (Bild im Unendlichen).
• Nur zwei Operatoren liefern einen nicht-endlichen Wert, und beide halten das vertraglich fest: depth_of_field liefert jenseits der hyperfokalen Distanz far_mm = inf (genau das bedeutet die hyperfokale Distanz), und gaussian_beam liefert an der Taille wavefront_radius_mm = inf (der Krümmungsradius einer ebenen Wellenfront). Beide liefern zusätzlich einen endlichen Partner (far_is_infinite / curvature_per_mm). Jedes andere stille NaN/Inf wird intern erkannt und löst ValueError aus — "float64 ist übergelaufen" und "die Antwort ist unendlich" sind verschiedene Aussagen; die erste wird nie im Gewand der zweiten geliefert.
• Größenobergrenzen: erzeugte Gitter durch optics.MAX_GRID (4096), übergebene Felder/PSFs/Blenden durch optics.MAX_FIELD_ELEMENTS (2^24), ABCD-Elementketten durch optics.MAX_SYSTEM_ELEMENTS (1024), Zernike durch MAX_ZERNIKE_TERMS (512) / MAX_ZERNIKE_ORDER (40) / MAX_ZERNIKE_BASIS (2^25). Damit werden Pfade fail-closed geschlossen, in denen ein kleines Argument eine riesige interne Allokation auslöst (gemessen: n_max=40 × 4096² braucht 108 GB).
• Physikalisch unmögliche Zustände werden ebenfalls abgelehnt: Stokes-Vektor mit Polarisationsgrad > 1, negative Transmission, negative Intensität und ungültige Zernike-Indizes wie ungerades n-|m|.
• Leitfaden zur Familie optics_imaging
• Katalog der Beispieldaten (Download-URLs / Lizenzen) — 2-D nutzt skimage.data (BSD/Public Domain) plus synthetische Bilder, 3-D nennt Download-URLs echter Datenquellen (Stanford, PDS, …).
• Herkunft und Literatur der Operatoren — die Quellen der Forschung/Verfahren, auf denen diese Operatorfamilie beruht.
• Der kanonische Algorithmus (Autor, Jahr) und seine Anwendungen stehen im Familienleitfaden oben.
• poc_fourier_ptychography — py -3.11 examples/poc_fourier_ptychography.py
table als Eingabe)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. Diese Notiz wird von tools/opdocs.py md erzeugt (nicht von Hand bearbeiten).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.