loomy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e58a5dd9cc41368d235d075797fed3c422b7abb9db8c38372f382c53ebe0a4a5
+  data.tar.gz: 8ea209c82cf8442a48408c9a607bdf5f967fe70262b74660bb427a3d8b28e193
+SHA512:
+  metadata.gz: c32b8633ff0d8160e342470f6214b6813cb01618b699be83c6b4acf10039a7e57785f70805973b2751f46776cfd0ec2ef67124f670a49ddd6e54b9721c31ce33
+  data.tar.gz: bd6720746b685ca99ed7eefa3d6fab6f6815f7de54d5a3b2d53fed406abfc76b24698c8cae736e56eb4e660b48257712f99897f1d0cfcee98e4047bdd74976dc

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+test/tmp/*

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in loomy.gemspec
+gemspec
+
+gem "benchmark-ips"

data/Gemfile.lock

@@ -0,0 +1,74 @@
+PATH
+  remote: .
+  specs:
+    loomy (0.1.0)
+      ruby-vips (~> 2.3)
+      zeitwerk (~> 2.7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    benchmark-ips (2.14.0)
+    ffi (1.17.3)
+    ffi (1.17.3-aarch64-linux-gnu)
+    ffi (1.17.3-aarch64-linux-musl)
+    ffi (1.17.3-arm-linux-gnu)
+    ffi (1.17.3-arm-linux-musl)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86-linux-gnu)
+    ffi (1.17.3-x86-linux-musl)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
+    logger (1.7.0)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    prism (1.9.0)
+    rake (13.3.1)
+    ruby-vips (2.3.0)
+      ffi (~> 1.12)
+      logger
+    zeitwerk (2.7.4)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  benchmark-ips
+  loomy!
+  minitest (~> 6.0)
+  rake (~> 13.0)
+
+CHECKSUMS
+  benchmark-ips (2.14.0) sha256=b72bc8a65d525d5906f8cd94270dccf73452ee3257a32b89fbd6684d3e8a9b1d
+  ffi (1.17.3) sha256=0e9f39f7bb3934f77ad6feab49662be77e87eedcdeb2a3f5c0234c2938563d4c
+  ffi (1.17.3-aarch64-linux-gnu) sha256=28ad573df26560f0aedd8a90c3371279a0b2bd0b4e834b16a2baa10bd7a97068
+  ffi (1.17.3-aarch64-linux-musl) sha256=020b33b76775b1abacc3b7d86b287cef3251f66d747092deec592c7f5df764b2
+  ffi (1.17.3-arm-linux-gnu) sha256=5bd4cea83b68b5ec0037f99c57d5ce2dd5aa438f35decc5ef68a7d085c785668
+  ffi (1.17.3-arm-linux-musl) sha256=0d7626bb96265f9af78afa33e267d71cfef9d9a8eb8f5525344f8da6c7d76053
+  ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f
+  ffi (1.17.3-x86-linux-gnu) sha256=868a88fcaf5186c3a46b7c7c2b2c34550e1e61a405670ab23f5b6c9971529089
+  ffi (1.17.3-x86-linux-musl) sha256=f0286aa6ef40605cf586e61406c446de34397b85dbb08cc99fdaddaef8343945
+  ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5
+  ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
+  ffi (1.17.3-x86_64-linux-musl) sha256=086b221c3a68320b7564066f46fed23449a44f7a1935f1fe5a245bd89d9aea56
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  loomy (0.1.0)
+  minitest (6.0.1) sha256=7854c74f48e2e975969062833adc4013f249a4b212f5e7b9d5c040bf838d54bb
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  ruby-vips (2.3.0) sha256=e685ec02c13969912debbd98019e50492e12989282da5f37d05f5471442f5374
+  zeitwerk (2.7.4) sha256=2bef90f356bdafe9a6c2bd32bcd804f83a4f9b8bc27f3600fff051eb3edcec8b
+
+BUNDLED WITH
+  4.0.3

data/README.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <img src="assets/logo.png" width="240" alt="Loomy Logo">
+</p>
+
+<h1 align="center">Loomy 🧶</h1>
+
+<p align="center">
+  <strong>The friendly pixel-weaver for Ruby.</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/loomy"><img src="https://img.shields.io/gem/v/loomy.svg" alt="Gem Version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://github.com/JohnAnon9771/loomy/actions"><img src="https://img.shields.io/badge/tests-passing-success.svg" alt="Tests Status"></a>
+</p>
+
+---
+
+**Loomy** is a modern, high-performance image processing engine for Ruby. Think of it as a master weaver for your images: it takes raw layers (the threads) and weaves them into complex compositions using a smart, declarative DSL.
+
+Built on top of `libvips`, Loomy doesn't just process images; it optimizes the entire "weaving" process (AST) to ensure your pipelines are as light and fast as silk.
+
+## 🚀 Key Features
+
+- **High Performance**: Built on `libvips` with a custom Batch Composition engine that flattens operations into a single efficient pipeline.
+- **Hierarchical Groups**: Nest layers and groups to create complex layouts with shared effects.
+- **Intelligent DSL**: Declarative, block-based syntax. Define properties naturally without complex argument lists.
+- **AST Optimizer**: A smart "pre-weaving" layer that prunes invisible layers and pre-calculates geometry before rendering.
+- **Extensible Effects**: Dynamic registry to add your own image processing strategies.
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'loomy'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## 🛠 Usage
+
+### 1. Generating Images
+
+Loomy offers two ways to get your results: `render` (write to file) and `generate` (get a `Vips::Image` object).
+
+#### Render to file
+
+```ruby
+Loomy.render("output.png", size: [1200, 630]) do
+  layer "background.jpg"
+end
+```
+
+#### Generate in-memory (Web Servers / Testing)
+
+```ruby
+# Returns a Vips::Image object
+image = Loomy.generate(size: [1200, 630]) do
+  layer "background.jpg"
+end
+
+# Get binary buffer for HTTP response or S3
+buffer = image.write_to_buffer(".png")
+```
+
+### 2. Hierarchical Groups
+
+Group layers to apply effects or positioning to a set of nodes collectively.
+
+```ruby
+Loomy.render("banner.png", size: [800, 400]) do
+  group x: 50, y: 50 do
+    layer "icon.png", width: 50
+    layer "text.png", x: 60
+
+    # Apply blur to the entire group
+    blur radius: 2
+  end
+end
+```
+
+### 3. The Smart DSL
+
+Forget about complex argument lists. Describe your image layout naturally:
+
+```ruby
+require 'loomy'
+
+Loomy.render("output.png", size: [1200, 630]) do
+  # Background
+  layer "background.jpg" do
+    fit :cover
+    blur radius: 10
+  end
+
+  # Overlay
+  layer "avatar.png" do
+    x :center
+    y :center
+    width "20%"
+    trim true # Auto-crop transparent borders
+  end
+end
+```
+
+### 4. Reusable Styles
+
+Define common looks and apply them anywhere.
+
+```ruby
+# Define a style
+Loomy.define_style :hero_layer do
+  x 50
+  y 100
+  blend :overlay
+end
+
+Loomy.render("post.png", size: [1000, 1000]) do
+  layer "texture.png" do
+    use :hero_layer # Apply the style
+    width 500       # Override or extend
+  end
+end
+```
+
+### 5. Custom Effects & Registry
+
+Loomy is extensible. You can register your own `libvips` processors:
+
+```ruby
+# Register a custom effect
+Loomy.register_effect(MyCustomEffectClass, ->(img, effect_node) {
+  img.my_vips_operation(effect_node.param)
+})
+```
+
+## ⚡ Performance
+
+Loomy is designed for scale. Leveraging `libvips`' streaming architecture and our proprietary AST optimization, Loomy delivers exceptional throughput:
+
+| Complexity                    | Throughput (M1) |
+| :---------------------------- | :-------------- |
+| Simple Composites             | ~70 images/sec  |
+| Complex (5+ layers + effects) | ~60 images/sec  |
+
+## 🗺 Roadmap
+
+- [ ] Full support for relative geometry (`%`, `vh`, `vw`)
+- [ ] Rounded corners and masking
+- [ ] SVG support as layers
+- [ ] Smart Saliency Masking (Background Removal)
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/bench.rb

@@ -0,0 +1,76 @@
+require "benchmark/ips"
+$LOAD_PATH.unshift File.expand_path("lib", __dir__)
+require "loomy"
+
+# Ensure assets are generated
+unless File.exist?("test/assets/base.png")
+  Vips::Image.black(1024, 1024, bands: 3).linear([1], [128,128,128]).bandjoin(255).cast(:uchar).write_to_file("test/assets/base.png")
+end
+
+unless File.exist?("test/assets/overlay.png")
+  Vips::Image.black(500, 500, bands: 3).linear([1], [255,0,0]).bandjoin(255).cast(:uchar).write_to_file("test/assets/overlay.png")
+end
+
+# Large assets (4200x4800)
+unless File.exist?("test/assets/base_large.png")
+  puts "Generating large base asset (4200x4800)..."
+  Vips::Image.black(4200, 4800, bands: 3).linear([1], [50,50,50]).bandjoin(255).cast(:uchar).write_to_file("test/assets/base_large.png")
+end
+
+unless File.exist?("test/assets/overlay_large.png")
+  puts "Generating large overlay asset (2000x2000)..."
+  Vips::Image.black(2000, 2000, bands: 3).linear([1], [0,255,0]).bandjoin(255).cast(:uchar).write_to_file("test/assets/overlay_large.png")
+end
+
+unless File.exist?("test/assets/trim_source_large.png")
+  puts "Generating large trim asset..."
+  # 2000x2000 image with 500x500 content in middle, rest transparent
+  content = Vips::Image.black(500, 500, bands: 3).linear([1], [0,0,255]).bandjoin(255)
+  padded = content.embed(750, 750, 2000, 2000, extend: :background, background: [0,0,0,0])
+  padded.cast(:uchar).write_to_file("test/assets/trim_source_large.png")
+end
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("simple_composite") do
+    Loomy.render("bench_output_simple.png", size: [1024, 1024]) do
+      layer "test/assets/base.png"
+      layer "test/assets/overlay.png", x: 200, y: 200
+    end
+  end
+
+  x.report("complex_composite") do
+    Loomy.render("bench_output_complex.png", size: [1024, 1024]) do
+      layer "test/assets/base.png"
+      layer "test/assets/overlay.png", x: 50, y: 50, blend: :multiply
+      layer "test/assets/overlay.png", x: 400, y: 400, width: 200, height: 200, fit: :cover
+      layer "test/assets/overlay.png", x: 600, y: 100, blur: 5
+      layer "test/assets/overlay.png", x: 100, y: 600, grayscale: true
+    end
+  end
+
+  x.report("large_composite_4k") do
+    Loomy.render("bench_output_large.png", size: [4200, 4800]) do
+      layer "test/assets/base_large.png"
+      layer "test/assets/overlay_large.png", x: 500, y: 500
+      layer "test/assets/overlay.png", x: 100, y: 100 # Mixing sizes
+    end
+  end
+
+  x.report("trim_composite") do
+    Loomy.render("bench_output_trim.png", size: [4200, 4800]) do
+      layer "test/assets/base_large.png"
+      # This image is 2000x2000 but only has 500x500 content. 
+      # With trim: true, it should act like 500x500 image.
+      layer "test/assets/trim_source_large.png", trim: true, x: 1000, y: 1000
+    end
+  end
+
+  x.compare!
+end
+
+# Cleanup outputs (keep inputs for re-runs)
+["bench_output_simple.png", "bench_output_complex.png", "bench_output_large.png", "bench_output_trim.png"].each do |f|
+  File.delete(f) if File.exist?(f)
+end

data/lib/loomy/ast/canvas.rb

@@ -0,0 +1,19 @@
+require_relative 'node'
+
+module Loomy
+  module AST
+    class Canvas < Node
+      def width
+        properties[:size][0]
+      end
+
+      def height
+        properties[:size][1]
+      end
+
+      def accept(visitor)
+        visitor.visit_canvas(self)
+      end
+    end
+  end
+end

data/lib/loomy/ast/effect.rb

@@ -0,0 +1,15 @@
+require_relative 'node'
+
+module Loomy
+  module AST
+    class Effect < Node
+      def map_source
+        properties[:map]
+      end
+
+      def accept(visitor)
+        visitor.visit_effect(self)
+      end
+    end
+  end
+end

data/lib/loomy/ast/effects/blur.rb

@@ -0,0 +1,17 @@
+require_relative '../effect'
+
+module Loomy
+  module AST
+    module Effects
+      class Blur < Effect
+        def radius
+          properties[:radius] || 0
+        end
+
+        def accept(visitor)
+          visitor.visit_blur_effect(self)
+        end
+      end
+    end
+  end
+end

data/lib/loomy/ast/effects/color_adjustment.rb

@@ -0,0 +1,21 @@
+require_relative '../effect'
+
+module Loomy
+  module AST
+    module Effects
+      class ColorAdjustment < Effect
+        def brightness
+          properties[:brightness] || 1.0
+        end
+        
+        def contrast
+          properties[:contrast] || 1.0
+        end
+
+        def accept(visitor)
+          visitor.visit_color_adjustment_effect(self)
+        end
+      end
+    end
+  end
+end

data/lib/loomy/ast/effects/displacement.rb

@@ -0,0 +1,17 @@
+require_relative '../effect'
+
+module Loomy
+  module AST
+    module Effects
+      class Displacement < Effect
+        def scale
+          properties[:scale] || 20
+        end
+
+        def accept(visitor)
+          visitor.visit_displacement_effect(self)
+        end
+      end
+    end
+  end
+end

data/lib/loomy/ast/effects/grayscale.rb

@@ -0,0 +1,13 @@
+require_relative '../effect'
+
+module Loomy
+  module AST
+    module Effects
+      class Grayscale < Effect
+        def accept(visitor)
+          visitor.visit_grayscale_effect(self)
+        end
+      end
+    end
+  end
+end

data/lib/loomy/ast/effects/lighting.rb

@@ -0,0 +1,21 @@
+require_relative '../effect'
+
+module Loomy
+  module AST
+    module Effects
+      class Lighting < Effect
+        def type
+          properties[:type] || :ambient
+        end
+        
+        def strength
+          properties[:strength] || 1.0
+        end
+
+        def accept(visitor)
+          visitor.visit_lighting_effect(self)
+        end
+      end
+    end
+  end
+end

data/lib/loomy/ast/group.rb

@@ -0,0 +1,39 @@
+require_relative 'node'
+
+module Loomy
+  module AST
+    class Group < Node
+      def x
+        properties[:x] || 0
+      end
+
+      def y
+        properties[:y] || 0
+      end
+
+      def width
+        properties[:width]
+      end
+
+      def height
+        properties[:height]
+      end
+
+      def blend_mode
+        properties[:blend] || :over
+      end
+
+      def effects
+        @effects ||= []
+      end
+
+      def add_effect(effect)
+        effects << effect
+      end
+
+      def accept(visitor)
+        visitor.visit_group(self)
+      end
+    end
+  end
+end

data/lib/loomy/ast/layer.rb

@@ -0,0 +1,55 @@
+require_relative 'node'
+
+module Loomy
+  module AST
+    class Layer < Node
+      def source
+        properties[:source]
+      end
+
+      def blend_mode
+        properties[:blend] || :over
+      end
+
+      def x
+        properties[:x] || 0
+      end
+
+      def y
+        properties[:y] || 0
+      end
+
+      def width
+        properties[:width]
+      end
+
+      def height
+        properties[:height]
+      end
+
+      def fit
+        properties[:fit]
+      end
+
+      def gravity
+        properties[:gravity] || :centre
+      end
+
+      def trim
+        properties[:trim]
+      end
+
+      def effects
+        @effects ||= []
+      end
+
+      def add_effect(effect)
+        effects << effect
+      end
+
+      def accept(visitor)
+        visitor.visit_layer(self)
+      end
+    end
+  end
+end

data/lib/loomy/ast/node.rb

@@ -0,0 +1,21 @@
+module Loomy
+  module AST
+    class Node
+      attr_reader :children, :properties
+
+      def initialize(properties = {})
+        @properties = properties
+        @children = []
+      end
+
+      def add_child(node)
+        @children << node
+        node
+      end
+
+      def accept(visitor)
+        visitor.visit_node(self)
+      end
+    end
+  end
+end