phoria2 1.2.0 → 1.4.0

package/src/View.js

@@ -4,6 +4,7 @@ import { DRAG_START, OrbitControl } from './OrbitControl.js'
 import { cameraPreset, fitPoints, framingScale, presetDirection } from './presets.js'
 import { EASES } from './ease.js'
 import { Raycaster } from './Raycaster.js'
+import { pickArea } from './area.js'
 import { ChangeWatch } from './watch.js'
 import { Box3 } from './value/Box3.js'
 import { Color } from './value/Color.js'
@@ -28,6 +29,7 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
 /** @import { ColorInput, Vec3Input } from './types.js' */
 /** @import { Node } from './scene/Node.js' */
 /** @import { Keyboard, KeyboardOptions } from './keyboard.js' */
+/** @import { DebugDraw, DebugOptions } from './debug.js' */
 
 /**
  * @typedef {'auto' | 'always' | 'manual'} RenderMode
@@ -75,6 +77,8 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
  *   text } says what it hears (default: the tooltip's text, the data, or the name). Default false
  * @property {string | null} [description] what the view shows, for screen readers: the canvas's label. With keyboard
  *   on and no description, one is made from the scene (charts describe themselves)
+ * @property {boolean | DebugOptions} [debug] pictures for checking a scene: lights, shadow cameras, bounds,
+ *   normals, axes, the orbit target and a stats readout. true shows all but normals. Default false
  */
 
 /** @typedef {'click' | 'hover'} ViewEvent */
