react-cheminfo 0.28.0 → 0.30.0

package/src/ir/core/spectrumJcamp.ts

@@ -0,0 +1,178 @@
+/**
+ * Writing spectra back out as JCAMP-DX, so what was loaded can be taken away.
+ *
+ * JCAMP is the format to write rather than two columns of text because it says
+ * what its second column means: an infrared spectrum is read either as
+ * absorbance or as percent transmittance, the two are the same measurement
+ * turned inside out, and a bare column of numbers leaves whoever opens it next
+ * to guess which. `##YUNITS=` states it, and `ir-spectrum` reads it back and
+ * derives the other axis from it, so a spectrum written here returns carrying
+ * both.
+ *
+ * The points are written as an `##PEAK TABLE=` of explicit `x y` pairs rather
+ * than as a compressed `##XYDATA=` record. An XYDATA record states a first
+ * wavenumber and an increment and lets the reader rebuild the axis, which is
+ * exact only for an evenly sampled trace — and an interferogram transformed onto
+ * a wavenumber grid is evenly sampled only until somebody trims or splices it.
+ * Explicit pairs round trip whatever the spacing.
+ */
+
+import { fromJSON } from 'convert-to-jcamp';
+
+import type { IrMode, IrSpectrum } from './irSpectrum.ts';
+
+/** The extension a written spectrum is saved under. */
+export const JCAMP_EXTENSION = '.jdx';
+
+/** What a JCAMP-DX file is served as. */
+export const JCAMP_MIME_TYPE = 'chemical/x-jcamp-dx';
+
+/** How the technique is named when the file that was read named nothing. */
+export const DEFAULT_DATA_TYPE = 'INFRARED SPECTRUM';
+
+/**
+ * Write one spectrum as a JCAMP-DX block.
+ *
+ * The axis written is the one the instrument recorded wherever the file said
+ * which that was, and only otherwise the one being read. Writing what is on
+ * screen instead would export a spectrum that had been through a logarithm it
+ * was never measured with — and, where a band bottoms out at zero transmittance,
+ * an absorbance of infinity that no reader can take back.
+ * @param spectrum - The spectrum.
+ * @param mode - The axis being read, used when the file named none.
+ * @returns The block, `##TITLE=` through `##END=`.
+ */
+export function irSpectrumToJcamp(spectrum: IrSpectrum, mode: IrMode): string {
+  const written = spectrum.origin.recorded ?? mode;
+  const values =
+    written === 'absorbance' ? spectrum.absorbance : spectrum.transmittance;
+  return fromJSON(
+    { x: spectrum.wavenumber, y: values },
+    { info: infoRecords(spectrum, written), meta: metaRecords(spectrum) },
+  );
+}
+
+/**
+ * Write every spectrum of a list as one JCAMP-DX file.
+ *
+ * One file rather than one download per spectrum: a browser asked for six files
+ * in a row blocks all but the first, and a sample and its background are wanted
+ * back as the pair they were compared as. The blocks go inside a `LINK` block,
+ * which is what JCAMP has for a container and what the instruments that write a
+ * pair already use, so dropping the file back on the chart brings the whole list
+ * back.
+ *
+ * A list of one is written as that block alone: wrapping a single spectrum in a
+ * container gains nothing, and the file is then exactly what asking for that one
+ * spectrum would have written.
+ * @param spectra - The spectra, in the order the list holds them.
+ * @param mode - The axis being read, used for a spectrum whose file named none.
+ * @param title - What to call the file's own outer block.
+ * @returns The file.
+ */
+export function irSpectraToJcamp(
+  spectra: readonly IrSpectrum[],
+  mode: IrMode,
+  title = `${spectra.length} infrared spectra`,
+): string {
+  const only = spectra.length === 1 ? spectra[0] : undefined;
+  if (only !== undefined) return irSpectrumToJcamp(only, mode);
+
+  const blocks: string[] = [];
+  for (const spectrum of spectra) {
+    blocks.push(irSpectrumToJcamp(spectrum, mode));
+  }
+  return `##TITLE=${recordValue(title)}
+##JCAMP-DX=4.24
+##DATA TYPE=LINK
+##BLOCKS=${blocks.length}
+${blocks.join('\n')}
+##END=
+`;
+}
+
+/**
+ * The standard records of a block: what it is called, and what its axes are.
+ * @param spectrum - The spectrum.
+ * @param written - The axis being written.
+ * @returns The records, as `convert-to-jcamp` takes them.
+ */
+function infoRecords(
+  spectrum: IrSpectrum,
+  written: IrMode,
+): Record<string, string> {
+  return {
+    title: recordValue(spectrum.name),
+    // The technique as the file stated it, so a Raman spectrum that was opened
+    // here is not written back out claiming to be infrared.
+    dataType: technique(spectrum) ?? DEFAULT_DATA_TYPE,
+    xUnits: '1/CM',
+    // Spelled the way `ir-spectrum` reads it: it takes the axis to be
+    // transmittance when the label says `trans`, and to be a percentage rather
+    // than a fraction when it carries a `%`.
+    yUnits: written === 'absorbance' ? 'ABSORBANCE' : 'Transmittance (%)',
+  };
+}
+
+/**
+ * The `$`-prefixed records of a block: the acquisition, as the file stated it.
+ *
+ * The table's labels are the record names themselves — the reader lists whatever
+ * `##$` records a block carried, under their own names — so writing it back is a
+ * matter of putting the `$` in front again. `Technique` is the one row that is
+ * not a record of that bag: it is the block's `##DATA TYPE=`, and it goes back
+ * there rather than becoming a user-defined record of its own.
+ * @param spectrum - The spectrum.
+ * @returns The records, keyed without their `##$`.
+ */
+function metaRecords(spectrum: IrSpectrum): Record<string, string> {
+  const records: Record<string, string> = {};
+  const fields = spectrum.meta?.fields ?? [];
+  for (const field of fields) {
+    if (field.label === TECHNIQUE) continue;
+    records[recordKey(field.label)] = recordValue(field.value);
+  }
+  return records;
+}
+
+/** The row of the table that holds the block's own data type. */
+const TECHNIQUE = 'Technique';
+
+/**
+ * What the file said the spectrum was, if it said.
+ * @param spectrum - The spectrum.
+ * @returns The technique, or `undefined` when the file stated none.
+ */
+function technique(spectrum: IrSpectrum): string | undefined {
+  for (const field of spectrum.meta?.fields ?? []) {
+    if (field.label === TECHNIQUE) return recordValue(field.value);
+  }
+  return undefined;
+}
+
+/**
+ * A label put where a JCAMP record's name goes.
+ *
+ * A record name runs to the `=` and holds no whitespace, so a label that picked
+ * up a space on its way through some other tool would otherwise write a record
+ * whose name is its first word and whose value starts with the rest of it.
+ * @param label - The row's label.
+ * @returns It as a record name.
+ */
+function recordKey(label: string): string {
+  return label.replaceAll(/[\s=]+/g, '_');
+}
+
+/**
+ * A value put where a JCAMP record's value goes.
+ *
+ * A record is one line and `$$` opens a comment that runs to the end of it, so a
+ * value with a newline in it would otherwise either break the file in two or
+ * lose its tail. Both failures are silent on the way back in, which is why this
+ * is done to every value rather than to the ones known to be long.
+ * @param value - The value as it is held.
+ * @returns The value as one line, with no comment marker in it.
+ */
+function recordValue(value: string): string {
+  return value.replaceAll(/\s+/g, ' ').replaceAll('$$', '$').trim();
+}

