dicom 0.6.1 → 0.7

data/CHANGELOG

@@ -1,3 +1,35 @@
+= 0.7
+
+=== 28th February, 2010
+
+* Added set_image() and set_image_narray() methods to write pixel data to the DICOM object, complementing set_image_magick().
+* Added method get_image() which retrieves pixel data to a standard Ruby Array.
+* Added a method for removing all private data elements in the DICOM object.
+* Anonymizer class has gained the ability to remove all private data elements when anonymizing.
+* Fixed an issue where Anonymizer failed to anonymize tags which had multiple instances in a DICOM file.
+* Fixed an issue where Anonymizer failed to honor an expception folder if it ended with a file separation character.
+* Private data elements can now be added to a DICOM object.
+* Created a new FileHandler class where the user can customize the way incoming DICOM files are handled in DServer.
+* Methods set_image_narray() and set_image_magick() takes options :min and :max to rescale pixel values.
+* The magick and narray image retrieval methods now takes the option :rescale to convert pixel values to presentation values.
+* Method get_pos() now takes the option :parent to narrow a search down.
+* Improved the set_value() method to handle the creation of data elements inside sequences/items.
+* All DObject methods who return Data Element positions now return an empty array instead of false if no matches are found.
+* Improved handling of private tags in the library.
+* Network transmissions with implicit encoding are now handled properly.
+* Improved the handling of associations in the networking code.
+* Some minor formatting improvements to the print() method.
+* Improve the logic of updating group/sequence/item lengths to handle changes to Data Elements in sequence hierarchies.
+* DLibrary class is permanently loaded when the gem is loaded and no longer needs to be specified by the user.
+* Method get_image_magick() now handles pixel representation and window leveling.
+* Program files was moved to a sub-directory and a module version string added, in accordance with gem guidelines.
+* Renamed DObject attribute :types to :vr in accordance with the terminology of the official DICOM standard.
+* Renamed method get_raw() to get_bin() and attribute :raw to :bin.
+* Renamed get_pos() option :array to :selection.
+* Updated Dictionary in accordance with the 2009 version of the official DICOM base standard.
+* Various "under the hood" improvements and code cleanups.
+
+
 = 0.6.1
 
 === 23rd August, 2009
@@ -36,8 +68,8 @@
   See documentation for details.
 * Several methods have been cleaned up, making execution in some cases somewhat snappier.
 * Several methods have been made more robust.
-* Added new keyword :partial to the get_pos() method, which will enable search for partial string matches.
-* Added new keyword :array to the get_value() and get_raw() methods which enables easy extraction of
+* Added new option :partial to the get_pos() method, which will enable search for partial string matches.
+* Added new option :array to the get_value() and get_raw() methods which enables easy extraction of
   multiple values of a given tag to an array (relevant for tags present at multiple places in a DICOM file).
 * Fixed a bug where exception folders where ignored in the Anonymizer class.
 
@@ -46,7 +78,7 @@
 
 === 3rd February, 2009
 
-* Change of syntax: Keywords are now supplied as hash.
+* Change of syntax: Options are now supplied as hash.
 * Method below() renamed to children().
 * Added method parents() which returns the position of all items/sequences that are the parent of
   the specified tag. This method is only relevant for DICOM tags that exist inside a hierarchy.
@@ -103,22 +135,12 @@ The library does have several known issues and lacks some features I would like
 offer basic functionality and should be usable for people interested in working with DICOM files in Ruby.
 The reading algorithm has been tested succesfully with some 40 different DICOM files, so it should be fairly robust.
 
-Features:
-* Reads DICOM files
-* Retrieve tags, formatted
-* Retrieve tags, unformatted
-* Retrieve image data as NArray object
-* Retrieve image data as RMagick object
-* Print file properties
-* Print tag information
-
 
 Known issues:
-* Network communication is highly experimental.
-* 12 bit image data not supported.
-* Color images not supported in NArray and RMagick retrieve methods.
-* Unpacking compressed image data has basic support but is not properly tested yet.
-* Reading Big Endian files has fairly good, but possibly not full, support.
-* Reading on a Big Endian system is not tested.
-* Reading of multiple frame image data to RMagick does not work in all cases.
-* Retrieving images when file contains two or more unrelated images may not be handled correctly.
+* The retrieve file network functionality (get_image() in DClient class) has not been tested.
+* Compressed pixel data is poorly handled.
+* Read/Write 12 bit image data not available.
+* Color image data is poorly handled.
+* Incomplete support for Big endian (Everything but signed short and signed long has been implemented).
+* Incomplete support for multiple frame image data to NArray and RMagick objects (partial support already featured).
+* Image handling does not take into consideration DICOM tags which specify orientation, samples per pixel and photometric interpretation.

