release: v10.10.0 — JP3D true partial-resolution + ROI footprint-skip + Z-narrow#446
Merged
Merged
Conversation
… + Z-narrow
Closes the long-standing JP3D follow-up: the resolution-level field
on JP3DDecoderConfiguration was wired but never consulted; the ROI
decoder was decode-then-crop. Both are now true-selective.
Decoder-only release; codestream bytes byte-identical to v10.9.3.
Encoder unchanged. MINOR bump for new functional behaviour on existing
public APIs (JP3DDecoderConfiguration.resolutionLevel and
JP3DROIDecoder.decode(_:region:)).
Three coordinated changes inside Sources/J2K3D/:
1. JP3DDecoderConfiguration.resolutionLevel becomes functional.
The field has shipped since v5.x but the decoder ignored it.
v10.10.0 routes each per-slice 2D codestream inside
JP3DSliceStackCodec through the 2D codec's existing
decodeResolution(_:options:) (v10.5.0); returned volume sized
⌈W / 2^K⌉ × ⌈H / 2^K⌉ × D as documented.
M2 release: 2.2-3.1x faster decode at resolutionLevel = 1.
2. JP3DROIDecoder swaps decode-then-crop for true ROI footprint-skip.
Per-tile in-tile sub-region passed into JP3DSliceStackCodec, which
routes the per-slice 2D decode through decodeRegion(_:options:)
.direct strategy (v10.6.0 footprint-skip). Returned buffers sized
exactly for the region, no second intersection-crop pass needed.
3. Z-narrow ROI skip. JP3DSliceStackCodec.decode pre-scans slice
headers (no decode), finds the latest non-residual slice ≤
zRange.lowerBound, decodes from there. Slices in [z_start, zLower)
keep the Z-delta residual chain intact; out-of-Z-range slices
that precede the request are entirely skipped.
M2 release ROI 1/4 (XY footprint-skip + Z-narrow combined):
mr_3d_small 18.78 → 5.57 ms (3.37x faster than full)
ct_3d_small 64.45 → 15.55 ms (4.14x)
mr_3d_mid 130.13 → 32.84 ms (3.96x)
Combined resolutionLevel + ROI throws loud (the 2D codec doesn't yet
implement footprint-skip at a downsampled resolution — separate arc).
Previously the combination silently ignored resolutionLevel.
Files (Sources/J2K3D + Tests/JP3DTests):
- JP3DDecoder.swift Phase 2 resolutionLevel
- JP3DSliceStackCodec.swift Phase 2 + Phase 3 + Phase 6 (zRange)
+ 20-line inline COD-marker peek
(peekDecompositionLevels) for per-slice N
- JP3DROIDecoder.swift Phase 3 (true ROI) + Phase 5 guard
+ Phase 6 (zRange plumbing)
- V10_18_TrueSelectiveParityTests.swift (NEW) 9 tests:
testFullDecodeLosslessRoundTripBaseline (anchor)
testROIDecodeMatchesFullDecodeCropped (Phase 3 guard)
testROIDecodeMatchesFullDecodeCroppedAtCorner
testResolutionLevel0IsBitExactFullDecode (Phase 2 backward-compat)
testPartialResolutionShape (Phase 2 dim contract)
testPartialResolutionDeterministic
testPartialResolutionLevel2Shape (Phase 2 K=2)
testZNarrowROIBitExactWithFullCropped (Phase 6 guard)
testCombinedResolutionLevelAndROIIsPhase5Future (Phase 5 tripwire)
Tests (release mode):
- V10_18_TrueSelectiveParityTests: 9/9 PASS
- JP3DDecoderTests: 61/61 PASS
- Mandatory commit gate (release mode):
* J2KMedicalCorpusEncodePerformanceTests: 2/2 PASS
* J2KMedicalCorpusPerformanceTests: 2/2 PASS
* J2KStrictCrossCodecValidationTests: 3/3 PASS
Total: 7 tests, 0 failures, 0 unexpected (32.26 s)
README updated with v10.10.0 Current Version + Release Status paragraph
+ v10.9.3 catch-up paragraph (was missing in the v10.9.3 release).
Companion doc: Documentation/research/V10_18_JP3D_TRUE_SELECTIVE_DECODE.md.
The bench-app scaffolding from v10.18-research (J2KBenchApp Volumes
tab, 3-plane MPR viewer, 6 anatomical phantoms, J2KBenchMac --jp3d)
stays on the research branch per feedback_research_no_main_merge.md —
only the codec changes ship in this release.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
resolutionLevel = 1.decodeRegion(.direct)+ Z-narrow non-residual scan). M2 release: ROI 1/4 is 3.4–4.1× faster than full decode.resolutionLevel + ROIthrows loud (was silently ignored). Codestream bytes byte-identical to v10.9.3.Correctness gate (release mode)
Test plan
Reproducing
Companion docs
RELEASE_NOTES_v10.10.0.mdDocumentation/research/V10_18_JP3D_TRUE_SELECTIVE_DECODE.md🤖 Generated with Claude Code