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.

Parameters:

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.

Parameters:

  • file (String) —

    the path to the dictionary file to be added



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.

Parameters:

  • uid (UID) —

    the custom uid instance to be added

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.

Parameters:

  • file (String) —

    the path to the dictionary file to be added



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.

Parameters:

  • value (String) —

    an element tag, element name or an element’s method name

Returns:

  • (Symbol, NilClass) —

    the matched element method, or nil if no match is made



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.

Parameters:

  • value (String) —

    an element tag, element name or an element’s method name

Returns:

  • (String, NilClass) —

    the matched element name, or nil if no match is made



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.

Parameters:

  • value (String) —

    an element tag, element name or an element’s method name

Returns:

  • (String, NilClass) —

    the matched element tag, or nil if no match is made



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.

Parameters:

  • tag (String) —

    the tag of the element

Returns:



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.

Returns:

  • (Array<Hash, Hash>) —

    transfer syntax and sop class hashes, each with uid as key and name as value



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.

Parameters:

  • name (String) —

    a data element name

Returns:

  • (String, NilClass) —

    the corresponding element tag, or nil if no match is made



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.

Parameters:

  • tag (String) —

    an element’s tag

Returns:

  • (Array<String, String>) —

    the name and value representation corresponding to the given tag



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.

Parameters:

  • value (String) —

    the unique identifier value

Returns:

  • (UID, NilClass) —

    a corresponding UID instance, or nil (if no match is made)



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

def uid(value)
  @uids[value]
end