dicom 0.9.3 → 0.9.4

data/lib/dicom/d_client.rb

@@ -3,11 +3,8 @@ module DICOM
 
   # This class contains code for handling the client side of DICOM TCP/IP network communication.
   #
-  # === Resources
-  #
-  # * For information regarding query, such as required/optional attributes and value matching, refer to the DICOM standard, PS3.4, C 2.2.
-  #--
-  # FIXME: The code which waits for incoming network packets seems to be very CPU intensive. Perhaps there is a more elegant way to wait for incoming messages?
+  # For more information regarding queries, such as required/optional attributes
+  # and value matching, refer to the DICOM standard, PS3.4, C 2.2.
   #
   class DClient
     include Logging
@@ -31,26 +28,17 @@ module DICOM
 
     # Creates a DClient instance.
     #
-    # === Notes
-    #
-    # * To customize logging behaviour, refer to the Logging module documentation.
-    #
-    # === Parameters
-    #
-    # * <tt>host_ip</tt> -- String. The IP adress of the server which you are going to communicate with.
-    # * <tt>port</tt> -- Fixnum. The network port to be used.
-    # * <tt>options</tt> -- A hash of parameters.
-    #
-    # === Options
+    # @note To customize logging behaviour, refer to the Logging module documentation.
     #
-    # * <tt>:ae</tt> -- String. The name of this client (application entity).
-    # * <tt>:host_ae</tt> -- String. The name of the server (application entity).
-    # * <tt>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes).
-    # * <tt>:timeout</tt> -- Fixnum. The maximum period the server will wait on an answer from a client before aborting the communication.
+    # @param [String] host_ip the IP adress of the server which you are going to communicate with
+    # @param [Integer] port the network port to be used
+    # @param [Hash] options the options to use for the network communication
+    # @option options [String] :ae the name of this client (application entity)
+    # @option options [String] :host_ae the name of the server (application entity)
+    # @option options [Integer] :max_package_size the maximum allowed size of network packages (in bytes)
+    # @option options [Integer] :timeout the number of seconds the client will wait on an answer from a server before aborting (defaults to 10)
     #
-    # === Examples
-    #
-    #   # Create a client instance using default settings:
+    # @example Create a client instance using default settings
     #   node = DICOM::DClient.new("10.1.25.200", 104)
     #
     def initialize(host_ip, port, options={})
@@ -78,7 +66,7 @@ module DICOM
       @link = Link.new(:ae => @ae, :host_ae => @host_ae, :max_package_size => @max_package_size, :timeout => @timeout)
     end
 
-    # Tests the connection to the server by performing a C-ECHO.
+    # Tests the connection to the server by performing a C-ECHO procedure.
     #
     def echo
       # Verification SOP Class:
@@ -88,24 +76,22 @@ module DICOM
 
     # Queries a service class provider for images (composite object instances) that match the specified criteria.
     #
-    # === Parameters
-    #
-    # * <tt>query_params</tt> -- A hash of query parameters.
+    # === Instance level attributes for this query:
     #
-    # === Options
+    # * '0008,0018' (SOP Instance UID)
+    # * '0020,0013' (Instance Number)
     #
-    # * <tt>"0008,0018"</tt> -- SOP Instance UID
-    # * <tt>"0020,0013"</tt> -- Instance Number
+    # In addition to the above listed attributes, a number of "optional" attributes
+    # may be specified. For a general list of optional object instance level attributes,
+    # please refer to the DICOM standard, PS3.4 C.6.1.1.5, Table C.6-4.
     #
-    # === Notes
+    # @note Caution: Calling this method without parameters will instruct your PACS
+    #   to return info on ALL images in the database!
+    # @param [Hash] query_params the query parameters to use
+    # @option query_params [String] 'GGGG,EEEE' a tag and value pair to be used in the query
     #
-    # * Caution: Calling this method without parameters will instruct your PACS to return info on ALL images in the database!
-    # * In addition to the above listed attributes, a number of "optional" attributes may be specified.
-    # * For a general list of optional object instance level attributes, refer to the DICOM standard, PS3.4 C.6.1.1.5, Table C.6-4.
-    #
-    # === Examples
-    #
-    #   node.find_images("0020,000D" => "1.2.840.1145.342", "0020,000E" => "1.3.6.1.4.1.2452.6.687844")
+    # @example Find all images belonging to a given study and series
+    #   node.find_images('0020,000D' => '1.2.840.1145.342', '0020,000E' => '1.3.6.1.4.1.2452.6.687844')
     #
     def find_images(query_params={})
       # Study Root Query/Retrieve Information Model - FIND:
