save_png

Saves the given range of cards to a PNG

Options

dir

default: '_output'

the directory for the output to be sent to. Will be created if it doesn’t exist.

prefix

default 'card_'

the prefix of all the filenames saved

count_format

default: '%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)

suffix

default: ''

the suffix of all the filenames saved, just before the .png extension.

rotate

default: 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. Possible values: true, false, :clockwise, :counterclockwise

trim

default: 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.

trim_radius

default: 0

the rounded rectangle radius around the card to trim before saving.

shadow_radius

default: nil

adds a drop shadow behind the card just before rendering, when non-nil. Does nothing when set to nil.

A larger radius extends the blur’s spread, making it softer. A radius of 0 still enables the shadow, but has no blur.

Recommended range: 3-10 pixels.

See Drop Shadow section below for more details.

shadow_offset_x

default: 3

the horizontal distance that the drop shadow will be shifted beneath the final image. Ignored when shadow_radius is nil.

See Drop Shadow section below for more details.

Supports Unit Conversion.

shadow_offset_y

default: 3

Ignored when shadow_radius is nil. See shadow_radius above for drop shadow details.

See Drop Shadow section below for more details.

Supports Unit Conversion.

shadow_trim

default: 0

the space around the lower right and bottom edge of the output image to be trimmed when a drop shadow is drawn. Can also enlarge the image if it is negative.

Ignored when shadow_radius is nil. See Drop Shadow section below for more details.

Supports Unit Conversion.

shadow_color

default: :black

the color or gradient of the drop shadow. See Specifying Colors & Gradients.

Note about gradients: Squib still does blurring, but gradients give you fine control over the softness of the shadow. See example below of doing a custom gradient for customizing your look.

See Drop Shadow section below for more details.

range

default: :all

the range of cards over which this will be rendered. See Using range to specify cards

Drop Shadow

Drop shadows don’t modify the original image. Instead, this will paint your existing card images onto a shadow of themselves. The final image will have the following dimensions:

  • final_width  = card_w + shadow_offset_x + (3 * shadow_radius) - (2 * shadow_trim) - (2 * trim)
  • final_height = card_h + shadow_offset_y + (3 * shadow_radius) - (2 * shadow_trim) - (2 * trim)

A shadow of your card graphic is created using your shadow_color.

See https://github.com/rcairo/rcairo/blob/master/lib/cairo/context/blur.rb for details on blur implementation. Supports Unit Conversion.

Examples

This sample lives here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
require 'squib'
# The save_png method supports drop shadows on the final save
# This is useful for when you want to generate images for your rulebook

Squib::Deck.new(width: 100, height: 150) do
  background color: '#abc'
  svg file: '../spanner.svg',
      x: 'middle - 25', y: 'middle - 25',
      width: 50, height: 50

  # Shadows off by default, i.e. shadow_radius is nil
  # So our final dimensions are 100 - 2*15 and 150-2*15
  save_png prefix: 'no_shadow_', trim: 15, trim_radius: 15

  # Here's a nice-looking drop shadow
  # Defaults are designed to be generally good, so I recommend just
  # trying out a shadow_radius of 3 to 10 and see how it looks first
  save_png prefix: 'with_shadow_', trim: 15, trim_radius: 15,
           shadow_radius: 8,
           shadow_offset_x: 3, shadow_offset_y: 3,  # about r / 2.5 looks good
           shadow_trim: 2.5, # about r/ 3 looks good
           shadow_color: '#101010aa' #tip: start the shadow color kinda transparent

  # Don't want a blur? Use a radius of 0
  save_png prefix: 'no_blur_', trim: 15, trim_radius: 15,
           shadow_radius: 0

  # Ok this next stop is crazytown, but it does give you ultimate control
  # Remember that all Squib colors can also be gradients.
  # They can be clunky but they do work here.
  #   - x,y's are centered in the card itself
  #   - stops go from fully empty to fully black
  #   - we need to still turn on radius to get the effect
  #   - but, this makes the upper-left corner not have a glowing effect and
  #     have a harder edge, which (to my eye at least) feels more realistic
  #     since the card would obscure the upper-left shadow at that angle
  #   - this also allows you have a larger, softer blur without making it look
  #     like it's glowing
  #
  # Oh just because it's easier to write we can use a ruby heredoc
  save_png prefix: 'gradient_blur_', trim: 15, trim_radius: 15,
           shadow_radius: 10,
           shadow_color: <<~EOS
              (25,25)
              (175,175)
              #0000@0.0
              #000f@1.0
           EOS

  # This one looks weird I know but it's for regression testing
  save_png prefix: 'with_shadow_test_',
           trim: 15, trim_radius: 15, rotate: :clockwise,
           shadow_offset_x: 5, shadow_offset_y: 25, shadow_radius: 10,
           shadow_trim: 10,
           shadow_color: '#123'
end

Squib::Deck.new(width:50, height: 50) do

  # What if we had a transparent card but just some shapes?
  # Like chits or something

  # background defaults to fully transparent here

  png file: 'doodle.png'

  save_png prefix: 'transparent_bg_shadow_',
           shadow_radius: 2,
           shadow_offset_x: 2, shadow_offset_y: 2,
           shadow_color: :black

end
../_images/with_shadow_00_expected.png

with_shadow_00.png

../_images/no_blur_00_expected.png

no_blur_00.png

../_images/gradient_blur_00_expected.png

gradient_blur_00.png

../_images/transparent_bg_shadow_00_expected.png

transparent_bg_shadow_00.png