Merge pull request #27 from tomaroberts/readme-update

Updates README
tomaroberts · Sep 1, 2023 · 09d20e0 · 09d20e0
2 parents b03b4aa + 3fb79e0
commit 09d20e0
Showing 1 changed file with 85 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -26,8 +26,8 @@
 <!-- Overview -->
 ## Overview
 
-[DICOM](https://www.dicomstandard.org/) is the international standard used to store and display medical images in 
-clinical institutions. It is a vast and complicated standard. The 
+[DICOM](https://www.dicomstandard.org/) is the international standard used to store, transfer and display medical images 
+in clinical institutions. It is a vast and complicated standard. The 
 [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/) file format is widely used within medical imaging 
 research because it is a comparatively simple data format, generally stripped of identifiable patient data and with far 
 fewer metadata fields.
@@ -38,38 +38,51 @@ Researchers often convert DICOM files to NIfTI files using tools such as
 **nii2dcm** is designed to convert a NIfTI file (.nii/.nii.gz) into a single-frame DICOM Series in one line, e.g.:
 
 ```sh
-nii2dcm nifti-file.nii.gz dicom-output-directory
+nii2dcm nifti-file.nii.gz dicom-output-directory/ --dicom-type MR
 ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
-<!-- GETTING STARTED -->
-## Getting Started
+<!-- Installation -->
+## Installation
 
-To install and run nii2dcm locally follow these steps.
+To install and run nii2dcm locally, you have two options:
+- pip
+- build from source
 
-### Prerequisites
+### pip
 
-* Python (tested with v3.9)
+```shell
+pip install nii2dcm
+```
 
+### build from source
 
-### Installation
+Clone this repo:
+```sh
+git clone https://github.com/tomaroberts/nii2dcm.git
+```
 
-Setup a Python virtual environment (recommended)
-   ```sh
-   python -m venv nii2dcm-venv
-   source nii2dcm-venv/bin/activate
-   ```
-Install nii2dcm
-   ```sh
-   pip install nii2dcm
-   ```
+Setup a Python virtual environment (recommended):
+```sh
+cd nii2dcm/
+python -m venv nii2dcm-venv
+source nii2dcm-venv/bin/activate
+python -m pip install --upgrade pip
+```
+
+Install dependencies and nii2dcm:
+```sh
+pip install setuptools wheel
+pip install -r requirements.txt
+pip install .
+```
 
 Verify installation by displaying nii2dcm help information
-   ```sh
-   nii2dcm -h
-   ```
+```sh
+nii2dcm -h
+```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -78,34 +91,69 @@ Verify installation by displaying nii2dcm help information
 <!-- USAGE EXAMPLES -->
 ## Usage
 
-nii2dcm is designed to be pointed at a single `.nii` or `.nii.gz` and generate a single-frame DICOM dataset:
+nii2dcm is designed to be pointed at a single `.nii` or `.nii.gz` from which it generates a single-frame DICOM dataset. 
+
+It is **recommended** to specify the output DICOM modality using the `-d` or `--dicom-type` flag (see examples below). 
+Without this, a generic DICOM is created without complete imaging modality metadata.
 
+### DicomMRI
+Create an MRI 2D multi-slice DICOM dataset:
 ```sh
-nii2dcm nifti-file.nii.gz dicom-output-directory
+nii2dcm nifti-file.nii.gz dicom-output-directory/ -d MR
 ```
 
-Currently, nii2dcm provides three Python classes in order to build different DICOM types. These are:
-* **Dicom** – generic DICOM class
-* **DicomMRI** – MRI DICOM class
-* **DicomMRISVR** – 3D [SVR](https://svrtk.github.io/) MRI DICOM class
+### DicomMRISVR
+Create an MRI 3D [SVR](https://svrtk.github.io/) DICOM dataset:
+```sh
+nii2dcm SVR-output.nii.gz dicom-output-directory/ -d SVR
+```
 
-The created DICOM type can be specified with the `-d` or `--dicom-type` flag. For example, the following will output a 
-3D MRI SVR DICOM dataset
+### Dicom
+Create a generic DICOM dataset:
 ```sh
-nii2dcm SVR-output.nii.gz path/to/output/dir/ -d SVR
+nii2dcm nifti-file.nii.gz dicom-output-directory/
 ```
 
+### Other
+Eventually, nii2dcm will be extended to cover other imaging modalities including CT, Ultrasound, X-Ray, etc.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+<!-- REFERENCE DICOM -->
+## Reference DICOM metadata transferral
+
+There are often situations where it can be useful to transfer information from an existing DICOM Study into a new DICOM 
+Series. For example, if you want to store your new DICOM dataset alongside your original DICOM Study.
+
+The `-r` or `--ref-dicom` flag attempts to transfer common DICOM attributes from a reference DICOM file into the 
+output DICOM:
+
+```shell
+nii2dcm nifti-file.nii.gz dicom-output-directory/ -d MR -r reference-dicom-file.dcm
+```
+
+Currently, attributes to transfer are [listed here in the DicomMRI class](https://github.com/tomaroberts/nii2dcm/blob/b03b4aacce25eeb6a00756bdb47365034dced787/nii2dcm/dcm.py#L236).
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
 <!-- ROADMAP -->
 ## Roadmap
 
-This project is in its infancy! Expect bugs :bug::ant::beetle:
+This project is in its infancy! Expect bugs :bug: :ant: :beetle:
 
 There are many things I would like to test and implement. 
 [Raise an Issue](https://github.com/tomaroberts/nii2dcm/issues) if you have ideas or suggestions.
 
+#### Developer Note
+If you would like to create another class of DICOM within nii2dcm, you can use the base 
+[DicomMRI](https://github.com/tomaroberts/nii2dcm/blob/b03b4aacce25eeb6a00756bdb47365034dced787/nii2dcm/dcm.py#L201) 
+class or the [DicomMRISVR](https://github.com/tomaroberts/nii2dcm/blob/main/nii2dcm/svr.py) class for inspiration. You 
+will also need to extend the command line interface to utilise your class, i.e. `--dicom-type CT`.
+
+Please [raise an Issue](https://github.com/tomaroberts/nii2dcm/issues) if you need developer support.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
@@ -116,9 +164,14 @@ There are many things I would like to test and implement.
 * [Chris Rorden for dcm2niix](https://github.com/rordenlab/dcm2niix/) - inspiration for the reverse process
 * [NHS Topol Digital Fellowships scheme](https://topol.hee.nhs.uk/digital-fellowships/) - for the protected time to work 
 on this
+* [highdicom](https://github.com/ImagingDataCommons/highdicom) - beautiful and extensive Python library for various 
+tasks, including DICOM creation
+* [SimpleITK](https://simpleitk.org/) - comprehensive software including DICOM reading and writing
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
-<!-- Links -->
+<!-- LINKS -->
 ## Links
 Some useful, free image viewing software:
 * [ITK-Snap](http://www.itksnap.org/) - fast, simple interface. Opens NIfTI and DICOM