image_paradise 0.4.8

data/lib/image_paradise/toplevel_methods/misc.rb

@@ -0,0 +1,1407 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'image_paradise/toplevel_methods/misc.rb'
+# ImageParadise.resize_by_percent
+# ImageParadise.draw_as_specified_from_the_yaml_file
+# ImageParadise.magic_card_border
+# ImageParadise.rounded_corner(ARGV)
+# ImageParadise.img2pdf(ARGV)
+# =========================================================================== #
+module ImageParadise
+
+  require 'fileutils'
+  require 'image_paradise/project/project.rb'
+  require 'image_paradise/toplevel_methods/esystem.rb'
+  require 'image_paradise/toplevel_methods/is_an_image_file.rb'
+
+  # ========================================================================= #
+  # === @hash
+  # ========================================================================= #
+  @hash = {}
+
+  # ========================================================================= #
+  # === :store_image_files_in_this_directory
+  # ========================================================================= #
+  @hash[:store_image_files_in_this_directory] = nil
+
+  # ========================================================================= #
+  # === ImageParadise.remove_comment
+  # ========================================================================= #
+  def self.remove_comment(i)
+    i = i.to_s
+    esystem 'convert '+i+' -strip -set comment "" new_'+i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.resize_by_percent
+  #
+  # This method will make use of ImageMagick to resize an image. So,
+  # naturally, in order to use this functionality the user has to
+  # have the "convert" binary which is part of ImageMagick.
+  #
+  # The direct API would be like this:
+  #
+  #   convert -resize <new size in %> <name of existing image> <name of new image>
+  #   convert -resize 40% image1.jpg output.jpg
+  #
+  # ========================================================================= #
+  def self.resize_by_percent(
+      path_to_the_image = '',
+      by_how_much       = :default # 75% percent is default.
+    )
+    case path_to_the_image
+    when /^-?-?help$/i
+      e 'The general syntax is:'
+      e
+      e '  shrink foobar.jpg 40%'
+      e '  shrink /Depot/jj/LEGO_COP.png 40%'
+      exit
+    end
+    by_how_much = by_how_much.first if by_how_much.is_a? Array
+    case by_how_much
+    when nil, :default
+      by_how_much = 75
+    end
+    by_how_much = by_how_much.to_s # Must be a String past this point.
+    # ======================================================================= #
+    # Work on the input as Array next:
+    # ======================================================================= #
+    [path_to_the_image].flatten.compact.each {|path_to_this_image|
+      if File.exist? path_to_this_image
+        by_how_much << '%' unless by_how_much.end_with?('%')
+        output_filename = File.absolute_path(
+          'output_'+
+          File.basename(path_to_this_image)
+        )
+        # =================================================================== #
+        # Build up the command next:
+        # =================================================================== #
+        cmd = "convert -resize #{by_how_much} #{path_to_this_image} #{output_filename}"
+        esystem(cmd)
+      else
+        e "No file exists at #{path_to_this_image}."
+      end
+    }
+  end; self.instance_eval { alias resize_by_percentage resize_by_percent } # === ImageParadise.resize_by_percentage
+       self.instance_eval { alias percent              resize_by_percent } # === ImageParadise.percent
+
+  # ========================================================================= #
+  # === ImageParadise.remove_metadata_from_this_image
+  #
+  # This method will strip meta-data from an image.
+  # ========================================================================= #
+  def self.remove_metadata_from_this_image(
+      i, output_file = :default
+    )
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = "output_#{i}"
+    end
+    _ = "convert -strip #{i} #{output_file}"
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.store_image_files_in_this_directory=
+  # ========================================================================= #
+  def self.store_image_files_in_this_directory=(
+    i = '/home/x/data/images/STUDIUM/'
+    )
+    i << '/' unless i.end_with? '/' # Directories must have a trailing '/' token.
+    @hash[:store_image_files_in_this_directory] = i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.store_image_files_in_this_directory?
+  # ========================================================================= #
+  def self.store_image_files_in_this_directory?
+    @hash[:store_image_files_in_this_directory]
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.log_dir?
+  # ========================================================================= #
+  def self.log_dir?
+    '/tmp/image_paradise/'
+  end; self.instance_eval { alias log_directory? log_dir? } # === ImageParadise.log_directory?
+
+  # ========================================================================= #
+  # === ImageParadise.increment_this_number_by_one
+  # ========================================================================= #
+  def self.increment_this_number_by_one(basename)
+    basename = basename.dup
+    scanned = basename.scan(/\d+$/).flatten.first.to_s
+    # ======================================================================= #
+    # scanned may now be '019'.
+    # ======================================================================= #
+    new_number = scanned.to_i + 1
+    # ======================================================================= #
+    # We must also look to expand to its original size again.
+    # ======================================================================= #
+    new_number = new_number.to_s.rjust(scanned.size, '0')
+    basename.sub!(/\d+$/, new_number)
+    basename
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.return_draw_rectangle
+  #
+  # This method will return the commandline option to use for drawing
+  # a rectangle via the commandline.
+  # ========================================================================= #
+  def self.return_draw_rectangle(
+      start_position  = [10, 10], # This is the x,y start position.
+      end_position    = [70, 90], # This is width, then height.
+      use_this_colour = :black
+    )
+    "-fill #{use_this_colour} "\
+    "-draw "\
+    "'rectangle #{start_position[0]},#{start_position[1]} "\
+               "#{end_position[0]},#{end_position[1]}'" # Width.
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.add_this_comment_to_that_image
+  #
+  # This method can be used to add a comment to an image.
+  #
+  # The first argument is the comment that the user wants to add to a
+  # particular image.
+  # ========================================================================= #
+  def self.add_this_comment_to_that_image(
+      comment,
+      image       = 'foobar.png',
+      output_file = :default
+    )
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = "output_#{File.basename(image)}"
+    end
+    _ = 'convert -comment "'+comment.to_s+'" '+image+' '+
+         output_file
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.gamma_correct_this_image
+  #
+  # Note that red, green and blue specifiy the gamma correction for each
+  # colour channel in the image.
+  # ========================================================================= #
+  def self.gamma_correct_this_image(
+      i,
+      red   = :default,
+      green = :default,
+      blue  = :default
+    )
+    case red
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      red = 0.7
+    end
+    case green
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      green = red
+    end
+    case blue
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      blue = red
+    end
+    _ = 'convert -gamma '+red.to_s+
+        ','+green.to_s+','+
+        blue.to_s+' '+i+' '+
+        'output_'+File.basename(i)
+    esystem _ 
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.morph_these_images
+  #
+  # This method can be used to morph together two images.
+  #
+  # This is currently hardcoded/set to two images as input.
+  #
+  # Any files that will be newly created OTHER than the main
+  # output file will be deleted.
+  # ========================================================================= #
+  def self.morph_these_images(
+      image1,
+      image2,
+      output_file = :default
+    )
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = 'output.png'
+    end
+    _ = 'convert -morph 1,2 '+image1.to_s+' '+image2.to_s+' '+
+        output_file
+    esystem _
+    modified_output_filename = output_file.sub(/\./,'-1.')
+    if File.exist? modified_output_filename
+      FileUtils.mv(modified_output_filename, output_file)
+    end
+    # ======================================================================= #
+    # Next, clean up a bit.
+    # ======================================================================= #
+    if File.exist? output_file.sub(/\./,'-0.')
+      File.delete(output_file.sub(/\./,'-0.'))
+    end
+    if File.exist? output_file.sub(/\./,'-2.')
+      File.delete(output_file.sub(/\./,'-2.'))
+    end
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.circle_masked
+  #
+  # This will "paint" a circle over the main image in use.
+  #
+  # Usage example:
+  #
+  #   ImageParadise.circle_masked('SANDRA.jpg')
+  #   ImageParadise.circle_masked('SANDRA.jpg', 'output.png')
+  #
+  # ========================================================================= #
+  def self.circle_masked(
+      i           = '*.jpg',
+      output_file = 'output.png'
+    )
+    _ = 'convert '+i.to_s+' -alpha set \( +clone -distort DePolar 0 '\
+        '-virtual-pixel HorizontalTile -background None -distort Polar '\
+        '0 \) -compose Dst_In -composite -trim +repage '+
+        output_file.to_s
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.torn_paper
+  #
+  # This will create a torn-paper effect.
+  #
+  # Usage example:
+  #
+  #   ImageParadise.torn_paper('SANDRA.jpg')
+  #   ImageParadise.torn_paper('SANDRA.jpg', 'output.png')
+  #
+  # ========================================================================= #
+  def self.torn_paper(
+      i           = '*.jpg',
+      threshold   = :default, # This means 50, basically.
+      output_file = :default
+    )
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = 'output.png'
+    end
+    case threshold
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      threshold = 50
+    end
+    _ = 'convert '+i.to_s+' \( +clone -alpha extract -virtual-pixel '\
+        'black -spread 10 -blur 0x3 -threshold '+threshold.to_s+
+        '% -spread 1 -blur 0x.7 \) '\
+        ' -alpha off -compose Copy_Opacity -composite '+
+        output_file.to_s
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.shadow
+  #
+  # This will create a shadow effect. The second argument is the colour
+  # that can be used, defaulting to :steelblue if omitted.
+  #
+  # Usage example:
+  #
+  #   ImageParadise.shadow('Leeann_Tweeden.png', :blue)
+  #
+  # ========================================================================= #
+  def self.shadow(
+      i             = '*.jpg',
+      colour_to_use = :default, # This means 50, basically.
+      output_file   = :default,
+      width         = 3 # 3px width.
+    )
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = 'output.png'
+    end
+    case colour_to_use
+    when :default
+      colour_to_use = :steelblue
+    end
+    _ = 'convert '+i.to_s+' -alpha set '\
+        '\( +clone -background '+
+        colour_to_use.to_s+' -shadow 60x0+'+width.to_s+'+'+width.to_s+' \) '\
+        '+swap -background none -mosaic '+
+        output_file.to_s
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.add_this_text_to_the_image
+  #
+  # This method can be used to add text to a given image.
+  #
+  # Usage examples:
+  #
+  #   ImageParadise.add_this_text_to_the_image('fun inside','Susanne_03.jpg')
+  #   ImageParadise.add_this_text_to_the_image('fun inside','Susanne_03.jpg', :lightgreen)
+  #
+  # ========================================================================= #
+  def self.add_this_text_to_the_image(
+      this_text                  = 'Foobar and Hello World!',
+      image                      = 'foobar.png',
+      use_this_background_colour = :white, # :khaki
+      output_image               = 'output.png',
+      append_or_prepend          = :append
+    )
+    _ = 'convert '+image.to_s+
+        ' -background '+use_this_background_colour.to_s+' '
+    _ << '-font Times-New-Roman -pointsize 25 '
+    _ << " label:'#{this_text}' ".dup 
+    _ << '+swap ' if append_or_prepend == :prepend
+    _ << '-gravity center '\
+         '-append '+ # -append means "add to the bottom of the image.
+         output_image
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.montage
+  #
+  # This will aggregate the images together into one big image, the
+  # "montage".
+  #
+  # By default this method will pick up all .jpg files from the current
+  # working directory.
+  # ========================================================================= #
+  def self.montage(
+      i                             = '*.jpg',
+      output_file                   = :default,
+      shall_we_autolabel_the_images = false,
+      frame_value_to_use            = '-frame 2'
+    )
+    case shall_we_autolabel_the_images
+    when :do_autolabel
+      shall_we_autolabel_the_images = true
+    end
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = 'output.png'
+    end
+    cmd = "montage".dup
+    if shall_we_autolabel_the_images
+      cmd << ' -label %f'
+    end
+    cmd << " #{frame_value_to_use}"
+    cmd << " #{i}"
+    cmd << " #{output_file}"
+    esystem cmd
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.chop_away_outer_pixels
+  #
+  # This method will chop away outer pixels from a given image.
+  # ========================================================================= #
+  def self.chop_away_outer_pixels(
+      i                  = 'foobar.png',
+      chop_away_n_pixels = 5, # 5px
+      output_file        = 'output.png'
+    )
+    esystem "convert -gravity NorthWest -chop "\
+            "#{chop_away_n_pixels}x#{chop_away_n_pixels} "\
+            "-trim #{i} "\
+            "#{output_file}" 
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.blur
+  #
+  # The blur command-line option of ImageMagick applies a Gaussian-based
+  # blurring operation to the given image at hand. It is also called
+  # "gaussian".
+  #
+  # The argument that has to be provided is the radius of the blur, 
+  # with an optional standard deviation.
+  #
+  # The default for this method is to specify just a radius, without
+  # a standard deviation. If you want to specify a standard deviation
+  # as well, use something like "12x2" rather than e. g. "12" for the
+  # radius_to_apply argument.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.blur "Water.jpg"
+  #
+  # ========================================================================= #
+  def self.blur(
+      i               = 'foobar.png',
+      radius_to_apply = 12, # 5px
+      output_file     = 'output.png'
+    )
+    esystem "convert "\
+            "-blur #{radius_to_apply} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.charcoal
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.charcoal "Water.jpg"
+  #
+  # ========================================================================= #
+  def self.charcoal(
+      i               = 'foobar.png',
+      radius_to_apply = 4, # 5px
+      output_file     = 'output.png'
+    )
+    esystem "convert "\
+            "-charcoal #{radius_to_apply} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.colour_fill_this_image
+  #
+  # This method can be used to fill an image with a specific colour,
+  # such as blue or green. It's like you overlay that colour over
+  # the given image at hand.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.colour_fill_this_image("Water.jpg", :blue, '33%', 'output.png')
+  #
+  # ========================================================================= #
+  def self.colour_fill_this_image(
+      i               = 'foobar.png',
+      colour_to_use   = :steelblue,
+      n_percent       = '10%',
+      output_file     = 'output.png'
+    )
+    esystem "convert "\
+            "-fill #{colour_to_use} "\
+            "-colorize #{n_percent.to_s.delete('%')} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.black_hole
+  #
+  # This method, alias aliased onto ImageParadise.implode, can transform
+  # an image starting from the center of said image, to look as if a black
+  # hole emerged. It will thus distort the image as if it is sucking the
+  # pixels into it.
+  #
+  # The implode command takes only one argument, which is the factor by
+  # which to apply the effect. The size of the effect on the image is
+  # that factor argument.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.implode("foobar.jpg", 2, 'output.png')
+  #
+  # ========================================================================= #
+  def self.black_hole(
+      i            = 'foobar.png',
+      implode_by_n = 1,
+      output_file  = 'output.png'
+    )
+    esystem "convert "\
+            "-implode #{implode_by_n} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end; self.instance_eval { alias implode black_hole } # === ImageParadise.implode
+
+  # ========================================================================= #
+  # === ImageParadise.noise
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.noise("foobar.jpg", 2, 'output.png')
+  #
+  # ========================================================================= #
+  def self.noise(
+      i           = 'foobar.png',
+      by_n        = 1,
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-noise #{by_n} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.raise
+  #
+  # The raise effect provides beveled edges for an image. You can
+  # specify the height and width for this bevel, as well as a
+  # direction for the bevel.
+  #
+  # 2x3 here means a horizontal bevel of 2 pixels and a
+  # vertical bevel size of 3 pixels.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.raise("foobar.jpg", '2x3', 'output.png')
+  #
+  # ========================================================================= #
+  def self.raise(
+      i           = 'foobar.png',
+      raise_by    = '2x2',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-raise #{raise_by} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.sepia_tone
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.sepia_tone("foobar.jpg", '80', 'output.png')
+  #
+  # ========================================================================= #
+  def self.sepia_tone(
+      i           = 'foobar.png',
+      n_percent   = '80',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-sepia-tone #{n_percent.to_s.delete('%')}% "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end; self.instance_eval { alias sepia_filter sepia_tone } # === ImageParadise.sepia_filter
+
+  # ========================================================================= #
+  # === ImageParadise.shade_transformation
+  #
+  # This will apply a shade onto the main image.
+  #
+  # A shade effect in this context refers to simulating having a distant
+  # light source cast a shadow on the image.
+  #
+  # This effect can be created by specifying an azimuth and elevation
+  # for the light source. The azimuth is the angle of the light source,
+  # with the following values:
+  #
+  #       0 degrees: north
+  #      90 degrees: east
+  #     180 degrees: south
+  #     270 degrees: west
+  #
+  # The elevation is the height of the light source. For example, to
+  # specify light from the east at height of 100, the following
+  # commandline can be used:
+  #
+  #   convert -shade 90x100 input.jpg output.jpg
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.shade_transformation("foobar.jpg", '80', 'output.png')
+  #
+  # ========================================================================= #
+  def self.shade_transformation(
+      i           = 'foobar.png',
+      modify_how  = '90x100',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-shade #{modify_how.to_s.delete('%')} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end; self.instance_eval { alias shade        shade_transformation } # === ImageParadise.shade
+       self.instance_eval { alias shade_effect shade_transformation } # === ImageParadise.shade_effect
+
+  # ========================================================================= #
+  # === ImageParadise.threshold
+  # ========================================================================= #
+  def self.threshold(
+      i           = 'foobar.png',
+      modify_how  = '90%',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-threshold #{modify_how.to_s} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.sharpen
+  #
+  # This method can be used to sharpen an existing image.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.sharpen("foobar.jpg", '3', 'output.png')
+  #
+  # ========================================================================= #
+  def self.sharpen(
+      i           = 'foobar.png',
+      modify_how  = '1',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-sharpen #{modify_how.to_s} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.wave
+  # ========================================================================= #
+  def self.wave(
+      i           = 'foobar.png',
+      modify_how  = '8x90%',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-wave #{modify_how.to_s} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.contrast
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.contrast("foobar.jpg", '1', 'output.png')
+  #
+  # ========================================================================= #
+  def self.contrast(
+      i           = 'foobar.png',
+      n_times     = '1',
+      output_file = 'output.png'
+    )
+    plus_or_minus = '-'
+    if n_times.is_a?(String) and n_times.start_with?('-')
+      plus_or_minus = '+'
+    end
+    contrast_string = "#{plus_or_minus}contrast " * n_times.to_i
+    esystem "convert "\
+            "#{contrast_string} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.reduce_contrast
+  # ========================================================================= #
+  def self.reduce_contrast(
+      i           = 'foobar.png',
+      n_times     = '-1',
+      output_file = 'output.png'
+    )
+    ImageParadise.contrast(i, n_times, output_file)
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.flip_this_image_up_to_bottom
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.flip_this_image_up_to_bottom("/Depot/NJOY/WaterGirl.png", 'output.png')
+  #
+  # ========================================================================= #
+  def self.flip_this_image_up_to_bottom(
+      i           = 'foobar.png',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-flip "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end; self.instance_eval { alias flip_image_up_to_bottom flip_this_image_up_to_bottom } # === ImageParadise.flip_image_up_to_bottom
+
+  # ========================================================================= #
+  # === ImageParadise.solarize
+  #
+  # This method can be used to lighten-up an existing image.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.solarize("foobar.jpg", '3', 'output.png')
+  #
+  # ========================================================================= #
+  def self.solarize(
+      i           = 'foobar.png',
+      modify_how  = '90',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-solarize #{modify_how.to_s} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.normalize
+  #
+  # Normalization is the process of improving the contrast in an image
+  # so that it uses all the available color range.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.normalize("foobar.jpg",  'output.png')
+  #
+  # ========================================================================= #
+  def self.normalize(
+      i           = 'foobar.png',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-normalize "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.shear
+  #
+  # The shear effect puts the input image at an angle. You can tilt
+  # the image horizontally and vertically in both directions (in other
+  # words, from left to right, from right to left, from top to bottom,
+  # and from bottom to top).
+  #
+  # The tilt is specified as an angle; for example, in the
+  # horizontal direction, a negative tilt is a tilt to the left,
+  # and a positive tilt is a tilt to the right.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.shear("foobar.jpg",  'output.png')
+  #
+  # ========================================================================= #
+  def self.shear(
+      i           = 'foobar.png',
+      modify_how  = '45',
+      output_file = 'output.png'
+    )
+    esystem "convert "\
+            "-shear #{modify_how.to_s} "\
+            "#{i} "\
+            "#{output_file}"
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.horizontal_append
+  #
+  # This will append images together, in a vertical manner.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.horizontal_append(["foobar1.jpg", "foobar2.jpg"], 'output.png')
+  #
+  # ========================================================================= #
+  def self.horizontal_append(
+      these_images       = ARGV,
+      output_file        = 'output.png',
+      use_this_as_border = nil
+    )
+    cmd = "convert +append #{these_images.join(' ')}".dup
+    cmd << " #{output_file}"
+    if use_this_as_border
+      cmd << "-border #{use_this_as_border}"
+    end
+    esystem cmd
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.vertical_append
+  #
+  # This will append images together, in a vertical manner.
+  #
+  # Invocation example:
+  #
+  #   ImageParadise.vertical_append(["foobar1.jpg", "foobar2.jpg"], 'output.png')
+  #
+  # ========================================================================= #
+  def self.vertical_append(
+      these_images       = ARGV,
+      output_file        = 'output.png',
+      use_this_as_border = nil
+    )
+    cmd = "convert -append #{these_images.join(' ')}".dup
+    cmd << " #{output_file}"
+    if use_this_as_border
+      cmd << "-border #{use_this_as_border}"
+    end
+    esystem cmd
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.to_webp
+  #
+  # This will convert the given image to the WebP format.
+  # ========================================================================= #
+  def self.to_webp(
+      this_image,
+      output_file    = :append,
+      quality_to_use = 80
+    )
+    case output_file
+    # ======================================================================= #
+    # === :append
+    # ======================================================================= #
+    when :append,
+         :default
+      output_file = this_image.dup.delete_suffix(
+        File.extname(this_image)
+      )+'.webp'
+    end
+    esystem 'magick '+this_image+
+            ' -quality '+quality_to_use.to_s+
+            ' -define webp:lossless=true '+
+            output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.rounded_corner_for_jpg_files
+  #
+  # This method is specifically for .jpg files.
+  # ========================================================================= #
+  def self.rounded_corner_for_jpg_files(i = '*jpg')
+    _ = 'convert '+i.to_s+' \
+    \( +clone -crop 16x16+0+0  -fill white -colorize 100% \
+       -draw \'fill black circle 15,15 15,0\' \
+       -background White  -alpha shape \
+       \( +clone -flip \) \( +clone -flop \) \( +clone -flip \) \
+     \) -flatten rounded_corners_white.jpg'
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.rounded_corner
+  #
+  # This method can create a rounded corner to an existing image.
+  #
+  # The polygon value allows one to create ellipsoid areas, which
+  # ultimately is the effect that you can see in a "rounded corner"
+  # image.
+  #
+  # Usage example:
+  #
+  #   ImageParadise.rounded_corner 'RandomBeachGal.jpg'
+  #
+  # ========================================================================= #
+  def self.rounded_corner(
+     i             = 'input_image.png',
+     output_file   = :default,
+     black_polygon = '0,0 0,15 15,0'
+    )
+    if i.is_a? Array
+      i = i.join(' ').strip
+    end
+    i = i.to_s
+    case output_file
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      output_file = File.absolute_path(File.basename("output_#{i}"))
+    end
+    _ = 'convert '+i+' '+
+        '\( +clone -alpha extract '+
+        '-draw \'fill black polygon '+black_polygon.to_s+
+        ' fill white circle 15,15 15,0\' '+
+        '\( +clone -flip \) -compose Multiply -composite '+
+        '\( +clone -flop \) -compose Multiply -composite '+
+        '\) -alpha off -compose CopyOpacity -composite '+
+        output_file.to_s
+    esystem _
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.return_draw_line
+  #
+  # We name the start point "Point A" and the end point "Point B".
+  # ========================================================================= #
+  def self.return_draw_line(
+      start_position  = [10, 10], # This is the x,y start position. Point A.
+      end_position    = [70, 90], # This is the x,y end position. Point B.
+      use_this_colour = :black,
+      optional_hash   = {}
+    )
+    _ = ''.dup
+    _ << "-fill #{use_this_colour} "
+    if optional_hash.has_key? :strokewidth
+      _ << "-stroke #{use_this_colour} "
+      _ << "-strokewidth #{optional_hash[:strokewidth].to_s} "
+    end
+    _ << '-draw '
+    _ << "'line #{start_position[0]},#{start_position[1]} "\
+               "#{end_position[0]},#{end_position[1]}'"
+    return _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.draw_as_specified_from_the_yaml_file
+  # ========================================================================= #
+  def self.draw_as_specified_from_the_yaml_file(
+      target_file =
+        # ::ImageParadise.project_base_directory?+'yaml/rectangle.yml',
+        ::ImageParadise.project_base_directory?+'yaml/circle.yml',
+      output_file = 'output.png'
+    )
+    require 'yaml'
+    if File.exist? target_file
+      key = 'circle'
+      dataset = YAML.load_file(target_file)
+      if dataset[key].has_key? 'resolution'
+        width, height = dataset[key]['resolution'].split('x')
+      else
+        e 'A key called `resolution` is mandatory.'
+        exit
+      end
+      _ = ''.dup
+      _ << 'convert'
+      if dataset[key].has_key? 'total_size'
+        _ << " -size #{dataset[key]['total_size']}"
+      else
+        _ << " -size #{500}x#{500}"
+      end
+      _ << ' -stroke '+dataset[key]['strokecolour'].to_s
+      _ << ' -strokewidth '+dataset[key]['strokewidth'].to_s
+      _ << ' -fill '+dataset[key]['fill_colour']
+      case key
+      when 'circle'
+        # The 250,250 part should be half the total size.
+        _ << ' -draw "circle 250,250 '+width.to_s+','+width.to_s+'"'
+      when 'rectangle'
+        if dataset[key]['round_rectangle'] == true
+          _ << ' -draw "roundRectangle 0,0 '+width.to_s+','+height.to_s+' 12,12"'
+        else
+          _ << ' -draw "rectangle 0,0 '+width.to_s+','+height.to_s+'"'
+        end
+      end
+      _ << ' xc:white'
+      _ << " #{output_file}"
+    end
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.drop_shadow_effect
+  #
+  # Note that this will create a border that is currently invariant.
+  # In the long run this may be different, allowing us to pick a
+  # border width, but for now, this is the way it is. 
+  #
+  # Usage example:
+  #
+  #   ImageParadise.drop_shadow_effect 'RandomBeachGal.jpg'
+  #
+  # ========================================================================= #
+  def self.drop_shadow_effect(
+     i               = 'input_image.png',
+     use_this_colour = :black,
+     output_file     = :default
+    )
+    if i.is_a? Array
+      i = i.join(' ').strip
+    end
+    i = i.to_s
+    case output_file
+    when :default
+      output_file = File.absolute_path(File.basename("output_#{i}"))
+    end
+    _ = 'convert '+i+' '+
+        '\( -clone 0 -background '+use_this_colour.to_s+
+        ' -shadow 80x3+12+12 \) \( -clone 0 -background '+use_this_colour+
+        ' -shadow 80x3-12-12 \)  -reverse -background none '\
+        '-layers merge +repage '+
+        output_file.to_s
+    esystem _
+    return output_file
+  end
+
+  # =========================================================================== #
+  # === ImageParadise.find_image_center
+  #
+  # gives back the image center
+  # =========================================================================== #
+  def self.find_image_center(image)
+    return [ (image.columns/2), (image.rows/2) ]
+  end
+
+  # =========================================================================== #
+  # === ImageParadise.create_shape
+  #
+  # This method can be used to create various pre-determined shapes,
+  # such as a gel.
+  # =========================================================================== #
+  def self.create_shape(
+      which_shape = :gel
+    )
+    case which_shape
+    # ========================================================================= #
+    # === :gel
+    #
+    # This will create a gel-shape - a fat ellipse.
+    # ========================================================================= #
+    when :gel,
+         :default
+      _ = "convert -size 100x60 xc:none 
+           -fill red -draw 'circle    25,30  10,30' 
+                     -draw 'circle    75,30  90,30' 
+                     -draw 'rectangle 25,15  75,45' 
+           gel_shape.png".tr("\n", ' ').squeeze(' ')
+      esystem _
+    end
+  end
+
+  # =========================================================================== #
+  # === ImageParadise.darken_the_borders
+  # =========================================================================== #
+  def self.darken_the_borders(
+      of_this_image = 'gel_shape.png'
+    )
+    _ = "convert "+of_this_image+" 
+          \( +clone -alpha extract -blur 0x2 -shade 0x90 -normalize 
+             -blur 0x2  +level 60,100%  -alpha On \)
+          -compose Multiply -composite "\
+          "gel_border.png".
+          tr("\n", ' ').squeeze(' ')
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.return_random_image
+  #
+  # This method will return a random image from the given argument, which
+  # is assumed to be a directory. It defaults to my home setup.
+  #
+  # A random image will then be returned, if there is at the least one
+  # image in that directory.
+  #
+  # Usage example for my home setup:
+  #
+  #   ImageParadise.return_random_image(:njoy)
+  #
+  # ========================================================================= #
+  def self.return_random_image(
+      i = Dir.pwd
+    )
+    # ======================================================================= #
+    # Handle special cases first.
+    # ======================================================================= #
+    case i
+    when 0, :adoptopn
+      i = ENV['IMG_RPG'].to_s+'/ADOPTION/'
+    # ======================================================================= #
+    # === njoy
+    # ======================================================================= #
+    when 1, :njoy
+      i = ENV['IMG'].to_s+'/NJOY/'
+    end
+    i = i.to_s.dup
+    unless i.end_with? '/'
+      i << '/'
+    end
+    if File.directory? i
+      all_entries = Dir["#{i}*"]
+      return all_entries.sample
+    else
+      raise 'This method (.return_random_image()) '\
+            'requires a valid directory as argument.'
+    end
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.identify_this_image
+  # ========================================================================= #
+  def self.identify_this_image(i)
+    result = `magick identify -format "%wx%h %xx%y" #{i}` # width-height and DPI
+    return result
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.default_position=
+  # ========================================================================= #
+  def self.default_position=(i = :default)
+    case i
+    # ======================================================================= #
+    # === :default
+    #
+    # This value can be changed to other values.
+    # ======================================================================= #
+    when :default
+      i = '35,125'
+    end
+    @hash[:default_position] = i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.default_position?
+  # ========================================================================= #
+  def self.default_position?
+    @hash[:default_position]
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.default_colour=
+  #
+  # This method can be used to set (assign) a default colour. Curiously
+  # enough, ImageMagick appears to default to black colour for text
+  # when writing something.
+  # ========================================================================= #
+  def self.default_colour=(i = :default) # :steelblue is the default colour
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      i = :steelblue
+    end
+    @hash[:default_colour] = i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.default_colour?
+  # ========================================================================= #
+  def self.default_colour?
+    @hash[:default_colour]
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.is_this_image_animated?
+  #
+  # Usage examples:
+  #
+  #   ImageParadise.is_this_image_animated?('/Depot/jjjj/NJOY/SneezAndPop.gif') # => true
+  #   ImageParadise.is_this_image_animated?("TANAKA.jpg")                       # => false
+  #
+  # ========================================================================= #
+  def self.is_this_image_animated?(i)
+    if i.is_a? Array
+      i = i.first
+    end
+    result = `identify -format "%n" #{i}`.to_i
+    result > 1
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.img2pdf
+  #
+  # This method depends on the external software (written in python)
+  # called img2pdf.
+  #
+  # This method will return the output-file that is generated.
+  # ========================================================================= #
+  def self.img2pdf(
+      work_on_these_files = '*.jpg'
+    )
+    if work_on_these_files.is_a?(Array) and work_on_these_files.empty?
+      work_on_these_files = '*.jpg'
+    end
+    if work_on_these_files.is_a?(String) and work_on_these_files.include?('*')
+      work_on_these_files = Dir[work_on_these_files] # Assume input such as '*.jpg'
+    end
+    work_on_these_files = work_on_these_files.join(' ').strip if work_on_these_files.is_a?(Array)
+    work_on_these_files_as_string = work_on_these_files
+    # ======================================================================= #
+    # Next we will determine the output-filename to use. This is important
+    # because if we use this method in a batch-manner then we do not want
+    # to overwrite the same output name - thus we need to make this a
+    # little bit more dynamic in its behaviour.
+    # ======================================================================= #
+    use_this_name = work_on_these_files_as_string
+    if use_this_name.include? ' '
+      use_this_name = 'aggregated_name'
+    end
+    # ======================================================================= #
+    # Next build the output-file. This needs to take the absolute
+    # path into consideration if the input contains a '/' token.
+    # ======================================================================= #
+    output_file = File.absolute_path(File.dirname(use_this_name))+
+                  '/output_aggregated_document_'+
+                  'taken_from_'+
+                  File.basename(
+                    use_this_name.delete_suffix(
+                      File.extname(use_this_name)
+                    )
+                  )+
+                  '.pdf'
+    cmd = 'img2pdf -o '+output_file+' '+
+           work_on_these_files_as_string
+    esystem(cmd)
+    return output_file
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.width_of_this_image?
+  # ========================================================================= #
+  def self.width_of_this_image?(i)
+    return `convert #{i} -print "%w" /dev/null`.to_i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.height_of_this_image?
+  #
+  # Usage example:
+  #
+  #   ImageParadise.height_of_this_image?("/home/x/data/images/fotos/urlaub/10.10.2004_Trieste_Miramare_Teich.jpg")
+  #
+  # ========================================================================= #
+  def self.height_of_this_image?(i)
+    return `convert #{i} -print "%h" /dev/null`.to_i
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.width_height_of_this_image?
+  #
+  # Usage example:
+  #
+  #   ImageParadise.width_height_of_this_image?("/home/x/data/images/fotos/urlaub/10.10.2004_Trieste_Miramare_Teich.jpg")
+  #
+  # ========================================================================= #
+  def self.width_height_of_this_image?(i)
+    return `convert #{i} -print "%wx%h" /dev/null`
+  end
+
+  # ========================================================================= #
+  # === ImageParadise.embed_the_filename_into_this_image
+  #
+  # This method will automatically attach the filename onto a
+  # particular images. So if the filename is "foobar.jpg" then
+  # the method will attach the word "foobar" to the image.
+  #
+  # The gravity-argument determines <b>where</b> the text will
+  # appear.
+  #
+  # The second argument to this method is the Hash that determines
+  # various options, such as font-size, which font to use and so
+  # forth.
+  #
+  # Usage examples:
+  #
+  #   ImageParadise.embed_the_filename_into_this_image('TANAKA.jpg')
+  #   ImageParadise.embed_the_filename_into_this_image('/foo/bar/')
+  #   ImageParadise.embed_the_filename_into_this_image('/Depot/jjj/NJOY/')
+  #
+  # ========================================================================= #
+  def self.embed_the_filename_into_this_image(
+      this_image = 'foobar.jpg',
+      hash_options = {
+        font_size:     30,
+        font_to_use:   'Luxi-Mono',
+        colour_to_use: :orangered # Or :white.
+      }
+    )
+    # ======================================================================= #
+    # Obtain the font size to use next:
+    # ======================================================================= #
+    font_size_to_use = hash_options[:font_size]
+    use_this_font    = hash_options[:font_to_use]
+    colour_to_use    = hash_options[:colour_to_use]
+    this_image = [this_image].flatten.compact
+    if this_image and this_image.first and
+       File.directory?(this_image.first)
+      # ===================================================================== #
+      # Working on a directory instead.
+      # ===================================================================== #
+      _ = "#{this_image.first}/".squeeze('/')
+      array = Dir[_+'*.jpg']+
+              Dir[_+'*.png']+
+              Dir[_+'*.gif']
+      array.flatten!
+      array.reject! {|entry| # Exclude animated .gif files.
+        entry.end_with?('.gif') and 
+        ::ImageParadise.is_this_image_animated?(entry)
+      }
+      this_image = array
+    end
+    # ======================================================================= #
+    # Batch process this next - treat it as an Array:
+    # ======================================================================= #
+    this_image.each {|this_image_specifically|
+      output_filename = 'output_'+File.basename(this_image_specifically).
+                        delete_suffix(
+                          File.extname(this_image_specifically)
+                        )
+      extname = File.extname(this_image_specifically)
+      filename_to_use = File.basename(this_image_specifically).
+                        delete_suffix(
+                          File.extname(this_image_specifically)
+                        ).tr('_', ' ')
+      cmd_to_use = "convert #{this_image_specifically} "\
+                   "-font #{use_this_font} "\
+                   "-pointsize #{font_size_to_use} "\
+                   "-draw \"gravity northwest fill #{colour_to_use} text 0,15 '#{filename_to_use}' \" "\
+                   "#{output_filename}"+extname
+     e
+     esystem(cmd_to_use)
+     e
+    }
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  ImageParadise.add_this_comment_to_that_image(
+    'Hello world!',
+    '/Depot/NJOY/Vratinaka_01.jpg'
+  ) 
+end