fix: decode the last sample of a scan that ends on a byte boundary

An entropy coded segment whose final Huffman code lands exactly on a byte
boundary needs no padding bits (T.81 B.1.1.2 pads only an incomplete final
byte), so EOI follows the last code immediately. `getHuffmanValue` and `getn`
treated that as having read into the marker and abandoned the scan one sample
early, leaving the frame's last sample 0.

`temp` holds `index` unconsumed bits. Once the 0xFF that introduces a marker
has been shifted in, its 8 bits are not data, so `index - 8` real bits are
left and consuming the last of them leaves `index === 8` - still a valid
decode. The guards tested `index < markerIndex` (9), which rejects it.
`readPastEntropyData` puts the boundary at `index < 8` and names what it is
testing; `markerIndex` keeps its 9 purely as the "marker seen" sentinel that
the other call sites already treat it as.

This replaces the `!isLastPixel()` special case in `getn`, which was covering
the same off-by-one for one of the three guard sites.

Reproduced with the single fragment of
CTImage.dcm_JPEGProcess14SV1TransferSyntax_1.2.840.10008.1.2.4.70.dcm, written
by DCMTK 3.6.1: 512x512 16 bit signed, ending in a long run of the image
minimum whose two-bit zero-difference codes tile the final byte exactly. Its
last sample decoded as 0 instead of -2000; every other sample was already
correct. Added as tests/data/jpeg_lossless_sel1-byte-aligned-end.jpg, checked
against the crc32 of the uncompressed CTImage.dcm pixel data.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: wayfarer3130

src/decoder.ts

