src/image/imageFactory.jsjavascript
import {RescaleSlopeAndIntercept} from './rsi.js';
import {WindowLevel} from './windowLevel.js';
import {WindowPreset} from './windowPreset.js';
import {Image} from './image.js';
import {Size} from './size.js';
import {Geometry} from './geometry.js';
import {ColourMap} from './luts.js';
import {safeGet, safeGetAll} from '../dicom/dataElement.js';
import {
getImage2DSize,
getPixelSpacing,
getTagPixelUnit,
getPhotometricInterpretation,
isMonochrome,
isSecondatyCapture
} from '../dicom/dicomImage.js';
import {hasAnyPixelDataElement} from '../dicom/dicomTag.js';
import {
getRootGeometry,
getSortedFramesGeometry
} from '../dicom/dicomGeometry.js';
import {getSuvFactor} from '../dicom/dicomPet.js';
import {logger} from '../utils/logger.js';
/**
* @import {DataElement} from '../dicom/dataElement.js';
* @import {TypedArray} from '../math/types.js';
*/
/**
* @typedef {Record<string, DataElement>} DataElements
*/
/**
* Related DICOM tag keys.
*/
const TagKeys = {
TransferSyntaxUID: '00020010',
SOPClassUID: '00080016',
SOPInstanceUID: '00080018',
Modality: '00080060',
SamplesPerPixel: '00280002',
PlanarConfiguration: '00280006',
NumberOfFrames: '00280008',
RescaleSlope: '00281053',
RescaleIntercept: '00281052',
MediaStorageSOPClassUID: '00020002',
ImageType: '00080008',
PhotometricInterpretation: '00280004',
PixelRepresentation: '00280103',
BitsAllocated: '00280100',
BitsStored: '00280101',
HighBit: '00280102',
ImageOrientationPatient: '00200037',
WindowCenter: '00281050',
WindowLevel: '00281051',
WindowCenterWidthExplanation: '00281055',
RedPaletteColorLookupTableDescriptor: '00281101',
RedPaletteColorLookupTableData: '00281201',
GreenPaletteColorLookupTableData: '00281202',
BluePaletteColorLookupTableData: '00281203',
RecommendedDisplayFrameRate: '00082144'
};
/**
* Meta tag keys.
*/
const MetaTagKeys = {
// patient
PatientName: '00100010',
PatientID: '00100020',
PatientBirthDate: '00100030',
PatientSex: '00100040',
// general study
StudyDate: '00080020',
StudyTime: '00080030',
StudyInstanceUID: '0020000D',
StudyID: '00200010',
StudyDescription: '00081030',
ReferringPhysicianName: '00080090',
// general series
SeriesDate: '00080021',
SeriesTime: '00080031',
SeriesInstanceUID: '0020000E',
SeriesNumber: '00200011',
// frame of reference
FrameOfReferenceUID: '00200052',
// general equipment
Manufacturer: '00080070',
ManufacturerModelName: '00081090',
DeviceSerialNumber: '00181000',
SoftwareVersions: '00181020',
// general image
LossyImageCompression: '00282110',
// voi lut
VOILUTFunction: '00281056'
};
/**
* Get the palette colour map.
*
* @param {Record<string, DataElement>} dataElements The data elements.
* @returns {ColourMap|undefined} The palette colour map.
*/
function getPaletteColourMap(dataElements) {
let colourMap;
// check red palette descriptor (should all be equal)
// Red Palette Color Lookup Table Descriptor
// 0: number of entries in the lookup table
// 1: first input value mapped
// 2: number of bits for each entry in the Lookup Table Data (8 or 16)
const descriptor =
safeGetAll(dataElements, TagKeys.RedPaletteColorLookupTableDescriptor);
if (typeof descriptor !== 'undefined' &&
descriptor.length === 3) {
let redLut;
let greenLut;
let blueLut;
// Red Palette Color Lookup Table Data
const redLutElement =
dataElements[TagKeys.RedPaletteColorLookupTableData];
// Green Palette Color Lookup Table Data
const greenLutElement =
dataElements[TagKeys.GreenPaletteColorLookupTableData];
// Blue Palette Color Lookup Table Data
const blueLutElement =
dataElements[TagKeys.BluePaletteColorLookupTableData];
if (descriptor[2] === 16) {
let doScale = false;
// (C.7.6.3.1.5 Palette Color Lookup Table Descriptor)
// Some implementations have encoded 8 bit entries with 16 bits
// allocated, padding the high bits;
let descSize = descriptor[0];
// (C.7.6.3.1.5 Palette Color Lookup Table Descriptor)
// The first Palette Color Lookup Table Descriptor value is the
// number of entries in the lookup table. When the number of table
// entries is equal to 216 then this value shall be 0.
if (descSize === 0) {
descSize = 65536;
}
// red palette VL
// TODO vl is undefined, find info elsewhere...
const vlSize = redLutElement.vl;
// check double size
if (vlSize !== 2 * descSize) {
doScale = true;
logger.info(`16bits lut but size is not double. desc: ${
descSize } vl: ${vlSize}`);
}
// (C.7.6.3.1.6 Palette Color Lookup Table Data)
// Palette color values must always be scaled across the full
// range of available intensities
const bitsAllocated = parseInt(
safeGet(dataElements, TagKeys.BitsAllocated), 10);
if (bitsAllocated === 8) {
doScale = true;
logger.info(
'Scaling 16bits color lut since bits allocated is 8.');
}
if (doScale) {
const scaleTo8 = function (value) {
return value >> 8;
};
redLut = redLutElement.value.map(scaleTo8);
greenLut = greenLutElement.value.map(scaleTo8);
blueLut = blueLutElement.value.map(scaleTo8);
}
} else if (descriptor[2] === 8) {
// lut with vr=OW was read as Uint16, convert it to Uint8
logger.info(
'Scaling 16bits color lut since the lut descriptor is 8.');
let clone = redLutElement.value.slice(0);
// @ts-expect-error -- clone is a plain number[], it has no buffer
redLut = Array.from(new Uint8Array(clone.buffer));
clone = greenLutElement.value.slice(0);
// @ts-expect-error -- clone is a plain number[], it has no buffer
greenLut = Array.from(new Uint8Array(clone.buffer));
clone = blueLutElement.value.slice(0);
// @ts-expect-error -- clone is a plain number[], it has no buffer
blueLut = Array.from(new Uint8Array(clone.buffer));
}
colourMap = new ColourMap(redLut, greenLut, blueLut);
}
// return
return colourMap;
}
/**
* Get the window level presets.
*
* @param {Record<string, DataElement>} dataElements The data elements.
* @param {number} intensityFactor The intensity factor.
* @returns {Record<string, WindowPreset>|undefined} The presets.
*/
function getWindowPresets(dataElements, intensityFactor) {
let windowPresets;
const windowCenter = safeGetAll(dataElements, TagKeys.WindowCenter);
const windowWidth = safeGetAll(dataElements, TagKeys.WindowLevel);
if (typeof windowCenter !== 'undefined' &&
typeof windowWidth !== 'undefined') {
windowPresets = {};
const windowCWExplanation =
safeGetAll(dataElements, TagKeys.WindowCenterWidthExplanation);
let name;
for (let j = 0; j < windowCenter.length; ++j) {
const center = parseFloat(windowCenter[j]);
let width = parseFloat(windowWidth[j]);
if (!isNaN(center) && !isNaN(width) && width !== 0) {
name = '';
if (typeof windowCWExplanation !== 'undefined') {
name = windowCWExplanation[j];
}
if (name === '') {
name = `Default${j}`;
}
// the width minimum depends on the VOI LUT function:
// it is applied by the view
width *= intensityFactor;
windowPresets[name] = new WindowPreset(
name,
[new WindowLevel(
center * intensityFactor,
width
)]
);
}
if (width === 0) {
logger.warn('Zero window width found in DICOM.');
}
}
}
// return
return windowPresets;
}
/**
* Frames geometry cache: frames of a multi-frame data share
* the same data elements, avoid calculating it for each frame.
*
* @type {WeakMap<DataElements, Geometry[]|undefined>}
*/
const framesGeometryCache = new WeakMap();
/**
* Get the geometry of one frame of a multi-frame data.
*
* Frames with per-frame positions get their geometry from
* getSortedFramesGeometry: the frame position and the data time,
* or the volume index as time if frames share positions. Other
* frames are time frames: the frame geometry has the root position
* and the frame number as time. Once all frames are appended
* (see Image.appendSlice), the image has the same layout as the one
* created from the full buffer.
*
* @param {DataElements} dataElements The DICOM tags.
* @param {number} frameNumber The frame number.
* @returns {Geometry} The frame geometry.
*/
function getFrameGeometry(dataElements, frameNumber) {
if (!framesGeometryCache.has(dataElements)) {
framesGeometryCache.set(
dataElements, getSortedFramesGeometry(dataElements));
}
const framesGeometry = framesGeometryCache.get(dataElements);
let res;
if (typeof framesGeometry !== 'undefined') {
// clone: the geometry of the first frame is modified by appends
res = framesGeometry[frameNumber].clone();
} else {
const geometry = getRootGeometry(dataElements);
const size2D = getImage2DSize(dataElements);
res = new Geometry(
[geometry.getOrigin()],
new Size([size2D[0], size2D[1], 1]),
geometry.getSpacing(),
geometry.getOrientation(),
{id: {value: frameNumber}}
);
}
return res;
}
/**
* {@link Image} factory.
*/
export class ImageFactory {
/**
* Possible warning created by checkElements.
*
* @type {string|undefined}
*/
#warning;
/**
* The PET SUV factor.
*
* @type {number|undefined}
*/
#suvFactor;
/**
* Get a warning string if elements are not as expected.
* Created by checkElements.
*
* @returns {string|undefined} The warning.
*/
getWarning() {
return this.#warning;
}
/**
* Check dicom elements.
*
* @param {DataElements} dataElements The DICOM data elements.
* @returns {string|undefined} A possible warning.
* @throws {Error} Error for missing or wrong data.
*/
checkElements(dataElements) {
// reset
this.#warning = undefined;
// check image size
if (typeof getImage2DSize(dataElements) === 'undefined') {
throw new Error('No image rows or columns in DICOM file');
};
// check pixel data
if (!hasAnyPixelDataElement(dataElements)) {
throw new Error('No pixel data in DICOM file');
}
// check PET SUV
const modality = safeGet(dataElements, TagKeys.Modality);
if (typeof modality !== 'undefined' && modality === 'PT') {
const photometricInterpretation =
getPhotometricInterpretation(dataElements);
const SOPClassUID = safeGet(dataElements, TagKeys.SOPClassUID);
if (isSecondatyCapture(SOPClassUID) ||
!isMonochrome(photometricInterpretation)) {
return this.#warning;
}
const suvFactor = getSuvFactor(dataElements);
this.#suvFactor = suvFactor.value;
this.#warning = suvFactor.warning;
}
return this.#warning;
}
/**
* Get an {@link Image} object from the read DICOM file.
*
* @param {DataElements} dataElements The DICOM tags.
* @param {TypedArray} pixelBuffer The pixel buffer.
* @param {number} numberOfItems The number of load items.
* @param {number} [frameNumber] The frame number if the pixel buffer
* only contains one frame of a multi-frame data: the image is
* then one frame, the other ones are to be appended to it.
* @returns {Image} A new Image.
* @throws {Error} Error for missing or wrong data.
*/
create(dataElements, pixelBuffer, numberOfItems, frameNumber) {
// safe get shortcuts
const safeGetLocal = function (key) {
return safeGet(dataElements, key);
};
// Sample per pixels
let samplesPerPixel = safeGetLocal(TagKeys.SamplesPerPixel);
if (typeof samplesPerPixel === 'undefined') {
samplesPerPixel = 1;
}
// geometry: frames of multi-frame data are created one by one
// and assembled by the image (see Image.appendSlice)
let geometry;
if (typeof frameNumber !== 'undefined') {
geometry = getFrameGeometry(dataElements, frameNumber);
} else {
geometry = getRootGeometry(dataElements);
}
// number of pixels
const numberOfPixels = geometry.getSize().getTotalSize();
// needed for unit
const spacing2D = getPixelSpacing(dataElements);
// SOP Instance UID
const sopInstanceUid = safeGetLocal(TagKeys.SOPInstanceUID);
// check buffer size
const bufferSize = numberOfPixels * samplesPerPixel;
if (bufferSize !== pixelBuffer.length) {
logger.warn(`Badly sized pixel buffer: ${
pixelBuffer.length } != ${bufferSize}`);
if (bufferSize < pixelBuffer.length) {
pixelBuffer = pixelBuffer.slice(0, numberOfPixels);
} else {
throw new Error('Underestimated buffer size, can\'t fix it...');
}
}
// image
const image = new Image(geometry, pixelBuffer, [sopInstanceUid]);
// PhotometricInterpretation
const photo = getPhotometricInterpretation(dataElements);
if (typeof photo !== 'undefined') {
image.setPhotometricInterpretation(photo);
}
// PlanarConfiguration
const planarConfiguration =
safeGetLocal(TagKeys.PlanarConfiguration);
if (typeof planarConfiguration !== 'undefined') {
image.setPlanarConfiguration(planarConfiguration);
}
// rescale slope and intercept
let slope = 1;
// RescaleSlope
const rescaleSlope = safeGetLocal(TagKeys.RescaleSlope);
if (typeof rescaleSlope !== 'undefined') {
const value = parseFloat(rescaleSlope);
if (!isNaN(value)) {
slope = value;
}
}
let intercept = 0;
// RescaleIntercept
const rescaleIntercept = safeGetLocal(TagKeys.RescaleIntercept);
if (typeof rescaleIntercept !== 'undefined') {
const value = parseFloat(rescaleIntercept);
if (!isNaN(value)) {
intercept = value;
}
}
// PET SUV
let isPetWithSuv = false;
let intensityFactor = 1;
if (typeof this.#suvFactor !== 'undefined') {
isPetWithSuv = true;
intensityFactor = this.#suvFactor;
logger.info(`Applying PET SUV calibration: ${intensityFactor}`);
slope *= intensityFactor;
intercept *= intensityFactor;
}
const rsi = new RescaleSlopeAndIntercept(slope, intercept);
image.setRescaleSlopeAndIntercept(rsi);
// PALETTE COLOR lut
if (image.getPhotometricInterpretation() === 'PALETTE COLOR') {
const colourMap = getPaletteColourMap(dataElements);
if (typeof colourMap !== 'undefined') {
image.setPaletteColourMap(colourMap);
}
}
// meta information
// (slice capacity is used to allocate the full buffer
// when appending slices, for frames: the total number of frames)
const meta = {
sliceCapacity: numberOfItems
};
if (typeof frameNumber !== 'undefined') {
const numberOfFrames = parseInt(
safeGetLocal(TagKeys.NumberOfFrames), 10);
meta.sliceCapacity *= numberOfFrames;
}
// defaults
meta.TransferSyntaxUID = safeGetLocal(TagKeys.TransferSyntaxUID);
meta.MediaStorageSOPClassUID =
safeGetLocal(TagKeys.MediaStorageSOPClassUID);
meta.SOPClassUID = safeGetLocal(TagKeys.SOPClassUID);
meta.Modality = safeGetLocal(TagKeys.Modality);
meta.ImageType = safeGetLocal(TagKeys.ImageType);
meta.SamplesPerPixel = safeGetLocal(TagKeys.SamplesPerPixel);
meta.PhotometricInterpretation =
safeGetLocal(TagKeys.PhotometricInterpretation);
meta.PixelRepresentation = safeGetLocal(TagKeys.PixelRepresentation);
meta.BitsAllocated = safeGetLocal(TagKeys.BitsAllocated);
meta.BitsStored = safeGetLocal(TagKeys.BitsStored);
meta.HighBit = safeGetLocal(TagKeys.HighBit);
// meta tags
const metaKeys = Object.keys(MetaTagKeys);
for (const key of metaKeys) {
meta[key] = safeGetLocal(MetaTagKeys[key]);
}
// local pixel unit
if (isPetWithSuv) {
meta.pixelUnit = 'SUV';
} else {
const pixelUnit = getTagPixelUnit(dataElements);
if (typeof pixelUnit !== 'undefined') {
meta.pixelUnit = pixelUnit;
}
}
// length unit
if (typeof spacing2D === 'undefined') {
meta.lengthUnit = 'unit.pixel';
} else {
meta.lengthUnit = 'unit.mm';
}
// window level presets
const presets = getWindowPresets(dataElements, intensityFactor);
if (typeof presets !== 'undefined') {
meta.windowPresets = presets;
}
// store the meta data
image.setMeta(meta);
return image;
}
}
/**
* Demo Image creation from DICOM elements: takes
* elements and first element of the pixel buffer
* to create an image.
*
* Warning: not to be used in production code.
*
* @param {Record<string, DataElement>} elements The DICOM elements.
* @returns {Image} The Image object.
*/
export function demoCreateImage(elements) {
const factory = new ImageFactory();
return factory.create(
elements,
elements['7FE00010'].value[0],
1
);
}