new stable release (v1.0.20241208)

.codespellrc

@@ -3,9 +3,10 @@ skip = .git,*.json,dcm_qa*
 # te - the TE used in the code often
 # clen - another common variable for length of smth
 # tage - for \tAge, inline ignores are yet to be released
+# SPOFF - GE diffusion cycling mode
 # nd - there is some kind of ND whi
 # ❯ grep -e 'trace or MD ' -e 'Trace/ND' ./console/nii_dicom_batch.cpp
 #		// the isotropic trace or MD can be calculated) often come as
 #			/*if (!dcmList[indx0].isDerived) //no need to warn if images are derived Trace/ND pair
 # ser - used in  printMessage(" acq %d img %d ser %ld ...
-ignore-words-list = te,clen,tage,nd,ser
+ignore-words-list = clen,hep,indx,nd,ser,spoff,tage,te

.github/workflows/release.yml

@@ -0,0 +1,13 @@
+name: Release
+on: {push: {tags: ['v*.*.*']}}
+jobs:
+  pypi:
+    permissions: {id-token: write}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with: {fetch-depth: 0, submodules: recursive}
+    - uses: actions/setup-python@v5
+      with: {python-version: '3.x'}
+    - uses: casperdcl/deploy-pypi@v2
+      with: {build: -s, upload: true}

.gitignore

@@ -10,6 +10,11 @@ __pycache__/
 /_cmake_test_compile/
 /dcm2niix/_dist_ver.py
 /dcm2niix/dcm2niix
-MANIFEST
+/MANIFEST*
 /*.egg*/
 /dist/
+
+dist
+node_modules
+dcm2niix.js
+dcm2niix.wasm

BIDS/README.md

@@ -78,10 +78,11 @@ These fields are present regardless of modality (e.g. MR, CT, PET).
 
 | Field                    | Unit | Comments            | Defined By |
 |--------------------------|------|---------------------|------------|
-| BodyPartExamined         |      | DICOM tag 0018,0015 | D          |
+| BodyPart                 |      | DICOM tag 0018,0015 | B          |
 | PatientPosition          |      | DICOM tag 0020,0032 | D          |
 | ProcedureStepDescription |      | DICOM tag 0040,0254 | D          |
 | SoftwareVersions         |      | DICOM tag 0020,1020 | B          |
+| StudyDescription         |      | DICOM tag 0008,1030 | D          |
 | SeriesDescription        |      | DICOM tag 0008,103E | D          |
 | ProtocolName             |      | DICOM tag 0018,1030 | D          |
 | ScanningSequence         |      | DICOM tag 0018,0020 | B          |
@@ -107,6 +108,9 @@ These fields contain personally identifiable information. By default dcm2niix wi
 | PatientID              |      | DICOM tag 0010,0020 | D          |
 | AccessionNumber        |      | DICOM tag 0008,0050 | D          |
 | PatientBirthDate       |      | DICOM tag 0010,0030 | D          |
+| PatientSex             |      | DICOM tag 0010,0040 | D          |
+| PatientAge             |      | DICOM tag 0010,1010 | D          |
+| PatientSize            |      | DICOM tag 0010,1020 | D          |
 | PatientWeight          | kg   | DICOM tag 0010,1030 | D          |
 | AcquisitionDateTime    |      | DICOM tag 0008,002A | D          |
 
