cytoscape-canvas-underlay 1.3.0 → 1.4.0

package/README.md

@@ -4,7 +4,8 @@ A [Cytoscape.js](https://js.cytoscape.org) plugin for rendering image/PDF backgr
 
 - **Image & PDF support** — load `.png`, `.jpg`, `.svg`, or `.pdf` as background
 - **Multiple drawings** — overlay additional drawings at arbitrary world positions
-- **Zoom/pan sync** — synchronous redraw on every viewport event for zero-lag rendering
+- **Zoom/pan sync** — viewport-synced redraw, coalesced to one draw per frame (requestAnimationFrame) for smooth pan/zoom
+- **Large-image performance** — optional downscaled proxy during pan/zoom for huge backgrounds, full resolution on idle (`lowQualityOnInteraction`); CSS filters are pre-baked once instead of per frame
 - **Pan clamping** — hard boundary or iOS-style rubber-band with spring-back
 - **Minimap** — DOM-based crisp image rendering, two viewport styles (`dim` / `rect`), auto-hide, full customization
 - **Adaptive PDF quality** — low-quality render during interaction, high-quality on idle
@@ -273,6 +274,15 @@ const inside = api.isPointInDrawing(world.x, world.y);
 | `drawingVisible` | `boolean` | `true` | Initial drawing visibility |
 | `graphVisible` | `boolean` | `true` | Initial graph layer visibility |
 
+### Interaction Quality
+
+For very large drawings (e.g. tens of megapixels), redrawing the full-resolution image on every pan/zoom frame can cause stutter. Enable `lowQualityOnInteraction` to draw a downscaled proxy during interaction and restore full resolution once it settles.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `lowQualityOnInteraction` | `boolean` | `false` | Draw a downscaled proxy + lower image smoothing during pan/zoom, restoring full quality when interaction stops. Recommended for large background images. |
+| `interactionProxyMax` | `number` | `2560` | Max edge (px) of the downscaled proxy used while interacting. Only sources larger than this are downscaled. |
+
 ### PDF Quality
 
 | Option | Type | Default | Description |

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "cytoscape-canvas-underlay",
-  "version": "1.3.0",
-  "description": "Cytoscape.js plugin for rendering image/PDF canvas underlay behind graph nodes with synchronized zoom and pan",
-  "main": "src/index.js",
-  "module": "src/index.js",
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./src/index.js",
-      "default": "./src/index.js"
-    }
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "cytoscape",
-    "cytoscape-extension",
-    "cytoscape-plugin",
-    "canvas",
-    "underlay",
-    "background",
-    "drawing",
-    "pdf",
-    "image",
-    "p&id",
-    "diagram"
-  ],
-  "author": "",
-  "license": "MIT",
-  "peerDependencies": {
-    "cytoscape": "^3.2.0",
-    "pdfjs-dist": "^4.0.0 || ^5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "pdfjs-dist": {
-      "optional": true
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": ""
-  },
-  "homepage": ""
-}
+{
+  "name": "cytoscape-canvas-underlay",
+  "version": "1.4.0",
+  "description": "Cytoscape.js plugin for rendering image/PDF canvas underlay behind graph nodes with synchronized zoom and pan",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cytoscape",
+    "cytoscape-extension",
+    "cytoscape-plugin",
+    "canvas",
+    "underlay",
+    "background",
+    "drawing",
+    "pdf",
+    "image",
+    "p&id",
+    "diagram"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "cytoscape": "^3.2.0",
+    "pdfjs-dist": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pdfjs-dist": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": ""
+}

package/src/DrawingOverlay.js

