Optics API Reference

This section documents the optical elements, wave optics, ray tracing utilities, PSF utilities, and related losses.

Geometric Surfaces

Spheric

class deeplens.optics.geometric_surface.Spheric(c, r, d, mat2, pos_xy=[0.0, 0.0], vec_local=[0.0, 0.0, 1.0], is_square=False, device='cpu')

Spherical surface parameterized by curvature.

Parameters:

  • c – Curvature 1/R [1/mm]

  • r – Aperture radius [mm]

  • d – Surface z-position [mm]

  • mat2 – Material after the surface (e.g., 'N-BK7', 'air')

  • pos_xy – Lateral offset [mm]

  • vec_local – Surface local normal (unit vector)

  • is_square – Square aperture if True, circular otherwise

  • device – Device

Key methods (inherited from :class:`deeplens.optics.geometric_surface.base.Surface` unless noted):

  • ray_reaction(ray, n1, n2, refraction=True): Intersect and refract/reflect a deeplens.optics.Ray.

  • intersect(ray, n=1.0): Solve ray-surface intersection.

  • sag(x, y): Surface sag function z(x, y).

  • normal_vec(ray): Surface normal at intersection points.

Aspheric

class deeplens.optics.geometric_surface.Aspheric(r, d, c, k, ai, mat2, pos_xy=[0.0, 0.0], vec_local=[0.0, 0.0, 1.0], is_square=False, device='cpu')

Even-order asphere.

Parameters:

  • r – Aperture radius [mm]

  • d – Surface z-position [mm]

  • c – Base curvature 1/R [1/mm]

  • k – Conic constant

  • ai – Aspheric coefficients list [a2, a4, a6, ...]

  • mat2 – Material after the surface

  • pos_xy – Lateral offset [mm]

  • vec_local – Surface local normal (unit vector)

  • is_square – Square aperture if True

  • device – Device

Mathematical form:

\[z = \frac{c\rho^2}{1 + \sqrt{1-(1+k)c^2\rho^2}} + \sum_{i=1}^{n} a_{2i} \rho^{2i}\]

Plane

class deeplens.optics.geometric_surface.Plane(r, d, mat2, pos_xy=[0.0, 0.0], vec_local=[0.0, 0.0, 1.0], is_square=False, device='cpu')

Flat surface (e.g., cover glass, IR filter, DOE base).

Parameters:

  • r – Aperture radius [mm]

  • d – Surface z-position [mm]

  • mat2 – Material after the surface

  • pos_xy – Lateral offset [mm]

  • vec_local – Surface local normal (unit vector)

  • is_square – Square aperture if True

  • device – Device

Aperture

class deeplens.optics.geometric_surface.Aperture(r, d=0.0, pos_xy=[0.0, 0.0], vec_local=[0.0, 0.0, 1.0], is_square=False, device='cpu')

Aperture stop.

Parameters:

  • r – Semi-diameter [mm]

  • d – Surface z-position [mm] (typically 0)

  • pos_xy – Lateral offset [mm]

  • vec_local – Surface local normal (unit vector)

  • is_square – Square aperture if True

  • device – Device

ThinLens

class deeplens.optics.geometric_surface.ThinLens(r, d, f=100.0, pos_xy=[0.0, 0.0], vec_local=[0.0, 0.0, 1.0], is_square=False, device='cpu')

Paraxial thin lens element.

Parameters:

  • r – Semi-diameter [mm]

  • d – Surface z-position [mm]

  • f – Focal length [mm]

  • pos_xy – Lateral offset [mm]

  • vec_local – Surface local normal (unit vector)

  • is_square – Square aperture if True

  • device – Device

Diffractive Surfaces

Fresnel

class deeplens.optics.diffractive_surface.Fresnel(d, f0=None, wvln0=0.55, res=(2000, 2000), mat='fused_silica', fab_ps=0.001, device='cpu')

Fresnel (zone-plate-like) DOE with inverse dispersion relative to refractive lenses.

