phoria2 1.1.0 → 1.3.0

package/src/particles/Emitter.js

@@ -1,7 +1,8 @@
 // A particle system as one Points node: particles are born at the emitter's origin, move under
 // velocity, gravity and drag, fade through a list of colours and die. The simulation runs in the
 // emitter's own update handler, so it follows the scene clock (frame-rate independent) and its
-// arrays go to the GPU as one buffer refill per frame.
+// arrays go to the GPU as one buffer refill per frame. Particles that grow, fade or turn give the
+// geometry per-point sizes, opacities or angles, and are drawn as squares.
 import * as mat4 from '../math/mat4.js'
 import { Geometry } from '../geometry/Geometry.js'
 import { Material } from '../material/Material.js'
@@ -48,17 +49,32 @@ import { checkNumber, describe, fail } from '../validate.js'
  *   frustumCulled?: boolean,
  *   renderOrder?: number,
  *   onParticle?: ((p: Particle) => boolean | void) | null,
- * }} EmitterOptions
+ *   sort?: boolean,
+ * } & LookOptions} EmitterOptions
  * max: most live particles at once (default 1000). rate: particles born per second (default 100).
  * gravity: acceleration, e.g. [0, -9.8, 0] (default none). drag: share of velocity lost per second
  * (default 0). follow: a node whose position becomes the origin each frame - a trail that stays
  * behind it. onParticle: called for every live particle each frame after it moves; return false to
- * remove it (a particle hitting something).
+ * remove it (a particle hitting something). sort: draw furthest first, for soft particles with
+ * blending 'normal' (smoke) that would otherwise layer wrongly.
+ */
+
+/**
+ * How particles look over their lives, beyond colour.
+ * @typedef {object} LookOptions
+ * @property {number | number[]} [size] a multiple of the material's size, or several each particle goes
+ *   through over its life - [0.5, 3] for smoke that billows out (default 1)
+ * @property {number} [sizeSpread] each particle's size varies by up to this share either way, 0-1 (default 0)
+ * @property {number | number[]} [opacity] 0-1, or several each particle goes through - [0, 1, 0] fades in
+ *   and out (default 1)
+ * @property {number | [number, number]} [spin] radians per second: a number turns each particle up to that
+ *   fast either way, [min, max] a range. Spinning particles start at a random angle (default 0)
  */
 
 const SPAWN_OPTIONS = ['origin', 'originSpread', 'velocity', 'velocitySpread', 'lifetime', 'color']