data/DOCUMENTATION

@@ -1,8 +1,8 @@
-DICOM is a small and simple library for handling DICOM files (reading, editing
+Ruby DICOM is a small and simple library for handling DICOM files (reading, editing
 and writing) and DICOM network communication (both client and server side).
 It is written completely in Ruby and has no external dependencies.
 
-Copyright 2008-2009 Christoffer Lerv�g (chris.lervag [@nospam] @gmail.com)
+Copyright 2008-2010 Christoffer Lervåg (chris.lervag [@nospam] @gmail.com)
 
 INSTALLATION
 
@@ -12,20 +12,6 @@ gem install dicom
 
 DOCUMENTATION
 
-CLASS DLibrary
-
-PUBLIC CLASS METHODS
-
-  new()
-
-    Initialize a new Library (dictionary) object.
-    Useful if you want to make a script that reads hundreds or thousands of DICOM files,
-    because you can save time by loading the library one time at startup instead of
-    having the library being loaded for each DICOM file being read.
-    Example:
-      myLib = DICOM::DLibrary.new
-
-
 CLASS DObject
 
 PUBLIC CLASS METHODS
@@ -36,10 +22,10 @@ PUBLIC CLASS METHODS
     Example 1: (The simplest way)
       require 'dicom'
       obj = DICOM::DObject.new("myFile.dcm")
-    Example 2: (Using a pre-loaded library to speed up reading when reading multiple files)
-      obj = DICOM::DObject.new("myFile.dcm", :verbose => false, :lib => myLib)
-    Example 3: (Open an empty DICOM object)
-      obj = DICOM::DObject.new(nil)
+    Example 2: (Reading a DICOM file that has already been loaded into memory in a binary string)
+      obj = DICOM::DObject.new(bin_data, :bin => true, :syntax => syntax_string)
+    Example 3: (Open an empty DICOM object & choose non-verbose behaviour)
+      obj = DICOM::DObject.new(nil, :verbose => false)
 
 ACCESSORS (read only)
   :read_success
@@ -60,10 +46,10 @@ ACCESSORS (read only)
   As such, their length is equal to the number of tags in a DICOM object.
   :names
   :tags
-  :types
+  :vr
   :lengths
   :values
-  :raw
+  :bin
   :levels
 
 PUBLIC INSTANCE METHODS
@@ -78,26 +64,50 @@ PUBLIC INSTANCE METHODS
     Example 2: (Return all element positions that is contained only directly beneath the following sequence)
       pos = obj.children("3006,0082", :next_only => true)
 
+  get_bin(element, options={})
+    Returns the unprocessed, binary string of the requested DICOM data element.
+    Element may be an array index, element name or element tag.
+    If you wish to return multiple data values of a tag that occurs several times in the file,
+    use the keyword :array => true .
+    Example: (Returns all data values in a array)
+      contour_data = obj.get_bin("3006,0050", :array => true)
+
   get_frames
     Returns the number of frames present in the image data in the DICOM file.
 
-  get_image_magick
+  get_image(options={})
+    Returns a standard Ruby array with the pixel data, where the length of the array corresponds
+    with the number of pixels in the image.
+    Example 1: (Retrieve the pixel data)
+      pixels = obj.get_image
+    Example 2: (Retrieve the pixel data rescaled to presentation values according to window center/width settings)
+      pixels = obj.get_image(:rescale => true)
+    Example 3: (Retrieve the rescaled pixel data and using a numerical array in the rescaling process (~2 times faster))
+      pixels = obj.get_image(:rescale => true, :narray => true)
+
+  get_image_magick(options={})
     Returns an array of RMagick image objects, where the size of the array corresponds
     with the number of frames in the image data.
     To call this method the user needs to have loaded the RMagick bindings in advance (require 'RMagick').
-    Example (retrieve object and display first frame):
-    require 'RMagick'
-    data = dicom.get_image_magick()
-    data[0].display
-
-  get_image_narray
+    Example 1: (Retrieve object and display first frame)
+      require 'RMagick'
+      images = obj.get_image_magick
+      images[0].display
+    Example 2: (Retrieve image object rescaled to presentation values according to window center/width settings)
+      images = obj.get_image_magick(:rescale => true)
+    Example 3: (Retrieve rescaled image object and using a numerical array in the rescaling process (~2 times faster))
+      images = obj.get_image_magick(:rescale => true, :narray => true)
+
+  get_image_narray(options={})
     Returns a 3d NArray object where the array dimensions are related to [frames, columns, rows].
     To call this method the user needs to have loaded the NArray library in advance (require 'narray').
-    Example (retrieve object and display first frame):
+    Example 1: (Retrieve object and display first frame):
       require 'narray'
       require 'nimage'
-      data = obj.get_image_narray()
+      data = obj.get_image_narray
       NImage.show data[0,true,true]
+    Example 2: (Retrieve numerical array rescaled from the original pixel values to presentation values)
+      data = obj.get_image_narray(:rescale => true)
 
   get_image_pos
     Returns the index(es) of the data element(s) that contain image data.
@@ -108,22 +118,16 @@ PUBLIC INSTANCE METHODS
     Example 1: (Find all occurences of the specified tag in the object)
       pos = obj.get_pos("3006,0080")
     Example 2: (Find all occurences of the specified tag inside the specified sequence)
-      selection = obj.children("3006,0082")
-      pos = obj.get_pos("3006,0080", :array => selection)
-    Example 3: (Using the :partial argument to find position of all elements containing a specific string)
+      mySelection = obj.children("3006,0082")
+      pos = obj.get_pos("3006,0080", :selection => mySelection)
+    Example 3: (Same as above, but slightly more concise using the :parent option)
+      pos = obj.get_pos("3006,0080", :parent => "3006,0082")
+    Example 4: (Using the :partial argument to find position of all elements containing a specific string)
       pos = obj.get_pos("0010", :partial => true)
       pos = obj.get_pos("Name", :partial => true)
 
-  get_raw(element, options={})
-    Returns the raw data of the requested DICOM data element.
-    Element may be an array index, element name or element tag.
-    If you wish to return multiple data values of a tag that occurs several times in the file,
-    use the keyword :array => true .
-    Example: (Returns all data values in a array)
-      contour_data = obj.get_raw("3006,0050", :array => true)
-
   get_value(element)
-    Returns the value (processed raw data) of the requested DICOM data element.
+    Returns the value (processed binary data) of the requested DICOM data element.
     Element may be an array index, element name or element tag.
     If you wish to return multiple values of a tag that occurs several times in the file,
     use the keyword :array => true .
@@ -143,7 +147,7 @@ PUBLIC INSTANCE METHODS
 
   print(pos, options={})
     Prints the information gathered on one or several/all tag(s) in the DICOM object:
-      (index, [hierarchy level,] label, name, type, length, value)
+      (index, [hierarchy level,] label, name, vr, length, value)
     The method can print to both screen or to a text file. If print to file is chosen,
     the text file will be put in the folder of the original DICOM file with a '.txt' extension.
     The argument pos may be a number (array position), an array of numbers, or true.
@@ -153,15 +157,51 @@ PUBLIC INSTANCE METHODS
       obj.print([4,5,6])
 
   print_all
-    Prints information of all tags stored in the DICOM object to the screen.
+    Prints information of all tags stored in the DICOM object to the screen (This is equal to using print(true)).
 
   print_properties
     Prints the key structural properties of the DICOM file to the screen.
 
-  remove(element)
+  remove(element, options={})
     Removes the specified data element from the DICOM object. You can use this method
     if you are editing a DICOM object and wants to get rid of one or more elements.
     Element may be an array index, element name or element tag.
+    The default behaviour of this method is to remove any encapsulated elements if a sequence
+    or item is selected for removal. If for some reason you want to avoid this, user the :ignore_children option.
+    Example 1: (Remove a sequence tag along with all its 'children' tags)
+      obj.remove("Request Attributes Sequence")
+    Example 2: (Remove a specific sequence tag only (not recommended unless you really know what you are doing))
+      obj.remove("0040,0275", :ignore_children => true)
+
+  remove_private
+    Removes all private data elements from the DICOM object.
+
+  set_image(array)
+    Encodes and inserts the content of your array to the pixel data element of your DICOM object.
+    Note that this method does not create or update tags related to image information in the DICOM object.
+
+  set_image_file(file)
+    Inserts the binary content of a file to the Pixel Data tag in your DICOM object.
+    This can be useful if you have processed some image data using a custom program
+    and just wants to put that data back into a DICOM object.
+
+  set_image_magick(object, options={})
+    Encodes and inserts a RMagick image object to the pixel data element of your DICOM object.
+    Note that this method does not create or update tags related to image information in the DICOM object.
+    If pixel value rescaling is desired, this can be specified by using both the :min and :max options.
+    NB! Because of rescaling when importing pixel values to a RMagick object, and the possible
+    difference between presentation values and original pixel values, the use of set_image_magick() may
+    result in pixel data that is completely different from what is expected.
+    This method should be used only with great care: Do not be suprised if your resulting DICOM image looks strange!
+    Example: (Encode an image object and requesting a specific pixel value range to be encoded)
+      obj.set_image_magick(myImage, :min => -2000, :max => 3000)
+
+  set_image_narray(object, options={})
+    Encodes and inserts a NArray object to the pixel data element of your DICOM object.
+    Note that this method does not create or update tags related to image information in the DICOM object.
+    If pixel value rescaling is desired, this can be specified by using both the :min and :max options.
+    Example: (Encode a numerical pixel data array and requesting a specific pixel value range to be encoded)
+      obj.set_image_narray(myArray, :min => -2000, :max => 3000)
 
   set_value(value, element, options={})
     This method can be used both to edit an existing data element, or to create
@@ -171,14 +211,11 @@ PUBLIC INSTANCE METHODS
       obj.set_value("Anonymous", "0010,0010", :create => false)
     Example 2: (Insert binary data for a specific tag)
       obj.set_value(data, 52, :bin => true, :create => false)
-
-  set_image_magick(object)
-    Inserts a RMagick image object to the pixel data tag of your DICOM object.
-
-  set_image_file(file)
-    Inserts the binary content of a file to the Pixel Data tag in your DICOM object.
-    This can be useful if you have processed some image data using a custom program
-    and just wants to put that data back into a DICOM object.
+    Example 3: (Create a private data element)
+      obj.set_value("Test", "0011,0010", :vr => "LO")
+    Example 4: (Create/edit a data element in a specific item in a given sequence)
+      items = obj.get_pos("FFFE,E000", :parent => "0040,0275")
+      obj.set_value("CT1", "0040,0007", :parent => items.first)
 
   write(file)
     Writes the DICOM object to the specified file.
@@ -197,10 +234,10 @@ PUBLIC CLASS METHODS
 
 ACCESSORS (Read & write)
   :blank
-    A boolean that you can set if you want to all anonymization tags to be blank
+    A boolean that you can set as true if you want all anonymization tags to be blank
     instead of having some generic value.
   :enumeration
-    A boolean that if set will make the script set enumerated values on anonymized tags,
+    A boolean that if set as true will make the script set enumerated values on anonymized tags,
     such that you are able to separate the DICOM files of unique individuals after anonymization.
     Example of fictious result:
       "Joe Sixpack" => "Person1" and "Joe Schmoe" => "Person2"
@@ -209,7 +246,9 @@ ACCESSORS (Read & write)
     the anonymized DICOM files at a later stage. The relationship between original names and
     enumerated values is stored in a text file which you can keep for yourself, while handing out
     the anonymized DICOM files to a third party.
-
+  :remove_private
+    If this accessor is set as true, all private tags in the selected DICOM files will be removed.
+    This can be useful if you are unsure whether the private tags contain sensitive data or not.
   :write_path
     You may set a different path for where the anonymized DICOM files will be stored. If this
     value is not set, the Anonymizer script will overwrite the old DICOM files.
@@ -218,14 +257,14 @@ ACCESSORS (Read & write)
 
 PUBLIC INSTANCE METHODS
 
+  add_exception(path)
+    Adds a folder who's files (including all files in its subfolders) will be excluded from anonymization.
+
   add_folder(path)
     Adds a folder who's files (including all files in subfolders) will be anonymized.
     Example:
       a.add_folder("/home/dicom")
 
-  add_exception(path)
-    Adds a folder who's files (including all files in its subfolders) will be excluded from anonymization.
-
   add_tag(tag, options={})
     Adds a tag to the list of tags that will be anonymized. As options you can specify value to be used
     and whether the tag should be included for enumeration if this feature has been activated.
@@ -288,16 +327,6 @@ ACCESSORS (Read only)
 
 PUBLIC INSTANCE METHODS
 
-  get_image(path, options={})
-    Retrieve a DICOM image file from a server (C-GET-RQ) (this method is untested (might not work)).
-    Accepted options:
-      "0008,0018" (SOP Instance UID)
-      "0008,0052" (Query/Retrieve Level)
-      "0020,000D" (Study Instance UID)
-      "0020,000E" (Series Instance UID)
-    Example:
-      node.get_image("/home/dicom/", "0008,0018" => sop_uid, "0020,000D" => study_uid, "0020,000E" => series_uid)
-
   find_images(options={})
     Query a server for DICOM images that matches your specified criteria.
     Accepted options:
@@ -351,6 +380,16 @@ PUBLIC INSTANCE METHODS
     Example:
       result = node.find_studies("0008,0020" => study_date, "0010,000D" => patient_id)
 
+  get_image(path, options={})
+    Retrieve a DICOM image file from a server (C-GET-RQ) (this method is untested (might not work)).
+    Accepted options:
+      "0008,0018" (SOP Instance UID)
+      "0008,0052" (Query/Retrieve Level)
+      "0020,000D" (Study Instance UID)
+      "0020,000E" (Series Instance UID)
+    Example:
+      node.get_image("/home/dicom/", "0008,0018" => sop_uid, "0020,000D" => study_uid, "0020,000E" => series_uid)
+
   move_image(destination, options={})
     Move an image to a dicom node other than yourself.
     Accepted options:
@@ -385,10 +424,17 @@ PUBLIC CLASS METHODS
 
   new(port, options={})
     Initialize a new DServer instance.
-    Example:
+    Example 1:
       server = DICOM::DServer.new(104)
+    Example 2: (Initialize a DServer using a customized FileHandler placed in your local folder)
+      require 'MyFileHandler'
+      server = DICOM::DServer.new(104, :host_ae => "RUBY_SERVER", :file_handler => DICOM::MyFileHandler)
 
 ACCESSORS (Read & write)
+  :file_handler
+    You may write your own, customized FileHandler (the file that determines how incoming DICOM files are handled),
+    put it in your local execution environment, and hook it to your DServer instance by using this accessor.
+    This is quite a powerful option, as it will enable you to do practically whatever you want with incoming DICOM files.
   :host_ae
     Called application entity (name of the service class provider - server).
   :max_package_size

data/README

@@ -9,7 +9,7 @@ and Communications in Medicine) is a standard for handling, storing, printing,
 and transmitting information in medical imaging. It includes a file format definition
 and a network communications protocol. Ruby DICOM supports reading from, editing and
 writing to this file format. It also features experimental support for network
