{
diff --git a/viewer/src/composite-color.ts b/viewer/src/composite-color.ts
new file mode 100644
index 0000000..53d7f9b
--- /dev/null
+++ b/viewer/src/composite-color.ts
@@ -0,0 +1,93 @@
+import { Color, SRGBColorSpace } from "three";
+import type { RGB } from "./color";
+import { channelLabel, type SceneFrame } from "./scene";
+import {
+ normalizeScalar,
+ resolveScalarRange,
+ type ResolvedScalarRange,
+ type ScalarRangeConfig,
+} from "./scalar-range";
+
+export const COMPOSITE_NEUTRAL: RGB = [0.55, 0.6, 0.58];
+export interface CompositeChannelConfig {
+ readonly index: number;
+ readonly enabled: boolean;
+ /** A six-digit CSS hexadecimal color in sRGB display space. */
+ readonly tint: string;
+ readonly range: ScalarRangeConfig;
+}
+export interface CompositeChannelLegend {
+ readonly index: number;
+ readonly label: string;
+ readonly tint: string;
+ readonly range: ResolvedScalarRange;
+}
+
+export function validateTint(tint: string): void {
+ if (!/^#[0-9a-fA-F]{6}$/.test(tint))
+ throw new RangeError(
+ "Use a six-digit hexadecimal tint, for example #ff0000.",
+ );
+}
+
+/** Return sRGB display colors, as required by ColonyViewer.setCellColors(). */
+export function mapCompositeSpecies(
+ frame: SceneFrame,
+ configuration: readonly CompositeChannelConfig[],
+): { colors: readonly RGB[]; channels: readonly CompositeChannelLegend[] } {
+ const seen = new Set();
+ const active = configuration.filter((channel) => channel.enabled);
+ for (const channel of active) {
+ if (
+ !Number.isSafeInteger(channel.index) ||
+ channel.index < 0 ||
+ channel.index >= frame.speciesCount
+ )
+ throw new RangeError(`species channel ${channel.index} is out of range`);
+ if (seen.has(channel.index))
+ throw new RangeError(`duplicate species channel ${channel.index}`);
+ seen.add(channel.index);
+ validateTint(channel.tint);
+ }
+ // Canonical summation order makes results bitwise independent of UI order.
+ const resolved = active
+ .toSorted((a, b) => a.index - b.index)
+ .map((channel) => ({
+ channel,
+ tint: new Color(channel.tint), // Three.js decodes CSS sRGB into linear RGB.
+ range: resolveScalarRange(
+ frame.cells.map((cell) => cell.species[channel.index] ?? 0),
+ channel.range,
+ ),
+ }));
+ const colors: RGB[] = frame.cells.map((cell) => {
+ if (resolved.length === 0) return COMPOSITE_NEUTRAL;
+ const linear = new Color(0, 0, 0);
+ for (const { channel, tint, range } of resolved) {
+ const intensity = normalizeScalar(
+ cell.species[channel.index] ?? 0,
+ range,
+ );
+ linear.r += intensity * tint.r;
+ linear.g += intensity * tint.g;
+ linear.b += intensity * tint.b;
+ }
+ linear.r = Math.min(1, linear.r);
+ linear.g = Math.min(1, linear.g);
+ linear.b = Math.min(1, linear.b);
+ const display = linear.getRGB({ r: 0, g: 0, b: 0 }, SRGBColorSpace);
+ return [display.r, display.g, display.b];
+ });
+ const byIndex = new Map(
+ resolved.map((value) => [value.channel.index, value]),
+ );
+ return {
+ colors,
+ channels: active.map(({ index, tint }) => ({
+ index,
+ tint,
+ label: channelLabel(frame, "species", index),
+ range: byIndex.get(index)!.range,
+ })),
+ };
+}
diff --git a/viewer/src/composite-controls.ts b/viewer/src/composite-controls.ts
new file mode 100644
index 0000000..7f5885b
--- /dev/null
+++ b/viewer/src/composite-controls.ts
@@ -0,0 +1,190 @@
+import type { CompositeChannelLegend } from "./composite-color";
+import { CompositeSpeciesState } from "./composite-state";
+import { ScalarRangeControls } from "./scalar-range-controls";
+import { DatasetScalarRanges, resolveScalarRange } from "./scalar-range";
+import { channelLabel, type SceneFrame } from "./scene";
+
+interface ChannelRow {
+ root: HTMLElement;
+ label: HTMLElement;
+ enabled: HTMLInputElement;
+ swatch: HTMLElement;
+ tint: HTMLInputElement;
+ tintError: HTMLElement;
+ range: ScalarRangeControls;
+ up: HTMLButtonElement;
+ down: HTMLButtonElement;
+}
+
+export class CompositeSpeciesControls {
+ private readonly rows = new Map();
+ private readonly list = document.createElement("div");
+ private readonly legend = document.createElement("div");
+ private visibleOrder = "";
+ private count = 0;
+
+ public constructor(
+ root: HTMLElement,
+ private readonly state: CompositeSpeciesState,
+ private readonly ranges: DatasetScalarRanges,
+ private readonly onChange: () => void,
+ private readonly formatNumber: (value: number) => string,
+ ) {
+ this.legend.id = "composite-legend";
+ this.legend.className = "composite-legend";
+ this.legend.setAttribute("aria-label", "Composite channel legend");
+ root.append(this.list, this.legend);
+ }
+
+ public beginDataset(): void {
+ this.rows.clear();
+ this.list.replaceChildren();
+ this.legend.replaceChildren();
+ this.visibleOrder = "";
+ }
+
+ public update(
+ frame: SceneFrame,
+ channels: readonly CompositeChannelLegend[],
+ ): void {
+ this.count = frame.speciesCount;
+ const indices = this.state.indices(this.count);
+ for (const [position, index] of indices.entries()) {
+ let row = this.rows.get(index);
+ if (row === undefined) {
+ row = this.createRow(index);
+ this.rows.set(index, row);
+ }
+ const name = channelLabel(frame, "species", index);
+ row.label.textContent = name;
+ row.root.setAttribute("aria-label", `${name} composite channel`);
+ row.enabled.setAttribute("aria-label", `Enable ${name}`);
+ row.up.setAttribute("aria-label", `Move ${name} up`);
+ row.down.setAttribute("aria-label", `Move ${name} down`);
+ row.up.disabled = position === 0;
+ row.down.disabled = position === indices.length - 1;
+ const preference = this.state.get(index);
+ row.enabled.checked = preference.enabled;
+ row.swatch.style.backgroundColor = preference.tint;
+ row.range.bind(
+ index,
+ resolveScalarRange(
+ frame.cells.map((cell) => cell.species[index] ?? 0),
+ this.ranges.get("species", index),
+ ),
+ );
+ }
+ const order = indices.join(",");
+ if (order !== this.visibleOrder) {
+ this.list.replaceChildren(
+ ...indices.map((index) => this.rows.get(index)!.root),
+ );
+ this.visibleOrder = order;
+ }
+ this.legend.replaceChildren();
+ if (channels.length === 0) {
+ this.legend.textContent = "No channels active. Cells use neutral gray.";
+ return;
+ }
+ for (const channel of channels) {
+ const item = document.createElement("div");
+ item.className = "composite-legend-channel";
+ const swatch = document.createElement("span");
+ swatch.className = "composite-swatch";
+ swatch.style.backgroundColor = channel.tint;
+ swatch.setAttribute("aria-hidden", "true");
+ const description = document.createElement("span");
+ const bounds =
+ channel.range.minimum === null || channel.range.maximum === null
+ ? "no values"
+ : `${this.formatNumber(channel.range.minimum)} to ${this.formatNumber(channel.range.maximum)}`;
+ description.textContent = `${channel.label} · ${channel.tint} · ${channel.range.mode === "fixed" ? "Fixed" : "Automatic"} ${bounds}${channel.range.count === 0 && channel.range.minimum !== null ? " (no values)" : ""}`;
+ item.append(swatch, description);
+ this.legend.append(item);
+ }
+ }
+
+ private createRow(index: number): ChannelRow {
+ const root = document.createElement("div");
+ root.className = "composite-channel";
+ root.dataset.channel = String(index);
+ root.setAttribute("role", "group");
+ const heading = document.createElement("label");
+ heading.className = "composite-channel-heading";
+ const enabled = document.createElement("input");
+ enabled.type = "checkbox";
+ const swatch = document.createElement("span");
+ swatch.className = "composite-swatch";
+ swatch.setAttribute("aria-hidden", "true");
+ const label = document.createElement("span");
+ heading.append(enabled, swatch, label);
+ const details = document.createElement("details");
+ const summary = document.createElement("summary");
+ summary.textContent = "Display settings";
+ const tintForm = document.createElement("form");
+ tintForm.className = "composite-tint-form";
+ const tintLabel = document.createElement("label");
+ tintLabel.className = "field";
+ tintLabel.textContent = "Tint (sRGB hex)";
+ const tint = document.createElement("input");
+ tint.type = "text";
+ tint.value = this.state.get(index).tint;
+ tint.spellcheck = false;
+ tint.setAttribute("aria-label", "Channel tint");
+ tintLabel.append(tint);
+ const tintApply = document.createElement("button");
+ tintApply.className = "button button-secondary";
+ tintApply.type = "submit";
+ tintApply.textContent = "Apply tint";
+ const tintError = document.createElement("p");
+ tintError.className = "scalar-range-message";
+ tintError.setAttribute("role", "status");
+ tintForm.append(tintLabel, tintApply, tintError);
+ const rangeRoot = document.createElement("div");
+ rangeRoot.id = `composite-range-${index}`;
+ const range = new ScalarRangeControls(
+ rangeRoot,
+ this.ranges,
+ "species",
+ this.onChange,
+ );
+ const order = document.createElement("div");
+ order.className = "composite-channel-order";
+ const moveButton = (direction: -1 | 1): HTMLButtonElement => {
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = "button button-secondary";
+ button.textContent = direction === -1 ? "Move up" : "Move down";
+ button.addEventListener("click", () => {
+ this.state.move(index, direction, this.count);
+ this.onChange();
+ this.rows.get(index)?.[direction === -1 ? "down" : "up"].focus();
+ });
+ order.append(button);
+ return button;
+ };
+ const up = moveButton(-1);
+ const down = moveButton(1);
+ details.append(summary, tintForm, rangeRoot, order);
+ root.append(heading, details);
+ enabled.addEventListener("change", () => {
+ this.state.setEnabled(index, enabled.checked);
+ this.onChange();
+ });
+ tintForm.addEventListener("submit", (event) => {
+ event.preventDefault();
+ try {
+ this.state.setTint(index, tint.value.trim());
+ tint.value = this.state.get(index).tint;
+ tint.removeAttribute("aria-invalid");
+ tintError.textContent = "";
+ this.onChange();
+ } catch (error) {
+ tint.setAttribute("aria-invalid", "true");
+ tintError.textContent =
+ error instanceof Error ? error.message : String(error);
+ }
+ });
+ return { root, label, enabled, swatch, tint, tintError, range, up, down };
+ }
+}
diff --git a/viewer/src/composite-state.ts b/viewer/src/composite-state.ts
new file mode 100644
index 0000000..04317f0
--- /dev/null
+++ b/viewer/src/composite-state.ts
@@ -0,0 +1,66 @@
+import { validateTint, type CompositeChannelConfig } from "./composite-color";
+import type { DatasetScalarRanges } from "./scalar-range";
+
+const TINTS = [
+ "#ff0000",
+ "#00ff00",
+ "#0080ff",
+ "#ff00ff",
+ "#00ffff",
+ "#ff8000",
+] as const;
+export interface CompositeChannelPreference {
+ readonly enabled: boolean;
+ readonly tint: string;
+}
+
+export class CompositeSpeciesState {
+ private readonly channels = new Map();
+ private order: number[] = [];
+ public beginDataset(): void {
+ this.channels.clear();
+ this.order = [];
+ }
+ public get(index: number): CompositeChannelPreference {
+ if (!Number.isSafeInteger(index) || index < 0)
+ throw new RangeError(
+ "Channel index must be a non-negative safe integer.",
+ );
+ return (
+ this.channels.get(index) ?? {
+ enabled: index < 2,
+ tint: TINTS[index % TINTS.length]!,
+ }
+ );
+ }
+ public setEnabled(index: number, enabled: boolean): void {
+ this.channels.set(index, { ...this.get(index), enabled });
+ }
+ public setTint(index: number, tint: string): void {
+ validateTint(tint);
+ this.channels.set(index, { ...this.get(index), tint: tint.toLowerCase() });
+ }
+ public indices(count: number): readonly number[] {
+ for (let index = 0; index < count; index += 1)
+ if (!this.order.includes(index)) this.order.push(index);
+ return this.order.filter((index) => index < count);
+ }
+ public move(index: number, direction: -1 | 1, count: number): void {
+ const visible = this.indices(count);
+ const neighbor = visible[visible.indexOf(index) + direction];
+ if (neighbor === undefined || !visible.includes(index)) return;
+ const from = this.order.indexOf(index);
+ const to = this.order.indexOf(neighbor);
+ [this.order[from], this.order[to]] = [neighbor, index];
+ }
+ public configuration(
+ count: number,
+ ranges: DatasetScalarRanges,
+ ): readonly CompositeChannelConfig[] {
+ return this.indices(count).map((index) => ({
+ index,
+ ...this.get(index),
+ range: ranges.get("species", index),
+ }));
+ }
+}
diff --git a/viewer/src/main.ts b/viewer/src/main.ts
index c983450..76eaf81 100644
--- a/viewer/src/main.ts
+++ b/viewer/src/main.ts
@@ -8,6 +8,8 @@ import {
} from "./scalar-range";
import { ScalarRangeControls } from "./scalar-range-controls";
import { ColonyViewer } from "./colony-viewer";
+import { CompositeSpeciesState } from "./composite-state";
+import { CompositeSpeciesControls } from "./composite-controls";
import { signalSlice, sliceDimension, type SliceAxis } from "./grid";
import { ReplayControls } from "./replay-controls";
import { DatasetPresentationState } from "./presentation-state";
@@ -88,6 +90,15 @@ let liveCheckpointEnabled = false;
let liveConnection: LiveConnection | null = null;
const presentation = new DatasetPresentationState();
const scalarRanges = new DatasetScalarRanges();
+const compositeState = new CompositeSpeciesState();
+const compositeRoot = required("composite-species");
+const compositeControls = new CompositeSpeciesControls(
+ compositeRoot,
+ compositeState,
+ scalarRanges,
+ updateColors,
+ formatNumber,
+);
const speciesRangeRoot = required("species-range");
const speciesRangeControls = new ScalarRangeControls(
speciesRangeRoot,
@@ -165,12 +176,19 @@ function updateColors(): void {
const mode = colorMode.value as ColorMode;
speciesField.hidden = mode !== "species";
speciesRangeRoot.hidden = mode !== "species";
+ compositeRoot.hidden = mode !== "composite";
const mapping = mapCellColors(frame, {
mode,
speciesIndex: selectedInteger(speciesChannel),
range: scalarRanges.get("species", selectedInteger(speciesChannel)),
+ compositeChannels: compositeState.configuration(
+ frame.speciesCount,
+ scalarRanges,
+ ),
});
viewer.setCellColors(mapping.colors);
+ if (mapping.composite !== undefined)
+ compositeControls.update(frame, mapping.composite);
colorLegend.hidden = mapping.range === null;
if (mapping.range !== null) {
if (mode === "species")
@@ -230,7 +248,11 @@ function updateSignal(): void {
signalRangeControls.bind(index, range);
viewer.setSignalSlice(signalVisible.checked ? value : null, config);
legend.hidden = false;
- required("signal-legend-title").textContent = `Signal ${index}`;
+ required("signal-legend-title").textContent = channelLabel(
+ frame,
+ "signals",
+ index,
+ );
required("signal-legend-min").textContent =
range.minimum === null ? "—" : formatNumber(range.minimum);
required("signal-legend-max").textContent =
@@ -300,6 +322,8 @@ function presentScene(
if (newDataset) {
presentation.beginDataset();
scalarRanges.beginDataset();
+ compositeState.beginDataset();
+ compositeControls.beginDataset();
speciesRangeControls.beginDataset();
signalRangeControls.beginDataset();
viewer.beginDataset();
diff --git a/viewer/src/scalar-range-controls.ts b/viewer/src/scalar-range-controls.ts
index 3e90aa2..ddee815 100644
--- a/viewer/src/scalar-range-controls.ts
+++ b/viewer/src/scalar-range-controls.ts
@@ -4,6 +4,7 @@ import {
suggestedFixedRange,
type ResolvedScalarRange,
type ScalarChannelKind,
+ type ScalarRangeConfig,
} from "./scalar-range";
/** Reusable keyboard-accessible editor; draft text never changes the active range. */
@@ -14,6 +15,7 @@ export class ScalarRangeControls {
private readonly maximum: HTMLInputElement;
private readonly message: HTMLElement;
private channel: number | null = null;
+ private active: ScalarRangeConfig | null = null;
private resolved: ResolvedScalarRange | null = null;
public constructor(
@@ -105,12 +107,16 @@ export class ScalarRangeControls {
public beginDataset(): void {
this.channel = null;
+ this.active = null;
this.resolved = null;
}
public bind(channel: number, resolved: ResolvedScalarRange): void {
this.resolved = resolved;
- if (this.channel !== channel) {
+ if (
+ this.channel !== channel ||
+ this.active !== this.ranges.get(this.kind, channel)
+ ) {
this.channel = channel;
this.syncFields();
}
@@ -119,6 +125,7 @@ export class ScalarRangeControls {
private syncFields(): void {
if (this.channel === null || this.resolved === null) return;
const active = this.ranges.get(this.kind, this.channel);
+ this.active = active;
const fixed =
this.ranges.lastFixed(this.kind, this.channel) ??
suggestedFixedRange(this.resolved);
diff --git a/viewer/src/style.css b/viewer/src/style.css
index 19fe657..675b270 100644
--- a/viewer/src/style.css
+++ b/viewer/src/style.css
@@ -722,6 +722,133 @@ dd {
}
}
+.device-visibility {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.75rem;
+ margin: 0.75rem 0;
+ color: var(--muted);
+ font-size: 0.75rem;
+}
+
+.device-visibility input {
+ width: 1rem;
+ height: 1rem;
+ margin: 0;
+ accent-color: var(--accent);
+}
+
+.scalar-range-fields {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+ gap: 8px;
+}
+
+.scalar-range-fields input {
+ width: 100%;
+ min-width: 0;
+ border: 1px solid var(--line-strong);
+ border-radius: 6px;
+ padding: 7px 8px;
+ background: var(--bg);
+ color: var(--text);
+ font-size: 12px;
+}
+
+.scalar-range-fields input[aria-invalid="true"] {
+ border-color: var(--danger);
+}
+
+.scalar-range-fields > button,
+.scalar-range-message {
+ grid-column: 1 / -1;
+}
+
+.scalar-range-message,
+.legend-caption {
+ margin: 0;
+ color: var(--muted);
+ font-size: 11px;
+ line-height: 1.5;
+}
+
+.scalar-range-message[data-error="true"] {
+ color: var(--danger);
+}
+
+.legend-caption {
+ margin-block: 6px;
+}
+
+.composite-channel {
+ margin-top: 12px;
+ border-top: 1px solid var(--line);
+ padding-top: 12px;
+}
+
+.composite-channel-heading,
+.composite-legend-channel {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-size: 12px;
+ overflow-wrap: anywhere;
+}
+
+.composite-channel-heading input {
+ accent-color: var(--accent);
+}
+
+.composite-swatch {
+ flex: 0 0 12px;
+ height: 12px;
+ border-radius: 3px;
+ border: 1px solid var(--line-strong);
+}
+
+.composite-channel summary {
+ cursor: pointer;
+ margin-block: 12px;
+ color: var(--muted);
+ font-size: 11px;
+}
+
+.composite-tint-form input {
+ width: 100%;
+ min-width: 0;
+ border: 1px solid var(--line-strong);
+ border-radius: 6px;
+ padding: 7px 8px;
+ background: var(--bg);
+ color: var(--text);
+}
+
+.composite-tint-form input[aria-invalid="true"] {
+ border-color: var(--danger);
+}
+
+.composite-channel-order {
+ display: flex;
+ gap: 8px;
+ margin-top: 12px;
+}
+
+.composite-channel-order button {
+ padding-inline: 8px;
+ font-size: 11px;
+}
+
+.composite-legend {
+ margin-top: 16px;
+ color: var(--muted);
+ font-size: 12px;
+}
+
+.composite-legend-channel + .composite-legend-channel {
+ margin-top: 8px;
+}
+
.replay-transport {
position: absolute;
left: 50%;
@@ -783,62 +910,3 @@ dd {
.replay-message[data-kind="error"] {
color: var(--danger);
}
-
-.scalar-range-fields {
- display: grid;
- grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
- gap: 8px;
-}
-
-.scalar-range-fields input {
- width: 100%;
- min-width: 0;
- border: 1px solid var(--line-strong);
- border-radius: 6px;
- padding: 7px 8px;
- background: var(--bg);
- color: var(--text);
- font-size: 12px;
-}
-
-.scalar-range-fields input[aria-invalid="true"] {
- border-color: var(--danger);
-}
-
-.scalar-range-fields > button,
-.scalar-range-message {
- grid-column: 1 / -1;
-}
-
-.scalar-range-message,
-.legend-caption {
- margin: 0;
- color: var(--muted);
- font-size: 11px;
- line-height: 1.5;
-}
-
-.scalar-range-message[data-error="true"] {
- color: var(--danger);
-}
-
-.legend-caption {
- margin-block: 6px;
-}
-
-.device-visibility {
- display: flex;
- align-items: center;
- justify-content: space-between;
- gap: 0.75rem;
- margin: 0.75rem 0;
- color: var(--muted);
- font-size: 0.75rem;
-}
-
-.device-visibility input {
- width: 1rem;
- height: 1rem;
- margin: 0;
- accent-color: var(--accent);
-}
diff --git a/viewer/tests/composite.test.ts b/viewer/tests/composite.test.ts
new file mode 100644
index 0000000..f05946c
--- /dev/null
+++ b/viewer/tests/composite.test.ts
@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import { mapCellColors } from "../src/color";
+import {
+ COMPOSITE_NEUTRAL,
+ mapCompositeSpecies,
+ type CompositeChannelConfig,
+} from "../src/composite-color";
+import { CompositeSpeciesState } from "../src/composite-state";
+import { DatasetScalarRanges } from "../src/scalar-range";
+import type { SceneFrame } from "../src/scene";
+
+const frame: SceneFrame = {
+ time: 0,
+ backend: {
+ kind: "cpu",
+ name: "CPU",
+ device: "host",
+ deviceIndex: 0,
+ native: true,
+ },
+ speciesCount: 2,
+ channelMetadata: { species: ["Red reporter", "Green reporter"], signals: [] },
+ cells: [
+ [1, 0],
+ [0, 1],
+ [1, 1],
+ [0, 0],
+ ].map((species, slot) => ({
+ id: String(slot + 1),
+ parentId: null,
+ slot,
+ position: [slot, 0, 0],
+ direction: [1, 0, 0],
+ length: 2,
+ radius: 0.5,
+ growthRate: 0,
+ fixed: false,
+ cellType: 0,
+ species,
+ })),
+ constraints: { planes: [], spheres: [], boxes: [], cylinders: [] },
+ signalGrid: null,
+};
+const channels: readonly CompositeChannelConfig[] = [
+ {
+ index: 0,
+ enabled: true,
+ tint: "#ff0000",
+ range: { mode: "fixed", minimum: 0, maximum: 1 },
+ },
+ {
+ index: 1,
+ enabled: true,
+ tint: "#00ff00",
+ range: { mode: "fixed", minimum: 0, maximum: 1 },
+ },
+];
+
+function expectColor(
+ actual: readonly number[] | undefined,
+ expected: readonly number[],
+ tolerance = 1e-10,
+): void {
+ expect(actual).toHaveLength(3);
+ expected.forEach((value, index) =>
+ expect(Math.abs(actual![index]! - value)).toBeLessThanOrEqual(tolerance),
+ );
+}
+
+describe("composite species blending", () => {
+ it("distinguishes red, green, coexpression yellow and zero expression", () => {
+ const mapping = mapCompositeSpecies(frame, channels);
+ [
+ [1, 0, 0],
+ [0, 1, 0],
+ [1, 1, 0],
+ [0, 0, 0],
+ ].forEach((color, index) => expectColor(mapping.colors[index], color));
+ expect(mapping.channels.map((channel) => channel.label)).toEqual([
+ "Red reporter",
+ "Green reporter",
+ ]);
+ });
+ it("is exactly independent of channel order and disabling removes only that contribution", () => {
+ const expected = mapCompositeSpecies(frame, channels);
+ expect(mapCompositeSpecies(frame, [...channels].reverse()).colors).toEqual(
+ expected.colors,
+ );
+ const disabled = mapCompositeSpecies(
+ frame,
+ channels.map((channel) => ({ ...channel, enabled: channel.index === 0 })),
+ );
+ expectColor(disabled.colors[2], [1, 0, 0]);
+ expectColor(disabled.colors[1], [0, 0, 0]);
+ expect(disabled.channels).toHaveLength(1);
+ });
+ it("weights and adds in linear RGB, then encodes once for the existing renderer boundary", () => {
+ const half = {
+ ...frame,
+ cells: [{ ...frame.cells[0]!, species: [0.5, 0] }],
+ };
+ const color = mapCompositeSpecies(half, channels).colors[0];
+ // Three.js encodes with its 0.41666 exponent approximation.
+ expectColor(color, [0.7353569830524495, 0, 0], 1e-5);
+ const decode = (value: number) =>
+ value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+ expect(Math.abs(decode(color![0]) - 0.5)).toBeLessThan(1e-5);
+ const gray = mapCompositeSpecies(half, [
+ { ...channels[0]!, tint: "#808080" },
+ ]).colors[0]!;
+ for (const value of gray)
+ expect(Math.abs(decode(value) - 0.5 * decode(128 / 255))).toBeLessThan(
+ 1e-5,
+ );
+ });
+ it("clamps summed components after addition and clips concentrations without mutating values", () => {
+ const input = {
+ ...frame,
+ cells: [
+ { ...frame.cells[0]!, species: [-10, 40] },
+ { ...frame.cells[1]!, species: [40, 40] },
+ ],
+ };
+ const mapping = mapCompositeSpecies(
+ input,
+ channels.map((channel) => ({ ...channel, tint: "#ff0000" })),
+ );
+ expectColor(mapping.colors[0], [1, 0, 0]);
+ expectColor(mapping.colors[1], [1, 0, 0]);
+ expect(input.cells.map((cell) => cell.species)).toEqual([
+ [-10, 40],
+ [40, 40],
+ ]);
+ });
+ it("uses neutral gray when no channels are enabled and handles empty data", () => {
+ const mapping = mapCompositeSpecies(
+ frame,
+ channels.map((channel) => ({ ...channel, enabled: false })),
+ );
+ expect(mapping.colors).toEqual(frame.cells.map(() => COMPOSITE_NEUTRAL));
+ expect(mapping.channels).toEqual([]);
+ expect(
+ mapCompositeSpecies({ ...frame, cells: [] }, channels).colors,
+ ).toEqual([]);
+ });
+ it("uses the shared automatic constant midpoint and validates channel identity/tints", () => {
+ const constant = {
+ ...frame,
+ cells: [{ ...frame.cells[0]!, species: [7, 0] }],
+ };
+ expectColor(
+ mapCompositeSpecies(constant, [
+ { ...channels[0]!, range: { mode: "automatic" } },
+ ]).colors[0],
+ [0.7353569830524495, 0, 0],
+ 1e-5,
+ );
+ expect(() =>
+ mapCompositeSpecies(frame, [channels[0]!, channels[0]!]),
+ ).toThrow("duplicate");
+ expect(() =>
+ mapCompositeSpecies(frame, [{ ...channels[0]!, index: 20 }]),
+ ).toThrow("out of range");
+ expect(() =>
+ mapCompositeSpecies(frame, [{ ...channels[0]!, tint: "red" }]),
+ ).toThrow("six-digit");
+ });
+ it("integrates with existing color modes without changing cell identity", () => {
+ const mapped = mapCellColors(frame, {
+ mode: "composite",
+ speciesIndex: 0,
+ compositeChannels: channels,
+ });
+ expect(mapped.colors).toEqual(mapCompositeSpecies(frame, channels).colors);
+ expect(mapped.composite).toHaveLength(2);
+ expect(frame.cells.map((cell) => cell.id)).toEqual(["1", "2", "3", "4"]);
+ expect(
+ mapCellColors(frame, { mode: "species", speciesIndex: 0 }).title,
+ ).toBe("Red reporter");
+ });
+});
+
+describe("composite channel settings", () => {
+ it("preserves tint/range/enabled identity through reordering and temporarily missing channels", () => {
+ const state = new CompositeSpeciesState();
+ const ranges = new DatasetScalarRanges();
+ ranges.set("species", 0, { mode: "fixed", minimum: -2, maximum: 10 });
+ ranges.set("species", 1, { mode: "fixed", minimum: 1, maximum: 8 });
+ state.setTint(1, "#ABCDEF");
+ state.setEnabled(1, false);
+ state.move(1, -1, 2);
+ expect(state.indices(2)).toEqual([1, 0]);
+ expect(state.indices(0)).toEqual([]);
+ expect(state.configuration(2, ranges)).toEqual([
+ {
+ index: 1,
+ tint: "#abcdef",
+ enabled: false,
+ range: { mode: "fixed", minimum: 1, maximum: 8 },
+ },
+ {
+ index: 0,
+ tint: "#ff0000",
+ enabled: true,
+ range: { mode: "fixed", minimum: -2, maximum: 10 },
+ },
+ ]);
+ state.setEnabled(1, true);
+ expect(state.configuration(2, ranges)[0]?.range).toMatchObject({
+ minimum: 1,
+ });
+ expect(() => state.setTint(1, "invalid")).toThrow();
+ expect(state.get(1).tint).toBe("#abcdef");
+ state.beginDataset();
+ ranges.beginDataset();
+ expect(state.indices(2)).toEqual([0, 1]);
+ expect(state.get(1)).toEqual({ enabled: true, tint: "#00ff00" });
+ expect(state.configuration(2, ranges)[0]?.range).toEqual({
+ mode: "automatic",
+ });
+ });
+});