Canvas Image LOD

Canvas Image LOD

Removes zoom lag in Obsidian Canvas on boards with many large images. Your image files are never modified.

The problem

Obsidian Canvas is plain DOM. Every time the zoom level changes, Chromium re-rasterizes each image from its source resolution. A 4800×3000 photo drawn 150 px wide on screen is still recomputed from 14 megapixels — on every zoom step, for every image in view.

Measured on one real board:

That gigabyte is re-rasterized as you zoom. It is the whole reason the board stutters.

What the plugin does

It builds downscaled proxies of each image and feeds every <img> the one that matches its real on-screen size. Zoom out and a 128 px copy is drawn; zoom in and the original comes back.

Simulated against the same board (tiers 128/320/768/1600, headroom 1.15):

Numbers come from one vault. Yours will differ with image sizes and board layout.

Design notes

Zoom is read from the transform matrix (getComputedStyle().transform) rather than from canvas internals, so Obsidian updates do not break it.

Each image is fully decoded exactly once. Tiers are then built as a chain — 1600 from the original, 768 from 1600, 320 from 768 — which is both faster and sharper than jumping straight from 4800 to 128.

Upgrades are deferred until the gesture ends. Downgrades apply immediately because the proxies are already in memory; originals are only reloaded 200 ms after you stop moving, so heavy files never load mid-zoom.

DOM reads and writes are split into phases. All sizes are measured first, then all swaps applied — otherwise the browser would recompute layout once per image.

Node widths are cached in a WeakMap and refreshed through a ResizeObserver, so offsetWidth is never touched during a frame.

Prewarm walks the board's JSON, not the DOM. Obsidian unmounts distant nodes, so they are not in the DOM to be found; this way proxies are ready for images you have not scrolled to yet.

Files are read through vault.readBinary, falling back to fetch for external URLs.

Storage

Proxies live in IndexedDB inside your Obsidian profile — not in your vault.

This matters: on a large vault the proxy set runs to roughly 100 MB. Kept under .obsidian, all of it would be pushed through Obsidian Sync, count against your storage quota, and — because cache keys include each file's mtime — quite possibly arrive useless on the other machine anyway. It is derived data, and it is cheaper to rebuild than to carry.

Memory is bounded separately. Every object URL keeps its blob alive, so entries are evicted least-recently-used once the RAM budget is exceeded; anything currently on screen is pinned and never revoked. Evicted proxies are reloaded from IndexedDB without re-decoding.

Both budgets are configurable, and cache keys invalidate themselves when you edit an image.

Install

Copy main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/canvas-image-lod/, then enable the plugin under Settings → Community plugins.

Commands

• Toggle proxy swapping
• Build proxies for the current canvas
• Restore original images on the current canvas
• Clear proxy cache

Limitations

• Desktop only. WebKit cannot encode WebP from a canvas and silently returns PNG, OffscreenCanvas needs Safari 16.4+, and decoding large images on a phone risks the OS killing the WebView. Mobile support needs its own work.
• SVG and video nodes are left alone.
• Text and markdown cards are untouched. This plugin fixes raster cost, not DOM cost — a board of 500 text cards will be exactly as slow as before.
• Exporting a canvas to an image restores originals first and waits for them to load, but it hooks the export command by name pattern. If that command is renamed upstream, use Restore original images on the current canvas manually before exporting.

Development

No build step — main.js is plain CommonJS, edit and reload.

cd test && npm install && npm test

Three suites:

• loadtest.js — the module loads, onload/onunload survive
• bindtest.js — deliberately broken canvas leaves never break plugin loading
• cachetest.js — IndexedDB round trip and pruning, memory eviction and pinning, the export wrapper, legacy cache removal, settings rendering

simulate.js measures the level-of-detail win against a real board; edit the vault path at the top before running it.

License

MIT