@@ -82,7 +86,12 @@ import { checkOneOf, checkOptions, checkRange, describe, fail, warnOnce } from '
 
 const OPTIONS = ['canvas', 'scene', 'camera', 'orbit', 'background', 'renderMode', 'framing', 'highlight', 'tooltip', 'pixelRatio',
   'antialias', 'outlineAntialias', 'context', 'toneMapping', 'exposure', 'bloom', 'autoLight', 'maxDelta', 'reducedMotion',
-  'keyboard', 'description']
+  'keyboard', 'description', 'debug']
+// what debug: true shows - everything but normals, which bristle on a big model
+/** @type {Required<DebugOptions>} */
+const DEBUG_ALL = { lights: true, shadows: true, bounds: true, normals: false, axes: true, camera: true, stats: 'top-left' }
+const DEBUG_OPTIONS = Object.keys(DEBUG_ALL)
+const CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right']
 const FRAMING_OPTIONS = ['keep', 'aspect']
 const HINTS = {
   renderer: 'the View makes its renderer - read it from view.renderer',
@@ -179,6 +188,12 @@ export class View {
   /** @type {Keyboard | null} */ #keyboard = null
   /** @type {Hit | null} */ #keyFocus = null
   /** @type {string | null} */ #description = null
+  // debug drawing: its code loads when turned on; the helpers are added to each frame, then taken out
+  /** @type {Required<DebugOptions> | null} */ #debug = null
+  /** @type {DebugDraw | null} */ #debugDraw = null
+  #debugLoading = false
+  #drawnAt = 0
+  #frameMs = 0
   // the canvas had no role, so describing it gave it one - taken away again with the description
   #gaveRole = false
   // the system's prefers-reduced-motion, kept up to date
@@ -276,6 +291,7 @@ export class View {
       interactive: (label) => labelHandlers(label, 'click').length > 0 || labelHandlers(label, 'hover').length > 0,
       on: (type, label, e) => this.#labelPointer(type, label, e),
     })
+    if (options.debug !== undefined) this.debug = options.debug
 
     if (options.framing !== undefined) {
       // 'both' is short for { keep: 'both' }
@@ -365,6 +381,32 @@ export class View {
     this.invalidate()
   }
 
+  /**
+   * Debug drawing, or false: what it shows, as DebugOptions. Assign true for everything but normals,
+   * options for some, or false. Its code loads the first time it's turned on.
+   *
+   *     view.debug = { lights: true, shadows: true, bounds: 'hovered', stats: 'bottom-right' }
+   * @returns {boolean | DebugOptions} the options in force, every one given, or false
+   */
+  get debug() { return this.#debug ?? false }
+  /** @param {boolean | DebugOptions} v */
+  set debug(v) {
+    this.#debug = debugOptions(v)
+    if (this.#debug && !this.#debugDraw && !this.#debugLoading) {
+      this.#debugLoading = true
+      import('./debug.js').then(({ DebugDraw }) => {
+        this.#debugLoading = false
+        if (this.#disposed) return
+        this.#debugDraw = new DebugDraw(this.#labels.root)
+        this.invalidate()
+      })
+    }
+    // hovered helpers need the pointer followed
+    if (this.#debug && (this.#debug.bounds === 'hovered' || this.#debug.normals === 'hovered')) this.#pickPending = true
+    if (!this.#debug) this.#debugDraw?.stats(false, /** @type {any} */ ({}), 0, 0)
+    this.invalidate()
+  }
+
   /**
    * What the view shows, for screen readers - the canvas's label - or null. With keyboard on and no
    * description, one is made from the scene.
@@ -510,9 +552,28 @@ export class View {
     this.scene.updateWorldTree()
     const frame = collect(this.scene, this.camera)
     if (this.autoLight && frame.lights.length === 0) this.#addAutoLights(frame)
+    frame.time = this.time
     frame.highlight = this.#highlightFor(this.#hovered)
     this.#occlude(frame)
+    // debug helpers go on the end of the frame for drawing, and come off again after: never picked,
+    // explained or kept in lastFrame
+    const debug = this.#debug && this.#debugDraw
+      ? this.#debugDraw.add(frame, this.#debug, { camera: this.camera, hovered: this.#hovered, bounds: this.scene.boundsFrom(this.camera) })
+      : null
+    const started = performance.now()
     this.renderer.renderFrame(frame, { wait })
+    if (debug) {
+      frame.opaque.length -= debug.opaque
+      frame.transparent.length -= debug.transparent
+    }
+    if (this.#debugDraw) {
+      const now = performance.now()
+      // time between frames drawn one after another, smoothed; after a pause, none
+      const gap = this.#drawnAt ? now - this.#drawnAt : 0
+      this.#frameMs = gap > 0 && gap < 250 ? this.#frameMs * 0.9 + gap * 0.1 : 0
+      this.#drawnAt = now
+      this.#debugDraw.stats(this.#debug?.stats ?? false, this.renderer.info, this.#frameMs, now - started)
+    }
     this.#labelStats = this.#labels.update(frame.labels, frame.overlays)
     // a node with its own tooltip needs the tooltip's code
     if (frame.tooltips && !this.#tooltip) this.#loadTooltip()
@@ -520,7 +581,7 @@ export class View {
     this.#dirty = false
     // remember what was drawn - including what drawing changed, such as fitting the camera - so
     // the next frame compares against it and doesn't draw the same picture again
-    if (this.renderMode === 'auto') this.#watch.changed(this.scene, this.camera)
+    if (this.renderMode === 'auto') this.#watch.changed(this.scene, this.camera, this.time)
     // things may have moved under a still pointer - or the keyboard's focus moved on screen
     if ((this.#pointer || this.#keyFocus) && this.#needsHover()) this.#pickPending = true
     return frame
@@ -731,7 +792,9 @@ export class View {
     const frame = this.lastFrame
     if (!frame) return null
     let work = 0
-    for (const { node, geometry, instances } of [...frame.opaque, ...frame.transparent]) {
+    for (const { node, geometry, instances, material } of [...frame.opaque, ...frame.transparent]) {
+      // a shader hook moves vertices where only the GPU knows: picked there, however small the scene
+      if (material.shader?.vertex) return frame
       const mode = /** @type {any} */ (node).drawMode
       work += instances ? instances.count : mode === 'points' ? geometry.drawnVertices : mode === 'lines' ? geometry.drawnCount / 2 : geometry.drawnCount / 3
     }
@@ -747,7 +810,8 @@ export class View {
   #exact(found, frame) {
     const node = /** @type {any} */ (found.item.node)
     const raycaster = new Raycaster().setFromCamera(found.ndc, this.camera)
-    const hit = raycaster.intersectElement(node, found.element)
+    // moved by a shader hook, the CPU's copy isn't where it was drawn: the GPU's depth is the hit
+    const hit = node.material.shader?.vertex ? null : raycaster.intersectElement(node, found.element)
     if (hit) return hit
     // the ray grazed an edge the GPU drew: place the hit at the depth the GPU found
     const inverse = new Mat4().copy(frame.camera.viewProjection).invert()
@@ -803,6 +867,21 @@ export class View {
     return new Mat4().multiplyMatrices(camera.projectionMatrix, camera.viewMatrix)
   }
 
+  /**
+   * Everything inside an area of the canvas, nearest first: a box `{ x, y, width, height }` or a
+   * lasso of `[x, y]` points, CSS pixels from the canvas's top left. Each point, instance and line
+   * segment is its own hit, found by where it is (a mesh by its middle) - hidden behind others or
+   * not - so a box dragged over a scatter selects that region of it.
+   *
+   *     const picked = view.pickArea({ x: 40, y: 30, width: 200, height: 120 }).map((h) => h.datum)
+   * @param {import('./area.js').PickArea} area
+   * @returns {Hit[]}
+   */
+  pickArea(area) {
+    this.scene.updateWorldTree()
+    return pickArea(this.scene, this.camera, this.#viewProjection(), this.#width, this.#height, area)
+  }
+
   /** Every hit under a canvas position, nearest first. @param {number | MouseEvent} x @param {number} [y] @returns {Hit[]} */
   pickAll(x, y) {
     if (typeof x === 'object') {
@@ -961,6 +1040,7 @@ export class View {
       contextLost: !!this.renderer.gl?.isContextLost?.(),
       interaction: { hover: this.#handlers.hover.size, click: this.#handlers.click.size, tooltip: !!this.#tooltipContent, highlight: !!this.#highlight,
         keyboard: !!this.#keyboard, reducedMotion: this.reducedMotion, description: this.canvas.getAttribute?.('aria-label') ?? this.#description },
+      debug: this.#debug,
     })
   }
 
@@ -978,6 +1058,7 @@ export class View {
     this.#labels.dispose()
     this.#tooltip?.dispose()
     this.#keyboard?.dispose()
+    this.#debugDraw?.dispose()
     if (this.#description !== null && !this.#keyboard) this.description = null
     this.renderer.dispose(this.scene)
     if (this.#ownContext) ownContexts--
@@ -1025,7 +1106,7 @@ export class View {
       this.#updateControls(dt)
       if (this.#pickPending) this.#updateHover()
       const draw = this.#dirty || this.renderMode === 'always' ||
-        (this.renderMode === 'auto' && this.#watch.changed(this.scene, this.camera))
+        (this.renderMode === 'auto' && this.#watch.changed(this.scene, this.camera, this.time))
       if (draw) this.render()
     } finally {
       // the next frame comes even if this one threw - the error still reaches the console, but one
@@ -1036,7 +1117,12 @@ export class View {
 
   #needsHover() {
     return this.#handlers.hover.size > 0 || !!this.#tooltipContent || !!this.#highlight || this.#handlers.click.size > 0 ||
-      !!this.lastFrame?.interactive
+      !!this.lastFrame?.interactive || this.#debugHovers()
+  }
+
+  /** Does debug draw something for what is under the pointer? */
+  #debugHovers() {
+    return !!this.#debug && (this.#debug.bounds === 'hovered' || this.#debug.normals === 'hovered')
   }
 
   // pick under the pointer and tell everyone when the thing under it changes - on the GPU without
@@ -1081,7 +1167,7 @@ export class View {
     if (p && hit && this.#tooltip) this.#tooltip.show(hit, p.clientX, p.clientY)
     else this.#tooltip?.hide()
     if (same) return
-    if (this.#highlightFor(before) || this.#highlightFor(hit)) this.invalidate()
+    if (this.#highlightFor(before) || this.#highlightFor(hit) || this.#debugHovers()) this.invalidate()
     if (this.#handlers.click.size || this.lastFrame?.interactive) {
       this.canvas.style.cursor = hit && nearestAbove(hit.node, 'onDrag') ? 'grab' : hit && this.#clickable(hit) ? 'pointer' : ''
     }
@@ -1474,3 +1560,31 @@ function resolveCanvas(canvas) {
   if (!(canvas instanceof HTMLCanvasElement)) fail('View', `'canvas' must be a <canvas> element or a selector, got ${describe(canvas)}`)
   return canvas
 }
+
+/**
+ * Debug options checked: true for everything but normals, false or null for none.
+ * @param {boolean | DebugOptions | null} v
+ * @returns {Required<DebugOptions> | null}
+ */
+function debugOptions(v) {
+  if (v === false || v === null) return null
+  if (v === true) return { ...DEBUG_ALL }
+  if (!v || typeof v !== 'object' || Array.isArray(v)) fail('View', `'debug' is true, false or { ${DEBUG_OPTIONS.join(', ')} }, got ${describe(v)}`)
+  checkOptions('View', v, DEBUG_OPTIONS, { helpers: "list what to draw: { lights: true, bounds: true, ... }", fps: "use 'stats: true'", wireframe: "use new Lines({ geometry: edges(geometry) }) for a wireframe" }, 'debug')
+  /** @type {any} */
+  const o = {}
+  for (const key of DEBUG_OPTIONS) {
+    const value = /** @type {any} */ (v)[key]
+    if (value === undefined) o[key] = false
+    else if (key === 'bounds' || key === 'normals') o[key] = value === 'hovered' ? 'hovered' : checkBool(key, value, "true, false or 'hovered'")
+    else if (key === 'stats') o[key] = value === true ? 'top-left' : value === false ? false : checkOneOf('View', 'debug.stats', value, CORNERS)
+    else o[key] = checkBool(key, value, 'true or false')
+  }
+  return o
+}
+
+/** @param {string} key @param {unknown} v @param {string} expected */
+function checkBool(key, v, expected) {
+  if (typeof v !== 'boolean') fail('View', `debug.${key} is ${expected}, got ${describe(v)}`)
+  return v
+}

package/src/area.js

@@ -0,0 +1,131 @@
+// Picking an area of the canvas: everything whose place on screen falls inside a box or a lasso drawn
+// over it - each point, instance and line segment on its own, and a mesh by its middle. Positions
+// are tested, not surfaces, so what is hidden behind other things is found too: selecting a region
+// of a scatter takes the whole region, front to back.
+import * as mat4 from './math/mat4.js'
+import { hiddenInstance } from './scene/drawables.js'
+import { Vec3 } from './value/Vec3.js'
+import { describe, fail } from './validate.js'
+
+/** @import { Hit } from './Raycaster.js' */
+/** @import { Node } from './scene/Node.js' */
+/** @import { Camera } from './scene/cameras.js' */
+
+/**
+ * A box on the canvas, CSS pixels from its top left - width and height may be negative, as a drag
+ * up or left makes them - or a lasso: the points of a polygon, [x, y] each.
+ * @typedef {{ x: number, y: number, width: number, height: number } | [number, number][]} PickArea
+ */
+
+const instanceWorld = new Float32Array(16)
+
+/**
+ * The polygon an area is, and its bounding box, for the inside test.
+ * @param {PickArea} area
+ * @returns {{ points: number[], left: number, top: number, right: number, bottom: number }}
+ */
+function outline(area) {
+  /** @type {number[]} */
+  let points
+  if (Array.isArray(area)) {
+    if (area.length < 3 || !area.every((p) => Array.isArray(p) && p.length === 2 && p.every(Number.isFinite))) {
+      fail('View', `pickArea() takes a box { x, y, width, height } or a lasso of three or more [x, y] points, got ${describe(area)}`)
+    }
+    points = area.flat()
+  } else {
+    const { x, y, width, height } = area ?? /** @type {any} */ ({})
+    if (![x, y, width, height].every(Number.isFinite)) {
+      fail('View', `pickArea() takes a box { x, y, width, height } or a lasso of three or more [x, y] points, got ${describe(area)}`)
+    }
+    points = [x, y, x + width, y, x + width, y + height, x, y + height]
+  }
+  let left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity
+  for (let i = 0; i < points.length; i += 2) {
+    left = Math.min(left, points[i])
+    right = Math.max(right, points[i])
+    top = Math.min(top, points[i + 1])
+    bottom = Math.max(bottom, points[i + 1])
+  }
+  return { points, left, top, right, bottom }
+}
+
+/** Is (x, y) inside the polygon? Even-odd crossings. @param {number[]} p @param {number} x @param {number} y */
+function inside(p, x, y) {
+  let into = false
+  for (let i = 0, j = p.length - 2; i < p.length; j = i, i += 2) {
+    const yi = p[i + 1], yj = p[j + 1]
+    if ((yi > y) !== (yj > y) && x < p[i] + (p[j] - p[i]) * (y - yi) / (yj - yi)) into = !into
+  }
+  return into
+}
+
+/**
+ * Everything in the scene the camera shows, pickable, whose place falls inside the area - nearest
+ * the camera first.
+ * @param {Node} scene @param {Camera} camera @param {Float32Array} viewProjection
+ * @param {number} width @param {number} height the canvas, CSS pixels
+ * @param {PickArea} area
+ * @returns {Hit[]}
+ */
+export function pickArea(scene, camera, viewProjection, width, height, area) {
+  const shape = outline(area)
+  const eye = camera.worldPosition
+  const m = viewProjection
+  /** @type {Hit[]} */
+  const hits = []
+  /** World position (x, y, z) inside the area? @param {number} x @param {number} y @param {number} z */
+  const within = (x, y, z) => {
+    const w = m[3] * x + m[7] * y + m[11] * z + m[15]
+    if (w <= 0) return false
+    const nz = (m[2] * x + m[6] * y + m[10] * z + m[14]) / w
+    if (nz < -1 || nz > 1) return false
+    const sx = ((m[0] * x + m[4] * y + m[8] * z + m[12]) / w * 0.5 + 0.5) * width
+    const sy = (0.5 - (m[1] * x + m[5] * y + m[9] * z + m[13]) / w * 0.5) * height
+    return sx >= shape.left && sx <= shape.right && sy >= shape.top && sy <= shape.bottom && inside(shape.points, sx, sy)
+  }
+  /** @param {any} node @param {number} x @param {number} y @param {number} z @param {number | null} face @param {number | null} instance */
+  const hit = (node, x, y, z, face, instance) => {
+    const point = new Vec3(x, y, z)
+    hits.push({ node, point, distance: point.distanceTo(eye), normal: null, face, instance, uv: null, datum: node.datumAt(instance ?? face) })
+  }
+  const p = new Vec3()
+
+  /** @param {Node} node */
+  const visit = (node) => {
+    if (!node.shownTo(camera) || !node.pickable) return
+    const n = /** @type {any} */ (node)
+    if (n.isDrawable && n.geometry.vertexCount) {
+      const g = n.geometry, world = n.worldMatrix
+      if (n.drawMode === 'points') {
+        const pos = g.positions
+        for (let i = 0; i < g.drawnVertices; i++) {
+          p.set(pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2]).applyMatrix4(world)
+          if (within(p[0], p[1], p[2])) hit(n, p[0], p[1], p[2], i, null)
+        }
+      } else if (n.drawMode === 'lines') {
+        // a segment by its middle
+        const pos = g.positions, idx = g.indices
+        for (let s = 0; s < Math.floor(g.drawnCount / 2); s++) {
+          const a = idx ? idx[s * 2] : s * 2, b = idx ? idx[s * 2 + 1] : s * 2 + 1
+          p.set((pos[a * 3] + pos[b * 3]) / 2, (pos[a * 3 + 1] + pos[b * 3 + 1]) / 2, (pos[a * 3 + 2] + pos[b * 3 + 2]) / 2).applyMatrix4(world)
+          if (within(p[0], p[1], p[2])) hit(n, p[0], p[1], p[2], s, null)
+        }
+      } else if (n.instanceMatrices) {
+        // each instance by the middle of its copy of the geometry; hidden ones aren't there
+        const centre = g.bounds.getCenter()
+        for (let i = 0; i < n.count; i++) {
+          if (hiddenInstance(n.instanceMatrices, i)) continue
+          mat4.multiply(instanceWorld, world, n.instanceMatrices.subarray(i * 16, i * 16 + 16))
+          p.copy(centre).applyMatrix4(instanceWorld)
+          if (within(p[0], p[1], p[2])) hit(n, p[0], p[1], p[2], null, i)
+        }
+      } else {
+        p.copy(g.bounds.getCenter()).applyMatrix4(world)
+        if (within(p[0], p[1], p[2])) hit(n, p[0], p[1], p[2], null, null)
+      }
+    }
+    for (const child of node.children) visit(child)
+  }
+  visit(scene)
+  return hits.sort((a, b) => a.distance - b.distance)
+}

package/src/charts/marks.js

@@ -3,6 +3,7 @@
 // lay out and draw, never animate.
 import { Geometry } from '../geometry/Geometry.js'
 import { box as boxGeometry, icosphere } from '../geometry/generators.js'
+import { Texture } from '../material/Texture.js'
 import { InstancedMesh, Lines, Mesh, Points } from '../scene/drawables.js'
 import { fail } from '../validate.js'
 import { distinct } from './scales.js'
@@ -154,8 +155,10 @@ export function pointMark(ctx) {
   /** @type {any} */
   let node = sized
     ? new InstancedMesh({ geometry: icosphere({ radius: 1, detail: 1 }), material, count: 64, labels: labelsOf(ctx, 'above') })
-    : new Points({ geometry: emptyPoints(64), material: { size: ctx.spec.channels.size?.value ?? unit * 1.4, vertexColors: true, ...material },
-      labels: labelsOf(ctx, 'above') })
+    // dots with a darker rim, so each one reads where they crowd together - drawn furthest first, so
+    // each blends over the ones behind it
+    : new Points({ geometry: emptyPoints(64), material: { size: ctx.spec.channels.size?.value ?? unit * 1.4, vertexColors: true, map: dot(), depthWrite: false, ...material },
+      sort: true, labels: labelsOf(ctx, 'above') })
   if (sized) node.count = 0
   const mark = {
     nodes: [node],
@@ -205,6 +208,30 @@ export function pointMark(ctx) {
   return mark
 }
 
+/** @type {Texture | null} */
+let dotTexture = null
+
+/**
+ * A dot: a white disc whose outer part darkens to a rim, with a soft edge - pixels of its own, so
+ * charts need no canvas to make it. Shared by every scatter.
+ */
+function dot() {
+  if (dotTexture) return dotTexture
+  const size = 64, data = new Uint8Array(size * size * 4), r = size / 2
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const d = Math.hypot(x + 0.5 - r, y + 0.5 - r) / r
+      // the colour full to 0.78 of the radius, then down to 0.62 at the edge; alpha soft over the last pixel and a half
+      const shade = d < 0.78 ? 1 : 1 - (d - 0.78) / 0.22 * 0.38
+      const alpha = Math.min(1, Math.max(0, (1 - d) * r / 1.5))
+      const o = (y * size + x) * 4
+      data[o] = data[o + 1] = data[o + 2] = Math.round(shade * 255)
+      data[o + 3] = Math.round(alpha * 255)
+    }
+  }
+  return (dotTexture = new Texture({ image: { data, width: size, height: size } }))
+}
+
 /** @param {number} n */
 function emptyPoints(n) {
   const g = new Geometry({ positions: new Float32Array(n * 3), colors: new Float32Array(n * 3) })