Class: DICOM::DLibrary

Inherits:
Object
  • Object
show all
Defined in:
lib/dicom/d_library.rb

Overview

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.

Examples:

Get a dictionary element corresponding to the given tag

element = DICOM::LIBRARY.element('0010,0010')

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ DLibrary

Creates a DLibrary instance.



20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/dicom/d_library.rb', line 20

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:

  add_element_dictionary("#{ROOT_DIR}/dictionary/elements.txt")
  # Load the unique identifiers dictionary:

  add_uid_dictionary("#{ROOT_DIR}/dictionary/uids.txt")
end

Instance Attribute Details

#methods_from_names ⇒ Object (readonly)

A hash with element name strings as key and method name symbols as value.



14
15
16
 
# File 'lib/dicom/d_library.rb', line 14

def methods_from_names
  @methods_from_names
end

#names_from_methods ⇒ Object (readonly)

A hash with element method name symbols as key and name strings as value.



16
17
18
 
# File 'lib/dicom/d_library.rb', line 16

def names_from_methods
  @names_from_methods
end

Instance Method Details

#add_element(element) ⇒ Object

Adds a custom DictionaryElement to the ruby-dicom element dictionary.

Raises:

  • (ArgumentError) 


36
37
38
39
40
41
42
43
44
 
# File 'lib/dicom/d_library.rb', line 36

def add_element(element)
  raise ArgumentError, "Invalid argument 'element'. Expected DictionaryElement, got #{element.class}" unless element.is_a?(DictionaryElement)
  # We store the elements in a hash with tag as key and the element instance as value:

  @elements[element.tag] = 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

#add_element_dictionary(file) ⇒ Object

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

Adds a custom dictionary file to the ruby-dicom element dictionary.



53
54
55
56
57
58
 
# File 'lib/dicom/d_library.rb', line 53

def add_element_dictionary(file)
  File.open(file, :encoding => 'utf-8').each do |record|
    fields = record.split("\t")
    add_element(DictionaryElement.new(fields[0], fields[1], fields[2].split(","), fields[3].rstrip, fields[4].rstrip))
  end
end

#add_uid(uid) ⇒ Object

Adds a custom uid (e.g. SOP Class, Transfer Syntax) to the ruby-dicom uid dictionary.

Raises:

  • (ArgumentError) 


64
65
66
67
68
 
# File 'lib/dicom/d_library.rb', line 64

def add_uid(uid)
  raise ArgumentError, "Invalid argument 'uid'. Expected UID, got #{uid.class}" unless uid.is_a?(UID)
  # We store the uids in a hash with uid-value as key and the uid instance as value:

  @uids[uid.value] = uid
end

#add_uid_dictionary(file) ⇒ Object

Note:

The format of the dictionary is a tab-separated text file with 4 columns:

  • Value, Name, Type & Retired status

  • For samples check out ruby-dicom’s uid dictionaries in the git repository

Adds a custom dictionary file to the ruby-dicom uid dictionary.



77
78
79
80
81
82
 
# File 'lib/dicom/d_library.rb', line 77

def add_uid_dictionary(file)
  File.open(file, :encoding => 'utf-8').each do |record|
    fields = record.split("\t")
    add_uid(UID.new(fields[0], fields[1], fields[2].rstrip, fields[3].rstrip))
  end
end

#as_method(value) ⇒ Symbol, NilClass

Gives the method (symbol) corresponding to the specified element string value.



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/dicom/d_library.rb', line 90

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

#as_name(value) ⇒ String, NilClass

Gives the name corresponding to the specified element string value.



108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/dicom/d_library.rb', line 108

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

#as_tag(value) ⇒ String, NilClass

Gives the tag corresponding to the specified element string value.



126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/dicom/d_library.rb', line 126

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

#element(tag) ⇒ DictionaryElement

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

Identifies the DictionaryElement that corresponds to the given tag.



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/dicom/d_library.rb', line 147

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

#extract_transfer_syntaxes_and_sop_classes ⇒ Array<Hash, Hash>

Extracts, and returns, all transfer syntaxes and SOP Classes from the dictionary.



178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/dicom/d_library.rb', line 178

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

#get_tag(name) ⇒ String, NilClass

Gives the tag that matches the supplied data element name, by searching the element dictionary.



196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/dicom/d_library.rb', line 196

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

#name_and_vr(tag) ⇒ Array<String, String>

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’

Determines the name and vr of the element which the specified tag belongs to, based on a lookup in the element data dictionary.



219
220
221
222
 
# File 'lib/dicom/d_library.rb', line 219

def name_and_vr(tag)
  de = element(tag)
  return de.name, de.vr
end

#uid(value) ⇒ UID, NilClass

Identifies the UID that corresponds to the given value.



229
230
231
 
# File 'lib/dicom/d_library.rb', line 229

def uid(value)
  @uids[value]
end