or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/dcm2niix@1.0.x

docs

reference

batch-processing.mdbids-json.mdcli-options.mdfiltering.mdimage-processing.mdoutput-formats.mdpython-api.mdsupported-formats.md
index.md
tile.json

tessl/pypi-dcm2niix

tessl install tessl/pypi-dcm2niix@1.0.5

Command-line application that converts medical imaging data from DICOM format to NIfTI format with BIDS support

bids-json.mddocs/reference/

BIDS JSON Metadata

dcm2niix generates comprehensive BIDS (Brain Imaging Data Structure) compliant JSON sidecars containing metadata extracted from DICOM headers.

Capabilities

BIDS Sidecar Generation

Control JSON sidecar file creation.

-b <y/n/o>

BIDS JSON generation mode:

  • y = create JSON sidecar alongside NIfTI (default)
  • n = no JSON sidecar
  • o = only JSON, no NIfTI file
-ba <y/n>

Anonymize BIDS output (default: y). Removes patient identifying information including:

  • Patient name
  • Patient ID
  • Patient birth date
  • SeriesInstanceUID
  • StudyInstanceUID
  • Study ID
  • Accession number
  • Referring physician name
  • Acquisition date/time
-bi <subject_id>

BIDS subject ID override. Overrides automatic subject identifier.

-bv <session_id>

BIDS session/visit identifier. Sets session ID for multi-session studies.

Patient Information Fields

Extracted when not anonymized (-ba n).

{
  "PatientName": "string",
  "PatientID": "string",
  "PatientSex": "M|F|O|?",
  "PatientAge": "number (years)",
  "PatientBirthDate": "YYYY-MM-DD",
  "PatientSize": "number (meters)",
  "PatientWeight": "number (kg)",
  "Quadruped": "boolean"
}

Study Identification Fields

Study-level identifiers (removed when -ba y).

{
  "SeriesInstanceUID": "string (DICOM UID)",
  "StudyInstanceUID": "string (DICOM UID)",
  "StudyID": "string",
  "AccessionNumber": "string",
  "ReferringPhysicianName": "string"
}

Study Information Fields

Study and series descriptive metadata.

{
  "StudyDescription": "string",
  "SeriesDescription": "string",
  "SeriesNumber": "integer",
  "AcquisitionNumber": "integer",
  "InstanceNumber": "integer"
}

Equipment Information Fields

Scanner and device identification.

{
  "Modality": "CR|CT|MR|PT|US",
  "Manufacturer": "string (Siemens|GE|Philips|Toshiba|Canon|Mediso|Hitachi|UIH|etc.)",
  "ManufacturersModelName": "string",
  "DeviceSerialNumber": "string",
  "StationName": "string",
  "SoftwareVersions": "string"
}

Institution Fields

Facility information.

{
  "InstitutionName": "string",
  "InstitutionalDepartmentName": "string",
  "InstitutionAddress": "string"
}

MR Acquisition Parameter Fields

Core MR imaging parameters.

{
  "MagneticFieldStrength": "number (Tesla)",
  "ImagingFrequency": "number (MHz)",
  "MRAcquisitionType": "2D|3D",
  "ProtocolName": "string",
  "ScanningSequence": "string (SE|IR|GR|EP|RM)",
  "SequenceVariant": "string (SK|MTC|SS|TRSS|SP|MP|OSP)",
  "SequenceName": "string",
  "PulseSequenceName": "string",
  "ScanOptions": "string"
}

Image Type Fields

Classification and processing status.

{
  "ImageType": ["string", "array", "from", "DICOM", "0008,0008"],
  "ImageTypeText": "string (vendor-specific interpretation)",
  "ImageComments": "string (from DICOM 0020,4000)",
  "ConversionComments": "string (user-supplied via -c option)",
  "ComplexImageComponent": "MAGNITUDE|PHASE|REAL|IMAGINARY|FIELDMAPHZ",
  "RawImage": "boolean (false for derived images)"
}

Timing Information Fields

Acquisition timing metadata.

{
  "AcquisitionTime": "HH:MM:SS.ffffff",
  "AcquisitionDateTime": "YYYY-MM-DDTHH:MM:SS.ffffff (when not anonymized)",
  "TriggerDelayTime": "number (milliseconds)",
  "ContentTime": "HH:MM:SS.ffffff"
}

