0
# dcm2niix
1
2
dcm2niix 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.
3
4
## Package Information
5
6
- **Package Name**: dcm2niix
7
- **Package Type**: github
8
- **Language**: C++ (core), JavaScript (wrapper)
9
- **Installation**:
10
- **Browser**: `npm install @niivue/dcm2niix`
11
- **Command-line**: Download from [GitHub releases](https://github.com/rordenlab/dcm2niix/releases)
12
- **Conda**: `conda install -c conda-forge dcm2niix`
13
- **Homebrew**: `brew install dcm2niix`
14
15
## Core Imports
16
17
JavaScript/WebAssembly (Browser):
18
19
```javascript
20
import { Dcm2niix } from '@niivue/dcm2niix';
21
```
22
23
For JPEG-LS and JPEG2000 support:
24
25
```javascript
26
import { Dcm2niix } from '@niivue/dcm2niix/jpeg';
27
```
28
29
C++ Library Integration:
30
31
```cpp
32
#include "nii_dicom_batch.h"
33
#include "nii_dicom.h"
34
```
35
36
## Basic Usage
37
38
### JavaScript/WebAssembly (Browser)
39
40
```javascript
41
import { Dcm2niix } from '@niivue/dcm2niix';
42
43
const dcm2niix = new Dcm2niix();
44
await dcm2niix.init();
45
46
// Convert DICOM files from file input
47
const fileInput = document.getElementById('fileInput'); // webkitdirectory, multiple
48
const convertedFiles = await dcm2niix
49
.input(fileInput.files)
50
.bids('y') // Generate BIDS sidecar
51
.verbose('y') // Enable verbose output
52
.gzip('y') // Compress output
53
.run();
54
55
console.log(convertedFiles); // Array of File objects (NIfTI, JSON, etc.)
56
```
57
58
### Command-Line Interface
59
60
```bash
61
# Basic conversion
62
dcm2niix /path/to/dicom/folder
63
64
# Advanced conversion with options
65
dcm2niix -z y -f %p_%t_%s -o /path/output /path/to/dicom/folder
66
```
67
68
### C++ Library Integration
69
70
```cpp
71
#include "nii_dicom_batch.h"
72
73
struct TDCMopts opts;
74
setDefaultOpts(&opts, NULL);
75
strcpy(opts.indir, "/path/to/dicom");
76
strcpy(opts.outdir, "/path/to/output");
77
opts.isGz = true;
78
opts.isCreateBIDS = true;
79
80
int result = nii_loadDir(&opts);
81
```
82
83
## Architecture
84
85
dcm2niix is built around several key components:
86
87
- **Core Engine**: C++ DICOM reading and NIfTI conversion engine with support for multiple vendor formats
88
- **JavaScript API**: WebAssembly wrapper providing browser-based conversion capabilities
89
- **Command-Line Interface**: Traditional CLI tool for batch processing and automation
90
- **Library Integration**: C++ API for embedding in other applications
91
- **Format Support**: Extensive DICOM transfer syntax support including JPEG, JPEG-LS, and JPEG2000
92
93
## Capabilities
94
95
### JavaScript/WebAssembly API
96
97
Browser-based DICOM to NIfTI conversion using WebAssembly. Ideal for web applications that need to process medical imaging data client-side without server uploads.
98
99
```javascript { .api }
100
class Dcm2niix {
101
constructor();
102
init(): Promise<boolean>;
103
input(fileList: FileList | File[]): Processor;
104
inputFromWebkitDirectory(fileList: FileList | File[]): Processor;
105
inputFromDropItems(items: DataTransferItem[]): Processor;
106
}
107
108
class Processor {
109
// Conversion options (chainable)
110
bids(value: 'y' | 'n' | 'o'): Processor;
111
verbose(value: 'y' | 'n' | '0' | '1' | '2'): Processor;
112
gzip(value: 'y' | 'o' | 'i' | 'n' | '3'): Processor;
113
114
// Execute conversion
115
run(): Promise<File[]>;
116
}
117
```
118
119
[JavaScript API](./javascript-api.md)
120
121
### C++ Library API
122
123
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.
124
125
```cpp { .api }
126
// Main processing function
127
int nii_loadDir(struct TDCMopts *opts);
128
129
// Single file processing
130
int singleDICOM(struct TDCMopts *opts, char *fname);
131
132
// DICOM file validation
133
int isDICOMfile(const char *fname);
134
135
// Configuration
136
void setDefaultOpts(struct TDCMopts *opts, const char *argv[]);
137
138
struct TDCMopts {
139
// Boolean options
140
bool isGz, isCreateBIDS, isVerbose, isIgnoreDerivedAnd2D;
141
142
// Integer options
143
int gzLevel, dirSearchDepth, saveFormat;
144
145
// String paths
146
char filename[512], outdir[512], indir[512];
147
148
// Series selection
149
double seriesNumber[16];
150
long numSeries;
151
};
152
```
153
154
[C++ Library API](./cpp-library-api.md)
155
156
### Command-Line Interface
157
158
Traditional command-line tool for batch processing, automation, and integration with neuroimaging pipelines. Supports all conversion options and output formats.
159
160
```bash { .api }
161
dcm2niix [options] <input_folder>
162
163
# Key options:
164
-o <dir> # Output directory
165
-f <format> # Filename format with placeholders
166
-z <y|o|i|n|3> # Compression options
167
-b <y|n|o> # BIDS sidecar generation
168
-v <n|y|0|1|2> # Verbosity level
169
-i <y|n> # Ignore derived images
170
-m <n|y|0|1|2> # Merge 2D slices
171
```
172
173
[Command-Line Interface](./command-line-interface.md)
174
175
## Types
176
177
### Common Data Structures
178
179
```cpp { .api }
180
// DICOM metadata structure
181
struct TDICOMdata {
182
long seriesNum;
183
int xyzDim[5]; // Image dimensions
184
uint32_t seriesUidCrc; // Series identifier
185
int manufacturer; // Vendor (Siemens, GE, Philips, etc.)
186
int imageBytes; // Size of image data
187
float pixelSpacing[3]; // Voxel dimensions
188
float sliceThickness; // Slice thickness
189
char protocolName[64]; // Acquisition protocol
190
char seriesDescription[64]; // Series description
191
// ... additional metadata fields
192
};
193
194
// DTI/DWI data structure
195
struct TDTI4D {
196
struct TDTI S[16384]; // DTI gradient information
197
int sliceOrder[65535]; // Slice ordering for 4D data
198
int gradDynVol[16384]; // Volume organization
199
};
200
201
// Processing preferences
202
struct TDCMprefs {
203
int isVerbose; // Verbosity level
204
int compressFlag; // Compression handling
205
int isIgnoreTriggerTimes; // Ignore trigger timing
206
};
207
```
208
209
### JavaScript Types
210
211
```typescript { .api }
212
// File input types
213
type FileInput = FileList | File[] | DataTransferItem[];
214
215
// Conversion result
216
interface ConversionResult extends File {
217
readonly name: string; // Output filename
218
readonly type: string; // MIME type
219
readonly size: number; // File size in bytes
220
}
221
222
// Processing options
223
type BooleanOption = 'y' | 'n';
224
type VerbosityLevel = 'n' | 'y' | '0' | '1' | '2';
225
type CompressionOption = 'y' | 'o' | 'i' | 'n' | '3';
226
type MergeOption = 'n' | 'y' | '0' | '1' | '2';
227
```
228
229
## Error Handling
230
231
### JavaScript API
232
233
```javascript
234
try {
235
const results = await dcm2niix.input(files).run();
236
} catch (error) {
237
if (error.message.includes('exit code')) {
238
// dcm2niix processing failed
239
console.error('Conversion failed:', error.message);
240
} else if (error.message.includes('Worker')) {
241
// WebAssembly worker error
242
console.error('Worker initialization failed:', error.message);
243
}
244
}
245
```
246
247
### C++ API
248
249
```cpp
250
int result = nii_loadDir(&opts);
251
switch (result) {
252
case EXIT_SUCCESS: // 0 - Success
253
break;
254
case EXIT_FAILURE: // 1 - General failure
255
break;
256
case 2: // No valid files found
257
break;
258
case 4: // Corrupt file found
259
break;
260
// Additional exit codes documented in command-line interface
261
}
262
```
263
264
### Command-Line Interface
265
266
Exit codes indicate processing status:
267
- **0**: Success
268
- **1**: General failure
269
- **2**: No valid DICOM files found
270
- **3**: Version information displayed
271
- **4**: Corrupt file encountered
272
- **5**: Invalid input folder
273
- **6**: Invalid output folder
274
- **7**: Read-only output folder
275
- **8**: Some files converted successfully, others failed
276
- **9**: File rename error
277
- **10**: Incomplete volumes found