imaging op• Data kinds: image2d → pairs
• Call: import fullseye as fs; fs.ledger.encircled_energy(psf, pixel_pitch_um=1.0, samples=64, max_radius_um=None, centre='centroid') (implementation को सीधे call करना हो तो import optics; optics.encircled_energy(psf, pixel_pitch_um=1.0, samples=64, max_radius_um=None, centre='centroid'), registry से लेना हो तो opsoptics.get("encircled_energy"))
point-spread function (PSF) की encircled energy: त्रिज्या r के वृत्त के भीतर ऊर्जा का अनुपात।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
The standard spot-quality curve of lens design (how much light lands inside a given pixel or fibre core). *psf* is an image2d of non-negative samples on a grid of *pixel_pitch_um* (use the pixel_pitch_um argument of lensimage.psf_from_opd, or the fine-grid spacing of pupil_psf); the circle is centred on the energy centroid by default (*centre* = 'centroid', 'peak', 'fft' for the fftshift origin, or a (row, col) pair in pixels). Edge pixels are weighted by the exact area inside the circle, so the curve is smooth in r; a radius under about two pixels is resolved only coarsely.
Returns a (samples, 2) float64 pairs array: column 0 the radius in micrometres from 0 to *max_radius_um* (default the largest circle that fits in the array about the centre), column 1 the fraction of the array's energy inside, in [0, 1], non-decreasing. Energy outside the array is not known, so a PSF window that cuts the wings off reads high; keep the window several times the spot.
Ground truth it reproduces: an unaberrated circular pupil gives the Airy pattern, whose encircled energy is 1 - J0(v)^2 - J1(v)^2 with v = 2 pi r / (lambda N): 83.8 % at the first dark ring (r = 1.2197 lambda N, Born and Wolf), 91.0 % at the second, 93.8 % at the third (measured in tests/test_optdesign_psf_metrics.py).
Raises ValueError: *psf* not 2-D / smaller than 3x3 / negative / zero energy / non-finite; non-positive *pixel_pitch_um* or *max_radius_um*; *samples* outside [2, 4096]; a radius that leaves the array; a bad *centre*.
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।
• measurement_uncertainty — Measurement uncertainty और calibration — 'हम माप रहे हैं' कहने के लिए क्या चाहिए
• mv_cameras — Industrial camera निर्माता (sensor mapping, line scan / TDI)
• virtual_machine_vision — Virtual machine vision — parameters की सूची और एक object model
• 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 में दिए गए हैं।
• optical_design_metrics — py -3.11 examples/optical_design_metrics.py
• poc_zoom_configurations — py -3.11 examples/poc_zoom_configurations.py
pairs को input के रूप में लेते हैं)mtf50 · energy_to_photons · spectral_product · spectral_integral · spectral_stats · kubelka_munk_reflectance · hyperspectral_capture · film_thickness_fft
imaging)psf_to_mtf · mtf_diffraction · ensquared_energy · energy_radii · mtf_tangential_sagittal · wavefront_stats · edge_spread · sfr_from_edge
*Provenance: optics.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.