Class: DICOM::Item

Inherits:
ImageItem show all
Includes:
Elemental
Defined in:
lib/dicom/item.rb

Overview

The Item class handles information related to items - the elements contained in sequences.

Inheritance

As the Item class inherits from the ImageItem class, which itself inherits from the Parent class, all ImageItem and Parent methods are also available to instances of Item.

Instance Attribute Summary collapse

Attributes included from Elemental

#bin, #length, #name, #parent, #tag, #vr

Instance Method Summary collapse

Methods included from Elemental

#name_as_method, #parents, #set_parent, #stream, #top_parent

Methods inherited from ImageItem

#add_element, #add_sequence, #color?, #compression?, #decode_pixels, #delete_sequences, #encode_pixels, #image, #image=, #image_from_file, #image_strings, #image_to_file, #images, #narray, #num_cols, #num_frames, #num_rows, #pixels, #pixels=

Methods included from ImageProcessor

#decompress, #export_pixels, #import_pixels, #valid_image_objects

Methods inherited from Parent

#[], #add, #add_item, #children, #children?, #count, #count_all, #delete, #delete_children, #delete_group, #delete_private, #delete_retired, #each, #each_element, #each_item, #each_sequence, #each_tag, #elements, #elements?, #encode_children, #exists?, #group, #handle_print, #inspect, #is_parent?, #items, #items?, #length=, #max_lengths, #method_missing, #print, #reset_length, #respond_to?, #sequences, #sequences?, #to_hash, #to_json, #to_yaml, #value

Methods included from Logging

included, #logger

Constructor Details

#initialize(options = {}) ⇒ Item

Creates an Item instance.

Normally, an Item contains data elements and/or sequences. However, in some cases, an Item will instead/also carry binary string data, like the pixel data of an encapsulated image fragment.

Examples:

Create an empty Item and connect it to the “Structure Set ROI Sequence”

item = Item.new(:parent => dcm["3006,0020"])

Create a “Pixel Data Item” which carries an encapsulated image frame (a pre-encoded binary)

pixel_item = Item.new(:bin => processed_pixel_data, :parent => dcm["7FE0,0010"][1])

Parameters:

  • options (Hash) (defaults to: {})

    the options to use for creating the item

Options Hash (options):

  • :bin (String)

    a binary string to be carried by the item

  • :indexif (String)

    the item is to be inserted at a specific index (Item number), this option parameter needs to set

  • :length (String)

    theiItem length (which either refers to the length of the encoded string of children of this item, or the length of its binary data)

  • :name (String)

    the name of the item may be specified upon creation (if not, a default name is used)

  • :parent (String)

    a Sequence or DObject instance which the item instance shall belong to

  • :vr (String)

    the value representation of the item may be specified upon creation (if not, a default vr is used)



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# File 'lib/dicom/item.rb', line 37

def initialize(options={})
  # Set common parent variables:
  initialize_parent
  # Set instance variables:
  @tag = ITEM_TAG
  @value = nil
  @name = options[:name] || "Item"
  @vr = options[:vr] || ITEM_VR
  if options[:bin]
    self.bin = options[:bin]
  else
    @length = options[:length] || -1
  end
  if options[:parent]
    @parent = options[:parent]
    @index = options[:index] if options[:index]
    @parent.add_item(self, :index => options[:index], :no_follow => true)
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class DICOM::Parent

Instance Attribute Details

#indexObject

The index of this Item in the group of items belonging to its parent. If the Item is without parent, index is nil.



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

def index
  @index
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Checks for equality.

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

Parameters:

  • other

    an object to be compared with self.

Returns:

  • (Boolean)

    true if self and other are considered equivalent



65
66
67
68
69
# File 'lib/dicom/item.rb', line 65

def ==(other)
  if other.respond_to?(:to_item)
    other.send(:state) == state
  end
end

#bin=(new_bin) ⇒ Object

Sets the binary string that the Item will contain.

Examples:

Insert a custom jpeg in the (encapsulated) pixel data element (in it’s first pixel data item)

dcm['7FE0,0010'][1].children.first.bin = jpeg_binary_string

Parameters:

  • new_bin (String)

    a binary string of encoded data

Raises:

  • (ArgumentError)


79
80
81
82
83
84
85
86
87
88
89
# File 'lib/dicom/item.rb', line 79

def bin=(new_bin)
  raise ArgumentError, "Invalid parameter type. String was expected, got #{new_bin.class}." unless new_bin.is_a?(String)
  # Add an empty byte at the end if the length of the binary is odd:
  if new_bin.length.odd?
    @bin = new_bin + "\x00"
  else
    @bin = new_bin
  end
  @value = nil
  @length = @bin.length
end

#hashFixnum

Note:

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

Computes a hash code for this object.

Returns:

  • (Fixnum)

    the object’s hash code



97
98
99
# File 'lib/dicom/item.rb', line 97

def hash
  state.hash
end

#parse(bin, syntax) ⇒ Object

Loads data from an encoded DICOM string and creates sequences and elements which are linked to this instance.

Parameters:

  • bin (String)

    an encoded binary string containing DICOM information

  • syntax (String)

    the transfer syntax to use when decoding the DICOM string

Raises:

  • (ArgumentError)


107
108
109
110
111
# File 'lib/dicom/item.rb', line 107

def parse(bin, syntax)
  raise ArgumentError, "Invalid argument 'bin'. Expected String, got #{bin.class}." unless bin.is_a?(String)
  raise ArgumentError, "Invalid argument 'syntax'. Expected String, got #{syntax.class}." unless syntax.is_a?(String)
  read(bin, signature=false, :syntax => syntax)
end

#to_itemItem

Returns self.

Returns:



117
118
119
# File 'lib/dicom/item.rb', line 117

def to_item
  self
end