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.



24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/dicom/d_library.rb', line 24

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.tsv")
  # Load the unique identifiers dictionary:
  add_uid_dictionary("#{ROOT_DIR}/dictionary/uids.tsv")
end

Instance Attribute Details

#elements ⇒ Object (readonly)

A hash with element tag strings as keys and DicitonaryElement instances as values.



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

def elements
  @elements
end

#methods_from_names ⇒ Object (readonly)

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



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

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.



18
19
20
 
# File 'lib/dicom/d_library.rb', line 18

def names_from_methods
  @names_from_methods
end

#uids ⇒ Object (readonly)

A hash with uid strings as keys and UID instances as values.



20
21
22
 
# File 'lib/dicom/d_library.rb', line 20

def uids
  @uids
end

Instance Method Details

#add_element(element) ⇒ Object

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

Parameters:

Raises:

  • (ArgumentError) 


40
41
42
43
44
45
46
47
48
 
# File 'lib/dicom/d_library.rb', line 40

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



57
58
59
60
61
62
 
# File 'lib/dicom/d_library.rb', line 57

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) 


68
69
70
71
72
 
# File 'lib/dicom/d_library.rb', line 68

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



81
82
83
84
85
86
 
# File 'lib/dicom/d_library.rb', line 81

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



94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/dicom/d_library.rb', line 94

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



112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/dicom/d_library.rb', line 112

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



130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/dicom/d_library.rb', line 130

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:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/dicom/d_library.rb', line 151

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
        element = unknown_or_range_element(tag)
      end
    end
  end
  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



171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/dicom/d_library.rb', line 171

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



189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/dicom/d_library.rb', line 189

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



212
213
214
215
 
# File 'lib/dicom/d_library.rb', line 212

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)



222
223
224
 
# File 'lib/dicom/d_library.rb', line 222

def uid(value)
  @uids[value]
end