proofsheet 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb63ef244e4dc5bd439965363d028bb5760f1d76cd4b04b9595278e85990cd5
-  data.tar.gz: '0699294e136dc91a4afa0b718b6ddf07626261c9cc6bcb6cdb756e3563679fdb'
+  metadata.gz: 32d08a5e2dc65281e9d912c3c1fbf1d99c62b6dbeada3292f1460d4f9a03f866
+  data.tar.gz: 9eed758acf8fbba11febe56cb65ccd4c880f851301eaac1e5f1e82bd7845d7b4
 SHA512:
-  metadata.gz: '0387c6a7d3fe71a573e937f0df9103c26646218f6f5f1283c7ab78fc72b4b3ec6b26d0361156c6280f9d95355ee21c8321dac89d33f3459ed4435f9f683da64e'
-  data.tar.gz: ad13fdcaf9caa12d724e54abaac56b096288a34f76881f15ff49ef008535911c6fbe7a334f653af89b10adee1cc3ef513c2b326aa68bfbc21f7efd3b46d06424
+  metadata.gz: a4691597bd56de3061f2767887c05b8ad3d23f8460b5d6ccce808c2162f5a2c70bfeb31d82b08c64389b9edf454010beb1244b493f4f4c8bb4ee6f475faae200
+  data.tar.gz: f398d39c015136879e4b0b4aad78ba34907e67713bae18d0dedf23392466993fc0e5652d97cc8bfb018c4d4e35043950f375c0c137144580eed7594b34075ee9

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-19
+
+- Add the `compose` command for arranging captured screenshots on solid, transparent, gradient, or image backgrounds
+- Add per-layer cropping, proportional resizing, rounded corners, rotation, and shadows
+
 ## [0.1.0] - 2026-09-09
 
 - Initial release

data/README.md

@@ -106,6 +106,56 @@ proofsheet list
 
 Relative output paths are resolved from the directory where the command runs.
 
+## Compositions
+
+Compositions arrange captured shots on a new PNG canvas. A background can be a solid color, an angled two-color gradient, or an image. Layers can be positioned, resized proportionally, rounded, rotated, and given a shadow.
+
+```yaml
+compositions:
+  launch-hero:
+    canvas: [1600, 1000]
+    background:
+      gradient: ["#211002", "#5aa579"]
+      angle: 135
+    layers:
+      - shot: dashboard
+        x: 120
+        y: 140
+        crop:
+          x: 80
+          y: 40
+          width: 1200
+          height: 700
+        width: 980
+        radius: 32
+        rotate: -4
+        shadow:
+          x: 8
+          y: 24
+          blur: 32
+          color: "#00000066"
+      - shot: activity
+        x: 900
+        y: 460
+        width: 560
+        rotate: 5
+        shadow: true
+```
+
+Solid colors can be written directly as `background: "#fff8f5"`. For a transparent canvas, use `background: "#00000000"`. For an image background, use `background: { image: "assets/background.png" }`; Proofsheet scales and center-crops it to cover the canvas. Colors use `#RRGGBB` or `#RRGGBBAA` notation.
+
+Layer crop coordinates are measured in pixels from the original captured shot. Proofsheet crops first, then resizes proportionally using `width`, rounds corners using `radius`, rotates, adds the shadow, and places the result on the canvas. The radius is measured in pixels after resizing and is clamped to half the layer's smaller dimension.
+
+Setting `shadow: true` uses `x: 0`, `y: 16`, `blur: 24`, and `color: "#00000055"`. Use the expanded shadow mapping shown above to override any of those values.
+
+Capture the source shots, then compose every configured image or selected compositions:
+
+```sh
+proofsheet capture
+proofsheet compose
+proofsheet compose launch-hero
+```
+
 ## Development
 
 Run `bin/setup`, then `bundle exec rake` to run the specs and linter. To install this gem locally, run `bundle exec rake install`.

data/lib/proofsheet/cli.rb

@@ -4,29 +4,30 @@ require "optparse"
 
 module Proofsheet
   class CLI
-    USAGE = "Usage: proofsheet <capture [SHOT ...] | list> [--config PATH] [--host HOST]"
+    USAGE = "Usage: proofsheet <capture [SHOT ...] | compose [COMPOSITION ...] | list> " \
+            "[--config PATH] [--host HOST]"
 
-    def initialize(argv, out: $stdout, err: $stderr, root: Dir.pwd, manifest_loader: Manifest.method(:load),
-                   capturer_class: Capturer)
+    def initialize(argv, out: $stdout, err: $stderr, root: Dir.pwd, manifest_loader: Manifest.method(:load), **classes)
       @argv = argv.dup
       @out = out
       @err = err
       @root = root
       @manifest_loader = manifest_loader
