Water for other software

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.