A DICOM to NIfTI converter for neuroimaging data with JavaScript/WebAssembly and C++ APIs
pkg:github/rordenlab/dcm2niix@1.0.x
npx @tessl/cli install tessl/github-dcm2niix@1.0.0dcm2niix is a specialized medical imaging conversion tool that transforms neuroimaging data from the DICOM format (standard output of medical imaging devices) to the NIfTI format (popular with neuroscientists). The software is designed to handle the complexity and vendor-specific variations in DICOM files, providing a simple and explicit output format while generating BIDS JSON sidecar files with relevant metadata.
npm install @niivue/dcm2niixconda install -c conda-forge dcm2niixbrew install dcm2niixJavaScript/WebAssembly (Browser):
import { Dcm2niix } from '@niivue/dcm2niix';For JPEG-LS and JPEG2000 support:
import { Dcm2niix } from '@niivue/dcm2niix/jpeg';C++ Library Integration:
#include "nii_dicom_batch.h"
#include "nii_dicom.h"import { Dcm2niix } from '@niivue/dcm2niix';
const dcm2niix = new Dcm2niix();
await dcm2niix.init();
// Convert DICOM files from file input
const fileInput = document.getElementById('fileInput'); // webkitdirectory, multiple
const convertedFiles = await dcm2niix
.input(fileInput.files)
.bids('y') // Generate BIDS sidecar
.verbose('y') // Enable verbose output
.gzip('y') // Compress output
.run();
console.log(convertedFiles); // Array of File objects (NIfTI, JSON, etc.)# Basic conversion
dcm2niix /path/to/dicom/folder
# Advanced conversion with options
dcm2niix -z y -f %p_%t_%s -o /path/output /path/to/dicom/folder#include "nii_dicom_batch.h"
struct TDCMopts opts;
setDefaultOpts(&opts, NULL);
strcpy(opts.indir, "/path/to/dicom");
strcpy(opts.outdir, "/path/to/output");
opts.isGz = true;
opts.isCreateBIDS = true;
int result = nii_loadDir(&opts);dcm2niix is built around several key components:
Browser-based DICOM to NIfTI conversion using WebAssembly. Ideal for web applications that need to process medical imaging data client-side without server uploads.
class Dcm2niix {
constructor();
init(): Promise<boolean>;
input(fileList: FileList | File[]): Processor;
inputFromWebkitDirectory(fileList: FileList | File[]): Processor;
inputFromDropItems(items: DataTransferItem[]): Processor;
}
class Processor {
// Conversion options (chainable)
bids(value: 'y' | 'n' | 'o'): Processor;
verbose(value: 'y' | 'n' | '0' | '1' | '2'): Processor;
gzip(value: 'y' | 'o' | 'i' | 'n' | '3'): Processor;
// Execute conversion
run(): Promise<File[]>;
}Core DICOM conversion engine for integration into C++ applications. Provides low-level access to DICOM metadata and image data with full control over conversion parameters.
// Main processing function
int nii_loadDir(struct TDCMopts *opts);
// Single file processing
int singleDICOM(struct TDCMopts *opts, char *fname);
// DICOM file validation
int isDICOMfile(const char *fname);
// Configuration
void setDefaultOpts(struct TDCMopts *opts, const char *argv[]);
struct TDCMopts {
// Boolean options
bool isGz, isCreateBIDS, isVerbose, isIgnoreDerivedAnd2D;
// Integer options
int gzLevel, dirSearchDepth, saveFormat;
// String paths
char filename[512], outdir[512], indir[512];
// Series selection
double seriesNumber[16];
long numSeries;
};Traditional command-line tool for batch processing, automation, and integration with neuroimaging pipelines. Supports all conversion options and output formats.
dcm2niix [options] <input_folder>
# Key options:
-o <dir> # Output directory
-f <format> # Filename format with placeholders
-z <y|o|i|n|3> # Compression options
-b <y|n|o> # BIDS sidecar generation
-v <n|y|0|1|2> # Verbosity level
-i <y|n> # Ignore derived images
-m <n|y|0|1|2> # Merge 2D slices// DICOM metadata structure
struct TDICOMdata {
long seriesNum;
int xyzDim[5]; // Image dimensions
uint32_t seriesUidCrc; // Series identifier
int manufacturer; // Vendor (Siemens, GE, Philips, etc.)
int imageBytes; // Size of image data
float pixelSpacing[3]; // Voxel dimensions
float sliceThickness; // Slice thickness
char protocolName[64]; // Acquisition protocol
char seriesDescription[64]; // Series description
// ... additional metadata fields
};
// DTI/DWI data structure
struct TDTI4D {
struct TDTI S[16384]; // DTI gradient information
int sliceOrder[65535]; // Slice ordering for 4D data
int gradDynVol[16384]; // Volume organization
};
// Processing preferences
struct TDCMprefs {
int isVerbose; // Verbosity level
int compressFlag; // Compression handling
int isIgnoreTriggerTimes; // Ignore trigger timing
};// File input types
type FileInput = FileList | File[] | DataTransferItem[];
// Conversion result
interface ConversionResult extends File {
readonly name: string; // Output filename
readonly type: string; // MIME type
readonly size: number; // File size in bytes
}
// Processing options
type BooleanOption = 'y' | 'n';
type VerbosityLevel = 'n' | 'y' | '0' | '1' | '2';
type CompressionOption = 'y' | 'o' | 'i' | 'n' | '3';
type MergeOption = 'n' | 'y' | '0' | '1' | '2';try {
const results = await dcm2niix.input(files).run();
} catch (error) {
if (error.message.includes('exit code')) {
// dcm2niix processing failed
console.error('Conversion failed:', error.message);
} else if (error.message.includes('Worker')) {
// WebAssembly worker error
console.error('Worker initialization failed:', error.message);
}
}int result = nii_loadDir(&opts);
switch (result) {
case EXIT_SUCCESS: // 0 - Success
break;
case EXIT_FAILURE: // 1 - General failure
break;
case 2: // No valid files found
break;
case 4: // Corrupt file found
break;
// Additional exit codes documented in command-line interface
}Exit codes indicate processing status: