zer0-image-generator 0.6.0 → 0.8.0

data/lib/zer0_image_generator/svg/banner_seed.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require_relative "local_renderer" # render_local_svg + the shared seed_for/palette/composition scheme
+require_relative "sanitizer"      # sanitize_svg + SvgError — the REAL sanitizer, never a copy
+require_relative "rasterizer"     # which() for montage discovery; rasterize_svg for the full sweep
+
+module Zer0ImageGenerator
+  module Svg
+    # Parametric adapter over the engine's OWN `local` banner template — the
+    # Ruby port of tools/svg/banner-seed.py, plus tools/svg/svg-sweep.sh's
+    # contact-sheet stitching.
+    #
+    # The adapter is deliberately thin: a sweep must judge the REAL `local`
+    # output, so it renders through LocalRenderer.render_local_svg and cleans
+    # through the real Sanitizer.sanitize_svg — the exact path LocalProvider
+    # ships (render_local_svg(slug, seed_for(slug)) -> sanitize_svg). It never
+    # reimplements either, so a change to the template is seen on true output
+    # instead of a lookalike.
+    #
+    # BYTE-IDENTITY (see test/ruby/test_banner_seed.rb):
+    #   * The PRE-sanitize render is byte-identical to the Python adapter's —
+    #     render_local_svg is a hard determinism contract (seeded LCG only).
+    #   * The FINAL sanitized string is the SAME DOM but NOT byte-identical: the
+    #     ported Sanitizer serializes via REXML (single quotes, alphabetized
+    #     attributes, spaced self-closing tags) where Python uses ElementTree.
+    #     That serializer difference is owned and documented by the sanitizer
+    #     slice; this adapter inherits it. The test proves DOM byte-identity by
+    #     canonicalizing both outputs through REXML.
+    module BannerSeed
+      # argparse defaults from banner-seed.py.
+      DEFAULT_SEED = 1
+      DEFAULT_OUT = ".sweep/banner.svg"
+
+      # OptionParser token for a base-10 integer flag (see main). A bare token
+      # object is all OptionParser#accept needs as the type key.
+      Base10Int = Object.new
+
+      # svg-sweep.sh's `montage` knobs, verbatim: a dark contact sheet, filename
+      # labels, fixed 400px cells with 8px gutters. The tile column count is
+      # per-run (ceil(sqrt(N))), so it is computed, not stored here.
+      MONTAGE_LABEL = "%f"
+      MONTAGE_BACKGROUND = "#111"
+      MONTAGE_FILL = "#eee"
+      MONTAGE_GEOMETRY = "400x400+8+8"
+
+      # Raised when a contact sheet is requested but ImageMagick's `montage` is
+      # not on PATH. svg-sweep.sh exits 127 for this; as a library we surface it
+      # as an explicit, actionable error rather than an exit code. ImageMagick
+      # is an OPTIONAL dependency — everything else here runs without it.
+      class MontageMissing < StandardError; end
+
+      module_function
+
+      # seed_for lives on LocalRenderer (the shared seed -> palette/composition
+      # contract also used by the claude provider). Re-exposed so the studio and
+      # CLI resolve slugs without reaching across modules. zlib.crc32 of the
+      # UTF-8 bytes; matches pg.seed_for exactly.
+      def seed_for(slug)
+        LocalRenderer.seed_for(slug)
+      end
+
+      # banner-seed.py's (title, seed) rule. A non-empty --slug wins and
+      # reproduces that post's banner (title = slug, seed derived as the engine
+      # derives it); otherwise a bare --seed drives the palette/composition
+      # scheme directly under a synthetic "banner-seed-N" title. Returns
+      # [title, seed]. Empty-string slug is falsy exactly as `if args.slug:` is.
+      def resolve(seed: DEFAULT_SEED, slug: "")
+        if slug.nil? || slug.empty?
+          ["banner-seed-#{seed}", seed]
+        else
+          [slug, seed_for(slug)]
+        end
+      end
+
+      # Core operation, == pg.sanitize_svg(pg.render_local_svg(title, seed)).
+      # Returns [svg_text, notes]; notes is the sanitizer's warnings list.
+      def generate(seed: DEFAULT_SEED, slug: "")
+        title, resolved = resolve(seed: seed, slug: slug)
+        Sanitizer.sanitize_svg(LocalRenderer.render_local_svg(title, resolved))
+      end
+
+      # Just the sanitized SVG string — the studio's common case. Notes are
+      # dropped; for the local template they are always empty (it renders SVG
+      # the sanitizer accepts untouched). Callers needing notes use #generate.
+      def svg(seed: DEFAULT_SEED, slug: "")
+        generate(seed: seed, slug: slug).first
+      end
+
+      # Rails "SVG studio" entry point: hand back one result per seed with no
+      # shelling out. Each entry is { seed:, title:, svg:, notes: }. Accepts any
+      # Enumerable of seeds (a form may request an arbitrary set, not a range).
+      def render_many(seeds)
+        seeds.map do |seed|
+          svg_text, notes = generate(seed: seed)
+          { seed: seed, title: "banner-seed-#{seed}", svg: svg_text, notes: notes }
+        end
+      end
+
+      # svg-sweep.sh's sweep shape: seeds `first .. first+count-1` (the bash
+      # sweeps 1..N). Returns the same { seed:, title:, svg:, notes: } records.
+      def sweep(count, first: 1)
+        raise ArgumentError, "count must be non-negative" if count.negative?
+
+        render_many(first...(first + count))
+      end
+
+      # File-writing half of banner-seed.py: make the parent dir, write UTF-8,
+      # emit sanitizer notes to `err`. Returns the out path (what the CLI prints
+      # to stdout). Separate from #generate so the studio never touches disk.
+      def write(out, seed: DEFAULT_SEED, slug: "", err: $stderr)
+        svg_text, notes = generate(seed: seed, slug: slug)
+        notes.each { |note| err.puts("sanitizer: #{note}") }
+        # os.makedirs(dirname(out) or ".", exist_ok=True): dirname("banner.svg")
+        # is "" -> ".", and mkdir_p(".") is a harmless no-op.
+        dir = File.dirname(out)
+        FileUtils.mkdir_p(dir.empty? ? "." : dir)
+        # The SVG string is UTF-8; write its bytes as-is (Python opens utf-8).
+        File.write(out, svg_text)
+        out
+      end
+
+      # CLI port of banner-seed.py's main(): parse --seed/--slug/--out, write the
+      # file, print the out path to `out`. Returns a process exit code (0 on
+      # success, 2 on a bad argument, mirroring argparse). Exposed so a bin/ shim
+      # or a test can drive the exact documented CLI surface without a subprocess.
+      def main(argv, out: $stdout, err: $stderr)
+        opts = { seed: DEFAULT_SEED, slug: "", out: DEFAULT_OUT }
+        parser = OptionParser.new do |p|
+          # Base-10, like Python argparse's `type=int` (int()). OptionParser's
+          # built-in Integer accepts 0x/0o/0b prefixes, so `--seed 010` would be
+          # octal 8 in Ruby but decimal 10 in Python — a different banner.
+          p.accept(Base10Int, /\A\s*[-+]?\d+\s*\z/) { |s| Integer(s.strip, 10) }
+          p.on("--seed N", Base10Int) { |v| opts[:seed] = v }
+          p.on("--slug SLUG", String, "derive the seed from a post slug, as the engine does") do |v|
+            opts[:slug] = v
+          end
+          p.on("--out PATH", String) { |v| opts[:out] = v }
+        end
+        begin
+          parser.parse(argv)
+        rescue OptionParser::ParseError => exc
+          # argparse writes usage + error to stderr and exits 2. Mirror the exit
+          # code with an explicit message; never swallow the parse failure.
+          err.puts(exc.message)
+          return 2
+        end
+        out.puts(write(opts[:out], seed: opts[:seed], slug: opts[:slug], err: err))
+        0
+      end
+
+      # ---- svg-sweep.sh contact-sheet logic --------------------------------
+
+      # ceil(sqrt(N)) — svg-sweep.sh's column count. Own method so the sweep and
+      # any caller building a montage agree on layout. Math.sqrt(N).ceil matches
+      # Python's math.ceil(math.sqrt(N)) (both IEEE-754, exact on perfect squares).
+      def tile_columns(count)
+        Math.sqrt(count).ceil
+      end
+
+      # `command -v montage` equivalent, via the ported Rasterizer.which (itself
+      # shutil.which-equivalent and memoized). nil when ImageMagick is absent.
+      def montage_path
+        Rasterizer.which("montage")
+      end
+
+      def montage_available?
+        !montage_path.nil?
+      end
+
+      # The exact `montage` argv from svg-sweep.sh, as an array (no shell). Built
+      # separately from #contact_sheet so the flag set can be asserted without
+      # ImageMagick installed. `bin` defaults to the plain name for that offline
+      # inspection; #contact_sheet passes the resolved absolute path.
+      def montage_argv(png_paths, out:, columns: nil, bin: "montage")
+        cols = columns || tile_columns(png_paths.length)
+        [bin, "-label", MONTAGE_LABEL,
+         "-background", MONTAGE_BACKGROUND, "-fill", MONTAGE_FILL,
+         "-tile", "#{cols}x", "-geometry", MONTAGE_GEOMETRY,
+         *png_paths.map(&:to_s), out.to_s]
+      end
+
+      # Stitch PNGs into one labelled contact sheet via ImageMagick `montage`.
+      # ImageMagick is optional: when `montage` is absent this raises
+      # MontageMissing with an actionable message instead of failing obscurely.
+      # Returns the output path on success.
+      def contact_sheet(png_paths, out:, columns: nil)
+        montage = montage_path
+        unless montage
+          raise MontageMissing,
+                "ImageMagick 'montage' not found on PATH; install ImageMagick " \
+                "(e.g. `brew install imagemagick`) to stitch contact sheets"
+        end
+        raise ArgumentError, "no PNGs to montage" if png_paths.empty?
+
+        cmd = montage_argv(png_paths, out: out, columns: columns, bin: montage)
+        # system returns false on non-zero exit; surface it rather than pretend
+        # the sheet was written.
+        unless system(*cmd)
+          raise "montage exited #{$?.exitstatus} building #{out}"
+        end
+
+        out
+      end
+
+      # Full svg-sweep.sh pipeline in Ruby, opt-in: render seeds 1..count to SVG
+      # under `dir`, rasterize each to PNG, then montage them into one sheet.
+      # Returns the contact-sheet path.
+      #
+      # The SVG->PNG step delegates to the engine's Rasterizer (another slice);
+      # the dev-side svg-render.sh chain (400px, ImageMagick-free) is not
+      # separately ported, so this reuses the engine chain and lets `montage`'s
+      # -geometry downscale to the same 400px cells. Both external tools are
+      # optional: an empty render set or a missing montage raises explicitly.
+      # The studio uses #sweep (in-memory) instead of this disk+subprocess path.
+      def sweep_contact_sheet(count, dir: ".sweep", preview_dir: ".preview",
+                              project_root: Dir.pwd)
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+        FileUtils.mkdir_p(preview_dir)
+
+        pngs = []
+        (1..count).each do |seed|
+          svg_path = File.join(dir, "seed-#{seed}.svg")
+          write(svg_path, seed: seed)
+          png_path = File.join(preview_dir, "seed-#{seed}.png")
+          # Only montage what actually rasterized; unlike the bash's stale
+          # `.preview/seed-*.png` glob, this feeds exactly this run's outputs.
+          pngs << png_path if Rasterizer.rasterize_svg(svg_path, png_path, project_root)
+        end
+        if pngs.empty?
+          raise "no PNGs rendered; install a rasterizer " \
+                "(resvg / rsvg-convert / inkscape / cairosvg) to sweep"
+        end
+
+        contact_sheet(pngs, out: File.join(dir, "contact-sheet.png"))
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/svg/generators/flowfield.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../../support/py_random"
+
+module Zer0ImageGenerator
+  module Svg
+    module Generators
+      # Parametric flow-field — port of `tools/svg/examples/flowfield.py`.
+      #
+      # Seed a cloud of particles, then walk each one downstream through a
+      # value-noise field, emitting the trail as a polyline. The canonical
+      # "generator with knobs": lines/steps/scale/palette are the only dials,
+      # every coordinate falls out of the seeded stream.
+      #
+      # The committed artwork under `docs/samples/flowfield-*.svg` and
+      # `docs/showcase/variants/flowfield-*.svg` was produced by the Python
+      # original, so this port is pinned to byte-identical output: every draw
+      # comes off `Support::PyRandom` in the same order the Python drew it, and
+      # every interpolated number is formatted to the same width the f-strings
+      # used.
+      module Flowfield
+        PALETTES = {
+          "ember" => ["#1a1423", "#f24236", "#f5a623", "#f7e8d3"].freeze,
+          "cyanic" => ["#0b132b", "#1c7293", "#5bc0be", "#e8f1f2"].freeze,
+          "moss" => ["#16211b", "#3e6b48", "#a3c9a8", "#e9edc9"].freeze,
+        }.freeze
+
+        DEFAULT_PALETTE = "cyanic"
+
+        # Python's `math.tau` is the precomputed double 2*pi; `Math::PI * 2` is
+        # the identical bit pattern, so `angle` matches to the last ULP.
+        TAU = Math::PI * 2
+
+        HALF = Rational(1, 2)
+        private_constant :HALF
+
+        class << self
+          # Cheap hash-based value noise with bilinear interpolation. Returns a
+          # callable sampler; the hash is pure integer arithmetic so it ports
+          # directly — Ruby and CPython agree on `>>`, `&`, and `^` for the
+          # negative lattice coordinates `math.floor` can produce.
+          def value_noise(seed)
+            hash = lambda do |ix, iy|
+              n = (ix * 374_761_393) + (iy * 668_265_263) + (seed * 1_442_695_040_888_963_407)
+              n = (n ^ (n >> 13)) * 1_274_126_177
+              # `/ 0xFFFF` is true division in Python; fdiv keeps it a Float
+              # instead of Ruby's integer division.
+              ((n ^ (n >> 16)) & 0xFFFF).fdiv(0xFFFF)
+            end
+            smooth = ->(t) { t * t * (3 - (2 * t)) }
+            lambda do |x, y|
+              ix = x.floor
+              iy = y.floor
+              fx = smooth.call(x - ix)
+              fy = smooth.call(y - iy)
+              a = hash.call(ix, iy)
+              b = hash.call(ix + 1, iy)
+              c = hash.call(ix, iy + 1)
+              d = hash.call(ix + 1, iy + 1)
+              ((a * (1 - fx)) + (b * fx)) * (1 - fy) + (((c * (1 - fx)) + (d * fx)) * fy)
+            end
+          end
+
+          # Returns the finished SVG document, newline-terminated.
+          def build(seed, w, h, lines, steps, scale, palette)
+            rng = Support::PyRandom.new(seed)
+            noise = value_noise(seed)
+            colors = PALETTES.fetch(palette)
+            out = []
+
+            lines.times do
+              x = rng.uniform(0, w)
+              y = rng.uniform(0, h)
+              pts = [[x, y]]
+              steps.times do
+                angle = noise.call(x / scale, y / scale) * TAU * 2
+                x += Math.cos(angle) * 4
+                y += Math.sin(angle) * 4
+                break unless -20 < x && x < w + 20 && -20 < y && y < h + 20
+
+                pts << [x, y]
+              end
+              # Too-short trails are dropped BEFORE their stroke/width/opacity
+              # draws — mirroring Python's `continue`, so the RNG stays in sync.
+              next if pts.length < 8
+
+              d = "M" + pts.map { |px, py| "#{fmt(px, 0)},#{fmt(py, 0)}" }.join(" L")
+              stroke = rng.choice(colors[1..])
+              width = rng.uniform(0.4, 2.4)
+              op = rng.uniform(0.25, 0.8)
+              out << %(<path d="#{d}" fill="none" stroke="#{stroke}" ) +
+                     %(stroke-width="#{fmt(width, 2)}" stroke-opacity="#{fmt(op, 2)}" ) +
+                     %(stroke-linecap="round"/>)
+            end
+
+            %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{w} #{h}" ) +
+              "role=\"img\">\n" \
+              "  <title>Flow field, seed #{seed}, palette #{palette}</title>\n" +
+              %(  <rect width="#{w}" height="#{h}" fill="#{colors[0]}"/>) + "\n  " +
+              out.join("\n  ") + "\n</svg>\n"
+          end
+
+          # Exact correctly-rounded fixed-point, matching Python's `f"{x:.Nf}"`
+          # (round-half-to-even on the exact binary value). Ruby's `%f`/`round`
+          # round the shortest decimal instead, which diverges on ties.
+          def fmt(value, places)
+            negative = value.negative? || (value.zero? && (1.0 / value).negative?)
+            scaled = value.abs.to_r * (10**places)
+            whole = scaled.floor
+            remainder = scaled - whole
+            whole += 1 if remainder > HALF || (remainder == HALF && whole.odd?)
+
+            digits = whole.to_s.rjust(places + 1, "0")
+            text = places.zero? ? digits : "#{digits[0...-places]}.#{digits[-places..]}"
+            negative ? "-#{text}" : text
+          end
+        end
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  require "fileutils"
+
+  opts = { seed: 1, out: "art/flowfield.svg", width: 800, height: 800,
+           lines: 240, steps: 70, scale: 180.0,
+           palette: Zer0ImageGenerator::Svg::Generators::Flowfield::DEFAULT_PALETTE }
+  argv = ARGV.dup
+  until argv.empty?
+    flag = argv.shift
+    val = argv.shift
+    case flag
+    when "--seed" then opts[:seed] = Integer(val)
+    when "--out" then opts[:out] = val
+    when "--width" then opts[:width] = Integer(val)
+    when "--height" then opts[:height] = Integer(val)
+    when "--lines" then opts[:lines] = Integer(val)
+    when "--steps" then opts[:steps] = Integer(val)
+    when "--scale" then opts[:scale] = Float(val)
+    when "--palette" then opts[:palette] = val
+    else raise ArgumentError, "unknown flag #{flag.inspect}"
+    end
+  end
+
+  dir = File.dirname(opts[:out])
+  FileUtils.mkdir_p(dir.empty? ? "." : dir)
+  svg = Zer0ImageGenerator::Svg::Generators::Flowfield.build(
+    opts[:seed], opts[:width], opts[:height], opts[:lines],
+    opts[:steps], opts[:scale], opts[:palette]
+  )
+  File.write(opts[:out], svg)
+  puts opts[:out]
+end

data/lib/zer0_image_generator/svg/generators/invaders.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "../../support/py_random"
+# The retro pixel toolkit is a sibling slice
+# (lib/zer0_image_generator/svg/pixel_kit.rb). Load it unless a caller — a test
+# harness pinning byte-identity — has already supplied the namespace; the
+# `defined?` guard lets that stub stand in without a second load, and a genuine
+# absence still surfaces as an explicit LoadError from require_relative.
+require_relative "../pixel_kit" unless defined?(Zer0ImageGenerator::Svg::PixelKit)
+
+module Zer0ImageGenerator
+  module Svg
+    module Generators
+      # Procedural fixed-shooter scene — port of `tools/svg/examples/invaders.py`.
+      #
+      # Each wave's alien species are *generated*: random cells in a half-grid,
+      # mirrored (hmirror) — bilateral symmetry is what makes random blobs read
+      # as creatures. One alien is mid-explosion; the symmetry break is the
+      # subject.
+      #
+      # Byte-identity contract: `docs/samples/invaders-*.svg` and
+      # `docs/showcase/variants/invaders-dusk-3.svg` were produced here, so every
+      # draw must come off `Support::PyRandom` in the Python order. `alien` does
+      # rejection sampling, so the number of draws is data-dependent — the
+      # density predicate has to match exactly or the whole stream desyncs.
+      module Invaders
+        SHIP = [
+          ".....#.....",
+          "....l#l....",
+          ".l.l###l.l.",
+          "###########",
+          "l#l#l#l#l#l",
+        ].freeze
+
+        BUNKER = [
+          ".########.",
+          "##########",
+          "##########",
+          "###....###",
+          "##......##",
+        ].freeze
+
+        MINI_SHIP = [
+          "..#..",
+          ".###.",
+          "#####",
+        ].freeze
+
+        BOOM = [
+          "#..#.#..#",
+          ".#..#..#.",
+          "..#####..",
+          ".#..#..#.",
+          "#..#.#..#",
+        ].freeze
+
+        DEFAULT_PALETTE = "cyanic"
+
+        class << self
+          # Random half-grid, mirrored. Reject sprites too sparse or too dense
+          # to read as a creature. The bounds are `0.35..0.75` of the half-grid
+          # cell count as floats, compared against the integer mass — mirror the
+          # comparison exactly, since a stricter/looser predicate changes how
+          # many times the loop redraws and shifts every later value.
+          def alien(rng, half_w = 6, height = 8)
+            loop do
+              rows = Array.new(height) do
+                Array.new(half_w) { rng.random < 0.55 ? "#" : "." }.join
+              end
+              mass = rows.sum { |row| row.count("#") }
+              lo = 0.35 * half_w * height
+              hi = 0.75 * half_w * height
+              return Svg::PixelKit.hmirror(rows) if mass >= lo && mass <= hi
+            end
+          end
+
+          def build(seed, palette = DEFAULT_PALETTE)
+            rng = Support::PyRandom.new(seed)
+            pal = Svg::PixelKit::PALETTES.fetch(palette)
+            canvas = Svg::Canvas.new(64, 48, px: 12, bg: pal[0])
+
+            # Starfield, sparse and uneven — heavier toward the top. The color
+            # draw happens only when the placement test passes; keep it inside
+            # the branch so the stream matches.
+            70.times do
+              col = rng.randrange(64)
+              row = rng.randrange(44)
+              if rng.random < ((1.0 - (row / 44.0)) * 0.8)
+                canvas.set(col, row, rng.random < 0.6 ? pal[1] : pal[2])
+              end
+            end
+
+            # Three ranks of aliens, one species per rank, 5 across
+            species = Array.new(3) { alien(rng) }
+            rank_color = [pal[5], pal[4], pal[3]]
+            hit = [rng.randrange(3), rng.randrange(5)] # one alien mid-explosion
+            3.times do |rank|
+              5.times do |i|
+                col = 1 + (i * 13)
+                row = 5 + (rank * 10)
+                if [rank, i] == hit
+                  canvas.blit(BOOM, { "#" => pal[4] }, col + 1, row + 1)
+                else
+                  canvas.blit(species[rank], { "#" => rank_color[rank] }, col, row)
+                end
+              end
+            end
+
+            # A shot on its way up from the player
+            shot_col = 1 + (rng.randrange(5) * 13) + 5
+            canvas.fill(shot_col, 33, 1, 3, pal[5])
+
+            # Bunkers, ship, ground, lives
+            3.times { |i| canvas.blit(BUNKER, { "#" => pal[2] }, 5 + (i * 22), 36) }
+            canvas.blit(SHIP, { "#" => pal[4], "l" => pal[3] }, 26, 41)
+            canvas.fill(0, 46, 64, 1, pal[2])
+            3.times { |i| canvas.blit(MINI_SHIP, { "#" => pal[2] }, 2 + (i * 7), 1) }
+
+            canvas.to_svg("Invader wave, seed #{seed}, palette #{palette}", crt: true)
+          end
+        end
+      end
+    end
+  end
+end