aspera-cli 4.14.0 → 4.16.0

data/lib/aspera/preview/file_types.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/log'
 require 'singleton'
+require 'mime/types'
 
 module Aspera
   module Preview
@@ -11,266 +12,41 @@ module Aspera
       # values for conversion_type : input format
       CONVERSION_TYPES = %i[image office pdf plaintext video].freeze
 
-      # define how files are processed based on mime type
+      # special cases for mime types
       # spellchecker:disable
       SUPPORTED_MIME_TYPES = {
-        'application/json'                                                          => :plaintext,
-        'application/mac-binhex40'                                                  => :office,
-        'application/msword'                                                        => :office,
-        'application/pdf'                                                           => :pdf,
-        'application/postscript'                                                    => :image,
-        'application/rtf'                                                           => :office,
-        'application/vnd.3gpp.pic-bw-small'                                         => :image,
-        'application/vnd.hp-hpgl'                                                   => :image,
-        'application/vnd.hp-pcl'                                                    => :image,
-        'application/vnd.lotus-wordpro'                                             => :office,
-        'application/vnd.mobius.msl'                                                => :image,
-        'application/vnd.mophun.certificate'                                        => :image,
-        'application/vnd.ms-excel'                                                  => :office,
-        'application/vnd.ms-excel.sheet.binary.macroenabled.12'                     => :office,
-        'application/vnd.ms-excel.sheet.macroenabled.12'                            => :office,
-        'application/vnd.ms-excel.template.macroenabled.12'                         => :office,
-        'application/vnd.ms-powerpoint'                                             => :office,
-        'application/vnd.ms-powerpoint.presentation.macroenabled.12'                => :office,
-        'application/vnd.ms-powerpoint.template.macroenabled.12'                    => :office,
-        'application/vnd.ms-word.document.macroenabled.12'                          => :office,
-        'application/vnd.ms-word.template.macroenabled.12'                          => :office,
-        'application/vnd.ms-works'                                                  => :office,
-        'application/vnd.oasis.opendocument.chart'                                  => :office,
-        'application/vnd.oasis.opendocument.formula'                                => :office,
-        'application/vnd.oasis.opendocument.graphics'                               => :office,
-        'application/vnd.oasis.opendocument.graphics-template'                      => :office,
-        'application/vnd.oasis.opendocument.presentation'                           => :office,
-        'application/vnd.oasis.opendocument.presentation-template'                  => :office,
-        'application/vnd.oasis.opendocument.spreadsheet'                            => :office,
-        'application/vnd.oasis.opendocument.spreadsheet-template'                   => :office,
-        'application/vnd.oasis.opendocument.text'                                   => :office,
-        'application/vnd.oasis.opendocument.text-template'                          => :office,
-        'application/vnd.openxmlformats-officedocument.presentationml.presentation' => :office,
-        'application/vnd.openxmlformats-officedocument.presentationml.slideshow'    => :office,
-        'application/vnd.openxmlformats-officedocument.presentationml.template'     => :office,
-        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'         => :office,
-        'application/vnd.openxmlformats-officedocument.spreadsheetml.template'      => :office,
-        'application/vnd.openxmlformats-officedocument.wordprocessingml.document'   => :office,
-        'application/vnd.openxmlformats-officedocument.wordprocessingml.template'   => :office,
-        'application/vnd.palm'                                                      => :office,
-        'application/vnd.sun.xml.calc'                                              => :office,
-        'application/vnd.sun.xml.calc.template'                                     => :office,
-        'application/vnd.sun.xml.draw'                                              => :office,
-        'application/vnd.sun.xml.draw.template'                                     => :office,
-        'application/vnd.sun.xml.impress'                                           => :office,
-        'application/vnd.sun.xml.impress.template'                                  => :office,
-        'application/vnd.sun.xml.math'                                              => :office,
-        'application/vnd.sun.xml.writer'                                            => :office,
-        'application/vnd.sun.xml.writer.template'                                   => :office,
-        'application/vnd.wordperfect'                                               => :office,
-        'application/x-abiword'                                                     => :office,
-        'application/x-director'                                                    => :image,
-        'application/x-font-type1'                                                  => :image,
-        'application/x-msmetafile'                                                  => :image,
-        'application/x-mspublisher'                                                 => :office,
-        'application/x-xfig'                                                        => :image,
-        'audio/ogg'                                                                 => :video,
-        'font/ttf'                                                                  => :image,
-        'image/bmp'                                                                 => :image,
-        'image/cgm'                                                                 => :image,
-        'image/gif'                                                                 => :image,
-        'image/jpeg'                                                                => :image,
-        'image/png'                                                                 => :image,
-        'image/sgi'                                                                 => :image,
-        'image/svg+xml'                                                             => :image,
-        'image/tiff'                                                                => :image,
-        'image/vnd.adobe.photoshop'                                                 => :image,
-        'image/vnd.djvu'                                                            => :image,
-        'image/vnd.dxf'                                                             => :office,
-        'image/vnd.fpx'                                                             => :image,
-        'image/vnd.ms-photo'                                                        => :image,
-        'image/vnd.wap.wbmp'                                                        => :image,
-        'image/webp'                                                                => :image,
-        'image/x-cmx'                                                               => :office,
-        'image/x-freehand'                                                          => :office,
-        'image/x-icon'                                                              => :image,
-        'image/x-mrsid-image'                                                       => :image,
-        'image/x-pcx'                                                               => :image,
-        'image/x-pict'                                                              => :office,
-        'image/x-portable-anymap'                                                   => :image,
-        'image/x-portable-bitmap'                                                   => :image,
-        'image/x-portable-graymap'                                                  => :image,
-        'image/x-portable-pixmap'                                                   => :image,
-        'image/x-rgb'                                                               => :image,
-        'image/x-tga'                                                               => :image,
-        'image/x-xbitmap'                                                           => :image,
-        'image/x-xpixmap'                                                           => :image,
-        'image/x-xwindowdump'                                                       => :image,
-        'text/csv'                                                                  => :office,
-        'text/html'                                                                 => :office,
-        'text/plain'                                                                => :plaintext,
-        'text/troff'                                                                => :image,
-        'video/h261'                                                                => :video,
-        'video/h263'                                                                => :video,
-        'video/h264'                                                                => :video,
-        'video/mp4'                                                                 => :video,
-        'video/mpeg'                                                                => :video,
-        'video/quicktime'                                                           => :video,
-        'video/x-flv'                                                               => :video,
-        'video/x-m4v'                                                               => :video,
-        'video/x-matroska'                                                          => :video,
-        'video/x-mng'                                                               => :image,
-        'video/x-ms-wmv'                                                            => :video,
-        'video/x-msvideo'                                                           => :video}.freeze
+        'application/json'                   => :plaintext,
+        'text/plain'                         => :plaintext,
+        'application/pdf'                    => :pdf,
+        'audio/ogg'                          => :video,
+        'application/mxf'                    => :video,
+        'application/mac-binhex40'           => :office,
+        'application/msword'                 => :office,
+        'application/rtf'                    => :office,
+        'application/x-abiword'              => :office,
+        'application/x-mspublisher'          => :office,
+        'image/vnd.dxf'                      => :office,
+        'image/x-cmx'                        => :office,
+        'image/x-freehand'                   => :office,
+        'image/x-pict'                       => :office,
+        'text/csv'                           => :office,
+        'text/html'                          => :office,
+        'application/dicom'                  => :image,
+        'application/postscript'             => :image,
+        'application/vnd.3gpp.pic-bw-small'  => :image,
+        'application/vnd.hp-hpgl'            => :image,
+        'application/vnd.hp-pcl'             => :image,
+        'application/vnd.mobius.msl'         => :image,
+        'application/vnd.mophun.certificate' => :image,
+        'application/x-director'             => :image,
+        'application/x-font-type1'           => :image,
+        'application/x-msmetafile'           => :image,
+        'application/x-xfig'                 => :image,
+        'font/ttf'                           => :image,
+        'text/troff'                         => :image,
+        'video/x-mng'                        => :image}.freeze
 
