Read different series of dicom

Hi everyone,
I’ve got an issue when loading some dicom files using itk-wasm, in the past I load the uploaded files through readImageDICOMFileSeries, it worked fine when there is just a single serie.
But some of the dicoms are mixed with different series, e.g. one series is a summary of 256 * 256 * 1 sized image with component 3 and othes have size of 800 * 800 * 1 with component 1, and the 256 * 256 one might be the first, the last or some other order to be imported. Here are some results for different imports and setups:
1. The image of 3 components is the first file to be imported, in this situation the error ReadImageDICOMFileSeries.umd.js:9 Only one pixel component is currently supported. Image pixel components: 3 will always show not matter singleSortedSeries param is true or false.
2. The image of 3 components is not the first and singleSortedSeries is set to false, in this situation the correct ct data will not be read, result will be only the 3 component one.
3. The image of 3 components is not the first and singleSortedSeries is set to true, in this situation the correct ct data can be read.

I can read the single file information with readImageFile, but since it’s not ordered, if I read it one by one, the error WebAssembly.instantiate(): Out of memory will show if files are big enough.

How should I handle this correctly to get the different series info? The source files are from different scan machines so the names of the files and the order can not be changed.


I’ve made a mistake that I didn’t pass the worker to next readImageFile call, when it is passed the out of memory situation will not present, the readImageFile can work properly.

Hi @Xoz ,

Welcome to the ITK community! :sun_with_face:

A note – the updated DICOM package is now at @itk-wasm/dicom.

The readDicomTags function can be used to help identify the different series.


Hi @matt.mccormick ,
I’ve met a problem that when reading dicom files from some devices, the readImageFile throws an error ‘No DICOM magic number found, but the file appears to be DICOM without a preamble’, it seems that the dicom files lost some part called preamble, but it can be display in 3d sclicer correctly, should I manully add the lost part to the file?

I’ve also done update itk to the newest version to check if this could be solved but find readImageFile deprecated, the error log tolds me to use new one from @itk-wam/image-io, but that module does not have a function exported which named with that. I’ve found a readImage function, but when I run it to replace the old readImageFile(params changed) like this:

import { readImage } from '@itk-wasm/image-io'
// in an async func, file is an input File given by an input element
    const imageResult = await readImage(file, { webWorker: null })

The promise keeps pending at this state and will not return anything. The readDicomTags from module dicom still have the same problem.

Did I miss anything important? The document for web io api is still the older version one at


Hi @Xoz ,

Just a note that there are improvements in progress in handling the dicom preamble in the upcoming ITK 5.4.

Yes, a dicom preamble should be in dicom files - you may want to fix the file or how it was generated.

Did I miss anything important? The document for web io api is still the older version one at Web Browser Input/Output - ITK-Wasm documentation

The docs are currently being updated.

The interface has been simplified and changed. Notes can be found in the migration guide and breaking changes log.

The readImage interface in @itk-wasm/image-io is documented here. This link can be found on the packages page.

Essentially, you want:

const { image } = await readImage(file)

And the @itk-wasm/dicom docs are here.

I plan to provide a high level interface in the dicom package that works with all types of dicom object types over the next few months.

1 Like

Thanks matt, I’ll check it again to find out the reason why async functions did not work

1 Like

Hi matt,
I still can not get it to work, here is a sandbox, could you please check it if you have spare time? The dicom file to test is in the public dir if you do not have.
ITK module demo
I’m just using the methods like what I did in older version itk-wasm(orders of params are changed), but the promise returned by new APIs (including readImage and readDicomTags) seem to be always pending

Hi @Xoz ,

With sandbox, I made the following changes. Reading the dicom tags work, I did not see about the images.

package.json: remove the itk-wasm entry, update the packages. Mixing that very old pre-release version of itk-wasm with the newer packages is likely not compatible. The newer itk-wasm packages are modular and self-sufficient.

  "dependencies": {
    "@ffmpeg/ffmpeg": "^0.11.6",
    "@itk-wasm/dicom": "^7.0.0",
    "@itk-wasm/image-io": "^1.2.0",
    "@kitware/vtk.js": "^28.2.7",
    "jszip": "^3.10.1",
    "vue": "^3.2.45"

vite.config.js: due to limitation / bug of vite regarding transitive dependencies, we want to exclude the itk-wasm packages from optimization. This can also be seen in the vite.config.js examples in the itk-wasm demo apps.

  optimizeDeps: {
    exclude: ['itk-wasm', '@itk-wasm/image-io', '@itk-wasm/dicom-io', '@thewtex/zstddec']

CTManager.ts: Update and use the simplified readImageDicomFileSeries calls. There is now only one function. And the input is an object with inputFiles property.

import {
} from "@itk-wasm/dicom";
import vtkImageData from "@kitware/vtk.js/Common/DataModel/ImageData";
import vtkITKHelper from "@kitware/vtk.js/Common/DataModel/ITKHelper";

class CTManager {
  vtkImage: vtkImageData;
  constructor() {
    this.vtkImage = vtkImageData.newInstance();
  // load dicom url
  public async loadDICOMsThroughURLs(urls: string[]) {
    try {
      const binaryFiles = (url) =>
        const response = fetch(url)
        const arrayBuffer = await response.arrayBuffer()
        const urlObj = new URL(url)
        const basename = urlObj.pathname.split('/').pop()
        return { path: basename, data: new Uint8Array(arrayBuffer) }
      const seriesBinaryFiles = await Promise.all(binaryFiles);
      const { image } = await readImageDicomFileSeries(
        { inputFiles: seriesBinaryFiles }
      this.vtkImage = vtkITKHelper.convertItkToVtkImage(image);
    } catch (err) {
      console.error("load dicom fail");
  // load dicom file
  public async loadDICOMsThroughFiles(list: FileList) {
    try {
      const { image } = await readImageDicomFileSeries({ inputImages: list });
      this.vtkImage = vtkITKHelper.convertItkToVtkImage(image);
    } catch (err) {
      console.error("load dicom fail");
  public getVtkImage() {
    return this.vtkImage;

export default CTManager;

ITKLoad.vue: use new API

      <button @click="triggerLoadFile">LoadFrom@itk-wasm/dicom</button>
      <input type="file" ref="input" class="invisible" @change="onFileChange" />
      <button type="primary" @click="triggerLoadFile2">
        Load from itk-wasm ver.b174(work)
<script lang="ts" setup>
import { readDicomTags } from "@itk-wasm/dicom";
import { readImage } from "@itk-wasm/image-io";
import { ref } from "vue";

type Nullable<T> = T | null;

const input = ref<Nullable<HTMLElement>>(null); // @itk-wasm/dicom
const input2 = ref<Nullable<HTMLElement>>(null); // itk-wasm
const triggerLoadFile = () => input.value?.click();
const triggerLoadFile2 = () => input2.value?.click();
const onFileChange = async (e: any) => {
  const files =;
  const tags = await readDicomTags(files[0], { webWorker: null });

input {
  visibility: hidden;
1 Like

Hi @matt.mccormick ,
Thank you for your reply, the reason I use the readDicomTags instead of readImageDicomFileSeries is that sometimes user would select and upload all the files in a folder which includes multiple series in a case. In this case readImageDicomFileSeries will throw error for the unsupported series whose image pixel components is 3, so I use readDicomTags to sort them at first.

I have set the excluded packages in vite config and update to newest package, it is working.

1 Like