dicom 0.4 → 0.5

data/CHANGELOG

@@ -1,4 +1,24 @@
-=0.4
+= 0.5
+
+=== 4th May, 2009
+
+* Several small changes have been made to achieve compatibility with both Ruby versions 1.8 and 1.9.
+* Implemented a change in syntax for several methods with a goal of simplification.
+* Implemented a change in syntax for some methods, variables and messages in order
+  to better match the terminology used in the official DICOM documents.
+* Added a new attr_reader :errors, an array that holds any warnings issued during your
+  interaction with DObject.
+* DObject has received new attr_readers for the arrays holding information on the DICOM object.
+  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
+  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.
+
+
+= 0.4
 
 === 3rd February, 2009
 
@@ -22,6 +42,7 @@
 * Introducing the Anonymizer class, which takes advantage of the new write capability in Ruby DICOM
   to offer a fairly powerful and customizable tool for anonymizing your DICOM files.
 
+
 = 0.3
 
 === 12th October, 2008
@@ -48,28 +69,29 @@
 * DRead class is more resistant to breaking if it is handed a faulty file to read, and will return an error message instead of halting execution.
 * Added option to load DICOM object in verbose or silent mode.
 
-= 0.1
-
-=== 20th July, 2008
-
-First public release.
-The library does have several known issues and lacks some features I would like it to have, but it does 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:
-* 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 has basic, but 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.
+
+= 0.1
+
+=== 20th July, 2008
+
+First public release.
+The library does have several known issues and lacks some features I would like it to have, but it does 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:
+* 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.

data/DOCUMENTATION

@@ -1,7 +1,7 @@
 DICOM is a small library for reading, editing and writing DICOM files.
 It is written completely in Ruby and has no external dependencies.
 
-Copyright 2008-2009 Christoffer Lervåg (chris.lervag [@nospam] @gmail.com)
+Copyright 2008-2009 Christoffer Lerv�g (chris.lervag [@nospam] @gmail.com)
 
 INSTALLATION
 
@@ -40,11 +40,14 @@ PUBLIC CLASS METHODS
 		Example 3: (Open an empty DICOM object)
 			obj = DICOM::DObject.new(nil)
 
-ACCESSORS
+ACCESSORS (read only)
 	:read_success
 		A boolean that is true if DICOM object was read successfully, and false if not.
 	:write_success
 		A boolean that is true if DICOM object was written successfully, and false if not.
+	:errors
+		An array holding any error messages, warnings or notices that have been logged
+		during your interaction with DObject.
 	:modality
 		A string which holds the description of the modality of the DICOM object that has been read.
 		Example of use:
@@ -52,95 +55,121 @@ ACCESSORS
 			if obj.read_success
 			  puts obj.modality
 			end
+	The following accessors are the arrays that hold all the information gathered on the DICOM object.
+	As such, their length is equal to the number of tags in a DICOM object.
+	:names
+	:tags
+	:types
+	:lengths
+	:values
+	:raw
+	:levels
 
 PUBLIC INSTANCE METHODS
 
-	children(id, options={})
-		Returns the positions of all tags inside the hierarchy of a sequence or an item.
-		This is useful if you later want to get the position(s) of a certain tag,
+	children(element, options={})
+		Returns the positions of all data elements inside the hierarchy of a sequence or an item.
+		This is useful if you later want to get the position(s) of a certain element,
 		restricted to the positions inside the given sequence or item.
-		Example 1: (Return all tag positions that is contained in the following sequence)
+		Element may be an array index, element name or element tag.
+		Example 1: (Return all element positions that is contained in the following sequence)
 			pos = obj.children("3006,0082")
-		Example 2: (Return all tag positions that is contained only directly beneath the following sequence)
+		Example 2: (Return all element positions that is contained only directly beneath the following sequence)
 			pos = obj.children("3006,0082", :next_only => true)
 
-	get_frames()
+	get_frames
 		Returns the number of frames present in the image data in the DICOM file.
 
-	get_image_magick()
+	get_image_magick
 		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 performed " require 'RMagick' " in advance.
+		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 = dicom.get_image_magick()
 		data[0].display
 
