perf(image): hold inflated pixels softly so the heap can reclaim them

[jcschaff]

Implements §5.3b of #2025. Stacked on #2026 — the diff below is this commit only; softening this
cache does nothing on its own while GeometrySpec holds a second strong reference to the same array.

VCImageCompressed kept its inflated pixels in a strong transient field, so once an image had been
read its 62 MB stayed resident for as long as the image object did — even though the compressed
form it can be rebuilt from is about 1 MB. Real geometry images compress 50–100× (measured
across 62 images in the VCML corpus: median 73.6×, 63.5× for those over 1 MP; #2025 §3.7).

The inflated array now hangs off a SoftReference, and getPixels() re-inflates on demand at
~700–950 MB/s.

Demonstrated under the shape of the incident

SoftPixelCacheDemo (included), 11 images all reachable at once, 256 MB heap:

soft cache OFF   OUT OF MEMORY after 9 of 11 images
soft cache ON    completed all 11
                 heap 246 MB -> 63 MB at image 10 as the collector reclaims
                 283 MB of pixels then re-read on demand

It's a main, not a test — driving a JVM to the edge of its heap doesn't belong in a shared test run.

Soft, not weak — the whole design

A WeakReference is cleared at the next GC whatever the heap looks like, so an image in active use
would re-inflate on essentially every collection: ~90 ms of CPU, repeatedly, for nothing. Soft
references are cleared only under real pressure.

Nothing about ordinary behaviour would look wrong if someone swapped the type, so
ordinaryGcDoesNotDiscardThePixels exists to fail if they do. Verified by temporarily switching
to WeakReference:

ordinaryGcDoesNotDiscardThePixels
  a plain GC must not clear the cache — SoftReference, not WeakReference
  ==> expected: <1527214863> but was: <172699023>

That control also improved the tests: with WeakReference in place my reflection helper threw
ClassCastException and turned two unrelated tests into errors, burying the one failure that
actually explains the problem. The helper is now typed Reference<?>.

Two details worth review

A race in getPixels() that had to be designed out. It takes a strong local reference once and
holds it for the whole method. Reading the SoftReference twice would let the collector clear it
between the null check and the return, handing the caller a null array — rare,
non-deterministic, and extremely unpleasant to diagnose.

Two loops hoisted, two deliberately not. ClientRequestManager:1169 (reached as
getGeometrySpec().getImage() — the stored image) and ImageFile:149/153 call getPixels() every
iteration and can receive a compressed image; under the very pressure that clears a soft reference
they would have re-inflated per iteration. ROIMultiPaintManager:2036 and ITextWriter:544 are
not touched — their receivers are locally built VCImageUncompressed instances, which hold
pixels in a final field and never inflate. (I nearly rewrote the ITextWriter index arithmetic
before checking; it would have been risk for no benefit.)

Escape hatch

vcell.image.softPixelCache=false restores strong caching.

Verification

• VCImageCompressedSoftCacheTest: 7/7 — content correctness, cache identity, soft-vs-weak,
  re-inflation after clearing, nullifyUncompressedPixels, the compressed form staying held, and
  the escape hatch.
• MathGen_IT: 1045 tests, 0 failures, 0 errors (705 math-generation comparisons over real
  stored VCML).
• vcell-core Fast: 587 run, 0 failures, 8 errors — the MathOverrideRoundTripTest /
  VCellDataTest errors docs/BUILDING.md documents for a worktree without the Poetry
  environments.
• Line endings checked: all three modified files are CRLF and stayed CRLF (git diff --stat reads
  59 insertions / 11 deletions, not a whole-file rewrite).

What this does not address

The per-pixel access path. VCImage.getPixel(x,y,z) is getPixels()[index], and
ImageSubVolume.isInside goes through GeometrySpec.getUncompressedPixels() one pixel at a time.
Both are cold today (#2025 §3.8 traced the only live caller to a 100-point curve check), but if
either ever becomes hot they want a bulk or hoisted accessor rather than a per-call fetch.

Refs #2021, #2025, #2026

🤖 Generated with Claude Code

https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt