dicoms 1.0.0

data/lib/dicoms/transfer.rb

@@ -0,0 +1,339 @@
+class DicomS
+  # Base class for Transfer strategy classes that define how
+  # the values of DICOM pixels are scales to be used as image pixels
+  # or to be processed as data (generic presentation values).
+  #
+  # Different strategies determine how much of the original
+  # data dynamic range is preserved.
+  #
+  # All the Transfer-derived classes can pass an :output option to the base
+  # which changes output range limits from what is stored in the DICOM.
+  # Two values are supported:
+  #
+  # * :byte Output consist of single byte values (0-255)
+  # * :unsigned Output is always unsigned
+  #
+  # The method min_max(sequence) of each class returns the minimum and maximum
+  # values which are mapped to the output limits.
+  # These values may be raw or rescaled depending on the min_max_rescaled? method
+  #
+  class Transfer
+    USE_DATA = false
+
+    include Support
+    extend  Support
+
+    def initialize(options = {})
+      @output = options[:output]
+    end
+
+    # Remapped DICOM pixel values as an Image
+    def image(dicom, min, max)
+      assign_dicom_pixels dicom, pixels(dicom, min, max)
+      dicom.image
+    end
+
+    # Remapped DICOM pixel values as an NArray
+    def pixels(dicom, min, max)
+      processed_data(dicom, min, max)
+    end
+
+    def self.strategy(strategy, options = {})
+      if strategy.is_a?(Array) && options.empty?
+        strategy, options = strategy
+      end
+      return nil if strategy.nil?
+      case strategy.to_sym
+      when :fixed
+        strategy_class = FixedTransfer
+      when :window
+        strategy_class = WindowTransfer
+      when :first
+        strategy_class = FirstTransfer
+      when :global
+        strategy_class = GlobalTransfer
+      when :sample
+        strategy_class = SampleTransfer
+      when :identity
+        strategy_class = IdentityTransfer
+      else
+        raise "INVALID: #{strategy.inspect}"
+      end
+      strategy_class.new options
+    end
+
+    # absolute output limits of the range (raw, not rescaled)
+    def min_max_limits(dicom)
+      case @output
+      when :byte
+        [0, 255]
+      when :unsigned
+        min, max = Transfer.min_max_limits(dicom)
+        if min < 0
+          min = 0
+          max -= min
+        end
+        [min, max]
+      else
+        Transfer.min_max_limits(dicom)
+      end
+    end
+
+    def self.min_max_limits(dicom)
+      num_bits = dicom_bit_depth(dicom)
+      signed = dicom_signed?(dicom)
+      pixel_value_range(num_bits, signed)
+    end
+
+    FLOAT_MAPPING = true
+
+  end
+
+  # Apply window-clipping; also
+  # always apply rescale (remap)
+  class WindowTransfer < Transfer
+
+    def initialize(options = {})
+      @center = options[:center]
+      @width  = options[:width]
+      super options
+    end
+
+    def min_max(sequence)
+      # TODO: use options to sample/take first/take all?
+      dicom = sequence.first
+      data_range dicom
+    end
+
+    def min_max_rescaled?
+      true
+    end
+
+    def processed_data(dicom, min, max)
+      center = (min + max)/2
+      width = max - min
+      data = dicom_narray(dicom, level: [center, width])
+      map_to_output dicom, data, min, max
+    end
+
+    # def image(dicom, min, max)
+    #   center = (min + max)/2
+    #   width = max - min
+    #   dicom.image(level: [center, width]).normalize
+    # end
+
+    private
+
+    def map_to_output(dicom, data, min, max)
+      output_min, output_max = min_max_limits(dicom)
+      output_range = output_max - output_min
+      input_range  = max - min
+      float_arith = FLOAT_MAPPING || output_range < input_range
+      data_type = data.typecode
+      data = data.to_type(NArray::SFLOAT) if float_arith
+      data.sbt! min
+      data.mul! (output_range).to_f/(input_range)
+      data.add! output_min
+      data = data.to_type(data_type) if float_arith
+      data
+    end
+
+    def data_range(dicom)
+      if USE_DATA
+        if @center && @width
+          level = [@center, @width]
+        else
+          level = true
+        end
+        data = dicom_narray(dicom, level: level)
+        [data.min, data.max]
+      else
+        center = @center || dicom_window_center(dicom)
+        width  = @width  || dicom_window_width(dicom)
+        low = center - width/2
+        high = center + width/2
+        [low, high]
+      end
+    end
+
+  end
+
+  # These strategies
+  # have optional dropping of the lowest level (base),
+  # photometric rescaling, extension factor
+  # and map the minimum/maximum input values
+  # (determined by the particular strategy and files)
+  # to the minimum/maximum output levels (black/white)
+  #
+  # +:ignore_min+ is used to ignore the minimum level present in the data
+  # and look for the next minimum value. Usually the absolute minimum
+  # corresponds to parts of the image outside the registered area and has
+  # typically the value -2048 for CT images. The next minimum value
+  # usually corresponds to air and is what's taken as the image's minimum
+  # when this option is set to +true+.
+  #
+  class RangeTransfer < Transfer
+
+    def initialize(options = {})
+      options = { ignore_min: true }.merge(options)
+      @rescale = options[:rescale]
+      @ignore_min = options[:ignore_min]
+      @extension_factor = options[:extend] || 0.0
+      super options
+    end
+
+    def min_max(sequence)
+      v0 = minimum = maximum = nil
+      select_dicoms(sequence) do |d|
+        d_v0, d_min, d_max = data_range(d)
+        v0 ||= d_v0
+        minimum ||= d_min
+        maximum ||= d_max
+        v0 = d_v0 if v0 && d_v0 && v0 > d_v0
+        minimum = d_min if minimum > d_min
+        maximum = d_max if maximum < d_max
+      end
+      [minimum, maximum]
+    end
+
+    def min_max_rescaled?
+      @rescale
+    end
+
+    def processed_data(dicom, min, max)
+      output_min, output_max = min_max_limits(dicom)
+      output_range = output_max - output_min
+      input_range  = max - min
+      float_arith = FLOAT_MAPPING || output_range < input_range
+      data = dicom_narray(dicom, level: false, remap: @rescale)
+      data_type = data.typecode
+      data = data.to_type(NArray::SFLOAT) if float_arith
+      data.sbt! min
+      data.mul! output_range/input_range.to_f
+      data.add! output_min
+      data[data < output_min] = output_min
+      data[data > output_max] = output_max
+      data = data.to_type(data_type) if float_arith
+      data
+    end
+
+    private
+
+    def data_range(dicom)
+      data = dicom_narray(dicom, level: false, remap: @rescale)
+      base = nil
+      minimum = data.min
+      maximum = data.max
+      if @ignore_min
+        base = minimum
+        minimum  = (data[data > base].min)
+      end
+      if @extension_factor != 0
+        # extend the range
+        minimum, maximum = extend_data_range(@extension_factor, base, minimum, maximum)
+      end
+      [base, minimum, maximum]
+    end
+
+    def extend_data_range(k, base, minimum, maximum)
+      k += 1.0
+      c = (maximum + minimum)/2
+      minimum = (c + k*(minimum - c)).round
+      maximum = (c + k*(maximum - c)).round
+      if base
+        minimum = base + 1 if minimum <= base
+      end
+      [minimum, maximum]
+    end
+
+  end
+
+  class FixedTransfer < RangeTransfer
+
+    def initialize(options = {})
+      @fixed_min = options[:min] || -2048
+      @fixed_max = options[:max] || +2048
+      options[:ignore_min] = false
+      options[:extend] = nil
+      unless options.key?(:rescale)
+        options[:rescale] = true
+      end
+      super options
+    end
+
+    def min_max(sequence)
+      # TODO: set default min, max regarding dicom data type
+      [@fixed_min, @fixed_max]
+    end
+
+  end
+
+  class GlobalTransfer < RangeTransfer
+
+    private
+
+    def select_dicoms(sequence, &blk)
+      sequence.each &blk
+    end
+
+  end
+
+  class FirstTransfer < RangeTransfer
+
+    def initialize(options = {})
+      extend = options[:extend] || 0.3
+      super options.merge(extend: extend)
+    end
+
+    private
+
+    def select_dicoms(sequence, &blk)
+      blk[sequence.first] if sequence.size > 0
+    end
+
+  end
+
+  class SampleTransfer < RangeTransfer
+
+    def initialize(options = {})
+      @max_files = options[:max_files] || 8
+      super options
+    end
+
+    private
+
+    def select_dicoms(sequence, &blk)
+      n = [sequence.size, @max_files].min
+      (0...sequence.size).to_a.sample(n).sort.each do |i|
+        blk[sequence.dicom(i)]
+      end
+    end
+
+  end
+
+  # Preserve internal values.
+  # Can be used with the output: :unsinged option
+  # to convert signed values to unsinged.
+  class IdentityTransfer < FixedTransfer
+    def initialize(options = {})
+      super options
+    end
+
+    def min_max(sequence)
+      min_max_limits(sequence.first)
+    end
+
+    def map_to_output(dicom, data, min, max)
+      if @rescale
+        intercept = dicom_rescale_intercept(dicom)
+        slope = dicom_rescale_slope(dicom)
+        if slope != 1 || intercept != 0
+          return super
+        end
+      end
+      data = dicom_narray(dicom)
+      data.add! -min if min < 0
+      data
+    end
+  end
+end