-	get_image_narray()
+	get_image_narray
 		Returns a 3d NArray object where the array dimensions are related to [frames, columns, rows].
-		To call this method the user needs to have performed " require 'narray' " in advance.
+		To call this method the user needs to have loaded the NArray library in advance (require 'narray').
 		Example (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]
 
-	get_image_pos()
-		Returns the index(es) of the tag(s) that contain image data.
+	get_image_pos
+		Returns the index(es) of the data element(s) that contain image data.
 
-	get_pos(id, options={})
-		Returns the index(es) of the tag(s) in the DICOM file that match the supplied tag ID.
+	get_pos(string, options={})
+		Returns the index(es) of the data element(s) in the DICOM file that match
+		the supplied element tag or name.
 		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)
-
-	get_raw(id)
-		Returns the raw data of the DICOM tag that matches the supplied tag ID.
-		The ID may be a tag index, tag name or tag label.
-
-	get_value(id)
-		Returns the value (processed raw data) of the DICOM tag that matches the supplied tag ID.
-		The ID may be a tag index, tag name or tag label.
+		Example 3: (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.
+		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 .
+		Example: (Returns all data values in a array)
+			contour_data = obj.get_value("3006,0050", :array => true)
 
 	image_to_file(file)
 		Dumps the pixel data of the DICOM object directly to the specified file.
 		This is useful if you wish to extract this data to process it with another program.
 
-	parents(id)
+	parents(element)
 		Returns the positions of all parents of this tag in the hierarchy.
 		This is useful if you want to know the position of the items or sequence tags that 'hold' your tag.
+		Element may be an array index, element name or element tag.
 		Example:
 			pos = obj.parents("300C,0006")
 
-	print(id, options={})
-		Prints the information of one or many tag(s):
+	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)
 		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 ID may be a tag name, label or position, or it might be an array of positions.
+		The argument pos may be a number (array position), an array of numbers, or true.
 		Example 1: (Print all tags to file, with both tree visualization and level numbers)
 			obj.print(true, :levels => true, :tree => true, :file => true)
 		Example 2: (Print an array of tags to screen, no level or tree visualization)
 			obj.print([4,5,6])
 
-	print_all()
+	print_all
 		Prints information of all tags stored in the DICOM object to the screen.
 
-	print_properties()
+	print_properties
 		Prints the key structural properties of the DICOM file to the screen.
 
-	remove_tag(tag)
-		Removes the specified tag from the DICOM object. You can use this method
-		if you are editing a DICOM object and wants to get rid of some tags.
+	remove(element)
+		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.
 
-	set_value(value, options={})
-		This method can be used both to edit an existing tag, or to create new tags in your DICOM object.
+	set_value(value, element, options={})
+		This method can be used both to edit an existing data element, or to create
+		new data elements in your DICOM object.
+		Element may be an array index, element name or element tag.
 		Example 1: (Edit patient name)
-			obj.set_value("Anonymous", :label => "0010,0010", :create => false)
+			obj.set_value("Anonymous", "0010,0010", :create => false)
 		Example 2: (Insert binary data for a specific tag)
-			obj.set_value(data, :pos => 52, :bin => true, :create => false)
+			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.
@@ -150,10 +179,10 @@ PUBLIC INSTANCE METHODS
 		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.
 
-	write_file(file)
+	write(file)
 		Writes the DICOM object to the specified file.
 		Example:
-			obj.write_file(myPath + "test_file.dcm")
+			obj.write(myPath + "test_file.dcm")
 
 
 CLASS Anonymizer
@@ -165,7 +194,7 @@ PUBLIC CLASS METHODS
 		Example:
 			a = DICOM::Anonymizer.new
 
-ACCESSORS
+ACCESSORS (Read & write)
 	:blank
 		A boolean that you can set if you want to all anonymization tags to be blank
 		instead of having some generic value.
@@ -211,7 +240,7 @@ PUBLIC INSTANCE METHODS
 		Verbose (=true/false) will apply to the read/update/write process that takes place in DObject, and not
 		the messages of the Anonymization script itself.
 
-	print()
+	print
 		Prints the list of tags that have been selected for anonymization, along with the values
 		that the original tags will be replaced with. If enumeration is selected, this method will also
 		print which tags have been selected for enumeration.

data/README

@@ -4,42 +4,42 @@ RUBY DICOM
 SUMMARY
 --------
 
-This is a fairly basic library for reading DICOM files in Ruby. Digital Imaging and Communications in Medicine (DICOM) is a standard for handling, storing, printing, and transmitting information in medical imaging. It includes a file format definition and a network communications protocol. The library supports reading, editing and writing the file format.
+This is a fairly basic library for handling DICOM files in Ruby. Digital Imaging and Communications in Medicine (DICOM) 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.
 
 BASIC USAGE
 -----------
 
 require 'dicom'
 # Read file:
-dcm = DICOM::DObject.new("myFile.dcm")
-# Display some key information about the file:
+dcm = DICOM::DObject.new("myFile.dcm")
+# Display some key information about the file:
 dcm.print_properties()
 # Print all tags to screen:
 dcm.print(true)
-# Retrieve a tag value:
+# Retrieve a data element value:
 name = dcm.get_value("0010.0010")
 # Retrieve pixel data:
 pixels = dcm.get_value("7FE0.0010")
-# Load pixel data in a RMagick object and display on screen:
+# Load pixel data to a RMagick object and display it on screen:
 image = dcm.get_image_magick()
 image[0].display
-# Load pixel data in a NArray object and display on screen:
+# Load pixel data to a NArray object and display it on screen:
 image = dcm.get_image_narray()
-NImage.show image[0,true,true]
-
-Tip:
-When playing around with Ruby DICOM in irb, you may be annoyed
-with all the information that is printed to screen, regardless
-if you have specified verbose as false. This is because in irb
-every variable loaded in the program is automatically printed.
-A hack to avoid this effect is to append ";0" after a command.
-Example:
+NImage.show image[0,true,true]
+
+Tip:
+When playing around with Ruby DICOM in irb, you may be annoyed
+with all the information that is printed to screen, regardless
+if you have specified verbose as false. This is because in irb
+every variable loaded in the program is automatically printed.
+A hack to avoid this effect is to append ";0" after a command.
+Example:
 dcm = DICOM::DObject.new("myFile.dcm") ;0
-  
+
 COPYRIGHT
 ---------
 
-Copyright 2008-2009 Christoffer Lervåg
+Copyright 2008-2009 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
@@ -59,12 +59,12 @@ ABOUT ME
 --------
 
 Name:
-Christoffer Lervåg
+Christoffer Lerv�g
 
 Location:
 Oslo, Norway
 
 Email:
 chris.lervag [@nospam] @gmail.com
-Please don't hesitate to email me if have any thoughts on this project!
-
+Please don't hesitate to email me if have any thoughts on this project!
+

data/lib/Anonymizer.rb

@@ -1,13 +1,13 @@
-#    Copyright 2008-2009 Christoffer Lerv�g
+#    Copyright 2008-2009 Christoffer Lervag
 module DICOM
 
   # Class for anonymizing DICOM files:
   # A good resource on this topic (report from the DICOM standards committee, work group 18):
   # ftp://medical.nema.org/medical/dicom/Supps/sup142_03.pdf
   class Anonymizer
-    
+
     attr_accessor :blank, :enumeration, :identity_file, :verbose, :write_path
-    
+
     # Initialize the Anonymizer instance:
     def initialize(opts={})
       # Default verbosity is true: # NB: verbosity is not used currently
@@ -22,11 +22,11 @@ module DICOM
       # Array of folders to be processed for anonymization:
       @folders = Array.new
       @exceptions = Array.new
-      # Tags that will be anonymized:
+      # Data elements which will be anonymized (the array will hold a list of tag strings):
       @tags = Array.new
-      # Default values to use on anonymized tags:
+      # Default values to use on anonymized data elements:
       @values = Array.new
-      # Which tags will have enumeration applied, if requested by the user:
+      # Which data elements will have enumeration applied, if requested by the user:
       @enum = Array.new
       # We use a hash to store information from DICOM files if enumeration is desired:
       @enum_old_hash = {}
