react-msaview 6.5.0 → 8.0.0

package/src/components/msa/drawFeatureSpans.ts

@@ -0,0 +1,150 @@
+import type { HierarchyNode } from '../../hierarchy.ts'
+import type { Annotation, NodeWithIdsAndLength } from '../../types.ts'
+import type { RenderCtx } from '../renderCtx.ts'
+
+/** one drawn span: a feature, the lane it sits in, and its row's depth */
+export interface SpanBand {
+  annotation: Annotation
+  lane: number
+  laneCount: number
+}
+
+/** one row's spans, at the row baseline `y` the tree layout gives it */
+export interface SpanRow<T extends SpanBand> {
+  y: number
+  bands: T[]
+}
+
+/**
+ * Where a band lands inside its row. The alignment overlay fills the row, bars
+ * it along the bottom, or stacks thin sub-rows; a `features` row panel divides
+ * the row between its lanes.
+ */
+export interface SpanLayout {
+  /** the band height in a row needing `laneCount` lanes */
+  height: (laneCount: number) => number
+  /** the band's top edge, from its row baseline, its lane and its height */
+  top: (y: number, lane: number, height: number) => number
+  /** how far a strand head reaches past the body */
+  headLength: (height: number) => number
+}
+
+/** the rows of `bandsByRow` that `leaves` covers, in display order */
+export function spanRows<T extends SpanBand>(
+  leaves: HierarchyNode<NodeWithIdsAndLength>[],
+  bandsByRow: Map<string, T[]>,
+): SpanRow<T>[] {
+  const rows: SpanRow<T>[] = []
+  for (const leaf of leaves) {
+    const bands = bandsByRow.get(leaf.data.name)
+    if (bands && bands.length > 0) {
+      rows.push({ y: leaf.x!, bands })
+    }
+  }
+  return rows
+}
+
+/**
+ * The span mark, in whatever x space the caller maps its bands into: alignment
+ * columns for the domain overlay, panel pixels for a `features` row panel. A
+ * feature with a strand draws as an arrow, one without as a box, and a label
+ * draws inside the span wherever the text fits.
+ *
+ * `xOf` returns the span's `[xStart, xEnd]` in the context's coordinates, and
+ * the context is translated so that `y - rowHeight` is the row's top edge.
+ */
+export function drawFeatureSpans<T extends SpanBand>({
+  ctx,
+  rows,
+  layout,
+  xOf,
+  colors,
+  labelOf,
+  labelDrawn,
+  contrastText,
+  xMin,
+  xMax,
+}: {
+  ctx: RenderCtx
+  rows: SpanRow<T>[]
+  layout: SpanLayout
+  xOf: (band: T) => [number, number]
+  colors: Map<Annotation, { fill: string; stroke: string }>
+  labelOf?: (band: T) => string | undefined
+  labelDrawn?: (band: T) => void
+  contrastText: (color: string) => string
+  xMin: number
+  xMax: number
+}) {
+  for (const { y, bands } of rows) {
+    const h = layout.height(bands[0]!.laneCount)
+    const headLen = layout.headLength(h)
+    for (const band of bands) {
+      const [xStart, xEnd] = xOf(band)
+      const w = xEnd - xStart
+      if (xEnd < xMin || xStart > xMax) {
+        continue
+      }
+      const t = layout.top(y, band.lane, h)
+      const { fill, stroke } = colors.get(band.annotation)!
+      ctx.fillStyle = fill
+      ctx.strokeStyle = stroke
+      const { strand } = band.annotation
+      if (strand === undefined) {
+        ctx.fillRect(xStart, t, w, h)
+        ctx.strokeRect(xStart, t, w, h)
+      } else {
+        drawGeneArrow({ ctx, x: xStart, t, w, h, headLen, strand })
+      }
+      const label = labelOf?.(band)
+      if (label !== undefined) {
+        const fontSize = Math.min(h - 2, 11)
+        ctx.font = `${fontSize}px sans-serif`
+        if (ctx.measureText(label).width + 2 <= w) {
+          labelDrawn?.(band)
+          ctx.fillStyle = contrastText(fill)
+          ctx.textAlign = 'center'
+          ctx.textBaseline = 'middle'
+          ctx.fillText(label, xStart + w / 2, t + h / 2)
+        }
+      }
+    }
+  }
+}
+
+// A gene arrow: a full-width rectangular body spanning the feature's
+// start..end columns, plus a triangular head that points *beyond* that end in
+// the strand direction (right for +, left for -). Keeping the body aligned to
+// the exact start/end columns means + and - strand features read as having the
+// same boundaries; the arrow lives outside them purely to show transcription
+// direction, preserving the column-by-column homology down the rows.
+function drawGeneArrow({
+  ctx,
+  x,
+  t,
+  w,
+  h,
+  headLen,
+  strand,
+}: {
+  ctx: RenderCtx
+  x: number
+  t: number
+  w: number
+  h: number
+  headLen: number
+  strand: number
+}) {
+  const dir = strand > 0 ? 1 : -1
+  const bodyStart = strand > 0 ? x : x + w
+  const bodyEnd = strand > 0 ? x + w : x
+  ctx.beginPath()
+  ctx.moveTo(bodyStart, t)
+  ctx.lineTo(bodyEnd, t)
+  ctx.lineTo(bodyEnd + dir * headLen, t + h / 2)
+  ctx.lineTo(bodyEnd, t + h)
+  ctx.lineTo(bodyStart, t + h)
+  ctx.closePath()
+  ctx.fill()
+  ctx.stroke()
+}

