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. observe is horizontal; observe_slant takes 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 GamutWarning says 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).