-      # this is a way to add support for extensions that are otherwise not known by node api (mime type)
-      SUPPORTED_EXTENSIONS = {
-        'aai'          => :image,
-        'art'          => :image,
-        'arw'          => :image,
-        'avs'          => :image,
-        'bmp2'         => :image,
-        'bmp3'         => :image,
-        'bpg'          => :image,
-        'cals'         => :image,
-        'cdr'          => :office,
-        'cin'          => :image,
-        'clipboard'    => :image,
-        'cmyk'         => :image,
-        'cmyka'        => :image,
-        'cr2'          => :image,
-        'crw'          => :image,
-        'cur'          => :image,
-        'cut'          => :image,
-        'cwk'          => :office,
-        'dbf'          => :office,
-        'dcm'          => :image,
-        'dcx'          => :image,
-        'dds'          => :image,
-        'dib'          => :image,
-        'dif'          => :office,
-        'divx'         => :video,
-        'dng'          => :image,
-        'docx'         => :office,
-        'dpx'          => :image,
-        'epdf'         => :image,
-        'epi'          => :image,
-        'eps2'         => :image,
-        'eps3'         => :image,
-        'epsf'         => :image,
-        'epsi'         => :image,
-        'ept'          => :image,
-        'exr'          => :image,
-        'fax'          => :image,
-        'fb2'          => :office,
-        'fits'         => :image,
-        'fodg'         => :office,
-        'fodp'         => :office,
-        'fods'         => :office,
-        'fodt'         => :office,
-        'gplt'         => :image,
-        'gray'         => :image,
-        'hdr'          => :image,
-        'hpw'          => :office,
-        'hrz'          => :image,
-        'info'         => :image,
-        'inline'       => :image,
-        'j2c'          => :image,
-        'j2k'          => :image,
-        'jbig'         => :image,
-        'jng'          => :image,
-        'jp2'          => :image,
-        'jpt'          => :image,
-        'jxr'          => :image,
-        'key'          => :office,
-        'log'          => :plaintext,
-        'mat'          => :image,
-        'mcw'          => :office,
-        'met'          => :office,
-        'miff'         => :image,
-        'mml'          => :office,
-        'mono'         => :image,
-        'mpr'          => :image,
-        'mrsid'        => :image,
-        'mrw'          => :image,
-        'mtv'          => :image,
-        'mvg'          => :image,
-        'mw'           => :office,
-        'mwd'          => :office,
-        'mxf'          => :video,
-        'nef'          => :image,
-        'numbers'      => :office,
-        'orf'          => :image,
-        'otb'          => :image,
-        'p7'           => :image,
-        'pages'        => :office,
-        'palm'         => :image,
-        'pam'          => :image,
-        'pcd'          => :image,
-        'pcds'         => :image,
-        'pdf'          => :pdf,
-        'pef'          => :image,
-        'picon'        => :image,
-        'pict'         => :image,
-        'pix'          => :image,
-        'pm'           => :office,
-        'pm6'          => :office,
-        'pmd'          => :office,
-        'png00'        => :image,
-        'png24'        => :image,
-        'png32'        => :image,
-        'png48'        => :image,
-        'png64'        => :image,
-        'png8'         => :image,
-        'ps2'          => :image,
-        'ps3'          => :image,
-        'ptif'         => :image,
-        'pwp'          => :image,
-        'rad'          => :image,
-        'raf'          => :image,
-        'rfg'          => :image,
-        'rgba'         => :image,
-        'rla'          => :image,
-        'rle'          => :image,
-        'sct'          => :image,
-        'sfw'          => :image,
-        'sgf'          => :office,
-        'sgv'          => :office,
-        'slk'          => :office,
-        'sparse-color' => :image,
-        'sun'          => :image,
-        'svm'          => :office,
-        'sylk'         => :office,
-        'tim'          => :image,
-        'txt'          => :plaintext,
-        'uil'          => :image,
-        'uof'          => :office,
-        'uop'          => :office,
-        'uos'          => :office,
-        'uot'          => :office,
-        'uyvy'         => :image,
-        'vds'          => :office,
-        'vdx'          => :office,
-        'vicar'        => :image,
-        'viff'         => :image,
-        'vsdx'         => :office,
-        'webm'         => :video,
-        'wb2'          => :office,
-        'wk1'          => :office,
-        'wk3'          => :office,
-        'wn'           => :office,
-        'wpg'          => :image,
-        'wq1'          => :office,
-        'wq2'          => :office,
-        'x'            => :image,
-        'x3f'          => :image,
-        'xcf'          => :image,
-        'xlk'          => :office,
-        'xlsx'         => :office,
-        'xls'          => :office,
-        'ycbcr'        => :image,
-        'ycbcra'       => :image,
-        'yuv'          => :image,
-        'zabw'         => :office}.freeze
-      # spellchecker:enable
-
-      private_constant :SUPPORTED_MIME_TYPES, :SUPPORTED_EXTENSIONS
+      private_constant :SUPPORTED_MIME_TYPES
 
       # @attr use_mimemagic [bool] true to use mimemagic to determine real mime type based on file content
       attr_accessor :use_mimemagic
@@ -279,16 +55,26 @@ module Aspera
         @use_mimemagic = false
       end
 
+      # @param mimetype [String] mime type
+      # @return file type, one of enum CONVERSION_TYPES
+      def mime_to_type(mimetype)
+        return SUPPORTED_MIME_TYPES[mimetype] if SUPPORTED_MIME_TYPES.key?(mimetype)
+        return :office if mimetype.start_with?('application/vnd.')
+        return :video if mimetype.start_with?('video/')
+        return :image if mimetype.start_with?('image/')
+        return nil
+      end
+
       # use mime magic to find mime type based on file content (magic numbers)
-      def mime_from_file(filepath)
-        # moved here, as mimemagic can cause installation issues
+      def file_to_mime(filepath)
+        # moved here, as `mimemagic` can cause installation issues
         require 'mimemagic'
         require 'mimemagic/version'
         require 'mimemagic/overlay' if MimeMagic::VERSION.start_with?('0.3.')
         # check magic number inside file (empty string if not found)
         detected_mime = MimeMagic.by_magic(File.open(filepath)).to_s
         # check extension only
-        if !SUPPORTED_MIME_TYPES.key?(detected_mime)
+        if mime_to_type(detected_mime).nil?
           Log.log.debug{"no conversion for #{detected_mime}, trying extension"}
           detected_mime = MimeMagic.by_extension(File.extname(filepath)).to_s
         end
