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