MR Imaging Parameter Fields

Detailed pulse sequence parameters.

{
  "FlipAngle": "number (degrees)",
  "EchoTime": "number (seconds, TE)",
  "RepetitionTime": "number (seconds, TR)",
  "InversionTime": "number (seconds, TI)",
  "PixelBandwidth": "number (Hz/pixel)",
  "PhaseEncodingSteps": "integer",
  "FrequencyEncodingSteps": "integer",
  "NumberOfAverages": "number",
  "NumberOfExcitations": "number",
  "EchoNumber": "integer",
  "EchoTrainLength": "integer"
}

Parallel Imaging Fields

Acceleration and reconstruction parameters.

{
  "AccelerationFactorPE": "number (SENSE/GRAPPA in-plane)",
  "AccelerationFactorOOP": "number (SMS/multiband slice)",
  "ParallelReductionFactorInPlane": "number",
  "ParallelAcquisitionTechnique": "string (SENSE|GRAPPA|mSENSE|ARC|etc.)"
}

Field of View and Geometry Fields

Spatial parameters and orientation.

{
  "PhaseFieldOfView": "number (fraction)",
  "PercentPhaseFOV": "number (percentage)",
  "PixelSpacing": "[number, number] (row, column in mm)",
  "SliceThickness": "number (mm)",
  "SpacingBetweenSlices": "number (mm)",
  "ImageOrientationPatientDICOM": "[6 numbers, direction cosines]",
  "InPlanePhaseEncodingDirectionDICOM": "COL|ROW",
  "PatientPosition": "string (HFS|FFS|HFP|FFP|HFDR|HFDL|FFDR|FFDL)",
  "BodyPartExamined": "string"
}

CT-Specific Fields

CT acquisition parameters.

{
  "ConvolutionKernel": "string",
  "ExposureTime": "number (milliseconds)",
  "XRayTubeCurrent": "number (mA)",
  "KVP": "number (kilovoltage peak)",
  "Exposure": "number (mAs)",
  "GantryTilt": "number (degrees)"
}

Diffusion Imaging Fields

DWI/DTI parameters.

{
  "DiffusionBValue": "number (s/mm²)",
  "DiffusionGradientDirection": "[number, number, number] (normalized x,y,z)",
  "DiffusionDirection": "[number, number, number] (original)",
  "DiffusionDirectionality": "DIRECTIONAL|ISOTROPIC|NONE",
  "DiffusionScheme": "string (MONOPOLAR|etc.)"
}

ASL (Arterial Spin Labeling) Fields

ASL perfusion imaging parameters.

{
  "LabelingDistance": "number (mm)",
  "LabelingPulseFlipAngle": "number (degrees)",
  "LabelingPulseDuration": "number (seconds)",
  "LabelingPulseMaximumGradient": "number (mT/m)",
  "PostLabelingDelay": "[array of PLD values for multi-PLD]"
}

PET Imaging Fields

PET-specific metadata including tracer and reconstruction details.

{
  "TracerRadionuclide": "string (e.g., C-11, F-18)",
  "Radiopharmaceutical": "string",
  "RadionuclidePositronFraction": "number",
  "RadionuclideHalfLife": "number (seconds)",
  "InjectedRadioactivity": "number (MBq)",
  "InjectedVolume": "number (mL)",
  "DoseCalibrationFactor": "number",
  "DecayCorrection": "string (START|ADMIN|NONE)",
  "AttenuationCorrectionMethod": "string",
  "ReconstructionMethod": "string",
  "ScatterFraction": "number",
  "DecayFactor": "[array for multi-frame]",
  "FrameTimesStart": "[array in seconds]",
  "FrameDuration": "[array in seconds]",
  "FrameReferenceTime": "[array in seconds]",
  "ReconFilterSize": "number (mm)",
  "ReconMethodName": "string",
  "ReconMethodParameterLabels": "[\"subsets\", \"iterations\"]",
  "ReconMethodParameterValues": "[integer, integer]"
}

Philips-Specific Fields

Philips vendor-specific scaling and parameters.

