Dicom Functions
===============

dicomanon
---------

 -- dicomanon(FILE_IN,: FILE_OUT)
 -- dicomanon(___,: NAME, VALUE)

     Anonymize a DICOM format file by removing or replacing specific fields.

Inputs
......

FILE_IN is filename to read from.

FILE_OUT is the filename to write to.

NAME, VALUE optional name/value properties.

Known property names are:

keep
     The value is a cell array of names to not remove during the anonymize procedure.

update
     A structure of name/values to update rather than remove.

Outputs
.......

None

dicomread, dicomwrite, dicominfo

dicomdict
---------

 -- DICTIONARY_NAME =: dicomdict ("get")
 -- dicomdict: ("factory")
 -- dicomdict: ("set", DICTIONARY_NAME)

     Get or set the active dicom data dictionary.

     The first usage returns the filename of the dictionary that is currently being used. Using "factory" resets the dictionary to the default. Using "set" allows setting the dictionary for future operations. In this case, the dictionary file DICTIONARY_NAME can be anywhere in the path.

Inputs
......

CODE -  string value of 'get', 'set' or 'factory'.

DICTIONARY_NAME' - name of dictionary file to use

Outputs
.......

DICTIONARY_NAME' - name of dictionary file currently set for dictionaty

Examples
........

Get current dicom dict path:

     > f = dicomdict('get')
     f = octavedicom.dic

Set a new dictionary:

     > dicomdict('set', 'anewdictfile.txt')

dicomread, dicomwrite

dicomdisp
---------

 -- dicomdisp: (FILENAME)
 -- dicomdisp: (FILENAME, [PROPERTYNAME, PROPERTVALUE ...])
     Read and display the metadata from a DICOM file.

Inputs
......

FILENAME - dicomfilename to display.

PROPERTYNAME, PROPERTVALUE - property pairs for options to the display function.

Currently the only known property is 'dictionary' to specify a non default dict to use.

Outputs
.......

None

dicomread, dicominfo

dicomfind
---------

 -- ATTRINFO: = dicomfind(FILENAME, ATTRIBUTE)
 -- ATTRINFO: = dicomfind(INFO, ATTRIBUTE)
     Find the location and value of an attribute in a dicom file or info structure.

Inputs
......

FILENAME - filename to open.

INFO - dicominfo struct.

ATTRIBUTE - attribute name to find.

Outputs
.......

ATTRINFO - a table with fields Location and Value for each matched attribute.

The Location value will be the attribute position in dot notation to show its position in dicom info structure.

Examples
........

      filename = file_in_loadpath("imdata/rtstruct.dcm");

      info = dicomfind(filename, "ROINumber");

dicominfo
---------

 -- INFO: = dicominfo (FILENAME)
 -- INFO: = dicominfo (FILENAME, "dictionary", DICTIONARY-NAME)
 -- dicominfo: (___, OPTIONS)
     Get all metadata from a DICOM file, excluding any actual image. INFO is a nested struct containing the data.

     If the dictionary argument is used, the given DICTIONARY-NAME is used for this operation, otherwise, the dictionary set by dicomdict is used.

Inputs
......

FILENAME - name of file to read.

'DICTIONARY' - string constant of 'dictionary'.

DICTIONARY-NAME - filename of dictionary to use.

OPTIONS - a string in format of 'optionname=value', or property/value pair 'optionname', value: truncate=n where n is the number of characters to limit the dump output display to n for each value.

Outputs
.......

INFO - struct of fields read frome the dicom file.

Examples
........