@@ -128,27 +114,25 @@ module DICOM
 
     # Queries a service class provider for patients that match the specified criteria.
     #
-    # === Parameters
+    # === Instance level attributes for this query:
     #
-    # * <tt>query_params</tt> -- A hash of parameters.
+    # * '0008,0052' (Query/Retrieve Level)
+    # * '0010,0010' (Patient's Name)
+    # * '0010,0020' (Patient ID)
+    # * '0010,0030' (Patient's Birth Date)
+    # * '0010,0040' (Patient's Sex)
     #
-    # === Options
+    # In addition to the above listed attributes, a number of "optional" attributes
+    # may be specified. For a general list of optional object instance level attributes,
+    # please refer to the DICOM standard, PS3.4 C.6.1.1.2, Table C.6-1.
     #
-    # * <tt>"0008,0052"</tt> -- Query/Retrieve Level
-    # * <tt>"0010,0010"</tt> -- Patient's Name
-    # * <tt>"0010,0020"</tt> -- Patient ID
-    # * <tt>"0010,0030"</tt> -- Patient's Birth Date
-    # * <tt>"0010,0040"</tt> -- Patient's Sex
+    # @note Caution: Calling this method without parameters will instruct your PACS
+    #   to return info on ALL patients in the database!
+    # @param [Hash] query_params the query parameters to use
+    # @option query_params [String] 'GGGG,EEEE' a tag and value pair to be used in the query
     #
-    # === Notes
-    #
-    # * Caution: Calling this method without parameters will instruct your PACS to return info on ALL patients in the database!
-    # * In addition to the above listed attributes, a number of "optional" attributes may be specified.
-    # * For a general list of optional patient level attributes, refer to the DICOM standard, PS3.4 C.6.1.1.2, Table C.6-1.
-    #
-    # === Examples
-    #
-    #   node.find_patients("0010,0010" => "James*")
+    # @example Find all patients matching the given name
+    #   node.find_patients('0010,0010' => 'James*')
     #
     def find_patients(query_params={})
       # Patient Root Query/Retrieve Information Model - FIND:
@@ -172,25 +156,23 @@ module DICOM
 
     # Queries a service class provider for series that match the specified criteria.
     #
-    # === Parameters
-    #
-    # * <tt>query_params</tt> -- A hash of query parameters.
+    # === Instance level attributes for this query:
     #
-    # === Options
+    # * '0008,0060' (Modality)
+    # * '0020,000E' (Series Instance UID)
+    # * '0020,0011' (Series Number)
     #
-    # * <tt>"0008,0060"</tt> -- Modality
-    # * <tt>"0020,000E"</tt> -- Series Instance UID
-    # * <tt>"0020,0011"</tt> -- Series Number
+    # In addition to the above listed attributes, a number of "optional" attributes
+    # may be specified. For a general list of optional object instance level attributes,
+    # please refer to the DICOM standard, PS3.4 C.6.1.1.4, Table C.6-3.
     #
-    # === Notes
+    # @note Caution: Calling this method without parameters will instruct your PACS
+    #   to return info on ALL series in the database!
+    # @param [Hash] query_params the query parameters to use
+    # @option query_params [String] 'GGGG,EEEE' a tag and value pair to be used in the query
     #
-    # * Caution: Calling this method without parameters will instruct your PACS to return info on ALL series in the database!
-    # * In addition to the above listed attributes, a number of "optional" attributes may be specified.
-    # * For a general list of optional series level attributes, refer to the DICOM standard, PS3.4 C.6.1.1.4, Table C.6-3.
-    #
-    # === Examples
-    #
-    #   node.find_series("0020,000D" => "1.2.840.1145.342")
+    # @example Find all series belonging to the given study
+    #   node.find_series('0020,000D' => '1.2.840.1145.342')
     #
     def find_series(query_params={})
       # Study Root Query/Retrieve Information Model - FIND:
@@ -215,29 +197,27 @@ module DICOM
 
     # Queries a service class provider for studies that match the specified criteria.
     #
-    # === Parameters
-    #
-    # * <tt>query_params</tt> -- A hash of query parameters.
-    #
-    # === Options
-    #
-    # * <tt>"0008,0020"</tt> -- Study Date
-    # * <tt>"0008,0030"</tt> -- Study Time
-    # * <tt>"0008,0050"</tt> -- Accession Number
-    # * <tt>"0010,0010"</tt> -- Patient's Name
-    # * <tt>"0010,0020"</tt> -- Patient ID
-    # * <tt>"0020,000D"</tt> -- Study Instance UID
-    # * <tt>"0020,0010"</tt> -- Study ID
+    # === Instance level attributes for this query:
     #
-    # === Notes
+    # * '0008,0020' (Study Date)
+    # * '0008,0030' (Study Time)
+    # * '0008,0050' (Accession Number)
+    # * '0010,0010' (Patient's Name)
+    # * '0010,0020' (Patient ID)
+    # * '0020,000D' (Study Instance UID)
+    # * '0020,0010' (Study ID)
     #
-    # * Caution: Calling this method without parameters will instruct your PACS to return info on ALL studies in the database!
-    # * In addition to the above listed attributes, a number of "optional" attributes may be specified.
-    # * For a general list of optional study level attributes, refer to the DICOM standard, PS3.4 C.6.2.1.2, Table C.6-5.
+    # In addition to the above listed attributes, a number of "optional" attributes
+    # may be specified. For a general list of optional object instance level attributes,
+    # please refer to the DICOM standard, PS3.4 C.6.2.1.2, Table C.6-5.
     #
-    # === Examples
+    # @note Caution: Calling this method without parameters will instruct your PACS
+    #   to return info on ALL studies in the database!
+    # @param [Hash] query_params the query parameters to use
+    # @option query_params [String] 'GGGG,EEEE' a tag and value pair to be used in the query
     #
-    #   node.find_studies("0008,0020" => "20090604-", "0010,000D" => "123456789")
+    # @example Find all studies matching the given study date and patient's id
+    #   node.find_studies('0008,0020' => '20090604-', '0010,0020' => '123456789')
     #
     def find_studies(query_params={})
       # Study Root Query/Retrieve Information Model - FIND:
@@ -266,25 +246,22 @@ module DICOM
 
     # Retrieves a DICOM file from a service class provider (SCP/PACS).
     #
-    # === Restrictions
-    #
-    # * This method has never actually been tested, and as such, it is probably not working! Feedback is welcome.
+    # === Instance level attributes for this procedure:
     #
-    # === Parameters
+    # * '0008,0018' (SOP Instance UID)
+    # * '0008,0052' (Query/Retrieve Level)
+    # * '0020,000D' (Study Instance UID)
+    # * '0020,000E' (Series Instance UID)
     #
-    # * <tt>path</tt> -- The path where incoming files will be saved.
-    # * <tt>options</tt> -- A hash of parameters.
+    # @note This method has never actually been tested, and as such,
+    #   it is probably not working! Feedback is welcome.
     #
-    # === Options
+    # @param [String] path the directory where incoming files will be saved
+    # @param [Hash] options the options to use for retrieving the DICOM object
+    # @option options [String] 'GGGG,EEEE' a tag and value pair to be used for the procedure
     #
-    # * <tt>"0008,0018"</tt> -- SOP Instance UID
-    # * <tt>"0008,0052"</tt> -- Query/Retrieve Level
-    # * <tt>"0020,000D"</tt> -- Study Instance UID
-    # * <tt>"0020,000E"</tt> -- Series Instance UID
-    #
-    # === Examples
-    #
-    #   node.get_image("c:/dicom/", "0008,0018" => sop_uid, "0020,000D" => study_uid, "0020,000E" => series_uid)
+    # @example Retrieve a file as specified by its UIDs
+    #   node.get_image('c:/dicom/', '0008,0018' => sop_uid, '0020,000D' => study_uid, '0020,000E' => series_uid)
     #
     def get_image(path, options={})
       # Study Root Query/Retrieve Information Model - GET:
@@ -299,25 +276,22 @@ module DICOM
 
     # Moves a single image to a DICOM server.
     #
-    # === Notes
-    #
-    # * This DICOM node must be a third party (not yourself).
-    #
-    # === Parameters
-    #
-    # * <tt>destination</tt> -- String. The name (AE title) of the DICOM server which will receive the file.
-    # * <tt>options</tt> -- A hash of parameters.
+    # This DICOM node must be a third party (i.e. not the client instance you
+    # are requesting the move with!).
     #
-    # === Options
+    # === Instance level attributes for this procedure:
     #
-    # * <tt>"0008,0018"</tt> -- SOP Instance UID
-    # * <tt>"0008,0052"</tt> -- Query/Retrieve Level
-    # * <tt>"0020,000D"</tt> -- Study Instance UID
-    # * <tt>"0020,000E"</tt> -- Series Instance UID
+    # * '0008,0018' (SOP Instance UID)
+    # * '0008,0052' (Query/Retrieve Level)
+    # * '0020,000D' (Study Instance UID)
+    # * '0020,000E' (Series Instance UID)
     #
