Seeing through water¶
Looking at something through water¶
For a horizontal path, the observed radiance splits into the target’s light that survived and the light the water added along the way:
import numpy as np, jerlov
wl = np.arange(450., 651., 50.)
iops = jerlov.water("III")
kd = jerlov.water("III", source="austin1986")
scene = jerlov.Scene.at_depth(iops, 10.0, np.ones_like(wl), wl, kd=kd)
b_inf = jerlov.veiling_radiance_estimate(
iops, scene.downwelling, wl, backscatter_ratio=0.015
)
obs = scene.observe(np.full_like(wl, 0.8), distance_m=5.0,
veiling_radiance=b_inf, face_irradiance_ratio=0.3)
obs.direct, obs.veiling, obs.radiance
obs.veiling_fraction # how much of what you see is just water
obs.contrast(background) # against another target down the same path
veiling_radiance has no default. B_inf depends on the backscattering
coefficient and the phase function, and neither follows from the water type.
veiling_radiance_estimate gives the usual single-scattering approximation
for callers with nothing better, but it has to be asked for.
face_irradiance_ratio is the light on the face of the target the observer
sees, as a fraction of the downwelling irradiance: 1 for a face turned
straight up, less for one turned towards a horizontal line of sight. The
water type does not fix it either, so it has no default; pass 1.0 for what
releases before 0.12.0 assumed.
Deliberate limits, all recorded in DECISIONS.md:
Slanted paths in uniform water only.
observeis horizontal;observe_slanttakes a target above or below (see below).No forward-scatter blur. This is the radiance of one point, not the sharpness of an image.
Lambertian targets.
Looking up or down¶
Scene.observe_slant takes a target at another depth, after Duntley
(1963). The observer is at the scene’s depth; nothing about the angle is
needed beyond the two depths and the distance:
# n_w and k_l are yours: measured, or from a model of the light field
obs = scene.observe_slant(np.full_like(wl, 0.8), 8.0, target_depth_m=15.0,
kd=kd, water_radiance=n_w,
radiance_attenuation=k_l,
face_irradiance_ratio=1.0)
water_radiance is the radiance of the water itself seen along that line
from the observer, and radiance_attenuation how fast it falls with depth.
Neither has a default: the second is not Kd, and is the same in every
direction only in the asymptotic light field. Looking down, contrast
falls faster than along a horizontal line; looking up, more slowly.
Duntley’s eq. (12) prints the wrong sign in front of the path radiance
(DATA.md section 34).
Coefficients for the Akkaynak-Treibitz form¶
Underwater vision work usually writes the same physics as
I = J * exp(-beta_D * r) + B_inf * (1 - exp(-beta_B * r))
p = scene.attenuation_coefficients((0.5, 5.0), veiling_radiance=b_inf)
p.beta_D, p.beta_B, p.B_inf
p.are_distinct # False
p.note # why
are_distinct is False, and that is the honest answer. Under single
scattering both coefficients are the beam attenuation coefficient c. The
central claim of Akkaynak & Treibitz (2018) is that in reality they differ and
vary with range, depth and target reflectance; separating them needs
measurements this package does not have.
It is still useful. Implementations that fit these coefficients often bound them by guesswork for want of a physical starting point. This gives them one, and says how far it can be trusted.
distance_range_m is required and recorded. A coefficient quoted without the
range it describes is not a well-defined quantity, so the API does not let you
omit it.
Light that is turned, not lost¶
The direct term above attenuates with c, which counts every scattered photon as gone. At Petzold’s eight stations 46 to 64 percent of the scattering turns light by less than 5 degrees, and that light still arrives near where it came from: blurred rather than lost. With one of his measured waters, the share of the scattering within a half-angle, and the attenuation of the light kept within it:
f = jerlov.forward_scatter(jerlov.petzold_scattering("HAOCE 11"), 5.0)
f.fraction # the share of b within 5 degrees
f.c_within # c - b(< 5 deg) of that water, 1/m, at 530 nm
jerlov.attenuation_within(jerlov.water("III"), wl, forward=f)
attenuation_within applies that share to a type’s own b,
which assumes the station’s phase function holds for the type at every
wavelength: neither is known, so the station has no default. This is
single scattering, checked against a Monte Carlo; reading it as the
light that forms an image is an assumption, and a blurred image itself
is not computed (DATA.md section 49).
What colour is that¶
white = scene.downwelling / np.pi # a perfect diffuser at that depth
rgb = jerlov.spectrum_to_srgb(obs.radiance, wl, white=white)
jerlov.spectrum_to_xyz(spectrum, wl) # unnormalised CIE XYZ
jerlov.integrate_response(spectrum, wl, sensitivity, sensitivity_wl)
white has no default. A radiance spectrum has no colour until something is
called white, and underwater the useful reference is usually the downwelling
irradiance at that depth rather than daylight. Both are legitimate and they
answer different questions:
white |
question answered |
|---|---|
downwelling at depth |
what a diver’s adapted eye, or a camera white-balanced there, sees |
daylight at the surface |
what a camera set at the surface records |
integrate_response takes any spectral sensitivity: three camera channels,
or a set of photoreceptor absorbances.
Two silent errors are checked rather than assumed:
Coverage. A spectrum spanning 450-650 nm integrated against colour matching functions spanning 360-830 nm quietly drops the ends. Every integration reports how much of the observer it actually covered and warns when it is not essentially all of it.
Gamut. Underwater colours often fall outside sRGB. Clipping changes them, so
GamutWarningsays so.
How far apart two colours are to an eye¶
Two pieces of visual ecology, each from its primary paper, with what belongs to a species left to you:
wl = np.arange(331.0, 701.0, 1.0)
# Govardovskii et al. (2000): the absorbance of a pigment with its peak at
# lambda_max, for an A1 or A2 chromophore. Neither has a default.
s = jerlov.visual_pigment_template(wl, lambda_max=500.0, chromophore="A1")
# Vorobyev & Osorio (1998): the distance between two colours in units of
# receptor noise, from quantum catches scaled to the background. The noise
# of each receptor channel has no default either.
catch = (jerlov.integrate_response(target, wl, sensitivities, wl)
/ jerlov.integrate_response(background, wl, sensitivities, wl))
jerlov.receptor_noise_distance(catch, other_catch, noise=noise)
The model is the paper’s: linear in the catches, for colours close to the background, in bright light. Its eq. (4) is misprinted; the package computes the general form the paper derives it from (DATA.md section 26).