class DICOM::ImageItem
Super class which contains common code for both the DObject
and Item
classes. This class includes the image related methods, since images may be stored either directly in the DObject
, or in items (encapsulated items in the “Pixel Data” element or in “Icon Image Sequence” items).
Inheritance¶ ↑
As the ImageItem
class inherits from the Parent
class, all Parent
methods are also available to objects which has inherited ImageItem
.
Public Instance Methods
Creates an Element
with the given arguments and connects it to self.
@param [String] tag an element tag @param [String, Integer, Float, Array
, NilClass] value an element value @param [Hash] options any options used for creating the element (see Element.new
documentation)
# File lib/dicom/image_item.rb, line 23 def add_element(tag, value, options={}) add(e = Element.new(tag, value, options)) e end
Creates a Sequence
with the given arguments and connects it to self.
@param [String] tag a sequence tag @param [Hash] options any options used for creating the sequence (see Sequence.new
documentation)
# File lib/dicom/image_item.rb, line 33 def add_sequence(tag, options={}) add(s = Sequence.new(tag, options)) s end
Checks if colored pixel data is present.
@return [Boolean] true if the object contains colored pixels, and false if not
# File lib/dicom/image_item.rb, line 42 def color? # "Photometric Interpretation" is contained in the data element "0028,0004": begin photometric = photometry if photometric.include?('COLOR') or photometric.include?('RGB') or photometric.include?('YBR') return true else return false end rescue return false end end
Checks if compressed pixel data is present.
@return [Boolean] true if the object contains compressed pixels, and false if not
# File lib/dicom/image_item.rb, line 60 def compression? # If compression is used, the pixel data element is a Sequence (with encapsulated elements), instead of a Element: if self[PIXEL_TAG].is_a?(Sequence) return true else return false end end
Unpacks pixel values from a binary pixel string. The decode is performed using values defined in the image related elements of the DObject
instance.
@param [String] bin a binary string containing the pixels to be decoded @param [Stream] stream a Stream
instance to be used for decoding the pixels (optional) @return [Array<Integer>] decoded pixel values
# File lib/dicom/image_item.rb, line 76 def decode_pixels(bin, stream=@stream) raise ArgumentError, "Expected String, got #{bin.class}." unless bin.is_a?(String) pixels = false # We need to know what kind of bith depth and integer type the pixel data is saved with: bit_depth_element = self['0028,0100'] pixel_representation_element = self['0028,0103'] if bit_depth_element and pixel_representation_element # Load the binary pixel data to the Stream instance: stream.set_string(bin) template = template_string(bit_depth_element.value.to_i) pixels = stream.decode_all(template) if template else raise "The Element specifying Bit Depth (0028,0100) is missing. Unable to decode pixel data." unless bit_depth_element raise "The Element specifying Pixel Representation (0028,0103) is missing. Unable to decode pixel data." unless pixel_representation_element end return pixels end
Packs a pixel value array to a binary pixel string. The encoding is performed using values defined in the image related elements of the DObject
instance.
@param [Array<Integer>] pixels an array containing the pixel values to be encoded @param [Stream] stream a Stream
instance to be used for encoding the pixels (optional) @return [String] encoded pixel string
# File lib/dicom/image_item.rb, line 101 def encode_pixels(pixels, stream=@stream) raise ArgumentError, "Expected Array, got #{pixels.class}." unless pixels.is_a?(Array) bin = false # We need to know what kind of bith depth and integer type the pixel data is saved with: bit_depth_element = self['0028,0100'] pixel_representation_element = self['0028,0103'] if bit_depth_element and pixel_representation_element template = template_string(bit_depth_element.value.to_i) bin = stream.encode(pixels, template) if template else raise "The Element specifying Bit Depth (0028,0100) is missing. Unable to encode the pixel data." unless bit_depth_element raise "The Element specifying Pixel Representation (0028,0103) is missing. Unable to encode the pixel data." unless pixel_representation_element end return bin end
Extracts a single image object, created from the encoded pixel data using the image related elements in the DICOM
object. If the object contains multiple image frames, the first image frame is returned, unless the :frame option is used.
@note Creates an image object in accordance with the selected image processor. Available processors are :rmagick and :mini_magick.
@param [Hash] options the options to use for extracting the image @option options [Integer] :frame for DICOM
objects containing multiple frames, this option can be used to extract a specific image frame (defaults to 0) @option options [TrueClass, Array
<Integer>] :level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @option options [Boolean] :narray if true, forces the use of NArray for the pixel remap process (for faster execution) @option options [Boolean] :remap if true, the returned pixel values are remapped to presentation values @return [MagickImage, NilClass, FalseClass] an image object, alternatively nil (if no image present) or false (if image decode failed)
@example Retrieve pixel data as an RMagick image object and display it
image = dcm.image image.display
@example Retrieve frame index 5 in the pixel data
image = dcm.image(:frame => 5)
# File lib/dicom/image_item.rb, line 136 def image(options={}) options[:frame] = options[:frame] || 0 image = images(options).first image = false if image.nil? && exists?(PIXEL_TAG) return image end
Encodes pixel data from a (Magick) image object and writes it to the pixel data element (7FE0,0010).
Because of pixel value issues related to image objects (images don't like signed integers), and the possible difference between presentation values and raw pixel values, the use of image=() may result in pixel data where the integer values differs somewhat from what is expected. Use with care! For precise pixel value processing, use the Array
and NArray based pixel data methods instead.
@param [MagickImage] image the image to be assigned to the pixel data element
# File lib/dicom/image_item.rb, line 286 def image=(image) raise ArgumentError, "Expected one of the supported image classes: #{valid_image_objects} (got #{image.class})" unless valid_image_objects.include?(image.class.to_s) # Export to pixels using the proper image processor: pixels = export_pixels(image, photometry) # Encode and write to the Pixel Data Element: self.pixels = pixels end
Reads a binary string from a specified file and writes it to the value field of the pixel data element (7FE0,0010).
@param [String] file a string which specifies the path of the file containing pixel data
@example Load pixel data from a file
dcm.image_from_file("custom_image.dat")
# File lib/dicom/image_item.rb, line 207 def image_from_file(file) raise ArgumentError, "Expected #{String}, got #{file.class}." unless file.is_a?(String) f = File.new(file, 'rb') bin = f.read(f.stat.size) if bin.length > 0 # Write the binary data to the Pixel Data Element: write_pixels(bin) else logger.info("The specified file (#{file}) is empty. Nothing to transfer.") end end
Extracts the pixel data binary string(s) in an array.
@param [Boolean] split if true, a pixel data string containing 3D volumetric data will be split into N substrings (where N equals the number of frames) @return [Array<String, NilClass>] an array of pixel data strings, or an empty array (if no pixel data present)
# File lib/dicom/image_item.rb, line 224 def image_strings(split=false) # Pixel data may be a single binary string in the pixel data element, # or located in several encapsulated item elements: pixel_element = self[PIXEL_TAG] strings = Array.new if pixel_element.is_a?(Element) if split strings = pixel_element.bin.dup.divide(num_frames) else strings << pixel_element.bin end elsif pixel_element.is_a?(Sequence) pixel_items = pixel_element.children.first.children pixel_items.each {|item| strings << item.bin} end return strings end
Dumps the binary content of the Pixel Data element to the specified file.
If the DICOM
object contains multi-fragment pixel data, each fragment will be dumped to separate files (e.q. 'fragment-0.dat', 'fragment-1.dat').
@param [String] file a string which specifies the file path to use when dumping the pixel data @example Dumping the pixel data to a file
dcm.image_to_file("exported_image.dat")
# File lib/dicom/image_item.rb, line 251 def image_to_file(file) raise ArgumentError, "Expected #{String}, got #{file.class}." unless file.is_a?(String) # Split the file name in case of multiple fragments: parts = file.split('.') if parts.length > 1 base = parts[0..-2].join extension = '.' + parts.last else base = file extension = '' end # Get the binary image strings and dump them to the file(s): images = image_strings images.each_index do |i| if images.length == 1 f = File.new(file, 'wb') else f = File.new("#{base}-#{i}#{extension}", 'wb') end f.write(images[i]) f.close end end
Extracts an array of image objects, created from the encoded pixel data using the image related elements in the DICOM
object.
@note Creates an array of image objects in accordance with the selected image processor. Available processors are :rmagick and :mini_magick.
@param [Hash] options the options to use for extracting the images @option options [Integer] :frame makes the method return an array containing only the image object corresponding to the specified frame number @option options [TrueClass, Array
<Integer>] :level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @option options [Boolean] :narray if true, forces the use of NArray for the pixel remap process (for faster execution) @option options [Boolean] :remap if true, the returned pixel values are remapped to presentation values @return [Array<MagickImage, NilClass>] an array of image objects, alternatively an empty array (if no image present or image decode failed)
@example Retrieve the pixel data as RMagick image objects
images = dcm.images
@example Retrieve the pixel data as RMagick image objects, remapped to presentation values (but without any leveling)
images = dcm.images(:remap => true)
@example Retrieve the pixel data as RMagick image objects, remapped to presentation values and leveled using the default center/width values in the DICOM
object
images = dcm.images(:level => true)
@example Retrieve the pixel data as RMagick image objects, remapped to presentation values, leveled with the specified center/width values and using numerical array for the rescaling (~twice as fast)
images = dcm.images(:level => [-200,1000], :narray => true)
# File lib/dicom/image_item.rb, line 164 def images(options={}) images = Array.new if exists?(PIXEL_TAG) # Gather the pixel data strings, and pick a single frame if indicated by options: strings = image_strings(split_to_frames=true) strings = [strings[options[:frame]]] if options[:frame] if compression? # Decompress, either to numbers (RLE) or to an image object (image based compressions): if [TXS_RLE].include?(transfer_syntax) pixel_frames = Array.new strings.each {|string| pixel_frames << decode_rle(num_cols, num_rows, string)} else images = decompress(strings) || Array.new logger.warn("Decompressing pixel values has failed (unsupported transfer syntax: '#{transfer_syntax}' - #{LIBRARY.uid(transfer_syntax) ? LIBRARY.uid(transfer_syntax).name : 'Unknown transfer syntax!'})") unless images.length > 0 end else # Uncompressed: Decode to numbers. pixel_frames = Array.new strings.each {|string| pixel_frames << decode_pixels(string)} end if pixel_frames images = Array.new pixel_frames.each do |pixels| # Pixel values and pixel order may need to be rearranged if we have color data: pixels = process_colors(pixels) if color? if pixels images << read_image(pixels, num_cols, num_rows, options) else logger.warn("Processing pixel values for this particular color mode failed, unable to construct image(s).") end end end end return images end
Creates an NArray containing the pixel data. If the pixel data is an image (single frame), a 2-dimensional NArray is returned [columns, rows]. If the pixel data is 3-dimensional (more than one frame), a 3-dimensional NArray is returned [frames, columns, rows].
@note To call this method you need to have loaded the NArray library in advance (require 'narray').
@param [Hash] options the options to use for extracting the pixel data @option options [TrueClass, Array
<Integer>] :level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @option options [Boolean] :remap if true, the returned pixel values are remapped to presentation values @option options [Boolean] :volume if true, the returned array will always be 3-dimensional, even if the pixel data only has one frame @return [NArray, NilClass, FalseClass] an NArray of pixel values, alternatively nil (if no image present) or false (if image decode failed)
@example Retrieve numerical pixel array
data = dcm.narray
@example Retrieve numerical pixel array remapped from the original pixel values to presentation values
data = dcm.narray(:remap => true)
# File lib/dicom/image_item.rb, line 337 def narray(options={}) pixels = nil if exists?(PIXEL_TAG) unless color? # Decode the pixel values: For now we only support returning pixel data of the first frame (if the image is located in multiple pixel data items). if compression? pixels = decompress(image_strings.first) else pixels = decode_pixels(image_strings.first) end if pixels # Import the pixels to NArray and give it a proper shape: raise "Missing Rows and/or Columns Element. Unable to construct pixel data array." unless num_rows and num_cols if num_frames > 1 or options[:volume] # Create an empty 3D NArray. fill it with pixels frame by frame, then reassign the pixels variable to it: narr = Numo::Int16.zeros(num_frames, num_cols, num_rows) num_frames.times do |i| narr[i, true, true] = Numo::NArray[*pixels[(i * num_cols * num_rows)..((i + 1) * num_cols * num_rows - 1)]].reshape!(num_cols, num_rows) end pixels = narr else pixels = Numo::NArray[*pixels].reshape!(num_cols, num_rows) end # Remap the image from pixel values to presentation values if the user has requested this: pixels = process_presentation_values_narray(pixels, -65535, 65535, options[:level]) if options[:remap] or options[:level] else logger.warn("Decompressing the Pixel Data failed. Pixel values can not be extracted.") end else logger.warn("The DICOM object contains colored pixel data. Retrieval of colored pixels is not supported by this method yet.") pixels = false end end return pixels end
Gives the number of columns in the pixel data.
@return [Integer, NilClass] the number of columns, or nil (if the columns value is undefined)
# File lib/dicom/image_item.rb, line 298 def num_cols self['0028,0011'].value rescue nil end
Gives the number of frames in the pixel data.
@note Assumes and gives 1 if the number of frames value is not defined. @return [Integer] the number of rows
# File lib/dicom/image_item.rb, line 307 def num_frames (self['0028,0008'].is_a?(Element) == true ? self['0028,0008'].value.to_i : 1) end
Gives the number of rows in the pixel data.
@return [Integer, NilClass] the number of rows, or nil (if the rows value is undefined)
# File lib/dicom/image_item.rb, line 315 def num_rows self['0028,0010'].value rescue nil end
Extracts the Pixel Data values in an ordinary Ruby Array
. Returns nil if no pixel data is present, and false if it fails to retrieve pixel data which is present.
The returned array does not carry the dimensions of the pixel data: It is put in a one dimensional Array
(vector).
@param [Hash] options the options to use for extracting the pixel data @option options [TrueClass, Array
<Integer>] :level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @option options [Boolean] :narray if true, forces the use of NArray for the pixel remap process (for faster execution) @option options [Boolean] :remap if true, the returned pixel values are remapped to presentation values @return [Array, NilClass, FalseClass] an Array
of pixel values, alternatively nil (if no image present) or false (if image decode failed)
@example Simply retrieve the pixel data
pixels = dcm.pixels
@example Retrieve the pixel data remapped to presentation values according to window center/width settings
pixels = dcm.pixels(:remap => true)
@example Retrieve the remapped pixel data while using numerical array (~twice as fast)
pixels = dcm.pixels(:remap => true, :narray => true)
# File lib/dicom/image_item.rb, line 392 def pixels(options={}) pixels = nil if exists?(PIXEL_TAG) # For now we only support returning pixel data of the first frame, if the image is located in multiple pixel data items: if compression? pixels = decompress(image_strings.first) else pixels = decode_pixels(image_strings.first) end if pixels # Remap the image from pixel values to presentation values if the user has requested this: if options[:remap] or options[:level] if options[:narray] # Use numerical array (faster): pixels = process_presentation_values_narray(pixels, -65535, 65535, options[:level]).to_a else # Use standard Ruby array (slower): pixels = process_presentation_values(pixels, -65535, 65535, options[:level]) end end else logger.warn("Decompressing the Pixel Data failed. Pixel values can not be extracted.") end end return pixels end
Encodes pixel data from a Ruby Array
or NArray, and writes it to the pixel data element (7FE0,0010).
@param [Array<Integer>, NArray] values an Array
(or NArray) containing integer pixel values
# File lib/dicom/image_item.rb, line 423 def pixels=(values) raise ArgumentError, "The given argument does not respond to #to_a (got an argument of class #{values.class})" unless values.respond_to?(:to_a) if values.class.ancestors.to_s.include?('NArray') # With an NArray argument, make sure that it gets properly converted to an Array: if values.shape.length > 2 # For a 3D NArray we need to rearrange to ensure that the pixels get their # proper order when converting to an ordinary Array instance: narr = NArray.int(values.shape[1] * values.shape[2], values.shape[0]) values.shape[0].times do |i| narr[true, i] = values[i, true, true].reshape(values.shape[1] * values.shape[2]) end values = narr end end # Encode the pixel data: bin = encode_pixels(values.to_a.flatten) # Write the binary data to the Pixel Data Element: write_pixels(bin) end
Private Instance Methods
Gives the effective bit depth of the pixel data (considers a special case for Palette colored images).
@raise [RuntimeError] if the 'Bits Allocated' element is missing @return [Integer] the effective bit depth of the pixel data
# File lib/dicom/image_item.rb, line 461 def actual_bit_depth raise "The 'Bits Allocated' Element is missing from this DICOM instance. Unable to encode/decode pixel data." unless exists?("0028,0100") if photometry == PI_PALETTE_COLOR # Only one channel is checked and it is assumed that all channels have the same number of bits. return self['0028,1101'].value.split("\\").last.to_i else return bit_depth end end
Gives the value from the “Bits Allocated” Element
.
@raise [RuntimeError] if the 'Bits Allocated' element is missing @return [Integer] the number of bits allocated
# File lib/dicom/image_item.rb, line 477 def bit_depth raise "The 'Bits Allocated' Element is missing from this DICOM instance. Unable to encode/decode pixel data." unless exists?("0028,0100") return value('0028,0100') end
Performs a run length decoding on the input stream.
@note For details on RLE encoding, refer to the DICOM
standard, PS3.5, Section 8.2.2 as well as Annex G.
@param [Integer] cols number of colums of the encoded image @param [Integer] rows number of rows of the encoded image @param [Integer] string the encoded pixel string @return [Array<Integer>] the decoded pixel values
# File lib/dicom/image_item.rb, line 491 def decode_rle(cols, rows, string) # FIXME: Remove cols and rows (were only added for debugging). pixels = Array.new # RLE header specifying the number of segments: header = string[0...64].unpack('L*') image_segments = Array.new # Extracting all start and endpoints of the different segments: header.each_index do |n| if n == 0 # This one need no processing. elsif n == header[0] # It's the last one image_segments << [header[n], -1] break else image_segments << [header[n], header[n + 1] - 1] end end # Iterate over each segment and extract pixel data: image_segments.each do |range| segment_data = Array.new next_bytes = -1 next_multiplier = 0 # Iterate this segment's pixel string: string[range[0]..range[1]].each_byte do |b| if next_multiplier > 0 next_multiplier.times { segment_data << b } next_multiplier = 0 elsif next_bytes > 0 segment_data << b next_bytes -= 1 elsif b <= 127 next_bytes = b + 1 else # Explaining the 257 at this point is a little bit complicate. Basically it has something # to do with the algorithm described in the DICOM standard and that the value -1 as uint8 is 255. # TODO: Is this architectur safe or does it only work on Intel systems??? next_multiplier = 257 - b end end # Verify that the RLE decoding has executed properly: throw "Size mismatch #{segment_data.size} != #{rows * cols}" if segment_data.size != rows * cols pixels += segment_data end return pixels end
Gives the value from the “Photometric Interpretation” Element
.
@raise [RuntimeError] if the 'Photometric Interpretation' element is missing @return [String] the photometric interpretation
# File lib/dicom/image_item.rb, line 543 def photometry raise "The 'Photometric Interpretation' Element is missing from this DICOM instance. Unable to encode/decode pixel data." unless exists?("0028,0004") return value('0028,0004').upcase end
Processes the pixel array based on attributes defined in the DICOM object,
to produce a pixel array with correct pixel colors (RGB) as well as pixel
order (RGB-pixel1, RGB-pixel2, etc). The relevant DICOM tags are Photometric Interpretation (0028,0004) and Planar Configuration (0028,0006). @param [Array<Integer>] pixels an array of (unsorted) color pixel values @return [Array<Integer>] an array of properly (sorted) color pixel values
# File lib/dicom/image_item.rb, line 556 def process_colors(pixels) proper_rgb = false photometric = photometry() # (With RLE COLOR PALETTE the Planar Configuration is not set) planar = self['0028,0006'].is_a?(Element) ? self['0028,0006'].value : 0 # Step 1: Produce an array with RGB values. At this time, YBR is not supported in ruby-dicom, # so this leaves us with a possible conversion from PALETTE COLOR: if photometric.include?('COLOR') # Pseudo colors (rgb values grabbed from a lookup table): rgb = Array.new(pixels.length*3) # Prepare the lookup data arrays: lookup_binaries = [self['0028,1201'].bin, self['0028,1202'].bin, self['0028,1203'].bin] lookup_values = Array.new nr_bits = self['0028,1101'].value.split("\\").last.to_i template = template_string(nr_bits) lookup_binaries.each do |bin| stream.set_string(bin) lookup_values << stream.decode_all(template) end lookup_values = lookup_values.transpose # Fill the RGB array, one RGB pixel group (3 pixels) at a time: pixels.each_index do |i| rgb[i*3, 3] = lookup_values[pixels[i]] end # As we have now ordered the pixels in RGB order, modify planar configuration to reflect this: planar = 0 elsif photometric.include?('YBR') rgb = false else rgb = pixels end # Step 2: If indicated by the planar configuration, the order of the pixels need to be rearranged: if rgb if planar == 1 # Rearrange from [RRR...GGG....BBB...] to [(RGB)(RGB)(RGB)...]: r_ind = [rgb.length/3-1, rgb.length*2/3-1, rgb.length-1] l_ind = [0, rgb.length/3, rgb.length*2/3] proper_rgb = [rgb[l_ind[0]..r_ind[0]], rgb[l_ind[1]..r_ind[1]], rgb[l_ind[2]..r_ind[2]]].transpose.flatten else proper_rgb = rgb end end return proper_rgb end
Converts original pixel data values to presentation values.
@param [Array<Integer>] pixel_data an array of pixel values (integers) @param [Integer] min_allowed the minimum value allowed in the pixel data @param [Integer] max_allowed the maximum value allowed in the pixel data @param [Boolean, Array
<Integer>] level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @return [Array<Integer>] presentation values
# File lib/dicom/image_item.rb, line 609 def process_presentation_values(pixel_data, min_allowed, max_allowed, level=nil) # Process pixel data for presentation according to the image information in the DICOM object: center, width, intercept, slope = window_level_values # Have image leveling been requested? if level # If custom values are specified in an array, use those. If not, the default values from the DICOM object are used: if level.is_a?(Array) center = level[0] width = level[1] end else center, width = false, false end # PixelOutput = slope * pixel_values + intercept if intercept != 0 or slope != 1 pixel_data.collect!{|x| (slope * x) + intercept} end # Contrast enhancement by black and white thresholding: if center and width low = center - width/2 high = center + width/2 pixel_data.each_index do |i| if pixel_data[i] < low pixel_data[i] = low elsif pixel_data[i] > high pixel_data[i] = high end end end # Need to introduce an offset? min_pixel_value = pixel_data.min if min_allowed if min_pixel_value < min_allowed offset = min_pixel_value.abs pixel_data.collect!{|x| x + offset} end end # Downscale pixel range? max_pixel_value = pixel_data.max if max_allowed if max_pixel_value > max_allowed factor = (max_pixel_value.to_f/max_allowed.to_f).ceil pixel_data.collect!{|x| x / factor} end end return pixel_data end
Converts original pixel data values to presentation values, using the efficient NArray library.
@note If a Ruby Array
is supplied, the method returns a one-dimensional NArray object (i.e. no columns & rows). @note If a NArray is supplied, the NArray is returned with its original dimensions.
@param [Array<Integer>, NArray] pixel_data pixel values @param [Integer] min_allowed the minimum value allowed in the pixel data @param [Integer] max_allowed the maximum value allowed in the pixel data @param [Boolean, Array
<Integer>] level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @return [Array<Integer>, NArray] presentation values
# File lib/dicom/image_item.rb, line 668 def process_presentation_values_narray(pixel_data, min_allowed, max_allowed, level=nil) # Process pixel data for presentation according to the image information in the DICOM object: center, width, intercept, slope = window_level_values # Have image leveling been requested? if level # If custom values are specified in an array, use those. If not, the default values from the DICOM object are used: if level.is_a?(Array) center = level[0] width = level[1] end else center, width = false, false end # Need to convert to NArray? if pixel_data.is_a?(Array) n_arr = Numo::NArray[*pixel_data] else n_arr = pixel_data end # Remap: # PixelOutput = slope * pixel_values + intercept if intercept != 0 or slope != 1 n_arr = slope * n_arr + intercept end # Contrast enhancement by black and white thresholding: if center and width low = center - width/2 high = center + width/2 n_arr[n_arr < low] = low n_arr[n_arr > high] = high end # Need to introduce an offset? min_pixel_value = n_arr.min if min_allowed if min_pixel_value < min_allowed offset = min_pixel_value.abs n_arr = n_arr + offset end end # Downscale pixel range? max_pixel_value = n_arr.max if max_allowed if max_pixel_value > max_allowed factor = (max_pixel_value.to_f/max_allowed.to_f).ceil n_arr = n_arr / factor end end return n_arr end
Creates an image object from the specified pixel value array, performing presentation value processing if requested.
@note Definitions for Window Center and Width can be found in the DICOM
standard, PS 3.3 C.11.2.1.2
@param [Array<Integer>] pixel_data an array of pixel values @param [Integer] columns the number of columns in the pixel data @param [Integer] rows the number of rows in the pixel data @param [Hash] options the options to use for reading the image @option options [Boolean] :remap if true, pixel values are remapped to presentation values (using intercept and slope values from the DICOM
object) @option options [Boolean, Array
<Integer>] :level if true, window leveling is performed using default values from the DICOM
object, or if an array ([center, width]) is specified, these custom values are used instead @option options [Boolean] :narray if true, forces the use of NArray for the pixel remap process (for faster execution) @return [MagickImage] the extracted image object
# File lib/dicom/image_item.rb, line 732 def read_image(pixel_data, columns, rows, options={}) raise ArgumentError, "Expected Array for pixel_data, got #{pixel_data.class}" unless pixel_data.is_a?(Array) raise ArgumentError, "Expected Integer for columns, got #{columns.class}" unless columns.is_a?(Integer) raise ArgumentError, "Expected Rows for columns, got #{rows.class}" unless rows.is_a?(Integer) raise ArgumentError, "Size of pixel_data must be at least equal to columns*rows. Got #{columns}*#{rows}=#{columns*rows}, which is less than the array size #{pixel_data.length}" if columns * rows > pixel_data.length # Remap the image from pixel values to presentation values if the user has requested this: if options[:remap] or options[:level] # How to perform the remapping? NArray (fast) or Ruby Array (slow)? if options[:narray] == true pixel_data = process_presentation_values_narray(pixel_data, 0, 65535, options[:level]).to_a else pixel_data = process_presentation_values(pixel_data, 0, 65535, options[:level]) end else # No remapping, but make sure that we pass on unsigned pixel values to the image processor: pixel_data = pixel_data.to_unsigned(bit_depth) if signed_pixels? end image = import_pixels(pixel_data.to_blob(actual_bit_depth), columns, rows, actual_bit_depth, photometry) return image end
Checks if the Pixel Representation indicates signed pixel values or not.
@raise [RuntimeError] if the 'Pixel Representation' element is missing @return [Boolean] true if pixel values are signed, false if not
# File lib/dicom/image_item.rb, line 758 def signed_pixels? raise "The 'Pixel Representation' data element is missing from this DICOM instance. Unable to process pixel data." unless exists?("0028,0103") case value('0028,0103') when 1 return true when 0 return false else raise "Invalid value encountered (#{value('0028,0103')}) in the 'Pixel Representation' data element. Expected 0 or 1." end end
Determines the template/format string for pack/unpacking pixel data, based on the number of bits per pixel as well as the pixel representation (signed or unsigned).
@param [Integer] depth the number of allocated bits in the integers to be decoded/encoded @return [String] a format string
# File lib/dicom/image_item.rb, line 776 def template_string(depth) template = false pixel_representation = self['0028,0103'].value.to_i # Number of bytes used per pixel will determine how to unpack this: case depth when 8 # (1 byte) template = 'BY' # Byte/Character/Integer when 16 # (2 bytes) if pixel_representation == 1 template = 'SS' # Signed short else template = 'US' # Unsigned short end when 32 # (4 bytes) if pixel_representation == 1 template = 'SL' # Signed long else template = 'UL' # Unsigned long end when 12 # 12 BIT SIMPLY NOT IMPLEMENTED YET! # This one is a bit tricky. I havent really given this priority so far as 12 bit image data is rather rare. raise "Packing/unpacking pixel data of bit depth 12 is not implemented yet! Please contact the author (or edit the source code)." else raise ArgumentError, "Encoding/Decoding pixel data with this Bit Depth (#{depth}) is not implemented." end return template end
Collects the window level values needed to convert the original pixel values to presentation values.
@note If some of these values are missing in the DObject
instance,
default values are used instead for intercept and slope, while center and width are set to nil. No errors are raised.
@return [Array<Integer, NilClass>] center, width, intercept and slope
# File lib/dicom/image_item.rb, line 813 def window_level_values center = (self['0028,1050'].is_a?(Element) == true ? self['0028,1050'].value.to_i : nil) width = (self['0028,1051'].is_a?(Element) == true ? self['0028,1051'].value.to_i : nil) intercept = (self['0028,1052'].is_a?(Element) == true ? self['0028,1052'].value.to_i : 0) slope = (self['0028,1053'].is_a?(Element) == true ? self['0028,1053'].value.to_i : 1) return center, width, intercept, slope end
Transfers a pre-encoded binary string to the pixel data element, either by overwriting the existing element value, or creating a new “Pixel Data” element.
@param [String] bin a binary string containing encoded pixel data
# File lib/dicom/image_item.rb, line 826 def write_pixels(bin) if self.exists?(PIXEL_TAG) # Update existing Data Element: self[PIXEL_TAG].bin = bin else # Create new Data Element: pixel_element = Element.new(PIXEL_TAG, bin, :encoded => true, :parent => self) end end