package/src/components/msa/legendRows.ts

@@ -0,0 +1,24 @@
+import type { Legend } from '../../types.ts'
+
+export interface LegendRow {
+  key: string
+  label: string
+  color?: string
+  hint?: string
+}
+
+// the legends flattened into the rows both the overlay and the export stack
+// top to bottom. A title row separates one legend from the next, and a lone
+// legend needs no title.
+export function legendRows(legends: Legend[]): LegendRow[] {
+  const titled = legends.length > 1
+  return legends.flatMap(legend => [
+    ...(titled ? [{ key: legend.id, label: legend.title }] : []),
+    ...legend.entries.map(entry => ({
+      key: `${legend.id}:${entry.id}`,
+      label: entry.label,
+      color: entry.color,
+      hint: entry.id,
+    })),
+  ])
+}

package/src/components/msa/msaRaster.ts

@@ -36,9 +36,8 @@ const colorCache = new Map<string, number>()
 
 /**
  * CSS color string -> the packed pixel an ImageData holds for it. Painting a 1x1
- * canvas and reading it back handles every form a color scheme can produce --
- * hex, rgb(), hsl(), named -- without a parser of our own, and the cache means
- * each distinct color is resolved once per session rather than once per cell.
+ * canvas and reading it back parses hex, rgb(), hsl() and named colors; the
+ * cache resolves each distinct color once per session.
  */
 export function cssColorToPixel(css: string) {
   const hit = colorCache.get(css)
@@ -63,14 +62,29 @@ export function cssColorToPixel(css: string) {
   return packed
 }
 
+function cellPixelFn(spec: RasterSpec, toPixel: (css: string) => number) {
+  const { columns, relativeTo, colorAt, bg, hover } = spec
+  const bgPixel = toPixel(bg)
+  const hoverPixel = toPixel(hover)
+  const reference = relativeTo ? columns.get(relativeTo) : undefined
+  return (name: string, col: number, letter: string) => {
+    if (reference && name !== relativeTo && letter === reference[col]) {
+      return hoverPixel
+    }
+    const color = colorAt(col, letter)
+    return color === undefined ? bgPixel : toPixel(color)
+  }
+}
+
 /**
  * Packs a rectangle of the alignment into one pixel per cell, in `rowNames`
  * order, ready to hand to putImageData. Cells past the end of a row, and rows
- * with no sequence at all, stay transparent -- what the per-cell tile painter
- * also leaves behind.
+ * with no sequence, stay transparent, as in the per-cell painter.
  *
- * `colStep`/`rowStep` sample instead of covering, which is how the minimap fits
- * a whole alignment into a 12px bar.
+ * `colStep`/`rowStep` sample every nth cell, which fits a whole alignment into
+ * the minimap's 12px bar. `colSpan`/`rowSpan` average each block of that many
+ * cells into one pixel, so a zoom below a device pixel per column still shows
+ * every column's color without blending neighbouring rows.
  */
 export function rasterPixels({
   spec,
@@ -80,7 +94,10 @@ export function rasterPixels({
   height,
   colStep = 1,
   rowStep = 1,
+  colSpan = 1,
+  rowSpan = 1,
   toPixel = cssColorToPixel,
+  out = new Uint32Array(width * height),
 }: {
   spec: RasterSpec
   col0: number
@@ -89,13 +106,27 @@ export function rasterPixels({
   height: number
   colStep?: number
   rowStep?: number
+  colSpan?: number
+  rowSpan?: number
   toPixel?: (css: string) => number
+  out?: Uint32Array
 }) {
-  const { rowNames, columns, relativeTo, colorAt, bg, hover } = spec
-  const out = new Uint32Array(width * height)
-  const bgPixel = toPixel(bg)
-  const hoverPixel = toPixel(hover)
-  const reference = relativeTo ? columns.get(relativeTo) : undefined
+  if (colSpan > 1 || rowSpan > 1) {
+    averagePixels({
+      spec,
+      col0,
+      row0,
+      width,
+      height,
+      colSpan,
+      rowSpan,
+      toPixel,
+      out,
+    })
+    return out
+  }
+  const { rowNames, columns } = spec
+  const cellPixel = cellPixelFn(spec, toPixel)
 
   for (let r = 0; r < height; r++) {
     const name = rowNames[row0 + r * rowStep]
@@ -106,7 +137,6 @@ export function rasterPixels({
     if (!str) {
       continue
     }
-    const isReference = name === relativeTo
     const base = r * width
     for (let c = 0; c < width; c++) {
       const col = col0 + c * colStep
@@ -114,21 +144,92 @@ export function rasterPixels({
       if (letter === undefined) {
         break
       }
-      if (reference && !isReference && letter === reference[col]) {
-        out[base + c] = hoverPixel
-      } else {
-        const color = colorAt(col, letter)
-        out[base + c] = color === undefined ? bgPixel : toPixel(color)
-      }
+      out[base + c] = cellPixel(name, col, letter)
     }
   }
   return out
 }
 
-// Getting a context object back is not the same as getting one that can do
-// this: the headless render shim hands back a context carrying only measureText,
-// which a truthiness test accepts and putImageData then does not survive. Name
-// the methods the raster actually calls, so every caller degrades together.
+function averagePixels({
+  spec,
+  col0,
+  row0,
+  width,
+  height,
+  colSpan,
+  rowSpan,
+  toPixel,
+  out,
+}: {
+  spec: RasterSpec
+  col0: number
+  row0: number
+  width: number
+  height: number
+  colSpan: number
+  rowSpan: number
+  toPixel: (css: string) => number
+  out: Uint32Array
+}) {
+  const { rowNames, columns } = spec
+  const cellPixel = cellPixelFn(spec, toPixel)
+  const cells = colSpan * rowSpan
+  const rShift = littleEndian ? 0 : 24
+  const gShift = littleEndian ? 8 : 16
+  const bShift = littleEndian ? 16 : 8
+  const aShift = littleEndian ? 24 : 0
+  const names: string[] = []
+  const strs: string[] = []
+
+  for (let r = 0; r < height; r++) {
+    names.length = 0
+    strs.length = 0
+    for (let dr = 0; dr < rowSpan; dr++) {
+      const name = rowNames[row0 + r * rowSpan + dr]
+      const str = name === undefined ? undefined : columns.get(name)
+      if (name !== undefined && str) {
+        names.push(name)
+        strs.push(str)
+      }
+    }
+    const base = r * width
+    for (let c = 0; c < width; c++) {
+      // premultiplied, so a cell past the end of a row dilutes the alpha of its
+      // pixel rather than darkening its color
+      let sumR = 0
+      let sumG = 0
+      let sumB = 0
+      let sumA = 0
+      for (let i = 0; i < strs.length; i++) {
+        const str = strs[i]!
+        const name = names[i]!
+        for (let dc = 0; dc < colSpan; dc++) {
+          const col = col0 + c * colSpan + dc
+          const letter = str[col]
+          if (letter === undefined) {
+            break
+          }
+          const p = cellPixel(name, col, letter)
+          const a = (p >>> aShift) & 255
+          sumR += ((p >>> rShift) & 255) * a
+          sumG += ((p >>> gShift) & 255) * a
+          sumB += ((p >>> bShift) & 255) * a
+          sumA += a
+        }
+      }
+      out[base + c] =
+        sumA === 0
+          ? 0
+          : packRgba(
+              Math.round(sumR / sumA),
+              Math.round(sumG / sumA),
+              Math.round(sumB / sumA),
+              Math.round(sumA / cells),
+            )
+    }
+  }
+}
+
 function usableRasterCtx(ctx: unknown): ctx is RasterCtx {
   const c = ctx as Record<string, unknown> | null
   return (
@@ -154,13 +255,17 @@ function makeRasterCanvas(width: number, height: number) {
     : undefined
 }
 
-function paint(pixels: Uint32Array, width: number, height: number) {
+function paint(
+  width: number,
+  height: number,
+  fill: (out: Uint32Array) => void,
+) {
   const made = makeRasterCanvas(width, height)
   if (!made) {
     return undefined
   }
   const image = made.ctx.createImageData(width, height)
-  new Uint32Array(image.data.buffer).set(pixels)
+  fill(new Uint32Array(image.data.buffer))
   made.ctx.putImageData(image, 0, 0)
   return made.canvas
 }
@@ -185,8 +290,8 @@ interface RasterCache {
 
 const caches = new WeakMap<object, RasterCache>()
 
-// Everything a cell's color depends on. A change to any of them makes every
-// cached tile stale, which a fresh cache expresses without tracking which.
+// Everything a cell's color depends on; a change to any of them starts a fresh
+// cache.
 function rasterKeys(model: MsaViewModel, theme: Theme) {
   return [
     model.columns,
@@ -223,8 +328,29 @@ function getCache(model: MsaViewModel, theme: Theme) {
   return next
 }
 
-function getTile(cache: RasterCache, tileRow: number, tileCol: number) {
-  const key = `${tileRow}_${tileCol}`
+// Cells averaged into one tile pixel along an axis: the smallest power of two
+// that brings a pixel back to at least one device pixel. Powers of two keep the
+// number of distinct tile sets a zoom sweep builds to a handful.
+function cellsPerPixel(devicePixelsPerCell: number) {
+  return devicePixelsPerCell >= 1
+    ? 1
+    : 2 ** Math.ceil(Math.log2(1 / devicePixelsPerCell))
+}
+
+function getTile({
+  cache,
+  tileRow,
+  tileCol,
+  colSpan,
+  rowSpan,
+}: {
+  cache: RasterCache
+  tileRow: number
+  tileCol: number
+  colSpan: number
+  rowSpan: number
+}) {
+  const key = `${colSpan}_${rowSpan}_${tileRow}_${tileCol}`
   const hit = cache.tiles.get(key)
   if (hit) {
     // re-inserting makes this the newest entry: a Map iterates in insertion
@@ -233,18 +359,31 @@ function getTile(cache: RasterCache, tileRow: number, tileCol: number) {
     cache.tiles.set(key, hit)
     return hit
   }
-  const col0 = tileCol * rasterTileSize
-  const row0 = tileRow * rasterTileSize
-  const width = Math.min(rasterTileSize, cache.numColumns - col0)
-  const height = Math.min(rasterTileSize, cache.numRows - row0)
+  const col0 = tileCol * rasterTileSize * colSpan
+  const row0 = tileRow * rasterTileSize * rowSpan
+  const width = Math.min(
+    rasterTileSize,
+    Math.ceil((cache.numColumns - col0) / colSpan),
+  )
+  const height = Math.min(
+    rasterTileSize,
+    Math.ceil((cache.numRows - row0) / rowSpan),
+  )
   if (width <= 0 || height <= 0) {
     return undefined
   }
-  const canvas = paint(
-    rasterPixels({ spec: cache.spec, col0, row0, width, height }),
-    width,
-    height,
-  )
+  const canvas = paint(width, height, out => {
+    rasterPixels({
+      spec: cache.spec,
+      col0,
+      row0,
+      width,
+      height,
+      colSpan,
+      rowSpan,
+      out,
+    })
+  })
   if (!canvas) {
     return undefined
   }
@@ -261,8 +400,12 @@ function getTile(cache: RasterCache, tileRow: number, tileCol: number) {
 /**
  * Paints the alignment background of one MSA block from cached
  * one-pixel-per-cell tiles. The tiles do not depend on the zoom level, so a zoom
- * frame costs a handful of drawImage calls instead of a fillRect per visible
- * cell -- which ran to 885ms per block at the minimum column width.
+ * frame costs a handful of drawImage calls. A fillRect per visible cell measured
+ * 885ms per block at the minimum column width.
+ *
+ * Below a device pixel per cell the tiles average cells together, per axis.
+ * The browser's image smoothing blurs both axes, which turns every row
+ * boundary into a gradient at fit-to-width, where only the columns are narrow.
  */
 export function drawMsaRaster({
   ctx,
@@ -279,17 +422,18 @@ export function drawMsaRaster({
 }) {
   const { colWidth, rowHeight, blockSize, highResScaleFactor } = model
   const cache = getCache(model, theme)
+  const colSpan = cellsPerPixel(colWidth * highResScaleFactor)
+  const rowSpan = cellsPerPixel(rowHeight * highResScaleFactor)
 
   ctx.resetTransform()
   ctx.scale(highResScaleFactor, highResScaleFactor)
   ctx.translate(-offsetX, -offsetY)
-  // below a pixel per cell a tile carries more cells than the block has room
-  // for, so let the browser downsample it rather than letting whichever cell
-  // landed last win
-  ctx.imageSmoothingEnabled = colWidth < 1 || rowHeight < 1
+  ctx.imageSmoothingEnabled = false
 
-  const tileWidth = rasterTileSize * colWidth
-  const tileHeight = rasterTileSize * rowHeight
+  const pixelWidth = colWidth * colSpan
+  const pixelHeight = rowHeight * rowSpan
+  const tileWidth = rasterTileSize * pixelWidth
+  const tileHeight = rasterTileSize * pixelHeight
   const firstCol = Math.max(0, Math.floor(offsetX / tileWidth))
   const lastCol = Math.floor((offsetX + blockSize) / tileWidth)
   const firstRow = Math.max(0, Math.floor(offsetY / tileHeight))
@@ -297,7 +441,7 @@ export function drawMsaRaster({
 
   for (let tileRow = firstRow; tileRow <= lastRow; tileRow++) {
     for (let tileCol = firstCol; tileCol <= lastCol; tileCol++) {
-      const tile = getTile(cache, tileRow, tileCol)
+      const tile = getTile({ cache, tileRow, tileCol, colSpan, rowSpan })
       if (tile) {
         ctx.drawImage(
           tile,
@@ -307,8 +451,8 @@ export function drawMsaRaster({
           tile.height,
           tileCol * tileWidth,
           tileRow * tileHeight,
-          tile.width * colWidth,
-          tile.height * rowHeight,
+          tile.width * pixelWidth,
+          tile.height * pixelHeight,
         )
       }
     }
@@ -320,12 +464,11 @@ export function drawMsaRaster({
 /**
  * A raster canvas as a PNG data URI, for embedding in the SVG export.
  *
- * toDataURL is the synchronous read-back. The DOM canvas has it, and so does a
- * node canvas standing in for OffscreenCanvas headlessly; a browser
- * OffscreenCanvas -- which is what the tile and thumbnail caches hold wherever
- * it exists -- gets copied onto a DOM canvas first. Returns undefined wherever
- * the read-back is unavailable (jsdom) rather than throwing, which is the
- * signal to fall back to drawing the thing in vector.
+ * toDataURL is the synchronous read-back. The DOM canvas and a headless node
+ * canvas have it; a browser OffscreenCanvas, which the tile and thumbnail
+ * caches hold where it exists, is copied onto a DOM canvas first. Returns
+ * undefined where read-back is unavailable (jsdom), and the caller then draws
+ * in vector.
  */
 export function canvasHref(canvas: RasterCanvas | undefined) {
   if (!canvas) {
@@ -352,10 +495,10 @@ export function canvasHref(canvas: RasterCanvas | undefined) {
   }
 }
 
-// A canvas much past this many pixels fails to allocate, and the browser's own
-// per-side limit is lower still, so a raster bigger than either samples down.
-// The result is still drawn across the same rectangle -- it loses cell-exact
-// detail at a size where no figure could show it anyway.
+// A canvas much past this many pixels fails to allocate, and the browser's
+// per-side limit is lower still, so a larger raster averages down per axis and
+// is drawn across the same rectangle. An alignment that hits the limit on
+// columns alone keeps every row.
 const maxImagePixels = 64e6
 const maxImageSide = 16384
 
@@ -363,14 +506,12 @@ const maxImageSide = 16384
  * The alignment rectangle [col0, col0+numCols) x [row0, row0+numRows) as a PNG
  * data URI, for the SVG export.
  *
- * SVG has no blit, so the export cannot reuse the tile cache the live canvas
- * draws from: one <image> is the whole background instead. That is the
- * difference between an export that scales and one that does not -- the vector
- * path emits a <rect> per cell, and a 200x500 alignment exhausts the heap
- * building them.
+ * SVG has no blit, so the export draws the whole background as one <image>. The
+ * vector path emits a <rect> per cell, and a 200x500 alignment exhausts the
+ * heap building them.
  *
- * Returns undefined wherever a canvas cannot be read back (jsdom, notably),
- * which is the signal to keep the per-cell path.
+ * Returns undefined where a canvas cannot be read back (jsdom), and the caller
+ * then keeps the per-cell path.
  */
 export function rasterImageHref({
   model,
@@ -391,38 +532,46 @@ export function rasterImageHref({
     return undefined
   }
   const cache = getCache(model, theme)
-  let step = 1
+  let colSpan = 1
+  let rowSpan = 1
+  while (Math.ceil(numCols / colSpan) > maxImageSide) {
+    colSpan *= 2
+  }
+  while (Math.ceil(numRows / rowSpan) > maxImageSide) {
+    rowSpan *= 2
+  }
   while (
-    Math.ceil(numCols / step) * Math.ceil(numRows / step) > maxImagePixels ||
-    Math.ceil(numCols / step) > maxImageSide ||
-    Math.ceil(numRows / step) > maxImageSide
+    Math.ceil(numCols / colSpan) * Math.ceil(numRows / rowSpan) >
+    maxImagePixels
   ) {
-    step *= 2
+    if (numCols / colSpan >= numRows / rowSpan) {
+      colSpan *= 2
+    } else {
+      rowSpan *= 2
+    }
   }
-  const width = Math.ceil(numCols / step)
-  const height = Math.ceil(numRows / step)
+  const width = Math.ceil(numCols / colSpan)
+  const height = Math.ceil(numRows / rowSpan)
 
   return canvasHref(
-    paint(
+    paint(width, height, out => {
       rasterPixels({
         spec: cache.spec,
         col0,
         row0,
         width,
         height,
-        colStep: step,
-        rowStep: step,
-      }),
-      width,
-      height,
-    ),
+        colSpan,
+        rowSpan,
+        out,
+      })
+    }),
   )
 }
 
 /**
- * The whole alignment sampled down to a strip small enough to sit behind the
- * minimap thumb, cached alongside the block tiles because it goes stale under
- * exactly the same conditions.
+ * The whole alignment sampled down to a strip behind the minimap thumb, cached
+ * with the block tiles since the same keys invalidate both.
  */
 export function msaThumbnail({
   model,
@@ -447,7 +596,7 @@ export function msaThumbnail({
     const h = Math.ceil(numRows / rowStep)
     cache.thumbnail = {
       height,
-      canvas: paint(
+      canvas: paint(w, h, out => {
         rasterPixels({
           spec: cache.spec,
           col0: 0,
@@ -456,10 +605,9 @@ export function msaThumbnail({
           height: h,
           colStep,
           rowStep,
-        }),
-        w,
-        h,
-      ),
+          out,
+        })
+      }),
     }
   }
   return cache.thumbnail.canvas