-communication modalities like query, move and send.
+communication modalities like query, move, sending and receiving files.
 
 BASIC USAGE
 -----------
@@ -47,7 +47,7 @@ dcm = DICOM::DObject.new("myFile.dcm") ;0
 COPYRIGHT
 ---------
 
-Copyright 2008-2009 Christoffer Lerv�g
+Copyright 2008-2010 Christoffer Lervåg
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -67,7 +67,7 @@ ABOUT ME
 --------
 
 Name:
-Christoffer Lerv�g
+Christoffer Lervåg
 
 Location:
 Oslo, Norway

data/lib/dicom.rb

@@ -1,14 +1,25 @@
 # Core library:
-require 'DClient'
-require 'Dictionary'
-require 'DLibrary'
-require 'DObject'
-require 'DRead'
-require 'DServer'
-require 'DWrite'
-require 'Link'
-require 'Stream'
+require 'dicom/DClient'
+require 'dicom/Dictionary'
+require 'dicom/DLibrary'
+require 'dicom/DObject'
+require 'dicom/DRead'
+require 'dicom/DServer'
+require 'dicom/DWrite'
+require 'dicom/FileHandler'
+require 'dicom/Link'
+require 'dicom/Stream'
 # Extended library:
-require 'Anonymizer'
-# Ruby library extensions:
-require 'ruby_extensions'
+require 'dicom/Anonymizer'
+# Extensions to the Ruby library:
+require 'dicom/ruby_extensions'
+
+# Ruby DICOM version string:
+DICOM::VERSION = "0.7"
+
+# Load the DICOM Library class (dictionary):
+DICOM::LIBRARY =  DICOM::DLibrary.new
+
+# Ruby DICOM implementation name and uid:
+DICOM::NAME = "RUBY_DICOM_" + DICOM::VERSION
+DICOM::UID = "1.2.826.0.1.3680043.8.641"