@@ -35,23 +35,23 @@ module DICOM
       @files = Array.new
       # Write paths will be determined later and put in this array:
       @write_paths = Array.new
-      # Set the default tags to be anonymized:
+      # Set the default data elements to be anonymized:
       set_defaults()
     end # of method initialize
-    
-    
+
+
     # Adds a folder who's files will be anonymized:
     def add_folder(path)
       @folders += [path] if path
     end
-   
-   
+
+
     # Adds an exception folder that is to be avoided when anonymizing:
     def add_exception(path)
       @exceptions += [path] if path
     end
-    
-    
+
+
     # Adds a tag to the list of tags that will be anonymized:
     def add_tag(tag, opts={})
       # Options and defaults:
@@ -60,7 +60,7 @@ module DICOM
       if tag
         if tag.is_a?(String)
           if tag.length == 9
-            # Add tag information:
+            # Add anonymization information for this tag:
             @tags += [tag]
             @values += [value]
             @enum += [enum]
@@ -74,8 +74,8 @@ module DICOM
         puts "Warning: No tag supplied. Nothing to add."
       end
     end # of method add_tag
-    
-    
+
+
     # Set enumeration status for a specific tag (toggle true/false)
     def change_enum(tag, enum)
       pos = @tags.index(tag)
@@ -89,8 +89,8 @@ module DICOM
         puts "Specified tag not found in anonymization array. No changes made."
       end
     end # of method change_enum
-    
-    
+
+
     # Changes the value used in anonymization for a specific tag:
     def change_value(tag, value)
       pos = @tags.index(tag)
@@ -104,8 +104,8 @@ module DICOM
         puts "Specified tag not found in anonymization array. No changes made."
       end
     end # of method change_value
-    
-    
+
+
     # Executes the anonymization process:
     def execute(verbose=false)
       # Search through the folders to gather all the files to be anonymized:
@@ -132,7 +132,7 @@ module DICOM
           # existing information associated with each tag:
           create_enum_hash() if @enumeration
           # Start the read/update/write process:
-          puts "Initiating read/update/write process..."
+          puts "Initiating read/update/write process (This may take some time)..."
           # Monitor whether every file read/write was successful:
           all_read = true
           all_write = true
@@ -158,10 +158,10 @@ module DICOM
                   value = @values[j]
                 end # of if @blank..else..
                 # Update DICOM object with new value:
-                obj.set_value(value, :create => false, :label => @tags[j])
+                obj.set_value(value, @tags[j], :create => false)
               end
               # Write DICOM file:
-              obj.write_file(@write_paths[i])
+              obj.write(@write_paths[i])
               all_write = false unless obj.write_success
             else
               all_read = false
@@ -195,15 +195,15 @@ module DICOM
       end
       puts "*******************************************************"
     end # of method execute
-    
-    
+
+
     # Prints a list of which tags are currently selected for anonymization along with
     # replacement values that will be used and enumeration status.
     def print()
       # Extract the string lengths which are needed to make the formatting nice:
       names = Array.new
       types = Array.new
-      label_lengths = Array.new
+      tag_lengths = Array.new
       name_lengths = Array.new
       type_lengths = Array.new
       value_lengths = Array.new
@@ -211,14 +211,14 @@ module DICOM
         arr = @lib.get_name_vr(@tags[i])
         names += [arr[0]]
         types += [arr[1]]
-        label_lengths[i] = @tags[i].length
+        tag_lengths[i] = @tags[i].length
         name_lengths[i] = names[i].length
         type_lengths[i] = types[i].length
         value_lengths[i] = @values[i].to_s.length unless @blank
         value_lengths[i] = "" if @blank
       end
       # To give the printed output a nice format we need to check the string lengths of some of these arrays:
-      label_maxL = label_lengths.max
+      tag_maxL = tag_lengths.max
       name_maxL = name_lengths.max
       type_maxL = type_lengths.max
       value_maxL = value_lengths.max
@@ -227,7 +227,7 @@ module DICOM
       @tags.each_index do |i|
         # Configure empty spaces:
         s = " "
-        f1 = " "*(label_maxL-@tags[i].length+1)
+        f1 = " "*(tag_maxL-@tags[i].length+1)
         f2 = " "*(name_maxL-names[i].length+1)
         f3 = " "*(type_maxL-types[i].length+1)
         f4 = " " if @blank