-    # === Examples
+    # @param [String] destination the AE title of the DICOM server which will receive the file
+    # @param [Hash] options the options to use for moving the DICOM object
+    # @option options [String] 'GGGG,EEEE' a tag and value pair to be used for the procedure
     #
-    #   node.move_image("SOME_SERVER", "0008,0018" => sop_uid, "0020,000D" => study_uid, "0020,000E" => series_uid)
+    # @example Move an image from e.q. a PACS to another SCP on the network
+    #   node.move_image('SOME_SERVER', '0008,0018' => sop_uid, '0020,000D' => study_uid, '0020,000E' => series_uid)
     #
     def move_image(destination, options={})
       # Study Root Query/Retrieve Information Model - MOVE:
@@ -332,24 +306,21 @@ module DICOM
 
     # Move an entire study to a DICOM server.
     #
-    # === Notes
-    #
-    # * This DICOM node must be a third party (not yourself).
+    # This DICOM node must be a third party (i.e. not the client instance you
+    # are requesting the move with!).
     #
-    # === Parameters
+    # === Instance level attributes for this procedure:
     #
-    # * <tt>destination</tt> -- String. The name (AE title) of the DICOM server which will receive the files.
-    # * <tt>options</tt> -- A hash of parameters.
+    # * '0008,0052' (Query/Retrieve Level)
+    # * '0010,0020' (Patient ID)
+    # * '0020,000D' (Study Instance UID)
     #
-    # === Options
+    # @param [String] destination the AE title of the DICOM server which will receive the files
+    # @param [Hash] options the options to use for moving the DICOM objects
+    # @option options [String] 'GGGG,EEEE' a tag and value pair to be used for the procedure
     #
-    # * <tt>"0008,0052"</tt> -- Query/Retrieve Level
-    # * <tt>"0010,0020"</tt> -- Patient ID
-    # * <tt>"0020,000D"</tt> -- Study Instance UID
-    #
-    # === Examples
-    #
-    #   node.move_study("SOME_SERVER", "0010,0020" => pat_id, "0020,000D" => study_uid)
+    # @example Move an entire study from e.q. a PACS to another SCP on the network
+    #   node.move_study('SOME_SERVER', '0010,0020' => pat_id, '0020,000D' => study_uid)
     #
     def move_study(destination, options={})
       # Study Root Query/Retrieve Information Model - MOVE:
@@ -364,13 +335,9 @@ module DICOM
 
     # Sends one or more DICOM files to a service class provider (SCP/PACS).
     #
-    # === Parameters
-    #
-    # * <tt>files</tt> -- A single file path or an array of paths, or a DObject or an array of DObject instances.
-    #
-    # === Examples
-    #
-    #   node.send("my_file.dcm")
+    # @param [Array<String, DObject>, String, DObject] files a single file path or an array of paths, alternatively a DObject or an array of DObject instances
+    # @example Send a DICOM file to a storage server
+    #   node.send('my_file.dcm')
     #
     def send(files)
       # Prepare the DICOM object(s):
@@ -393,7 +360,8 @@ module DICOM
       end
     end
 
-    # Tests the connection to the server in a very simple way  by negotiating an association and then releasing it.
+    # Tests the connection to the server in a very simple way  by negotiating
+    # an association and then releasing it.
     #
     def test
       logger.info("TESTING CONNECTION...")
@@ -418,7 +386,6 @@ module DICOM
     end
 
 
-    # Following methods are private:
     private
 
 
@@ -748,18 +715,15 @@ module DICOM
       else
         # We still consider the request 'approved' if at least one context were accepted:
         @request_approved = true if @approved_syntaxes.length > 0
-
         logger.error("One or more of your presentation contexts were denied by host #{@host_ae}!")
-
         @approved_syntaxes.each_pair do |key, value|
-          sntx_k = LIBRARY.get_syntax_description(key)
-          sntx_v = LIBRARY.get_syntax_description(value[1])
+          sntx_k = (LIBRARY.uid(key) ? LIBRARY.uid(key).name : 'Unknown UID!')
+          sntx_v = (LIBRARY.uid(value[1]) ? LIBRARY.uid(value[1]).name : 'Unknown UID!')
           logger.info("APPROVED: #{sntx_k} (#{sntx_v})")
         end
-
         rejected.each_pair do |key, value|
-          sntx_k = LIBRARY.get_syntax_description(key)
-          sntx_v = LIBRARY.get_syntax_description(value[1])
+          sntx_k = (LIBRARY.uid(key) ? LIBRARY.uid(key).name : 'Unknown UID!')
+          sntx_v = (LIBRARY.uid(value[1]) ? LIBRARY.uid(value[1]).name : 'Unknown UID!')
           logger.error("REJECTED: #{sntx_k} (#{sntx_v})")
         end
       end