Parameters:

  • d – DOE z-position [mm]

  • f0 – Design focal length at wvln0 [mm]

  • wvln0 – Design wavelength [μm]

  • res – DOE resolution (H, W) [pixels]

  • mat – DOE material name

  • fab_ps – Fabrication pixel size [mm]

  • device – Device

Binary2

class deeplens.optics.diffractive_surface.Binary2(d, res=(2000, 2000), mat='fused_silica', wvln0=0.55, fab_ps=0.001, device='cpu')

Two-level binary phase DOE with polynomial radial phase.

Parameters:

  • d – DOE z-position [mm]

  • res – DOE resolution (H, W) [pixels]

  • mat – DOE material name

  • wvln0 – Design wavelength [μm]

  • fab_ps – Fabrication pixel size [mm]

  • device – Device

Pixel2D

class deeplens.optics.diffractive_surface.Pixel2D(d, phase_map_path=None, res=(2000, 2000), mat='fused_silica', wvln0=0.55, fab_ps=0.001, device='cpu')

Pixelated metasurface with per-pixel phase parameters or a provided phase map path.

Parameters:

  • d – DOE z-position [mm]

  • phase_map_path – Optional path to a saved phase map tensor

  • res – DOE resolution (H, W) [pixels]

  • mat – DOE material name

  • wvln0 – Design wavelength [μm]

  • fab_ps – Fabrication pixel size [mm]

  • device – Device

Zernike

class deeplens.optics.diffractive_surface.Zernike(d, z_coeff=None, zernike_order=37, res=(2000, 2000), mat='fused_silica', fab_ps=0.001, wvln0=0.55, device='cpu')

DOE parameterized by Zernike polynomials.

Parameters:

  • d – DOE z-position [mm]

  • z_coeff – Zernike coefficients tensor/list

  • zernike_order – Number of Zernike terms (currently 37)

  • res – DOE resolution (H, W) [pixels]

  • mat – DOE material name

  • fab_ps – Fabrication pixel size [mm]

  • wvln0 – Design wavelength [μm]

  • device – Device

Ray Class

class deeplens.optics.Ray(o, d, wvln=0.55, coherent=False, device='cpu')

Light ray representation.

Parameters:

  • o – Origins […, N, 3] in mm

  • d – Directions […, N, 3] (unit vectors)

  • wvln – Wavelength [μm]

  • coherent – Enable coherent tracing and OPL accumulation

  • device – Device

Attributes:

  • o: Ray origins […, N, 3]

  • d: Ray directions […, N, 3]

  • valid: Valid mask […, N]

  • wvln: Wavelength field […, 1] in μm

  • opl: Optical path length […, 1] (coherent mode)

  • is_forward: Direction flag (z-forward)

Selected methods:

  • prop_to(z, n=1.0): Propagate rays to plane z

  • centroid(): Centroid of ray bundle

  • rms_error(center_ref=None): RMS spot size

  • clone(device=None): Deep copy optionally on a device

  • squeeze(dim=None): Squeeze dimensions

Materials

class deeplens.optics.Material(name=None, device='cpu')

Optical material with dispersion from built-in catalogs and custom tables.

Parameters:

  • name – Material name (e.g., 'N-BK7', 'air') or an "n/V" string

  • device – Device

Selected methods:

  • refractive_index(wvln): Refractive index at wavelength(s) in μm

  • match_material(mat_table='CDGM'): Match to closest catalog material

  • get_optimizer_params(lrs=[...]): Parameters for optimizing n, V

Notes:

  • Supports Sellmeier, Schott, Cauchy, interpolation, and optimizable modes.

Wave Optics

ComplexWave

class deeplens.optics.wave.ComplexWave(u=None, wvln=0.55, z=0.0, phy_size=(4.0, 4.0), res=(2000, 2000))

Complex scalar field with convenience constructors and propagation.

Selected classmethods:

  • point_wave(point=(0,0,-1000.0), wvln=0.55, ...)

  • plane_wave(wvln=0.55, ...)

  • image_wave(img, wvln=0.55, ...)

Selected methods:

  • prop(prop_dist, n=1.0): Propagate by distance (ASM under the hood)

  • prop_to(z, n=1.0): Propagate to plane z

  • save(filepath) / load(filepath)

  • show(save_name=None, data='irr')

