save_png: add trim and trim_radius options

Close #122.

lib/squib/api/save.rb

@@ -55,6 +55,8 @@ module Squib
     # @option opts [String] prefix (card_) the prefix of the file name to be printed.
     # @option opts [String] count_format (%02d) the format string used for formatting the card count (e.g. padding zeros). Uses a Ruby format string (see the Ruby doc for Kernel::sprintf for specifics)
     # @option opts [Boolean, :clockwise, :counterclockwise] rotate (false) if true, the saved cards will be rotated 90 degrees clockwise. Or, rotate by the number of radians. Intended to rendering landscape instead of portrait.
+    # @option opts trim [Integer] (0) the space around the edge of each card to trim (e.g. to cut off the bleed margin for print-and-play). Supports unit conversion.
+    # @option opts trim_radius [Integer] (38) the rounded rectangle radius around the card to trim before putting into the showcase
     # @return [nil] Returns nothing
     # @api public
     def save_png(opts = {})

lib/squib/args/save_batch.rb

@@ -12,11 +12,14 @@ module Squib
       end
 
       def self.parameters
-        { dir: '_output',
-          prefix: 'card_',
-          count_format: '%02d',
-          rotate: false,
+        {
           angle: 0,
+          count_format: '%02d',
+          dir: '_output',
+          prefix: 'card_',
+          rotate: false,
+          trim_radius: 0,
+          trim: 0,
         }
       end
 
@@ -25,7 +28,7 @@ module Squib
       end
 
       def self.params_with_units
-        [] # none of them
+        [:trim, :trim_radius]
       end
 
       def validate_dir(arg, _i)

lib/squib/graphics/save_images.rb

@@ -4,27 +4,33 @@ module Squib
     # :nodoc:
     # @api private
     def save_png(batch)
-      surface = if batch.rotate
-                  rotated_image(batch.angle)
+      surface = if preprocess_save?(batch)
+                  preprocessed_save(batch.angle, batch.trim, batch.trim_radius)
                 else
-                  surface = @cairo_surface
+                  @cairo_surface
                 end
       write_png(surface, index, batch.dir, batch.prefix, batch.count_format)
     end
 
     # :nodoc:
     # @api private
-    def rotated_image(angle)
-      rotated_cc = Cairo::Context.new(Cairo::ImageSurface.new(@height, @width) )
-      rotated_cc.translate(@height * 0.5, @width * 0.5)
-      rotated_cc.rotate(angle)
-      rotated_cc.translate(@width * -0.5, @height * -0.5)
-      rotated_cc.set_source(@cairo_surface)
-      rotated_cc.paint
-      rotated_cc.target
+    def preprocess_save?(batch)
+      batch.rotate || batch.trim > 0
     end
-    # :nodoc:
-    # @api private
+
+    def preprocessed_save(angle, trim, trim_radius)
+      new_width, new_height = @width - 2*trim, @height - 2*trim
+      new_cc = Cairo::Context.new(Cairo::ImageSurface.new(new_width, new_height))
+      new_cc.translate(new_width * 0.5, new_height * 0.5)
+      new_cc.rotate(angle)
+      new_cc.translate(new_width * -0.5, new_height * -0.5)
+      new_cc.set_source(@cairo_surface, -trim, -trim)
+      new_cc.rounded_rectangle(0, 0, new_width, new_height, trim_radius, trim_radius)
+      new_cc.clip
+      new_cc.paint
+      new_cc.target
+    end
+
     def write_png(surface, i, dir, prefix, count_format)
       surface.write_to_png("#{dir}/#{prefix}#{count_format % i}.png")
     end