@@ -918,23 +882,31 @@ module DICOM
     def set_user_information_array
       @user_information = [
         [ITEM_MAX_LENGTH, "UL", @max_package_size],
-        [ITEM_IMPLEMENTATION_UID, "STR", UID],
+        [ITEM_IMPLEMENTATION_UID, "STR", UID_ROOT],
         [ITEM_IMPLEMENTATION_VERSION, "STR", NAME]
       ]
     end
 
+    # Checks if an association has been established.
+    #
     def association_established?
       @association == true
     end
 
+    # Checks if a request has been approved.
+    #
     def request_approved?
       @request_approved == true
     end
 
+    # Extracts the presentation context id from the approved syntax.
+    #
     def presentation_context_id
       @approved_syntaxes.to_a.first[1][0] # ID of first (and only) syntax in this Hash.
     end
 
+    # Sets the data_elements instance array with the given options.
+    #
     def set_data_elements(options)
       @data_elements = []
       options.keys.sort.each do |tag|

data/lib/dicom/d_library.rb

@@ -1,288 +1,220 @@
-module DICOM
-
-  # This class contains methods that interact with Ruby DICOM's dictionary.
-  #
-  class DLibrary
-
-    # A hash with element name strings as key and method name symbols as value.
-    attr_reader :methods_from_names
-    # A hash with element method name symbols as key and name strings as value.
-    attr_reader :names_from_methods
-    # A hash containing tags as key and an array as value, where the array contains data element vr and name.
-    attr_reader :tags
-    # A hash containing UIDs as key and an array as value, where the array contains name and type.
-    attr_reader :uid
-
-    # Creates a DLibrary instance.
-    #
-    def initialize
-      # Load the data elements hash, where the keys are tag strings, and values
-      # are two-element arrays [vr, name] (where vr itself is an array of 1-3 elements):
-      @tags = Dictionary.load_data_elements
-      # Load UID hash (DICOM unique identifiers), where the keys are UID strings,
-      # and values are two-element arrays [description, type]:
-      @uid = Dictionary.load_uid
-      create_method_conversion_tables
-    end
-
-    # Returns the method (symbol) corresponding to the specified string value (which may represent a element tag, name or method).
-    # Returns nil if no match is found.
-    #
-    def as_method(value)
-      case true
-      when value.tag?
-        name, vr = get_name_vr(value)
-        @methods_from_names[name]
-      when value.dicom_name?
-        @methods_from_names[value]
-      when value.dicom_method?
-        @names_from_methods.has_key?(value.to_sym) ? value.to_sym : nil
-      else
-        nil
-      end
-    end
-
-    # Returns the name (string) corresponding to the specified string value (which may represent a element tag, name or method).
-    # Returns nil if no match is found.
-    #
-    def as_name(value)
-      case true
-      when value.tag?
-        name, vr = get_name_vr(value)
-        name
-      when value.dicom_name?
-        @methods_from_names.has_key?(value) ? value.to_s : nil
-      when value.dicom_method?
-        @names_from_methods[value.to_sym]
-      else
-        nil
-      end
-    end
-
-    # Returns the tag (string) corresponding to the specified string value (which may represent a element tag, name or method).
-    # Returns nil if no match is found.
-    #
-    def as_tag(value)
-      case true
-      when value.tag?
-        name, vr = get_name_vr(value)
-        name.nil? ? nil : value
-      when value.dicom_name?
-        get_tag(value)
-      when value.dicom_method?
-        get_tag(@names_from_methods[value.to_sym])
-      else
-        nil
-      end
-    end
-
-    # Checks whether a given string is a valid transfer syntax or not.
-    # Returns true if valid, false if not.
-    #
-    # === Parameters
-    #
-    # * <tt>uid</tt> -- String. A DICOM UID value which will be matched against known transfer syntaxes.
-    #
-    def check_ts_validity(uid)
-      result = false
-      value = @uid[uid]
-      if value
-        result = true if value[1] == "Transfer Syntax"
-      end
-      return result
-    end
-
-    # Extracts, and returns, all transfer syntaxes and SOP Classes from the dictionary,
-    # in the form of a transfer syntax hash and a sop class hash.
-    #
-    # Both hashes have UIDs as keys and their descriptions as values.
-    #
-    def extract_transfer_syntaxes_and_sop_classes
-      transfer_syntaxes = Hash.new
-      sop_classes = Hash.new
-      @uid.each_pair do |key, value|
-        if value[1] == "Transfer Syntax"
-          transfer_syntaxes[key] = value[0]
-        elsif value[1] == "SOP Class"
-          sop_classes[key] = value[0]
-        end
-      end
-      return transfer_syntaxes, sop_classes
-    end
-
-    # Checks if the specified transfer syntax implies the presence of pixel compression.
-    # Returns true if pixel compression is implied, false if not.
-    #
-    # === Parameters
-    #
-    # * <tt>uid</tt> -- String. A DICOM UID value.
-    #
-    def get_compression(uid)
-      raise ArgumentError, "Expected String, got #{uid.class}" unless uid.is_a?(String)
-      result = false
-      value = @uid[uid]
-      if value
-        first_word = value[0].split(" ").first
-        result = true if value[1] == "Transfer Syntax" and not ["Implicit", "Explicit"].include?(first_word)
-      end
-      return result
-    end
-
-    # Determines, and returns, the name and vr of the data element which the specified tag belongs to.
-    # Values are retrieved from the Ruby DICOM dictionary if a match is found.
-    #
-    # === Notes
-    #
-    # * Private tags will have their names listed as "Private".
-    # * Non-private tags that are not found in the dictionary will be listed as "Unknown".
-    #
-    # === Parameters
-    #
-    # * <tt>tag</tt> -- String. A data element tag.
-    #
-    def get_name_vr(tag)
-      if tag.private? and tag.element != GROUP_LENGTH
-        name = "Private"
-        vr = "UN"
-      else
-        # Check the dictionary:
-        values = @tags[tag]
-        if values
-          name = values[1]
-          vr = values[0][0]
-        else
-          # For the tags that are not recognised, we need to do some additional testing to see if it is one of the special cases:
-          if tag.element == GROUP_LENGTH
-            # Group length:
-            name = "Group Length"
-            vr = "UL"
-          elsif tag[0..6] == "0020,31"
-            # Source Image ID's (Retired):
-            values = @tags["0020,31xx"]
-            name = values[1]
-            vr = values[0][0]
-          elsif tag.group == "1000" and tag.element =~ /\A\h{3}[0-5]\z/
-            # Group 1000,xxx[0-5] (Retired):
-            new_tag = tag.group + "xx" + tag.element[3..3]
-            values = @tags[new_tag]
-          elsif tag.group == "1010"
-            # Group 1010,xxxx (Retired):
-            new_tag = tag.group + "xxxx"
-            values = @tags[new_tag]
-          elsif tag[0..1] == "50" or tag[0..1] == "60"
-            # Group 50xx (Retired) and 60xx:
-            new_tag = tag[0..1]+"xx"+tag[4..8]
-            values = @tags[new_tag]
-            if values
-              name = values[1]
-              vr = values[0][0]
-            end
-          elsif tag[0..1] == "7F" and tag[5..6] == "00"
-            # Group 7Fxx,00[10,11,20,30,40] (Retired):
-            new_tag = tag[0..1]+"xx"+tag[4..8]
-            values = @tags[new_tag]
-            if values
-              name = values[1]
-              vr = values[0][0]
-            end
-          end
-          # If none of the above checks yielded a result, the tag is unknown:
-          unless name
-            name = "Unknown"
-            vr = "UN"
-          end
-        end
-      end
-      return name, vr
-    end
-
-    # Returns the tag that matches the supplied data element name, by searching the Ruby DICOM dictionary.
-    # Returns nil if no match is found.
-    #
-    # === Parameters
-    #
-    # * <tt>name</tt> -- String. A data element name.
-    #
-    def get_tag(name)
-      tag = nil
-      name = name.to_s.downcase
-      @tag_name_pairs_cache ||= Hash.new
-      return @tag_name_pairs_cache[name] unless @tag_name_pairs_cache[name].nil?
-      @tags.each_pair do |key, value|
-        next unless value[1].downcase == name
-        tag = key
-        break
-      end
-      @tag_name_pairs_cache[name]=tag
-      return tag
-    end
-
-    # Returns the description/name of a specified UID (i.e. a transfer syntax or SOP class).
-    # Returns nil if no match is found
-    #
-    # === Parameters
-    #
-    # * <tt>uid</tt> -- String. A DICOM UID value.
-    #
-    def get_syntax_description(uid)
-      name = nil
-      value = @uid[uid]
-      name = value[0] if value
-      return name
-    end
-
-    # Checks the validity of the specified transfer syntax UID and determines the
-    # encoding settings (explicitness & endianness) associated with this value.
-    # The results are returned as 3 booleans: validity, explicitness & endianness.
-    #
-    # === Parameters
-    #
-    # * <tt>uid</tt> -- String. A DICOM UID value.
-    #
-    def process_transfer_syntax(uid)
-      valid = check_ts_validity(uid)
-      case uid
-        # Some variations with uncompressed pixel data:
-        when IMPLICIT_LITTLE_ENDIAN
-          explicit = false
-          endian = false
-        when EXPLICIT_LITTLE_ENDIAN
-          explicit = true
-          endian = false
-        when "1.2.840.10008.1.2.1.99" # Deflated Explicit VR, Little Endian
-          # Note: Has this transfer syntax been tested yet?
-          explicit = true
-          endian = false
-        when EXPLICIT_BIG_ENDIAN
-          explicit = true
-          endian = true
-        else
-          # For everything else, assume compressed pixel data, with Explicit VR, Little Endian:
-          explicit = true
-          endian = false
-      end
-      return valid, explicit, endian
-    end
-
-
-    private
-
-
-    # Creates the instance hashes that are used for name to/from method conversion.
-    #
-    def create_method_conversion_tables
-      if @methods_from_names.nil?
-        @methods_from_names = Hash.new
-        @names_from_methods = Hash.new
-        # Fill the hashes:
-        @tags.each_pair do |key, value|
-          name = value[1]
-          method_name = name.dicom_methodize
-          @methods_from_names[name] = method_name.to_sym
-          @names_from_methods[method_name.to_sym] = name
-        end
-      end
-    end
-
-  end
+module DICOM
+
+  # The DLibrary class contains methods for interacting with ruby-dicom's dictionary data.
+  #
+  # In practice, the library is for internal use and not accessed by the user. However, a
+  # a library instance is available through the DICOM::LIBRARY constant.
+  #
+  # @example Get a dictionary element corresponding to the given tag
+  #   element = DICOM::LIBRARY.element('0010,0010')
+  #
+  class DLibrary
+
+    # A hash with element name strings as key and method name symbols as value.
+    attr_reader :methods_from_names
+    # A hash with element method name symbols as key and name strings as value.
+    attr_reader :names_from_methods
+
+    # Creates a DLibrary instance.
+    #
+    def initialize
+      # Create instance hashes used for dictionary data and method conversion:
+      @elements = Hash.new
+      @uids = Hash.new
+      @methods_from_names = Hash.new
+      @names_from_methods = Hash.new
+      # Load the elements dictionary:
+      File.open("#{ROOT_DIR}/dictionary/elements.txt").each do |record|
+        load_element(record)
+      end
+      # Load the unique identifiers dictionary:
+      File.open("#{ROOT_DIR}/dictionary/uids.txt").each do |record|
+        fields = record.split("\t")
+        # Store the uids in a hash with uid-value as key and the uid instance as value:
+        @uids[fields[0]] = UID.new(fields[0], fields[1], fields[2].rstrip, fields[3].rstrip)
+      end
+    end
+
+    # Adds a custom dictionary file to the ruby-dicom element dictionary.
+    #
+    # @note The format of the dictionary is a tab-separated text file with 5 columns:
+    #   * Tag, Name, VR, VM & Retired status
+    #   * For samples check out ruby-dicom's element dictionaries in the git repository
+    # @param [String] file The path to the dictionary file to be added
+    #
+    def add_element_dictionary(file)
+      File.open(file).each do |record|
+        load_element(record)
+      end
+    end
+
+
+    # Gives the method (symbol) corresponding to the specified element string value.
+    #
+    # @param [String] value an element tag, element name or an element's method name
+    # @return [Symbol, NilClass] the matched element method, or nil if no match is made
+    #
+    def as_method(value)
+      case true
+      when value.tag?
+        @methods_from_names[element(value).name]
+      when value.dicom_name?
+        @methods_from_names[value]
+      when value.dicom_method?
+        @names_from_methods.has_key?(value.to_sym) ? value.to_sym : nil
+      else
+        nil
+      end
+    end
+
+    # Gives the name corresponding to the specified element string value.
+    #
+    # @param [String] value an element tag, element name or an element's method name
+    # @return [String, NilClass] the matched element name, or nil if no match is made
+    #
+    def as_name(value)
+      case true
+      when value.tag?
+        element(value).name
+      when value.dicom_name?
+        @methods_from_names.has_key?(value) ? value.to_s : nil
+      when value.dicom_method?
+        @names_from_methods[value.to_sym]
+      else
+        nil
+      end
+    end
+
+    # Gives the tag corresponding to the specified element string value.
+    #
+    # @param [String] value an element tag, element name or an element's method name
+    # @return [String, NilClass] the matched element tag, or nil if no match is made
+    #
+    def as_tag(value)
+      case true
+      when value.tag?
+        element(value) ? value : nil
+      when value.dicom_name?
+        get_tag(value)
+      when value.dicom_method?
+        get_tag(@names_from_methods[value.to_sym])
+      else
+        nil
+      end
+    end
+
+    # Identifies the DictionaryElement that corresponds to the given tag.
+    #
+    # @note If a given tag doesn't return a dictionary match, a new DictionaryElement is created.
+    #   * For private tags, a name 'Private' and VR 'UN' is assigned
+    #   * For unknown tags, a name 'Unknown' and VR 'UN' is assigned
+    # @param [String] tag the tag of the element
+    # @return [DictionaryElement] a corresponding DictionaryElement
+    #
+    def element(tag)
+      element = @elements[tag]
+      unless element
+        if tag.group_length?
+          element = DictionaryElement.new(tag, 'Group Length', ['UL'], '1', '')
+        else
+          if tag.private?
+            element = DictionaryElement.new(tag, 'Private', ['UN'], '1', '')
+          else
+            if !(de = @elements["#{tag[0..3]},xxx#{tag[8]}"]).nil? # 1000,xxxh
+              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
+            elsif !(de = @elements["#{tag[0..3]},xxxx"]).nil? # 1010,xxxx
+              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
+            elsif !(de = @elements["#{tag[0..1]}xx,#{tag[5..8]}"]).nil? # hhxx,hhhh
+              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
+            elsif !(de = @elements["#{tag[0..6]}x#{tag[8]}"]).nil? # 0028,hhxh
+              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
+            else
+              # We are facing an unknown (but not private) tag:
+              element = DictionaryElement.new(tag, 'Unknown', ['UN'], '1', '')
+            end
+          end
+        end
+      end
+      return element
+    end
+
+    # Extracts, and returns, all transfer syntaxes and SOP Classes from the dictionary.
+    #
+    # @return [Array<Hash, Hash>] transfer syntax and sop class hashes, each with uid as key and name as value
+    #
+    def extract_transfer_syntaxes_and_sop_classes
+      transfer_syntaxes = Hash.new
+      sop_classes = Hash.new
+      @uids.each_value do |uid|
+        if uid.transfer_syntax?
+          transfer_syntaxes[uid.value] = uid.name
+        elsif uid.sop_class?
+          sop_classes[uid.value] = uid.name
+        end
+      end
+      return transfer_syntaxes, sop_classes
+    end
+
+    # Gives the tag that matches the supplied data element name, by searching the element dictionary.
+    #
+    # @param [String] name a data element name
+    # @return [String, NilClass] the corresponding element tag, or nil if no match is made
+    #
+    def get_tag(name)
+      tag = nil
+      name = name.to_s.downcase
+      @tag_name_pairs_cache ||= Hash.new
+      return @tag_name_pairs_cache[name] unless @tag_name_pairs_cache[name].nil?
+      @elements.each_value do |element|
+        next unless element.name.downcase == name
+        tag = element.tag
+        break
+      end
+      @tag_name_pairs_cache[name]=tag
+      return tag
+    end
+
+    # Determines the name and vr of the element which the specified tag belongs to,
+    # based on a lookup in the element data dictionary.
+    #
+    # @note If a given tag doesn't return a dictionary match, the following values are assigned:
+    #   * For private tags: name 'Private' and VR 'UN'
+    #   * For unknown (non-private) tags: name 'Unknown' and VR 'UN'
+    # @param [String] tag an element's tag
+    # @return [Array<String, String>] the name and value representation corresponding to the given tag
+    #
+    def name_and_vr(tag)
+      de = element(tag)
+      return de.name, de.vr
+    end
+
+    # Identifies the UID that corresponds to the given value.
+    #
+    # @param [String] value the unique identifier value
+    # @return [UID, NilClass] a corresponding UID instance, or nil (if no match is made)
+    #
+    def uid(value)
+      @uids[value]
+    end
+
+
+    private
+
+
+    # Loads an element to the dictionary from an element string record.
+    #
+    # @param [String] record a tab-separated string line as extracted from a dictionary file
+    #
+    def load_element(record)
+      fields = record.split("\t")
+      # Store the elements in a hash with tag as key and the element instance as value:
+      element = DictionaryElement.new(fields[0], fields[1], fields[2].split(","), fields[3].rstrip, fields[4].rstrip)
+      @elements[fields[0]] = element
+      # Populate the method conversion hashes with element data:
+      method = element.name.to_element_method
+      @methods_from_names[element.name] = method
+      @names_from_methods[method] = element.name
+    end
+
+  end
 end