ialdev-vis 0.2.2__tar.gz → 0.2.4__tar.gz

ialdev_vis-0.2.4/IMVIEW.md

@@ -0,0 +1,223 @@
+# imview — interactive image grid
+
+`iad.vis.imview` is the anywidget-based image grid for marimo and Jupyter. It
+replaces JSON heatmaps with binary pixel transport and client-side rendering.
+
+## Capabilities
+
+| Feature | Where | Notes |
+|---------|-------|-------|
+| Multi-panel grids | Python layout | Regular `(rows, cols)` or mosaic strings |
+| Scalar + RGB panels | `data.py` | Auto-detect; grayscale RGB collapsed to scalar |
+| Colormaps + clim | Frontend | LUTs built in Python, applied in browser |
+| Pan / zoom | `grid.ts` | Per-panel view window; nearest-neighbor upscale |
+| Pixel inspect | `inspect.ts` | Fixed-width coordinate/value readout |
+| Axis ticks | `labels.ts` | Follow visible window during pan/zoom |
+| Colorbars | Python layout + renderer | Scalar panels only |
+| Static oversampling | `data.py` | One-time integer downsample in Python |
+| `figsize` sizing | `data.py` + CSS | Reference CSS px; 240 px min per dimension |
+| `max_zoom` / `downsample` | `data.py` | Control buffer resolution vs. transfer size |
+| Data budget readout | Toolbar | MB / Mpx sent vs. full; red when over budget |
+| Resolution badge | `labels.ts` | Per-panel `(N:1)` ratio, updates with zoom |
+| In-place updates | `ImageGrid.update_data` | Same shapes; reuses prep kwargs |
+| marimo / Jupyter | `api.py` | Auto backend; `.ui` for layout composition |
+
+## Architecture
+
+```
+Python                              Browser (imgrid.js)
+─────────────────────────────────   ────────────────────────────────
+imgrid()                              index.ts (entry)
+  └─ prepare_grid / data.py             ├─ GridModel (trait bridge)
+       layout, downsample, pack         ├─ Canvas2DRenderer
+  └─ ImageGridWidget.create             ├─ LabelsOverlay (ticks, titles)
+       traitlets → binary buffers       ├─ controls (toolbar)
+  └─ ImageGrid wrapper                  ├─ inspect (hover readout)
+       display / update_data             └─ grid (pan/zoom)
+```
+
+**Static oversampling:** Python chooses an integer downsample factor per panel,
+packs buffers once, and sends them over anywidget binary comm. The frontend
+draws a sub-window of the buffer for pan/zoom. Upscaling past buffer detail
+uses nearest-neighbor interpolation; downscaling stays smooth.
+
+**Layout:** All panel rects, colorbar positions, and canvas size are computed
+in Python (`_display_layout`) as reference CSS pixels. The frontend scales
+to the display width (driven by `figsize`) while preserving aspect ratio.
+
+## Package layout
+
+```
+vis/
+├── IMVIEW.md                 # this file
+├── README.md                 # package overview + install
+├── js/                       # TypeScript sources (build → static/imgrid.js)
+│   └── src/
+│       ├── index.ts          # anywidget render entry, wiring
+│       ├── model.ts          # trait getters (panels, view, data_*)
+│       ├── canvas.ts         # HiDPI canvas sync
+│       ├── grid.ts           # pan/zoom, view state
+│       ├── controls.ts       # toolbar, data readout, clim/cmap toggles
+│       ├── inspect.ts        # pixel hover readout
+│       ├── labels.ts         # titles, axis ticks, resolution badge
+│       ├── selection.ts      # panel selection state
+│       ├── colormap.ts       # scalar recoloring
+│       ├── types.ts          # PanelMeta, ViewState, …
+│       └── renderer/
+│           ├── Renderer.ts   # interface
+│           └── Canvas2DRenderer.ts
+├── src/iad/vis/
+│   ├── gridcore.py           # shared grid/mosaic/resize helpers
+│   ├── mutils.py             # marimo mogrid(); backend='wgt' → imview
+│   └── imview/
+│       ├── __init__.py       # exports imgrid, ImageGrid
+│       ├── api.py            # imgrid(), ImageGrid
+│       ├── data.py           # prepare_grid*, layout, downsample
+│       ├── widget.py         # anywidget traits + apply_prepared
+│       ├── colormaps.py      # matplotlib LUT → bytes
+│       └── static/
+│           ├── imgrid.js     # built bundle
+│           └── imgrid.css
+└── tests/test_imview.py
+```
+
+## Public API
+
+### `imgrid(...)`
+
+Main entry point. Returns an `ImageGrid` unless `out=` requests a component.
+
+```python
+from iad.vis.imview import imgrid
+
+grid = imgrid(
+    left, right, diff,
+    titles=["left", "right", "diff"],
+    figsize=(900, None),
+    max_zoom=2,
+    clim="auto",
+)
+```
+
+### `ImageGrid`
+
+| Attribute / method | Description |
+|--------------------|-------------|
+| `.widget` | Raw anywidget instance (traits, buffers) |
+| `.ui` | marimo `mo.ui.anywidget(...)` when backend is marimo |
+| `.value` | `{'cursor', 'selection', 'view'}` reactive state |
+| `.panels` | Python `PanelData` list from preparation |
+| `.update_data(data)` | Replace buffers in place (dict by title or sequence) |
+
+### marimo usage
+
+```python
+# Single grid — return as last expression
+grid = imgrid(a, b, figsize=(800, None))
+
+# Stack multiple grids — use .ui
+mo.vstack([grid1.ui, grid2.ui])
+
+# Reactive readout
+grid.value["cursor"]  # current hover panel + coords
+```
+
+Via `mutils`:
+
+```python
+from iad.vis.mutils import mogrid, Backend
+
+mogrid(a, b, backend=Backend.WGT, figsize=(800, 600), max_zoom=2)
+```
+
+### Preparation API (lower level)
+
+```python
+from iad.vis.imview.data import prepare_grid, prepare_grid_from_parsed
+
+prepared = prepare_grid(img, titles=["a"], figsize=(600, 400), max_zoom=1.5)
+# prepared.panels, prepared.canvas_size, prepared.sent_bytes, …
+```
+
+## Key parameters
+
+### `figsize=(width, height)`
+
+Target grid size in CSS pixels. Either dimension may be `None`:
+
+- `(800, None)` — fit width 800, height from aspect ratio + chrome
+- `(None, 600)` — fit height 600
+- `(800, 600)` — fit inside both bounds
+
+Panel aspect ratios always match the source images. Each dimension has a
+**240 px minimum** (`_MIN_PANEL_PX`).
+
+### `max_zoom` vs `downsample`
+
+Mutually exclusive.
+
+| Mode | Effect |
+|------|--------|
+| *(default)* | Auto factor from `max_pixels` budget |
+| `max_zoom=2` | Buffer ≥ 2× panel display size (crisp 2× zoom headroom) |
+| `max_zoom='full'` | Factor 1 — full resolution sent |
+| `downsample=4` | Fixed 4× block-mean downsample |
+
+When `max_zoom` or `downsample` is set explicitly and total sent pixels exceed
+`max_pixels * n_panels`, the toolbar readout turns red (`data_over_budget`).
+
+### `update_data`
+
+```python
+grid.update_data({"left": new_left, "right": new_right})
+grid.update_data([arr0, arr1])  # panel order
+```
+
+Arrays must match original shapes. Uses the same `prep_kwargs` as initial
+creation (cmap, clim, figsize, downsample, …).
+
+## Widget traits (Python ↔ JS)
+
+| Trait | Direction | Purpose |
+|-------|-----------|---------|
+| `panels` | → JS | Metadata: layout, clim, factor, source dims |
+| `buffers` | → JS | Binary pixel data (float32 scalar / uint8 RGBA) |
+| `luts` | → JS | Colormap byte blobs |
+| `canvas_width/height` | → JS | Reference layout size |
+| `data_sent_*`, `data_full_*` | → JS | Transfer accounting |
+| `view` | ↔ | `{scale, tx, ty}` pan/zoom |
+| `cursor`, `selection` | ← JS | Inspect / selection state |
+| `cbar`, `ticks`, `show_grid`, `adj_clim` | ↔ | Display toggles |
+
+## Frontend modules
+
+| Module | Role |
+|--------|------|
+| `Canvas2DRenderer` | Draw panels, colorbars, grid overlay; nearest upscale |
+| `LabelsOverlay` | DOM overlay for titles, ticks (pan/zoom-aware), res badge |
+| `attachPanZoom` | Wheel zoom + drag pan; updates `view` trait |
+| `attachInspect` | Hover readout with tabular-nums formatting |
+| `buildToolbar` | Cmap/clim controls, data MB/Mpx readout |
+| `GridModel` | Typed accessors over anywidget model traits |
+
+## Build (developers)
+
+```bash
+cd vis/js && npm install && npm run build
+# writes vis/src/iad/vis/imview/static/imgrid.js
+```
+
+Run tests:
+
+```bash
+pixi run pytest vis/tests/test_imview.py
+```
+
+## Related backends
+
+| Module | Backend | Use case |
+|--------|---------|----------|
+| `iad.vis.imview` | anywidget | Interactive notebooks (this doc) |
+| `iad.vis.insight` | matplotlib | Desktop / static figures |
+| `iad.vis.plgrid` | Plotly | Lightweight overview plots |
+| `iad.vis.mutils.mogrid` | switchable | marimo helper; `backend='wgt'` → imview |

