Class: RTKIT::Study

Inherits:
Object
  • Object
show all
Defined in:
lib/rtkit/study.rb

Overview

Contains the DICOM data and methods related to a study.

Relations

  • A Study belongs to a Patient.

  • A Study has many Series instances.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(study_uid, patient, options = {}) ⇒ Study

Creates a new Study instance. The Study Instance UID string is used to uniquely identify a Study.

Parameters

  • study_uid – The Study Instance UID string.

  • patient – The Patient instance that this Study belongs to.

  • options – A hash of parameters.

Options

  • :date – String. The Study Date (DICOM tag ‘0008,0020’).

  • :time – String. The Study Time (DICOM tag ‘0008,0030’).

  • :description – String. The Study Description (DICOM tag ‘0008,1030’).

  • :id – String. The Study ID (DICOM tag ‘0020,0010’).

Raises:

  • (ArgumentError) 


65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/rtkit/study.rb', line 65

def initialize(study_uid, patient, options={})
  raise ArgumentError, "Invalid argument 'study_uid'. Expected String, got #{study_uid.class}." unless study_uid.is_a?(String)
  raise ArgumentError, "Invalid argument 'patient'. Expected Patient, got #{patient.class}." unless patient.is_a?(Patient)
  raise ArgumentError, "Invalid option ':date'. Expected String, got #{options[:date].class}." if options[:date] && !options[:date].is_a?(String)
  raise ArgumentError, "Invalid option ':time'. Expected String, got #{options[:time].class}." if options[:time] && !options[:time].is_a?(String)
  raise ArgumentError, "Invalid option ':description'. Expected String, got #{options[:description].class}." if options[:description] && !options[:description].is_a?(String)
  raise ArgumentError, "Invalid option ':id'. Expected String, got #{options[:id].class}." if options[:id] && !options[:id].is_a?(String)
  # Key attributes:
  @study_uid = study_uid
  @patient = patient
  # Default attributes:
  @image_series = Array.new
  @series = Array.new
  # A hash with the associated Series' UID as key and the instance of the Series that belongs to this Study as value:
  @associated_series = Hash.new
  @associated_iseries = Hash.new
  # Optional attributes:
  @date = options[:date]
  @time = options[:time]
  @description = options[:description]
  @id = options[:id]
  # Register ourselves with the patient:
  @patient.add_study(self)
end

Instance Attribute Details

#date ⇒ Object (readonly)

The Study Date.



13
14
15
 
# File 'lib/rtkit/study.rb', line 13

def date
  @date
end

#description ⇒ Object (readonly)

The Study Description.



15
16
17
 
# File 'lib/rtkit/study.rb', line 15

def description
  @description
end

#id ⇒ Object (readonly)

The Study ID.



17
18
19
 
# File 'lib/rtkit/study.rb', line 17

def id
  @id
end

#image_series ⇒ Object (readonly)

An array of ImageSeries references.



19
20
21
 
# File 'lib/rtkit/study.rb', line 19

def image_series
  @image_series
end

#patient ⇒ Object (readonly)

The Study’s Patient reference.



21
22
23
 
# File 'lib/rtkit/study.rb', line 21

def patient
  @patient
end

#series ⇒ Object (readonly)

An array of Series references.



23
24
25
 
# File 'lib/rtkit/study.rb', line 23

def series
  @series
end

#study_uid ⇒ Object (readonly)

The Study Instance UID.



25
26
27
 
# File 'lib/rtkit/study.rb', line 25

def study_uid
  @study_uid
end

#time ⇒ Object (readonly)

The Study Time.



27
28
29
 
# File 'lib/rtkit/study.rb', line 27

def time
  @time
end

Class Method Details

.load(dcm, patient) ⇒ Object

Creates a new Study instance by loading study information from the specified DICOM object. The Study’s UID string value is used to uniquely identify a study.

Parameters

  • dcm – An instance of a DICOM object (DICOM::DObject).

  • patient – The Patient instance that this Study belongs to.

Raises:

  • (ArgumentError) 


37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/rtkit/study.rb', line 37

def self.load(dcm, patient)
  raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
  raise ArgumentError, "Invalid argument 'patient'. Expected Patient, got #{patient.class}." unless patient.is_a?(Patient)
  uid = dcm.value(STUDY_UID)
  date = dcm.value(STUDY_DATE)
  time = dcm.value(STUDY_TIME)
  description = dcm.value(STUDY_DESCR)
  id = dcm.value(STUDY_ID)
  study = self.new(uid, patient, :date => date, :time => time, :description => description, :id => id)
  study.add(dcm)
  return study
