454 refactored Encoding/Decoding logic to expose DICOM encoding mappings for consumption

.jshintrc

@@ -1,3 +1,3 @@
 {
-  "esversion": 6
+  "esversion": 11
 }

src/AsyncDicomReader.js

@@ -7,16 +7,17 @@ import {
     VM_DELIMITER,
     UNDEFINED_LENGTH,
     TagHex,
-    encodingMapping,
     UNDEFINED_LENGTH_FIX,
     VALID_VRS,
+    singleVRs,
     isVideoTransferSyntax
 } from "./constants/dicom";
+import { encodingMapping } from "./constants/encodings";
 import { Tag } from "./Tag";
-import { DicomMessage, singleVRs } from "./DicomMessage";
+import { DicomMessage } from "./DicomMessage";
 import { DicomMetaDictionary } from "./DicomMetaDictionary";
 import { DicomMetadataListener } from "./utilities/DicomMetadataListener.js";
-import { log } from "./log.js";
+import { log } from "./utilities/log.js";
 
 const readLog = log.getLogger("AsyncDicomReader");
 
@@ -720,13 +721,13 @@ export class AsyncDicomReader {
             }
         } else {
             const value = vr.read(stream, length, syntax)?.value;
-            if (!vr.isBinary() && singleVRs.indexOf(vr.type) == -1) {
+            if (!vr.isBinary() && !singleVRs.has(vr.type)) {
                 values = value;
                 if (typeof value === "string") {
                     const delimiterChar = String.fromCharCode(VM_DELIMITER);
                     values = vr.dropPadByte(value.split(delimiterChar));
                 }
-            } else if (vr.type == "OW" || vr.type == "OB") {
+            } else if (vr.type === "OW" || vr.type === "OB") {
                 values = value;
             } else {
                 Array.isArray(value) ? (values = value) : values.push(value);
@@ -737,9 +738,8 @@ export class AsyncDicomReader {
             if (values.length > 0) {
                 let [coding] = values;
                 coding = coding.replace(/[_ ]/g, "-").toLowerCase();
-                if (coding in encodingMapping) {
-                    coding = encodingMapping[coding];
-                    this.stream.setDecoder(new TextDecoder(coding));
+                if (encodingMapping.has(coding)) {
+                    this.stream.setEncoding(coding);
                 } else if (options?.ignoreErrors) {
                     log.warn(
                         `Unsupported character set: ${coding}, using default character set`

src/BufferCODEC.js

@@ -0,0 +1,75 @@
+import { DicomMetaDictionary } from "./DicomMetaDictionary";
+import { defaultEncoding } from "./constants/encodings";
+import { selectNativeEncoding } from "./utilities/selectEncoding";
+
+/**
+ * Facilitates the conversion of binary buffers from a DICOM encoding scheme to
+ * a web supported string encoding scheme and vice versa.
+ */
+export class DicomBufferCODEC {
+    encoder = new TextEncoder(defaultEncoding);
+    decoder = new TextDecoder(defaultEncoding);
+
+    /**
+     * Use this method if you want to change the decoder directly and do not
+     * need to have the encoding scheme name translated to one of the encoding
+     * schemes supported by web browsers.
+     *
+     * For example, instead of passing ISO 2022 IR 100, you have to pass latin1.
+     * Passing an incorrect encoding scheme name will result in an exception.
+     *
+     * @param {string} webEncoding
+     */
+    setNativeDecoder(webEncoding) {
+        this.decoder = new TextDecoder(webEncoding);
+    }
+
+    /**
+     * Unused since we typically default to utf-8. This method is provided for
+     * convenience in case someone needs to encode a buffer in something else
+     * before storing in a DICOM header.
+     *
+     * @param {string} webEncoding
+     */
+    setNativeEncoder(webEncoding) {
+        this.decoder = new TextEncoder(webEncoding);
+    }
+
+    /**
+     * Main method for changing encoder.
+     *
+     * Given a DICOM encoding scheme like ISO 2022 IR 100, generate the correct
+     * string to store to disk.
+     *
+     * Optionally, include whether to ignore or throw an exception if dicom to
+     * web encoding is not found in our mapping
+     *
+     * @param {string} dicomEncoding
+     * @param {boolean} ignoreErrors
+     */
+    setEncoding(dicomEncoding, ignoreErrors = false) {
+        let coding = selectNativeEncoding(dicomEncoding, ignoreErrors);
+        this.setNativeEncoder(coding);
+        this.setNativeDecoder(coding);
+    }
+
+    /**
+     * Convenience method as would be found in TextEncoder and TextDecoder APIs.
+     *
+     * @param data
+     * @returns {string}
+     */
+    decode(data) {
+        return this.decoder.decode(data);
+    }
+
+    /**
+     * Convenience method as would be found in TextEncoder and TextDecoder APIs.
+     *
+     * @param {string} data
+     * @returns {Uint8Array}
+     */
+    encode(data) {
+        return this.encoder.encode(data);
+    }
+}

src/BufferStream.js

@@ -2,6 +2,8 @@ import pako from "pako";
 import SplitDataView from "./SplitDataView";
 import { toFloat } from "./utilities/toFloat";
 import { toInt } from "./utilities/toInt";
+import { DicomBufferCODEC } from "./BufferCODEC";
+import { defaultDICOMEncoding } from "./constants/encodings";
 
 export class BufferStream {
     offset = 0;
@@ -18,12 +20,14 @@ export class BufferStream {
     /** A flag to set to indicate to clear buffers as they get consumed */
     clearBuffers = false;
 
-    encoder = new TextEncoder("utf-8");
+    codec = new DicomBufferCODEC();
 
     constructor(options = null) {
         this.isLittleEndian = options?.littleEndian || this.isLittleEndian;
         this.view.defaultSize = options?.defaultSize ?? this.view.defaultSize;
         this.clearBuffers = options.clearBuffers || false;
+
+        this.setEncoding(options?.encoding || defaultDICOMEncoding);
     }
 
     /**
@@ -68,8 +72,20 @@ export class BufferStream {
         return true;
     }
 
-    setEndian(isLittle) {
-        this.isLittleEndian = isLittle;
+    setEncoding(dicomEncoding, ignoreErrors) {
+        this.codec.setEncoding(dicomEncoding, ignoreErrors);
+    }
+
+    setEndian(isLittleEndian = true) {
+        this.isLittleEndian = isLittleEndian;
+    }
+
+    setLittleEndian() {
+        this.isLittleEndian = true;
+    }
+
+    setBigEndian() {
+        this.isLittleEndian = false;
     }
 
     slice(start = this.startOffset, end = this.endOffset) {
@@ -169,7 +185,7 @@ export class BufferStream {
     }
 
     writeUTF8String(value) {
-        const encodedString = this.encoder.encode(value);
+        const encodedString = this.codec.encode(value);
         this.checkSize(encodedString.byteLength);
         this.view.writeBuffer(encodedString, this.offset);
         return this.increment(encodedString.byteLength);
@@ -300,7 +316,7 @@ export class BufferStream {
         const view = new DataView(
             this.slice(this.offset, this.offset + length)
         );
-        const result = this.decoder.decode(view);
+        const result = this.codec.decode(view);
         this.increment(length);
         return result;
     }
@@ -453,16 +469,16 @@ export class BufferStream {
 export class ReadBufferStream extends BufferStream {
     constructor(
         buffer,
-        littleEndian,
+        littleEndian = false,
         options = {
             start: null,
             stop: null,
             noCopy: false
-        }
+        },
+        encoding = defaultDICOMEncoding
     ) {
-        super({ ...options, littleEndian });
+        super({ ...options, littleEndian, encoding });
         this.noCopy = options.noCopy;
-        this.decoder = new TextDecoder("latin1");
 
         if (buffer instanceof BufferStream) {
             this.view.from(buffer.view, options);
@@ -478,10 +494,6 @@ export class ReadBufferStream extends BufferStream {
         this.endOffset = this.size;
     }
 
-    setDecoder(decoder) {
-        this.decoder = decoder;
-    }
-
     reset() {
         this.offset = this.startOffset;
         return this;
@@ -564,8 +576,8 @@ export class DeflatedReadBufferStream extends ReadBufferStream {
 }
 
 export class WriteBufferStream extends BufferStream {
-    constructor(defaultSize, littleEndian) {
-        super({ defaultSize, littleEndian });
+    constructor(defaultSize, littleEndian, encoding = defaultDICOMEncoding) {
+        super({ defaultSize, littleEndian, encoding });
         this.size = 0;
     }
 }

src/DicomDict.js

@@ -1,6 +1,7 @@
 import { WriteBufferStream } from "./BufferStream";
 import { ValueRepresentation } from "./ValueRepresentation";
 import { TagHex } from "./constants/dicom";
+import { defaultDICOMEncoding } from "./constants/encodings";
 
 const EXPLICIT_LITTLE_ENDIAN = "1.2.840.10008.1.2.1";
 
@@ -22,13 +23,28 @@ class DicomDict {
         }
     }
 
-    write(writeOptions = { allowInvalidVRLength: false }) {
-        var metaSyntax = EXPLICIT_LITTLE_ENDIAN;
-        var fileStream = new WriteBufferStream(4096, true);
+    write(
+        writeOptions = {
+            allowInvalidVRLength: false,
+            encoding: defaultDICOMEncoding,
+            littleEndian: true
+        }
+    ) {
+        const metaSyntax = EXPLICIT_LITTLE_ENDIAN;
+        const fileStream = new WriteBufferStream(
+            4096,
+            writeOptions.littleEndian,
+            writeOptions.encoding
+        );
+
         fileStream.writeUint8Repeat(0, 128);
         fileStream.writeAsciiString("DICM");
 
-        var metaStream = new WriteBufferStream(1024);
+        const metaStream = new WriteBufferStream(
+            1024,
+            writeOptions.littleEndian,
+            writeOptions.encoding
+        );
         if (!this.meta[TagHex.TransferSyntaxUID]) {
             this.meta[TagHex.TransferSyntaxUID] = {
                 vr: "UI",
@@ -46,7 +62,7 @@ class DicomDict {
         );
         fileStream.concat(metaStream);
 
-        var useSyntax = this.meta[TagHex.TransferSyntaxUID].Value[0];
+        const useSyntax = this.meta[TagHex.TransferSyntaxUID].Value[0];
         DicomMessage.write(this.dict, fileStream, useSyntax, writeOptions);
         return fileStream.getBuffer();
     }