@@ -297,18 +83,19 @@ module Aspera
         return detected_mime
       end
 
-      # return file type, one of enum CONVERSION_TYPES
       # @param filepath [String] full path to file
-      # @param mimetype [String] provided by node api
+      # @param mimetype [String] provided by node API
+      # @return file type, one of enum CONVERSION_TYPES
+      # @raise [RuntimeError] if no conversion type found
       def conversion_type(filepath, mimetype)
         Log.log.debug{"conversion_type(#{filepath},m=#{mimetype},t=#{@use_mimemagic})"}
         # 1- get type from provided mime type, using local mapping
-        conversion_type = SUPPORTED_MIME_TYPES[mimetype] if !mimetype.nil?
+        conversion_type = mime_to_type(mimetype) if !mimetype.nil?
         # 2- else, from computed mime type (if available)
         if conversion_type.nil? && @use_mimemagic
-          detected_mime = mime_from_file(filepath)
+          detected_mime = file_to_mime(filepath)
           if !detected_mime.nil?
-            conversion_type = SUPPORTED_MIME_TYPES[detected_mime]
+            conversion_type = mime_to_type(detected_mime)
             if !mimetype.nil?
               if mimetype.eql?(detected_mime)
                 Log.log.debug('matching mime type per magic number')
@@ -320,9 +107,10 @@ module Aspera
           end
         end
         # 3- else, from extensions, using local mapping
-        extension = File.extname(filepath.downcase)[1..-1]
-        conversion_type = SUPPORTED_EXTENSIONS[extension] if conversion_type.nil?
-        Log.log.debug{"conversion_type(#{extension}): #{conversion_type.class.name} [#{conversion_type}]"}
+        mime_by_ext = MIME::Types.of(File.basename(filepath)).first
+        conversion_type = mime_to_type(mime_by_ext.to_s) if conversion_type.nil? && !mime_by_ext.nil?
+        raise "no conversion type found for #{File.basename(filepath)}" if conversion_type.nil?
+        Log.log.trace1{"conversion_type(#{File.basename(filepath)}): #{conversion_type.class.name} [#{conversion_type}]"}
         return conversion_type
       end
     end