{
  "PhilipsRWVSlope": "number",
  "PhilipsRWVIntercept": "number",
  "PhilipsRescaleSlope": "number",
  "PhilipsRescaleIntercept": "number",
  "PhilipsScaleSlope": "number",
  "UsePhilipsFloatNotDisplayScaling": "boolean"
}

GE-Specific Fields

GE vendor-specific parameters.

{
  "InternalPulseSequenceName": "string (e.g., EPI, EPI2, spiral)"
}

Gradient Correction Fields

Gradient nonlinearity correction status.

{
  "NonlinearGradientCorrection": "boolean"
}

Deidentification Fields

Documentation of anonymization methods.

{
  "DeidentificationMethod": "string",
  "DeidentificationMethodCodeSequence": [
    {
      "CodeValue": "string",
      "CodeMeaning": "string",
      "CodingSchemeDesignator": "string",
      "CodingSchemeVersion": "string"
    }
  ]
}

Usage Examples

Generate BIDS JSON Sidecars

dcm2niix -b y /input/folder

Creates .json files alongside .nii files with full metadata.

Anonymized BIDS Output

dcm2niix -b y -ba y /input/folder

Generates JSON sidecars with patient identifying information removed.

Non-Anonymized (Full Metadata)

dcm2niix -b y -ba n /input/folder

Includes patient name, ID, birthdate, and UIDs in JSON output.

BIDS with Subject and Session IDs

dcm2niix -b y -bi sub-001 -bv ses-01 /input/folder

Overrides subject ID to "sub-001" and session ID to "ses-01" in metadata.

JSON Only, No NIfTI

dcm2niix -b o /input/folder

Generates only JSON sidecars without creating NIfTI files. Useful for metadata extraction.

No BIDS JSON

dcm2niix -b n /input/folder

Converts DICOM to NIfTI without generating JSON sidecars.

Custom Comment in JSON

dcm2niix -c "Study_XYZ" -b y /input/folder

Adds "Study_XYZ" to the ConversionComments field in JSON output.

Anonymize Comment Field

dcm2niix -c "" -b y /input/folder

Clears the DICOM comment field (0020,4000) and omits it from JSON.

BIDS JSON Example

Example JSON sidecar for an MR T1-weighted MPRAGE sequence:

{
  "Modality": "MR",
  "Manufacturer": "Siemens",
  "ManufacturersModelName": "Prisma",
  "MagneticFieldStrength": 3,
  "ImagingFrequency": 123.25,
  "DeviceSerialNumber": "67890",
  "StationName": "AWP67890",
  "SoftwareVersions": "syngo MR E11",
  "MRAcquisitionType": "3D",
  "SeriesDescription": "T1_MPRAGE_SAG_P2_ISO",
  "ProtocolName": "T1_MPRAGE",
  "ScanningSequence": "GR\\IR",
  "SequenceVariant": "SK\\SP\\MP",
  "ScanOptions": "IR",
  "SequenceName": "*tfl3d1_16ns",
  "ImageType": ["ORIGINAL", "PRIMARY", "M", "ND", "NORM"],
  "SeriesNumber": 5,
  "AcquisitionTime": "13:45:23.567000",
  "AcquisitionNumber": 1,
  "SliceThickness": 1,
  "FlipAngle": 9,
  "EchoTime": 0.00296,
  "RepetitionTime": 2.3,
  "InversionTime": 0.9,
  "PixelBandwidth": 200,
  "PhaseEncodingSteps": 256,
  "AccelerationFactorPE": 2,
  "ParallelAcquisitionTechnique": "GRAPPA",
  "PatientPosition": "HFS",
  "ConversionComments": "VIP_Study"
}

Notes

  • BIDS JSON files have the same base name as NIfTI files with .json extension
  • When -ba y (anonymize), patient-identifying fields are omitted entirely
  • JSON format follows BIDS specification for standardized neuroimaging data
  • Vendor-specific fields vary by manufacturer (Siemens, GE, Philips, etc.)
  • Multi-echo sequences may produce multiple JSON files with _e1, _e2 postfixes
  • Field presence depends on DICOM header completeness; missing tags result in omitted fields
  • UTC timestamps are used when available; local time otherwise