# spectrIm NIfTI / DICOM conversion — first version

## What this version does

The GUI contains two tabs.

### NIfTI to DICOM

1. Select a folder containing `.nii` or `.nii.gz` files.
2. The program lists the files and lets the user select any subset.
3. Each selected NIfTI file is converted with `NiftiToDicomConverter`.
4. The generated DICOM instances are written below the selected output folder.
5. By default, all selected NIfTI files share one synthetic DICOM Study Instance UID and appear as separate series in the spectrIm Study → Series → Instance tree.
6. Each NIfTI file keeps its own Frame of Reference UID because study membership alone does not prove that two NIfTI volumes share one spatial frame.
7. A four-dimensional NIfTI file creates one DICOM series per volume.
8. The last selected NIfTI source and DICOM output folders are stored in the spectrIm-QMRS global settings. When a NIfTI source folder is selected, the DICOM output folder is suggested as a sibling folder close to the source path.

### DICOM to NIfTI

1. Select a directory containing DICOM files.
2. The Java scanner reads metadata only and stops before Pixel Data.
3. Files are grouped by Study Instance UID and Series Instance UID.
4. The user selects one or more series.
5. Each selected series is staged separately and passed to `dcm2niix` or the older `dcm2nii` executable.
6. Output is organised into one folder per DICOM study and normally one NIfTI file per selected series.
7. JSON sidecars and gzip compression can be selected in the GUI.
8. The last selected DICOM source folder, NIfTI output folder and converter executable are stored in the spectrIm-QMRS global settings. When a DICOM source folder is selected, the NIfTI output folder is suggested as a sibling folder close to the source path.

`dcm2niix` is strongly preferred. The older `dcm2nii` path is retained only because spectrIm already has a `RegistrationSettings.getDicom2niiInstallPath()` setting.

## NIfTI and multiple DICOM series

NIfTI does not contain a DICOM-style Patient → Study → Series → Instance hierarchy. A NIfTI file represents one n-dimensional image dataset, commonly one 3-D volume or one 4-D set of related volumes.

Therefore:

- one DICOM study with six image series normally becomes six NIfTI files;
- the study relationship is preserved by the output directory structure and optionally by JSON sidecars;
- unrelated DICOM series must not be combined into one 4-D NIfTI merely because they belong to the same study;
- one DICOM Series Instance UID can occasionally produce more than one NIfTI file when the DICOM content contains incompatible echoes, orientations, acquisitions or other subdivisions. That split is safer than forcing them into an invalid single grid.

## Source files

Copy these files into:

```text
src/mbsq/spectrim/io/nifti/
```

- `NiftiToDicomConverter.java`
- `DicomToNiftiSeriesConverter.java`
- `NiftiDicomConversionDialog.java`

The included `NiftiToDicomConverter` is the converter supplied earlier, with two additions:

- optional externally supplied `studyInstanceUid` and `frameOfReferenceUid`;
- public `createDicomUid()` for grouping several conversions into one synthetic study.

It still uses dcm4che 2.x (`org.dcm4che2`) and is intended for the existing spectrIm dependency set.

## Menu integration

In the action handler for the menu item, use:

```java
private void handleNiftiDicomConversionRequest() {
    NiftiDicomConversionDialog.showFor(this);
}
```

This assumes the containing class is a `Window`, such as `JFrame`.

Otherwise use:

```java
private void handleNiftiDicomConversionRequest() {
    Window owner = SwingUtilities.getWindowAncestor(this);
    NiftiDicomConversionDialog.showFor(owner);
}
```

Required imports:

```java
import java.awt.Window;
import javax.swing.SwingUtilities;
import mbsq.spectrim.io.nifti.NiftiDicomConversionDialog;
```

The menu text should be:

```text
NIfTI / DICOM conversion ...
```

## External converter path

The dialog initially reads:

```java
bin/nifty/dcm2niix_win
```

This is a relative path to the bundled Windows `dcm2niix` folder. When the
application is started from the `dist` directory, the GUI resolves this relative
path by searching from the current working directory and the jar/code-source
location.

The user can override the path in the conversion window. The path selected in
the conversion window is saved in `GlobalSettings`, so the next converter
session starts with the most recently used executable or executable folder.

For current installations, point this setting to `dcm2niix.exe` on Windows or `dcm2niix` on Linux. The GUI detects `dcm2niix` from the executable filename and uses its command-line syntax.

## Output behaviour

### NIfTI to DICOM

The selected output directory receives one subdirectory per source NIfTI file. This prevents accidental overwriting and allows the existing DICOM directory parser to mount the common root.

When the NIfTI source folder is selected, the GUI suggests a DICOM output folder
next to it. The user can still override this manually, and the chosen path is
remembered for the next session.

The output objects are explicitly marked as derived/secondary and contain synthetic patient and study metadata where the NIfTI file does not provide clinical metadata.

### DICOM to NIfTI

Output is organised approximately as:

```text
output-root/
    study_20260715_description_uid/
        series_1_T1_uid/
            series_1_T1_uid.nii.gz
            series_1_T1_uid.json
        series_2_FLAIR_uid/
            series_2_FLAIR_uid.nii.gz
            series_2_FLAIR_uid.json
```

Temporary staging directories are removed after each conversion. Hard links are attempted first, then symbolic links, then file copies. Large series may temporarily require duplicated disk space when links are unavailable.

When the DICOM source folder is selected, the GUI suggests a NIfTI output folder
next to it. The user can still override this manually, and the chosen path is
remembered for the next session.

## First-version limitations

- DICOM to NIfTI is delegated to `dcm2niix`; reimplementing vendor-specific DICOM interpretation in Java would be inefficient and substantially less reliable.
- DICOM spectroscopy, structured reports, presentation states, segmentations and other non-image SOP classes may be listed but can fail conversion.
- A NIfTI file normally lacks the original DICOM patient, scanner, sequence, coil and acquisition metadata. NIfTI-to-DICOM output must not be treated as the original diagnostic scanner series.
- Converted DICOM should not be sent to PACS as an original acquisition.
- The GUI currently processes selected files and series sequentially. This is deliberate for a first version and avoids multiple external converter processes competing for disk bandwidth.
- Cancellation while an external converter is running is not implemented yet.

## Validation performed

The three Java files were syntax-compiled together against a minimal dcm4che2-compatible API stub. Final compilation must still be performed against the exact dcm4che 2.0.29 jars and `RegistrationSettings` class in the spectrIm project.