package/src/ir/core/toIrSpectrum.ts

@@ -0,0 +1,102 @@
+/**
+ * Turning what a reader produced into what the viewer holds.
+ *
+ * A reader answers about a file and knows nothing about the session it is being
+ * read into — which spectra are already open, what colours they took, what this
+ * one should be called. That is the gap this closes, and it is the only place an
+ * identity or a colour is invented.
+ */
+
+import { nextSpectrumColor } from '../../chart/core/spectrumColor.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+
+/** What has to be decided for a loaded spectrum to become a held one. */
+export interface ToIrSpectrumOptions {
+  /**
+   * Identity, which every later edit and selection is keyed on.
+   * @default a fresh UUID
+   */
+  id?: string;
+  /**
+   * The colour to draw it in.
+   * @default the lowest hue not in `taken`
+   */
+  color?: string;
+  /**
+   * The colours the spectra already open have taken, so a new one is told apart
+   * from them. Ignored when `color` says outright.
+   * @default no colours taken
+   */
+  taken?: readonly string[];
+  /**
+   * What to call it, overriding the file's own title.
+   * @default the file's title, then its name, then `spectrum`
+   */
+  name?: string;
+  /**
+   * Whether it is drawn as soon as it is added.
+   * @default true
+   */
+  visible?: boolean;
+}
+
+/**
+ * Make a held spectrum out of a read one.
+ * @param loaded - What the reader produced.
+ * @param options - The identity, colour and name to give it.
+ * @returns The spectrum as the viewer holds it.
+ */
+export function toIrSpectrum(
+  loaded: LoadedIrSpectrum,
+  options: ToIrSpectrumOptions = {},
+): IrSpectrum {
+  const {
+    id = crypto.randomUUID(),
+    taken = [],
+    name,
+    visible = true,
+  } = options;
+  const color = options.color ?? nextSpectrumColor(taken);
+  return {
+    id,
+    name: name ?? loaded.name ?? loaded.origin.fileName ?? 'spectrum',
+    color,
+    wavenumber: loaded.wavenumber,
+    absorbance: loaded.absorbance,
+    transmittance: loaded.transmittance,
+    meta: loaded.meta,
+    origin: loaded.origin,
+    visible,
+  };
+}
+
+/**
+ * Make held spectra out of everything one file held.
+ *
+ * The colours are handed out one at a time against a growing list, so a file
+ * carrying a sample and its background gives two spectra of two colours rather
+ * than two of the same — `nextSpectrumColor` can only answer that if it is told
+ * what the previous call took.
+ * @param loaded - What the reader produced, in file order.
+ * @param options - The colours already taken, and whether the spectra are drawn.
+ * @returns The spectra, in the same order.
+ */
+export function toIrSpectra(
+  loaded: readonly LoadedIrSpectrum[],
+  options: Pick<ToIrSpectrumOptions, 'taken' | 'visible'> = {},
+): IrSpectrum[] {
+  const { taken = [], visible } = options;
+  const colors = [...taken];
+  const spectra: IrSpectrum[] = [];
+  for (const entry of loaded) {
+    const spectrum = toIrSpectrum(entry, {
+      taken: colors,
+      ...(visible === undefined ? {} : { visible }),
+    });
+    colors.push(spectrum.color);
+    spectra.push(spectrum);
+  }
+  return spectra;
+}