Read the metadata of a dicomfile:

     > info = dicominfo(file_in_loadpath('imdata/simple-test.dcm')
     info =
     scalar structure containing the fields:
     Filename = a.dcm
     FileModDate = 04-Feb-2017 02:08:31
     FileMetaInformationVersion =
     0  1
     MediaStorageSOPClassUID = 1.2.840.10008.5.1.4.1.1.7
     MediaStorageSOPInstanceUID = 1.2.826.0.1.3680043.2.1143.4379544382488839209812957878553810312
     TransferSyntaxUID = 1.2.840.10008.1.2
     ImplementationClassUID = 1.2.826.0.1.3680043.2.1143.107.104.103.115.2.6.3
     ImplementationVersionName = GDCM 2.6.3
     SourceApplicationEntityTitle = GDCM
     ImageType = DERIVED \\SECONDARY
     SOPClassUID = 1.2.840.10008.5.1.4.1.1.7
     SOPInstanceUID = 1.2.826.0.1.3680043.2.1143.4379544382488839209812957878553810312
     StudyDate = 20170203
     StudyTime = 210831.360586
     Modality = OT
     ConversionType = WSD
     NominalScannedPixelSpacing =
     1
     1
     StudyInstanceUID = 1.2.826.0.1.3680043.2.1143.1282184104726305239898701219563360204
     SeriesInstanceUID = 1.2.826.0.1.3680043.2.1143.9385265081744858155080799316976198629
     SamplesPerPixel = 1
     PhotometricInterpretation = MONOCHROME1
     Rows = 10
     Columns = 5
     BitsAllocated = 8
     BitsStored = 8
     HighBit = 7
     PixelRepresentation = 0
     RescaleIntercept = 0
     RescaleSlope =  1
     RescaleType = US
     PixelData = not assigned

dicomread, dicomdict

dicomlookup
-----------

 -- KEYWORD: = dicomlookup (GROUP, ELEMENT)
 -- [GROUP,: ELEMENT] = dicomlookup (KEYWORD)

     Lookup an attribute in the DICOM data dictionary.

     KEYWORD = dicomlookup (GROUP, ELEMENT) will look in the current dicom dictionary for a specified GROUP and ELEMENT tag and returns string name of the attribute.

     [GROUP, ELEMENT] = dicomlookup (KEYWORD) will look in the current dicom dictionary for a specified KEYWORD string and returns the GROUP and ELEMENT for keyword.

Inputs
......

KEYWORD - string keyword name to look up a group, element value.

GROUP - group value to look up (string or integer).

ELEMENT - element value to look up (string or integer).

Outputs
.......

KEYWORD - string keyword name to looked up from a group, element value.

GROUP, ELEMENT - group and element value looked up from keyword.

Outputs
.......

Look up tag name for 0x10 0x10:

     > name = dicomlookup(0x10,0x10)
     name = PatientName

Look up tag group and element value:

     > [grp, elm] = dicomlookup('TransferSyntaxUID')
     grp = 2
     elm = 16

dicomdict

dicomread
---------

 -- IMAGE: = dicomread (FILENAME)
 -- IMAGE: = dicomread (STRUCTURE)

     Load the image from a DICOM file.

Inputs
......

FILENAME - a string giving the filename.*

STRUCTURE - a structure with a field Filename (such as returned by dicominfo).

IMAGE - may be two or three dimensional, depending on the content of the file.

Outputs
.......

IMAGE - An integer or float matrix will be returned, the number of bits will depend on the file.

Examples
........

Load the image data of a dcm file:

     > image = dicomread(file_in_loadpath('imdata/simple-test.dcm'))
     image =
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0
     0  0  0  0  0

dicominfo

dicomuid
--------

 -- UUID: = dicomuid ()

     Generate a DICOM unique id .

Inputs
......

None

Outputs
.......

UUID is a unique id string.

Examples
........

Get a new uid:

     > uid = dicomuid ()
     uid = 1.2.826.0.1.3680043.2.1143.3114589836670200378351641061429967573

dicomupdate
-----------

 -- INFO =: dicomupdate(FILEINFO, ATTRIBUTE, VALUE)
 -- INFO =: dicomupdate(INFO, ATTRINFO)
     Update a dicom struct with new values

Inputs
......

INFO - dicominfo struct.

ATTRIBUTE - attribute name to find and change value of.

VALUE - attribute value to set.

ATTRINFO - a table with fields Location and Value for each matched attribute to change.

Outputs
.......

INFO - dicominfo struct.

Examples
........

      filename = file_in_loadpath("imdata/rtstruct.dcm");
      info = dicominfo(filename);

      % update specific values
      finfo = dicomfind(info, "ROINumber");
      finfo.Value{1} = 10;
      info = dicomupdate(info, finfo);

      % update all matching
      info = dicomupdate(info, "ROINumber", 100);

dicomwrite
----------

 -- dicomwrite(IM,: FILENAME)
 -- dicomwrite(IM,: FILENAME, INFO)

     Write a DICOM format file to FILENAME.

Inputs
......

IM - image data or empty matrix, [], if only metadata save is required

FILENAME - filename to write dicom to. if [], then function runs in verbose trial mode.

INFO - struct, like that produced by dicominfo

Examples
........

Create a dicom file using default info, and the supplied data:

     > wdata = uint8 (10*rand (10,10));
     > dicomwrite (wdata, 'test.dcm');

Create a dicom file using data and meta info:

     > wdata = dicomread(file_in_loadpath('imdata/CT-MONO2-16-ankle.dcm');
     > info = dicominfo(file_in_loadpath('imdata/CT-MONO2-16-ankle.dcm');
     > dicomwrite(wdata, info);

dicomread, dicominfo

images.dicom.decodeUID
----------------------

 -- UIDINFO: = images.dicom.decodeUID(UID)
     Look up information about a uid string

Inputs
......

UID - dicom uid string.

Outputs
.......

UIDINFO - a structure with fields of Value, Name and Type.

Additional fields may be present in the case of a Transfer Syntax type uid.

Examples
........

      > info = images.dicom.decodeUID("1.2.840.10008.1.1");
      info =
       scalar structure containing the fields:
         Value = 1.2.840.10008.1.1
         Name = Verification SOP Class
         Type = SOP Class

images.dicom.parseDICOMDIR
--------------------------

 -- INFO: = images.dicom.parseDICOMDIR(FILENAME)
     Parse a DICOMDIR file and return the information as a struct.

Inputs
......

FILENAME - filename to open.

Outputs
.......

INFO - A struct containing the directory information from a DICOMDIR file

Th info structure will be an array of Patients, with an array of Studies with an array of Series with an array of Images.

Each element will contain a Payload field.

Examples
........

      filename = file_in_loadpath("imdata/DICOMDIR");

      info = images.dicom.parseDICOMDIR(filename);

isdicom
-------

 -- YESNO =: isdicom (FILENAME)
     Return true if FILENAME is a valid DICOM file.

Inputs
......

FILENAME - name of file to read.

Outputs
.......

YESNO - logical value of true if filename is a dicom file.

dicomdict, dicominfo, dicomread, dicomwrite