data/lib/aspera/preview/generator.rb

@@ -2,12 +2,14 @@
 
 # ffmpeg options:
 # spellchecker:ignore pauseframes libx264 trunc bufsize muxer apng libmp3lame maxrate posterize movflags faststart
-# spellchecker:ignore palettegen paletteuse pointsize bordercolor repage lanczos
+# spellchecker:ignore palettegen paletteuse pointsize bordercolor repage lanczos unoconv optipng reencode conv transframes
 
 require 'open3'
 require 'aspera/preview/options'
 require 'aspera/preview/utils'
 require 'aspera/preview/file_types'
+require 'aspera/log'
+require 'aspera/assert'
 
 module Aspera
   module Preview
@@ -19,6 +21,7 @@ module Aspera
       FFMPEG_OPTIONS_LIST = %w[in out].freeze
 
       # CLI needs to know conversion type to know if need skip it
+      # one of CONVERSION_TYPES
       attr_reader :conversion_type
 
       # @param src source file path
@@ -32,55 +35,40 @@ module Aspera
       #   -> preview_format is one of Generator::PREVIEW_FORMATS
       # the conversion video->mp4 is implemented in methods: convert_video_to_mp4_using_<video_conversion>
       #  -> conversion method is one of Generator::VIDEO_CONVERSION_METHODS
-      def initialize(options, src, dst, main_temp_dir, api_mime_type)
-        @options = options
+      def initialize(src, dst, options, main_temp_dir, api_mime_type)
         @source_file_path = src
         @destination_file_path = dst
+        @options = options
         @temp_folder = File.join(main_temp_dir, @source_file_path.split('/').last.gsub(/\s/, '_').gsub(/\W/, ''))
         # extract preview format from extension of target file
-        @preview_format_symb = File.extname(@destination_file_path).gsub(/^\./, '').to_sym
-        @conversion_type = FileTypes.instance.conversion_type(@source_file_path, api_mime_type)
-      end
-
-      # name of processing method in this object
-      # combination of: conversion type and output format (and video_conversion for video)
-      def processing_method_symb
-        name = "convert_#{@conversion_type}_to_#{@preview_format_symb}"
-        if @conversion_type.eql?(:video)
-          case @preview_format_symb
+        @preview_format_sym = File.extname(@destination_file_path).gsub(/^\./, '').to_sym
+        conversion_type = FileTypes.instance.conversion_type(@source_file_path, api_mime_type)
+        @processing_method = "convert_#{conversion_type}_to_#{@preview_format_sym}"
+        if conversion_type.eql?(:video)
+          case @preview_format_sym
           when :mp4
-            name = "#{name}_using_#{@options.video_conversion}"
+            @processing_method = "#{@processing_method}_using_#{@options.video_conversion}"
           when :png
-            name = "#{name}_using_#{@options.video_png_conv}"
+            @processing_method = "#{@processing_method}_using_#{@options.video_png_conv}"
           end
         end
-        Log.log.debug{"method: #{name}"}
-        return name.to_sym
-      end
-
-      # @return true if conversion is supported.
-      # for instance, plaintext to mp4 is not supported
-      def supported?
-        return false if @conversion_type.nil?
-        return respond_to?(processing_method_symb, true)
+        @processing_method = @processing_method.to_sym
+        Log.log.debug{"method: #{@processing_method}"}
+        assert(respond_to?(@processing_method, true)){"no processing know for #{conversion_type} -> #{@preview_format_sym}"}
       end
 
       # create preview as specified in constructor
       def generate
-        raise 'could not detect type of file' if @conversion_type.nil?
-        method_symb = processing_method_symb
-        Log.log.info{"#{@source_file_path}->#{@destination_file_path} (#{method_symb})"}
+        Log.log.info{"#{@source_file_path}->#{@destination_file_path} (#{@processing_method})"}
         begin
-          send(method_symb)
+          send(@processing_method)
           # check that generated size does not exceed maximum
           result_size = File.size(@destination_file_path)