@@ -181,23 +185,31 @@ PET fields extracted from [DICOM tags](http://dicom.nema.org/medical/dicom/curre
 
 The term ECAT in the comments suggests that values are defined by the [ECAT7](http://www.turkupetcentre.net/petanalysis/format_image_ecat.html) format. Therefore, these fields will not be populated for DICOM data.
 
-| Field                        | Unit | Comments                    | Defined By |
-|------------------------------|------|-----------------------------|------------|
-| Radiopharmaceutical          |      | DICOM tag 0018,0031 or ECAT | D          |
-| RadionuclidePositronFraction | f    | DICOM tag 0018,1076         | D          |
-| RadionuclideTotalDose        | MBq  | DICOM tag 0018,1074         | D          |
-| RadionuclideHalfLife         | s    | DICOM tag 0018,1075         | D          |
-| DoseCalibrationFactor        |      | DICOM tag 0054,1322         | D          |
-| IsotopeHalfLife              |      | ECAT                        | D          |
-| Dosage                       |      | ECAT                        | D          |
-| ConvolutionKernel            |      | DICOM tag 0018,1210         | D          |
-| Units                        |      | DICOM tag 0054,1001         | D          |
-| DecayCorrection              |      | DICOM tag 0054,1102         | D          |
-| AttenuationCorrectionMethod  |      | DICOM tag 0054,1101         | D          |
-| ReconstructionMethod         |      | DICOM tag 0054,1103         | D          |
-| DecayFactor                  |      | DICOM tag 0054,1321         | D          |
-| FrameTimesStart              | s    | DICOM tags 0008,0022        | D          |
-| FrameDuration                | s    | DICOM tag 0018,1242         | D          |
+| Field                        | Unit | Comments                         | Defined By |
+|------------------------------|------|----------------------------------|------------|
+| IsotopeHalfLife              |      | ECAT                             | D          |
+| Dosage                       |      | ECAT                             | D          |
+| FrameTimesStart              | s    | DICOM tag 0008,0022              | B          |
+| TracerRadionuclide           |      | DICOM tag 0008,0100 or 0008,0104 | B          |
+| Radiopharmaceutical          |      | DICOM tag 0018,0031 or ECAT      | D          |
+| InjectedRadioactivity        | MBq  | DICOM tag 0018,1074              | B          |
+| RadionuclideHalfLife         | s    | DICOM tag 0018,1075              | D          |
+| RadionuclidePositronFraction | f    | DICOM tag 0018,1076              | D          |
+| ConvolutionKernel            |      | DICOM tag 0018,1210              | D          |
+| Units                        |      | DICOM tag 0054,1001              | B          |
+| AttenuationCorrectionMethod  |      | DICOM tag 0054,1101              | B          |
+| DecayCorrection              |      | DICOM tag 0054,1102              | D          |
+| ReconstructionMethod         |      | DICOM tag 0054,1103              | B          |
+| DecayCorrectionFactor        |      | DICOM tag 0054,1321              | B          |
+| DoseCalibrationFactor        |      | DICOM tag 0054,1322              | B          |
+| ScatterFraction              |      | DICOM tag 0054,1323              | B          |
+| FrameDuration                | s    | DICOM tag 0018,1242              | B          |
+
+n.b. ConvolutionKernel (0018,1210) can be parsed to BIDS `ReconFilterType` and `ReconFilterSize`. However, manufacturer variations (Siemens: `XYZGAUSSIAN3.00` GE `Rad: \ rectangle \  4.000000 mm  \ Ax: \ rectangle \  8.500000 mm` require complex logic).
+
+n.b. ReconstructionMethod (0054,1103) can be parsed to ReconMethodName, ReconMethodParameterLabels, ReconMethodParameterUnits and ReconMethodParameterValues. However, this requires maniufacturer specific logic (e.g. Siemens `OP-OSEM4i21s`, GE `3D Kinahan - Rogers`
+
+For Philips scanners, [Source Isotope Name](https://dicom.innolitics.com/ciods/rt-brachy-treatment-record/rt-brachy-session-record/30080100/300a0226) may be a good source for TracerRadionuclide
 
 ## Manufacturer Fields
 
@@ -232,8 +244,18 @@ Data unique to [GE](https://github.com/rordenlab/dcm2niix/tree/master/GE). Deter
 | ASLLabelingTechnique           |      | DICOM tag 0043,10A4      | D          |
 | LabelingDuration               | s    | DICOM tag 0043,10A5      | B          |
 | SliceTiming                    | s    | [see notes](https://github.com/rordenlab/dcm2niix/tree/master/GE#slice-timing)  | B          |
-| CompressedSensingFactor        |      | DICOM tag 0043,10b7      | D          |
-| DeepLearningFactor             |      | DICOM tag 0043,10ca      | D          |
+| CompressedSensingFactor        |      | DICOM tag 0043,10B7      | D          |
+| TablePosition                  | mm   | The 3rd value of DICOM tag 0043,10B2 - the value of DICOM tag 0019,107F    | B          |
+| DeepLearningFactor             |      | DICOM tag 0043,10CA      | D          |
+
+### Manufacturer GE (Positron Emission Tomography)
+
+[GE Private Tags](https://www.gehealthcare.com/-/jssmedia/b86f641ae0bd4a7b919c79215e5c01e7)
+
+| Field                              | Unit | Comments              | Defined By |
+|------------------------------------|------|-----------------------|------------|
+| InjectedVolume                     |      | DICOM tag 0009,103A   | B          |
+| ReconFilterSize                    |      | DICOM tag 0009,108F   | B          |
 
 ### Manufacturer Philips
 
@@ -246,11 +268,12 @@ Data unique to Philips, including [custom intensity scaling](https://www.ncbi.nl
 | PhilipsRWVIntercept                |      | DICOM tag 0040,9224              | D          |
 | PhilipsRescaleSlope                |      | DICOM tag 0028,1053              | D          |
 | PhilipsRescaleIntercept            |      | DICOM tag 0028,1052              | D          |
-| PhilipsScaleSlope                  |      | DICOM tag 2005,100E              | D          |
 | UsePhilipsFloatNotDisplayScaling   |      | dcm2niix option `-p y` or `-p n` | D          |
 | PartialFourierEnabled              |      | DICOM tag 0018,9081, `YES`       | D          |
 | PhaseEncodingStepsNoPartialFourier |      | DICOM tag 0018,9231              | D          |
 | WaterFatShift                      |      | DICOM tag 2001,1022              | D          |
+| PhilipsScaleSlope                  |      | DICOM tag 2005,100E              | D          |
+| TablePosition                      | mm   | DICOM tag 2005,143C              | B          |
 
 ### Manufacturer Siemens (Arterial Spin Labeling)
 
@@ -320,6 +343,7 @@ Fields specific to Siemens V*-series (e.g. VB, VE) MRI systems (e.g. Verio, Trio
 | ConsistencyInfo                |                                                 | The more complete software version, e.g. VE11C or VE11E instead of just VE11.                                                                                                                                                                                                                                                                                                                          | D          |
 | CoilCombinationMethod          |                                                 | Detects `Sum of Squares` and `Adaptive Combine`                                                                                                                                                                                                                                                                                                                                                        | B          |
 | MatrixCoilMode                 |                                                 | Detects `SENSE` and `GRAPPA`                                                                                                                                                                                                                                                                                                                                                                           | B          |
+| TablePosition                  | mm                                              | DICOM tag 0019,1014                                                                                                                                                                                                                                                                                                                                                                                    | B          |
 | DwellTime                      |                                                 | DICOM tag 0019,1018                                                                                                                                                                                                                                                                                                                                                                                    | B          |
 | BandwidthPerPixelPhaseEncode   | Hz                                              | DICOM tag 0019,1028                                                                                                                                                                                                                                                                                                                                                                                    | D          |
 | ImageOrientationText           |                                                 | DICOM tag 0051,100E                                                                                                                                                                                                                                                                                                                                                                                    | D          |
@@ -335,9 +359,10 @@ Fields specific to [Siemens XA-series](https://github.com/rordenlab/dcm2niix/tre
 | BandwidthPerPixelPhaseEncode | Hz   | DICOM tag 0021,1153        | D          |
 | ScanningSequence             |      | DICOM tag 0021,105a        | D          |
 | PostLabelingDelay            | s    | DICOM tag 0018,9258        | B          |
+| TablePosition                | mm   | DICOM tag 0021,1005        | B          |
 | NonlinearGradientCorrection  | b    | 0008,0008 or 0021,1175     | B          |
 | PhaseEncodingDirection       |      | polarity from 0021,111c    | B          |
-| SpoilingState                |      | 0021,105B                  | B          |
+| SpoilingState                |      | DICOM tag 0021,105B        | B          |
 
 Siemens also includes some sequence information in the private MRPhoenixProtocol (0021,1019) tag. You can view this with [gdcmdump](https://gdcm.sourceforge.net/html/gdcmdump.html), e.g. `gdcmdump --mrprotocol img.dcm`. Fields that dcm2niix inspects include `sPat.lAccelFact3D `, `sPat.lAccelFactPE`, `sPat.lRefLinesPE` and `sPat.ucPATMode`. The behavior of dcm2niix will be more well documented as our understanding of this tag improves.
 

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 2.8.12)
+cmake_minimum_required(VERSION 3.5)
 
 if(COMMAND CMAKE_POLICY)
     CMAKE_POLICY(SET CMP0003 NEW)

CONTRIBUTE.md

@@ -6,7 +6,7 @@ Like the [Brain Imaging Data Structure](https://bids.neuroimaging.io/get_involve
 
 The easiest way to contribute to dcm2niix is to ask questions you have by [generating Github issues](https://github.com/rordenlab/dcm2niix/issues) or [asking a question on the NITRC forum](https://www.nitrc.org/forum/?group_id=880). 
 
-The code is open source, and you can share your improvements by [creating a pull request](https://github.com/rordenlab/dcm2niix/pulls).
+The code is open source, and you can share your improvements by [creating a pull request](https://github.com/rordenlab/dcm2niix/pulls) to the **development** branch. Please note that the **master** branch is always the current stable release and does not accept pull requests.
 dcm2niix is a community project that has benefitted from many [contributors](https://github.com/rordenlab/dcm2niix/graphs/contributors). 
 
 The INCF suggests indicating who is responsible for maintaining software for [stability and support](https://incf.org/incf-standards-review-criteria-v20). Therefore, below we indicate several active contributors and their primary domain of expertise. However, this list is not comprehensive, and it is noted that the project has been supported by contributions from many users. This list does not reflect magnitude of prior contributions, rather it is a non-exhaustive list of members who are actively maintaining the project.

FILENAMING.md

@@ -63,7 +63,7 @@ DICOM images can have up to [16](https://www.medicalconnections.co.uk/kb/Number-
 
 ## File Name Conflicts
 
-dcm2niix will attempt to write your image using the naming scheme you specify with the '-f' parameter. However, if an image already exists with the specified output name, dcm2niix will append a letter (e.g. 'a') to the end of a file name to avoid overwriting existing images. Consider a situation where dcm2niix is run with '-f %t'. This will name images based on the study time. If a single study has multiple series (for example, a T1 sequence and a fMRI scan, the reulting file names will conflict with each other. In order to avoid overwriting images, dcm2niix will resort to adding the post fix 'a', 'b', etc. There are a few solutions to avoiding these situations. You may want to consider using both of these:
+dcm2niix will attempt to write your image using the naming scheme you specify with the '-f' parameter. However, if an image already exists with the specified output name, dcm2niix will append a letter (e.g. 'a') to the end of a file name to avoid overwriting existing images. Consider a situation where dcm2niix is run with '-f %t'. This will name images based on the study time. If a single study has multiple series (for example, a T1 sequence and a fMRI scan, the resulting file names will conflict with each other. In order to avoid overwriting images, dcm2niix will resort to adding the post fix 'a', 'b', etc. There are a few solutions to avoiding these situations. You may want to consider using both of these:
  - Make sure you specify a naming scheme that can discriminate between your images. For example '-f %t' will not disambiguate different series acquired in the same session. However, '-f %t_%s' will discriminate between series.
  - Localizer (scout) images are the first scans acquired for any scanning session, and are used to plan the location for subsequent images. Localizers are not used in subsequent analyses (due to resolution, artefacts, etc). Localizers are often acquired with three orthogonal image planes (sagittal, coronal and axial). The NIfTI format requires that all slices in a volume are co-planar, so these localizers will generate naming conflicts. The solution is to use '-i y' which will ignore (not convert) localizers (it will also ignore derived images and 2D slices). This command helps exclude images that are not required for subsequent analyses.
  - Be aware that if you run dcm2niix twice with the same parameters on the same data, you will encounter file naming conflicts.