pagyra-js 0.0.1

package/src/pdf/font/glyph-atlas-maxrects.ts

@@ -0,0 +1,305 @@
+/**
+ * MaxRects glyph atlas packer (separate module).
+ *
+ * Implements MaxRects (Best Short Side Fit) packing with basic free-rect
+ * splitting and pruning. This lives alongside the existing shelf packer so
+ * we can switch to it safely and run tests incrementally.
+ *
+ * API mirrors glyph-atlas.ts: GlyphAtlasMaxRects with pack/getPages/getPlacement.
+ */
+
+export interface AtlasPlacement {
+  readonly pageIndex: number;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface AtlasPage {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array; // RGBA
+}
+
+type Key = string;
+
+const DEFAULT_PAGE_SIZE = 2048;
+const DEFAULT_PADDING = 3;
+
+class Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  constructor(x: number, y: number, w: number, h: number) {
+    this.x = x; this.y = y; this.width = w; this.height = h;
+  }
+}
+
+function fnv1a32(buf: Uint8Array): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < buf.length; i++) {
+    h ^= buf[i];
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+export class GlyphAtlasMaxRects {
+  private pageSize: number;
+  private padding: number;
+  private pages: {
+    width: number;
+    height: number;
+    data: Uint8Array;
+    freeRects: Rect[];
+    usedArea: number;
+    lastUsed: number;
+  }[] = [];
+  private placements = new Map<Key, AtlasPlacement>();
+  private hashIndex = new Map<number, AtlasPlacement[]>();
+
+  // Eviction / memory control (LRU)
+  private maxPages = 8;
+  setMaxPages(n: number) {
+    if (!Number.isFinite(n) || n < 1) return;
+    this.maxPages = Math.max(1, Math.floor(n));
+    this.evictIfNeeded();
+  }
+
+  constructor(pageSize = DEFAULT_PAGE_SIZE, padding = DEFAULT_PADDING) {
+    this.pageSize = Math.max(128, Math.floor(pageSize));
+    this.padding = Math.max(0, Math.floor(padding));
+  }
+
+  setPageSize(px: number) {
+    if (!Number.isFinite(px) || px <= 0) return;
+    this.pageSize = Math.max(128, Math.floor(px));
+  }
+
+  setPadding(p: number) {
+    this.padding = Math.max(0, Math.floor(p));
+  }
+
+  clear() {
+    this.pages = [];
+    this.placements.clear();
+    this.hashIndex.clear();
+  }
+
+  getPages(): AtlasPage[] {
+    return this.pages.map(p => ({ width: p.width, height: p.height, data: p.data.slice() }));
+  }
+
+  has(key: Key) { return this.placements.has(key); }
+  getPlacement(key: Key): AtlasPlacement | null { return this.placements.get(key) ?? null; }
+  stats() { return { pages: this.pages.length, placements: this.placements.size }; }
+
+  pack(key: Key, mask: Uint8ClampedArray, w: number, h: number): AtlasPlacement | null {
+    if (this.placements.has(key)) return this.placements.get(key)!;
+    if (!mask || mask.length !== w * h) return null;
+
+    const rw = w + this.padding * 2;
+    const rh = h + this.padding * 2;
+    if (rw <= 0 || rh <= 0) return null;
+
+    // dedupe
+    const hash = fnv1a32(new Uint8Array(mask.buffer, mask.byteOffset, mask.byteLength));
+    const candList = this.hashIndex.get(hash);
+    if (candList) {
+      for (const cand of candList) {
+        const page = this.pages[cand.pageIndex];
+        if (!page) continue;
+        let equal = true;
+        for (let row = 0; row < h && equal; row++) {
+          const srcOff = row * w;
+          const dstRow = (cand.y + row) * page.width;
+          for (let col = 0; col < w; col++) {
+            const di = (dstRow + (cand.x + col)) * 4 + 3;
+            if (mask[srcOff + col] !== page.data[di]) { equal = false; break; }
+          }
+        }
+        if (equal) { this.placements.set(key, cand); return cand; }
+      }
+    }
+
+    // try existing pages
+    for (let pi = 0; pi < this.pages.length; pi++) {
+      const page = this.pages[pi];
+      const node = this.findPosition(page.freeRects, rw, rh);
+      if (node) {
+        const dstX = node.x + this.padding;
+        const dstY = node.y + this.padding;
+        this.blitToPage(page.data, page.width, page.height, dstX, dstY, mask, w, h);
+        page.usedArea += rw * rh;
+        page.lastUsed = Date.now();
+        this.splitFreeRectangles(node, page.freeRects);
+        this.pruneFreeList(page.freeRects);
+        const placement: AtlasPlacement = { pageIndex: pi, x: dstX, y: dstY, width: w, height: h };
+        this.placements.set(key, placement);
+        const list = this.hashIndex.get(hash) ?? [];
+        list.push(placement);
+        this.hashIndex.set(hash, list);
+        return placement;
+      }
+    }
+
+    // create new page
+    const pageW = this.pageSize, pageH = this.pageSize;
+    if (rw > pageW || rh > pageH) return null;
+    const data = new Uint8Array(pageW * pageH * 4);
+    const freeRects: Rect[] = [new Rect(0, 0, pageW, pageH)];
+    const page = { width: pageW, height: pageH, data, freeRects, usedArea: 0, lastUsed: Date.now() };
+    this.pages.push(page);
+    // enforce max pages after adding
+    this.evictIfNeeded();
+
+    const node = this.findPosition(page.freeRects, rw, rh);
+    if (!node) return null;
+    const dstX = node.x + this.padding;
+    const dstY = node.y + this.padding;
+    this.blitToPage(page.data, page.width, page.height, dstX, dstY, mask, w, h);
+    page.usedArea += rw * rh;
+    page.lastUsed = Date.now();
+    this.splitFreeRectangles(node, page.freeRects);
+    this.pruneFreeList(page.freeRects);
+    const placement: AtlasPlacement = { pageIndex: this.pages.length - 1, x: dstX, y: dstY, width: w, height: h };
+    this.placements.set(key, placement);
+    const list = this.hashIndex.get(hash) ?? [];
+    list.push(placement);
+    this.hashIndex.set(hash, list);
+    this.evictIfNeeded();
+    return placement;
+  }
+
+  // Best Short Side Fit
+  private findPosition(freeRects: Rect[], width: number, height: number): Rect | null {
+    let bestRect: Rect | null = null;
+    let bestShort = Infinity;
+    let bestLong = Infinity;
+    for (const r of freeRects) {
+      if (r.width >= width && r.height >= height) {
+        const leftoverW = r.width - width;
+        const leftoverH = r.height - height;
+        const shortSide = Math.min(leftoverW, leftoverH);
+        const longSide = Math.max(leftoverW, leftoverH);
+        if (shortSide < bestShort || (shortSide === bestShort && longSide < bestLong)) {
+          bestShort = shortSide; bestLong = longSide;
+          bestRect = new Rect(r.x, r.y, width, height);
+        }
+      }
+      // rotated
+      if (r.width >= height && r.height >= width) {
+        const leftoverW = r.width - height;
+        const leftoverH = r.height - width;
+        const shortSide = Math.min(leftoverW, leftoverH);
+        const longSide = Math.max(leftoverW, leftoverH);
+        if (shortSide < bestShort || (shortSide === bestShort && longSide < bestLong)) {
+          bestShort = shortSide; bestLong = longSide;
+          bestRect = new Rect(r.x, r.y, height, width);
+        }
+      }
+    }
+    return bestRect;
+  }
+
+  private splitFreeRectangles(placed: Rect, freeRects: Rect[]) {
+    const toAdd: Rect[] = [];
+    for (let i = freeRects.length - 1; i >= 0; i--) {
+      const r = freeRects[i];
+      if (!this.intersect(r, placed)) continue;
+      freeRects.splice(i, 1);
+      if (placed.x > r.x && placed.x < r.x + r.width) toAdd.push(new Rect(r.x, r.y, placed.x - r.x, r.height));
+      if (placed.x + placed.width < r.x + r.width) toAdd.push(new Rect(placed.x + placed.width, r.y, (r.x + r.width) - (placed.x + placed.width), r.height));
+      if (placed.y > r.y && placed.y < r.y + r.height) toAdd.push(new Rect(r.x, r.y, r.width, placed.y - r.y));
+      if (placed.y + placed.height < r.y + r.height) toAdd.push(new Rect(r.x, placed.y + placed.height, r.width, (r.y + r.height) - (placed.y + placed.height)));
+    }
+    for (const nr of toAdd) if (nr.width > 0 && nr.height > 0) freeRects.push(nr);
+  }
+
+  private pruneFreeList(freeRects: Rect[]) {
+    for (let i = 0; i < freeRects.length; i++) {
+      for (let j = i + 1; j < freeRects.length; j++) {
+        const a = freeRects[i], b = freeRects[j];
+        if (this.isContained(a, b)) { freeRects.splice(i, 1); i--; break; }
+        if (this.isContained(b, a)) { freeRects.splice(j, 1); j--; }
+      }
+    }
+  }
+
+  private intersect(a: Rect, b: Rect) {
+    return !(b.x >= a.x + a.width || b.x + b.width <= a.x || b.y >= a.y + a.height || b.y + b.height <= a.y);
+  }
+  private isContained(a: Rect, b: Rect) {
+    return a.x >= b.x && a.y >= b.y && (a.x + a.width) <= (b.x + b.width) && (a.y + a.height) <= (b.y + b.height);
+  }
+
+  private evictIfNeeded() {
+    while (this.pages.length > this.maxPages) {
+      this.evictLeastRecentlyUsedPage();
+    }
+  }
+
+  private evictLeastRecentlyUsedPage() {
+    if (this.pages.length === 0) return;
+    let oldest = 0;
+    let oldestTime = Infinity;
+    for (let i = 0; i < this.pages.length; i++) {
+      const p = this.pages[i];
+      if (p.lastUsed < oldestTime) {
+        oldestTime = p.lastUsed;
+        oldest = i;
+      }
+    }
+    this.evictPage(oldest);
+  }
+
+  private evictPage(idx: number) {
+    if (idx < 0 || idx >= this.pages.length) return;
+    // Remove page data
+    this.pages.splice(idx, 1);
+    // Remove placements that pointed to this page and adjust pageIndex for later pages
+    for (const [k, placement] of Array.from(this.placements.entries())) {
+      if (placement.pageIndex === idx) {
+        this.placements.delete(k);
+      } else if (placement.pageIndex > idx) {
+        this.placements.set(k, { ...placement, pageIndex: placement.pageIndex - 1 });
+      }
+    }
+    // Rebuild hashIndex: remove entries referencing removed page and adjust indices
+    const newHash = new Map<number, AtlasPlacement[]>();
+    for (const [h, list] of this.hashIndex.entries()) {
+      const newList: AtlasPlacement[] = [];
+      for (const p of list) {
+        if (p.pageIndex === idx) continue;
+        if (p.pageIndex > idx) {
+          newList.push({ ...p, pageIndex: p.pageIndex - 1 });
+        } else {
+          newList.push(p);
+        }
+      }
+      if (newList.length > 0) newHash.set(h, newList);
+    }
+    this.hashIndex = newHash;
+  }
+
+  private blitToPage(pageData: Uint8Array, pageW: number, _pageH: number, dstX: number, dstY: number, mask: Uint8ClampedArray, w: number, h: number) {
+    for (let row = 0; row < h; row++) {
+      const srcOff = row * w;
+      const dstRow = (dstY + row) * pageW;
+      let dstCol = dstX;
+      for (let col = 0; col < w; col++) {
+        const a = mask[srcOff + col];
+        const di = (dstRow + dstCol) * 4;
+        pageData[di] = 0;
+        pageData[di + 1] = 0;
+        pageData[di + 2] = 0;
+        pageData[di + 3] = a;
+        dstCol++;
+      }
+    }
+  }
+}
+
+export const globalGlyphAtlasMaxRects = new GlyphAtlasMaxRects(DEFAULT_PAGE_SIZE, DEFAULT_PADDING);

package/src/pdf/font/glyph-atlas-tuner.ts

@@ -0,0 +1,98 @@
+/**
+ * Simple heuristic tuner for glyph atlas parameters.
+ *
+ * Exports pickAtlasSettingsFromSamples(samples)
+ * - samples: Array of { width:number, height:number } representing a sample
+ *   of glyph mask sizes (in px) for a font/size combination.
+ *
+ * Heuristic:
+ * - Try candidate page sizes (1024, 2048, 4096)
+ * - Try padding values (0..3)
+ * - For each (pageSize, padding) compute:
+ *    * If any glyph (w+2p > pageSize or h+2p > pageSize) -> invalid
+ *    * totalPaddedArea = sum((w+2p)*(h+2p))
+ *    * estimatedPages = ceil(totalPaddedArea / (pageSize*pageSize))
+ *    * wastedRatio = estimatedPages * pageSize*pageSize / totalPaddedArea
+ * - Prefer configurations with smallest estimatedPages; tie-break by smallest wastedRatio,
+ *   then smaller pageSize and smaller padding.
+ *
+ * This is fast and conservative. It doesn't run an actual packer; it's only a
+ * lightweight selector to choose sensible defaults for pageSize and padding.
+ */
+
+export interface AtlasSettings {
+  pageSize: number;
+  padding: number;
+  estimatedPages: number;
+  wastedRatio: number;
+  valid: boolean;
+}
+
+export function pickAtlasSettingsFromSamples(
+  samples: Array<{ width: number; height: number }>,
+  opts?: { candidates?: number[]; paddings?: number[] }
+): AtlasSettings {
+  const candidates = opts?.candidates ?? [1024, 2048, 4096];
+  const paddings = opts?.paddings ?? [0, 1, 2, 3];
+
+  // sanitize samples
+  const filtered = (samples || []).map(s => ({ width: Math.max(0, Math.floor(s.width)), height: Math.max(0, Math.floor(s.height)) }));
+  if (filtered.length === 0) {
+    // default safe
+    return { pageSize: 2048, padding: 1, estimatedPages: 1, wastedRatio: 1, valid: true };
+  }
+
+  let best: AtlasSettings | null = null;
+
+  for (const pageSize of candidates) {
+    for (const padding of paddings) {
+      let invalid = false;
+      let totalPaddedArea = 0;
+      for (const s of filtered) {
+        const pw = s.width + padding * 2;
+        const ph = s.height + padding * 2;
+        if (pw > pageSize || ph > pageSize) {
+          invalid = true;
+          break;
+        }
+        totalPaddedArea += pw * ph;
+      }
+      if (invalid) continue;
+      const pageArea = pageSize * pageSize;
+      const estimatedPages = Math.max(1, Math.ceil(totalPaddedArea / pageArea));
+      const wastedRatio = (estimatedPages * pageArea) / Math.max(1, totalPaddedArea);
+
+      const candidate: AtlasSettings = {
+        pageSize,
+        padding,
+        estimatedPages,
+        wastedRatio,
+        valid: true,
+      };
+
+      if (!best) {
+        best = candidate;
+        continue;
+      }
+
+      // prefer fewer pages, then lower wastedRatio, then smaller pageSize, then smaller padding
+      if (candidate.estimatedPages < best.estimatedPages) {
+        best = candidate;
+      } else if (candidate.estimatedPages === best.estimatedPages) {
+        if (candidate.wastedRatio < best.wastedRatio - 1e-9) {
+          best = candidate;
+        } else if (Math.abs(candidate.wastedRatio - best.wastedRatio) < 1e-9) {
+          if (candidate.pageSize < best.pageSize) best = candidate;
+          else if (candidate.pageSize === best.pageSize && candidate.padding < best.padding) best = candidate;
+        }
+      }
+    }
+  }
+
+  if (!best) {
+    // fallback conservative
+    return { pageSize: 2048, padding: 1, estimatedPages: 1, wastedRatio: 1, valid: false };
+  }
+
+  return best;
+}

package/src/pdf/font/glyph-atlas.ts

@@ -0,0 +1,226 @@
+/**
+ * Simple shelf-based glyph atlas packer.
+ *
+ * Purpose:
+ * - Pack many small glyph alpha masks into one or more RGBA atlas pages.
+ * - Provide placement metadata so caller can later extract or reference the region.
+ *
+ * Notes:
+ * - This implementation focuses on correctness and simplicity (shelf packer).
+ * - Atlas pages are stored as RGBA Uint8Array buffers where R=G=B=0 and A=mask.
+ * - Does NOT yet integrate automatically with PDF image registration;
+ *   that will be done in the rendering path in a follow-up step.
+ */
+
+export interface AtlasPlacement {
+  readonly pageIndex: number;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface AtlasPage {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array; // RGBA
+}
+
+type Key = string;
+
+const DEFAULT_PAGE_SIZE = 2048; // square atlas page default
+// Increase base padding to reduce risk of blur bleeding between packed glyphs.
+// We still add extraPadding from the caller (e.g. glyph-cache) for blur radius.
+const PADDING = 2; // padding around glyphs to avoid bleeding
+
+class Shelf {
+  y: number;
+  height: number;
+  xCursor: number;
+  remaining: number;
+  constructor(y: number, height: number, pageWidth: number) {
+    this.y = y;
+    this.height = height;
+    this.xCursor = 0;
+    this.remaining = pageWidth;
+  }
+}
+
+/**
+ * AtlasManager
+ */
+export class GlyphAtlas {
+  private pageSize = DEFAULT_PAGE_SIZE;
+  private pages: { width: number; height: number; data: Uint8Array; shelves: Shelf[]; used: number; lastUsed: number }[] = [];
+  private placements = new Map<Key, AtlasPlacement>();
+  // LRU eviction control for shelf atlas
+  private maxPages = 8;
+  setMaxPages(n: number) {
+    if (!Number.isFinite(n) || n < 1) return;
+    this.maxPages = Math.max(1, Math.floor(n));
+    this.evictIfNeeded();
+  }
+
+  constructor(pageSize = DEFAULT_PAGE_SIZE) {
+    this.pageSize = pageSize;
+  }
+
+  clear() {
+    this.pages = [];
+    this.placements.clear();
+  }
+
+  getPages(): AtlasPage[] {
+    return this.pages.map((p) => ({ width: p.width, height: p.height, data: p.data.slice() }));
+  }
+
+  has(key: Key): boolean {
+    return this.placements.has(key);
+  }
+
+  getPlacement(key: Key): AtlasPlacement | null {
+    return this.placements.get(key) ?? null;
+  }
+
+  /**
+   * Pack an alpha mask into the atlas.
+   * - key: unique identifier for the glyph (e.g., fontUid|gid|size|ss)
+   * - mask: Uint8ClampedArray length = w*h
+   * - w,h: dimensions
+   * Returns placement or null on failure.
+   */
+  pack(key: Key, mask: Uint8ClampedArray, w: number, h: number, extraPadding = 0): AtlasPlacement | null {
+    if (this.placements.has(key)) {
+      return this.placements.get(key)!;
+    }
+    const pw = this.pageSize;
+    const ph = this.pageSize;
+    const pad = PADDING + Math.max(0, Math.floor(extraPadding));
+    const rw = w + pad * 2;
+    const rh = h + pad * 2;
+
+    // Try existing pages
+    for (let pi = 0; pi < this.pages.length; pi++) {
+      const page = this.pages[pi];
+      // try to fit in existing shelves
+      for (const shelf of page.shelves) {
+        if (rh <= shelf.height && rw <= shelf.remaining) {
+          // place it
+          const x = shelf.xCursor + pad;
+          const y = shelf.y + pad;
+          this.blitToPage(page.data, page.width, page.height, x, y, mask, w, h);
+          shelf.xCursor += rw;
+          shelf.remaining -= rw;
+          page.used += rw * rh;
+          page.lastUsed = Date.now();
+          const placement: AtlasPlacement = { pageIndex: pi, x, y, width: w, height: h };
+          this.placements.set(key, placement);
+          return placement;
+        }
+      }
+
+      // If no shelf fits, try to create a new shelf at bottom if space allows
+      const usedHeight = page.shelves.reduce((s, sh) => s + sh.height, 0);
+      if (usedHeight + rh <= page.height) {
+        const shelfY = usedHeight;
+        const shelf = new Shelf(shelfY, rh, page.width);
+        page.shelves.push(shelf);
+        // place at start
+        const x = shelf.xCursor + pad;
+        const y = shelf.y + pad;
+        this.blitToPage(page.data, page.width, page.height, x, y, mask, w, h);
+        shelf.xCursor += rw;
+        shelf.remaining -= rw;
+        page.used += rw * rh;
+        page.lastUsed = Date.now();
+        const placement: AtlasPlacement = { pageIndex: pi, x, y, width: w, height: h };
+        this.placements.set(key, placement);
+        return placement;
+      }
+    }
+
+    // No existing page fits: create a new page
+    const pageW = pw;
+    const pageH = ph;
+    const pageData = new Uint8Array(pageW * pageH * 4); // RGBA
+    // default rgba zeros
+    const newPage = { width: pageW, height: pageH, data: pageData, shelves: [] as Shelf[], used: 0, lastUsed: Date.now() };
+    // create first shelf
+    if (rh > pageH || rw > pageW) {
+      // too large for page
+      return null;
+    }
+    const shelf = new Shelf(0, rh, pageW);
+    newPage.shelves.push(shelf);
+    this.pages.push(newPage);
+    // enforce max pages after adding page
+    this.evictIfNeeded();
+    const x = shelf.xCursor + pad;
+    const y = shelf.y + pad;
+    this.blitToPage(newPage.data, newPage.width, newPage.height, x, y, mask, w, h);
+    shelf.xCursor += rw;
+    shelf.remaining -= rw;
+    newPage.used += rw * rh;
+    newPage.lastUsed = Date.now();
+    const placement: AtlasPlacement = { pageIndex: this.pages.length - 1, x, y, width: w, height: h };
+    this.placements.set(key, placement);
+    return placement;
+  }
+
+  private evictIfNeeded() {
+    while (this.pages.length > this.maxPages) {
+      this.evictLeastRecentlyUsedPage();
+    }
+  }
+
+  private evictLeastRecentlyUsedPage() {
+    if (this.pages.length === 0) return;
+    let oldest = 0;
+    let oldestTime = Infinity;
+    for (let i = 0; i < this.pages.length; i++) {
+      const p = this.pages[i];
+      if (p.lastUsed < oldestTime) {
+        oldestTime = p.lastUsed;
+        oldest = i;
+      }
+    }
+    this.evictPage(oldest);
+  }
+
+  private evictPage(idx: number) {
+    if (idx < 0 || idx >= this.pages.length) return;
+    // Remove page data
+    this.pages.splice(idx, 1);
+    // Remove placements that pointed to this page and adjust pageIndex for later pages
+    for (const [k, placement] of Array.from(this.placements.entries())) {
+      if (placement.pageIndex === idx) {
+        this.placements.delete(k);
+      } else if (placement.pageIndex > idx) {
+        this.placements.set(k, { ...placement, pageIndex: placement.pageIndex - 1 });
+      }
+    }
+    // NOTE: shelf atlas does not maintain a hashIndex for dedupe.
+    // Eviction only updates placements above; nothing more to adjust here.
+  }
+
+  private blitToPage(pageData: Uint8Array, pageW: number, _pageH: number, dstX: number, dstY: number, mask: Uint8ClampedArray, w: number, h: number) {
+    // pageData is RGBA; we write R=G=B=0, A = mask
+    for (let row = 0; row < h; row++) {
+      const srcOff = row * w;
+      const dstRow = (dstY + row) * pageW;
+      let dstCol = dstX;
+      for (let col = 0; col < w; col++) {
+        const a = mask[srcOff + col];
+        const di = (dstRow + dstCol) * 4;
+        pageData[di] = 0;
+        pageData[di + 1] = 0;
+        pageData[di + 2] = 0;
+        pageData[di + 3] = a;
+        dstCol++;
+      }
+    }
+  }
+}
+
+/** Singleton atlas for now (can be replaced with per-font/per-size atlases later) */
+export const globalGlyphAtlas = new GlyphAtlas(DEFAULT_PAGE_SIZE);