@magmacrunch/adenosine-spectrum 0.0.0-stage → 0.1.0

package/API.md

@@ -0,0 +1,236 @@
+# API Reference: adenosine-spectrum
+
+Colour science for light. Every function is pure and every spectrum is in
+nanometres. Global `AdSpectrum` in the IIFE build.
+
+## Table of Contents
+
+- [Types](#types)
+- [Spectra](#spectra)
+- [Physics](#physics)
+- [Colorimetry](#colorimetry)
+- [OKLab](#oklab)
+- [sRGB](#srgb)
+- [Output](#output)
+
+---
+
+## Types
+
+| Type | Shape |
+|------|-------|
+| `Spectrum` | `{ start, step, values }`: `values[i]` is the value at `start + i * step` nm |
+| `SpectrumLike` | a `Spectrum`, or a function from nm to a value |
+| `XYZ` | `[X, Y, Z]`, CIE tristimulus |
+| `RGB` | `[r, g, b]`, linear or encoded depending on the function, 0..1 in gamut |
+| `Oklab` | `[L, a, b]`, perceptual lightness 0..1 and two opponent axes |
+| `Gamut` | `'perceptual'` (default), `'desaturate'`, `'clip'` or `'none'` |
+
+`CMF_RANGE` is `{ start: 360, end: 830 }`, the matching functions' range and
+the default sampling range.
+
+---
+
+## Spectra
+
+### `spectrum(start, step, values)`
+
+Builds a sampled spectrum. Copies `values`. Throws `RangeError` for a step that
+is not positive or an empty array.
+
+### `sample(fn, start?, end?, step?)`
+
+Samples a function of wavelength onto a uniform grid, both ends included.
+Defaults to 360-830 nm at 1 nm.
+
+### `valueAt(s, nm)`
+
+The value at a wavelength. Linear interpolation between samples, zero outside
+the range. A function is simply called.
+
+### `multiply(a, ...others)`
+
+Multiplies spectra together on the grid of `a`. This is how a filter, a
+reflectance or a transmission is applied to a light. `others` may be spectra or
+functions.
+
+```js
+const ground = multiply(blackbody(5778), rayleigh(0.1));
+```
+
+### `scale(s, k)`
+
+Multiplies every sample by `k`.
+
+### `normalize(s)`
+
+Scales so the largest sample is 1. An all-zero spectrum comes back unchanged.
+
+---
+
+## Physics
+
+### `planck(nm, kelvin)`
+
+Planck's law: blackbody spectral radiance in W sr⁻¹ m⁻² nm⁻¹, with the exact
+CODATA 2018 constants.
+
+### `wienPeak(kelvin)`
+
+The wavelength in nm at which a blackbody's spectral radiance peaks. 501.5 nm
+for the Sun's 5778 K.
+
+### `blackbody(kelvin, start?, end?, step?)`
+
+A blackbody's relative spectrum, 1 at 560 nm. Defaults to 360-830 nm at 1 nm.
+
+### `illuminantD65()`
+
+CIE standard illuminant D65, average daylight, from the CIE table: 300-780 nm
+at 5 nm, 100 at 560 nm. Zero beyond 780 nm, where the matching functions carry
+almost nothing.
+
+### `illuminantA()`
+
+CIE standard illuminant A, tungsten, from the CIE's defining formula:
+300-830 nm at 1 nm, 100 at 560 nm.
+
+### `rayleigh(opticalDepth, referenceNm?)`
+
+A transmission function for a Rayleigh-scattering layer: the fraction of light
+left after optical depth τ at the reference wavelength (550 nm by default),
+scaling as the inverse fourth power of wavelength. Clear air at zenith is about
+τ = 0.1 at 550 nm.
+
+---
+
+## Colorimetry
+
+### `cmf(nm)`
+
+The CIE 1931 2° colour-matching functions `[x̄, ȳ, z̄]` at a wavelength, from
+the 1 nm table. Interpolated linearly, zero outside 360-830 nm. ȳ is 1 at
+555 nm.
+
+### `toXYZ(s, opts?)`
+
+CIE XYZ of a spectrum, integrated against the 1931 observer at 1 nm.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `s` | `SpectrumLike` | | the light, or with an illuminant, a reflectance 0..1 |
+| `opts.illuminant` | `SpectrumLike` | | when given, `s` is a reflectance and Y = 1 for a perfect reflector |
+
+With no illuminant the result is the raw integral, in the units of `s` times nm.
+Throws `RangeError` for an illuminant with no luminance.
+
+```js
+const grey = toXYZ(() => 0.5, { illuminant: illuminantD65() });  // Y = 0.5
+```
+
+### `chromaticity(xyz)`
+
+CIE xy. Black returns the D65 white point.
+
+---
+
+## OKLab
+
+Björn Ottosson's perceptual colour space (2020): lightness L from 0 to 1, and
+`a`, `b` whose angle is hue and whose length is chroma. The gamut mapping
+below works in it. All four accept out-of-gamut and negative values.
+
+### `xyzToOklab(xyz)` / `oklabToXyz(lab)`
+
+CIE XYZ (D65, Y = 1 for white) to OKLab and back, with Ottosson's matrices.
+
+### `linearSrgbToOklab(rgb)` / `oklabToLinearSrgb(lab)`
+
+The same, from and to linear sRGB.
+
+---
+
+## sRGB
+
+### `xyzToLinearSrgb(xyz)`
+
+XYZ (D65, Y = 1 for white) to linear sRGB with the IEC 61966-2-1 matrix. Out of
+gamut gives channels outside 0..1.
+
+### `linearSrgbToXyz(rgb)`
+
+The inverse.
+
+### `encodeSrgb(v)` / `decodeSrgb(v)`
+
+The sRGB transfer function and its inverse, per channel.
+
+### `xyzToSrgb(xyz, opts?)`
+
+XYZ to encoded sRGB.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `opts.gamut` | `Gamut` | `'perceptual'` | how an out-of-gamut colour is brought inside |
+
+| Gamut | What it does | Keeps |
+|---|---|---|
+| `'perceptual'` | reduces OKLab chroma at constant lightness and hue until the colour fits, by bisection; lightness past white gives white, below black gives black | perceived hue and lightness |
+| `'desaturate'` | mixes toward the grey of the same luminance until no channel is negative, then scales down if any exceeds 1 | dominant wavelength, which is not perceived hue: a deep spectral red lands on the red-blue edge and reads pink |
+| `'clip'` | clamps each channel to 0..1 | nothing in particular; cheap |
+| `'none'` | returns what the matrix gives, negatives included | |
+
+### `lightColor(s, opts?)`
+
+The colour of a light at full brightness: its chromaticity, scaled so the
+brightest channel is 1, encoded. Intensity is discarded, so a spectrum and any
+multiple of it give the same colour. Black for a spectrum with no luminance.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `opts.gamut` | `Gamut` | `'perceptual'` | as for `xyzToSrgb` |
+
+A light inside sRGB is scaled so its brightest channel is 1. Under
+`'perceptual'`, a light outside it becomes the most chromatic sRGB colour of
+the same OKLab hue, the cusp, which is where the in-gamut case arrives at the
+gamut's edge, so the two meet without a step.
+
+```js
+lightColor(blackbody(5778));   // the Sun from space: slightly warm of white
+lightColor(illuminantD65());   // [1, 1, 1]
+```
+
+### `wavelengthColor(nm, opts?)`
+
+Monochromatic light at a wavelength as displayable sRGB. Every spectral colour
+is outside sRGB; under the default `'perceptual'` mapping each wavelength gets
+the most chromatic sRGB colour of its OKLab hue. Black outside 360-830 nm.
+
+What that looks like, and why: at full brightness the two ends of the strip are
+flat, because 380-420 nm share one hue to the eye and so do 640-700 nm; the
+blue to cyan stretch changes fast, because hue does there, and passes through
+sRGB blue near 459.5 nm. OKLab puts deep spectral red a few degrees toward blue
+of the sRGB red primary, so reds carry a little blue. `brightness: 'luminous'`
+is the more natural strip: the flat ends fade, as they do to the eye.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `opts.gamut` | `Gamut` | `'perceptual'` | as for `xyzToSrgb` |
+| `opts.brightness` | `'full' \| 'luminous'` | `'full'` | `'luminous'` dims each wavelength by ȳ, so the ends fade as they do to the eye |
+
+---
+
+## Output
+
+### `to8bit(rgb)`
+
+Encoded 0..1 channels to 0..255 integers, clamped.
+
+### `toCss(rgb, alpha?)`
+
+Encoded channels to a CSS colour string: the `rgb` form, or the `rgba` form
+when `alpha` is given, with 0..255 integer channels.
+
+```js
+ctx.fillStyle = toCss(wavelengthColor(550));
+```

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog: `@magmacrunch/adenosine-spectrum`
+
+This package only. Repo-wide changes, such as CI, guard scripts and build
+tooling, live in the [monorepo changelog](../../CHANGELOG.md).
+
+The packages version independently, so a number here means nothing about any
+other package.
+
+## Unreleased
+
+_Nothing yet._
+
+## 0.1.0 - 2026-10-17
+
+First release. Colour science for light, lifted out of the music video
+*sunlight is more green than any other color* and made exact:
+
+- The CIE 1931 2° colour-matching functions at 1 nm, from the CIE table rather
+  than the piecewise-Gaussian fit the video used, which is good to a few
+  percent and no better.
+- `planck` with exact CODATA constants, `blackbody`, `wienPeak`, and the
+  D65 and A illuminants.
+- `rayleigh`, a transmission function, and `multiply` to apply it or any
+  filter or reflectance.
+- `toXYZ`, emissive or reflective under an illuminant, and `chromaticity`.
+- OKLab both ways, from XYZ and from linear sRGB.
+- `lightColor` and `wavelengthColor`, and a `'perceptual'` gamut mapping as
+  the default everywhere: OKLab chroma reduced at constant lightness and hue,
+  and for full-brightness colours the most chromatic sRGB colour of the same
+  hue. `'desaturate'` (toward the grey of the same luminance, keeping dominant
+  wavelength), `'clip'` and `'none'` remain as options.
+- Held by tests to reference values from colour-science, which
+  `tools/generate.py` computes and also writes the tables from.

package/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright 2026 magmacrunch media (https://magmacrunch.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/NOTICE

@@ -0,0 +1,18 @@
+Adenosine
+Copyright 2026 magmacrunch media
+
+Required Notice: Copyright 2026 magmacrunch media (https://magmacrunch.com)
+
+Licensed under the PolyForm Noncommercial License 1.0.0, in the LICENSE file
+beside this one. Any noncommercial purpose is permitted, personal projects,
+teaching and research included. Commercial use is not; for a commercial
+licence, ask.
+
+The licence asks that the "Required Notice" line above travels with any copy
+you pass on. That is how credit for adenosine reaches people downstream.
+
+Versions published under Apache-2.0, up to 2026-10-15, stay under Apache-2.0
+for anyone who already has them. These terms govern this version onward.
+
+Adenosine is a collection of lightweight web game engines:
+https://magmacrunch.com/ware/adenosine/

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @magmacrunch/adenosine-spectrum
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Colour science for light: the CIE 1931 2° colour-matching functions at 1 nm,
+Planck blackbodies, the D65 and A illuminants, Rayleigh scattering, and
+spectrum to sRGB with a perceptual gamut mapping (OKLab chroma reduction at
+constant lightness and hue). For anything that needs
+the colour of a light rather than a colour picked by eye. No runtime
+dependencies.
+
+```bash
+npm install @magmacrunch/adenosine-spectrum
+```
+
+## Use
+
+```js
+import {
+  blackbody, multiply, rayleigh, lightColor, wavelengthColor, toCss,
+} from '@magmacrunch/adenosine-spectrum';
+
+// The Sun from space, and after a thick slab of air
+const sun = blackbody(5778);
+ctx.fillStyle = toCss(lightColor(sun));
+ctx.fillStyle = toCss(lightColor(multiply(sun, rayleigh(1))));
+
+// A spectrum strip, ends fading the way they do to the eye
+for (let nm = 380; nm <= 700; nm++) {
+  ctx.fillStyle = toCss(wavelengthColor(nm, { brightness: 'luminous' }));
+  ctx.fillRect(nm - 380, 0, 1, 20);
+}
+```
+
+From a `<script>` tag, everything is on `window.AdSpectrum`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@magmacrunch/adenosine-spectrum@0.1/dist/index.global.js"></script>
+```
+
+A spectrum is either a sampled `{ start, step, values }` in nm or a plain
+function of nm, and the two mix freely: `multiply(blackbody(5778), (nm) => 0.5)`
+works.
+
+## Accuracy
+
+The tables are the CIE's own, as distributed by
+[colour-science](https://www.colour-science.org/): the 1931 2° observer at
+1 nm from 360 to 830 nm, and D65 at 5 nm. The test suite holds the package to
+reference values colour-science computes, by `tools/generate.py`, which is also
+what writes `src/data.ts`: blackbody chromaticities from 1000 K to 20000 K to
+2×10⁻⁶ in xy, reflectances under D65 to 10⁻⁶ in XYZ, and the published D65 and
+A white points to 10⁻⁴.
+
+What this is not: a colour-appearance model, a chromatic adaptation transform
+or a wide-gamut pipeline. Output is sRGB, D65 white, for a screen.
+
+See [API.md](API.md) for every function.
+
+## Licence
+
+PolyForm Noncommercial 1.0.0. See `LICENSE` and `NOTICE`.

package/dist/data.d.ts

@@ -0,0 +1,15 @@
+export type Matrix = readonly (readonly [number, number, number])[];
+export declare const CMF_START = 360;
+export declare const CMF_STEP = 1;
+export declare const CMF_X: readonly number[];
+export declare const CMF_Y: readonly number[];
+export declare const CMF_Z: readonly number[];
+export declare const D65_START = 300;
+export declare const D65_STEP = 5;
+export declare const D65_VALUES: readonly number[];
+export declare const XYZ_TO_LINEAR_SRGB: Matrix;
+export declare const LINEAR_SRGB_TO_XYZ: Matrix;
+export declare const OKLAB_M1: Matrix;
+export declare const OKLAB_M1_INV: Matrix;
+export declare const OKLAB_M2: Matrix;
+export declare const OKLAB_M2_INV: Matrix;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './spectrum.js';