class DICOM::Element

The Element class handles information related to ordinary (non-parent) elementals (data elements).

Public Class Methods

new(tag, value, options={}) click to toggle source

Creates an Element instance.

@note In the case where the Element is given a binary instead of value,

the Element will not have a formatted value (value = nil).

@note Private data elements are named as 'Private'. @note Non-private data elements that are not found in the dictionary are named as 'Unknown'.

@param [String] tag a ruby-dicom type element tag string @param [String, Integer, Float, Array, NilClass] value a custom value to be encoded as the data element binary string, or in some cases (specified by options), a pre-encoded binary string @param [Hash] options the options to use for creating the element

@option options [String] :bin if you already have the value pre-encoded to a binary string, the string can be supplied with this option to avoid it being encoded a second time @option options [Boolean] :encoded if the value parameter contains a pre-encoded binary, this boolean must to be set as true @option options [String] :name the name of the Element (if not specified, the name is retrieved from the dictionary) @option options [DObject, Item, NilClass] :parent a parent instance (Item or DObject) which the element belongs to @option options [String] :vr if a private element is created with a custom value, this must be specified to enable the encoding of the value (if not specified, the vr is retrieved from the dictionary)

@example Create a new data element and connect it to a DObject instance

patient_name = Element.new('0010,0010', 'John Doe', :parent => dcm)

@example Create a “Pixel Data” element and insert image data that you have already encoded elsewhere

pixel_data = Element.new('7FE0,0010', processed_pixel_data, :encoded => true, :parent => dcm)

@example Create a private data element

private = Element.new('0011,2102', some_data, :parent => dcm, :vr => 'LO')
# File lib/dicom/element.rb, line 34
def initialize(tag, value, options={})
  raise ArgumentError, "The supplied tag (#{tag}) is not valid. The tag must be a string of the form 'GGGG,EEEE'." unless tag.is_a?(String) && tag.tag?
  # Set instance variables:
  @tag = tag.upcase
  # We may need to retrieve name and vr from the library:
  if options[:name] and options[:vr]
    @name = options[:name]
    @vr = options[:vr].upcase
  else
    name, vr = LIBRARY.name_and_vr(tag)
    @name = options[:name] || name
    @vr = (options[:vr] ? options[:vr].upcase : vr)
  end
  # Manage the parent relation if specified:
  if options[:parent]
    @parent = options[:parent]
    # FIXME: Because of some implementation problems, attaching the special
    # Data Set Trailing Padding element to a parent is not supported yet!
    @parent.add(self, :no_follow => true) unless @tag == 'FFFC,FFFC' && @parent.is_a?(Sequence)
  end
  # Value may in some cases be the binary string:
  unless options[:encoded]
    # The Data Element may have a value, have no value and no binary, or have no value and only binary:
    if value
      # Is binary value provided or do we need to encode it?
      if options[:bin]
        @value = value
        @bin = options[:bin]
      else
        if value == ''
          @value = value
          @bin = ''
        else
          # Set the value with our custom setter method to get proper encoding:
          self.value = value
        end
      end
    else
      # When no value is present, we set the binary as an empty string, unless the binary is specified:
      @bin = options[:bin] || ''
    end
  else
    @bin = value
  end
  # Let the binary decide the length:
  @length = @bin.length
end

Public Instance Methods

==(other) click to toggle source

Checks for equality.

Other and self are considered equivalent if they are of compatible types and their attributes are equivalent.

@param other an object to be compared with self. @return [Boolean] true if self and other are considered equivalent

# File lib/dicom/element.rb, line 90
def ==(other)
  if other.respond_to?(:to_element)
    other.send(:state) == state
  end
end
Also aliased as: eql?
bin=(new_bin) click to toggle source

Sets the binary string of a Element.

@note if the specified binary has an odd length, a proper pad byte will automatically be appended

to give it an even length (which is needed to conform with the DICOM standard).

@param [String] new_bin a binary string of encoded data

# File lib/dicom/element.rb, line 105
def bin=(new_bin)
  raise ArgumentError, "Expected String, got #{new_bin.class}." unless new_bin.is_a?(String)
  # Add a zero byte at the end if the length of the binary is odd:
  if new_bin.length.odd?
    @bin = new_bin + stream.pad_byte[@vr]
  else
    @bin = new_bin
  end
  @value = nil
  @length = @bin.length
end
children?() click to toggle source

Checks if the Element actually has any child elementals.

@return [FalseClass] always returns false, as Element instances by definition can't have children

# File lib/dicom/element.rb, line 121
def children?
  return false
end
endian() click to toggle source

Gives the endianness of the encoded binary value of this element.

@return [Boolean] false if little endian, true if big endian

# File lib/dicom/element.rb, line 129
def endian
  return stream.str_endian
end
eql?(other)
Alias for: ==
hash() click to toggle source

