0
# Command-Line Interface
1

2
Traditional command-line tool for batch processing, automation, and integration with neuroimaging pipelines. The CLI supports all conversion options and output formats with comprehensive parameter control.
3

4
## Installation
5

6
### Package Managers
7

8
```bash
9
# Conda (recommended)
10
conda install -c conda-forge dcm2niix
11

12
# Homebrew (macOS)
13
brew install dcm2niix
14

15
# APT (Debian/Ubuntu)
16
sudo apt-get install dcm2niix
17

18
# pip (Python wrapper)
19
python -m pip install dcm2niix
20
```
21

22
### Binary Downloads
23

24
Download pre-compiled binaries from [GitHub Releases](https://github.com/rordenlab/dcm2niix/releases):
25

26
```bash
27
# Linux
28
curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
29

30
# macOS
31
curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/macos_dcm2niix.pkg
32

33
# Windows
34
curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_win.zip
35
```
36

37
## Basic Usage
38

39
```bash { .api }
40
dcm2niix [options] <input_folder>
41
```
42

43
### Simple Examples
44

45
```bash
46
# Basic conversion
47
dcm2niix /path/to/dicom/folder
48

49
# Specify output directory
50
dcm2niix -o /path/to/output /path/to/dicom
51

52
# Enable compression and BIDS
53
dcm2niix -z y -b y /path/to/dicom
54

55
# Custom filename format
56
dcm2niix -f %p_%s_%t -o /output /dicom
57
```
58

59
### Advanced Examples
60

61
```bash
62
# Complete neuroimaging pipeline setup
63
dcm2niix -z y -b y -ba y -f %p_%t_%s -o /bids/sub-01/ses-01 /dicom/sub-01/ses-01
64

65
# High-quality conversion with maximum compression
66
dcm2niix -z o -9 -l y -p y -x n -b y /dicom
67

68
# Selective series conversion
69
dcm2niix -n 1234567890 -n 0987654321 -v y /dicom
70

71
# Research-grade conversion with detailed output
72
dcm2niix -z y -v 2 -b y -ba n -l y -m 2 -i n /dicom
73
```
74

75
## Command-Line Options
76

77
### Core Options
78

79
```bash { .api }
80
-h                    # Show help information
81
-v [n|y|0|1|2]       # Verbosity: n/0=quiet, y/1=verbose, 2=very verbose  
82
-o <directory>        # Output directory (default: input directory)
83
-f <format>          # Filename format with placeholders (default: %f_%p_%t_%s)
84
```
85

86
**Usage:**
87
```bash
88
dcm2niix -v 2 -o /output -f %p_%s_%e /dicom  # Very verbose, custom output and filename
89
```
90

91
### BIDS Options
92

93
```bash { .api }
94
-b [y|n|o]           # BIDS sidecar: y=generate, n=none, o=only sidecar (no NIfTI)
95
-ba [y|n]            # BIDS anonymization: y=anonymize, n=keep patient details
96
```
97

98
**Usage:**
99
```bash
100
dcm2niix -b y -ba y /dicom        # Generate anonymized BIDS sidecar
101
dcm2niix -b o /dicom              # Generate only BIDS sidecar, no NIfTI
102
```
103

104
### Compression Options
105

106
```bash { .api }
107
-z [y|o|i|n|3]       # Compression: y=pigz, o=optimal pigz, i=internal, n=none, 3=no 3D
108
-1..-9               # Compression level (1=fastest, 9=smallest, default=6)
109
```
110

111
**Usage:**
112
```bash
113
dcm2niix -z y -6 /dicom          # Use pigz with level 6 compression
114
dcm2niix -z o -9 /dicom          # Optimal pigz with maximum compression
115
dcm2niix -z i /dicom             # Use internal compression
116
```
117

118
### Processing Options  
119

120
```bash { .api }
121
-a [y|n]             # Adjacent DICOMs: y=same folder assumption, n=search subdirs
122
-i [y|n]             # Ignore derived, localizer and 2D images: y=ignore, n=include
123
-m [n|y|0|1|2]       # Merge 2D slices: n/0=no merge, y/1=force merge, 2=auto merge
124
-s [y|n]             # Single file mode: y=process one file only, n=process all
125
-r [y|n]             # Rename mode: y=rename files instead of convert, n=convert
126
```
127

128
**Usage:**
129
```bash
130
dcm2niix -i y -m 2 /dicom        # Ignore derived images, auto-merge 2D slices
131
dcm2niix -s y /dicom/image.dcm   # Process single file only
132
dcm2niix -r y -f %p_%s /dicom    # Rename files with custom format
133
```
134

135
### Data Processing Options
136

137
```bash { .api }
138
-l [y|n|o]           # Lossless 16-bit scaling: y=scale, n=uint16→int16, o=original
139
-p [y|n]             # Philips precise float scaling: y=precise, n=display scaling
140
-x [y|n|i]           # Crop 3D acquisitions: y=crop, n=no crop, i=ignore (no crop/rotate)
141
```
142

143
**Usage:**
144
```bash
145
dcm2niix -l y -p y -x n /dicom   # Scale 16-bit, precise Philips scaling, no crop
146
```
147

148
### Format Options
149

150
```bash { .api }
151
-e [y|n|o|j|b]       # Export format: y=NRRD, n=NIfTI, o=MGH, j=JSON, b=BJNIfTI
152
--big-endian [y|n|o] # Byte order: y=big-endian, n=little-endian, o=optimal/native
153
```
154

155
**Usage:**
156
```bash
157
dcm2niix -e y /dicom             # Export as NRRD instead of NIfTI
158
dcm2niix -e j /dicom             # Export as JSON/JNIfTI  
159
dcm2niix --big-endian y /dicom   # Force big-endian byte order
160
```
161

162
### Metadata Options
163

164
```bash { .api }
165
-c <comment>         # Comment for NIfTI aux_file (up to 24 characters)
166
-d [0-9]             # Directory search depth (default: 5)
167
-n <number>          # Convert specific series CRC number (repeatable up to 16 times)
168
```
169

170
**Usage:**
171
```bash
172
dcm2niix -c "Research Study" /dicom              # Add comment to NIfTI header
173
dcm2niix -d 3 /dicom                            # Search 3 levels deep
174
dcm2niix -n 1234567890 -n 0987654321 /dicom    # Convert only specific series
175
```
176

177
### Search and Processing Control
178

179
```bash { .api }
180
-q [y|l|n]           # Search directory: y=show count, l=list files, n=no search info
181
-w [0|1|2]           # Name conflicts: 0=skip duplicates, 1=overwrite, 2=add suffix
182
```
183

184
**Usage:**
185
```bash
186
dcm2niix -q l /dicom             # List all DICOM files found
187
dcm2niix -w 1 /dicom             # Overwrite existing files
188
```
189

190
### Advanced Options
191

192
```bash { .api }
193
--progress [y|n]     # Progress reporting: y=show progress, n=quiet
194
--ignore_trigger_times # Disregard trigger time values from DICOM tags
195
--terse              # Omit filename post-fixes (may cause overwrites)
196
--xml                # Enable Slicer format features  
197
--version            # Display version information and exit
198
```
199

200
**Usage:**
201
```bash
202
dcm2niix --progress y --ignore_trigger_times /dicom
203
dcm2niix --terse -f %p_%s /dicom
204
dcm2niix --xml /dicom
205
```
206

207
## Filename Format Placeholders
208

209
The `-f` option accepts format strings with placeholders that are replaced with DICOM metadata:
210

211
```bash { .api }
212
%a    # Antenna (coil) name
213
%b    # Basename  
214
%c    # Comments
215
%d    # Description
216
%e    # Echo number
217
%f    # Folder name
218
%g    # Accession number
219
%i    # Patient ID
220
%j    # Series Instance UID
221
%k    # Study Instance UID  
222
%m    # Manufacturer
223
%n    # Patient name
224
%o    # Media Object Instance UID
225
%p    # Protocol name
226
%r    # Instance number
227
%s    # Series number
228
%t    # Time
229
%u    # Acquisition number
230
%v    # Vendor
231
%x    # Study ID
232
%z    # Sequence name
233
```
234

235
### Filename Examples
236

237
```bash
238
# Protocol_Series_Time format
239
dcm2niix -f %p_%s_%t /dicom
240

241
# Patient_Protocol_Echo format  
242
dcm2niix -f %n_%p_e%e /dicom
243

244
# BIDS-style naming
245
dcm2niix -f sub-%i_ses-%t_task-%p /dicom
246

247
# Manufacturer and protocol
248
dcm2niix -f %m_%p_%s /dicom
249
```
250

251
## Exit Codes
252

253
```bash { .api }
254
0     # EXIT_SUCCESS - Conversion completed successfully
255
1     # EXIT_FAILURE - General failure  
256
2     # No valid DICOM files found in input directory
257
3     # Version information displayed (not an error)
258
4     # Corrupt DICOM file encountered
259
5     # Invalid input folder specified
260
6     # Invalid output folder specified
261
7     # Output folder is read-only
262
8     # Some files converted successfully, others failed
263
9     # File rename error occurred
264
10    # Incomplete volumes found in input
265
11    # Nominal completion (no conversion expected)
266
```
267

268
### Exit Code Handling
269

270
```bash
271
#!/bin/bash
272
dcm2niix -z y -b y "$1"
273
result=$?
274

275
case $result in
276
  0)
277
    echo "Conversion successful"
278
    ;;
279
  2)
280
    echo "No DICOM files found in $1"
281
    exit 1
282
    ;;
283
  4)
284
    echo "Corrupt DICOM files detected"
285
    exit 1
286
    ;;
287
  8)
288
    echo "Partial conversion - some files failed"
289
    exit 1
290
    ;;
291
  *)
292
    echo "Conversion failed with exit code $result"
293
    exit 1
294
    ;;
295
esac
296
```
297

298
## Integration Examples
299

300
### Neuroimaging Pipeline Integration
301

302
```bash
303
#!/bin/bash
304
# Complete BIDS conversion pipeline
305

306
DICOM_DIR="/data/dicom"
307
BIDS_DIR="/data/bids"
308
SUBJECT="01"
309
SESSION="baseline"
310

311
# Create BIDS directory structure
312
mkdir -p "$BIDS_DIR/sub-$SUBJECT/ses-$SESSION"
313

314
# Convert with BIDS format
315
dcm2niix \
316
  -z y \
317
  -b y \
318
  -ba y \
319
  -f "sub-${SUBJECT}_ses-${SESSION}_%p_%s_%t" \
320
  -o "$BIDS_DIR/sub-$SUBJECT/ses-$SESSION" \
321
  "$DICOM_DIR/sub-$SUBJECT/ses-$SESSION"
322

323
# Validate conversion
324
if [ $? -eq 0 ]; then
325
  echo "BIDS conversion completed for sub-$SUBJECT ses-$SESSION"
326
  
327
  # Run BIDS validator
328
  bids-validator "$BIDS_DIR"
329
else
330
  echo "BIDS conversion failed"
331
  exit 1
332
fi
333
```
334

335
### Batch Processing Script
336

337
```bash
338
#!/bin/bash
339
# Batch convert multiple subjects
340

341
DICOM_ROOT="/data/dicom"  
342
OUTPUT_ROOT="/data/nifti"
343

344
# Process all subject directories
345
for subject_dir in "$DICOM_ROOT"/sub-*; do
346
  if [ -d "$subject_dir" ]; then
347
    subject=$(basename "$subject_dir")
348
    echo "Processing $subject..."
349
    
350
    # Create output directory
351
    mkdir -p "$OUTPUT_ROOT/$subject"
352
    
353
    # Convert with quality settings
354
    dcm2niix \
355
      -z y \
356
      -b y \
357
      -v 1 \
358
      -l y \
359
      -m 2 \
360
      -i y \
361
      -f "${subject}_%p_%s_%e" \
362
      -o "$OUTPUT_ROOT/$subject" \
363
      "$subject_dir"
364
    
365
    result=$?
366
    if [ $result -eq 0 ]; then
367
      echo "✓ $subject converted successfully"
368
    else
369
      echo "✗ $subject conversion failed (exit code: $result)"
370
    fi
371
  fi
372
done
373
```
374

375
### Research Quality Control
376

377
```bash
378
#!/bin/bash
379
# Research-grade conversion with QC
380

381
INPUT_DIR="$1"
382
OUTPUT_DIR="$2"
383
LOG_FILE="${OUTPUT_DIR}/conversion.log"
384

385
if [ $# -ne 2 ]; then
386
  echo "Usage: $0 <input_dir> <output_dir>"
387
  exit 1
388
fi
389

390
# Create output directory
391
mkdir -p "$OUTPUT_DIR"
392

393
# Convert with maximum quality and logging
394
dcm2niix \
395
  -z o \
396
  -9 \
397
  -b y \
398
  -ba n \
399
  -v 2 \
400
  -l y \
401
  -p y \
402
  -m 2 \
403
  -i n \
404
  -x n \
405
  -f "%p_%t_%s_%e" \
406
  -o "$OUTPUT_DIR" \
407
  "$INPUT_DIR" 2>&1 | tee "$LOG_FILE"
408

409
result=$?
410

411
# Generate summary report
412
echo "=== Conversion Summary ===" >> "$LOG_FILE"
413
echo "Input: $INPUT_DIR" >> "$LOG_FILE"
414
echo "Output: $OUTPUT_DIR" >> "$LOG_FILE"
415
echo "Exit Code: $result" >> "$LOG_FILE"
416
echo "Files Generated:" >> "$LOG_FILE"
417
find "$OUTPUT_DIR" -name "*.nii*" -o -name "*.json" | wc -l >> "$LOG_FILE"
418

419
if [ $result -eq 0 ]; then
420
  echo "Conversion completed successfully"
421
else
422
  echo "Conversion failed - check $LOG_FILE for details"
423
fi
424
```
425

426
### Selective Series Conversion
427

428
```bash
429
#!/bin/bash
430
# Convert only specific sequences
431

432
DICOM_DIR="$1"
433
OUTPUT_DIR="$2"
434

435
# First, discover series
436
echo "Discovering DICOM series..."
437
dcm2niix -q l "$DICOM_DIR" > series_list.txt
438

439
# Extract series CRC numbers for specific protocols  
440
T1_SERIES=$(grep -i "t1.*mprage\|mprage.*t1" series_list.txt | awk '{print $1}')
441
T2_SERIES=$(grep -i "t2.*flair\|flair.*t2" series_list.txt | awk '{print $1}')
442
DTI_SERIES=$(grep -i "dti\|diffusion" series_list.txt | awk '{print $1}')
443

444
# Convert T1 anatomical
445
if [ ! -z "$T1_SERIES" ]; then
446
  echo "Converting T1 series: $T1_SERIES"
447
  dcm2niix -n "$T1_SERIES" -f "anat_T1w_%s" -o "$OUTPUT_DIR/anat" "$DICOM_DIR"
448
fi
449

450
# Convert T2 FLAIR
451
if [ ! -z "$T2_SERIES" ]; then
452
  echo "Converting T2 series: $T2_SERIES" 
453
  dcm2niix -n "$T2_SERIES" -f "anat_T2w_%s" -o "$OUTPUT_DIR/anat" "$DICOM_DIR"
454
fi
455

456
# Convert DTI
457
if [ ! -z "$DTI_SERIES" ]; then
458
  echo "Converting DTI series: $DTI_SERIES"
459
  dcm2niix -n "$DTI_SERIES" -f "dwi_DTI_%s" -o "$OUTPUT_DIR/dwi" "$DICOM_DIR"
460
fi
461

462
rm series_list.txt
463
```
464

465
## Performance Optimization
466

467
### High-Volume Processing
468

469
```bash
470
# Optimize for large datasets
471
dcm2niix \
472
  -z o \               # Optimal compression (uses multiple cores)  
473
  -9 \                 # Maximum compression
474
  -a y \               # Adjacent DICOMs (faster)
475
  -m 2 \               # Auto-merge (reduces I/O)
476
  -v 0 \               # Quiet mode (faster)
477
  /path/to/dicom
478
```
479

480
### Memory-Constrained Systems
481

482
```bash  
483
# Reduce memory usage
484
dcm2niix \
485
  -z i \               # Internal compression (less memory)
486
  -6 \                 # Moderate compression
487
  -s y \               # Single file mode if processing one at a time
488
  /path/to/dicom
489
```
490

491
### Network Storage Optimization
492

493
```bash
494
# Optimize for network filesystems
495
dcm2niix \
496
  -z n \               # No compression initially
497
  -a y \               # Assume adjacent files
498
  -v 0 \               # Minimize I/O chatter
499
  -o /local/temp \     # Use local storage for output
500
  /network/dicom
501

502
# Compress afterward if needed
503
gzip /local/temp/*.nii
504
```
505

506
## Troubleshooting
507

508
### Common Issues
509

510
```bash
511
# Issue: No DICOM files found
512
dcm2niix -q l /path/to/check     # List files to verify DICOM presence
513
dcm2niix -d 9 /path/to/deep      # Increase search depth
514

515
# Issue: Permission errors  
516
dcm2niix -o /tmp /readonly/dicom # Use writable output directory
517

518
# Issue: Filename conflicts
519
dcm2niix -w 2 /dicom             # Add suffix to avoid overwrites
520

521
# Issue: Large file sizes
522
dcm2niix -z y -9 /dicom          # Enable maximum compression
523

524
# Issue: Missing metadata
525
dcm2niix -v 2 -b y /dicom        # Verbose output with BIDS sidecar
526
```
527

528
### Debugging
529

530
```bash
531
# Maximum verbosity for debugging
532
dcm2niix -v 2 --progress y /dicom 2>&1 | tee debug.log
533

534
# Test single file
535
dcm2niix -s y -v 2 /dicom/single_file.dcm
536

537
# Check version and build info
538
dcm2niix --version
539
```
540

541
### Validation
542

543
```bash
544
# Verify output files
545
find output_dir -name "*.nii*" -exec file {} \;
546

547
# Check NIfTI headers  
548
fslhd output.nii.gz
549

550
# Validate BIDS compliance
551
bids-validator /bids/dataset
552

553
# Compare with reference
554
dcm2niix -v 2 reference/ > ref.log 2>&1
555
dcm2niix -v 2 test/ > test.log 2>&1
556
diff ref.log test.log
557
```