Difference between revisions of "Documentation/Nightly/Modules/DICOM"

From Slicer Wiki
Jump to: navigation, search
(Moved to readthedocs)
Tags: 2017 source edit, Replaced
Line 1: Line 1:
{{Clear|right}}{{TOC right}}
<!-- ---------------------------- -->
<!-- ---------------------------- -->
<!-- ---------------------------- -->
{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
| text = [https://slicer.readthedocs.io/en/latest/user_guide/modules/dicom.html This page has been moved to read-the-docs.]
| background-color = 8FBC8F }}
:'''Author(s)/Contributor(s):''' Steve Pieper (Isomics Inc.), Michael Onken (Offis), Marco Nolden (DFKZ), Julien Finet (Kitware), Stephen Aylward (Kitware), Nicholas Herlambang (AZE), Alireza Mehrtash (BWH), Csaba Pinter (PerkLab, Queen's)<br>
: '''Acknowledgements:''' This work is part of the [http://www.na-mic.org/ National Alliance for Medical Image Computing] (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149, and by Quantitative Image Informatics for Cancer Research (QIICR) (U24 CA180918) <br>
: '''Contact:''' Steve Pieper, <email>pieper@bwh.harvard.edu</email><br>
<!-- ---------------------------- -->
{{documentation/{{documentation/version}}/module-section|Module Description}}
DICOM is a widely used and sophisticated set of standards for digital radiology (see the [[#References|References]] section for more information). Slicer provides support for a subset of DICOM functionality, with the particular features driven by the needs of clinical research: '''loading''' and '''saving''' data sets from/to disk in DICOM format and '''sending''' and '''receiving''' data sets via DICOM networking.
<!-- ---------------------------- -->
{{documentation/{{documentation/version}}/module-section|Use Cases}}
===Data import and loading===
Since DICOM files are often located in several folders, they can cross-reference each other, and can be often interpreted in different ways, importing and loading of DICOM files are performed as two separate steps:
- Import: User selects a folder that contains DICOM files. Slicer reads header of all files in a folder (and all its subfolders) and stores essential information in the Slicer DICOM database. Optionally Slicer can also make a full copy of the files into the database, which is useful if files are stored on a removable media (CD, DVD, USB drive). All indexed data gets listed in the DICOM browser.
- Loading: Items that user selected in the DICOM browser are loaded into the scene and displayed in viewers. In advanced mode, loading is performed in two steps: the application examines selected items and offers a list of loadable items that the user can choose from.
====Data import====
*Make sure that all required Slicer extensions are installed. Slicer core contains DICOM import plugin for importing images, but additional extensions may be needed for other information objects. For example, ''SlicerRT extension is needed for importing RT structure set as segmentation''.
*Select folders that contain DICOM files
**Option A: Drag-and-drop the folder that contains DICOM files to the Slicer application window. Slicer displays a popup, asking what to do - click OK ("Load directory in DICOM database"). After import is completed, go to DICOM module.
**Option B: Go to DICOM module. Click "Import" button in the top-left corner of the DICOM browser. Select folder that contains DICOM files.
Optionally select the Copy option so that the files are copied into the database directory.  Otherwise they will only be referenced in their original location. It is recommended to copy data if importing files from removable media (CD/DVD/USB drives) to be able to load the data set even after media is ejected.
====Data loading====
*Go to DICOM module. Click "Show DICOM browser" if the browser window is not visible (window title: "DICOM Browser"; it shows a list of patients, studies, and series).
*Select items to load. If an item in the patient or study list is selected then by default all series that belong to that item will be loaded.
*Click "Load" button to load selected items.
*Go to Data module to see what has been loaded and show/hide them.
Advanced data loading: It is often possible to interpret DICOM data in different ways. If the application loaded data differently than expected then check "Advanced" checkbox, click "Examine" button, select all loadables in the list in the box at the bottom, and click "Load".
Some extensions make Slicer recognize more DICOM information object types. For example, SlicerRT extension makes it possible to load/export radiation therapy information objects (RT structure set, RT dose, RT image, RT plan). Make sure all relevant extensions are installed before attempting to load your data set.
====Deleting imported data====
By right clicking on a Patient, Study, or Series, you can delete the entry from the DICOM database.  Note that to avoid accidental data loss, Slicer does not delete the corresponding image data files.
===DICOM export===
Data in the scene can be exported to the DICOM database:
*Make sure that all required Slicer extensions are installed. Slicer core contains DICOM export plugin for exporting images, but additional extensions may be needed for other information objects. For example, ''SlicerRT extension is needed for exporting segmentation as RT structure set''.
*Prepare DICOM study to export in Data module (subject hierarchy tab). Make sure you have the nodes in the study that you want to export.
**If you need to create a new patient, then right-click the empty space and choose Create new subject. Studies can be created under patients the same way.
*Right-click on a data set to export it to DICOM format (export can also be initiated from DICOM browser).
*Select the export modality in the bottom left of the export dialog.
*Edit tags for exportables. The metadata from the select study will be automatically filled in to the Export dialog and you can select a Slicer volume to export.
*Exported files are added to the DICOM database
''Note that you should exercise extreme caution when working with these files in clinical situations, since non-standard or incorrect DICOM files can interfere with clinical operations.''
You can also choose to encapsulate the current MRML scene (via an MRB file) inside a DICOM dataset, which will be treated as a DICOM secondary capture document. This secondary capture information stores all details of the scene but only 3D Slicer can interpret the data. This export feature has not been widely tested and should be considered experimental.
===Data networking===
DICOM is also a network communication standard. Slicer supports a DICOM Listener, DICOM Query/Retrieve interface, and a DICOM Send option.  Note that in order to use these features, you must coordinate with the operators of the other DICOM nodes with which you wish to communicate. For example, you must work out agreement on such topics as network ports and application entity titles (AE Titles).  Be aware that not all equipment supports all networking options, so configuration may be challenging and is often difficult to troubleshoot.
====Connection Ports====
Port 104 is the standard DICOM port. All ports below 1024 require root access on unix-like systems (Linux and Mac).  So you can run Slicer with the sudo command to be able to open the port for the DICOM Listener.  Or you can use a different port, like 11112.  You need to configure that on both sides of the connection.  You can only have one process at a time listening on a port so if you have a listener running the second one won't start up.  Also if something adverse happens (a crash) the port may be kept open an you need to either kill the storescp helper process (or just reboot the computer) to free the port.  Consult the [[documentation/{{documentation/version}}/SlicerApplication/ErrorLog|Error Log]] for diagnostic information.
<!-- ---------------------------- -->
|[[image:DICOM Screenshot-1 1204-11-17-10-36.png|thumb|380px|DICOM module in use]]
|[[Image:Form_224.png|thumb|380px|DICOM Query dialog]]
|[[Image:DICOM Horizontal View 2014-11-17-09-35.png|thumb|380px|Horizontal table view]]
|[[Image:DICOM-3 2014-11-17-10-42.png‎|thumb|380px|DICOM Browser in Advanced Mode (Control plugins and access to load options)]]
|[[Image:DICOM4 2014-11-17-09-38.png|thumb|380px|DICOM Meta Data Browser (DICOM header viewer)]]
|[[Image:DICOM-5 2014-11-17-10-46.png|thumb|380px|More options (change local database directory and table display density)]]
|[[Image:20141103_DICOM_Export_Dialog.png|thumb|380px|DICOM Export Dialog]]
|[[Image:DICOM-Preferences.png|thumb|380px|DICOM Preferences]]
<!-- Tutorials ---------------------------- -->
*See [http://www.na-mic.org/Wiki/index.php/RSNA_2012#3D_Interactive_Visualization_of_DICOM_images the RSNA 2012 Training on Visualization] for description and sample data (Direct link to [http://www.na-mic.org/Wiki/images/6/66/3DVisualizationDICOM_RadiologyApplications_SoniaPujol_RSNA2012.pdf slides as pdf]).
*[https://pieper.github.io/content/handson/#/DICOM This screen capture animation] shows how to import and load DICOM data (also includes inspection of the file contents, which is an optional step).
<!-- Panels ---------------------------- -->
==DICOM import==
Referring to the "DICOM in use" image in the top left of this page, the most important controls for day-to-day use are highlighted with gray callouts.  The are described here in the order you are likely to use them.
Basic options:
*'''Import DICOM files''' all DICOM files in the selected folder (including subfolders) will be parsed and basic information from file headers will be stored in Slicer's DICOM database. If enabled, then Slicer will make a copy of the imported files into the database folder.
*'''Show DICOM database''' toggle between DICOM browser and viewers (slice view, 3D view, etc.)
*'''Patient list''' shows patients in the database. Studies available for the selected patient(s) are listed in study list. Multiple patients can be selected.
*'''Study list''': shows studies for the currently selected patient(s).  Multiple studies can be selected.
*'''Series list''' shows list of series (images, structure sets, segmentations, registration objects, etc.) available for selected studies.
*'''Load''' click this to load currently selected loadables into slicer.
*'''Loaded data''' shows all currently loaded content, which can be displayed in viewers by clicking the eye icon
Additional options:
* '''Search boxes''': each patient/study/series can be filtered by typing in these fields.
* '''View DICOM metadata''' (right-click in patient/study/series list): view metadata stored in file headers of selected series
* '''Delete''' (right-click in patient/study/series list): delete the selected item from the database. If the data set was copied into the DICOM database then the DICOM files are deleted, too.
* '''Export to file system''' (right-click in patient/study/series list): export selected items in the DICOM database to DICOM files
* '''Send to DICOM server''' (right-click in patient/study/series list): push selected items sets to a DICOM C-store SCP server
Advanced loading (allows loading DICOM data sets using non-default options):
* '''Advanced''' '''checkbox''' Enables advanced loading options
* '''Plugin options''': you can choose which plugins will be allowed to examine the selected series for loading.
*'''Examine button''' Runs each of the DICOM Plugins on the currently selected series and offers the result in the Load Options table.
*'''Loadables list''' displays all possible interpretations of the selected series by the selected plugins.  The plugin that most likely interprets the series correctly, is selected by default.  You can override the defaults if you want to load the data in a different way. There will not always be a one-to-one mapping of selected series to list of loadable items.
DICOM module settings:
* DICOM networking: download data from remote server using query retrieve, set up receiving data via C-store SCP
* DICOM database settings: allows you to select a location on disk for Slicer's database of DICOM files. The application manages content of this folder (stores metadata and copy of imported DICOM files): do not manually copy any data into this folder.
==DICOM export==
===How to export data from the Slicer scene to DICOM files===
*Open Data module, go to Subject Hierarchy tab (it is the tab shown by default)
*Make sure the data nodes that you want to export are in a DICOM-compliant hierarchy: parent of the data node is a Study, parent of the study is a Subject. To create a hierarchy, right-click in an empty area of the tree, select "Create new subject", then right-click on the newly created subject and select "Create child study", then drag-and-drop your data nodes under this study.
*Right-click on the data node to be exported and click "Export to DICOM..." to display DICOM export window (you can also show it by clicking "Export" button in the toolbar of DICOM browser module)
*Choose Output folder: By default, files are written into the folder where Slicer DICOM database is located.
*Click Export button: Export may take a few minutes. In case of error, the message is displayed in red on the left side of the dialog in the line of the "Save tags on export" checkbox.
This workflow is also explained in a 2-minute [https://youtu.be/nzWf4xHy1BM video tutorial]
===Advanced options===
*DICOM export window can be also opened from the DICOM browser, by clicking "Export" button in the toolbar
*Export mode:
**Export series: export one or more selected series, to be viewed on a standard DICOM-compliant viewer
**Export entire scene: save the entire Slicer scene into a DICOM secondary capture file; the content can be stored on a DICOM archival system but can only be edited in Slicer
*Export type: Once the user selected a node, the DICOM plugins generate exportables for the series they can export. The list of the results appear in this section, grouped by plugin. The confidence number will be the average of the confidence numbers for the individual series for that plugin.
*Editing DICOM tags:
**DICOM tag editor consists of a list of tables. Tables for the common tags for the patient and study on the top, and the tags for the individual series below them (see image about tag editor below)
**"Tags" in the displayed table are not written directly to DICOM tags, they are just used by the DICOM plugins to fill DICOM tags in the exported files. This allows much more flexibility and DICOM plugins can auto-populate some information and plugins can expose other export options in this list (e.g. compression, naming convention).
**Save tags to scene: Checkbox to allow saving the tags back to the MRML nodes as attributes.
*Import exported data: if checked, the exported files are added to Slicer's DICOM database.
*The Edit->Preferences->DICOM page can be used to select options
***Load referenced series will give you the option of easily loading, for example, the master volume of a segmentation when you open the segmentation.  This can also be made to happen automatically.
**Scalar Volume
***You can choose what back-end library to use (currently GDCM, DCMTK, or GDCM with DCMTK fallback with the last option being the default.  This is provided in case some data is unsupported by one library or the other.
***Acquisition geometry regularization option supports the creation of a nonlinear transform that corrects for things like missing slices or gantry tilt in the acquisition.  See [https://github.com/Slicer/Slicer/commit/b7650af3c27f34fc894bfdd587f2a4c02ba62a8b this commit message for more information]
***Autoloading subseries by time is an option break up some 4D acquisitions into individual volume, but is optional since some volumes are also acquired in time unites and should not be split.
=Slicer DICOM Database=
To organize the data and avoid redundant calculations, Slicer keeps a DICOM Database of information about the DICOM data.  You can have multiple databases on your computer at a time, and switch between them if, for example, they include data from different research projects.  Each database is simply a directory on your local disk that has a few [http://sqlite.org/ SQLite] files and subdirectories to store image data.  Don't manually modify the contents of these directories.  DICOM data can enter the database either through manual import or via a DICOM network transfer.  Modules may also populate the DICOM database with the results of computation.
You can change location where the database is stored by opening the DICOM module, clicking the double arrow (>>) button on the right side of the menu bar, click the button next to "LocalDatabase" label, and select the new location (an empty folder).
Note that the DICOM standard does not specify how files will be organized on disk, so if you have DICOM data from a CDROM or otherwise transferred from a scanner, you cannot in general tell anything about the contents from the file or directory names.  However once the data is imported to the database, it will be organized according the the DICOM standard Patient/Study/Series hierarchy.
=DICOM Loading/Saving and Plugins=
A main function of the DICOM module is to map from ''acquisition'' data organization into ''volume'' representation.  That is, DICOM files typically describe attributes of the image capture, like the sequence of locations of the table during CT acquisition, while Slicer operates on image volumes of regularly spaced pixels.  If, for example, the speed of the table motion is not consistent during an acquisition (which can be the case for some contrast 'bolus chasing' scans, Slicer's DICOM module will warn the user that the acquisition geometry is not consistent and the user should use caution when interpreting analysis results such as measurements.
From a developer perspective, the DICOM module exposes a plug-in architecture that allows acquisition-specific and modality-specific interpretation of DICOM data.  From a user perspective this means that often Slicer will be able to suggest multiple ways of interpreting the data (such as reading DICOM files as a [[Documentation/{{documentation/version}}#Diffusion|Diffusion]] dataset or as a scalar volume.  When it is computable by examining the files, the DICOM module will select the most likely interpretation option by default.  As of this release, standard plugins include scalar volumes and diffusion volumes, while extensions are available for segmentation objects, RT data, and PET/CT data.  More plugins are expected for future versions.  It is a long-term objective to be able to represent most, if not all, of Slicer's data in the corresponding DICOM data objects as the standard evolves to support them.
See the [[Documentation/{{documentation/version}}/FAQ/DICOM|Slicer DICOM FAQ]] for troubleshooting tips.
==How to obtain DICOM metadata==
*Open DICOM browser
*Right-click on the data set that you want to inspect
*Choose "View DICOM metadata"
*Click Copy Metadata button
*Paste the copied text to any text editor
*'''Remove patient name, birthdate, ID, and all other patient identifiable information'''
*Copy-paste remaining text to Slicer forum post or email
<!-- Similar modules ---------------------------- -->
{{documentation/{{documentation/version}}/module-section|Similar modules}}
*[[Documentation/{{documentation/version}}/SlicerApplication/LoadingData|Loading Data]] Can read scalar volume DICOM data, bypassing the database.
*[[Documentation/{{documentation/version}}/Extensions/Reporting|Reporting Extension]] reads and writes DICOM Segmentation Objects (label maps).
*[[Documentation/{{documentation/version}}/Extensions/Reporting|SlicerRT]] reads and write DICOM Radiation Therapy Objects and provides tools for processing them.
*[[Documentation/{{documentation/version}}/Extensions/Reporting|LongitudinalPETCT]] reads all PET/CT studies for a selected patient and provides tools for tracking metabolic activity detected by PET tracers.
<!-- References ---------------------------- -->
See the [http://commontk.org CTK web site] for more information on the internals of the DICOM implementation.  This tool uses the [http://dicom.offis.de DCMTK DICOM library].
===Useful links===
*The DICOM Homepage: http://dicom.nema.org/
*DICOM on wikipedia: http://en.wikipedia.org/wiki/DICOM
*Clean and simple DICOM tag browser: http://dicom.innolitics.com
*A useful tag lookup site: http://dicomlookup.com/
*A hyperlinked version of the standard: http://dabsoft.ch/dicom/
*A handy book about DICOM: http://www.amazon.com/Digital-Imaging-Communications-Medicine-DICOM/dp/3642108490/ref=dp_ob_title_bk
<!-- ---------------------------- -->
{{documentation/{{documentation/version}}/module-section|Information for Developers}}
[[Image:DICOM-architecture.png|thumb|580px|DICOM module architecture.]]
The overall DICOM Implementation in 3D Slicer consists of two main bodies of code embedded within the application.  [http://commontk.org CTK] code is responsible for the implementation of the DICOM database and networking layer.  The CTK code is implemented C++ and follows the Qt style.  The DICOM Module exposes this functionality to slicer users, and provides hooks through which other module can register DICOM Plugins to handle the conversion of specific DICOM data objects into the corresponding MRML representation.  Once the data is in slicer, it can be operated on via the standard slicer mechanisms.
====Customize table columns in DICOM browser====
Columns in the browser can be renamed, reordered, shown/hidden, etc. An example snippet to customize the browser can be found in the [https://www.slicer.org/wiki/Documentation/Nightly/ScriptRepository#Customize_table_columns_in_DICOM_browser script repository]
The changes made like this are written into the database (ColumnDisplayProperties table), so the column customizations can be done only once per database.
====Customize DICOM browser table content====
The way the raw DICOM tags are represented in the fields of the DICOM tables is determined by the displayed field generator rules. These rules are subclasses of the [https://github.com/commontk/CTK/blob/9c2af28e84da1abb986036317d75009d4c149923/master/Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorAbstractRule.h ctkDICOMDisplayedFieldGeneratorAbstractRule class], and need to be [https://github.com/commontk/CTK/blob/9c2af28e84da1abb986036317d75009d4c149923/master/Libs/DICOM/Core/ctkDICOMDisplayedFieldGenerator.h#L70 registered] to the displayed field generator in order to take part of the generation.
The fields are [https://github.com/commontk/CTK/9c2af28e84da1abb986036317d75009d4c149923/blob/master/Libs/DICOM/Core/ctkDICOMDatabase.h#L207 updated] when 1) files are added to the database or 2) the database schema is updated (happens when opening an older database with a newer Slicer). In the [https://github.com/commontk/CTK/tree/9c2af28e84da1abb986036317d75009d4c149923 current] version only those files (i.e. instances) are processed for which the displayed fields have never been generated.
When updating the displayed fields, every rule defines the fields it is responsible for using the cached DICOM tags in the database. Tags can be requested to be cached in the rules from the [https://github.com/commontk/CTK/blob/9c2af28e84da1abb986036317d75009d4c149923/Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorAbstractRule.h#L63 getRequiredDICOMTags] function. New field values are generated by the rules instance by instance. First, the getDisplayedFieldsForInstance function is called for each rule in which the custom values are generated from the raw tags, then the results are merged by calling mergeDisplayedFieldsForInstance for all the rules. Each field can be requested to be merged with "expect same value", which uses the only non-empty value and throws a warning if conflicting values are encountered, or with "concatenate", which simply concatenates the displayed field values together.
The existing two rules can be used as examples: the [https://github.com/commontk/CTK/blob/9c2af28e84da1abb986036317d75009d4c149923/Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorDefaultRule.cpp default] and the [https://github.com/commontk/CTK/blob/9c2af28e84da1abb986036317d75009d4c149923/Libs/DICOM/Core/ctkDICOMDisplayedFieldGeneratorRadiotherapySeriesDescriptionRule.cpp RT] rules.
<!-- ---------------------------- -->
<!-- ---------------------------- -->

Latest revision as of 19:02, 2 November 2020

Home < Documentation < Nightly < Modules < DICOM

For the stable Slicer documentation, visit the 4.10 page.

This page has been moved to read-the-docs.