end

Instance Method Details

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

Returns true if the argument is an instance with attributes equal to self.



123
124
125
126
127
 
# File 'lib/rtkit/study.rb', line 123

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

#add(dcm) ⇒ Object

Adds a DICOM object to the study, by adding it to an existing Series, or creating a new Series.

Raises:

  • (ArgumentError) 


93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/rtkit/study.rb', line 93

def add(dcm)
  raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
  existing_series = @associated_series[dcm.value(SERIES_UID)]
  if existing_series
    existing_series.add(dcm)
  else
    # New series (series subclass depends on modality):
    case dcm.value(MODALITY)
    when *IMAGE_SERIES
      # Create the ImageSeries:
      s = ImageSeries.load(dcm, self)
      @image_series << s
    when 'RTSTRUCT'
      s = StructureSet.load(dcm, self)
    when 'RTPLAN'
      s = Plan.load(dcm, self)
    when 'RTDOSE'
      s = RTDose.load(dcm, self)
    when 'RTIMAGE'
      s = RTImage.load(dcm, self)
    else
      raise ArgumentError, "Unexpected (unsupported) modality (#{dcm.value(MODALITY)})in Study#add()"
    end
    # Add the newly created series to this study:
    add_series(s)
  end
end

#add_series(series) ⇒ Object

Adds a Series to this Study.

– Note: At some time we may decide to allow only ImageSeries (i.e. excluding other kinds of series) to be attached to a study.

Raises:

  • (ArgumentError) 


137
138
139
140
141
142
143
144
 
# File 'lib/rtkit/study.rb', line 137

def add_series(series)
  raise ArgumentError, "Invalid argument 'series'. Expected Series, got #{series.class}." unless series.is_a?(Series)
  # Do not add it again if the series already belongs to this instance:
  @series << series unless @associated_series[series.uid]
  @image_series << series if series.is_a?(ImageSeries) && !@associated_series[series.uid]
  @associated_series[series.uid] = series
  @associated_iseries[series.uid] = series if series.is_a?(ImageSeries)
end

#fseries(*args) ⇒ Object

Returns the Series instance mathcing the specified unique identifier (if an argument is used). The unique identifier is either a Series Instance UID (for ImageSeries) or a SOP Instance UID (for other kinds). If a specified UID doesn’t match, nil is returned. If no argument is passed, the first Series instance associated with the Study is returned.

Parameters

  • uid – The Series’ unique identifier string.

Raises:

  • (ArgumentError) 


180
181
182
183
184
185
186
187
188
189
 
# File 'lib/rtkit/study.rb', line 180

def fseries(*args)
  raise ArgumentError, "Expected one or none arguments, got #{args.length}." unless [0, 1].include?(args.length)
  if args.length == 1
    raise ArgumentError, "Expected String (or nil), got #{args.first.class}." unless [String, NilClass].include?(args.first.class)
    return @associated_series[args.first]
  else
    # No argument used, therefore we return the first Series instance:
    return @series.first
  end
end

#hash ⇒ Object

Generates a Fixnum hash value for this instance.



148
149
150
 
# File 'lib/rtkit/study.rb', line 148

def hash
  state.hash
end

#iseries(*args) ⇒ Object

Returns the ImageSeries instance mathcing the specified Series Instance UID (if an argument is used). If a specified UID doesn’t match, nil is returned. If no argument is passed, the first ImageSeries instance associated with the Study is returned.

Parameters

  • uid – String. The value of the Series Instance UID element.

Raises:

  • (ArgumentError) 


160
161
162
163
164
165
166
167
168
169
 
# File 'lib/rtkit/study.rb', line 160

def iseries(*args)
  raise ArgumentError, "Expected one or none arguments, got #{args.length}." unless [0, 1].include?(args.length)
  if args.length == 1
    raise ArgumentError, "Expected String (or nil), got #{args.first.class}." unless [String, NilClass].include?(args.first.class)
    return @associated_iseries[args.first]
  else
    # No argument used, therefore we return the first ImageSeries instance:
    return @image_series.first
  end
end

#to_study ⇒ Object

Returns self.



193
194
195
 
# File 'lib/rtkit/study.rb', line 193

def to_study
  self
end

#uid ⇒ Object

Returns the unique identifier string, which for this class is the Study Instance UID.



199
200
201
 
# File 'lib/rtkit/study.rb', line 199

def uid
  return @study_uid
end