-const OPTIONS = [...Points.OPTIONS, ...SPAWN_OPTIONS,
-  'max', 'rate', 'gravity', 'drag', 'follow', 'onParticle']
+const LOOK_OPTIONS = ['size', 'sizeSpread', 'opacity', 'spin']
+const BEHAVIOUR_OPTIONS = ['rate', 'gravity', 'drag', 'follow', 'onParticle', ...LOOK_OPTIONS]
+const OPTIONS = [...Points.OPTIONS, ...SPAWN_OPTIONS, 'max', ...BEHAVIOUR_OPTIONS]
 const HINTS = {
   count: "use 'max' for the most particles alive at once, 'rate' for how many are born per second",
   lifetimeRnd: "give 'lifetime' a [min, max] range",
@@ -111,6 +127,13 @@ export class Emitter extends Points {
   /** @type {Map<string, number>} */ #paletteIds = new Map()
   /** @type {Uint8Array} */ #palette
   #spawnPalette = 0
+  // the looks: stops over each particle's life, and each one's own size factor and turn rate
+  /** @type {number[]} */ #size = [1]
+  #sizeSpread = 0
+  /** @type {number[]} */ #opacity = [1]
+  /** @type {[number, number]} */ #spin = [0, 0]
+  /** @type {Float32Array | null} */ #sizeFactors = null
+  /** @type {Float32Array | null} */ #spins = null
   /** Last frame's origin, so a moving source leaves an even trail rather than clumps. */
   #lastOrigin = /** @type {Vec3 | null} */ (null)
   #particle = /** @type {Particle} */ ({ position: new Vec3(), velocity: new Vec3(), age: 0, lifetime: 0 })
@@ -144,12 +167,12 @@ export class Emitter extends Points {
   /**
    * Change several settings at once - a preset, say. Vectors are copied into the emitter's own,
    * so anything bound to `emitter.gravity` and friends stays bound. Live particles carry on.
-   * @param {SpawnOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
+   * @param {SpawnOptions & LookOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null,
    *   onParticle?: ((p: Particle) => boolean | void) | null }} options
    * @returns {this}
    */
   set(options) {
-    const known = [...SPAWN_OPTIONS, 'rate', 'gravity', 'drag', 'follow', 'onParticle']
+    const known = [...SPAWN_OPTIONS, ...BEHAVIOUR_OPTIONS]
     for (const key of Object.keys(options ?? {})) {
       if (!known.includes(key)) fail('Emitter', `set() doesn't take '${key}' - it takes ${known.join(', ')}`)
     }
@@ -169,6 +192,22 @@ export class Emitter extends Points {
   /** @returns {[number, number, number][]} */
   get color() { return /** @type {[number, number, number][]} */ (this.#palettes[0].map((s) => [...s])) }
 
+  /** Each particle's size over its life, as multiples of the material's. @param {number | number[]} v */
+  set size(v) { this.#setLooks({ size: v }) }
+  /** @returns {number[]} */
+  get size() { return [...this.#size] }
+  /** How much each particle's size varies, 0-1 either way. @param {number} v */
+  set sizeSpread(v) { this.#setLooks({ sizeSpread: v }) }
+  get sizeSpread() { return this.#sizeSpread }
+  /** Each particle's opacity over its life. @param {number | number[]} v */
+  set opacity(v) { this.#setLooks({ opacity: v }) }
+  /** @returns {number[]} */
+  get opacity() { return [...this.#opacity] }
+  /** How fast particles turn, radians per second, as a [min, max] range. @param {number | [number, number]} v */
+  set spin(v) { this.#setLooks({ spin: v }) }
+  /** @returns {[number, number]} */
+  get spin() { return [...this.#spin] }
+
   /**
    * Birth `count` particles at once - explosions, splashes. Options override the emitter's own
    * spawn settings for this burst only.
@@ -211,6 +250,7 @@ export class Emitter extends Points {
     const v = this.#velocities, ages = this.#ages, lives = this.#lifetimes
     const g = this.gravity, keep = Math.exp(-this.drag * dt)
     const hook = this.onParticle, particle = this.#particle
+    const angles = this.geometry.angles, spins = this.#spins
 
     for (let i = 0; i < this.#alive;) {
       const age = ages[i] += dt
@@ -223,6 +263,7 @@ export class Emitter extends Points {
         v[i3 + k] = (v[i3 + k] + g[k] * dt) * keep
         p[i3 + k] += v[i3 + k] * dt
       }
+      if (angles && spins) angles[i] += spins[i] * dt
       this.#paint(i, age / lives[i])
       if (hook) {
         particle.position.set(p[i3], p[i3 + 1], p[i3 + 2])
@@ -256,7 +297,7 @@ export class Emitter extends Points {
     const rest = super.cloneOptions()
     delete rest.geometry
     return { ...rest, ...this.#saveSpawn(), max: this.#max, rate: this.rate, gravity: this.gravity.clone(),
-      drag: this.drag, follow: this.follow, onParticle: this.onParticle, color: this.color }
+      drag: this.drag, follow: this.follow, onParticle: this.onParticle, color: this.color, ...this.#looks() }
   }
 
   /** @internal @returns {Record<string, unknown>} */
@@ -266,7 +307,8 @@ export class Emitter extends Points {
     return { ...rest, max: this.#max, rate: this.rate, gravity: this.gravity.toArray(), drag: this.drag,
       origin: this.origin.toArray(), originSpread: this.originSpread, velocity: this.velocity.toArray(),
       velocitySpread: typeof this.velocitySpread === 'number' ? this.velocitySpread : this.velocitySpread.toArray(),
-      lifetime: [...this.lifetime], color: this.#palettes[0].map((s) => new Color().setSRGB(s[0], s[1], s[2]).toJSON()) }
+      lifetime: [...this.lifetime], color: this.#palettes[0].map((s) => new Color().setSRGB(s[0], s[1], s[2]).toJSON()),
+      ...this.#looks() }
   }
 
   // birth one particle somewhere between a and b, already `head` seconds into its life
@@ -287,6 +329,12 @@ export class Emitter extends Points {
     this.#lifetimes[i] = min + Math.random() * (max - min)
     this.#ages[i] = head
     this.#palette[i] = this.#spawnPalette
+    if (this.#sizeFactors) this.#sizeFactors[i] = 1 + (Math.random() * 2 - 1) * this.#sizeSpread
+    const angles = this.geometry.angles, spins = this.#spins
+    if (angles && spins) {
+      spins[i] = this.#spin[0] + Math.random() * (this.#spin[1] - this.#spin[0])
+      angles[i] = Math.random() * Math.PI * 2 + spins[i] * head
+    }
     this.#paint(i, head / this.#lifetimes[i])
   }
 
@@ -302,10 +350,16 @@ export class Emitter extends Points {
     this.#ages[i] = this.#ages[last]
     this.#lifetimes[i] = this.#lifetimes[last]
     this.#palette[i] = this.#palette[last]
+    for (const a of [this.geometry.sizes, this.geometry.opacities, this.geometry.angles, this.#sizeFactors, this.#spins]) {
+      if (a) a[i] = a[last]
+    }
   }
 
   /** @param {number} i @param {number} t 0-1 through its life */
   #paint(i, t) {
+    const { sizes, opacities } = this.geometry
+    if (sizes) sizes[i] = along(this.#size, t) * (this.#sizeFactors ? this.#sizeFactors[i] : 1)
+    if (opacities) opacities[i] = along(this.#opacity, t)
     const c = /** @type {Float32Array} */ (this.geometry.colors), stops = this.#palettes[this.#palette[i]]
     if (stops.length === 1) {
       c.set(stops[0], i * 3)
@@ -349,8 +403,9 @@ export class Emitter extends Points {
     if (o.color !== undefined) this.#palettes[0] = colorStops(o.color)
   }
 
-  /** @param {{ rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null, onParticle?: ((p: Particle) => boolean | void) | null }} o */
+  /** @param {LookOptions & { rate?: number, gravity?: Vec3Input, drag?: number, follow?: Node | null, onParticle?: ((p: Particle) => boolean | void) | null }} o */
   #setBehaviour(o) {
+    this.#setLooks(o)
     const owner = 'Emitter'
     if (o.rate !== undefined) this.rate = Math.max(0, checkNumber(owner, 'rate', o.rate))
     if (o.gravity !== undefined) this.gravity.copy(o.gravity, owner)
@@ -359,6 +414,31 @@ export class Emitter extends Points {
     if (o.onParticle !== undefined) this.onParticle = o.onParticle
   }
 
+  // Sizes, opacities and angles go on the geometry when first wanted (the points are then drawn as
+  // squares) and stay; live particles get the plain values until they are next painted.
+  /** @param {LookOptions} o */
+  #setLooks(o) {
+    const owner = 'Emitter', g = this.geometry, max = this.#max
+    if (o.size !== undefined) this.#size = lookStops('size', o.size, Infinity)
+    if (o.sizeSpread !== undefined) this.#sizeSpread = Math.min(Math.max(checkNumber(owner, 'sizeSpread', o.sizeSpread), 0), 1)
+    if (o.opacity !== undefined) this.#opacity = lookStops('opacity', o.opacity, 1)
+    if (o.spin !== undefined) this.#spin = spinRange(o.spin)
+    const plain = (/** @type {number[]} */ stops) => stops.length === 1 && stops[0] === 1
+    if (!g.sizes && (!plain(this.#size) || this.#sizeSpread)) g.sizes = new Float32Array(max).fill(1)
+    if (!this.#sizeFactors && this.#sizeSpread) this.#sizeFactors = new Float32Array(max).fill(1)
+    if (!g.opacities && !plain(this.#opacity)) g.opacities = new Float32Array(max).fill(1)
+    if (!g.angles && (this.#spin[0] || this.#spin[1])) {
+      g.angles = new Float32Array(max)
+      this.#spins = new Float32Array(max)
+    }
+  }
+
+  /** The looks, as options. @returns {LookOptions} */
+  #looks() {
+    return { size: unstop(this.#size), sizeSpread: this.#sizeSpread, opacity: unstop(this.#opacity),
+      spin: /** @type {[number, number]} */ ([...this.#spin]) }
+  }
+
   /** The spawn settings other than colour, as options. @returns {SpawnOptions} */
   #saveSpawn() {
     return { origin: this.origin.clone(), originSpread: this.originSpread, velocity: this.velocity.clone(),
@@ -397,6 +477,37 @@ function lifetimeRange(v) {
   return [Math.min(range[0], range[1]), Math.max(range[0], range[1])]
 }
 
+/** @param {string} name @param {number | number[]} v @param {number} most @returns {number[]} */
+function lookStops(name, v, most) {
+  const list = Array.isArray(v) ? v : [v]
+  if (!list.length || !list.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
+    fail('Emitter', `'${name}' must be a number of 0 or more, or a list of them a particle goes through, got ${describe(v)}`)
+  }
+  return list.map((n) => Math.min(n, most))
+}
+
+/** One stop as a number, several as a list. @param {number[]} stops @returns {number | number[]} */
+function unstop(stops) {
+  return stops.length === 1 ? stops[0] : [...stops]
+}
+
+/** The value t (0-1) of the way through evenly spaced stops. @param {number[]} stops @param {number} t */
+function along(stops, t) {
+  if (stops.length === 1) return stops[0]
+  const x = Math.min(Math.max(t, 0), 1) * (stops.length - 1)
+  const s = Math.min(Math.floor(x), stops.length - 2)
+  return stops[s] + (stops[s + 1] - stops[s]) * (x - s)
+}
+
+/** @param {number | [number, number]} v @returns {[number, number]} */
+function spinRange(v) {
+  const range = typeof v === 'number' ? [-Math.abs(v), Math.abs(v)] : v
+  if (!Array.isArray(range) || range.length !== 2 || !range.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+    fail('Emitter', `'spin' must be radians per second, or a [min, max] range, got ${describe(v)}`)
+  }
+  return [Math.min(range[0], range[1]), Math.max(range[0], range[1])]
+}
+
 /** @param {ColorInput | ColorInput[]} v @returns {number[][]} */
 function colorStops(v) {
   // a single [r, g, b] array is one colour, not three

package/src/scene/Node.js

@@ -10,7 +10,7 @@ import { Vec3 } from '../value/Vec3.js'
 import { checkOptions, describe, fail } from '../validate.js'
 import { Clip } from '../clip.js'
 
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 /** @import { Hit } from '../Raycaster.js' */
 /** @import { Camera } from './cameras.js' */
 /** @import { ClipOptions } from '../clip.js' */
@@ -44,7 +44,7 @@ import { Clip } from '../clip.js'
  * @property {string} [name]
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion] [x, y, z, w] - instead of rotation
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - instead of rotation
  * @property {Vec3Input | number} [scale] a number scales uniformly
  * @property {boolean} [visible]
  * @property {boolean} [pickable] include in view.pick() (default true)
@@ -54,7 +54,8 @@ import { Clip } from '../clip.js'
  * @property {UpdateHandler | UpdateHandler[]} [onUpdate]
  * @property {((hit: Hit) => any) | null} [tooltip] tooltip for anything picked in this subtree; nearer nodes win, and
  *   all win over the View's
- * @property {ColorInput | null} [highlight] hover tint for this subtree, over the View's
+ * @property {ColorInput | null | false} [highlight] hover tint for this subtree, over the View's; false for none - a
+ *   floor or wall left plain under a View that tints everything else (null: the View's)
  * @property {boolean} [highlightWhole] hovering any part of this subtree tints all of it, as one thing - a
  *   piece of furniture, a machine - rather than just the part under the pointer (default false)
  * @property {((hit: Hit | null) => void) | null} [onHover] called as the thing under the pointer in this subtree changes
@@ -136,7 +137,7 @@ export class Node {
   onDrag = null
   /** @type {Outline | null} */
   #outline = null
-  /** @type {Color | null} */
+  /** @type {Color | null | false} */
   #highlight = null
   /** Hovering any part of this subtree tints all of it, not just the part under the pointer. */
   highlightWhole = false
@@ -164,7 +165,7 @@ export class Node {
   set rotation(v) { this.#rotation.copy(/** @type {any} */ (v), this.constructor.name) }
   /** Kept in sync with rotation. Assigning copies, normalised. @returns {Quat} */
   get quaternion() { return this.#quaternion }
-  /** @param {ArrayLike<number>} v */
+  /** @param {QuatInput} v */
   set quaternion(v) { this.#quaternion.copy(v, this.constructor.name).normalize() }
 
   /** @param {NodeOptions} [options] */
@@ -191,7 +192,7 @@ export class Node {
       if (typeof fn !== 'function') fail(owner, `'${key}' must be a function, got ${describe(fn)}`)
       this[key] = fn
     }
-    if (options.highlight != null) this.#highlight = Color.fromInput(options.highlight, owner)
+    if (options.highlight != null) this.#setHighlight(options.highlight, owner)
     if (options.highlightWhole !== undefined) {
       if (typeof options.highlightWhole !== 'boolean') fail(owner, `'highlightWhole' must be true or false, got ${describe(options.highlightWhole)}`)
       this.highlightWhole = options.highlightWhole
@@ -201,14 +202,23 @@ export class Node {
     if (options.children) for (const child of options.children) this.add(child)
   }
 
-  /** Hover tint for this subtree, over the View's; set any colour, or null. @returns {Color | null} */
+  /**
+   * Hover tint for this subtree, over the View's: a colour, false for none, or null to use the View's.
+   * @returns {Color | null | false}
+   */
   get highlight() {
     return this.#highlight
   }
 
-  /** @param {ColorInput | null} value */
+  /** @param {ColorInput | null | false} value */
   set highlight(value) {
-    this.#highlight = value == null ? null : Color.fromInput(value, this.constructor.name)
+    this.#setHighlight(value, this.constructor.name)
+  }
+
+  /** @param {ColorInput | null | false | true} value @param {string} owner */
+  #setHighlight(value, owner) {
+    if (value === true) fail(owner, "'highlight' is a colour, false for no tint, or null to use the View's - got true")
+    this.#highlight = value == null ? null : value === false ? false : Color.fromInput(value, owner)
   }
 
   /**
@@ -612,6 +622,7 @@ export class Node {
     if (!this.pickable) json.pickable = false
     if (!this.matrixAutoUpdate) json.matrixAutoUpdate = false
     if (this.highlight) json.highlight = this.highlight.getStyle()
+    else if (this.highlight === false) json.highlight = false
     if (this.highlightWhole) json.highlightWhole = true
     if (this.#clip) json.clip = this.#clip.toJSON()
     if (this.#outline) json.outline = { color: this.#outline.color.getStyle(), width: this.#outline.width }

package/src/scene/Scene.js

@@ -44,6 +44,8 @@ export class Scene extends Node {
   environmentIntensity = 1
   /** 0-1: how blurred a panorama background is drawn - a soft backdrop that doesn't compete. */
   backgroundBlur = 0
+  /** @internal Set by the View drawing it, from its reducedMotion: charts' transitions and flows stand still. */
+  motionReduced = false
   /** @type {Fog | null} */
   #fog = null
 

package/src/scene/cameras.js

@@ -20,7 +20,10 @@ const tmp3 = new Float32Array(9)
 export function aimAt(node, target) {
   if (node.position.equals(target, 1e-9)) return
   const dir = target.clone().sub(node.position).normalize()
-  const up = Math.abs(dir[1]) > 0.9999 ? [0, 0, -1] : UP
+  // world up keeps the picture upright, and turns it smoothly with the view right up to straight up
+  // or down - the orbit stops a thousandth of a radian short. Only within a hair of exactly vertical
+  // (the 'top' preset's view), where up would no longer say which way the screen faces, is north up
+  const up = Math.hypot(dir[0], dir[2]) < 5e-4 ? [0, 0, -1] : UP
   mat4.targetTo(tmp, node.position, target, up)
   const q = quat.normalize(new Float32Array(4), quat.fromMat3(new Float32Array(4), mat3.fromMat4(tmp3, tmp)))
   node.quaternion.copy(q)

package/src/scene/drawables.js

@@ -12,7 +12,7 @@ import { NODE_OPTIONS, Node } from './Node.js'
 /** @import { Material, MaterialOptions } from '../material/Material.js' */
 /** @import { GeometryOptions } from '../geometry/Geometry.js' */
 /** @import { NodeOptions } from './Node.js' */
-/** @import { ColorInput, Vec3Input } from '../types.js' */
+/** @import { ColorInput, QuatInput, Vec3Input } from '../types.js' */
 
 /**
  * @typedef {NodeOptions & {
@@ -45,11 +45,14 @@ import { NODE_OPTIONS, Node } from './Node.js'
  * @property {'left' | 'right' | null} [edge] set the label at the view's left or right edge, level with its
  *   point - callouts in a column down the side of a diagram, with leader: true. offset then moves it in from
  *   the edge and up or down (default null: by its point)
+ * @property {number} [minScale] show the label only when zoomed in this far: at least this many CSS pixels to
+ *   one world unit, at the label's point - details that appear as you come closer (default 0: always)
  */
 /** @typedef {'center' | 'above' | 'below' | 'left' | 'right'} LabelPlace */
 
 /**
- * One label per instance or point, from its row of data.
+ * One label per instance or point, from its row of data - or a list of these, for several each (a symbol
+ * always, its details when zoomed in).
  * @typedef {Omit<LabelPlacement, 'priority'> & {
  *   text: (datum: any, index: number) => string | number | null | undefined,
  *   priority?: number | ((datum: any, index: number) => number),
@@ -61,7 +64,7 @@ import { NODE_OPTIONS, Node } from './Node.js'
  */
 
 export const LABEL_PLACES = /** @type {LabelPlace[]} */ (['center', 'above', 'below', 'left', 'right'])
-const PLACEMENT_OPTIONS = ['place', 'offset', 'className', 'priority', 'overlap', 'occlude', 'leader', 'edge']
+const PLACEMENT_OPTIONS = ['place', 'offset', 'className', 'priority', 'overlap', 'occlude', 'leader', 'edge', 'minScale']
 const LABEL_HINTS = {
   line: 'use leader: true - a line from the point to the label',
   callout: "use leader: true, with edge: 'left' | 'right' to line the labels up down the side",
@@ -70,6 +73,8 @@ const LABEL_HINTS = {
   pointer: 'use leader: true - a line from the point to the label',
   anchor: "use place: 'center' | 'above' | 'below' | 'left' | 'right' (where the label goes)",
   zIndex: "use 'priority': higher stays when labels overlap",
+  minZoom: "use 'minScale': CSS pixels to one world unit at the label's point",
+  lod: "use 'minScale': the label shows when zoomed in at least this far (CSS pixels to one world unit)",
   collision: "use overlap: 'hide' | 'dim' | 'show'",
 }
 // labels per instance or point take one more: they can't be moved anywhere but by offset
@@ -94,12 +99,26 @@ function placement(owner, o) {
     occlude: !!o.occlude,
     leader: !!o.leader,
     edge: o.edge == null ? null : /** @type {'left' | 'right'} */ (checkOneOf(owner, 'edge', o.edge, ['left', 'right'])),
+    minScale: o.minScale === undefined ? 0 : minScale(owner, o.minScale),
   }
 }
 
-/** @param {string} owner @param {unknown} v @returns {(InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }) | null} */
+/** @param {string} owner @param {unknown} v @returns {number} */
+function minScale(owner, v) {
+  const n = checkNumber(owner, 'minScale', v)
+  if (!(n >= 0)) fail(owner, `'minScale' is CSS pixels to one world unit, 0 or more, got ${n}`)
+  return n
+}
+
+/** @typedef {InstanceLabels & Required<Omit<LabelPlacement, 'priority'>> & { priority: number | ((datum: any, index: number) => number) }} CheckedLabels */
+
+/** @param {string} owner @param {unknown} v @returns {CheckedLabels | CheckedLabels[] | null} */
 function instanceLabels(owner, v) {
   if (v == null) return null
+  if (Array.isArray(v)) {
+    if (!v.length) fail(owner, "'labels' as a list needs at least one { text: (datum, index) => string, ... }")
+    return v.map((one) => /** @type {CheckedLabels} */ (instanceLabels(owner, one)))
+  }
   if (typeof v !== 'object' || typeof (/** @type {any} */ (v)).text !== 'function') {
     fail(owner, `'labels' must be { text: (datum, index) => string, ... }, got ${describe(v)}`)
   }
@@ -253,7 +272,7 @@ export class Mesh extends Drawable {
  * @typedef {object} InstanceOptions
  * @property {Vec3Input} [position]
  * @property {Vec3Input | Euler} [rotation] Euler angles in radians, XYZ order
- * @property {ArrayLike<number>} [quaternion]
+ * @property {QuatInput} [quaternion] [x, y, z, w] or { x, y, z, w } - as physics engines give them
  * @property {Vec3Input | number} [scale]
  * @property {ColorInput} [color] multiplies the material colour
  */
@@ -261,11 +280,23 @@ export class Mesh extends Drawable {
 const INSTANCE_OPTIONS = new Set(['position', 'rotation', 'quaternion', 'scale', 'color'])
 // reused by setInstance, so updating every instance of a large mesh each frame allocates nothing
 const scratch = { position: new Vec3(), scale: new Vec3(), quaternion: new Quat(), rotation: new Euler() }
+const SCRATCH_COLOR = new Color()
 const scratchMatrix = new Float32Array(16)
 
+/**
+ * True when an instance is scaled to nothing - hidden: it draws nothing, takes no room in its mesh's
+ * bounds and shows no label.
+ * @internal @param {ArrayLike<number>} m instance matrices @param {number} i
+ */
+export function hiddenInstance(m, i) {
+  const o = i * 16
+  return !m[o] && !m[o + 1] && !m[o + 2] && !m[o + 4] && !m[o + 5] && !m[o + 6] && !m[o + 8] && !m[o + 9] && !m[o + 10]
+}
+
 /**
  * Many copies of one geometry and material, drawn together. Set each copy with setInstance().
- * Picking reports which instance was hit.
+ * Picking reports which instance was hit. An instance scaled to 0 is hidden - it draws nothing, and
+ * framing, culling, shadows and labels leave it out - so a pool of instances can keep spares.
  */
 export class InstancedMesh extends Mesh {
   static type = 'instanced-mesh'
@@ -279,12 +310,12 @@ export class InstancedMesh extends Mesh {
   instanceColors = null
   /** @internal Bumped when instance data changes, so renderers re-upload. */
   version = 0
-  /** A label per instance, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+  /** A label per instance from its row of data - or a list of them, several per instance. @type {ReturnType<typeof instanceLabels>} */
   labels = null
 
   /**
    * @param {DrawableOptions & { count?: number, instances?: InstanceOptions[], instanceMatrices?: ArrayLike<number>,
-   *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | null }} options count defaults to the number
+   *   instanceColors?: ArrayLike<number>, labels?: InstanceLabels | InstanceLabels[] | null }} options count defaults to the number
    *   of instances or rows of data; instanceMatrices/instanceColors are raw data, as toJSON() writes
    */
   constructor(options) {
@@ -375,7 +406,7 @@ export class InstancedMesh extends Mesh {
   /** @param {number} i @param {ColorInput} color */
   #setColor(i, color) {
     if (!this.instanceColors) this.instanceColors = new Float32Array(this.instanceMatrices.length / 16 * 3).fill(1)
-    this.instanceColors.set(Color.fromInput(color, 'InstancedMesh'), i * 3)
+    this.instanceColors.set(SCRATCH_COLOR.set(color, 'InstancedMesh'), i * 3)
   }
 
   /** @internal @param {Box3} box */
@@ -401,6 +432,7 @@ export class InstancedMesh extends Mesh {
     const ex = (local.max[0] - local.min[0]) / 2, ey = (local.max[1] - local.min[1]) / 2, ez = (local.max[2] - local.min[2]) / 2
     const w = this.worldMatrix, im = this.instanceMatrices, m = scratchMatrix
     for (let i = 0; i < this.count; i++) {
+      if (hiddenInstance(im, i)) continue
       mat4.multiply(m, w, im.subarray(i * 16, i * 16 + 16))
       const x = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
       const y = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
@@ -434,20 +466,44 @@ export class InstancedMesh extends Mesh {
 /** Each vertex drawn as a square point sprite: star fields, particles, scatter plots. */
 export class Points extends Drawable {
   static type = 'points'
-  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'labels'] }
+  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'labels', 'sort'] }
 
-  /** A label per point, from its row of data. @type {ReturnType<typeof instanceLabels>} */
+  /** A label per point from its row of data - or a list of them, several per point. @type {ReturnType<typeof instanceLabels>} */
   labels = null
+  /**
+   * Draw the points back to front, furthest first, each frame - for soft points that cover what is
+   * behind them (smoke, with blending 'normal'), which then layer the right way round. Drawn as squares.
+   */
+  sort = false
 
-  /** @param {DrawableOptions & { labels?: InstanceLabels | null }} options */
+  /** @param {DrawableOptions & { labels?: InstanceLabels | InstanceLabels[] | null, sort?: boolean }} options */
   constructor(options) {
     super(options)
     this.labels = instanceLabels(this.constructor.name, options?.labels)
+    if (options?.sort !== undefined) {
+      if (typeof options.sort !== 'boolean') fail(this.constructor.name, `'sort' is true or false, got ${describe(options.sort)}`)
+      this.sort = options.sort
+    }
+  }
+
+  /**
+   * @internal Drawn as squares, one a point, rather than as GL points: when the geometry gives each
+   * point its own size, opacity or angle, or the points are sorted. Squares can be any size and stay
+   * whole at the edge of the view.
+   */
+  get drawsSprites() {
+    const g = this.geometry
+    return this.sort || !!(g.sizes || g.opacities || g.angles)
   }
 
   /** @internal @returns {Record<string, unknown>} */
   cloneOptions() {
-    return { ...super.cloneOptions(), labels: this.labels }
+    return { ...super.cloneOptions(), labels: this.labels, sort: this.sort }
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  jsonOptions() {
+    return { ...super.jsonOptions(), ...(this.sort ? { sort: true } : {}) }
   }
 
   /** @returns {'points'} */
@@ -456,12 +512,52 @@ export class Points extends Drawable {
   }
 }
 
+const ARROWS = ['none', 'start', 'end', 'both']
+
+/**
+ * @typedef {DrawableOptions & { arrows?: 'none' | 'start' | 'end' | 'both', arrowSize?: number }} LinesOptions
+ */
+
 /**
  * Line segments: indices (or consecutive vertices) in pairs. Width is in pixels and works on
- * every platform. edges(geometry) makes a wireframe of any geometry.
+ * every platform. edges(geometry) makes a wireframe of any geometry. Segments each starting where
+ * the one before ended make a chain - a polyline - which dashes run on along and arrowheads finish.
  */
 export class Lines extends Drawable {
   static type = 'lines'
+  static get OPTIONS() { return [...DRAWABLE_OPTIONS, 'arrows', 'arrowSize'] }
+
+  /** Arrowheads at the ends of each chain: at its 'start', its 'end', 'both' or 'none'. @type {'none' | 'start' | 'end' | 'both'} */
+  arrows = 'none'
+  /** Arrowhead length in pixels; 0 sizes them from the material's width. */
+  arrowSize = 0
+
+  /** @param {LinesOptions} options */
+  constructor(options) {
+    super(options)
+    if (options?.arrows !== undefined) this.arrows = /** @type {any} */ (checkOneOf('Lines', 'arrows', options.arrows, ARROWS))
+    if (options?.arrowSize !== undefined) this.arrowSize = Math.max(0, checkNumber('Lines', 'arrowSize', options.arrowSize))
+  }
+
+  /** @internal Which ends get arrowheads, for the shader: 1 the start, 2 the end. */
+  get arrowBits() {
+    return ARROWS.indexOf(this.arrows)
+  }
+
+  /** @internal An arrowhead's length in pixels, before the pixel ratio. @param {number} width */
+  arrowPixels(width) {
+    return this.arrowSize || 6 + width * 3
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  cloneOptions() {
+    return { ...super.cloneOptions(), arrows: this.arrows, arrowSize: this.arrowSize }
+  }
+
+  /** @internal @returns {Record<string, unknown>} */
+  jsonOptions() {
+    return { ...super.jsonOptions(), ...(this.arrows !== 'none' ? { arrows: this.arrows } : {}), ...(this.arrowSize ? { arrowSize: this.arrowSize } : {}) }
+  }
 
   /** @returns {'lines'} */
   get drawMode() {
@@ -505,6 +601,8 @@ export class Label extends Node {
   leader = false
   /** Set at the view's left or right edge, level with its point, or null for by its point. @type {'left' | 'right' | null} */
   edge = null
+  /** Shown only when zoomed in this far: CSS pixels to one world unit at its point; 0 for always. */
+  minScale = 0
 
   /** @param {LabelOptions} options */
   constructor(options) {
@@ -529,7 +627,8 @@ export class Label extends Node {
   /** @internal @returns {Record<string, unknown>} */
   cloneOptions() {
     return { ...super.cloneOptions(), text: this.text, className: this.className, place: this.place,
-      offset: [...this.offset], priority: this.priority, overlap: this.overlap, occlude: this.occlude, leader: this.leader, edge: this.edge }
+      offset: [...this.offset], priority: this.priority, overlap: this.overlap, occlude: this.occlude, leader: this.leader, edge: this.edge,
+      minScale: this.minScale }
   }
 
   /** @internal @returns {Record<string, unknown>} */
@@ -544,6 +643,7 @@ export class Label extends Node {
     if (this.occlude) json.occlude = true
     if (this.leader) json.leader = true
     if (this.edge) json.edge = this.edge
+    if (this.minScale) json.minScale = this.minScale
     return json
   }
 }