How episphere/imagebox3 works
Project Type and Purpose
• Type: A zero-footprint, client-only JavaScript library (not a full-stack app).
• Purpose: Enable browsers to extract image patches directly from large remote TIFF/WSI files via HTTP Range Requests, with no server-side tiling.
Main Architectural Components
a. Host Application (consuming page or framework)
b. ImageBox3 Core Module (imagebox3.mjs / imagebox3.js)
c. Decoder Layer
– decoders.json (configuration)
– decoder_33005.js (example JPEG2000 codec)
– Additional decoder plugins
d. HTTP Range Request Engine (built into Core)
e. Remote Storage / WSI File Server (S3, HTTP server)
f. Browser Runtime
– Fetch API (HTTP Range)
– Blob & URL APIs
– Optional Service Worker (demo/serviceWorker)
g. Demo UI (index.html, index.js, CSS) – illustrates usage
h. Documentation Site (docs/) – static JSDoc pages
Relationships & Data Flows
1. Host App loads ImageBox3 module
→ initializes instance with URL or File object
2. Core Module issues HTTP Range Requests (Fetch API)
→ requests specific byte ranges from Remote Storage
3. Fetched ArrayBuffer slices flow into Decoder Layer
→ selects appropriate codec (via decoders.json)
→ decodes compressed tiles to raw image data
4. Core Module assembles raw pixels, re-encodes as PNG Blob
→ returns Blob promise to Host App
5. Host App renders Blob via Object URL in an <img> tag
6. (In Demo) Service Worker can intercept range requests and cache byte ranges
Architectural Patterns & Design Principles
• Modular “plugin” decoders (Strategy Pattern)
• Single-responsibility separation:
– Core orchestration (init, metadata parsing, request routing)
– Decoding abstraction (decoders/)
– Presentation/demo separated (demo/, docs/)
• Lazy loading of decoders only when needed
• Zero-footprint: no server-side; all computation in browser
Technologies & Libraries
• ECMAScript Modules (imagebox3.mjs)
• HTTP Range Requests (Fetch API with Range header)
• TIFF/WSI metadata parsing (in Core)
• Codec implementations in pure JS (decoder_33005.js)
• Service Worker API (demo)
• JSDoc-generated static docs