package/src/ir/ui/BandMarks.tsx

@@ -0,0 +1,166 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import {
+  CHART_COLORS,
+  CHART_FONT,
+  LABEL_HALO,
+} from '../../chart/core/chartTheme.ts';
+import type { AssignedBand } from '../core/assignBands.ts';
+import { BAND_MARK, planBandLabels } from '../core/bandLabelPlan.ts';
+import type { IrBand } from '../core/irBand.ts';
+import { sameIrBand } from '../core/irBand.ts';
+import { bandsPointDown } from '../core/irMode.ts';
+import type { IrMode } from '../core/irSpectrum.ts';
+
+export interface BandMarksProps {
+  /** The bands to mark, with whatever the table said about them. */
+  assigned: readonly AssignedBand[];
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+  /** The wavenumber axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /** The value axis as it is currently zoomed. */
+  yScale: ChartScale;
+  /** Which value axis is being drawn. */
+  mode: IrMode;
+  /**
+   * Whether each label names the assignment as well as the wavenumber.
+   * @default false
+   */
+  showAssignments?: boolean;
+  /**
+   * At most how many bands are named. Marks are drawn on all of them.
+   * @default 12
+   */
+  limit?: number;
+  /**
+   * The band the pointer has come to rest on, drawn larger, `null` for none.
+   * @default null
+   */
+  highlight?: IrBand | null;
+}
+
+/**
+ * A mark on every band, and a label on the ones there is room for.
+ *
+ * The mark reaches *away* from the label, into the band, because the clear space
+ * on the label's side is where the numbers are written and the mark is there to
+ * say which band they are about. So in transmittance both hang downwards from a
+ * dip and in absorbance both rise from a maximum, and the pair reads the same way
+ * up in either.
+ *
+ * A leader line is drawn only when a label had to be slid off its band to clear
+ * its neighbours — a leader from a label that is already directly above its band
+ * is a line saying what the position already said. A label slid too far is not
+ * drawn at all; the mark still says the band is there, which is the honest
+ * outcome, where a label hanging over a band it says nothing about is not.
+ * @param props - Component props.
+ * @returns The marks and labels, as SVG.
+ */
+export function BandMarks(props: BandMarksProps): ReactElement {
+  const {
+    assigned,
+    plot,
+    xScale,
+    yScale,
+    mode,
+    showAssignments = false,
+    limit = 12,
+    highlight = null,
+  } = props;
+
+  const plans = useMemo(
+    () =>
+      planBandLabels({
+        assigned,
+        plot,
+        xScale,
+        yScale,
+        mode,
+        showAssignments,
+        limit,
+      }),
+    [assigned, plot, xScale, yScale, mode, showAssignments, limit],
+  );
+
+  const down = bandsPointDown(mode);
+  const reach = down ? BAND_MARK : -BAND_MARK;
+
+  return (
+    <g pointerEvents="none">
+      {plans.map((plan) => {
+        const highlighted = sameIrBand(plan.band, highlight);
+        const dropped = !Number.isFinite(plan.labelX);
+        const firstBaseline = plan.baselines[0];
+        const slid = !dropped && Math.abs(plan.labelX - plan.tipX) > LEADER_AT;
+        return (
+          <g key={`${plan.band.spectrumId} ${plan.band.wavenumber}`}>
+            <line
+              x1={plan.tipX}
+              y1={plan.tipY}
+              x2={plan.tipX}
+              y2={plan.tipY + reach}
+              style={highlighted ? highlightMarkStyle : markStyle}
+              strokeWidth={highlighted ? 2 : 1}
+            />
+            {slid && firstBaseline !== undefined ? (
+              <line
+                x1={plan.tipX}
+                y1={plan.tipY + reach}
+                x2={plan.labelX}
+                y2={firstBaseline}
+                style={leaderStyle}
+              />
+            ) : null}
+            {dropped
+              ? null
+              : plan.lines.map((line, index) => (
+                  <text
+                    key={line}
+                    x={plan.labelX}
+                    y={plan.baselines[index]}
+                    textAnchor="middle"
+                    style={highlighted ? highlightTextStyle : textStyle}
+                  >
+                    {line}
+                  </text>
+                ))}
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+/**
+ * How far a label may sit from its band before a leader is drawn to it.
+ *
+ * Two pixels: below that the label is over its band and a leader would be a
+ * line nobody needs, and the declutter sweep leaves most labels within a pixel
+ * of where they wanted to be.
+ */
+const LEADER_AT = 2;
+
+const markStyle = { stroke: CHART_COLORS.annotation } as const;
+
+const highlightMarkStyle = { stroke: CHART_COLORS.highlight } as const;
+
+const leaderStyle = { stroke: CHART_COLORS.leader } as const;
+
+// Haloed: an infrared label is written over the trace as often as beside it,
+// since a band is named where it dips and the neighbouring bands dip too.
+const textStyle = {
+  fill: CHART_COLORS.labelText,
+  fontSize: CHART_FONT.label,
+  ...LABEL_HALO,
+} as const;
+
+const highlightTextStyle = {
+  fill: CHART_COLORS.highlight,
+  fontSize: CHART_FONT.label,
+  fontWeight: 600,
+  ...LABEL_HALO,
+} as const;