@jbrowse/core 5.0.0-beta.4 → 5.0.0-beta.8

package/esm/util/markEncoding.js

@@ -0,0 +1,436 @@
+import { GLYPH_DISC } from '@jbrowse/render-core/shaders/pointMarkConsts';
+import { categoricalPalette, categoricalValueColor } from '../ui/colors.js';
+import { cssColorToABGR, cssColorToRgba, packAbgr } from './colorBits.js';
+import { VIRIDIS_STOPS, buildColorRampLut } from './colorRamp.js';
+import Flatbush from './flatbush/index.js';
+import { GLYPH_CODES, GLYPH_NAMES } from './glyphNames.js';
+import { isJexl, stringToJexlExpression } from './jexlStrings.js';
+import { buildJexlContext } from './simpleFeature.js';
+export const DEFAULT_MARK_COLOR = '#0068d1';
+// What a feature paints when its colour field is missing or a `jexl:` colour
+// yields a non-string: visible, so a misconfiguration surfaces rather than
+// vanishing.
+const FALLBACK_COLOR = cssColorToABGR('#808080');
+/**
+ * #api
+ * The key row a feature with nothing in a categorical field lands on, so the
+ * legend says why a mark is grey, or a disc, rather than listing a blank
+ * value.
+ */
+export const NO_VALUE_LABEL = '(no value)';
+function jexlExpression(ref, jexl) {
+    if (!jexl) {
+        throw new Error(`a jexl: channel needs a jexl instance (${ref})`);
+    }
+    return stringToJexlExpression(ref, jexl);
+}
+function fieldReader(ref, jexl) {
+    if (typeof ref === 'function') {
+        return ref;
+    }
+    if (isJexl(ref)) {
+        const expr = jexlExpression(ref, jexl);
+        return feature => expr.eval(buildJexlContext({ feature }));
+    }
+    return feature => feature.get(ref);
+}
+/**
+ * #api
+ * The field a `y` declaration reads, whichever of its two forms it is
+ * written in.
+ */
+export function valueField(y) {
+    return typeof y === 'string' ? y : y.field;
+}
+function isGlyphName(glyph) {
+    return glyph in GLYPH_CODES;
+}
+function glyphReader(glyph, jexl) {
+    if (glyph === undefined) {
+        return () => GLYPH_DISC;
+    }
+    if (typeof glyph === 'function') {
+        return glyph;
+    }
+    if (isGlyphName(glyph)) {
+        const code = GLYPH_CODES[glyph];
+        return () => code;
+    }
+    const expr = jexlExpression(glyph, jexl);
+    return feature => {
+        const v = expr.eval(buildJexlContext({ feature }));
+        return typeof v === 'string' && isGlyphName(v) ? GLYPH_CODES[v] : GLYPH_DISC;
+    };
+}
+function rampStops(ramp) {
+    if (ramp === undefined || ramp === 'viridis') {
+        return VIRIDIS_STOPS;
+    }
+    return ramp.map(c => cssColorToRgba(c));
+}
+function lutColorAt(lut, t) {
+    const entries = lut.length / 4;
+    const i = Math.min(entries - 1, Math.max(0, Math.round(t * (entries - 1))));
+    const o = i * 4;
+    return packAbgr(lut[o], lut[o + 1], lut[o + 2], lut[o + 3]);
+}
+// The `[0, 1]` fraction a value sits at in the domain: the scale half of the
+// y-channel split (ADR-097), spelled once here for colour. The log arm floors
+// at the domain's own minimum so a domain below 1 still spreads.
+function normalizer(scale, domain) {
+    const [min, max] = domain;
+    if (scale === 'log') {
+        const floorV = min > 0 ? min : 1;
+        const logMin = Math.log2(floorV);
+        const logRange = Math.log2(Math.max(max, floorV)) - logMin;
+        return (v) => logRange <= 0
+            ? 0
+            : Math.min(1, Math.max(0, (Math.log2(Math.max(v, floorV)) - logMin) / logRange));
+    }
+    const range = max - min;
+    return (v) => range <= 0 ? 0 : Math.min(1, Math.max(0, (v - min) / range));
+}
+function categoryOrder(seen, domain) {
+    const listed = (domain ?? []).map(String);
+    const rest = [...seen.keys()].filter(k => !listed.includes(k));
+    const numeric = rest.every(k => k !== '' && Number.isFinite(Number(k)));
+    rest.sort(numeric ? (a, b) => Number(a) - Number(b) : (a, b) => a.localeCompare(b));
+    return [...listed, ...rest];
+}
+// The categorical arm `color` and `glyph` share: the walk records which
+// distinct value each admitted instance carried, and `resolve` hands every
+// value its range entry once the region's table is known. A listed domain
+// is the author's order and walks the range; without one the entry derives
+// from the value itself, so two regions that met different value sets still
+// agree on every value they share.
+function categoricalChannel(read, n) {
+    const categories = new Map();
+    const indexOf = new Int32Array(n);
+    return {
+        indexOf,
+        collect(f, at) {
+            const raw = read(f);
+            if (raw === undefined || raw === null || raw === '') {
+                indexOf[at] = -1;
+                return;
+            }
+            const label = String(raw);
+            let index = categories.get(label);
+            if (index === undefined) {
+                index = categories.size;
+                categories.set(label, index);
+            }
+            indexOf[at] = index;
+        },
+        resolve(domain, range) {
+            const ofIndex = Array.from({ length: categories.size });
+            const entries = [];
+            categoryOrder(categories, domain).forEach((label, slot) => {
+                const value = domain
+                    ? range[slot % range.length]
+                    : categoricalValueColor(label, range);
+                const index = categories.get(label);
+                if (index !== undefined) {
+                    ofIndex[index] = value;
+                }
+                entries.push({ label, value });
+            });
+            return { ofIndex, entries };
+        },
+    };
+}
+function hasMissing(indexOf, count) {
+    for (let i = 0; i < count; i++) {
+        if (indexOf[i] < 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * #api
+ * Evaluate one encoding over a feature list into dense channel arrays for
+ * the lanes named, the scale table each scaled channel came from, the `y`
+ * extremes and — when `index` is among the lanes — a hit index.
+ *
+ * A feature whose `x`, `x2` or (declared and asked-for) `y` is not finite is
+ * skipped and counted in `skipped`, so every array stays index-aligned with
+ * the Flatbush. Pure: the RPC around it owns the adapter, the filters and the
+ * transferables.
+ */
+export function encodeFeatures(features, encoding, lanes, ctx = {}) {
+    const { jexl, report } = ctx;
+    const n = features.length;
+    const has = (lane) => lanes.includes(lane);
+    const readX = fieldReader(encoding.x ?? 'start', jexl);
+    const readX2 = fieldReader(encoding.x2 ?? 'end', jexl);
+    const { y: yEncoding } = encoding;
+    const readY = has('y') && yEncoding !== undefined
+        ? fieldReader(typeof yEncoding === 'object' ? valueField(yEncoding) : yEncoding, jexl)
+        : undefined;
+    const readRow = has('row') && encoding.row !== undefined
+        ? fieldReader(encoding.row, jexl)
+        : undefined;
+    const x = new Uint32Array(n);
+    const x2 = new Uint32Array(n);
+    const y = has('y') ? new Float32Array(n) : undefined;
+    const row = has('row') ? new Uint32Array(n) : undefined;
+    const glyph = has('glyph') ? new Uint8Array(n) : undefined;
+    const featureIndex = new Uint32Array(n);
+    let yMin = Infinity;
+    let yMax = -Infinity;
+    let count = 0;
+    const colorEncoding = encoding.color ?? DEFAULT_MARK_COLOR;
+    const declaredScale = typeof colorEncoding === 'object' ? colorEncoding : undefined;
+    const rampEncoding = declaredScale && declaredScale.scale !== 'categorical'
+        ? declaredScale
+        : undefined;
+    // Which side of the wire a ramp resolves on is the caller's lane choice: a
+    // shape that reads the ramp itself names `colorValue` and gets the raw
+    // values, and the display unions the regions' extremes into one domain.
+    // Anything else names `color` and the walk resolves per region.
+    const colorValue = rampEncoding && has('colorValue') ? new Float32Array(n) : undefined;
+    const color = has('color') && !colorValue ? new Uint32Array(n) : undefined;
+    const wantColor = color !== undefined || colorValue !== undefined;
+    const scaled = wantColor ? declaredScale : undefined;
+    const readColor = !wantColor
+        ? undefined
+        : typeof colorEncoding === 'function'
+            ? colorEncoding
+            : scaled === undefined
+                ? colorEvaluator(colorEncoding, jexl)
+                : fieldReader(scaled.field, jexl);
+    // A scaled channel resolves after the walk, once the table is known: the
+    // category per admitted instance, or a ramp's raw value, kept here.
+    const colorCategories = scaled?.scale === 'categorical' && readColor
+        ? categoricalChannel(readColor, n)
+        : undefined;
+    const rampValues = scaled && scaled.scale !== 'categorical'
+        ? (colorValue ?? new Float32Array(n))
+        : undefined;
+    const { glyph: glyphEncoding } = encoding;
+    const glyphScaled = glyph && typeof glyphEncoding === 'object' ? glyphEncoding : undefined;
+    const glyphCategories = glyphScaled
+        ? categoricalChannel(fieldReader(glyphScaled.field, jexl), n)
+        : undefined;
+    const readGlyph = glyph
+        ? glyphReader(typeof glyphEncoding === 'object' ? undefined : glyphEncoding, jexl)
+        : undefined;
+    for (let i = 0; i < n; i++) {
+        report?.(i);
+        const f = features[i];
+        const xv = Number(readX(f));
+        const x2v = Number(readX2(f));
+        const yv = readY ? Number(readY(f)) : 0;
+        if (!Number.isFinite(xv) || !Number.isFinite(x2v) || !Number.isFinite(yv)) {
+            continue;
+        }
+        x[count] = xv;
+        x2[count] = x2v;
+        if (y) {
+            y[count] = yv;
+        }
+        if (readY) {
+            if (yv < yMin) {
+                yMin = yv;
+            }
+            if (yv > yMax) {
+                yMax = yv;
+            }
+        }
+        if (row && readRow) {
+            const rv = Number(readRow(f));
+            row[count] = rv > 0 ? rv : 0;
+        }
+        if (glyphCategories) {
+            glyphCategories.collect(f, count);
+        }
+        else if (glyph && readGlyph) {
+            glyph[count] = readGlyph(f);
+        }
+        featureIndex[count] = i;
+        if (colorCategories) {
+            colorCategories.collect(f, count);
+        }
+        else if (rampValues && readColor) {
+            rampValues[count] = Number(readColor(f));
+        }
+        else if (color && readColor) {
+            color[count] = readColor(f);
+        }
+        count++;
+    }
+    let scale;
+    if (scaled?.scale === 'categorical' && colorCategories && color) {
+        const palette = (scaled.palette ?? categoricalPalette).map(cssColorToABGR);
+        const { ofIndex, entries } = colorCategories.resolve(scaled.domain, palette);
+        const { indexOf } = colorCategories;
+        for (let i = 0; i < count; i++) {
+            const index = indexOf[i];
+            color[i] = index < 0 ? FALLBACK_COLOR : ofIndex[index];
+        }
+        scale = {
+            kind: 'categorical',
+            field: scaled.field,
+            entries: [
+                ...entries.map(e => ({ label: e.label, color: e.value })),
+                ...(hasMissing(indexOf, count)
+                    ? [{ label: NO_VALUE_LABEL, color: FALLBACK_COLOR }]
+                    : []),
+            ],
+        };
+    }
+    else if (scaled && scaled.scale !== 'categorical' && rampValues) {
+        const extent = finiteExtremes(rampValues, count);
+        const domain = scaled.domain ?? extent;
+        const lut = buildColorRampLut(rampStops(scaled.ramp));
+        if (color) {
+            const norm = normalizer(scaled.scale, domain);
+            for (let i = 0; i < count; i++) {
+                const v = rampValues[i];
+                color[i] = Number.isFinite(v)
+                    ? lutColorAt(lut, norm(v))
+                    : FALLBACK_COLOR;
+            }
+        }
+        scale = {
+            kind: 'ramp',
+            field: scaled.field,
+            scale: scaled.scale,
+            domain,
+            pinned: scaled.domain !== undefined,
+            extent,
+            lut,
+        };
+    }
+    let glyphScale;
+    if (glyphScaled && glyphCategories && glyph) {
+        const { ofIndex, entries } = glyphCategories.resolve(glyphScaled.domain, glyphScaled.range ?? GLYPH_NAMES);
+        const codeOfIndex = Uint8Array.from(ofIndex, name => GLYPH_CODES[name]);
+        const { indexOf } = glyphCategories;
+        for (let i = 0; i < count; i++) {
+            const index = indexOf[i];
+            glyph[i] = index < 0 ? GLYPH_DISC : codeOfIndex[index];
+        }
+        glyphScale = {
+            kind: 'glyph',
+            field: glyphScaled.field,
+            entries: [
+                ...entries.map(e => ({ label: e.label, glyph: e.value })),
+                ...(hasMissing(indexOf, count)
+                    ? [{ label: NO_VALUE_LABEL, glyph: 'disc' }]
+                    : []),
+            ],
+        };
+    }
+    let flatbushData;
+    if (has('index') && count > 0) {
+        const fb = new Flatbush(count, undefined, Float64Array);
+        for (let i = 0; i < count; i++) {
+            const v = y ? y[i] : 0;
+            fb.add(x[i], v, x2[i], v);
+        }
+        fb.finish();
+        flatbushData = fb.data;
+    }
+    const encoded = {
+        count,
+        skipped: n - count,
+        x: x.subarray(0, count),
+        x2: x2.subarray(0, count),
+        featureIndex: featureIndex.subarray(0, count),
+        yMin,
+        yMax,
+    };
+    if (y) {
+        encoded.y = y.subarray(0, count);
+    }
+    if (row) {
+        encoded.row = row.subarray(0, count);
+    }
+    if (color) {
+        encoded.color = color.subarray(0, count);
+    }
+    if (colorValue) {
+        encoded.colorValue = colorValue.subarray(0, count);
+    }
+    if (glyph) {
+        encoded.glyph = glyph.subarray(0, count);
+    }
+    if (flatbushData) {
+        encoded.flatbushData = flatbushData;
+    }
+    if (scale) {
+        encoded.scale = scale;
+    }
+    if (glyphScale) {
+        encoded.glyphScale = glyphScale;
+    }
+    return encoded;
+}
+function finiteExtremes(values, count) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < count; i++) {
+        const v = values[i];
+        if (Number.isFinite(v)) {
+            if (v < min) {
+                min = v;
+            }
+            if (v > max) {
+                max = v;
+            }
+        }
+    }
+    return min === Infinity ? [0, 1] : [min, max];
+}
+/**
+ * #api
+ * A CSS colour or `jexl:` colour expression as a per-feature packed ABGR —
+ * the unscaled arm of {@link ColorEncoding}, on its own for a display that
+ * carries a plain `color` slot.
+ */
+export function colorEvaluator(color, jexl) {
+    if (isJexl(color)) {
+        const expr = jexlExpression(color, jexl);
+        // A jexl colour answers from a handful of strings over a million
+        // features; parsing each answer once is a third of the arm's cost
+        // (packages/core/benches/encodeFeatures.bench.ts).
+        const packed = new Map();
+        return feature => {
+            const v = expr.eval(buildJexlContext({ feature }));
+            if (typeof v !== 'string') {
+                return FALLBACK_COLOR;
+            }
+            let c = packed.get(v);
+            if (c === undefined) {
+                c = cssColorToABGR(v);
+                packed.set(v, c);
+            }
+            return c;
+        };
+    }
+    const constant = cssColorToABGR(color);
+    return () => constant;
+}
+/**
+ * #api
+ * The buffers an {@link EncodedChannels} owns, for `rpcResult`'s transfer
+ * list.
+ */
+export function encodedChannelTransferables(c) {
+    const buffers = [
+        c.x.buffer,
+        c.x2.buffer,
+        c.featureIndex.buffer,
+    ];
+    for (const lane of [c.y, c.row, c.color, c.colorValue, c.glyph]) {
+        if (lane) {
+            buffers.push(lane.buffer);
+        }
+    }
+    if (c.flatbushData) {
+        buffers.push(c.flatbushData);
+    }
+    return buffers;
+}