-      @capturer_class = capturer_class
+      @capturer_class = classes.fetch(:capturer_class, Capturer)
+      @composer_class = classes.fetch(:composer_class, Composer)
     end
 
     def run
       command = @argv.shift
       return help(0) if %w[help --help -h].include?(command)
       return version if %w[--version -v].include?(command)
-      return help(1) unless %w[capture list].include?(command)
+      return help(1) unless %w[capture compose list].include?(command)
 
       options = { config: Manifest::DEFAULT_PATH }
       parser(options).parse!(@argv)
       manifest = @manifest_loader.call(options[:config])
 
-      command == "list" ? list(manifest) : capture(manifest, options)
+      dispatch(command, manifest, options)
       0
     rescue OptionParser::ParseError, Error, KeyError => e
       @err.puts "proofsheet: #{e.message}"
@@ -35,6 +36,13 @@ module Proofsheet
 
     private
 
+    def dispatch(command, manifest, options)
+      return list(manifest) if command == "list"
+      return compose(manifest) if command == "compose"
+
+      capture(manifest, options)
+    end
+
     def parser(options)
       OptionParser.new do |opts|
         opts.on("-c", "--config PATH") { |path| options[:config] = path }
@@ -61,6 +69,13 @@ module Proofsheet
       @out.puts "Done."
     end
 
+    def compose(manifest)
+      names = @argv.empty? ? manifest.composition_names : @argv
+      @out.puts "Composing #{names.size} #{names.size == 1 ? "image" : "images"}"
+      @composer_class.new(manifest: manifest, root: @root, out: @out).compose(names)
+      @out.puts "Done."
+    end
+
     def help(status)
       (status.zero? ? @out : @err).puts USAGE
       status

data/lib/proofsheet/composer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "vips"
+
+module Proofsheet
+  class Composer
+    def initialize(manifest:, root: Dir.pwd, out: $stdout)
+      @manifest = manifest
+      @root = Pathname(root)
+      @out = out
+    end
+
+    def compose(names = @manifest.composition_names)
+      names.each { |name| compose_one(@manifest.composition(name)) }
+    end
+
+    private
+
+    def compose_one(composition)
+      @out.puts composition.name
+      image = background_image(composition)
+      composition.layers.each { |layer| image = add_layer(image, layer) }
+      write(composition, image)
+    end
+
+    def background_image(composition)
+      spec = composition.background
+      return solid(composition.width, composition.height, spec.color) if spec.color
+      return gradient(composition.width, composition.height, spec.gradient, spec.angle) if spec.gradient
+      return cover_image(spec.image, composition.width, composition.height) if spec.image
+
+      raise Error, "#{composition.name}: background must set color, gradient, or image"
+    end
+
+    def add_layer(canvas, layer)
+      image = layer_image(layer)
+      canvas = add_shadow(canvas, image, layer) if layer.shadow
+      canvas.composite2(image, :over, x: layer.x, y: layer.y)
+    end
+
+    def layer_image(layer)
+      image = load_image(output_path("#{layer.shot}.png"))
+      image = Cropper.call(image, layer.crop) if layer.crop
+      image = image.resize(layer.width.to_f / image.width) if layer.width
+      image = RoundedCorners.call(image, layer.radius)
+      image = image.rotate(layer.rotate, background: [0, 0, 0, 0]) unless layer.rotate.zero?
+      image
+    end
+
+    def add_shadow(canvas, image, layer)
+      shadow = layer.shadow
+      alpha, padding = shadow_mask(image, shadow.blur)
+      overlay = shadow_overlay(alpha, shadow.color)
+      canvas.composite2(overlay, :over, x: layer.x + shadow.x - padding,
+                                        y: layer.y + shadow.y - padding)
+    end
+
+    def shadow_mask(image, blur)
+      padding = (blur * 3).ceil
+      alpha = image.extract_band(3).embed(padding, padding, image.width + (padding * 2),
+                                          image.height + (padding * 2), extend: :black)
+      alpha = alpha.gaussblur(blur) if blur.positive?
+      [alpha, padding]
+    end
+
+    def shadow_overlay(alpha, value)
+      color = parse_color(value)
+      opacity = color.pop
+      rgb = solid(alpha.width, alpha.height, color).extract_band(0, n: 3)
+      rgb.bandjoin(alpha * (opacity / 255.0))
+    end
+
+    def solid(width, height, color)
+      channels = color.is_a?(Array) ? color : parse_color(color)
+      rgb = Vips::Image.black(width, height).new_from_image(channels.first(3)).copy(interpretation: :srgb)
+      rgb.bandjoin(channels.fetch(3, 255))
+    end
+
+    def gradient(width, height, colors, angle)
+      raise Error, "gradient must contain exactly two colors" unless colors&.size == 2
+
+      from, to = colors.map { |color| parse_color(color) }
+      amount = gradient_amount(width, height, angle)
+      channels = from.zip(to).map { |start, finish| (amount * (finish - start)) + start }
+      channels.shift.bandjoin(channels).cast(:uchar).copy(interpretation: :srgb)
+    end
+
+    def gradient_amount(width, height, degrees)
+      coordinates = Vips::Image.xyz(width, height)
+      radians = degrees * Math::PI / 180
+      projection = (coordinates[0] * Math.cos(radians)) + (coordinates[1] * Math.sin(radians))
+      minimum = projection.min
+      maximum = projection.max
+      return Vips::Image.black(width, height) if minimum == maximum
+
+      (projection - minimum) / (maximum - minimum)
+    end
+
+    def cover_image(path, width, height)
+      image = load_image(@root.join(path))
+      scale = [width.to_f / image.width, height.to_f / image.height].max
+      image = image.resize(scale)
+      image.crop((image.width - width) / 2, (image.height - height) / 2, width, height)
+    end
+
+    def load_image(path)
+      raise Error, "image not found: #{path}" unless path.exist?
+
+      image = Vips::Image.new_from_file(path.to_s, access: :sequential)
+      image = image.colourspace(:srgb) unless image.interpretation == :srgb
+      image.has_alpha? ? image : image.bandjoin(255)
+    end
+
+    def parse_color(value)
+      match = /\A#([0-9a-f]{6})([0-9a-f]{2})?\z/i.match(value.to_s)
+      raise Error, "invalid color #{value.inspect}; use #RRGGBB or #RRGGBBAA" unless match
+
+      (match[1].scan(/../) + [match[2] || "ff"]).map { |channel| channel.to_i(16) }
+    end
+
+    def output_path(filename) = @root.join(@manifest.output_dir, filename)
+
+    def write(composition, image)
+      path = output_path(composition.filename)
+      FileUtils.mkdir_p(path.dirname)
+      image.write_to_file(path.to_s)
+      @out.puts "  wrote #{path.relative_path_from(@root)}"
+    end
+  end
+end

data/lib/proofsheet/composition_config.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Proofsheet
+  class CompositionConfig
+    Background = Data.define(:color, :gradient, :image, :angle)
+    Shadow = Data.define(:x, :y, :blur, :color)
+    Crop = Data.define(:x, :y, :width, :height)
+    Layer = Data.define(:shot, :x, :y, :crop, :width, :radius, :rotate, :shadow)
+    Composition = Data.define(:name, :width, :height, :background, :layers) do
+      def filename
+        "#{name}.png"
+      end
+    end
+
+    def initialize(data, path:)
+      @data = data
+      @path = path
+    end
+
+    def names
+      @data.keys
+    end
+
+    def fetch(name)
+      raw = @data[name]
+      raise Error, unknown_message(name) if raw.nil?
+
+      width, height = raw.fetch("canvas")
+      Composition.new(name: name, width: width, height: height,
+                      background: background(raw.fetch("background", "#ffffff")),
+                      layers: raw.fetch("layers").map { |layer| layer_spec(layer) })
+    rescue KeyError => e
+      raise Error, "#{name}: #{e.message} in #{@path}"
+    end
+
+    private
+
+    def unknown_message(name)
+      "unknown composition #{name.inspect} — known compositions: #{names.join(", ")}"
+    end
+
+    def background(raw)
+      return Background.new(color: raw, gradient: nil, image: nil, angle: 0) if raw.is_a?(String)
+
+      Background.new(color: raw["color"], gradient: raw["gradient"], image: raw["image"],
+                     angle: raw.fetch("angle", 0))
+    end
+
+    def layer_spec(raw)
+      Layer.new(shot: raw.fetch("shot"), x: raw.fetch("x", 0), y: raw.fetch("y", 0),
+                crop: crop(raw["crop"]), width: raw["width"], radius: raw.fetch("radius", 0),
+                rotate: raw.fetch("rotate", 0), shadow: shadow(raw["shadow"]))
+    end
+
+    def crop(raw)
+      return if raw.nil?
+
+      Crop.new(x: raw.fetch("x"), y: raw.fetch("y"),
+               width: raw.fetch("width"), height: raw.fetch("height"))
+    end
+
+    def shadow(raw)
+      return if raw.nil? || raw == false
+
+      raw = {} if raw == true
+      Shadow.new(x: raw.fetch("x", 0), y: raw.fetch("y", 16), blur: raw.fetch("blur", 24),
+                 color: raw.fetch("color", "#00000055"))
+    end
+  end
+end

data/lib/proofsheet/cropper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Proofsheet
+  class Cropper
+    def self.call(image, spec)
+      new(image, spec).call
+    end
+
+    def initialize(image, spec)
+      @image = image
+      @spec = spec
+    end
+
+    def call
+      raise Error, "crop #{@spec.to_h} exceeds source image #{@image.width}×#{@image.height}" unless valid?
+
+      @image.crop(@spec.x, @spec.y, @spec.width, @spec.height)
+    end
+
+    private
+
+    def valid?
+      @spec.x >= 0 && @spec.y >= 0 && positive_dimensions? && within_bounds?
+    end
+
+    def positive_dimensions?
+      @spec.width.positive? && @spec.height.positive?
+    end
+
+    def within_bounds?
+      @spec.x + @spec.width <= @image.width && @spec.y + @spec.height <= @image.height
+    end
+  end
+end

data/lib/proofsheet/manifest.rb

@@ -73,6 +73,12 @@ module Proofsheet
       names.map { |name| shot(name) }
     end
 
+    def composition_names = composition_config.names
+
+    def composition(name)
+      composition_config.fetch(name)
+    end
+
     def shot(name)
       raw = shot_data[name]
       raise Error, "unknown shot #{name.inspect} — known shots: #{names.join(", ")}" if raw.nil?
@@ -124,5 +130,9 @@ module Proofsheet
     rescue KeyError
       raise Error, "shots is missing from #{@path}"
     end
+
+    def composition_config
+      @composition_config ||= CompositionConfig.new(@data.fetch("compositions", {}), path: @path)
+    end
   end
 end

data/lib/proofsheet/rounded_corners.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Proofsheet
+  class RoundedCorners
+    def self.call(image, requested_radius)
+      return image unless requested_radius.positive?
+
+      new(image, requested_radius).call
+    end
+
+    def initialize(image, requested_radius)
+      @image = image
+      @radius = [requested_radius.to_f, image.width / 2.0, image.height / 2.0].min
+    end
+
+    def call
+      alpha = (@image.extract_band(3) * (coverage / 255.0)).cast(:uchar)
+      @image.extract_band(0, n: 3).bandjoin(alpha)
+    end
+
+    private
+
+    def coverage
+      distance = ((x_distance * x_distance) + (y_distance * y_distance))**0.5
+      value = (((distance * -1) + @radius + 0.5) * 255)
+      value = value.relational_const(:more, [255]).ifthenelse(255, value)
+      value.relational_const(:less, [0]).ifthenelse(0, value)
+    end
+
+    def x_distance
+      corner_distance(coordinates[0], @image.width)
+    end
+
+    def y_distance
+      corner_distance(coordinates[1], @image.height)
+    end
+
+    def corner_distance(coordinate, length)
+      distance = (coordinate - ((length - 1) / 2.0)).abs - ((length / 2.0) - @radius)
+      distance.relational_const(:more, [0]).ifthenelse(distance, 0)
+    end
+
+    def coordinates
+      @coordinates ||= Vips::Image.xyz(@image.width, @image.height)
+    end
+  end
+end

data/lib/proofsheet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proofsheet
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/proofsheet.rb

@@ -10,6 +10,10 @@ end
 require_relative "proofsheet/browser"
 require_relative "proofsheet/clip"
 require_relative "proofsheet/credentials"
+require_relative "proofsheet/composition_config"
 require_relative "proofsheet/manifest"
 require_relative "proofsheet/capturer"
+require_relative "proofsheet/cropper"
+require_relative "proofsheet/rounded_corners"
+require_relative "proofsheet/composer"
 require_relative "proofsheet/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proofsheet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marc Heiligers
@@ -70,8 +70,12 @@ files:
 - lib/proofsheet/capturer.rb
 - lib/proofsheet/cli.rb
 - lib/proofsheet/clip.rb
+- lib/proofsheet/composer.rb
+- lib/proofsheet/composition_config.rb
 - lib/proofsheet/credentials.rb
+- lib/proofsheet/cropper.rb
 - lib/proofsheet/manifest.rb
+- lib/proofsheet/rounded_corners.rb
 - lib/proofsheet/version.rb
 - sig/proofsheet.rbs
 homepage: https://github.com/FASCINATION-works/proofsheet