Computes a hash code for this object.

@note Two objects with the same attributes will have the same hash code.

@return [Integer] the object's hash code

# File lib/dicom/element.rb, line 139
def hash
  state.hash
end
inspect() click to toggle source

Gives a string containing a human-readable hash representation of the Element.

@return [String] a hash representation string of the element

# File lib/dicom/element.rb, line 147
def inspect
  to_hash.inspect
end
is_parent?() click to toggle source

Checks if the Element is a parent.

@return [FalseClass] always returns false, as Element instances by definition are not parents

# File lib/dicom/element.rb, line 155
def is_parent?
  return false
end
to_element() click to toggle source

Returns self.

@return [Element] self

# File lib/dicom/element.rb, line 173
def to_element
  self
end
to_hash() click to toggle source

Creates a hash representation of the element instance.

@note The key representation in this hash is configurable

(refer to the DICOM module methods documentation for more details).

@return [Hash] a hash containing a key & value pair (e.g. {“Modality”=>“MR”})

# File lib/dicom/element.rb, line 165
def to_hash
  return {self.send(DICOM.key_representation) => value}
end
to_json() click to toggle source

Gives a json string containing a human-readable representation of the Element.

@return [String] a string containing a key & value pair (e.g. “{"Modality":"MR"}”)

# File lib/dicom/element.rb, line 181
def to_json
  to_hash.to_json
end
to_yaml() click to toggle source

Gives a yaml string containing a human-readable representation of the Element.

@return [String] a string containing a key & value pair (e.g. “—nModality: MRn”)

# File lib/dicom/element.rb, line 189
def to_yaml
  to_hash.to_yaml
end
value() click to toggle source

Gives the (decoded) value of the data element.

@note Returned string values are automatically converted from their originally

encoding (e.g. ISO8859-1 or ASCII-8BIT) to UTF-8 for convenience reasons.
If the value string is wanted in its original encoding, extract the data
element's bin attribute instead.

@note Note that according to the DICOM Standard PS 3.5 C.12.1.1.2, the Character Set only applies to values of data elements of type SH, LO, ST, PN, LT or UT. Currently in ruby-dicom, all string values are encoding converted regardless of VR, but whether this causes any problems is uknown.

@return [String, Integer, Float] the formatted element value

# File lib/dicom/element.rb, line 206
def value
  if @value.is_a?(String)
    # Unless this is actually the Character Set data element,
    # get the character set (note that it may not be available):
    character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
    # Convert to UTF-8 from [original encoding]:
    # In most cases the original encoding is IS0-8859-1 (ISO_IR 100), but if
    # it is not specified in the DICOM object, or if the specified string
    # is not recognized, ASCII-8BIT is assumed.
    @value.encode('UTF-8', ENCODING_NAME[character_set])
    # If unpleasant encoding exceptions occur, the below version may be considered:
    #@value.encode('UTF-8', ENCODING_NAME[character_set], :invalid => :replace, :undef => :replace)
  else
    @value
  end
end
value=(new_value) click to toggle source

Sets the value of the Element instance.

In addition to updating the value attribute, the specified value is encoded to binary and used to update the Element's bin and length attributes too.

@note The specified value must be of a type that is compatible with the Element's value representation (vr). @param [String, Integer, Float, Array] new_value a formatted value that is assigned to the element

# File lib/dicom/element.rb, line 231
def value=(new_value)
  if VALUE_CONVERSION[@vr] == :to_s
    # Unless this is actually the Character Set data element,
    # get the character set (note that it may not be available):
    character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
    # Convert to [DObject encoding] from [input string encoding]:
    # In most cases the DObject encoding is IS0-8859-1 (ISO_IR 100), but if
    # it is not specified in the DICOM object, or if the specified string
    # is not recognized, ASCII-8BIT is assumed.
    @value = new_value.to_s.encode(ENCODING_NAME[character_set], new_value.to_s.encoding.name)
    @bin = encode(@value)
  else
    # We may have an array (of numbers) which needs to be passed directly to
    # the encode method instead of being forced into a numerical:
    if new_value.is_a?(Array)
      @value = new_value
      @bin = encode(@value)
    else
      @value = new_value.send(VALUE_CONVERSION[@vr])
      @bin = encode(@value)
    end
  end
  @length = @bin.length
end

Private Instance Methods

encode(formatted_value) click to toggle source

Encodes a formatted value to a binary string.

@param [String, Integer, Float, Array] formatted_value a formatted value @return [String] the encoded, binary string

# File lib/dicom/element.rb, line 265
def encode(formatted_value)
  stream.encode_value(formatted_value, @vr)
end
state() click to toggle source

Collects the attributes of this instance.

@return [Array<String>] an array of attributes

# File lib/dicom/element.rb, line 273
def state
  [@tag, @vr, @value, @bin]
end