wordcloud-art-svg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24d01c246c65aac006387ffb99724a50e83a4d640f6b6af605911d10094768ef
+  data.tar.gz: e76789dab4ba284e660659c24220a2ee4d3b463bdc1d6dcc1df1966e995d7eb5
+SHA512:
+  metadata.gz: '0297d296948576df7ca8887f7c006f45a9f7d299f374fe7b0217d744ded423af60aabd4c55aa6b4314c6ef9d2211c4e2c9e7a964e4185529a3be59d8284a3102'
+  data.tar.gz: 00d0c05c69d5f1e361826ce64aa2745994c726334570d1b6fea447ffd81d6662b2669ee91f300b046e5466df1acf2d42ad0756f136ebcb7aaafd486837460dea

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wordcloud.art
+
+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,27 @@
+# Wordcloud.art SVG
+
+Generate an SVG word cloud locally from text or a weighted word list. The command does not require a Wordcloud.art account or send input to a server. Words are placed horizontally using a simple collision-free spiral layout; results will differ from the interactive site's designs.
+
+## Install
+
+```bash
+gem install wordcloud-art-svg
+```
+
+## Use
+
+```bash
+wordcloud-art-svg --text 'design design words colors colors' --output cloud.svg
+wordcloud-art-svg --input notes.txt --output notes.svg --width 1200 --height 800
+wordcloud-art-svg --weights words.tsv --output weighted.svg
+```
+
+Weighted input is UTF-8 TSV with one word and positive weight per line:
+
+```text
+design	8
+visualization	5
+words	3
+```
+
+For shaped word clouds, more colors, and animation, visit [Wordcloud.art](https://www.wordcloud.art/).

data/exe/wordcloud-art-svg

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require_relative '../lib/wordcloud_art_svg'
+
+options = { width: 800, height: 500, background: 'white', max_words: 80 }
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: wordcloud-art-svg (--text TEXT | --input FILE | --weights FILE) --output FILE.svg'
+  opts.on('--text TEXT', 'Text to render') { |v| options[:text] = v }
+  opts.on('--input FILE', 'UTF-8 text file') { |v| options[:input] = v }
+  opts.on('--weights FILE', 'UTF-8 TSV file: WORD<TAB>WEIGHT') { |v| options[:weights] = v }
+  opts.on('--output FILE', 'SVG output file') { |v| options[:output] = v }
+  opts.on('--width NUMBER', Integer) { |v| options[:width] = v }
+  opts.on('--height NUMBER', Integer) { |v| options[:height] = v }
+  opts.on('--background COLOR', 'SVG color value') { |v| options[:background] = v }
+  opts.on('--max-words NUMBER', Integer) { |v| options[:max_words] = v }
+end
+
+begin
+  parser.parse!
+  sources = [:text, :input, :weights].count { |key| options.key?(key) }
+  raise ArgumentError, 'choose exactly one of --text, --input, or --weights' unless sources == 1
+  raise ArgumentError, '--output must end in .svg' unless options[:output]&.downcase&.end_with?('.svg')
+  text = options[:text] || File.read(options[:input] || options[:weights], encoding: 'UTF-8')
+  frequencies = options[:weights] ? WordcloudArtSvg.frequencies_from_tsv(text) : WordcloudArtSvg.frequencies_from_text(text)
+  svg = WordcloudArtSvg.render(frequencies, width: options[:width], height: options[:height], background: options[:background], max_words: options[:max_words])
+  File.write(options[:output], svg, encoding: 'UTF-8')
+  puts options[:output]
+rescue OptionParser::ParseError, ArgumentError, SystemCallError => error
+  warn "wordcloud-art-svg: #{error.message}"
+  warn parser
+  exit 1
+end

data/lib/wordcloud_art_svg/version.rb

@@ -0,0 +1,3 @@
+module WordcloudArtSvg
+  VERSION = '0.1.0'
+end

data/lib/wordcloud_art_svg.rb

@@ -0,0 +1,63 @@
+require 'cgi'
+
+module WordcloudArtSvg
+  module_function
+
+  def frequencies_from_text(text)
+    words = text.scan(/[[:alnum:]][[:alnum:]'’-]*/u)
+    counts = Hash.new(0.0)
+    words.each { |word| counts[word.downcase] += 1.0 }
+    raise ArgumentError, 'input has no words' if counts.empty?
+    counts
+  end
+
+  def frequencies_from_tsv(text)
+    counts = Hash.new(0.0)
+    text.each_line.with_index(1) do |raw, line_number|
+      line = raw.strip
+      next if line.empty? || line.start_with?('#')
+      fields = line.split("\t", -1)
+      raise ArgumentError, "line #{line_number}: expected WORD<TAB>WEIGHT" unless fields.length == 2 && !fields[0].strip.empty?
+      weight = Float(fields[1]) rescue nil
+      raise ArgumentError, "line #{line_number}: weight must be positive and finite" unless weight && weight.finite? && weight.positive?
+      counts[fields[0].strip] += weight
+    end
+    raise ArgumentError, 'word list has no usable entries' if counts.empty?
+    counts
+  end
+
+  def render(frequencies, width: 800, height: 500, background: 'white', max_words: 80)
+    raise ArgumentError, 'width and height must be positive' unless width.to_i.positive? && height.to_i.positive?
+    raise ArgumentError, 'max_words must be positive' unless max_words.to_i.positive?
+    raise ArgumentError, 'word list has no usable entries' if frequencies.empty?
+    width, height = width.to_i, height.to_i
+    entries = frequencies.sort_by { |word, weight| [-weight, word] }.first(max_words.to_i)
+    highest = entries.first[1].to_f
+    placed = []
+    elements = []
+    entries.each_with_index do |(word, weight), index|
+      next unless weight.to_f.finite? && weight.to_f.positive?
+      size = (14 + 58 * Math.sqrt(weight.to_f / highest)).round
+      size = [size, [width / 3, height / 3].min].min
+      estimated_width = word.each_char.sum { |char| char.ord > 0x2e80 ? 1.0 : 0.6 } * size
+      box_width = estimated_width + 8
+      box_height = size * 1.25 + 8
+      next if box_width > width || box_height > height
+      1800.times do |step|
+        radius = 2.6 * Math.sqrt(step)
+        angle = step * 2.399963229728653 + index
+        x = width / 2.0 + radius * Math.cos(angle) - box_width / 2.0
+        y = height / 2.0 + radius * Math.sin(angle) - box_height / 2.0
+        next if x < 0 || y < 0 || x + box_width > width || y + box_height > height
+        next if placed.any? { |bx, by, bw, bh| x < bx + bw && x + box_width > bx && y < by + bh && y + box_height > by }
+        placed << [x, y, box_width, box_height]
+        color = %w[#275dad #29a69a #ef7d57 #6b5b95 #c15c86][index % 5]
+        elements << %(<text x="#{(x + 4).round(1)}" y="#{(y + size + 2).round(1)}" font-size="#{size}" fill="#{color}">#{CGI.escapeHTML(word)}</text>)
+        break
+      end
+    end
+    raise ArgumentError, 'canvas is too small to place any words' if elements.empty?
+    safe_background = CGI.escapeHTML(background.to_s)
+    %(<?xml version="1.0" encoding="UTF-8"?>\n<svg xmlns="http://www.w3.org/2000/svg" width="#{width}" height="#{height}" viewBox="0 0 #{width} #{height}">\n<rect width="100%" height="100%" fill="#{safe_background}"/>\n<g font-family="Arial, Helvetica, sans-serif" font-weight="bold">\n#{elements.join("\n")}\n</g>\n</svg>\n)
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: wordcloud-art-svg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wordcloud.art
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-11-03 00:00:00.000000000 Z
+dependencies: []
+description: A small offline Ruby command that lays out weighted words in a collision-free
+  SVG word cloud.
+email: 
+executables:
+- wordcloud-art-svg
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/wordcloud-art-svg
+- lib/wordcloud_art_svg.rb
+- lib/wordcloud_art_svg/version.rb
+homepage: https://www.wordcloud.art/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.wordcloud.art/
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Generate SVG word clouds from text or weighted word lists
+test_files: []