-          if result_size > @options.max_size
-            Log.log.warn{"preview size exceeds maximum allowed #{result_size} > #{@options.max_size}"}
-          end
+          Log.log.warn{"preview size exceeds maximum allowed #{result_size} > #{@options.max_size}"} if result_size > @options.max_size
         rescue StandardError => e
           Log.log.error{"Ignoring: #{e.message}"}
           Log.log.debug(e.backtrace.join("\n").red)
-          FileUtils.cp(File.expand_path(@preview_format_symb.eql?(:mp4) ? 'video_error.png' : 'image_error.png', File.dirname(__FILE__)), @destination_file_path)
+          FileUtils.cp(File.expand_path(@preview_format_sym.eql?(:mp4) ? 'video_error.png' : 'image_error.png', File.dirname(__FILE__)), @destination_file_path)
         ensure
           FileUtils.rm_rf(@temp_folder)
         end
@@ -100,7 +88,7 @@ module Aspera
       # @param total_count of parts
       # @param index of part (start at 1)
       def get_offset(duration, start_offset, total_count, index)
-        raise 'duration must be Float' unless duration.is_a?(Float)
+        assert_type(duration, Float){'duration'}
         return start_offset + ((index - 1) * (duration - start_offset) / total_count)
       end
 
@@ -134,8 +122,8 @@ module Aspera
       # generate n clips starting at offset
       def convert_video_to_mp4_using_clips
         p_duration = Utils.video_get_duration(@source_file_path)
-        filelist = File.join(this_tmpdir, 'clip_files.txt')
-        File.open(filelist, 'w+') do |f|
+        file_list_file = File.join(this_tmpdir, 'clip_files.txt')
+        File.open(file_list_file, 'w+') do |f|
           1.upto(@options.clips_count.to_i) do |i|
             offset_seconds = get_offset(p_duration, @options.video_start_sec.to_i, @options.clips_count.to_i, i)
             tmp_file_name = format('clip%04d.mp4', i)
@@ -153,19 +141,20 @@ module Aspera
         end
         # concat clips
         Utils.ffmpeg(
-          in_f: filelist,
+          in_f: file_list_file,
           in_p: ['-f', 'concat'],
           out_f: @destination_file_path,
           out_p: ['-codec', 'copy'])
+        File.delete(file_list_file)
       end
 
       # do a simple re-encoding
       def convert_video_to_mp4_using_reencode
         options = @options.reencode_ffmpeg
-        raise 'reencode_ffmpeg must be a Hash' unless options.is_a?(Hash)
+        assert_type(options, Hash){'reencode_ffmpeg'}
         options.each do |k, v|
