@zumer/snapdom-plugins 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Plugin changes
 
+## 4.2.0
+
+- Export asciiFromCanvas(source, options) from @zumer/snapdom-plugins/ascii-export: the ASCII conversion on its own, for a canvas, an image, a video frame or a stream frame. toAscii() keeps its output.
+- Add asciiStream(element, options): stream() plus asciiFromCanvas() on every frame, with onText(text, frame).
+
+Requires SnapDOM 3.4.0 or newer within 3.x.
+
 ## 4.1.0
 
 - Add the stream plugin at @zumer/snapdom-plugins/stream: a live canvas that mirrors an element and repaints only the boxes that changed, for WebGL textures, video overlays and WebRTC tracks.

package/README.md

@@ -1,7 +1,7 @@
 # @zumer/snapdom-plugins
 
-Official plugins for [SnapDOM](https://github.com/zumerlab/snapdom), a high-performance engine
-for capturing, modifying, and converting DOM elements into any format. Core exports images and
+Official plugins for [SnapDOM](https://github.com/zumerlab/snapdom), a high-performance DOM engine
+that exports a rendered element as PNG, SVG or canvas in the browser. Core exports images and
 canvases; this package adds HTML, structured context, element maps, PDF, editable vectors, ASCII,
 visual transforms, live GIF/video recording and live DOM streaming.
 

package/ascii-export.d.ts

@@ -6,6 +6,7 @@
  * at capture time.
  */
 import type { SnapdomPlugin } from '@zumer/snapdom';
+import type { Stream, StreamOptions, StreamFrame } from './stream.js';
 
 export interface AsciiExportOptions {
   /** Character width of the output. */
@@ -23,8 +24,17 @@ export interface AsciiExportOptions {
 /** Adds `result.toAscii()`. */
 export declare function asciiExport(options?: AsciiExportOptions): SnapdomPlugin;
 
+/** ASCII art from any drawable (a canvas, an image, a video frame, a `stream()` frame). No capture involved. */
+export declare function asciiFromCanvas(source: CanvasImageSource & { width: number; height: number }, options?: AsciiExportOptions & { charset?: string | string[] }): string;
+
 declare module '@zumer/snapdom' {
   interface CaptureResult {
     toAscii(options?: AsciiExportOptions): Promise<string>;
   }
 }
+
+/** `stream()` plus `asciiFromCanvas()` on every frame; `onText` receives the text (or HTML when `format: 'html'`). */
+export declare function asciiStream(
+  element: Element,
+  options?: AsciiExportOptions & { charset?: string | string[] } & StreamOptions & { onText?: (text: string, frame: StreamFrame) => void }
+): Stream;

package/ascii-export.js

@@ -12,6 +12,8 @@
  * @param {number} [options.contrast=0] - Non-negative luminance contrast boost
  * @returns {Object} SnapDOM plugin
  */
+import { stream } from './stream.js';
+
 export function asciiExport(options = {}) {
   const {
     width: charWidth = 80,
@@ -46,35 +48,76 @@ export function asciiExport(options = {}) {
             ...opts, width: ctx.width, height: ctx.height, scale: 1, dpr: 1, canvas: null,
             backgroundColor: !opts.backgroundColor || opts.backgroundColor === 'transparent' ? '#ffffff' : opts.backgroundColor,
           });
-          const rows = Math.max(1, Math.round(cols * source.height / source.width * 0.5));
-          const canvas = document.createElement('canvas');
-          canvas.width = cols;
-          canvas.height = rows;
-          const c = canvas.getContext('2d');
-          // Squash the bitmap, not the SVG viewport: Firefox preserves its viewBox aspect ratio.
-          c.drawImage(source, 0, 0, cols, rows);
-          const data = c.getImageData(0, 0, cols, rows).data;
-
-          const colored = outputFormat === 'html';
-          let ascii = colored ? '<pre style="margin:0;font:7px/1 monospace;white-space:pre;overflow-wrap:normal;max-width:100%;overflow:auto;background:white">' : '';
-          for (let y = 0; y < rows; y++) {
-            for (let x = 0; x < cols; x++) {
-              const i = (y * cols + x) * 4;
-              let lum = 1 - (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) / 255;
-              lum = Math.max(0, Math.min(1, (1 + gain) * (lum - 0.5) + 0.5));
-              if (inv) lum = 1 - lum;
-              const ci = Math.min(Math.floor(lum * chars.length), chars.length - 1);
-              const char = chars[ci];
-              if (colored) {
-                const safe = char.replace(/[&<>]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
-                ascii += `<span style="color:rgb(${data[i]},${data[i + 1]},${data[i + 2]})">${safe}</span>`;
-              } else ascii += char;
-            }
-            ascii += '\n';
-          }
-          return colored ? ascii + '</pre>' : ascii;
+          return asciiFromCanvas(source, { width: cols, charset: chars, invert: inv, format: outputFormat, contrast: gain });
         }
       };
     }
   };
 }
+
+/**
+ * Convert any drawable (canvas, image, video frame) to ASCII art. Pure pixel work, no capture:
+ * use it on a `stream()` frame, a video element or a canvas of your own.
+ * @param {CanvasImageSource & { width: number, height: number }} source
+ * @param {Object} [options]
+ * @param {number} [options.width=80] - Character width of output
+ * @param {string|string[]} [options.charset=' .:-=+*#%@'] - Characters from lightest to darkest
+ * @param {boolean} [options.invert=false]
+ * @param {'text'|'html'} [options.format='text']
+ * @param {number} [options.contrast=0]
+ * @returns {string}
+ */
+export function asciiFromCanvas(source, options = {}) {
+  const cols = Math.max(1, Math.floor(options.width ?? 80));
+  const chars = Array.isArray(options.charset) ? options.charset : Array.from(options.charset ?? ' .:-=+*#%@');
+  const inv = options.invert ?? false;
+  const colored = options.format === 'html';
+  const gain = options.contrast ?? 0;
+  const srcW = source.videoWidth || source.naturalWidth || source.width;
+  const srcH = source.videoHeight || source.naturalHeight || source.height;
+  const rows = Math.max(1, Math.round(cols * srcH / srcW * 0.5));
+  const canvas = document.createElement('canvas');
+  canvas.width = cols;
+  canvas.height = rows;
+  const c = canvas.getContext('2d', { willReadFrequently: true });
+  // Squash the bitmap, not the SVG viewport: Firefox preserves its viewBox aspect ratio.
+  c.drawImage(source, 0, 0, cols, rows);
+  const data = c.getImageData(0, 0, cols, rows).data;
+
+  let ascii = colored ? '<pre style="margin:0;font:7px/1 monospace;white-space:pre;overflow-wrap:normal;max-width:100%;overflow:auto;background:white">' : '';
+  for (let y = 0; y < rows; y++) {
+    for (let x = 0; x < cols; x++) {
+      const i = (y * cols + x) * 4;
+      let lum = 1 - (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) / 255;
+      lum = Math.max(0, Math.min(1, (1 + gain) * (lum - 0.5) + 0.5));
+      if (inv) lum = 1 - lum;
+      const ci = Math.min(Math.floor(lum * chars.length), chars.length - 1);
+      const char = chars[ci];
+      if (colored) {
+        const safe = char.replace(/[&<>]/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[ch]));
+        ascii += `<span style="color:rgb(${data[i]},${data[i + 1]},${data[i + 2]})">${safe}</span>`;
+      } else ascii += char;
+    }
+    ascii += '\n';
+  }
+  return colored ? ascii + '</pre>' : ascii;
+}
+
+/**
+ * Stream a live element as ASCII: `stream()` keeps a canvas in step with the element and every
+ * frame is converted with `asciiFromCanvas()`. Returns the stream handle (`ready`, `stats`, `stop()`).
+ * @param {Element} element
+ * @param {Object} [options] - ascii options (width, charset, invert, format, contrast) plus stream
+ *   options (fps, scale, plugins, ...) and `onText(text, frame)`, called after each repaint.
+ */
+export function asciiStream(element, options = {}) {
+  const { width, charset, invert, format, contrast, onText, onFrame, ...streamOptions } = options;
+  const ascii = { width, charset, invert, format, contrast };
+  return stream(element, {
+    ...streamOptions,
+    onFrame(frame) {
+      onFrame?.(frame);
+      onText?.(asciiFromCanvas(frame.canvas, ascii), frame);
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom-plugins",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Official plugins for SnapDOM",
   "type": "module",
   "scripts": {