data/lib/dicoms/unpack.rb

@@ -0,0 +1,209 @@
+class DicomS
+  ELEMENTS_TO_REMOVE = %w(0028,2110 0028,2112 0018,1151 0018,1152 0028,1055 7FE0,0000 7FE0,0010)
+
+  # When generating DICOMs back:
+  # Elements that must be replaced (because image format is not preserved)
+  #   0002,0010     Transfer Syntax UID
+  #                 replace by 1.2.840.10008.1.2.1 Implicit VR Little Endian
+  #                 or maybe 1.2.840.10008.1.2: Implicit VR Little Endian: Default Transfer Syntax for DICOM
+  # these should be removed if present:
+  #   0028,2110       Lossy Image Compression
+  #   0028,2112       Lossy Image Compression Ratio
+  # we need to adjust metadata elements (which refer to first slice)
+  # to each slice.
+  # elements that vary from slice to slice but whose variation probably doesn't matter:
+  #   0008,0033     Content Time
+  # elements that vary and should be removed:
+  #   0018,1151     X-Ray Tube Current
+  #   0018,1152     Exposure
+  # elements that should be adjusted:
+  #   0020,0013     Instance Number # increment by 1 for each slice
+  #   0020,0032     Image Position (Patient) # should be computed from additional metadata (dz)
+  #   0020,1041     Slice Location  # should be computed from additional metadata (dz)
+  # elements that may need adjusting depending on value restoration method:
+  #   0028,0100     Bits Allocated        (keep if value size is maintained)
+  #   0028,0101     Bits Stored           make = Bits Allocated
+  #   0028,0102     High Bit              make = BIts Stored - 1
+  #   0028,0103     Pixel Representation  0-unsigned 1-signed
+  #   0028,1050     Window Center
+  #   0028,1051     Window Width
+  #   0028,1052     Rescale Intercept
+  #   0028,1053     Rescale Slope
+  #   0028,1054     Rescale Type
+  #   0028,1055     Window Center & Width Explanation  - can be removed if present
+  # elements that shouldn't vary:
+  #   0028,0002     Samples per Pixel                   = 1
+  #   0028,0004     Photometric Interpretation          = MONOCHROME2
+  # also, these element should be removed (because Pixel data is set by assigning an image)
+  #   7FE0,0000     Group Length    - can be omitted
+  #   7FE0,0010     Pixel Data      - will be assigned by assigning an image
+  # other varying elements that need further study: (vary in some studies)
+  #   0002,0000     File Meta Information Group Length # drop this and 0002,0001?
+  #   0002,0003     Media Storage SOP Instance UID
+  #   0008,0018     SOP Instance UID
+
+  def unpack(pack_file, options = {})
+    options = CommandOptions[options]
+
+    progress = Progress.new('unpacking', options)
+
+    unpack_dir = options.path_option(:output,
+      File.basename(pack_file, '.mkv')
+    )
+    FileUtils.mkdir_p unpack_dir
+
+    prefix = File.basename(pack_file, '.mkv')
+    output_file_pattern = File.join(unpack_dir, "#{prefix}-%3d.jpeg")
+
+    progress.begin_subprocess 'extracting_images', -70
+    ffmpeg = SysCmd.command('ffmpeg', @ffmpeg_options) do
+      option '-y' # overwrite existing files
+      option '-hide_banner'
+      option '-loglevel', 'quiet'
+      option '-i', file: pack_file
+      option '-q:v', 2
+      file output_file_pattern
+    end
+    ffmpeg.run error_output: :separate
+    check_command ffmpeg
+
+    progress.begin_subprocess 'extracting_metadata', -10
+    metadata_file = File.join(unpack_dir, 'metadata.txt')
+    ffmpeg = SysCmd.command('ffmpeg', @ffmpeg_options) do
+      option '-y' # overwrite existing files
+      option '-hide_banner'
+      option '-loglevel', 'quiet'
+      option '-i', file: pack_file
+      option '-f', 'ffmetadata'
+      file metadata_file
+    end
+    ffmpeg.run error_output: :separate
+    check_command ffmpeg
+
+    dicom_elements, metadata = meta_codec.read_metadata(metadata_file)
+    metadata = cast_metadata(metadata)
+
+    metadata_yaml = File.join(unpack_dir, 'metadata.yml')
+    File.open(metadata_yaml, 'w') do |yaml|
+      yaml.write metadata.to_yaml
+    end
+
+    if options[:dicom_output]
+      dicom_directory = options.path_option(:dicom_output,
+        'DICOM'
+      )
+      img_files = File.join(unpack_dir, "#{prefix}-*.jpeg")
+      if options.roi
+        firstx, lastx, firsty, lasty, firstz, lastz = options.roi
+        columns = lastx - firstx + 1
+        rows = lasty - firsty + 1
+      else
+        rows = metadata.ny
+        columns = metadata.nx
+      end
+      progress.begin_subprocess 'generating_dicoms', 100, img_files.size
+      count = 0
+      pos = 0.0
+      slice_pos = 0.0
+      Dir[img_files].each do |fn, i|
+        count += 1
+        dicom_file = File.join(dicom_directory, File.basename(fn, '.jpeg')+'.dcm')
+        image = Magick::Image::read(fn).first
+        image_columns = image.columns
+        image_rows = image.rows
+        if image_columns != columns || image_rows != rows
+          raise "Inconsistent image size"
+        end
+        dicom = DICOM::DObject.new
+        dicom_elements.each do |element|
+          case element.tag
+          when '0002,0010'
+            # TODO: replace value by 1.2.840.10008.1.2.1
+          when *ELEMENTS_TO_REMOVE
+            element = nil
+          when '0020,0013'
+            element.value = count
+          when '0020,0032'
+            if count == 1
+              pos = element.value.split('\\').map(&:to_f)
+            else
+              pos[2] += metadata.dz
+              element.value = pos.join('\\')
+            end
+          when '0020,1041'
+            if count == 1
+              slice_pos = element.value.to_f
+            else
+              slice_pos += metadata.dz
+              element.value = slice_pos.to_f
+            end
+          when '0028,0010'
+            element.value = image_rows
+          when '0028,0011'
+            element.value = image_columns
+          when '0028,0101'
+            element.value = metadata.bits
+          when '0028,0102'
+            element.value = metadata.bits - 1
+          when '0028,0103'
+            element.value = metadata.signed
+          end
+          if element
+            DICOM::Element.new(element.tag, element.value, :parent => dicom)
+          end
+        end
+        dicom.pixels = image_to_dicom_pixels(metadata, image)
+        dicom.write dicom_file
+        progress.update_subprocess count
+      end
+    end
+    progress.finish
+  end
+
+  def image_to_dicom_pixels(metadata, image)
+    min_v = metadata.min # value assigned to black
+    max_v = metadata.max # value assigned to white
+    if metadata.rescaled.to_i == 1
+      slope = metadata.slope
+      intercept = metadata.intercept
+      if slope != 1 || intercept != 0
+        # unscale
+        min_v = (min_v - intercept)/slope
+        max_v = (max_v - intercept)/slope
+      end
+    end
+    pixels = image.export_pixels(0, 0, image.columns, image.rows, 'I')
+    pixels =  NArray.to_na(pixels).reshape!(image.columns, image.rows)
+    pixels = pixels.to_type(NArray::SFLOAT)
+    q = Magick::MAGICKCORE_QUANTUM_DEPTH
+    min_p, max_p = pixel_value_range(q, false)
+    # min_p => min_v; max_p => max_v
+    # pixels.sbt! min_p # not needed, min_p should be 0
+    pixels.mul! (max_v - min_v).to_f/(max_p - min_p)
+    pixels.add! min_v
+    bits = metadata.bits # original bit depth, in accordance with '0028,0100' if dicom metatada present
+    signed = metadata.signed == 1 ? true : false # in accordance with 0028,0103 if dicom metadata
+    if true
+      pixels = pixels.to_i
+    else
+      if bits > 16
+        if signed
+          pixels = pixels.to_type(3) # sint (signed, four bytes)
+        else
+          pixels = pixels.to_type(4) # sfloat (single precision float)
+        end
+      elsif bits > 8
+        if signed
+          pixels = pixels.to_type(2) # int (signed, two bytes)
+        else
+          pixels = pixels.to_type(3) # sint (signed, four bytes)
+        end
+      elsif signed
+        pixels = pixels.to_type(2) # sint (signed, two bytes)
+      else
+        pixels = pixels.to_type(1) # byte (unsiged)
+      end
+    end
+    pixels
+  end
+end