Propagation Functions

deeplens.optics.AngularSpectrumMethod(u, z, wvln, ps, n=1.0, padding=True)

Angular spectrum propagation. u can be [H, W] or [B, 1, H, W].

deeplens.optics.FresnelDiffraction(u, z, wvln, ps, n=1.0, padding=True, TF=None)

Fresnel diffraction (transfer function or impulse response form).

deeplens.optics.FraunhoferDiffraction(u, z, wvln, ps, n=1.0, padding=True)

Fraunhofer diffraction (far-field approximation).

deeplens.optics.RayleighSommerfeld(u, z, wvln, ps, n=1.0, memory_saving=True)

Rayleigh–Sommerfeld diffraction (reference, more expensive).

deeplens.optics.wave.Fresnel_zmin(wvln, ps, side_length, n=1.0)

Minimum propagation distance for Fresnel diffraction (Nyquist sampling criterion).

deeplens.optics.wave.Nyquist_ASM_zmax(wvln, ps, side_length, n=1.0)

Maximum propagation distance for Angular Spectrum Method (Nyquist sampling criterion).

PSF Utilities

deeplens.optics.psf.conv_psf(img, psf)

Convolve an image batch with one PSF per channel.

deeplens.optics.psf.conv_psf_map(img, psf_map)

Convolve with a spatial PSF map (grid-based).

deeplens.optics.psf.conv_psf_map_depth_interp(img, depth, psf_map, psf_depths)

Depth-aware PSF map interpolation and convolution.

deeplens.optics.psf.conv_psf_pixel(img, psf)

Per-pixel PSF convolution.

deeplens.optics.psf.read_psf_map(filename, grid=10)

Read a PSF map image into a tensor.

Loss Functions

PSFLoss

class deeplens.optics.loss.PSFLoss(w_achromatic=1.0, w_psf_size=1.0)

Loss promoting concentrated, achromatic PSFs.

forward(psf)
Parameters:

psf – PSF tensor [B, C, H, W] or compatible

Returns:

Scalar loss

Monte Carlo Integration

deeplens.optics.monte_carlo.forward_integral(ray, ps, ks, pointc=None, coherent=False)

Forward Monte Carlo integration for PSF or wavefront from rays.

deeplens.optics.monte_carlo.assign_points_to_pixels(points, mask, ks, x_range, y_range, interpolate=True, coherent=False, amp=None, phase=None)

Helper for assigning sample points to pixel grids.

deeplens.optics.monte_carlo.backward_integral(ray, img, ps, H, W, interpolate=True, pad=True, energy_correction=1)

Backward integral (experimental) for ray-tracing-based rendering.

Examples

Ray Tracing Example

import torch
from deeplens.optics import Ray, Material
from deeplens.optics.geometric_surface import Spheric

# Create surface and material
surface = Spheric(c=1/50.0, r=12.5, d=5.0, mat2='N-BK7')
glass = Material('N-BK7')

# Create rays
ray = Ray(
    o=torch.tensor([[0.0, 0.0, -10.0]]),
    d=torch.tensor([[0.0, 0.0, 1.0]]),
    wvln=0.55,
    device='cpu'
)

# Trace through surface
n1 = 1.0  # air
n2 = glass.refractive_index(0.55)
ray_out = surface.ray_reaction(ray, n1, n2)

Wave Propagation Example

from deeplens.optics.wave import ComplexWave

# Plane wave then propagate 10 mm in air
field = ComplexWave.plane_wave(wvln=0.55, phy_size=(5.12, 5.12), res=(512, 512))
field.prop(10.0)

Material Dispersion Example

import torch
import matplotlib.pyplot as plt
from deeplens.optics import Material

glass = Material('N-BK7')

w = torch.linspace(0.4, 0.7, 100)  # μm
n = glass.refractive_index(w)

plt.plot(w.cpu(), n.cpu())
plt.xlabel('Wavelength [μm]')
plt.ylabel('Refractive Index')
plt.title('N-BK7 Dispersion')
plt.show()

See Also