shape_from_polarization op• Data kinds: polsweep → table
• Call: import fullseye as fs; fs.ledger.sfp_normals(sweep, refractive_index=1.5, model='specular', angles_deg=(0.0, 45.0, 90.0, 135.0), violation_tol=0.05, out_of_range='invalid') (implementation को सीधे call करना हो तो import sfpolar; sfpolar.sfp_normals(sweep, refractive_index=1.5, model='specular', angles_deg=(0.0, 45.0, 90.0, 135.0), violation_tol=0.05, out_of_range='invalid'), registry से लेना हो तो opsoptics.get("sfp_normals"))
• GPU: नहीं (केवल CPU reference implementation)
polariser sweep से हर pixel के surface normal के उम्मीदवारों का स्पष्ट समुच्चय — diffuse में 2, specular में 4 (2 zenith × 2 azimuth) (table)।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
*sweep* is an (N, H, W) stack through linear analysers at *angles_deg* (the polsweep sort; optics.polarization_demosaic gives it from a raw mosaic). Per pixel the sinusoid I(t) = a0 + a1 cos 2t + a2 sin 2t is fitted (the same least-squares fit as specularity.polarization_dolp_map), giving DoLP = hypot(a1, a2)/a0 and AoLP = 0.5 atan2(a2, a1); then dolp_to_zenith and aolp_to_azimuth give the zenith and azimuth candidates.
A fitted minimum below zero (modulation above the mean, DoLP > 1) is impossible for light. Near Brewster's angle the true minimum is ~0, so sensor noise pushes it slightly negative; *violation_tol* is the largest excess DoLP - 1 that is read as noise (DoLP clipped to 1). A larger excess marks the pixel invalid — the frames do not match *angles_deg*, or the pixel saw something other than a polariser sweep. Such a pixel is reported in violation, never silently clipped. (specularity.polarization_dolp_map refuses the whole image instead; a shape map with one hot pixel is still a shape map, so here the decision is per pixel and sfp_disambiguate refuses invalid pixels inside its mask by default.)
*out_of_range*: a DoLP that no zenith produces (diffuse model, above (n^2-1)/(n^2+1)) makes the pixel "invalid" (default) or is "clamp"-ed to the reachable limit and kept, flagged in clamped.
Returns a dict (a table, marked kind == "sfp_candidates"):
• candidates (K, H, W, 3) unit normals; specular order is [low zenith & azimuth 0, low & azimuth 1, high & azimuth 0, high & azimuth 1], diffuse [azimuth 0, azimuth 1]. Zero vectors at invalid pixels (see valid) — never NaN, never a made-up unit normal.
• zenith_deg (1|2, H, W), azimuth_deg (2, H, W), dolp, aolp_deg, intensity (S0) (H, W).
• n_distinct (H, W) — how many genuinely different normals the pixel admits: 4 (specular), 2 at Brewster's angle or for the diffuse model, 0 where nothing fits or the pixel is dark.
• valid (H, W) bool — lit, physically possible and invertible; violation / clamped (H, W) bool — why a pixel is suspect.
• dark (H, W) bool — the fitted mean a0 = S0/2 is at most specularity.POLAR_DARK_K (3) × the noise of the modulation amplitude σ_A = σ̂·√(v₁+v₂) (v = the diagonal of the fit's (MᵀM)⁻¹; σ̂ = one noise level for the image, from the median per-pixel residual of the N > 3 frames, χ²-median corrected), i.e. the DoLP's own noise would be 1/3 or more: no degree of polarisation is defined there, so the pixel is not lit (valid False, n_distinct 0). ★Before 2026-11-09 only a0 > 0 was required, and clipped sensor noise in a dark region (σ 0.001 of a scene peaking at 1) gave DoLP ≈ 1 and Brewster-angle normals on 26–28 % of the dark pixels, all valid. (A first fix used a floor relative to the brightest 1 % of the image, which ignored the noise: it killed a dark diffuse object next to specular highlights and fell into the noise when the bright part was under 1 % of the image.) A frame that does not belong to the sweep raises the residual to the level of the signal, and then every pixel is dark — the sweep defines no DoLP anywhere (fail-closed); the violation flags are still computed independently of dark. With three angles there is no residual and only a0 <= 0 is dark — noise-only dark pixels are not screened.
• dolp_noise (H, W) — the DoLP's noise level σ_A/a0 (0 on unlit pixels — they have no DoLP, see valid / dark), and noisy = lit pixels with dolp_noise > violation_tol — a flag only (valid is not changed by it): their DoLP, hence their zenith, is mostly noise. With three angles dolp_noise is None and noisy all False. ★One σ̂ for the image assumes stationary noise; shot noise grows with the signal, so treat the flag as a screen.
• model, refractive_index, brewster_deg.
Nothing here chooses among the candidates; a single "best" normal map returned at this stage would be a guess dressed as a measurement.
Raises ValueError: not an (N, H, W) stack of >= 3 finite non-negative frames; angles that do not match or do not determine the fit; *violation_tol* outside [0, 1]; index not > 1; unknown *model* / *out_of_range*.
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। घोषित अपवाद: bottle_fit_from_pattern का u_map न मापे जा सके पिक्सेल को NaN के रूप में लेता है (अनंत अब भी अस्वीकार)।
• शून्य से भाग और उससे जुड़े मामलों को नाम लेकर अस्वीकार किया जाता है: 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 हुआ" और "उत्तर अनंत है" अलग-अलग दावे हैं, इसलिए पहले को दूसरे का चेहरा पहनाकर नहीं लौटाया जाता। घोषित अपवाद: bottle_background_map जिन पिक्सेल की किरण अनुपयोगी है (पूर्ण आंतरिक परावर्तन आदि) उनके लिए u_mm में NaN लौटाता है, साथ में valid मास्क और गिनती भी।
• 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_shape_from_polarization — py -3.11 examples/poc_shape_from_polarization.py
table को input के रूप में लेते हैं)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
shape_from_polarization)sfp_dolp_model · dolp_to_zenith · aolp_to_azimuth · sfp_render · sfp_disambiguate · sfp_estimate_index · sfp_height
*Provenance: sfpolar.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.