chore(openjphjs): upstream OpenJPH master + partial HTJ2K decode (supersedes #68)

packages/dicom-codec/src/codecs/codecFactory.js

@@ -229,6 +229,34 @@ function getImageFrame(typedArray) {
   return typedArray;
 }
 
+/**
+ * Copies a codec buffer out of WASM memory into a JS-owned typed array.
+ *
+ * The codecs' getDecodedBuffer()/getEncodedBuffer() hand back an emscripten
+ * `typed_memory_view` — a live window onto the wasm heap, owned by the codec
+ * instance, NOT a copy. Every way that instance can move on invalidates it:
+ *
+ *   - `delete()` frees the underlying vector, so the view aliases memory the
+ *     allocator is free to hand to anything else;
+ *   - reusing the instance (see `reuseDecoder`) overwrites the same bytes on the
+ *     next decode, so a caller holding views for frames 1..n of a series would
+ *     find every one of them showing frame n;
+ *   - a decode that grows the heap detaches the view's ArrayBuffer outright, and
+ *     reads then throw.
+ *
+ * So the copy is not an optimisation trade-off — returning the view is wrong in
+ * all three cases. It costs one memcpy of the frame against a decode, and it is
+ * what makes reuse safe.
+ *
+ * @param {TypedArray} typedArray a view into WASM memory.
+ * @returns {TypedArray} an equivalent array backed by its own ArrayBuffer.
+ */
+function copyFromWasm(typedArray) {
+  // slice() preserves the element type and returns a fresh buffer at offset 0,
+  // which also keeps the 16-bit views getPixelData() builds correctly aligned.
+  return getImageFrame(typedArray).slice();
+}
+
 /**
  * Encode imageFrame using Encoder from the given local param.
  *
@@ -264,6 +292,11 @@ function encode(context, codecConfig, imageFrame, imageInfo, options = {}) {
     "Encoded is a Typed array of: " + encodedTypedArray.constructor.name
   );
 
+  // Copy BEFORE delete(): see copyFromWasm. delete() frees the vector this view
+  // points into, so returning the view alone hands the caller memory the wasm
+  // allocator may reissue at any time.
+  const encodedCopy = copyFromWasm(encodedTypedArray);
+
   // cleanup allocated memory
   encoderInstance.delete();
 
@@ -272,7 +305,7 @@ function encode(context, codecConfig, imageFrame, imageInfo, options = {}) {
   };
 
   return {
-    imageFrame: getImageFrame(encodedTypedArray),
+    imageFrame: encodedCopy,
     imageInfo: getTargetImageInfo(imageInfo, imageInfo),
     processInfo,
   };
@@ -287,14 +320,43 @@ function encode(context, codecConfig, imageFrame, imageInfo, options = {}) {
  * @param {CodecWrapper} codecConfig codec wrapper configuration.
  * @param {TypedArray} imageFrame current image frame pixels.
  * @param {ExtendedImageInfo} imageInfo previous image info object.
- * @returns Object containing decoded image frame and imageInfo (current) data
+ * @param {*} [options] process options.
+ * @param {boolean} [options.reuseDecoder=false] keep one decoder instance on
+ *   codecConfig and reuse it across calls instead of constructing and deleting
+ *   one per frame. Opt-in per codec: a decoder that carries state between
+ *   decodes, or whose retained buffers grow, must not set it. The returned
+ *   imageFrame is copied out of WASM memory either way (see copyFromWasm), so
+ *   holding frames from several decodes is safe; call releaseDecoder to give the
+ *   retained heap back.
+ * @returns Object containing decoded image frame and imageInfo (current) data.
+ *   processInfo.partial is true when the codec parsed the header but did not
+ *   finish decoding; the frame is correctly sized and the undecoded region is
+ *   zero-filled.
+ * @throws Will throw when the codec could not parse the codestream header, so
+ *   that an unusable frame is never reported as a successful decode.
  *
  */
-function decode(context, codecConfig, imageFrame, imageInfo) {
+function decode(context, codecConfig, imageFrame, imageInfo, options = {}) {
   if (!imageFrame?.length) {
     throw new Error("Image frame not defined for decoding");
   }
-  const decoderInstance = new codecConfig.Decoder();
+
+  // Constructing a wasm decoder is not cheap — it allocates heap, registers
+  // embind bindings and, for openjph, ran its constructor banner through the
+  // console. Doing that per frame dominated series decoding: it is the bulk of
+  // the gap between dispatching HTJ2K through this factory and calling
+  // openjphjs directly. Reused decoders are held on codecConfig, which is the
+  // per-codec singleton the wrapper modules already share.
+  const reuseDecoder = options.reuseDecoder === true;
+  let decoderInstance;
+  if (reuseDecoder) {
+    if (!codecConfig.reusedDecoder) {
+      codecConfig.reusedDecoder = new codecConfig.Decoder();
+    }
+    decoderInstance = codecConfig.reusedDecoder;
+  } else {
+    decoderInstance = new codecConfig.Decoder();
+  }
 
   const { length } = imageFrame;
   // get pointer to the source/encoded bit stream buffer in WASM memory
@@ -318,23 +380,108 @@ function decode(context, codecConfig, imageFrame, imageInfo) {
   // get information about the decoded image
   const decodedImageInfo = decoderInstance.getFrameInfo();
 
-  // cleanup allocated memory
-  decoderInstance.delete();
+  // Copy out of WASM memory before anything can invalidate the view — the
+  // delete() below, or the next decode on a reused instance. See copyFromWasm.
+  const decodedCopy = copyFromWasm(decodedTypedArray);
+
+  const decodeStatus = getDecodeStatus(decoderInstance);
+
+  // cleanup allocated memory — except when reusing, where the whole point is
+  // that this instance survives to the next call. openjphjs' decoder-reuse
+  // test covers the consequence that matters: retained buffers must not make
+  // successive decodes progressively slower.
+  if (!reuseDecoder) {
+    decoderInstance.delete();
+  }
+
+  if (decodeStatus.failed && !decodeStatus.headerValid) {
+    // Nothing usable came back: the codec could not parse the header, so the
+    // dimensions and the buffer are both meaningless. Decoders that swallow
+    // this (openjph, so that truncated streams can degrade gracefully) would
+    // otherwise have this function report success on an empty or wrongly sized
+    // frame — and with a reused decoder, report it under the previous frame's
+    // pixels. Throwing here is the pre-reuse behaviour for a stream that
+    // genuinely cannot be decoded.
+    throw new Error("Decode failed: " + decodeStatus.message);
+  }
 
   const processInfo = {
     duration: context.timer.getDuration(),
   };
 
+  if (decodeStatus.failed) {
+    // Header parsed but the decode did not finish: a correctly sized frame
+    // whose undecoded region is zero-filled. Not the truncation case — openjph
+    // absorbs a short codestream as zero coefficients and calls that a success
+    // (measured across every truncation length of a 185 KB fixture), so what
+    // lands here is a codestream whose markers parse but whose parameters the
+    // decoder rejects. Reported rather than thrown, because the frame that came
+    // back is real as far as it goes; flagged, because it is not the whole image.
+    processInfo.partial = true;
+    processInfo.partialReason = decodeStatus.message;
+    context.logger.log("Partial decode: " + decodeStatus.message);
+  }
+
   return {
-    imageFrame: getImageFrame(decodedTypedArray),
+    imageFrame: decodedCopy,
     imageInfo: getTargetImageInfo(imageInfo, decodedImageInfo),
     processInfo,
   };
 }
 
+/**
+ * Reads a decoder's post-decode failure state.
+ *
+ * Most codecs signal a decode failure by throwing, which runProcess already
+ * propagates. openjph does not: it swallows the exception so that a partial
+ * codestream can degrade to a partial image, and reports the outcome through
+ * getIsHeaderValid()/getLastErrorMessage() instead. Both are optional — a codec
+ * that does not expose them is treated as "succeeded", which is exactly right
+ * for the throw-on-failure codecs.
+ *
+ * @param {Object} decoderInstance codec decoder instance.
+ * @returns {{failed: boolean, headerValid: boolean, message: string}}
+ */
+function getDecodeStatus(decoderInstance) {
+  const message =
+    typeof decoderInstance.getLastErrorMessage === "function"
+      ? decoderInstance.getLastErrorMessage() || ""
+      : "";
+  const headerValid =
+    typeof decoderInstance.getIsHeaderValid === "function"
+      ? decoderInstance.getIsHeaderValid()
+      : true;
+
+  return { failed: message !== "", headerValid, message };
+}
+
+/**
+ * Deletes the decoder a previous decode({ reuseDecoder: true }) left on
+ * codecConfig, releasing the WASM heap it retains.
+ *
+ * A reused decoder keeps the buffers sized for the largest frame it has seen
+ * for the lifetime of the module, which is the point — but a consumer that
+ * decoded one very large series and is done with it has no other way to get
+ * that memory back. Safe to call at any time and on a codec that never reused:
+ * the next decode simply constructs a new decoder.
+ *
+ * @param {CodecWrapper} codecConfig codec wrapper configuration.
+ * @returns {boolean} true if a decoder was released.
+ */
+function releaseDecoder(codecConfig) {
+  if (!codecConfig?.reusedDecoder) {
+    return false;
+  }
+
+  codecConfig.reusedDecoder.delete();
+  codecConfig.reusedDecoder = undefined;
+  return true;
+}
+
 exports.runProcess = runProcess;
 exports.encode = encode;
 exports.decode = decode;
 exports.initialize = initialize;
 exports.getPixelData = getPixelData;
 exports.getTargetImageInfo = getTargetImageInfo;
+exports.releaseDecoder = releaseDecoder;

packages/dicom-codec/src/codecs/htj2k.js

@@ -29,7 +29,9 @@ async function decode(imageFrame, imageInfo) {
     codecWasmModule,
     codecWrapper.decoderName,
     (context) => {
-      return codecFactory.decode(context, codecWrapper, imageFrame, imageInfo);
+      return codecFactory.decode(context, codecWrapper, imageFrame, imageInfo, {
+        reuseDecoder: true,
+      });
     }
   );
 }
@@ -64,6 +66,17 @@ function getPixelData(imageFrame, imageInfo) {
   return codecFactory.getPixelData(imageFrame, imageInfo);
 }
 
+/**
+ * Release the decoder kept alive by `reuseDecoder` above, and the WASM heap
+ * sized for the largest frame it has decoded. The next decode builds a new one.
+ *
+ * @returns {boolean} true if a reused decoder was released.
+ */
+function release() {
+  return codecFactory.releaseDecoder(codecWrapper);
+}
+
 exports.decode = decode;
 exports.encode = encode;
 exports.getPixelData = getPixelData;
+exports.release = release;

packages/dicom-codec/src/codecs/index.js

@@ -55,6 +55,16 @@ function hasCodec(transferSyntaxUID) {
   return !!codecsMap[transferSyntaxUID];
 }
 
+/**
+ * Every distinct codec module, deduplicated — codecsMap points several transfer
+ * syntaxes at the same module.
+ *
+ * @returns {Array<Object>} codec modules.
+ */
+function getCodecs() {
+  return [...new Set(Object.values(codecsMap))];
+}
+
 function getCodec(transferSyntaxUID) {
   const codec = codecsMap[transferSyntaxUID];
   if (!codec) {
@@ -112,4 +122,5 @@ function adaptImageInfo(imageInfo) {
 
 exports.adaptImageInfo = adaptImageInfo;
 exports.getCodec = getCodec;
+exports.getCodecs = getCodecs;
 exports.hasCodec = hasCodec;

packages/dicom-codec/src/index.js

@@ -133,6 +133,34 @@ function hasCodec(transferSyntaxUID) {
   return codecs.hasCodec(transferSyntaxUID)
 }
 
+/**
+ * Release any per-codec resources held between calls.
+ *
+ * Only codecs that keep a decoder alive across decodes have anything to release
+ * (currently HTJ2K, which reuses one decoder instead of constructing one per
+ * frame). Everything the codec needs is rebuilt on the next decode, so this is
+ * always safe — it is for consumers who are done with a large series and want
+ * the WASM heap back rather than something callers must remember to do.
+ *
+ * @param {string} [transferSyntaxUID] release only this codec; omit to release all.
+ * @returns {boolean} true if anything was released.
+ *
+ * @throws Will throw an error if transferSyntaxUID is given and has no codec.
+ */
+function release(transferSyntaxUID) {
+  const target = transferSyntaxUID
+    ? [codecs.getCodec(transferSyntaxUID)]
+    : codecs.getCodecs()
+
+  // Several transfer syntaxes share one codec module; reduce over all of them
+  // so `release()` with no argument does not stop at the first one that had
+  // nothing to free.
+  return target.reduce(
+    (released, codec) => (codec.release ? codec.release() : false) || released,
+    false
+  )
+}
+
 /**
  * Set codecs general configuration.
  *
@@ -153,6 +181,7 @@ const dicomCodec = {
   encode,
   getPixelData,
   hasCodec,
+  release,
   setConfig,
   transcode,
 }