dicoms 1.0.0

data/lib/dicoms/command_options.rb

@@ -0,0 +1,40 @@
+class DicomS
+  class CommandOptions < Settings
+    def initialize(options)
+      @base_dir = nil
+      if settings_file = options.delete(:settings_io)
+        @settings_io = SharedSettings.new(settings_file)
+      else
+        settings_file = options.delete(:settings)
+      end
+      if settings_file
+        settings = SharedSettings.new(settings_file).read
+        options = settings.merge(options.to_h.reject{ |k, v| v.nil? })
+        @base_dir = File.dirname(settings_file)
+      else
+        @base_dir = nil
+      end
+      super options
+    end
+
+    def path_option(option, default = nil)
+      path = self[option.to_sym] || default
+      path = File.expand_path(path, @base_dir) if @base_dir && path
+      path
+    end
+
+    attr_reader :base_name
+
+    def self.[](options)
+      options.is_a?(CommandOptions) ? options : CommandOptions.new(options)
+    end
+
+    def save_settings(command, data)
+      if @settings_io
+        @settings_io.update do |settings|
+          settings.merge command.to_sym => data
+        end
+      end
+    end
+  end
+end

data/lib/dicoms/extract.rb

@@ -0,0 +1,87 @@
+class DicomS
+  # extract the images of a set of DICOM files
+  def extract(dicom_directory, options = {})
+    options = CommandOptions[options]
+
+    progress = Progress.new('extracting', options)
+    progress.begin_subprocess 'reading_metadata', 2
+
+    strategy = define_transfer(options, :window)
+    sequence = Sequence.new(
+      dicom_directory,
+      transfer: strategy,
+      reorder: options[:reorder]
+    )
+
+    progress.begin_subprocess 'extracting_images', 100, sequence.size
+
+    extract_dir = options.path_option(
+      :output, File.join(File.expand_path(dicom_directory), 'images')
+    )
+    FileUtils.mkdir_p FileUtils.mkdir_p extract_dir
+    prefix = nil
+    min, max = sequence.metadata.min, sequence.metadata.max
+    sequence.each do |d, i, file|
+      unless prefix
+        prefix, name_pattern, start_number = dicom_name_pattern(file, extract_dir)
+      end
+      if options.raw
+        output_file = output_file_name(extract_dir, prefix, file, '.raw')
+        endianness = dicom_endianness(d, options)
+        sequence.metadata.endianness = endianness.to_s
+        bits = dicom_bit_depth(d)
+        signed = dicom_signed?(d)
+        fmt = pack_format(bits, signed, endianness)
+        File.open(output_file, 'wb') do |out|
+          out.write sequence.dicom_pixels(d).flatten.to_a.pack("#{fmt}*")
+        end
+      else
+        output_image = output_file_name(extract_dir, prefix, file)
+        sequence.save_jpg d, output_image
+      end
+      progress.update_subprocess i
+    end
+
+    metadata = cast_metadata(sequence.metadata)
+    metadata_yaml = File.join(extract_dir, 'metadata.yml')
+    File.open(metadata_yaml, 'w') do |yaml|
+      yaml.write metadata.to_yaml
+    end
+
+    progress.finish
+  end
+
+  def dicom_endianness(dicom, options = {})
+    if options[:big_endian]
+      :big
+    elsif options[:little_endian]
+      :little
+    elsif dicom.stream.str_endian
+      :big
+    else
+      :little
+    end
+  end
+
+  def pack_format(bits, signed, endianness)
+    if bits > 16
+      if signed
+        endianness == :little ? 'l<' : 'l>'
+      else
+        endianness == :little ? 'L<' : 'L>'
+      end
+    elsif bits > 8
+      if signed
+        endianness == :little ? 's<' : 's>'
+      else
+        endianness == :little ? 'S<' : 'S>'
+      end
+    else
+      if signed
+        "c"
+      else
+        "C"
+      end
+    end
+  end
+end

data/lib/dicoms/meta_codec.rb

