asciify-engine 1.0.38 → 1.0.40

package/dist/index.d.cts

@@ -79,6 +79,24 @@ interface AsciiOptions {
      * `0` = no dithering, `1` = full dithering. Default: `0`
      */
     ditherStrength: number;
+    /**
+     * Assumed aspect ratio (width ÷ height) of a single output character.
+     * Controls how many rows vs columns are generated — must match your rendering
+     * environment to preserve the source image's proportions.
+     * - `0.55` — browser monospace at `line-height: 1.09` (default)
+     * - `0.52` — browser monospace at `line-height: 1.15`
+     * - `0.5`  — most terminal emulators
+     * Default: `0.55`
+     */
+    charAspect: number;
+    /**
+     * Auto-stretch the luminance range before charset mapping.
+     * When `true`, the darkest pixel in the frame maps to the first charset character
+     * and the brightest to the last, maximising perceived detail and contrast.
+     * Particularly useful for images with low inherent contrast or muted tones.
+     * Default: `false`
+     */
+    normalize: boolean;
     /**
      * Overall intensity of the hover / cursor interaction effect.
      * `0` disables the effect. Default: `0`

package/dist/index.d.ts

@@ -79,6 +79,24 @@ interface AsciiOptions {
      * `0` = no dithering, `1` = full dithering. Default: `0`
      */
     ditherStrength: number;
+    /**
+     * Assumed aspect ratio (width ÷ height) of a single output character.
+     * Controls how many rows vs columns are generated — must match your rendering
+     * environment to preserve the source image's proportions.
+     * - `0.55` — browser monospace at `line-height: 1.09` (default)
+     * - `0.52` — browser monospace at `line-height: 1.15`
+     * - `0.5`  — most terminal emulators
+     * Default: `0.55`
+     */
+    charAspect: number;
+    /**
+     * Auto-stretch the luminance range before charset mapping.
+     * When `true`, the darkest pixel in the frame maps to the first charset character
+     * and the brightest to the last, maximising perceived detail and contrast.
+     * Particularly useful for images with low inherent contrast or muted tones.
+     * Default: `false`
+     */
+    normalize: boolean;
     /**
      * Overall intensity of the hover / cursor interaction effect.
      * `0` disables the effect. Default: `0`

package/dist/index.js

@@ -110,6 +110,8 @@ var DEFAULT_OPTIONS = {
   animationSpeed: 1,
   dotSizeRatio: 0.8,
   ditherStrength: 0,
+  charAspect: 0.55,
+  normalize: false,
   hoverStrength: 0,
   hoverRadius: 0.2,
   hoverEffect: "spotlight",
@@ -604,7 +606,7 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
   if (srcWidth === 0 || srcHeight === 0) {
     return { frame: [], cols: 0, rows: 0 };
   }
-  const charAspect = 0.55;
+  const charAspect = options.charAspect;
   const cellW = options.fontSize * options.charSpacing;
   const cellH = options.fontSize / charAspect * options.charSpacing;
   const renderW = targetWidth || srcWidth;
@@ -618,6 +620,18 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
   ctx.drawImage(source, 0, 0, cols, rows);
   const imageData = ctx.getImageData(0, 0, cols, rows);
   const pixels = imageData.data;
+  let normMin = 0;
+  let normRange = 255;
+  if (options.normalize) {
+    let lo = 255, hi = 0;
+    for (let k = 0; k < pixels.length; k += 4) {
+      const l = 0.299 * pixels[k] + 0.587 * pixels[k + 1] + 0.114 * pixels[k + 2];
+      if (l < lo) lo = l;
+      if (l > hi) hi = l;
+    }
+    normMin = lo;
+    normRange = hi > lo ? hi - lo : 255;
+  }
   const frame = [];
   for (let y = 0; y < rows; y++) {
     const row = [];
@@ -627,7 +641,8 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
       const g = pixels[i + 1];
       const b = pixels[i + 2];
       const a = pixels[i + 3];
-      const lum = 0.299 * r + 0.587 * g + 0.114 * b;
+      const rawLum = 0.299 * r + 0.587 * g + 0.114 * b;
+      const lum = options.normalize ? (rawLum - normMin) / normRange * 255 : rawLum;
       const adjustedLum = adjustLuminance(lum, options.brightness, options.contrast);
       const ditheredLum = applyDither(adjustedLum, x, y, options.ditherStrength);
       const char = options.customText ? customTextToChar(ditheredLum, options.customText, x, y, cols, options.invert) : luminanceToChar(ditheredLum, options.charset, options.invert);