feat: Add untilTag option to readFile

[swederik]

Test it with:

const fs = require('fs');
const dcmjs = require('./build/dcmjs.js')
const buffer = fs.readFileSync('1-001.dcm');

const { DicomMessage, DicomMetaDictionary } = dcmjs.data;
console.time('readFile');
const fullData = DicomMessage.readFile(buffer.buffer)
console.timeEnd('readFile');

console.time('readFile with untilTag');
const dicomData = DicomMessage.readFile(buffer.buffer, { 'untilTag': '7FE00010' });
console.timeEnd('readFile with untilTag');

const dataset = DicomMetaDictionary.naturalizeDataset(dicomData.dict);
dataset._meta = DicomMetaDictionary.namifyDataset(dicomData.meta);

console.log(dataset.PixelData);

[swederik]

@pieper suggests switching it to allow namified version instead and I agree. I'll do that before merging

[jmhmd]

@swederik May be helpful also to have an stopAfterTag option as well, to include the provided tag and exclude everything after. I implemented this quickly in my own fork like this:

while (!bufferStream.end()) {
  if (breakOnNextLoop === true) {
      break;
  }
  const readInfo = DicomMessage.readTag(bufferStream, syntax);
  const cleanTagString = readInfo.tag.toCleanString();

  if (untilTag && untilTag === cleanTagString) {
      break;
  }
  if (stopAfterTag && stopAfterTag === cleanTagString) {
      breakOnNextLoop = true;
  }

  ...
}

Would submit pull request but looks like you want to allow namified version to these options. Happy to help if you like, but still getting my bearings with this library!

[jmhmd]

Opened PR #149 to address these issues, including namified support. Would appreciate feedback/review!

[Ouwen]

@jmhmd Great PR on #149, I think the fromDirtyString function is quite convenient.

@pieper @swederik @jmhmd
Would it be okay to simplify the API to just untilTag, and ignoreTheUntilTagValue?
This will change the default behavior of untilTag to finish adding the value to the dict (so it becomes like stopTag).

ignoreTheUntilTagValue will decide whether or not to actually parse the tag value and hook into the ReadTag function where bytes are parsed.

The only major deviation will be that this will return a dict where a tag is present with null values and null value representation. I don't think this should be a big issue since the existence of the tag key is a useful flag for whether the untilTag condition was met. Additionally, the user explicitly asked to ignore values of the tag in question and can delete this strange key prior to passing it to other dcmjs functions.

[pieper]

fromDirtyString function is quite convenient

True, but as a matter of style I'd like to encourage the use of the keywords from the data dictionary and keep the hex out of the code for readability.

Would it be okay to simplify the API to just untilTag, and ignoreTheUntilTagValue?

That make sense. There's a general guideline to use positive statements for boolean flags, so maybe better is readUntilTagValue or includeUntilTagValue.