@@ -35,6 +35,12 @@ const DEFAULTS = {
   drawingVisible: true,      // Show/hide the background drawing
   graphVisible: true,        // Show/hide the cytoscape graph layer
 
+  // ── Interaction Quality ──
+  // pan/zoom 중 큰 도면을 다운스케일 프록시 + 저품질 스무딩으로 그려 끊김을 줄인다(멈추면 풀해상도 복원).
+  // 큰 배경 이미지에서 pan/zoom 이 끊길 때 true 로 사용.
+  lowQualityOnInteraction: false, // pan/zoom 중 저품질 렌더 사용 여부
+  interactionProxyMax: 2560,      // 프록시 최대 변(px). 이보다 큰 소스만 축소.
+
   // ── PDF Quality ──
   qualityDelay: 100,         // ms delay before high-quality PDF re-render
   pdfMinRenderSize: 2048,    // Minimum PDF render dimension (px)
@@ -207,11 +213,18 @@ export class DrawingOverlay {
     // Additional drawings
     this._drawings = new Map();
 
+    // PDF 존재 여부 캐시 (zoom/pan마다 순회 방지)
+    this._hasPdfCached = false;
+
     // RAF / debounce
     this._rafId = null;
     this._qualityTimer = null;
     this._abortController = null;
 
+    // pan/zoom 중 저품질 렌더 플래그 + 멈춤 감지 타이머
+    this._interacting = false;
+    this._interactTimer = null;
+
     // Pan clamping re-entry guard
     this._isPanAdjusting = false;
 
@@ -293,17 +306,17 @@ export class DrawingOverlay {
   _bindEvents() {
     this._onViewport = () => {
       this._enforceLimits();
-      this._draw();
-      if (this._minimap) this._minimap.render();
 
-      // Schedule high-quality PDF re-render at current zoom level
-      const hasPdf = this._main.isPdf || [...this._drawings.values()].some(d => d.isPdf && d.visible);
-      if (hasPdf) {
-        if (this._qualityTimer) clearTimeout(this._qualityTimer);
-        this._qualityTimer = setTimeout(() => {
-          this._reRenderAllPdfs().then(() => this._draw());
-        }, this.opts.qualityDelay);
-      }
+      // pan/zoom 중에는 저품질로 그리고, 멈추면 idle 후 고품질로 한 번 더 그린다.
+      this._interacting = true;
+      if (this._interactTimer) clearTimeout(this._interactTimer);
+      this._interactTimer = setTimeout(() => {
+        this._interacting = false;
+        this._scheduleRedraw();
+      }, 120);
+
+      // 매 이벤트 동기 _draw() 대신 프레임당 1회로 코얼레싱(_scheduleRedraw 가 PDF 고품질 재렌더도 예약).
+      this._scheduleRedraw();
     };
     this._onResize = () => {
       this._setupCanvas();
@@ -340,6 +353,7 @@ export class DrawingOverlay {
     this._cancelSpringBack();
     if (this._rafId) cancelAnimationFrame(this._rafId);
     if (this._qualityTimer) clearTimeout(this._qualityTimer);
+    if (this._interactTimer) clearTimeout(this._interactTimer);
     if (this._abortController) this._abortController.abort();
 
     // Remove rubber-band drag listeners
@@ -649,6 +663,7 @@ export class DrawingOverlay {
       }
     }
     this._loading = false;
+    this._updateHasPdf();
 
     if (this.opts.fitOnLoad) this.fit();
     this._draw();
@@ -891,6 +906,16 @@ export class DrawingOverlay {
      Public API: Utility
      ═══════════════════════════════════════ */
 
+  /** PDF 존재 여부 캐시 갱신 */
+  _updateHasPdf() {
+    this._hasPdfCached = this._main.isPdf;
+    if (!this._hasPdfCached) {
+      for (const d of this._drawings.values()) {
+        if (d.isPdf && d.visible) { this._hasPdfCached = true; break; }
+      }
+    }
+  }
+
   /** Force redraw. */
   refresh() {
     this._setupCanvas();
@@ -1044,6 +1069,7 @@ export class DrawingOverlay {
     }
 
     this._drawings.set(id, state);
+    this._updateHasPdf();
     this._draw();
     this._emit('drawingAdd', id, { x: state.x, y: state.y, width: state.width, height: state.height });
   }
@@ -1059,6 +1085,7 @@ export class DrawingOverlay {
     const state = this._drawings.get(id);
     if (!state) return;
     state.visible = visible;
+    if (state.isPdf) this._updateHasPdf();
     this._draw();
   }
 
@@ -1069,12 +1096,14 @@ export class DrawingOverlay {
 
   removeDrawing(id) {
     this._drawings.delete(id);
+    this._updateHasPdf();
     this._draw();
     this._emit('drawingRemove', id);
   }
 
   clearDrawings() {
     this._drawings.clear();
+    this._updateHasPdf();
     this._draw();
   }
 
@@ -1146,6 +1175,73 @@ export class DrawingOverlay {
     }
   }
 
+  /**
+   * 필터(invert/brightness/contrast/...)를 적용한 소스를 반환.
+   * 매 프레임 ctx.filter 로 큰 도면을 필터링하면 매우 느리므로, 소스(이미지/PDF캔버스)를
+   * 오프스크린 캔버스에 한 번만 구워두고 필터 문자열/소스가 바뀔 때만 재생성한다.
+   * 필터가 없으면(none) 원본 소스를 그대로 반환.
+   */
+  _filtered(holder, source, filterStr) {
+    if (!filterStr || filterStr === 'none') return source;
+    const w = source.naturalWidth || source.width;
+    const h = source.naturalHeight || source.height;
+    if (!w || !h) return source;
+
+    const cache = holder._filteredCache;
+    if (cache && cache.src === source && cache.filter === filterStr && cache.w === w && cache.h === h) {
+      return cache.canvas;
+    }
+
+    const canvas = (cache && cache.canvas) || document.createElement('canvas');
+    if (canvas.width !== w) canvas.width = w;
+    if (canvas.height !== h) canvas.height = h;
+    const cx = canvas.getContext('2d');
+    cx.clearRect(0, 0, w, h);
+    cx.filter = filterStr;
+    cx.imageSmoothingEnabled = true;
+    cx.imageSmoothingQuality = 'high';
+    cx.drawImage(source, 0, 0, w, h);
+    cx.filter = 'none';
+
+    holder._filteredCache = { src: source, filter: filterStr, w, h, canvas };
+    return canvas;
+  }
+
+  /**
+   * 큰 소스(예: 10000×7074 도면)를 매 프레임 통째로 drawImage 하면 pan/zoom 이 끊긴다.
+   * → 최대 변(PROXY_MAX) 으로 축소한 캔버스를 캐시해 인터랙션 중에만 사용. 소스가 작으면 원본 그대로.
+   */
+  _proxy(holder, src) {
+    const PROXY_MAX = this.opts.interactionProxyMax || 2560;
+    const sw = src.naturalWidth || src.width;
+    const sh = src.naturalHeight || src.height;
+    if (!sw || !sh || (sw <= PROXY_MAX && sh <= PROXY_MAX)) return src;
+
+    const scale = PROXY_MAX / Math.max(sw, sh);
+    const pw = Math.max(1, Math.round(sw * scale));
+    const ph = Math.max(1, Math.round(sh * scale));
+
+    const cache = holder._proxyCache;
+    if (cache && cache.src === src && cache.w === pw && cache.h === ph) return cache.canvas;
+
+    const canvas = (cache && cache.canvas) || document.createElement('canvas');
+    canvas.width = pw; canvas.height = ph;
+    const cx = canvas.getContext('2d');
+    cx.clearRect(0, 0, pw, ph);
+    cx.imageSmoothingEnabled = true;
+    cx.imageSmoothingQuality = 'high';
+    cx.drawImage(src, 0, 0, pw, ph);
+
+    holder._proxyCache = { src, w: pw, h: ph, canvas };
+    return canvas;
+  }
+
+  /** _draw 가 사용할 소스: 필터 적용본. 옵션 켜진 경우 인터랙션 중에는 축소 프록시로 대체(멈추면 풀해상도). */
+  _displaySource(holder, source, filterStr) {
+    const full = this._filtered(holder, source, filterStr);
+    return (this._interacting && this.opts.lowQualityOnInteraction) ? this._proxy(holder, full) : full;
+  }
+
   /** Draw an image/canvas with optional rotation around its center. */
   _drawRotated(ctx, source, x, y, w, h, rotation) {
     if (!rotation) {
@@ -1185,9 +1281,10 @@ export class DrawingOverlay {
     const hasAdditional = this._drawings.size > 0;
     if (!hasMain && !hasAdditional) return;
 
-    // High-quality image smoothing
+    // Image smoothing — 옵션 켜진 경우에만 pan/zoom 중 'low', 그 외엔 'high'.
+    const lowQ = this._interacting && this.opts.lowQualityOnInteraction;
     ctx.imageSmoothingEnabled = true;
-    ctx.imageSmoothingQuality = 'high';
+    ctx.imageSmoothingQuality = lowQ ? 'low' : 'high';
 
     // Apply cytoscape transform
     ctx.setTransform(
@@ -1197,18 +1294,18 @@ export class DrawingOverlay {
       Math.round(pan.y * dpr)
     );
 
-    // CSS filters
-    ctx.filter = buildFilterString(this.opts);
+    // CSS 필터는 매 프레임 ctx.filter 로 적용하지 않고, 미리 구워둔 캔버스(_filtered)를 사용.
+    const filterStr = buildFilterString(this.opts);
 
     // Draw main source
     if (hasMain) {
       ctx.globalAlpha = this.opts.opacity;
       const mainRot = this.opts.rotation || 0;
       if (this._main.img) {
-        this._drawRotated(ctx, this._main.img, 0, 0, this._main.w, this._main.h, mainRot);
+        this._drawRotated(ctx, this._displaySource(this._main, this._main.img, filterStr), 0, 0, this._main.w, this._main.h, mainRot);
       } else if (this._main.pdfCanvas && this._main.pdfClip) {
         const c = this._main.pdfClip;
-        this._drawRotated(ctx, this._main.pdfCanvas, c.x, c.y, c.w, c.h, mainRot);
+        this._drawRotated(ctx, this._displaySource(this._main, this._main.pdfCanvas, filterStr), c.x, c.y, c.w, c.h, mainRot);
       }
     }
 
@@ -1218,15 +1315,14 @@ export class DrawingOverlay {
       ctx.globalAlpha = state.opacity * this.opts.opacity;
       const rot = state.rotation || 0;
       if (state.img) {
-        this._drawRotated(ctx, state.img, state.x, state.y, state.width, state.height, rot);
+        this._drawRotated(ctx, this._displaySource(state, state.img, filterStr), state.x, state.y, state.width, state.height, rot);
       } else if (state.pdfCanvas && state.pdfClip) {
         const c = state.pdfClip;
-        this._drawRotated(ctx, state.pdfCanvas, state.x + c.x, state.y + c.y, c.w, c.h, rot);
+        this._drawRotated(ctx, this._displaySource(state, state.pdfCanvas, filterStr), state.x + c.x, state.y + c.y, c.w, c.h, rot);
       }
     }
 
     // Reset
     ctx.globalAlpha = 1;
-    ctx.filter = 'none';
   }
 }

package/src/Minimap.js

@@ -183,7 +183,27 @@ export class Minimap {
 
     if (main.img && main.img.src) {
       if (this._lastImgSrc !== main.img.src) {
-        this._imgDiv.style.backgroundImage = `url(${main.img.src})`;
+        // 큰 원본(예: 70MP 도면)을 CSS 배경으로 통째로 디코드하면 메모리·디코드 비용이 큼.
+        // → 작은 썸네일 1장으로 축소해 사용(미니맵 화질엔 충분).
+        let bg = main.img.src;
+        try {
+          const THUMB_MAX = 256;
+          const iw = main.img.naturalWidth || main.w;
+          const ih = main.img.naturalHeight || main.h;
+          const s = Math.min(1, THUMB_MAX / Math.max(iw, ih));
+          if (s < 1) {
+            const tw = Math.max(1, Math.round(iw * s));
+            const th = Math.max(1, Math.round(ih * s));
+            const c = document.createElement('canvas');
+            c.width = tw; c.height = th;
+            const cx = c.getContext('2d');
+            cx.imageSmoothingEnabled = true;
+            cx.imageSmoothingQuality = 'high';
+            cx.drawImage(main.img, 0, 0, tw, th);
+            bg = c.toDataURL('image/png');
+          }
+        } catch (_) { /* cross-origin tainted 등 → 원본 src 폴백 */ }
+        this._imgDiv.style.backgroundImage = `url(${bg})`;
         this._lastImgSrc = main.img.src;
         if (this._blobUrl) { URL.revokeObjectURL(this._blobUrl); this._blobUrl = null; }
       }