-          raise "Key not supported: #{k}. Use keys: #{FFMPEG_OPTIONS_LIST.join(',')}" unless FFMPEG_OPTIONS_LIST.include?(k)
-          raise "Value for #{k} must be Array" unless v.is_a?(Array)
+          assert_values(k, FFMPEG_OPTIONS_LIST){'key'}
+          assert_type(v, Array){k}
         end
         Utils.ffmpeg(
           in_f: @source_file_path,

data/lib/aspera/preview/options.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# cspell:ignore reencode conv transframes pauseframes
+
 module Aspera
   module Preview
     # generator options. Used as parameter to preview generator object.

data/lib/aspera/preview/terminal.rb

@@ -2,36 +2,54 @@
 
 # cspell:words Magick MAGICKCORE ITERM mintty winsize termcap
 
-require 'rmagick' # https://rmagick.github.io/index.html
 require 'rainbow'
 require 'io/console'
 module Aspera
   module Preview
-    # Generates a string that can display an image in a terminal
+    # Display a picture in the terminal, either using coloured characters or iTerm2
     class Terminal
-      # quantum depth is 8 or 16: convert xc: -format "%q" info:
       # Rainbow only supports 8-bit colors
-      SHIFT_FOR_8_BIT = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
-      ITERM_NAMES = %w[iTerm WezTerm mintty].freeze
+      # env vars to detect terminal type
       TERM_ENV_VARS = %w[TERM_PROGRAM LC_TERMINAL].freeze
-      private_constant :SHIFT_FOR_8_BIT, :ITERM_NAMES, :TERM_ENV_VARS
+      # terminal names that support iTerm2 image display
+      ITERM_NAMES = %w[iTerm WezTerm mintty].freeze
+      # TODO: retrieve terminal font ratio using some termcap ?
+      # ratio = font height / font width
+      DEFAULT_FONT_RATIO = 32.0 / 14.0
+      private_constant :TERM_ENV_VARS, :ITERM_NAMES, :DEFAULT_FONT_RATIO
       class << self
-        def build(blob, reserved_lines: 0, double_precision: true)
-          return iterm_display_image(blob) if iterm_supported?
+        # @return [String] the image as text, or the iTerm2 escape sequence
+        # @param blob [String] the image as a binary string
+        # @param reserve [Integer] number of lines to reserve for other text than the image
+        # @param text [Boolean] true to display the image as text, false to use iTerm2
+        # @param double [Boolean] true to use colors on half lines, false to use colors on full lines
+        # @param font_ratio [Float] ratio = font height / font width
+        def build(blob, reserve: 3, text: false, double: true, font_ratio: DEFAULT_FONT_RATIO)
+          return iterm_display_image(blob) if iterm_supported? && !text
+          begin
+            # do not require statically, as the package is optional
+            require 'rmagick' # https://rmagick.github.io/index.html
+          rescue LoadError => e
+            Log.log.error('Install missing gem: gem install rmagick')
+            # fallback to iterm, if supported
+            return iterm_display_image(blob) if iterm_supported?
+            Log.log.error('Cant display picture.')
+            raise e
+          end
           image = Magick::ImageList.new.from_blob(blob)
           (term_rows, term_columns) = IO.console.winsize
-          term_rows -= reserved_lines
+          term_rows -= reserve
           # compute scaling to fit terminal
           fit_term_ratio = [term_rows / image.rows.to_f, term_columns / image.columns.to_f].min
-          # TODO: retrieve terminal font ratio using some termcap ?
-          font_ratio = 1.7
-          height_ratio = double_precision ? 2.0 : 1.0
+          height_ratio = double ? 2.0 : 1.0
           image = image.scale((image.columns * fit_term_ratio * font_ratio).to_i, (image.rows * fit_term_ratio * height_ratio).to_i)
+          # quantum depth is 8 or 16, see: `convert xc: -format "%q" info:`
+          shift_for_8_bit = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
           # get all pixel colors, adjusted for Rainbow
           pixel_colors = []
           image.each_pixel do |pixel, col, row|
             pixel_rgb = [pixel.red, pixel.green, pixel.blue]
-            pixel_rgb = pixel_rgb.map { |color| color >> SHIFT_FOR_8_BIT } unless SHIFT_FOR_8_BIT.eql?(0)
+            pixel_rgb = pixel_rgb.map { |color| color >> shift_for_8_bit } unless shift_for_8_bit.eql?(0)
             # init 2-dim array
             pixel_colors[row] ||= []
             pixel_colors[row][col] = pixel_rgb
@@ -39,10 +57,10 @@ module Aspera
           # now generate text
           text_pixels = []
           pixel_colors.each_with_index do |row_data, row|
-            next if double_precision && row.odd?
+            next if double && (row.odd? || row.eql?(pixel_colors.length - 1))
             row_data.each_with_index do |pixel_rgb, col|
               text_pixels.push("\n") if col.eql?(0) && !row.eql?(0)
-              if double_precision
+              if double
                 text_pixels.push(Rainbow('▄').background(pixel_rgb).foreground(pixel_colors[row + 1][col]))
               else
                 text_pixels.push(Rainbow(' ').background(pixel_rgb))
@@ -53,8 +71,10 @@ module Aspera
         end
 
         # display image in iTerm2
+        # https://iterm2.com/documentation-images.html
         def iterm_display_image(blob)
           # image = Magick::ImageList.new.from_blob(blob)
+          # parameters for iTerm2 image display
           arguments = {
             inline:              1,
             preserveAspectRatio: 1,
@@ -63,7 +83,7 @@ module Aspera
             # height:              image.rows
           }.map { |k, v| "#{k}=#{v}" }.join(';')
           # \a is BEL, \e is ESC : https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
-          # https://iterm2.com/documentation-images.html
+          # escape sequence for iTerm2 image display
           return "\e]1337;File=#{arguments}:#{Base64.encode64(blob)}\a"
         end