@@ -0,0 +1,131 @@
+# Inserting/extracting DICOM metadata in video files with FFMpeg
+#
+# Example of use:
+#
+#   # Add metadata to a file
+#   dicom = DICOM::DObject.read(dicom_file)
+#   meta_codec = MetaCodec.new(mode: :chunked)
+#   meta_file = 'ffmetadata'
+#   meta_codec.write_metadata(dicom, meta_file, dx: 111, dy: 222, dz: 333)
+#   input_file = 'video.mkv'
+#   output_file = 'video_with_metadata.mkv'
+#   `ffmpeg -i #{input_file} -i #{meta_file} -map_metadata 1 -codec copy #{output_file}`
+#
+#   # Extract metadata from a file
+#   `ffmpeg -i #{output_file}  -f ffmetadata #{meta_file}`
+#   dicom_elements, additional_values = meta_codec.read_metadata(meta_file)
+#
+class DicomS::MetaCodec
+
+  # Two encoding modes:
+  # * :chunked : use few metadata entries (dicom_0)
+  #   that encode all the DICOM elements (several are used because there's a limit
+  #   in the length of a single metadata entry)
+  # * :individual : use individual metadata entries for each DICOM tag
+  def initialize(options = {})
+    @mode = options[:mode] || :individual
+  end
+
+  def encode_metadata(dicom, additional_metadata = {}, &blk)
+    elements = dicom.elements.select{|e| !e.value.nil?}
+    elements = elements.select(&blk) if blk
+    elements = elements.map{|e| [e.tag, e.value]}
+    case @mode
+    when :chunked
+      txt = elements.map{|tag, value| "#{inner_escape(tag)}#{VALUE_SEPARATOR}#{inner_escape(value)}"}.join(PAIR_SEPARATOR)
+      chunks = in_chunks(txt, CHUNK_SIZE).map{|txt| escape(txt)}
+      metadata = Hash[chunks.each_with_index.to_a.map(&:reverse)]
+    else
+      pairs = elements.map { |tag, value|
+        group, tag = tag.split(',')
+        ["#{group}_#{tag}", escape(value)]
+      }
+      metadata = Hash[pairs]
+    end
+
+    metadata.merge(additional_metadata)
+  end
+
+  # Write DICOM metatada encoded for FFMpeg into a metadatafile
+  # The file can be attached to a video input_file with:
+  #   `ffmpeg -i #{input_file} -i #{metadatafile} -map_metadata 1 -codec copy #{output_file}`
+  def write_metadata(dicom, metadatafile, additional_metadata = {}, &blk)
+    metadata = encode_metadata(dicom, additional_metadata, &blk)
+    File.open(metadatafile, 'w') do |file|
+      file.puts ";FFMETADATA1"
+      metadata.each do |name, value|
+        file.puts "dicom_#{name}=#{value}"
+      end
+    end
+  end
+
+  def decode_metadata(txt)
+    txt = unescape(txt)
+    data = txt.split(PAIR_SEPARATOR).map{|pair| pair.split(VALUE_SEPARATOR)}
+    data = data.map{|tag, value| [inner_unescape(tag), inner_unescape(value)]}
+    data.map{|tag, value|
+      DICOM::Element.new(tag, value)
+    }
+  end
+
+  # Can extract the metadatafile from a video input_file with:
+  #   `ffmpeg -i #{input_file}  -f ffmetadata #{metadatafile}`
+  def read_metadata(metadatafile)
+    lines = File.read(metadatafile).lines[1..-1]
+    lines = lines.reject { |line|
+      line = line.strip
+      line.empty? || line[0, 1] == '#' || line[0, 1] == ';'
+    }
+    chunks = []
+    elements = []
+    additional_metadata = {}
+    lines.each do |line|
+      key, value = line.strip.split('=')
+      key = key.downcase
+      if match = key.match(/\Adicom_(\d+)\Z/)
+        i = match[1].to_i
+        chunks << [i, value]
+      elsif match = key.match(/\Adicom_(\h+)_(\h+)\Z/)
+        group = match[1]
+        tag = match[2]
+        tag = "#{group},#{tag}"
+        elements << DICOM::Element.new(tag, unescape(value))
+      elsif match = key.match(/\Adicom_(.+)\Z/)
+        additional_metadata[match[1].downcase.to_sym] = value # TODO: type conversion?
+      end
+    end
+    if chunks.size > 0
+      elements += decode_metadata(chunks.sort_by(&:first).map(&:last).join)
+    end
+    [elements, additional_metadata]
+  end
+
+  private
+
+  def escape(txt)
+    txt.to_s.gsub('\\', Regexp.quote('\\\\')).gsub('=', '\\=').gsub(';', '\\;').gsub('#', '\\#').gsub('\n', '\\\n')
+  end
+
+  def unescape(txt)
+    txt.to_s.gsub('\\\\', Regexp.quote('\\')).gsub('\\=', '=').gsub('\\;', ';').gsub('\\#', '#').gsub('\\\n', '\n')
+  end
+
+  VALUE_SEPARATOR = '>'
+  PAIR_SEPARATOR = '<'
+
+  def inner_escape(txt)
+    txt.to_s.gsub(VALUE_SEPARATOR, '[[METACODEC_VSEP]]').gsub(PAIR_SEPARATOR, '[[METACODEC_PSEP]]')
+  end
+
+  def inner_unescape(txt)
+    txt.to_s.gsub('[[METACODEC_VSEP]]', VALUE_SEPARATOR).gsub('[[METACODEC_PSEP]]', PAIR_SEPARATOR)
+  end
+
+  CHUNK_SIZE = 800
+
+  def in_chunks(txt, max_size=CHUNK_SIZE)
+    # txt.chars.each_slice(max_size).map(&:join)
+    txt.scan(/.{1,#{max_size}}/)
+  end
+
+end

data/lib/dicoms/pack.rb

@@ -0,0 +1,82 @@
+class DicomS
+  def pack(dicom_directory, options = {})
+    # TODO: keep more metadata to restore the exact strategy+min,max and so
+    # be able to restore original DICOM values (and rescaling/window metadata)
+    # bit depth, signed/unsigned, rescale, window, data values corresponding
+    # to minimum (black) and maximum (white)
+    options = CommandOptions[options]
+
+    progress = Progress.new('packaging', options)
+    progress.begin_subprocess 'reading_metadata', 2
+
+    strategy = define_transfer(options, :sample)
+    sequence = Sequence.new(
+      dicom_directory,
+      transfer: strategy,
+      roi: options[:roi],
+      reorder: options[:reorder]
+    )
+
+    output_name = (options.path_option(:output) || File.basename(dicom_directory)) + '.mkv'
+    pack_dir = options.path_option(:tmp, 'dspack_tmp') # TODO: better default
+    FileUtils.mkdir_p pack_dir
+
+    name_pattern = start_number = prefix = nil
+
+    progress.begin_subprocess 'extracting_images', 60, sequence.size
+    image_files = []
+    keeping_path do
+      sequence.each do |d, i, file|
+        unless name_pattern
+          prefix, name_pattern, start_number = dicom_name_pattern(file, pack_dir)
+        end
+        output_image = output_file_name(pack_dir, prefix, file)
+        image_files << output_image
+        sequence.save_jpg d, output_image
+        progress.update_subprocess i
+      end
+    end
+    if options[:dicom_metadata]
+      metadata_file = File.join(pack_dir, 'ffmetadata')
+      meta_codec.write_metadata(sequence.first, metadata_file, sequence.metadata.to_h)
+    end
+    progress.begin_subprocess 'packing_images'
+    ffmpeg = SysCmd.command('ffmpeg', @ffmpeg_options) do
+      # global options
+      option '-y' # overwrite existing files
+      option '-loglevel', 'quiet'
+      option '-hide_banner'
+
+      # input
+      option '-start_number', start_number
+      option '-i', name_pattern
+
+      # metadata
+      if metadata_file
+        # additional input: metadata
+        option '-i', metadata_file
+        # use metadata from input file #1 (0 is the image sequence)
+        option '-map_metadata', 1
+      else
+        sequence.metadata.each do |key, value|
+          option '-metadata', "dicom_#{key}", equal_value: value
+        end
+      end
+
+      # output
+      option '-vcodec', 'mjpeg'
+      option '-q:v', '2.0'
+      file output_name
+    end
+    ffmpeg.run error_output: :separate
+    check_command ffmpeg
+    if File.expand_path(File.dirname(output_name)) == File.expand_path(pack_dir)
+      image_files.files.each do |file|
+        FileUtils.rm file
+      end
+    else
+      FileUtils.rm_rf pack_dir
+    end
+    progress.finish
+  end
+end

data/lib/dicoms/progress.rb

@@ -0,0 +1,80 @@
+class DicomS
+  class Progress
+    def initialize(description, options={})
+      options = CommandOptions[options]
+      filename = options.path_option(:progress)
+      @progress = options[:initial_progress] || 0
+      # TODO: if filename == :console, show progress on the console
+      if filename
+        @file = SharedSettings.new(
+          filename,
+          replace_contents: {
+            process: description,
+            subprocess: options[:subprocess],
+            progress: @progress
+          }
+        )
+      else
+        @file = nil
+      end
+      @subprocess_start = @subprocess_size = @subprocess_percent = nil
+    end
+
+    attr_reader :progress
+
+    def finished?
+      @progress >= 100
+    end
+
+    def update(value, subprocess = nil)
+      @progress = value
+      if @file
+        @file.update do |data|
+          data.progress = @progress
+          data.subprocess = subprocess if subprocess
+          data
+        end
+      end
+    end
+
+    def finish
+      update 100, 'finished'
+    end
+
+    # Begin a subprocess which represent `percent`
+    # of the total process. The subprocess will be measured
+    # with values up to `size`
+    def begin_subprocess(description, percent=nil, size=0)
+      end_subprocess if @subprocess_start
+      @subprocess_start = @progress
+      percent ||= 100
+      if percent < 0
+        # interpreted as percent of what's lef
+        percent = (100 - @progress)*(-percent)/100.0
+      end
+      percent = [percent, 100 - @progress].min
+      # @subprocess_end = @progress + percent
+      @subprocess_size = size.to_f
+      @subprocess_percent = percent
+      update @progress, description
+    end
+
+    def update_subprocess(value)
+      raise "Subprocess not started" unless @subprocess_start
+      sub_fraction = value/@subprocess_size
+      @progress = @subprocess_start + @subprocess_percent*sub_fraction
+      if @subprocess_size < 20 || (value % 10) == 0
+        # frequently updated processes don't update the file every
+        # fime to avoid the overhead (just 1 in 10 times)
+        update @progress
+      end
+    end
+
+    def end_subprocess
+      raise "Subprocess not started" unless @subprocess_start
+      @progress = @subprocess_start + @subprocess_percent
+      @subprocess_start = @subprocess_size = @subprocess_percent = nil
+      update @progress
+    end
+  end
+end

data/lib/dicoms/projection.rb

@@ -0,0 +1,422 @@
+require 'rmagick'
+
+class DicomS
+  NORMALIZE_PROJECTION_IMAGES = true
+  ASSIGN_IMAGE_PIXELS_AS_ARRAY = true
+  ADJUST_AAP_FOR_WIDTH = true
+
+  # extract projected images of a set of DICOM files
+  def projection(dicom_directory, options = {})
+    options = CommandOptions[options]
+
+    progress = Progress.new('projecting', options)
+    progress.begin_subprocess 'reading_metadata', 1
+
+    # We can save on memory use by using 8-bit processing, so it will be the default
+    strategy = define_transfer(options, :window, output: :byte)
+    sequence = Sequence.new(
+      dicom_directory,
+      transfer: strategy,
+      reorder: options[:reorder]
+    )
+
+    extract_dir = options.path_option(
+      :output, File.join(File.expand_path(dicom_directory), 'images')
+    )
+    FileUtils.mkdir_p extract_dir
+
+    if sequence.metadata.lim_max <= 255
+       bits = 8
+     else
+       bits = 16
+    end
+
+    scaling = projection_scaling(sequence.metadata, options)
+    sequence.metadata.merge! scaling
+    scaling = Settings[scaling]
+
+    reverse_x = sequence.metadata.reverse_x.to_i == 1
+    reverse_y = sequence.metadata.reverse_y.to_i == 1
+    reverse_z = sequence.metadata.reverse_z.to_i == 1
+
+    maxx = sequence.metadata.nx
+    maxy = sequence.metadata.ny
+    maxz = sequence.metadata.nz
+
+    # minimum and maximum slices with non-(almost)-blank contents
+    minx_contents = maxx
+    maxx_contents = 0
+    miny_contents = maxy
+    maxy_contents = 0
+    minz_contents = maxz
+    maxz_contents = 0
+
+    if full_projection?(options[:axial]) || full_projection?(options[:coronal]) || full_projection?(options[:sagittal])
+      percent = 65
+    else
+      percent = 90
+    end
+    progress.begin_subprocess 'generating_volume', percent, maxz
+
+    # Load all the slices into a (big) 3D array
+    if bits == 8
+      # TODO: support signed too
+      volume = NArray.byte(maxx, maxy, maxz)
+    else
+      # With type NArray::SINT instead of NArray::INT we would use up half the
+      # memory, but each slice to be converted to image would have to be
+      # convertd to INT...
+      # volume = NArray.sint(maxx, maxy, maxz)
+      volume = NArray.int(maxx, maxy, maxz)
+    end
+    keeping_path do
+      sequence.each do |dicom, z, file|
+        slice = sequence.dicom_pixels(dicom, unsigned: true)
+        volume[true, true, z] = slice
+        if center_slice_projection?(options[:axial])
+          minz_contents, maxz_contents = update_min_max_contents(
+            z, slice.max, maxy, minz_contents, maxz_contents
+          )
+        end
+        progress.update_subprocess z
+      end
+    end
+
+    if center_slice_projection?(options[:coronal])
+      (0...maxy).each do |y|
+        miny_contents, maxy_contents = update_min_max_contents(
+          y, volume[true, y, true].max, maxy, miny_contents, maxy_contents
+        )
+      end
+    end
+
+    if center_slice_projection?(options[:sagittal])
+      (0...maxz).each do |z|
+        minz_contents, maxz_contents = update_min_max_contents(
+          z, volume[true, true, z].max, maxz, minz_contents, maxz_contents
+        )
+      end
+    end
+
+    if single_slice_projection?(options[:axial])
+      axial_zs = [options[:axial].to_i]
+    elsif center_slice_projection?(options[:axial])
+      axial_zs = [[(minz_contents+maxz_contents)/2, 'c']]
+    elsif middle_slice_projection?(options[:axial])
+      axial_zs = [[maxz/2, 'm']]
+    elsif full_projection?(options[:axial])
+      axial_zs = (0...maxz)
+    else
+      axial_zs = []
+    end
+
+    if single_slice_projection?(options[:sagittal])
+      sagittal_xs = [options[:sagittal].to_i]
+    elsif center_slice_projection?(options[:sagittal])
+      sagittal_xs = [[(minx_contents+maxx_contents)/2, 'c']]
+    elsif middle_slice_projection?(options[:sagittal])
+      sagittal_xs = [[maxx/2, 'm']]
+    elsif full_projection?(options[:sagittal])
+      sagittal_xs = (0...maxx)
+    else
+      sagittal_xs = []
+    end
+
+    if single_slice_projection?(options[:coronal])
+      coronal_ys = [options[:coronal].to_i]
+    elsif center_slice_projection?(options[:coronal])
+      coronal_ys = [[(miny_contents+maxy_contents)/2, 'c']]
+    elsif middle_slice_projection?(options[:coronal])
+      coronal_ys = [[maxy/2, 'm']]
+    elsif full_projection?(options[:coronal])
+      coronal_ys = (0...maxx)
+    else
+      coronal_ys = []
+    end
+
+    n = axial_zs.size + sagittal_xs.size + coronal_ys.size
+
+    progress.begin_subprocess 'generating_slices', -70, n if n > 0
+    axial_zs.each_with_index do |(z, suffix), i|
+      slice = volume[true, true, z]
+      output_image = output_file_name(extract_dir, 'axial_', suffix || z.to_s)
+      save_pixels slice, output_image,
+        bit_depth: bits, reverse_x: reverse_x, reverse_y: reverse_y,
+        cols: scaling.scaled_nx, rows: scaling.scaled_ny,
+        normalize: NORMALIZE_PROJECTION_IMAGES
+      progress.update_subprocess i
+    end
+    sagittal_xs.each_with_index do |(x, suffix), i|
+      slice = volume[x, true, true]
+      output_image = output_file_name(extract_dir, 'sagittal_', suffix || x.to_s)
+      save_pixels slice, output_image,
+        bit_depth: bits, reverse_x: !reverse_y, reverse_y: !reverse_z,
+        cols: scaling.scaled_ny, rows: scaling.scaled_nz,
+        normalize: NORMALIZE_PROJECTION_IMAGES
+      progress.update_subprocess axial_zs.size + i
+    end
+    coronal_ys.each_with_index do |(y, suffix), i|
+      slice = volume[true, y, true]
+      output_image = output_file_name(extract_dir, 'coronal_', suffix || y.to_s)
+      save_pixels slice, output_image,
+        bit_depth: bits, reverse_x: reverse_x, reverse_y: !reverse_z,
+        cols: scaling.scaled_nx, rows: scaling.scaled_nz,
+        normalize: NORMALIZE_PROJECTION_IMAGES
+      progress.update_subprocess axial_zs.size + sagittal_xs.size + i
+    end
+
+    n = [:axial, :coronal, :sagittal].map{ |axis|
+      aggregate_projection?(options[axis]) ? 1 : 0
+    }.inject(&:+)
+    progress.begin_subprocess 'generating_projections', 100, n if n > 0
+    i = 0
+
+    float_v = nil
+    if options.to_h.values_at(:axial, :coronal, :sagittal).any?{ |sel|
+         aggregate_projection_includes?(sel, 'aap')
+       }
+      # It's gonna take memory... (a whole lot of precious memory)
+      float_v ||= volume.to_type(NArray::SFLOAT)
+      # To enhance result contrast we will apply a gamma of x**4
+      float_v.mul! 1.0/float_v.max
+      float_v.mul! float_v
+      float_v.mul! float_v
+    end
+    if aggregate_projection?(options[:axial])
+      views = []
+      if aggregate_projection_includes?(options[:axial], 'aap')
+        slice = accumulated_attenuation_projection(
+          float_v, Z_AXIS, sequence.metadata.lim_max, maxz
+        ).to_type(volume.typecode)
+        views << ['aap', slice]
+      end
+      if aggregate_projection_includes?(options[:axial], 'mip')
+        slice = maximum_intensity_projection(volume, Z_AXIS)
+        views << ['mip', slice]
+      end
+      views.each do |view, slice|
+        output_image = output_file_name(extract_dir, 'axial_', view)
+        save_pixels slice, output_image,
+          bit_depth: bits, reverse_x: reverse_x, reverse_y: reverse_y,
+          cols: scaling.scaled_nx, rows: scaling.scaled_ny,
+          normalize: NORMALIZE_PROJECTION_IMAGES
+      end
+      i += 1
+      progress.update_subprocess i
+    end
+    if aggregate_projection?(options[:coronal])
+      views = []
+      if aggregate_projection_includes?(options[:coronal], 'aap')
+        # It's gonna take memory... (a whole lot of precious memory)
+        float_v ||= volume.to_type(NArray::SFLOAT)
+        slice = accumulated_attenuation_projection(
+          float_v, Y_AXIS, sequence.metadata.lim_max, maxy
+        ).to_type(volume.typecode)
+        views << ['aap', slice]
+      end
+      if aggregate_projection_includes?(options[:coronal], 'mip')
+         slice = maximum_intensity_projection(volume, Y_AXIS)
+         views << ['mip', slice]
+      end
+      views.each do |view, slice|
+        output_image = output_file_name(extract_dir, 'coronal_', view)
+        save_pixels slice, output_image,
+          bit_depth: bits, reverse_x: reverse_x, reverse_y: !reverse_z,
+          cols: scaling.scaled_nx, rows: scaling.scaled_nz,
+          normalize: NORMALIZE_PROJECTION_IMAGES
+      end
+      i += 1
+      progress.update_subprocess i
+    end
+    if aggregate_projection?(options[:sagittal])
+      views = []
+      if aggregate_projection_includes?(options[:sagittal], 'aap')
+        # It's gonna take memory... (a whole lot of precious memory)
+        float_v ||= volume.to_type(NArray::SFLOAT)
+        slice = accumulated_attenuation_projection(
+          float_v, X_AXIS, sequence.metadata.lim_max, maxx
+        ).to_type(volume.typecode)
+        views << ['aap', slice]
+      end
+      if aggregate_projection_includes?(options[:sagittal], 'mip')
+        slice = maximum_intensity_projection(volume, X_AXIS)
+        views << ['mip', slice]
+      end
+      views.each do |view, slice|
+        output_image = output_file_name(extract_dir, 'sagittal_', view)
+        save_pixels slice, output_image,
+          bit_depth: bits, reverse_x: !reverse_y, reverse_y: !reverse_z,
+          cols: scaling.scaled_ny, rows: scaling.scaled_nz,
+          normalize: NORMALIZE_PROJECTION_IMAGES
+      end
+      i += 1
+      progress.update_subprocess i
+    end
+    float_v = nil
+    options.save_settings 'projection', sequence.metadata
+    progress.finish
+  end
+
+  private
+
+  X_AXIS = 0
+  Y_AXIS = 1
+  Z_AXIS = 2
+
+  def update_min_max_contents(pos, max, ref_max, current_min, current_max)
+    if max/ref_max.to_f >= 0.05
+      current_min = [current_min, pos].min
+      current_max = [current_max, pos].max
+    end
+    [current_min, current_max]
+  end
+
+  def maximum_intensity_projection(v, axis)
+    v.max(axis)
+  end
+
+  def accumulated_attenuation_projection(float_v, axis, max_output_level, max=500)
+    k = 0.02
+    if ADJUST_AAP_FOR_WIDTH
+      k *= 500.0/max
+    end
+    v = float_v.sum(axis)
+    v.mul! -k
+    v = NMath.exp(v)
+    # Invert result (from attenuation to transmission)
+    v.mul! -max_output_level
+    v.add! max_output_level
+    v
+  end
+
+  def axis_index(v, maxv, reverse)
+    reverse ? maxv - v : v
+  end
+
+  def aggregate_projection?(axis_selection)
+    axis_selection && axis_selection.split(',').any? { |sel|
+      ['*', 'mip', 'aap'].include?(sel)
+    }
+  end
+
+  def full_projection?(axis_selection)
+    axis_selection && axis_selection.split(',').any? { |sel| sel == '*' }
+  end
+
+  def single_slice_projection?(axis_selection)
+    axis_selection.is_a?(String) && /\A\d+\Z/i =~ axis_selection
+  end
+
+  def center_slice_projection?(axis_selection)
+    axis_selection && axis_selection.split(',').any? { |sel| sel.downcase == 'c' }
+  end
+
+  def middle_slice_projection?(axis_selection)
+    axis_selection && axis_selection.split(',').any? { |sel| sel.downcase == 'm' }
+  end
+
+  def aggregate_projection_includes?(axis_selection, projection)
+    axis_selection && axis_selection.split(',').any? { |sel|
+      sel == projection
+    }
+  end
+
+  def projection_scaling(data, options = {})
+    sx = sy = sz = 1
+
+    nx = data.nx
+    ny = data.ny
+    nz = data.nz
+    dx = data.dx
+    dy = data.dy
+    dz = data.dz
+
+    unless dx == dy && dy == dz
+      # need to cope with different scales in different axes.
+      # will always produce shrink factors (<1)
+      ref = [dx, dy, dz].max.to_f
+      sx = dx/ref
+      sy = dy/ref
+      sz = dz/ref
+    end
+
+    scaled_nx = (nx*sx).round
+    scaled_ny = (ny*sy).round
+    scaled_nz = (nz*sz).round
+
+    # further shrinking may be needed to avoid any projection
+    # to be larger thant the maximum image size
+    # Axis X is the columns of axial an coronal views
+    # Axis Y is the rows of axial and the columns of sagittal
+    # Axis Z is the rows of coronal and sagittal views
+    max_nx = [scaled_nx, options.max_x_pixels, options[:maxcols]].compact.min
+    if scaled_nx > max_nx
+      scaled_nx = max_nx
+      sx = scaled_nx/nx.to_f
+    end
+
+    max_ny = [scaled_ny, options.max_y_pixels, options[:maxcols], options[:maxrows]].compact.min
+    if scaled_ny > max_ny
+      scaled_ny = max_ny
+      sy = scaled_ny/ny.to_f
+    end
+
+    max_nz = [scaled_nz, options.max_z_pixels, options[:maxrows]].compact.min
+    if scaled_nz > max_nz
+      scaled_nz = max_nz
+      sz = scaled_nz/nz.to_f
+    end
+
+    {
+      scale_x: sx, scale_y: sy, scale_z: sz,
+      scaled_nx: scaled_nx, scaled_ny: scaled_ny, scaled_nz: scaled_nz
+    }
+  end
+
+  def save_pixels(pixels, output_image, options = {})
+    bits = options[:bit_depth] || 16
+    reverse_x = options[:reverse_x]
+    reverse_y = options[:reverse_y]
+    normalize = options[:normalize]
+
+    # max image size
+    scaled_columns = options[:cols]
+    scaled_rows = options[:rows]
+
+    columns, rows = pixels.shape
+
+    if ASSIGN_IMAGE_PIXELS_AS_ARRAY
+      # assign from array
+      if Magick::MAGICKCORE_QUANTUM_DEPTH != bits
+        if bits == 8
+          # scale up the data
+          pixels = pixels.to_type(NArray::INT)
+          pixels.mul! 256
+        else
+          # scale down
+          pixels.div! 256
+          pixels = pixels.to_type(NArray::BYTE) # FIXME: necessary?
+        end
+      end
+      image = Magick::Image.new(columns, rows).import_pixels(0, 0, columns, rows, 'I', pixels.flatten)
+    else
+      # Pack to a String (blob) and let Magick do the conversion
+      if bits == 8
+        rm_type = Magick::CharPixel
+        blob = pixels.flatten.to_a.pack('C*')
+      else
+        rm_type = Magick::ShortPixel
+        blob = pixels.flatten.to_a.pack('S<*')
+      end
+      image = Magick::Image.new(columns, rows).import_pixels(0, 0, columns, rows, 'I', blob, rm_type)
+    end
+    image.flip! if reverse_y
+    image.flop! if reverse_x
+    image = image.normalize if normalize
+    if scaled_columns != columns || scaled_rows != rows
+      image = image.resize(scaled_columns, scaled_rows)
+    end
+    image.write(output_image)
+  end
+
+end