@@ -31,6 +31,15 @@ export class Decoder {
   static RESTART_MARKER_BEGIN = 0xffd0
   static RESTART_MARKER_END = 0xffd7
 
+  // Value `markerIndex` takes once the 0xFF that introduces a marker has been
+  // shifted into `temp`. Only `!== 0` is ever tested - see `readPastEntropyData`
+  // for what the bit count itself means.
+  static MARKER_SEEN = 9
+
+  // How many bits of `temp` that 0xFF occupies. Bits below it are the marker,
+  // not entropy coded data.
+  static MARKER_BITS = 8
+
   buffer: ArrayBuffer | null = null
   stream: DataStream | null = null
   frame = new FrameHeader()
@@ -505,7 +514,7 @@ export class Decoder {
       if (input === 0xff) {
         this.marker = this.stream.get8()
         if (this.marker !== 0) {
-          this.markerIndex = 9
+          this.markerIndex = Decoder.MARKER_SEEN
         }
       }
       temp[0] |= input
@@ -528,7 +537,7 @@ export class Decoder {
       if (input === 0xff) {
         this.marker = this.stream.get8()
         if (this.marker !== 0) {
-          this.markerIndex = 9
+          this.markerIndex = Decoder.MARKER_SEEN
         }
       }
 
@@ -543,7 +552,7 @@ export class Decoder {
       throw new Error('index=' + index[0] + ' temp=' + temp[0] + ' code=' + code + ' in HuffmanValue()')
     }
 
-    if (index[0] < this.markerIndex) {
+    if (this.readPastEntropyData(index)) {
       this.markerIndex = 0
       return 0xff00 | this.marker
     }
@@ -575,8 +584,7 @@ export class Decoder {
     index[0] -= n
 
     if (index[0] >= 0) {
-      if (index[0] < this.markerIndex && !this.isLastPixel()) {
-        // this was corrupting the last pixel in some cases
+      if (this.readPastEntropyData(index)) {
         this.markerIndex = 0
         return (0xff00 | this.marker) << 8
       }
@@ -590,7 +598,7 @@ export class Decoder {
       if (input === 0xff) {
         this.marker = this.stream.get8()
         if (this.marker !== 0) {
-          this.markerIndex = 9
+          this.markerIndex = Decoder.MARKER_SEEN
         }
       }
 
@@ -609,7 +617,7 @@ export class Decoder {
         if (input === 0xff) {
           this.marker = this.stream.get8()
           if (this.marker !== 0) {
-            this.markerIndex = 9
+            this.markerIndex = Decoder.MARKER_SEEN
           }
         }
 
@@ -621,7 +629,7 @@ export class Decoder {
         throw new Error('index=' + index[0] + ' in getn()')
       }
 
-      if (index[0] < this.markerIndex) {
+      if (this.readPastEntropyData(index)) {
         this.markerIndex = 0
         return (0xff00 | this.marker) << 8
       }
@@ -669,8 +677,26 @@ export class Decoder {
     }
   }
 
-  isLastPixel() {
-    return this.xLoc === this.xDim - 1 && this.yLoc === this.yDim - 1
+  /**
+   * True when the bits just consumed came out of a marker rather than out of
+   * the entropy coded segment.
+   *
+   * `temp` holds `index` unconsumed bits (see the `getHuffmanValue` notes). The
+   * moment `getHuffmanValue`/`getn` shifts in a byte that turns out to be the
+   * 0xFF introducing a marker, those 8 bits stop being data: only the
+   * `index - MARKER_BITS` bits above them are real, and the scan is over once
+   * they run out.
+   *
+   * Consuming the last real bit leaves `index === MARKER_BITS`, and that is
+   * still a valid decode - it is a scan whose final Huffman code ends exactly
+   * on a byte boundary, so the encoder had no partial byte left to pad (T.81
+   * B.1.1.2 pads only an incomplete final byte). Testing `index < markerIndex`
+   * rejected that case and dropped the frame's last sample, which is what
+   * DCMTK produces when a frame ends in a long run of one value: the run's
+   * short codes tile the final byte exactly.
+   */
+  readPastEntropyData(index: number[]): boolean {
+    return this.markerIndex !== 0 && index[0] < Decoder.MARKER_BITS
   }
 
   outputSingle(PRED: number[]) {

tests/byte-aligned-end.test.ts

@@ -0,0 +1,62 @@
+import fs from 'fs'
+import { describe, it, assert } from 'vitest'
+import { Utils, Decoder } from '../src/main.js'
+import { toArrayBuffer } from './utils.js'
+
+/**
+ * A scan whose entropy coded segment ends exactly on a byte boundary.
+ *
+ * The frame is the single encapsulated fragment of
+ * `CTImage.dcm_JPEGProcess14SV1TransferSyntax_1.2.840.10008.1.2.4.70.dcm`
+ * (cornerstone3D `packages/dicomImageLoader/testImages`): 512x512, 16 bit
+ * signed, one component, process 14 selection value 1, point transform 0,
+ * written by DCMTK 3.6.1.
+ *
+ * It ends in a long run of the image minimum (-2000, air). A run of equal
+ * samples is a run of zero differences, and this table codes a zero difference
+ * in two bits, so the run tiles the last byte exactly and the encoder had no
+ * partial byte left to pad - EOI follows the final code with no padding bits in
+ * between. The decoder used to treat that as having read into the marker and
+ * dropped the last sample, leaving it 0 instead of -2000. Every other sample
+ * was already correct, so the assertion that matters is the last one; the
+ * checksum guards the rest of the frame against a regression that shifts it.
+ */
+const buf = fs.readFileSync('./tests/data/jpeg_lossless_sel1-byte-aligned-end.jpg')
+const decoder = new Decoder()
+const output = decoder.decode(toArrayBuffer(buf), 0, buf.length)
+const samples = new Int16Array(output.buffer, output.byteOffset, output.byteLength / 2)
+
+describe('byte-aligned-end', function () {
+  it('dimX should equal 512', function () {
+    assert.equal(512, decoder.frame.dimX)
+  })
+
+  it('dimY should equal 512', function () {
+    assert.equal(512, decoder.frame.dimY)
+  })
+
+  it('number of components should be 1', function () {
+    assert.equal(1, decoder.frame.numComp)
+  })
+
+  it('point transform should be 0', function () {
+    // So this frame is not confused with the point transform handling that is
+    // its own fix - the last sample is wrong here with Al 0.
+    assert.equal(0, decoder.scan.al)
+  })
+
+  it('decompressed size should be 524288', function () {
+    assert.equal(524288, output.byteLength)
+  })
+
+  it('the last sample should be decoded, not left at 0', function () {
+    assert.equal(-2000, samples[samples.length - 1])
+  })
+
+  it('data checksum should equal 2510355201', function () {
+    // crc32 of the pixel data of the uncompressed CTImage.dcm this was encoded
+    // from, so the whole frame is checked against ground truth, not against
+    // whatever this decoder happens to produce.
+    assert.equal(Utils.crc32(output.buffer), 2510355201)
+  })
+})