@@ -240,7 +240,7 @@ module DICOM
         if @blank
           value = ""
         else
-          value = @values [i]
+          value = @values[i]
         end
         tag = @tags[i]
         lines += [tag + f1 + names[i] + f2 + types[i] + f3 + value.to_s + f4 + enum.to_s ]
@@ -250,8 +250,8 @@ module DICOM
         puts line
       end
     end # of method print_tags
-    
-    
+
+
     # Removes a tag from the list of tags that will be anonymized:
     def remove_tag(tag)
       pos = @tags.index(tag)
@@ -263,12 +263,12 @@ module DICOM
         puts "Specified tag not found in anonymization array. No changes made."
       end
     end # of method remove_tag
-    
-    
+
+
     # The following methods are private:
     private
-    
-    
+
+
     # Finds the common path in an array of files, by performing a recursive search.
     # Returns the index of the last folder in str_arr that is common in all file paths.
     def common_path(str_arr, index)
@@ -288,8 +288,8 @@ module DICOM
       end
       return result
     end # of method common_path
-    
-    
+
+
     # Creates a hash that is used for storing information used when enumeration is desired.
     def create_enum_hash()
       @enum.each_index do |i|
@@ -297,8 +297,8 @@ module DICOM
         @enum_new_hash[@tags[i]] = Array.new
       end
     end
-    
-    
+
+
     # Handles enumeration for current DICOM tag:
     def get_enumeration_value(current, j)
       # Is enumeration requested for this tag?
@@ -324,8 +324,8 @@ module DICOM
       end # of if @enum[j]..else..
       return value
     end # of method handle_enumeration
-    
-    
+
+
     # Discover all the files contained in the specified directory and all its sub-directories:
     def load_files()
       # Load find library:
@@ -334,10 +334,14 @@ module DICOM
       for dir in @folders
         Find.find(dir) do |path|
           if FileTest.directory?(path)
-            if @exceptions.include?(File.basename(path))
-              Find.prune  # Don't look any further into this directory.
-            else
+            proceed = true
+            @exceptions.each do |e|
+              proceed = false if e == path
+            end
+            if proceed
               next
+            else
+              Find.prune  # Don't look any further into this directory.
             end
           else
             @files += [path]  # Store the file in our array
@@ -345,13 +349,14 @@ module DICOM
         end
       end # of for dir...
     end # of method load_files
-    
-    
+
+
     # Analyses the write_path and the 'read' file path to determine if the have some common root.
     # If there are parts of file that exist also in write path, it will not add those parts to write_path.
     def process_write_paths()
-      # First make sure @write_path ends with a "/" (represented by decimal 47):
-      @write_path = @write_path + "/" unless @write_path[@write_path.length-1] == 47
+      # First make sure @write_path ends with a "/":
+      last_character = @write_path[(@write_path.length-1)..(@write_path.length-1)]
+      @write_path = @write_path + "/" unless last_character == "/"
       # Separate behaviour if we have one, or several files in our array:
       if @files.length == 1
         # One file.
@@ -379,8 +384,8 @@ module DICOM
         end
       end # of if @files.length..
     end # of method process_write_paths
-    
-    
+
+
     # Default tags that will be anonymized, along with some settings for each:
     def set_defaults()
       data = [
@@ -403,14 +408,14 @@ module DICOM
       @values = data[1]
       @enum = data[2]
     end # of method set_defaults
-    
-    
+
+
     # Writes an identity file, which allows reidentification of DICOM files that have been anonymized
     # using the enumeration feature. Values will be saved in a text file, using semi colon delineation.
     def write_identity_file()
       # Open file and prepare to write text:
       File.open( @identity_file, 'w' ) do |output|
-        # Cycle through each 
+        # Cycle through each
         @tags.each_index do |i|
           if @enum[i]
             # This tag has had enumeration. Gather original and anonymized values:
@@ -427,7 +432,7 @@ module DICOM
         end # of @tags.each...
       end # of File.open...
     end # of method write...
-    
-    
+
+
   end # of class
 end # of module