Skip to content

fix: compute exact pyramid resolutions to keep THUMBNAIL levels aligned (slim#318)#245

Open
igoroctaviano wants to merge 2 commits into
masterfrom
fix/318-thumbnail-pyramid-resolution
Open

fix: compute exact pyramid resolutions to keep THUMBNAIL levels aligned (slim#318)#245
igoroctaviano wants to merge 2 commits into
masterfrom
fix/318-thumbnail-pyramid-resolution

Conversation

@igoroctaviano

Copy link
Copy Markdown
Collaborator

Summary

Fixes the annotation misplacement reported in ImagingDataCommons/slim#318, where the presence of a THUMBNAIL image causes the slide to "jump" and annotations to render in the wrong place while zooming.

Root cause

_computeImagePyramid computed each level's resolution (zoom factor) as baseTotalPixelMatrixColumns / totalPixelMatrixColumns and then rounded it to the nearest integer (Math.round).

  • VOLUME levels are clean (power-of-two style) downsamples of the base level, so their ratio is already (essentially) an integer and rounding is harmless.
  • THUMBNAIL images are not exact fractions of the base level. Confirmed against the repo's own TCGA-LUAD fixture:
flavor columns base/cols (true) rounded (old)
THUMBNAIL 803 57.7036 58
VOLUME 2896 16.0000 16
VOLUME 11584 4.0000 4
VOLUME 46336 1.0000 1

Rounding 57.70 → 58 is a ~0.5% scale error (~238 px across the slide). It stretches the thumbnail level so its upsampled image content drifts toward the bottom-right relative to the (correctly placed) vector annotation layer. This is why disabling thumbnails (skipThumbnails) "fixed" it — the remaining volume-only pyramid has integer ratios.

This is distinct from, but compounds, the transient nearest-neighbor upsampling shift discussed in openlayers/openlayers#12768.

Fix

Use the exact column ratio for every level instead of rounding. Levels are processed base → top, so each zoom factor is naturally strictly greater than the previous; a small floating-point guard preserves OpenLayers' requirement that resolutions be unique and strictly descending.

Test plan

  • New src/pyramid.test.js regression tests: thumbnail level is kept, every resolution equals the exact ratio, the thumbnail factor is not rounded to an integer, and resolutions remain unique/strictly descending.
  • Full suite green: 162 passed.
  • biome check clean.
  • Production bundle builds (webpack-bundle).

Follow-up

After release, ImagingDataCommons/slim can drop the skipThumbnails: true workaround and re-enable thumbnails for faster initial load (see slim#318 discussion).

The per-level zoom factor in _computeImagePyramid was rounded to the nearest
integer (Math.round). VOLUME levels are clean power-of-two downsamples so
rounding was harmless, but THUMBNAIL images are not exact fractions of the base
level. For example a thumbnail whose base/level column ratio is ~57.70 was
rounded to 58, a ~0.5% scale error that stretches the level and makes its
upsampled image content drift relative to vector annotations while zooming, so
annotations appear misplaced.

Use the exact column ratio for every level instead of rounding, keeping each
level aligned to the base coordinate system. Resolutions are still guaranteed to
be unique and strictly descending as required by OpenLayers.

Fixes ImagingDataCommons/slim#318
Refs openlayers/openlayers#12768
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant