make-image-square 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 191824a355074b9d1afdddc527d0c4c5e7bcf3d2a89592d0db5beb93892f86ce
+  data.tar.gz: fea14d5dcdb9decfa3d21ae4b0a6bf0bc5696793dc5c0a158bb7ccd7ebc2e3de
+SHA512:
+  metadata.gz: 5fe9c3da96a81d08278f2d93b19fd432fb7038821725209dddf01b693031669e58188548307269639e29f7cce527900d890870b2e38b5eb6fcd0388e60cc1a3b
+  data.tar.gz: 42bb112f28e47eb89544d8ff0cd1db0fd23749a1f019e73a1520ad351b7dcde09c0a2ea17a2828a5797cf7a57d12f156ff2e65cd1520378ef9075d83608ee5a8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 squareimage.run
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,47 @@
+# make-image-square
+
+Tiny helper that turns any image size into a **1:1 layout plan**: square canvas size plus left/right/top/bottom padding so you can fit without cropping.
+
+Useful when you need the math for letterboxing / pillarboxing before you draw to a canvas, generate CSS `object-fit`-style boxes, or prep assets for Instagram and profile photos.
+
+## Install
+
+```ruby
+gem "make-image-square", "~> 0.1"
+```
+
+```bash
+gem install make-image-square
+```
+
+## Usage
+
+```ruby
+require "make_image_square"
+
+# 1200×800 landscape → 1200×1200 with top/bottom pads
+layout = MakeImageSquare.make_image_square(1200, 800)
+# canvas 1200, pad_top 200, pad_bottom 200
+
+# Force a 1080 square (typical feed post)
+ig = MakeImageSquare.make_image_square(1200, 800, canvas_size: 1080)
+
+# Padding-only helper
+pads = MakeImageSquare.square_padding(800, 1200)
+```
+
+### Modes
+
+| Mode | Behavior |
+|------|----------|
+| `:fit` (default) | Entire image visible; empty bands become padding |
+| `:fill` | Image covers the square; caller is expected to crop overflow |
+
+## Notes
+
+- This gem only returns numbers. It does not decode or rewrite image files.
+- Prefer a UI instead of wiring ImageMagick yourself? There is an [online 1:1 letterbox editor](https://squareimage.run) that can pad, blur the frame, or crop in the browser.
+
+## License
+
+MIT

data/lib/make_image_square/version.rb

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

data/lib/make_image_square.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "make_image_square/version"
+
+# Compute a square canvas and letterbox/pillarbox padding for an image.
+# Does not load or transform pixels — layout math only.
+module MakeImageSquare
+  Layout = Struct.new(
+    :canvas,
+    :content_width,
+    :content_height,
+    :offset_x,
+    :offset_y,
+    :pad_left,
+    :pad_right,
+    :pad_top,
+    :pad_bottom,
+    keyword_init: true
+  )
+  Padding = Struct.new(:canvas, :left, :right, :top, :bottom, keyword_init: true)
+
+  class Error < StandardError; end
+  class InvalidSize < Error; end
+
+  module_function
+
+  def make_image_square(width, height, mode: :fit, canvas_size: nil)
+    w = require_positive(width)
+    h = require_positive(height)
+    canvas = canvas_size.nil? ? [w, h].max : require_positive(canvas_size)
+    mode = mode.to_sym
+
+    if mode == :fill
+      scale = canvas / [w, h].min
+      content_width = w * scale
+      content_height = h * scale
+      offset_x = (canvas - content_width) / 2.0
+      offset_y = (canvas - content_height) / 2.0
+      return Layout.new(
+        canvas: canvas,
+        content_width: content_width,
+        content_height: content_height,
+        offset_x: offset_x,
+        offset_y: offset_y,
+        pad_left: [0, offset_x].max,
+        pad_right: [0, canvas - content_width - offset_x].max,
+        pad_top: [0, offset_y].max,
+        pad_bottom: [0, canvas - content_height - offset_y].max
+      )
+    end
+
+    unless mode == :fit
+      raise InvalidSize, "mode must be :fit or :fill"
+    end
+
+    scale = canvas / [w, h].max
+    content_width = w * scale
+    content_height = h * scale
+    pad_x = (canvas - content_width) / 2.0
+    pad_y = (canvas - content_height) / 2.0
+    Layout.new(
+      canvas: canvas,
+      content_width: content_width,
+      content_height: content_height,
+      offset_x: pad_x,
+      offset_y: pad_y,
+      pad_left: pad_x,
+      pad_right: pad_x,
+      pad_top: pad_y,
+      pad_bottom: pad_y
+    )
+  end
+
+  def square_padding(width, height, canvas_size = nil)
+    layout = make_image_square(width, height, mode: :fit, canvas_size: canvas_size)
+    Padding.new(
+      canvas: layout.canvas,
+      left: layout.pad_left,
+      right: layout.pad_right,
+      top: layout.pad_top,
+      bottom: layout.pad_bottom
+    )
+  end
+
+  def require_positive(value)
+    value = Float(value)
+    raise InvalidSize, "width, height, and canvas size must be positive numbers" unless value.finite? && value.positive?
+
+    value
+  end
+  private_class_method :require_positive
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: make-image-square
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- hiltonlee981
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-08 00:00:00.000000000 Z
+dependencies: []
+description: Tiny Ruby helper that turns any image size into a square canvas plus
+  left/right/top/bottom padding. Fit mode letterboxes; fill mode covers. Layout math
+  only — it does not decode or rewrite image files.
+email:
+- hiltonlee981@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/make_image_square.rb
+- lib/make_image_square/version.rb
+homepage: https://squareimage.run
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://squareimage.run
+  rubygems_mfa_required: 'false'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Compute 1:1 letterbox/pillarbox padding from a photo's width and height.
+test_files: []