jerlov
Inherent optical properties of the Jerlov optical water types, with provenance.
https://github.com/tishibashi-cpu/jerlov
Documentation, with guides and the API reference: https://tishibashi-cpu.github.io/jerlov/
pip install jerlov
Every coefficient carries the source it came from. Values that a published table got wrong are flagged rather than quietly repaired, and quantities that the data do not determine are refused rather than guessed.
What is claimed. That the published coefficients are implemented correctly, and that every shipped table can be regenerated from its primary source. The tests demonstrate both, by reproducing each paper's tables from that paper's own equations.
What is not claimed. That this predicts what a camera will record
underwater. That would need measurements which, as far as we can tell, have
not been made. DATA.md records what is uncertain and DECISIONS.md records
where the model stops.
import jerlov
w = jerlov.water("III") # Williamson & Hollins (2022) by default
w.a(550), w.b(550), w.c(550)
Why the source is part of the API
The same Jerlov water type has different coefficients in different papers, and the differences are not small. Solonenko & Mobley (2015) obtained a and b by inverting Kd; Williamson & Hollins (2022) measured them. At 510 nm their scattering coefficients differ by up to a factor of 3.8, at Jerlov III.
The equations differ too. Both papers use the scattering model of Haltrin (1999), but with different constants: Haltrin's Eq. (6) gives a small-particle coefficient of 1.151302, and Solonenko & Mobley print and compute with 1.513. Reproducing a published table therefore needs that paper's own constant, so constants are attached to sources.
What this package will not do
- Extrapolate. Asking for a wavelength outside the data raises. Values that a source itself extrapolated are returned, but marked, and they warn.
- Fill a gap. Where a published value is wrong and could not be recovered, the value is NaN and stays NaN through interpolation.
- Supply bb. The backscattering coefficient is not determined by the
Jerlov classification. Deriving it from the particle concentrations of the
two sources gives answers differing by up to a factor of 31, so
Water.bbrequires an explicit ratio:backscatter_ratio(bb/b, pure water included) orparticle_backscatter_ratio(bbp/bp).
Provenance warnings
Interpolating across a value that a paper got wrong gives a number that looks
no different from a sound one. ProvenanceWarning is the only thing that
tells them apart.
>>> w = jerlov.water("5C", source="solonenko2015")
>>> w.b(650)
ProvenanceWarning: b for Jerlov 5C rests on flagged values:
reconstructed at 650 nm. ...
Water.caveats() returns everything known to be doubtful about that water.
Sources
| key | a, b from | types | range |
|---|---|---|---|
williamson2022 |
measurement | IB-5C | 300-800 nm |
solonenko2015 |
inversion of Kd | I-9C | 300-700 nm |
jerlov1976 |
Kd only | I-9C | 300-715 nm; printed 310-700, and outside that it warns |
jerlov1968 |
Kd only, first edition | I-9C | 310-700 nm |
austin1986 |
Kd only, replacement values | I-1C | 350-700 nm |
solonenko2015 also carries kd_hydrolight(), the Kd that HydroLight
computed from its a and b; DATA.md section 19 says how it differs from kd().
jerlov.SOURCES holds the full citation, DOI and caveats for each. The two
Jerlov editions differ by up to 35 percent at single wavelengths; establish
which one a number came from before comparing it with either.
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.
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).
If you measured backscattering
Water.bb refuses to guess a backscattering ratio. If you have an instrument
you do not have to:
r = jerlov.bb_from_vsf(0.0021, 140, 532, salinity_psu=37.0) # beta, angle, nm
r.bb, r.particulate, r.water # 1/m
r.chi_p, r.quoted_error_percent # 1.18, 3.5
Boss & Pegau (2001). The pure sea water terms are analytic and are checked against the definition of bb rather than transcribed; only the particle conversion is tabulated. The salinity has no default: pure sea water at 37 scatters 30 percent more than fresh water. Angles outside 90-170 degrees are refused, and 170 warns: its quoted spread is 34.8 percent against 2.6-6.4 from 90 to 160.
This gives the bb of the water your instrument was in. It still gives no bb for a Jerlov water type, because nothing does.
Measured scattering functions
Without an instrument, the next best thing to a guess is a water that was measured. Petzold (1972) measured the volume scattering function from 0.1 to 180 degrees in eight ocean waters, from the clear Tongue of the Ocean to San Diego Harbor:
jerlov.PETZOLD_STATIONS # clearest first: 'AUTEC 8', ..., 'NUC 2040'
f = jerlov.petzold_scattering("HAOCE 11")
f.c, f.b, f.backscatter_ratio # 0.398, 0.21933, 0.013 (1/m, 1/m, bb/b)
f.vsf_at(120.0) # 1/(m sr), at 530 nm
f.phase_function() # vsf / b, at f.angles_deg
w.bb(532, backscatter_ratio=f.backscatter_ratio) # bb/b of a measured water
The ratio spans 0.013 to 0.044 across the eight. These are eight waters on eight days in 1971, at 530 nm, water and particles together; none of them is a Jerlov type. Every value was transcribed from the report and checked against its own integrals and its second printing; DATA.md section 21.
Measured reflectances of real materials
m = jerlov.usgs2017_reflectance("red_nylon") # one of jerlov.USGS2017_MATERIALS
m.wavelengths, m.reflectance # 350-830 nm, every nm
Ten materials found in and around water, from white PVC to cobalt violet,
as the USGS Spectral Library Version 7 measured them (CC0): something real
to put in front of Scene instead of an invented curve. They are dry
laboratory samples; wet, or another sample, they would reflect differently
(DATA.md section 37).
The type changes with depth
The classification is defined on the top 10 m, but clarity does not stay put. Water that is Jerlov I at the surface is typically IB below 40 m; turbid coastal water clears as you go down.
jerlov.water_type_at_depth("I", 60.0) # 'IB'
jerlov.water_type_at_depth("3C", 45.0) # 'II'
jerlov.water_type_at_depth("9C", 15.0) # None: the paper declined to say
jerlov.water_type_at_depth("I", [0, 30, 60]) # array(['I', 'IA', 'IB'], dtype=object)
None means fewer than ten measurement campaigns supported a declaration, so
nothing is asserted. This is a lookup, not a correction applied on your
behalf.
To carry the downwelling irradiance down through that profile, with each 10 m layer attenuating by the Kd of its own type:
d = jerlov.descend("1C", 45.0, wl) # source="jerlov1976" by default
d.layers # ((0, 10, '1C'), (10, 20, '1C'), (20, 30, 'III'), ..., (40, 45, 'II'))
d # <Descent 1C to 45 m: 1C 0-20, III 20-40, II 40-45 m; Kd from jerlov1976; ...>
scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
It refuses to go through a layer the paper declared nothing for, rather than
carrying the last type on: 3C stops at 70 m, 9C at 10 m.
jerlov.profile_depth("3C") says how far a descent can go, and
d.transmittance_at(z) gives any depth above the descent's bottom without
descending again.
Light for photosynthesis
PAR, the photon flux from 400 to 700 nm, attenuated wavelength by wavelength rather than with one coefficient, and the depth at which it falls to 1 percent of its surface value:
p = jerlov.par_profile(surface, wl, [0, 25, 50], kd=d, unit="energy")
p.par # umol photons m-2 s-1 at each depth
p.fraction # PAR(z) / PAR(0)
p.depth_of_fraction(0.01) # m
p.kd_par(0, 1) # effective Kd(PAR) over the top metre, 1/m
p.spectrum_at(25) # photons per nm at 25 m, on p.wavelengths_nm
kd is a Water carrying Kd, an array, or a Descent. unit has no
default, because PAR counts photons and an energy spectrum read as photons is
weighted wrongly with no sign of it. This is planar PAR, from Ed. PAR on
scalar irradiance, what a spherical sensor reads, is larger by a factor that
depends on the light field, which the package does not model; give it as the
mean cosine (Ed - Eu) / E0 and the reflectance Eu / Ed, neither of which has
a default:
p.scalar_par(mean_cosine=0.75, reflectance=0.02) # E0 = Ed (1 - R) / mu
reflectance=0 leaves out the upwelling light, as a choice you make
(DECISIONS.md section 59).
band=(lo, hi) integrates over another band instead, such as part of PAR
for the share of one colour; outside 400-700 nm the result is a photon flux
in that band, not PAR, and p.band_nm says which. photon_weight= weights
each photon by its wavelength, for a pigment's absorption or a receptor's
sensitivity, and the depths and Kd then follow the weighted flux.
A measured Kd with a standard uncertainty gives a range as well:
w = jerlov.Water.from_measurements(wl, kd=measured_kd,
uncertainty={"kd": sigma_kd})
p = jerlov.par_profile(surface, wl, [0, 25, 50], kd=w, unit="energy")
p.depth_of_fraction_bounds(0.01) # (shallower, deeper), m, Kd +- 1 sigma
p.par_bounds(k=2) # (lower, higher) PAR, Kd +- 2 sigma
kd_uncertainty= does the same beside an array kd. The errors are taken
as fully correlated between wavelengths, the widest range any errors within
k sigma can give (DECISIONS.md section 57). The published types carry no
uncertainty, so they and descend give no range.
Jerlov measured quanta irradiance, 350-700 nm, by water type, and his
tables are shipped for checking against, with
band=jerlov.QUANTA_BAND_NM to integrate over his band:
jerlov.jerlov1977_quanta("II") # <QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; ...>
From II to 3C the package agrees with them within 2 m at every level. For
Jerlov I it agrees only through descend; for IB it puts the 1 percent
level a third too deep, because Jerlov's IB water grew more turbid below
15 m; the profiles of quanta and the spectra measured at the stations he
drew on show the same. DATA.md section 22; DECISIONS.md sections 53-56.
Tyler measured the radiance from every direction at seven depths in a deep lake, and his tables are shipped too, for checking a radiative transfer model against:
jerlov.tyler1958_radiance(41.3) # <RadianceDistribution Tyler 1958, 41.3 m, 19 tilts x 10 azimuths>
The package solves no radiative transfer itself; the Monte Carlo model in
examples/radiance_distribution.py is compared with these tables, and does
not match them. DATA.md section 23.
Under a wavy surface the light flickers. Two field studies that give it only in figures are shipped as values read off those figures, each with its conditions and the precision of the reading:
jerlov.darecki2011_irradiance_cv() # CV of Ed, 0.86-9.58 m, 443/532/670 nm
jerlov.darecki2011_radiance_cv("a") # CV of radiance, 13 angles in the sun's plane
jerlov.gernez2009_cv_by("sun_zenith_deg") # CV of Ed at 510 nm against the sun's zenith angle
jerlov.darecki2011_spectral_cv() # CV of Ed at 410-670 nm on five days of wind
jerlov.gernez2009_cv_by("kd490_per_m") # ... against wave height, wind or Kd(490)
jerlov.gernez2009_cv_by("wind_m_s", sky="overcast") # overcast; or irradiance="Eu"
jerlov.gernez2009_spectral_cv("Eu") # CV of Eu at 412-683 nm, clear and overcast
jerlov.gernez2009_band_cv("wind_m_s") # CV of Ed at six bands against the conditions
jerlov.gernez2009_diffuse_share() # the sky's share of the light, as printed
They carry status = read_from_figure. The package does not model the
fluctuations, which depend on the wind, the waves and the collector as much
as on the water. DATA.md sections 24 and 25; DECISIONS.md section 42.
Which type is my water nearest?
r = jerlov.classify_kd(wl, measured_kd) # source="jerlov1976" by default
r # <KdClassification II 0.064, then IB 0.412 (jerlov1976, 26 wavelengths)>
r.distances # every type, nearest first: rms of ln(measured / type)
r.beyond # "clearer" or "more turbid" than every type, or None
jerlov.classify_kd(wl, measured_kd, uncertainty=sigma_kd
).nearest_within_uncertainty # ("II", "IB"): either, within 1 sigma
It ranks the types of one edition; it draws no boundaries, since those differ
between editions. A single wavelength is accepted, and ranks oceanic and
coastal types less well apart than a spectrum does. types= compares with
some of the types only, which keeps the wavelengths where only the others
have gaps.
Other entry points
# Reconstruct a Kd spectrum from one measured value (Austin & Petzold 1986).
jerlov.kd_spectrum(0.06, 490, [440, 550, 650]) # Kd, its nm, the nm wanted
# Estimate b from a transmissometer's c (Smart 2007).
jerlov.b_from_c(0.5, 555, bw=0.0019, cw=0.0659) # c, its nm
jerlov.pure_water_scattering(555, salinity_psu=37.0) # Morel's bw, if c was corrected with it
# An attenuation coefficient from a Secchi depth, by a rule you name; warns.
jerlov.k_from_secchi(4.0, coefficient=jerlov.POOLE1929_SECCHI_COEFFICIENT) # 1.7 / 4 m
# The measured points behind the williamson2022 spectra, with their spread.
m = jerlov.measured_points("III", "a") # m.wavelengths, m.values, m.std_dev
# The pure water absorption williamson2022 built its a on (300-800 nm).
jerlov.pure_water_absorption(440) # 0.0104; other sources say why they have none
# A published pure water absorption in its own right: "pope1997", "smith1981",
# "mason2016", "lee2015" or "lee2015_smoothed". Which one is yours to say.
jerlov.pure_water_absorption_table(440, source="pope1997") # 0.00635
# Use your own measurements; they take exactly the same path, flags included.
w = jerlov.Water.from_measurements(
wavelengths, a=..., b=...,
flags={"a": statuses}, # "ok", "suspect", ...: as in DATA.md; flagged ones warn
uncertainty={"a": sigma_a}, # 1/m; w.uncertainty("a", 532)
)
Without a water type: chlorophyll, a and bb, the Secchi depth
# Kd of case 1 water from its chlorophyll, mg m^-3 (Morel & Maritorena 2001).
jerlov.morel2001_kd([443, 490, 555], chlorophyll_mg_m3=0.3)
# The 1988 edition, whose C is chlorophyll a plus pheophytin a.
jerlov.morel1988_kd([443, 490, 555], pigment_mg_m3=0.3)
# The clearest ocean water measured (Morel et al. 2007): eight stations of the
# South Pacific gyre, and their pure water absorption.
stations = jerlov.morel2007_stations()
jerlov.pure_water_absorption_table([310, 420], source="morel2007")
# From the same chlorophyll: absorption by phytoplankton (Bricaud et al. 1995)
# and backscattering by particles (Morel & Maritorena 2001). Water, and the
# rest of what absorbs, are not included.
jerlov.bricaud1995_aph([443, 490, 555], chlorophyll_mg_m3=0.3)
jerlov.morel2001_bbp([443, 490, 555], chlorophyll_mg_m3=0.3)
# Kd from a, bb and the sun (Lee et al. 2005, 2013); bb has no default.
bbw_490 = jerlov.pure_water_backscattering(490, salinity_psu=35.0)
jerlov.lee2013_kd(0.03, 0.004, bb_water=bbw_490, sun_zenith_deg=30.0)
# The visible (350-700 nm) energy's attenuation from the surface to a depth,
# and the depth where 1 percent of it is left, from a(490) and bb(490)
# (Lee et al. 2005, C09019; Lee et al. 2007).
jerlov.lee2005_kvis(0.03, 0.004, 20.0, sun_zenith_deg=30.0)
jerlov.lee2007_depth_of_fraction(0.03, 0.004, sun_zenith_deg=30.0, fraction=0.01)
# A Kd under another sun and sky, by Gordon's (1989) D0. Both D0 are yours:
# Jerlov's tables do not record the light they were measured under.
d0 = jerlov.gordon1989_d0(30.0, direct_fraction=0.8)
jerlov.gordon1989_kd(0.05, d0_from=d0, d0_to=jerlov.gordon1989_d0(60.0, direct_fraction=0.7))
# The remote sensing reflectance, below and above the surface.
rrs = jerlov.subsurface_rrs(a, bb, coefficients=jerlov.GORDON1988_RRS_COEFFICIENTS)
Rrs = jerlov.above_surface_rrs(rrs)
# From above-water radiances: Rrs = (Lt - rho Lsky) / Ed, with rho from one
# of Mobley's tables (1999 or 2015; no default) or a value you choose.
rho = jerlov.mobley_rho(source="mobley1999", wind_speed=5.0, sun_zenith_deg=30.0,
view_nadir_deg=40.0, view_azimuth_deg=135.0)
jerlov.rrs_from_above_water(lt, lsky, ed, rho=rho)
# An ac-9's absorption corrected for the light its tube misses, by one of the
# four methods Röttgers et al. (2013) compared; the method has no default.
jerlov.rottgers2013_scatter_correction(am, cm, am715, cm715, method="proportional", ec=1.0)
# Or above the surface with water and particles apart, at one of the seven
# viewing geometries Lee et al. (2011) print; (0, 0, 0) is straight down.
jerlov.lee2011_rrs(a, bb, bb_water=bb_water,
coefficients=jerlov.LEE2011_RRS_COEFFICIENTS[(0.0, 0.0, 0.0)])
# Take Raman scattering out of a measured Rrs first (Lee et al. 2013), 412-667 nm.
jerlov.lee2013_raman_correction(bands_nm, measured_Rrs,
bands={"440": 443, "550": 555}).rrs
# The Secchi depth from one Kd and one Rrs spectrum, 400-700 nm (Lee et al. 2015).
jerlov.lee2015_secchi_depth(wavelengths, kd, Rrs)
# And back: a and bbp from Rrs by the quasi-analytical algorithm, either version.
q = jerlov.qaa_v6(bands_nm, Rrs, bands={"412": 412, "443": 443, "490": 490,
"55x": 555, "670": 670},
pure_water=(pw_nm, aw, bbw)) # q.a, q.bbp, q.adg, q.aph
# pw_nm, aw and bbw are arrays covering the bands: for instance
# pure_water_absorption_table(pw_nm, source="pope1997") and
# pure_water_backscattering(pw_nm, salinity_psu=35.0).
jerlov.qaa_ioccg2006(...) # the version IOCCG Report 5 tested; same arguments
These are forward relations, each from its paper and each with the
conditions it was fitted for: Morel & Maritorena's for case 1 water only,
the reflectance for deep water seen from straight above. A result outside
what the paper fitted or checked comes with a ProvenanceWarning. The
inverse comes in two versions: QAA_v6 reproduces the results its author's
spreadsheet stored, and the IOCCG Report 5 version reproduces that report's
statistics on its synthetic data (DATA.md section 28). Nothing here reads
satellite files; pass the Rrs you have read (DECISIONS.md sections 66 and
67).
The light at the sea surface under a clear sky
sky = jerlov.gregg1990_irradiance(
np.arange(350, 701), sun_zenith_deg=40.0, day_of_year=172,
pressure_hpa=1013.25, air_mass_type=1, relative_humidity=80.0,
precipitable_water_cm=1.5, wind_speed_24h=3.0, wind_speed=5.0,
ozone_du=300.0, visibility_km=15.0) # or aerosol_optical_thickness_550
sky.direct_above, sky.diffuse_above # W m-2 nm-1, just above the sea
sky.below # just below: Scene.at_depth, par_profile
The model of Gregg & Carder (1990), with its table of the sun's spectrum and the gases' absorption at every nm from 350 to 700. Every input that describes the sky is yours; none has a default. It reproduces the paper's own diffuse shares (Table 5) to the printed percent. The paper prints a second 1/2 inside Fresnel's law (DATA.md section 35).
Water for a renderer
rgb = jerlov.rgb_attenuation(
jerlov.water("III"), colour_space="acescg", # or linear_srgb, rec2020
illuminant=jerlov.d65(), distance_range_m=(0.5, 10.0))
rgb.sigma_t, rgb.sigma_s, rgb.albedo # 1/m, one per channel
rgb.max_relative_error_t # what one exponential costs
table = jerlov.rgb_transmittance(jerlov.water("III"), [1.0, 5.0, 10.0],
colour_space="acescg",
illuminant=jerlov.d65())
table.transmittance # (3 distances, 3 channels), unfitted
hg = jerlov.henyey_greenstein_fit(jerlov.petzold_scattering("HAOCE 5"),
method="backscatter_ratio") # or mean_cosine
hg.g, hg.log_ratio # and where HG misses Petzold
spectra = jerlov.spectral_coefficients(jerlov.water("III"),
range_nm=(400, 700))
spectra.as_dict() # for json.dump, as are the others
For film, games and simulation. A renderer in RGB attenuates each channel
as one exponential, which the spectrum is not, and the answer depends on
the light entering the water and on the distances in the scene, so both
are yours to state and the error over them comes back with the fit; a
renderer that reads a table can have the transmittance itself, unfitted. A
channel that turns negative, as the red of linear sRGB does after a few
metres of clear water, is refused rather than clipped. The
Henyey-Greenstein g is matched to Petzold's measured B/S or to his mean
cosine, which you choose; neither matches sea water's forward peak. The
spectra go to Mitsuba 3 or pbrt-v4 without an RGB step.
examples/rendering_export.py writes all three for Mitsuba 3, pbrt-v4
and Blender (DECISIONS.md section 82).
Water for a radiative transfer code
iii = jerlov.water("III")
profile = jerlov.osoaa_user_profile( # OSOAA's -HYD.UserProfile
iii, 440.0, depths_m=[0, 10, 50],
pure_water=(0.00635, 0.00501629)) # what OSOAA adds back at 440 nm
phase = jerlov.osoaa_phase_function( # OSOAA's -HYD.ExtData
jerlov.petzold_scattering("NUC 2200"), minus_f12_over_f11=0.0,
f22_over_f11=1.0, f33_over_f11=1.0) # Petzold measured none of these
wl = [440.0, 550.0]
ac9 = jerlov.hydrolight_ac9_file( # HydroLight's standard ac-9 format
iii, wl, depths_m=[0, 50],
pure_water=(jerlov.pure_water_absorption(wl), # the aw under III's a
jerlov.pure_water_scattering(wl, salinity_psu=35.0)))
This package does not solve the radiative transfer equation; OSOAA and
HydroLight do. Each function returns the text of an input file for one of
them. Both codes add their own pure water back, so the pure water to take
off is the one the run will add: there is no default, and a coefficient
that turns negative without it is refused. Petzold measured no
polarization, so OSOAA's ratios are yours too. The OSOAA files were run in
OSOAA by hand and gave back Jerlov III's c and b/c; HydroLight was not
available, and its file follows the documentation (DATA.md section 38).
examples/radiative_transfer_inputs.py writes all three.
from pathlib import Path
run = Path("results") # OSOAA's -OSOAA.ResRoot
flux = jerlov.read_osoaa_flux((run / "Advanced_outputs/Flux.txt").read_text())
flux.kd(0.0, 50.0) # mean Kd of Ed, 1/m
flux.total_down, flux.total_up # normalized: the sun above is pi
lu = jerlov.read_osoaa_radiance_vs_depth(
(run / "Standard_outputs/RESLUM_vsZ.txt").read_text())
lu.radiance, lu.reflectance # pi L / Esun and pi L / Ed
OSOAA's results read back, as it prints them, normalized to the sun
above the atmosphere, which OSOAA leaves to you and so does this package.
read_osoaa_radiance_vs_vza reads the radiance against the viewing angle.
OSOAA's "direct" flux is not the unscattered beam: it counts the forward
peak it truncates from the phase function as transmitted. HydroLight's
outputs are not read; no file from it was available to test against.
Solar heating of the upper ocean
Ocean circulation models absorb shortwave radiation as a sum of two exponentials, with parameters per Jerlov type from Paulson & Simpson (1977):
jerlov.solar_fraction("IB", 10.0) # 0.183 of the surface irradiance
p = jerlov.shortwave_parameters("IB") # R, zeta1_m, zeta2_m
depths, fraction = jerlov.jerlov1968_solar_fraction("IB") # the table itself
Broadband, 300-2500 nm; nothing to do with the spectral quantities above. The
parameters are usually copied from secondary sources, so tools/ refits them
from the table the paper fitted, Jerlov (1968) Table XXI, and reproduces R for
every row.
They miss their own source by 46 percent at 1 m for types II and III. Two
exponentials cannot follow the near-surface decay. DATA.md section 14 has
the numbers; anyone heating a thin surface layer should read it.
Only the five oceanic types were fitted. Asking for a coastal type raises rather than substituting a neighbour.
Lee et al. (2005, C09019) let the attenuation change with depth, the visible part's from a(490), bb(490) and the sun, the infrared's from the depth and the sun; the visible share of the surface shortwave has no default:
jerlov.lee2005_shortwave_transmittance(0.03, 0.004, [1.0, 10.0],
sun_zenith_deg=30.0, visible_fraction=0.424)
jerlov.lee2005_kir(1.0, sun_zenith_deg=30.0) # 700-2500 nm, 1/m
Against Table XXI it misses less than the two exponentials in the top 10 m
for most oceanic types, and more below; DATA.md section 42.
Examples
python examples/sources_disagree.py why the source is an argument
python examples/from_one_measurement.py from an instrument reading
python examples/synthetic_underwater_images.py appearance at range and depth
python examples/solar_heating.py for ocean circulation models
python examples/what_an_eye_sees.py any spectral sensitivity
python examples/light_at_depth.py light through the depth profile
python examples/measured_scattering.py Petzold's measured bb/b
python examples/what_is_in_the_water.py absorption without the water
python examples/euphotic_zone.py PAR and the 1 percent depth
python examples/optical_link.py laser range for links and lidar
python examples/seagrass_depth_limit.py light at the bottom, by requirement
python examples/isolumes.py light levels and vertical migration
python examples/lure_colours.py painted lures: colour and contrast
python examples/ultraviolet.py UV-A at depth, against PAR
python examples/radiance_distribution.py radiance from every direction
python examples/painted_sphere.py a sphere seen from four directions
python examples/wave_focusing.py flicker under waves, against Darecki
python examples/fish_colour_differences.py colour differences for a fish's cones
python examples/ocean_colour_and_secchi.py Kd from chlorophyll or a and bb, the Secchi depth
python examples/sunlight_and_d65.py the clear sky at the surface against D65
python examples/looking_up_and_down.py contrast looking up, across and down
python examples/rendering_export.py water for Mitsuba, pbrt and Blender
python examples/rgb_versus_spectral.py what RGB rendering does to colours
python examples/water_lookup_tables.py tables for games and real-time shaders
python examples/phase_function_choice.py Henyey-Greenstein against Petzold
python examples/reference_images.py measured materials through three types
python examples/radiative_transfer_inputs.py files for OSOAA and HydroLight
python examples/closure_with_jerlov_kd.py an open question: IOPs against Jerlov's Kd
Twenty-eight scripts, each aimed at a different reader; examples/README.md says
which to start with. CI runs all of them on every push, so an example that has
stopped working is a failed build. Every one ends with the assumptions it
made.
Provenance and design
DATA.md records, for every shipped table, where it came from, what was
verified, and what is known to be wrong with it. Forty-six entries are
documented there: thirteen confirmed defects in the source literature, three
questions the first edition of Jerlov settled, and the rest notes.
DECISIONS.md records why the package is shaped the way it is, including the
alternatives that were rejected and why.
OPEN_QUESTIONS.md gathers what comparing the sources found: where they
disagree, by how much, and how much of it the conditions a source leaves
unrecorded could explain. The package does not settle these questions;
it puts numbers on them, each recomputed by a test.
Contributing, and reporting a wrong number
CONTRIBUTING.md sets out what goes in and what it takes: a primary source, a
script in tools/ that produces the table, checks inside that script against
the paper's own equations, an entry in DATA.md, and a regression test.
A coefficient that disagrees with a paper you have is the most useful report
this package can receive. DATA.md exists because several such
disagreements turned out to be defects in the literature rather than here.
Issues: https://github.com/tishibashi-cpu/jerlov/issues
CHANGELOG.md covers every release. What a release may and may not change,
from 1.0 on, is under "Compatibility" in CONTRIBUTING.md.
Licence
Apache-2.0. The Williamson & Hollins data are Crown copyright, Dstl, under
the Open Government Licence v3.0; Mobley's rho tables are from the Ocean
Optics Web Book, under a Creative Commons Attribution licence; see NOTICE.
Citation
Cite the concept DOI, which always resolves to the latest version:
Ishibashi, T. jerlov: inherent optical properties of the Jerlov optical water types, with provenance. Zenodo. https://doi.org/10.5281/zenodo.22321312
Please also cite the sources the coefficients came from; they are listed with
their DOIs at the top of DATA.md. The package is a carrier for other
people's measurements, and this work does not replace citing them.
Metadata
Release files for jerlov 1.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jerlov-1.20.0.tar.gz | 2.1 MB | With provenance | Details for jerlov-1.20.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jerlov-1.20.0-py3-none-any.whl | Python 3 | none | any | Details for jerlov-1.20.0-py3-none-any.whl |
Total release size: 2.5 MB
Release files / jerlov-1.20.0.tar.gz
| Download URL | jerlov-1.20.0.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9dd26bdce23be8389cafd04868ac2e43c899b08f76f751e242146bc146ff5f51
|
|
BLAKE2b-256 checksum How to use checksums |
f43fcbb97d68e776b68de9a705561ce1445a2859d9d8e1ea2d6fffab0f83799a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / jerlov-1.20.0-py3-none-any.whl
| Download URL | jerlov-1.20.0-py3-none-any.whl |
|---|---|
| Size | 404.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
91c34afd6bd2a8f3a3f32215041c63fd125922ba6aa5e2d488967e5745b53093
|
|
BLAKE2b-256 checksum How to use checksums |
60f6df6fc9c0843e0afa250f6af5549705f83c866ddb5bb94ee6c64815fe1a0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for jerlov 1.20.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for jerlov-1.20.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.