{ialdev_vis-0.2.2 → ialdev_vis-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ialdev-vis
-Version: 0.2.2
+Version: 0.2.4
 Summary: iad.vis — visualization utilities (image grids, viewers, colormaps, matplotlib helpers)
 Author: ipcoder
 Requires-Python: >=3.10
@@ -12,19 +12,25 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: ialdev-core>=0.2.4
-Requires-Dist: ialdev-io>=0.2.2
+Requires-Dist: ialdev-core>=0.2.6
+Requires-Dist: ialdev-io>=0.2.4
 Requires-Dist: matplotlib>=3.5.0
 Requires-Dist: numpy>=1.26.4,<2
 Requires-Dist: regex>=2021.0.0
 Requires-Dist: open3d>=0.15.0 ; extra == "3d"
 Requires-Dist: ipyvolume>=0.6.0 ; extra == "3d"
-Requires-Dist: ialdev-vis[graphviz, qt, jupyter, 3d, dev]>=0.2.2 ; extra == "all"
+Requires-Dist: ialdev-vis[graphviz, qt, jupyter, notebook, marimo, 3d, dev]>=0.2.4 ; extra == "all"
 Requires-Dist: pytest>=7.0.0 ; extra == "dev"
 Requires-Dist: pytest-cov>=3.0.0 ; extra == "dev"
 Requires-Dist: pygraphviz>=1.14,<2 ; extra == "graphviz"
 Requires-Dist: ipywidgets>=7.0.0 ; extra == "jupyter"
 Requires-Dist: IPython>=7.0.0 ; extra == "jupyter"
+Requires-Dist: plotly>=5.20 ; extra == "jupyter"
+Requires-Dist: anywidget>=0.9 ; extra == "jupyter"
+Requires-Dist: marimo>=0.23 ; extra == "marimo"
+Requires-Dist: plotly>=5.20 ; extra == "marimo"
+Requires-Dist: pandas>=2.0.0 ; extra == "marimo"
+Requires-Dist: anywidget>=0.9 ; extra == "notebook"
 Requires-Dist: PyQt5>=5.15.0 ; extra == "qt"
 Requires-Dist: scikit-image>=0.19.0 ; extra == "qt"
 Project-URL: Homepage, https://github.com/ipcoder/ialdev/tree/master/vis
@@ -35,6 +41,8 @@ Provides-Extra: all
 Provides-Extra: dev
 Provides-Extra: graphviz
 Provides-Extra: jupyter
+Provides-Extra: marimo
+Provides-Extra: notebook
 Provides-Extra: qt
 
 # ialdev-vis
@@ -54,6 +62,8 @@ Optional extras:
 ```bash
 pip install "ialdev-vis[qt]"
 pip install "ialdev-vis[jupyter]"
+pip install "ialdev-vis[notebook]"   # anywidget interactive image grid (imview)
+pip install "ialdev-vis[marimo]"
 pip install "ialdev-vis[3d]"
 pip install "ialdev-vis[all]"
 ```
@@ -63,6 +73,7 @@ Requires Python `>=3.10`.
 ## Highlights
 
 - `imgrid` and `imhist` for fast inspection of images and distributions.
+- `iad.vis.imview.imgrid` — interactive notebook image grid (marimo / Jupyter) via anywidget; static oversampling, `figsize` layout, client-side colormap/clim/zoom, mosaic layouts, data-budget readout, and cross-panel inspection. See [IMVIEW.md](IMVIEW.md).
 - Matplotlib helpers for figure capture and conversion to arrays/PIL images.
 - Built-in custom colormaps.
 - Polygon-to-mask helpers and interactive ROI tools.
@@ -71,7 +82,7 @@ Requires Python `>=3.10`.
 ## Examples
 
 ```python
-from iad.vis import imgrid, imhist
+from iad.vis.insight import imgrid, imhist
 
 imgrid(left_image, right_image, titles=["left", "right"], clim="auto")
 imhist(left_image, right_image, titles=["left", "right"])
@@ -83,3 +94,30 @@ from iad.vis.mpl_utils import fig2img
 pil_image = fig2img(figure)
 ```
 
+### Interactive image grid in marimo / Jupyter (`imview`)
+
+See **[IMVIEW.md](IMVIEW.md)** for architecture, parameters (`figsize`, `max_zoom`, `downsample`), module layout, and marimo stacking patterns.
+
+```python
+from iad.vis.imview import imgrid
+import marimo as mo
+
+grid = imgrid(left, right, diff, titles=["left", "right", "diff"], figsize=(900, None), max_zoom=2)
+grid.ui          # use in mo.vstack / mo.hstack
+grid.value       # reactive cursor, selection, view state
+grid.update_data({"left": new_left})  # in-place buffer refresh
+```
+
+In marimo, `iad.vis.mutils.mogrid(..., backend='wgt')` routes to the same anywidget backend.
+
+Rebuild the frontend after editing TypeScript (widget developers only):
+
+```bash
+cd vis/js && npm install && npm run build
+# or: pixi run build-imview-js   (requires pixi feature build-js / nodejs)
+```
+
+**Roadmap:** WebGL renderer (large images), ROI / line-profile tools, live histogram panel, linked selections into pandas/marimo cells.
+
+**Note:** `iad.vis.plgrid` remains a lightweight Plotly overview option; desktop/Qt inspection still uses `iad.vis.insight.imgrid` (matplotlib).
+

ialdev_vis-0.2.4/README.md

@@ -0,0 +1,75 @@
+# ialdev-vis
+
+Visualization utilities for the `iad` toolbox, published as `ialdev-vis` and imported as `iad.vis`.
+
+Use this package for quick image grids, histograms, Matplotlib helpers, custom colormaps, interactive annotation widgets, Jupyter logging, and optional Qt/3D visualization tools.
+
+## Install
+
+```bash
+pip install ialdev-vis
+```
+
+Optional extras:
+
+```bash
+pip install "ialdev-vis[qt]"
+pip install "ialdev-vis[jupyter]"
+pip install "ialdev-vis[notebook]"   # anywidget interactive image grid (imview)
+pip install "ialdev-vis[marimo]"
+pip install "ialdev-vis[3d]"
+pip install "ialdev-vis[all]"
+```
+
+Requires Python `>=3.10`.
+
+## Highlights
+
+- `imgrid` and `imhist` for fast inspection of images and distributions.
+- `iad.vis.imview.imgrid` — interactive notebook image grid (marimo / Jupyter) via anywidget; static oversampling, `figsize` layout, client-side colormap/clim/zoom, mosaic layouts, data-budget readout, and cross-panel inspection. See [IMVIEW.md](IMVIEW.md).
+- Matplotlib helpers for figure capture and conversion to arrays/PIL images.
+- Built-in custom colormaps.
+- Polygon-to-mask helpers and interactive ROI tools.
+- Optional Qt image viewer and optional `ipyvolume`/Open3D 3D views.
+
+## Examples
+
+```python
+from iad.vis.insight import imgrid, imhist
+
+imgrid(left_image, right_image, titles=["left", "right"], clim="auto")
+imhist(left_image, right_image, titles=["left", "right"])
+```
+
+```python
+from iad.vis.mpl_utils import fig2img
+
+pil_image = fig2img(figure)
+```
+
+### Interactive image grid in marimo / Jupyter (`imview`)
+
+See **[IMVIEW.md](IMVIEW.md)** for architecture, parameters (`figsize`, `max_zoom`, `downsample`), module layout, and marimo stacking patterns.
+
+```python
+from iad.vis.imview import imgrid
+import marimo as mo
+
+grid = imgrid(left, right, diff, titles=["left", "right", "diff"], figsize=(900, None), max_zoom=2)
+grid.ui          # use in mo.vstack / mo.hstack
+grid.value       # reactive cursor, selection, view state
+grid.update_data({"left": new_left})  # in-place buffer refresh
+```
+
+In marimo, `iad.vis.mutils.mogrid(..., backend='wgt')` routes to the same anywidget backend.
+
+Rebuild the frontend after editing TypeScript (widget developers only):
+
+```bash
+cd vis/js && npm install && npm run build
+# or: pixi run build-imview-js   (requires pixi feature build-js / nodejs)
+```
+
+**Roadmap:** WebGL renderer (large images), ROI / line-profile tools, live histogram panel, linked selections into pandas/marimo cells.
+
+**Note:** `iad.vis.plgrid` remains a lightweight Plotly overview option; desktop/Qt inspection still uses `iad.vis.insight.imgrid` (matplotlib).

ialdev_vis-0.2.4/js/build.mjs

@@ -0,0 +1,30 @@
+import * as esbuild from 'esbuild';
+import { mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(fileURLToPath(import.meta.url));
+const outFile = resolve(root, '../src/iad/vis/imview/static/imgrid.js');
+mkdirSync(dirname(outFile), { recursive: true });
+
+const watch = process.argv.includes('--watch');
+
+const ctx = await esbuild.context({
+  entryPoints: [resolve(root, 'src/index.ts')],
+  bundle: true,
+  format: 'esm',
+  platform: 'browser',
+  target: ['es2020'],
+  outfile: outFile,
+  minify: !watch,
+  sourcemap: watch,
+});
+
+if (watch) {
+  await ctx.watch();
+  console.log('watching imview bundle...');
+} else {
+  await ctx.rebuild();
+  await ctx.dispose();
+  console.log('built', outFile);
+}