RubyGems - inkplot - Versions diffs - 0.1.0 → 0.3.0 - Mend

inkplot 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +2 -2
data/LICENSE.txt +1 -1
data/README.md +70 -22
data/bench/inkplot.rb +3 -0
data/examples/gallery/09-signed-stack.svg +1 -0
data/examples/gallery/12-histogram.svg +1 -0
data/examples/gallery/13-log-scale.svg +1 -0
data/examples/gallery/14-time-axis.svg +1 -0
data/examples/gallery/15-category-order.svg +1 -0
data/examples/gallery/16-dark-theme.svg +1 -0
data/examples/gallery/17-annotations.svg +1 -0
data/examples/gallery/18-combo.svg +1 -0
data/examples/gallery/19-legend-position.svg +1 -0
data/examples/gallery/20-long-categories.svg +1 -0
data/examples/gallery/README.md +7 -2
data/examples/gallery.rb +52 -2
data/lib/inkplot/core.rb +177 -7
data/lib/inkplot/renderers/raster.rb +322 -0
data/lib/inkplot/version.rb +1 -1
data/lib/inkplot.rb +8 -0
data/sig/inkplot.rbs +7 -1
metadata +20 -5

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b849fabe00ddcb70337337fe69039b30a4d5c6897ba99c1ab23503c856c9355
-  data.tar.gz: 1303d52c866fbab95d6a933200162b890f2e1deee22c2dc1bc3eb95e7bf3942b
+  metadata.gz: 90a3ec94d835a8c52be1645190c450486b74e3d69e69f9c7a32759c52cd9fbad
+  data.tar.gz: 670616432fd769febb36b31b338d506e58abb41fbdc32820fd0b97b0df9c2ec3
 SHA512:
-  metadata.gz: f5c7e69766bb2bd50ed69f680693e90463390b7183366802273c3d940ac343a5a3ec120a94b2afe362438fbca4c6d8b7ecf7afc9af2624583852971240a0122d
-  data.tar.gz: e4a74f925d2c6d2eec4af35f034f4278531e09e0f3517ce8c82dde71611b0771da34bdf4ea6a3cc548c68cf5690f19137c189985e1a28a1012bf0dbf859c312e
+  metadata.gz: 23eef7bbe84575c0b7d32626a36d880de2a7e5c408791df60b9b0675a8a561bf9c58aa2aea0d28dd0653c126ce9746672bfd83ea734480a84cfbf74af334a861
+  data.tar.gz: c80647ebc946d60e8ec623010735aea0f71e922c296d2777265251ad8766a2fef0d3848326ed735d48ca72c0d797cf8eda00468a2dc76cad36c22fa85e9c358c

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,5 @@
 # Changelog
-## [0.1.0] - 2026-09-25
+## [0.3.0] - 2026-09-25
-Initial release
+- Implement SVG and PNG chart rendering, scales, annotations, terminal sparklines, REPL adaptation, and the 20-chart gallery.

data/LICENSE.txt CHANGED Viewed

@@ -1,6 +1,6 @@
 The MIT License (MIT)
-Copyright (c) 2026 Yudai Takada
+Copyright (c) 2026 ydah
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 <h1 align="center">Inkplot</h1>
-<p align="center">Build clear charts as standalone SVG with plain Ruby data.</p>
+<p align="center">Ruby charts, drawn as portable SVG or PNG.</p>
 <p align="center">
   <a href="https://github.com/rbgfx/inkplot/actions/workflows/main.yml"><img src="https://github.com/rbgfx/inkplot/actions/workflows/main.yml/badge.svg" alt="CI"></a>
@@ -8,65 +8,113 @@
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="MIT license"></a>
 </p>
-Inkplot draws line, scatter, bar, area, and step charts without native libraries or runtime dependencies.
+Line, bar, scatter, area, step, and histogram charts with clean defaults. SVG runs on Ruby alone; optional pure Ruby image gems add PNG output and REPL display.
+## At a glance
+- **No runtime dependencies for SVG** and no native graphics libraries.
+- **Useful defaults:** automatic linear, logarithmic, category, and time scales; readable ticks, legends, and light or dark themes.
+- **Ruby data in:** arrays, hashes, CSV tables, and records with string or symbol keys.
+- **Flexible output:** SVG strings, PNG bytes, `Tessel::Image`, files, and terminal sparklines.
+- **Optional adapters:** Tessel and Glyphic for PNG; Inlay for IRB, Pry, and IRuby.
 ## Install
-Until the first RubyGems release, add the GitHub repository to your Gemfile:
+Until the first RubyGems release, add Inkplot from GitHub:
 ```ruby
 gem "inkplot", github: "rbgfx/inkplot"
 ```
+SVG needs only Inkplot. For PNG output, add the optional render dependencies:
+```ruby
+gem "tessel", github: "rbgfx/tessel"
+gem "glyphic", github: "rbgfx/glyphic"
+```
+Glyphic's built-in font covers ASCII. For other scripts, set a TrueType font:
+```ruby
+Inkplot.config.font = "/path/to/font.ttf"
+```
 ## Quick start
 ```ruby
 require "inkplot"
-chart = Inkplot.line([3, 1, 4, 1, 5, 9], title: "A small series")
+chart = Inkplot.line([3, 1, 4, 1, 5, 9, 2, 6], title: "A small series")
 chart.save("series.svg")
+chart.save("series.png", width: 800, height: 450, scale: 2)
+```
+Use CSV or records directly. Keys can be symbols or strings; `color:` splits records into labeled series.
+```ruby
+require "csv"
+rows = CSV.parse(File.read("sales.csv"), headers: true)
+chart = Inkplot.line(rows, x: "month", y: "sales", color: "region", title: "Monthly sales")
+chart.to_svg # => standalone SVG string
 ```
-Use the builder to combine series and configure axes:
+The builder API combines marks, scales, and annotations:
 ```ruby
 chart = Inkplot.plot(width: 720, height: 420, theme: :dark) do |plot|
-  plot.title "Quarterly requests"
-  plot.x_axis(label: "Quarter")
-  plot.y_axis(label: "Requests", min: 0)
-  plot.line(%w[Q1 Q2 Q3 Q4], [18, 23, 28, 36], label: "Current")
-  plot.line(%w[Q1 Q2 Q3 Q4], [14, 19, 21, 30], label: "Previous", dash: true)
-  plot.hline(25, label: "Target")
-  plot.legend(position: :top_right)
+  plot.title "Request latency"
+  plot.x_axis label: "Time", type: :time
+  plot.y_axis label: "Milliseconds", scale: :log, min: 1
+  plot.line times, p50, label: "p50"
+  plot.line times, p99, label: "p99", dash: true
+  plot.hline 200, label: "SLO", color: :red
+  plot.legend position: :top_right
 end
-svg = chart.to_svg
 ```
-## Data and output
+`Inkplot.bar(data, horizontal: true)` draws horizontal bars. `Inkplot.histogram(values, bins: :auto)` chooses bins with Freedman–Diaconis, falling back to Sturges when the interquartile range is zero. Builder methods also provide grouped and signed stacked bars, areas, steps, sized scatter points, and text or line annotations.
-Charts accept arrays, hashes, CSV tables, and records with string or symbol keys. Scales include linear, logarithmic, and ordered categories. Light and dark themes, grouped and stacked bars, and terminal sparklines are included.
+## Gallery
-The [gallery](examples/gallery/README.md) contains ten runnable examples. Regenerate its SVG previews with:
+Twenty runnable chart examples and SVG previews are in the [gallery](examples/gallery/README.md). Rebuild the SVGs with:
 ```sh
 ruby examples/gallery.rb
 ```
+## REPL and terminal
+When [Inlay](https://github.com/rbgfx/inlay) is loaded, Inkplot's `to_inlay` adapter returns SVG plus a lazy PNG fallback. A terminal without an inline image protocol can use:
+```ruby
+puts Inkplot.sparkline([3, 1, 4, 1, 5, 9, 2, 6]) # => "▃▁▄▁▅█▂▅"
+```
+## Performance
+Reference run on Ruby 4.0.6 with YJIT, at 640×360: a 1,000-point line rendered to SVG in 3 ms, the same chart to PNG in 235 ms, and a 10,000-point scatter plot to PNG in 668 ms. These single-run measurements met the design targets of 50 ms, 300 ms, and 1 second respectively; see `bench/inkplot.rb` to rerun them.
 ## API contracts
-- `to_svg` returns a standalone SVG string; `save` writes an `.svg` file.
-- Paired x/y arrays must have the same length. Non-finite y values break line segments by default; use `gaps: :connect` to bridge them.
-- Explicit axis limits must be ordered. Log scales omit non-positive values.
-- Invalid scales, colors, dimensions, and file extensions raise `ArgumentError`.
+- Chart dimensions must be at least 120×100 pixels. Paired x/y vectors must have equal lengths.
+- Non-finite y values are treated as gaps. `gaps: :connect` connects line segments across them.
+- Explicit axis limits must be valid and ordered. Log axes omit non-positive values with a warning; mixed time-zone offsets raise `ArgumentError`.
+- Invalid scales, colors, dimensions, bin definitions, and output extensions raise `ArgumentError`.
+- `to_svg` needs no optional gems. PNG methods raise `LoadError` with the missing gem's install command.
+- SVG text is escaped; color input accepts a hexadecimal value or a supported CSS color name.
+- PNG rendering uses a built-in 2× coverage pass before downsampling. Pure Ruby rendering is intended for charts and reports, not huge photo workloads.
 ## Development
 ```sh
 bundle install
 bundle exec rake verify
+bundle exec rbs validate
 ```
+The test suite compares all gallery PNGs against Lookalike snapshots. Update them intentionally with `bundle exec ruby examples/gallery.rb --update-snapshots`.
 ## License
-MIT. See [LICENSE.txt](LICENSE.txt).
+[MIT](LICENSE.txt)

data/bench/inkplot.rb CHANGED Viewed

@@ -5,8 +5,11 @@ require "inkplot"
 points = 1_000.times.map { |index| Math.sin(index / 20.0) }
 line = Inkplot.line(points)
+scatter = Inkplot.scatter(10_000.times.map { |index| [index % 1_000, Math.sin(index / 100.0)] })
 puts "YJIT=#{RubyVM::YJIT.enabled?} Ruby=#{RUBY_VERSION}"
 Benchmark.bm(22) do |bench|
   bench.report("1k line SVG") { line.to_svg }
+  bench.report("1k line PNG") { line.to_png }
+  bench.report("10k scatter PNG") { scatter.to_png }
 end

data/examples/gallery/09-signed-stack.svg ADDED Viewed

@@ -0,0 +1 @@

+ <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" width="640" height="360" role="img" class="inkplot"><defs><clipPath id="plot-clip"><rect x="42" y="40" width="460" height="286"/></clipPath></defs><rect x="0" y="0" width="640" height="360" fill="#FFFFFF"/><path class="grid-line" d="M 42 326 L 502 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="330" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">-10</text><path class="grid-line" d="M 42 230.67 L 502 230.67" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="234.67" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">0</text><path class="grid-line" d="M 42 135.33 L 502 135.33" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="139.33" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">10</text><path class="grid-line" d="M 88 40 L 88 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="88" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Mon</text><path class="grid-line" d="M 180 40 L 180 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="180" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Tue</text><path class="grid-line" d="M 272 40 L 272 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="272" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Wed</text><path class="grid-line" d="M 364 40 L 364 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="364" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Thu</text><path class="grid-line" d="M 456 40 L 456 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="456" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Fri</text><path class="axis-line" d="M 42 40 L 42 326 L 502 326" fill="none" stroke="#626B78" stroke-width="1"/><text x="320" y="22" fill="#20242B" text-anchor="middle" font-size="15" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Daily net change</text><path class="mark-line" d="M 390 54 L 406 54" fill="none" stroke="#0072B2" stroke-width="2"/><text x="412" y="58" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">New</text><path class="mark-line" d="M 390 72 L 406 72" fill="none" stroke="#E69F00" stroke-width="2"/><text x="412" y="76" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Removed</text><g class="series-marks" clip-path="url(#plot-clip)"><g class="series series-0" data-series="0"><rect class="bar-mark" x="52.12" y="154.4" width="70.76" height="76.27" fill="#0072B2"/><rect class="bar-mark" x="144.12" y="230.67" width="70.76" height="38.13" fill="#0072B2"/><rect class="bar-mark" x="236.12" y="183" width="70.76" height="47.67" fill="#0072B2"/><rect class="bar-mark" x="328.12" y="230.67" width="70.76" height="19.07" fill="#0072B2"/><rect class="bar-mark" x="420.12" y="144.87" width="70.76" height="85.8" fill="#0072B2"/></g><g class="series series-1" data-series="1"><rect class="bar-mark" x="52.12" y="125.8" width="70.76" height="28.6" fill="#E69F00"/><rect class="bar-mark" x="144.12" y="268.8" width="70.76" height="57.2" fill="#E69F00"/><rect class="bar-mark" x="236.12" y="163.93" width="70.76" height="19.07" fill="#E69F00"/><rect class="bar-mark" x="328.12" y="249.73" width="70.76" height="47.67" fill="#E69F00"/><rect class="bar-mark" x="420.12" y="106.73" width="70.76" height="38.13" fill="#E69F00"/></g></g></svg>

data/examples/gallery/12-histogram.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/13-log-scale.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/14-time-axis.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/15-category-order.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/16-dark-theme.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/17-annotations.svg ADDED Viewed

@@ -0,0 +1 @@

data/examples/gallery/18-combo.svg ADDED Viewed

@@ -0,0 +1 @@

+ <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" width="640" height="360" role="img" class="inkplot"><defs><clipPath id="plot-clip"><rect x="42" y="40" width="460" height="286"/></clipPath></defs><rect x="0" y="0" width="640" height="360" fill="#FFFFFF"/><path class="grid-line" d="M 42 326 L 502 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="330" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">0</text><path class="grid-line" d="M 42 230.67 L 502 230.67" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="234.67" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">20</text><path class="grid-line" d="M 42 135.33 L 502 135.33" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="139.33" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">40</text><path class="grid-line" d="M 99.5 40 L 99.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="99.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Jan</text><path class="grid-line" d="M 214.5 40 L 214.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="214.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Feb</text><path class="grid-line" d="M 329.5 40 L 329.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="329.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Mar</text><path class="grid-line" d="M 444.5 40 L 444.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="444.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Apr</text><path class="axis-line" d="M 42 40 L 42 326 L 502 326" fill="none" stroke="#626B78" stroke-width="1"/><text x="320" y="22" fill="#20242B" text-anchor="middle" font-size="15" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Sales and conversion</text><path class="mark-line" d="M 390 54 L 406 54" fill="none" stroke="#0072B2" stroke-width="2"/><text x="412" y="58" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Orders</text><path class="mark-line" d="M 390 72 L 406 72" fill="none" stroke="red" stroke-width="2"/><text x="412" y="76" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Conversion %</text><g class="series-marks" clip-path="url(#plot-clip)"><g class="series series-0" data-series="0"><rect class="bar-mark" x="52.35" y="211.6" width="93.3" height="114.4" fill="#0072B2"/><rect class="bar-mark" x="167.35" y="183" width="93.3" height="143" fill="#0072B2"/><rect class="bar-mark" x="282.35" y="197.3" width="93.3" height="128.7" fill="#0072B2"/><rect class="bar-mark" x="397.35" y="125.8" width="93.3" height="200.2" fill="#0072B2"/></g><g class="series series-1" data-series="1"><path class="mark-line" d="M 99.5 312.65 L 214.5 311.22 L 329.5 311.7 L 444.5 307.89" fill="none" stroke="red" stroke-width="2"/></g></g></svg>

data/examples/gallery/19-legend-position.svg ADDED Viewed

@@ -0,0 +1 @@

+ <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 380" width="640" height="380" role="img" class="inkplot"><defs><clipPath id="plot-clip"><rect x="42" y="40" width="580" height="306"/></clipPath></defs><rect x="0" y="0" width="640" height="380" fill="#FFFFFF"/><path class="grid-line" d="M 42 346 L 622 346" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="350" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">2</text><path class="grid-line" d="M 42 244 L 622 244" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="248" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">4</text><path class="grid-line" d="M 42 142 L 622 142" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="146" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">6</text><text x="42" y="364" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">1</text><text x="187" y="364" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">2</text><text x="332" y="364" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">3</text><text x="477" y="364" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">4</text><text x="622" y="364" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">5</text><path class="axis-line" d="M 42 40 L 42 346 L 622 346" fill="none" stroke="#626B78" stroke-width="1"/><text x="320" y="22" fill="#20242B" text-anchor="middle" font-size="15" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Legend below</text><path class="mark-line" d="M 50 306 L 66 306" fill="none" stroke="#0072B2" stroke-width="2"/><text x="72" y="310" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Actual</text><path class="mark-line" d="M 50 324 L 66 324" fill="none" stroke="#E69F00" stroke-width="2"/><text x="72" y="328" fill="#20242B" text-anchor="start" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Plan</text><g class="series-marks" clip-path="url(#plot-clip)"><g class="series series-0" data-series="0"><path class="mark-line" d="M 42 295 L 187 193 L 332 244 L 477 91 L 622 142" fill="none" stroke="#0072B2" stroke-width="2"/></g><g class="series series-1" data-series="1"><path class="mark-line" d="M 42 346 L 187 295 L 332 244 L 477 193 L 622 142" fill="none" stroke="#E69F00" stroke-width="2"/></g></g></svg>

data/examples/gallery/20-long-categories.svg ADDED Viewed

@@ -0,0 +1 @@

+ <?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" width="640" height="360" role="img" class="inkplot"><defs><clipPath id="plot-clip"><rect x="42" y="40" width="580" height="286"/></clipPath></defs><rect x="0" y="0" width="640" height="360" fill="#FFFFFF"/><path class="grid-line" d="M 42 326 L 622 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="330" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">0</text><path class="grid-line" d="M 42 254.5 L 622 254.5" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="258.5" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">10</text><path class="grid-line" d="M 42 183 L 622 183" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="187" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">20</text><path class="grid-line" d="M 42 111.5 L 622 111.5" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="34" y="115.5" fill="#626B78" text-anchor="end" font-size="11" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">30</text><path class="grid-line" d="M 114.5 40 L 114.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="114.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">North America</text><path class="grid-line" d="M 259.5 40 L 259.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="259.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">South America</text><path class="grid-line" d="M 404.5 40 L 404.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="404.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Europe</text><path class="grid-line" d="M 549.5 40 L 549.5 326" fill="none" stroke="#E7EAF0" stroke-width="1"/><text x="549.5" y="344" fill="#626B78" text-anchor="middle" font-size="10" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Asia Pacific</text><path class="axis-line" d="M 42 40 L 42 326 L 622 326" fill="none" stroke="#626B78" stroke-width="1"/><text x="320" y="22" fill="#20242B" text-anchor="middle" font-size="15" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif, 'Noto Sans CJK JP'">Labels rotate when needed</text><g class="series-marks" clip-path="url(#plot-clip)"><g class="series series-0" data-series="0"><rect class="bar-mark" x="55.05" y="168.7" width="117.9" height="157.3" fill="#0072B2"/><rect class="bar-mark" x="200.05" y="225.9" width="117.9" height="100.1" fill="#0072B2"/><rect class="bar-mark" x="345.05" y="104.35" width="117.9" height="221.65" fill="#0072B2"/><rect class="bar-mark" x="490.05" y="132.95" width="117.9" height="193.05" fill="#0072B2"/></g></g></svg>

data/examples/gallery/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Inkplot gallery
-Generated by [`../gallery.rb`](../gallery.rb). Run `ruby examples/gallery.rb` from the repository root to refresh the SVG previews.
+Generated by [`../gallery.rb`](../gallery.rb). Run `ruby examples/gallery.rb` from the repository root to refresh the SVG files.
 | Example | Preview | Example | Preview |
 |---|---|---|---|
@@ -8,4 +8,9 @@ Generated by [`../gallery.rb`](../gallery.rb). Run `ruby examples/gallery.rb` fr
 | Series | ![Multiple series](03-series.svg) | Scatter | ![Scatter plot](04-scatter.svg) |
 | Bars | ![Bars](05-bars.svg) | Horizontal bars | ![Horizontal bars](06-horizontal-bars.svg) |
 | Grouped bars | ![Grouped bars](07-grouped-bars.svg) | Stacked bars | ![Stacked bars](08-stacked-bars.svg) |
-| Area | ![Area chart](10-area.svg) | Step | ![Step chart](11-step.svg) |
+| Signed stacks | ![Signed stacks](09-signed-stack.svg) | Area | ![Area chart](10-area.svg) |
+| Step | ![Step chart](11-step.svg) | Histogram | ![Histogram](12-histogram.svg) |
+| Log scale | ![Log scale](13-log-scale.svg) | Time scale | ![Time scale](14-time-axis.svg) |
+| Category order | ![Ordered categories](15-category-order.svg) | Dark theme | ![Dark chart](16-dark-theme.svg) |
+| Annotations | ![Chart annotations](17-annotations.svg) | Mixed marks | ![Mixed chart](18-combo.svg) |
+| Legend position | ![Legend placement](19-legend-position.svg) | Long labels | ![Rotated labels](20-long-categories.svg) |

data/examples/gallery.rb CHANGED Viewed

@@ -31,19 +31,69 @@ module InkplotGallery
         p.bar(%w[Mon Tue Wed Thu Fri], [12, 16, 11, 19, 22], label: "Direct", stacked: true)
         p.bar(%w[Mon Tue Wed Thu Fri], [8, 9, 13, 10, 14], label: "Search", stacked: true)
       end],
+      ["09-signed-stack", Inkplot.plot(title: "Daily net change") do |p|
+        p.bar(%w[Mon Tue Wed Thu Fri], [8, -4, 5, -2, 9], label: "New", stacked: true)
+        p.bar(%w[Mon Tue Wed Thu Fri], [3, -6, 2, -5, 4], label: "Removed", stacked: true)
+      end],
       ["10-area", Inkplot.plot(title: "Build time over a release") { |p| p.area((1..8).to_a, [25, 29, 27, 38, 36, 44, 40, 51], label: "Seconds") }],
-      ["11-step", Inkplot.plot(title: "Queue depth") { |p| p.step((0..7).to_a, [3, 3, 5, 5, 4, 8, 8, 2], label: "Jobs") }]
+      ["11-step", Inkplot.plot(title: "Queue depth") { |p| p.step((0..7).to_a, [3, 3, 5, 5, 4, 8, 8, 2], label: "Jobs") }],
+      ["12-histogram", Inkplot.histogram([8, 9, 10, 10, 11, 12, 12, 13, 14, 15, 17, 18, 22, 25, 31, 33], bins: :auto, title: "Response time", x_label: "Milliseconds")],
+      ["13-log-scale", Inkplot.plot(title: "Growth on a log scale") do |p|
+        p.y_axis(scale: :log, min: 1)
+        p.line((0..5).to_a, [1, 3, 9, 27, 81, 243])
+      end],
+      ["14-time-axis", Inkplot.plot(title: "Hourly requests") do |p|
+        p.x_axis(label: "UTC", type: :time)
+        p.line((0..6).map do |hour|
+          Time.utc(2026, 9, 24, hour * 4)
+        end, [12, 17, 15, 24, 31, 27, 38])
+      end],
+      ["15-category-order", Inkplot.plot(title: "Deployment health") do |p|
+        p.x_axis(order: %w[dev staging production])
+        p.line(%w[production dev staging], [98, 100, 99], label: "Success %")
+      end],
+      ["16-dark-theme", Inkplot.plot(title: "Dark dashboard", theme: :dark) do |p|
+        p.line((1..7).to_a, [12, 18, 16, 24, 22, 30, 35], label: "Throughput")
+        p.hline(20, label: "Target", color: :orange)
+      end],
+      ["17-annotations", Inkplot.plot(title: "Service level objective") do |p|
+        p.line((1..7).to_a, [32, 28, 41, 36, 30, 24, 27])
+        p.hline(35, label: "SLO", color: :red)
+        p.vline(4, color: :blue)
+        p.text(4.1, 42, "deploy")
+      end],
+      ["18-combo", Inkplot.plot(title: "Sales and conversion") do |p|
+        p.bar(%w[Jan Feb Mar Apr], [24, 30, 27, 42], label: "Orders")
+        p.line(%w[Jan Feb Mar Apr], [2.8, 3.1, 3.0, 3.8], label: "Conversion %", color: :red)
+      end],
+      ["19-legend-position", Inkplot.plot(title: "Legend below", width: 640, height: 380) do |p|
+        p.line((1..5).to_a, [3, 5, 4, 7, 6], label: "Actual")
+        p.line((1..5).to_a, [2, 3, 4, 5, 6], label: "Plan")
+        p.legend(position: :bottom_left)
+      end],
+      ["20-long-categories", Inkplot.plot(title: "Labels rotate when needed") do |p|
+        p.x_axis(order: ["North America", "South America", "Europe", "Asia Pacific"])
+        p.bar(["North America", "South America", "Europe", "Asia Pacific"], [22, 14, 31, 27])
+      end]
     ]
   end
 end
 if $PROGRAM_NAME == __FILE__
-  raise ArgumentError, "usage: ruby examples/gallery.rb" unless ARGV.empty?
+  update_snapshots = ARGV.delete("--update-snapshots")
+  raise ArgumentError, "usage: ruby examples/gallery.rb [--update-snapshots]" unless ARGV.empty?
   svg_dir = File.expand_path("gallery", __dir__)
   FileUtils.mkdir_p(svg_dir)
   InkplotGallery.charts.each do |name, chart|
     File.write(File.join(svg_dir, "#{name}.svg"), chart.to_svg)
+    next unless update_snapshots
+    require "tessel"
+    require "glyphic"
+    png_dir = File.expand_path("../spec/snapshots", __dir__)
+    FileUtils.mkdir_p(png_dir)
+    File.binwrite(File.join(png_dir, "#{name}.png"), Tessel::PNG.encode(chart.to_image))
   end
 end

data/lib/inkplot/core.rb CHANGED Viewed

@@ -58,6 +58,13 @@ module Inkplot
     rescue NoMethodError
       nil
     end
+    def time(value)
+      case value
+      when Time then value
+      when Date then value.to_time
+      end
+    end
   end
   module Ticks
@@ -104,6 +111,41 @@ module Inkplot
       end
     end
+    def time(minimum, maximum, offset: 0)
+      span = maximum - minimum
+      intervals = [1, 5, 15, 30, 60, 300, 900, 1800, 3600, 10_800, 21_600, 43_200, 86_400, 604_800, 2_592_000, 7_776_000, 15_552_000, 31_536_000]
+      step = intervals.find { |value| span / value <= 6 } || 31_536_000
+      ticks = if step < 2_592_000
+                first = (minimum / step).ceil * step
+                (0..10).map { |index| first + (index * step) }.take_while { |value| value <= maximum }
+              elsif step < 31_536_000
+                time = Time.at(minimum).getlocal(offset)
+                month = time.month
+                month += 1 while Time.new(time.year, month, 1, 0, 0, 0, offset).to_f < minimum
+                month_ticks = Array.new(8) do |index|
+                  absolute = (time.year * 12) + month - 1 + (index * (step / 2_592_000).round)
+                  Time.new(absolute / 12, (absolute % 12) + 1, 1, 0, 0, 0, offset).to_f
+                end
+                month_ticks.take_while { |value| value <= maximum }
+              else
+                time = Time.at(minimum).getlocal(offset)
+                year = time.year
+                year += 1 while Time.new(year, 1, 1, 0, 0, 0, offset).to_f < minimum
+                Array.new(8) { |index| Time.new(year + (index * (step / 31_536_000).round), 1, 1, 0, 0, 0, offset).to_f }.take_while { |value| value <= maximum }
+              end
+      ticks.empty? ? [minimum, maximum].uniq : ticks
+    end
+    def time_label(value, span, offset: 0)
+      time = Time.at(value).getlocal(offset)
+      return time.strftime("%Y") if span >= 31_536_000
+      return time.strftime("%Y-%m") if span >= 2_592_000
+      return time.strftime("%Y-%m-%d") if span >= 86_400
+      return time.strftime("%H:%M") if span >= 60
+      time.strftime("%H:%M:%S")
+    end
     def number_label(value)
       value.to_i == value ? value.to_i.to_s : format("%.8f", value).sub(/0+\z/, "").sub(/\.\z/, "")
     end
@@ -223,6 +265,51 @@ module Inkplot
       def bandwidth = (@range[1] - @range[0]) / [@domain.length, 1].max
       def format(value) = value.to_s
     end
+    class TimeScale
+      attr_reader :domain, :ticks, :offset
+      attr_accessor :range
+      def initialize(values, options = {})
+        times = values.filter_map { |value| Data.time(value) }
+        offsets = times.map(&:utc_offset).uniq
+        raise ArgumentError, "time axis contains mixed UTC offsets" if offsets.length > 1
+        @offset = offsets.first || 0
+        numbers = times.map(&:to_f)
+        low, high = numbers.minmax
+        low ||= 0.0
+        high ||= low + 86_400
+        low = time_limit(options[:min], low, "minimum")
+        high = time_limit(options[:max], high, "maximum")
+        raise ArgumentError, "time axis minimum must be less than maximum" unless low < high
+        @ticks = Ticks.time(low, high, offset: @offset)
+        @domain = [low, high]
+      end
+      def map(value)
+        time = value.is_a?(Numeric) ? value.to_f : Data.time(value)&.to_f
+        return nil unless time
+        raise ArgumentError, "time axis contains mixed UTC offsets" if !value.is_a?(Numeric) && Data.time(value).utc_offset != @offset
+        @range[0] + ((time - @domain[0]) * (@range[1] - @range[0]) / (@domain[1] - @domain[0]))
+      end
+      def format(value) = Ticks.time_label(value, @domain[1] - @domain[0], offset: @offset)
+      private
+      def time_limit(value, fallback, name)
+        return fallback if value.nil?
+        time = Data.time(value)
+        raise ArgumentError, "time axis #{name} must be a Time or Date" unless time
+        raise ArgumentError, "time axis contains mixed UTC offsets" unless time.utc_offset == @offset
+        time.to_f
+      end
+    end
   end
   module TextMetrics
@@ -247,7 +334,7 @@ module Inkplot
       Glyphic.default
     rescue LoadError => e
-      raise LoadError, "font metrics need glyphic; install it with `gem install glyphic` (#{e.message})"
+      raise LoadError, "PNG output needs glyphic; install it with `gem install glyphic` (#{e.message})"
     end
   end
@@ -340,6 +427,21 @@ module Inkplot
       add(:bar, points, label:, color:, horizontal:, stacked:, **)
     end
+    def histogram(values, bins: :auto, label: nil, color: nil, **)
+      numbers = Array(values).filter_map { |value| Data.number(value) }
+      raise ArgumentError, "histogram needs at least one numeric value" if numbers.empty?
+      numbers.sort!
+      edges = histogram_edges(numbers, bins)
+      counts = Array.new(edges.length - 1, 0)
+      numbers.each do |number|
+        index = edges.each_cons(2).find_index { |left, right| number >= left && (number < right || right == edges.last) }
+        counts[index] += 1 if index
+      end
+      points = counts.each_index.map { |index| { x: edges[index], x2: edges[index + 1], y: counts[index] } }
+      add(:bar, points, label:, color:, histogram: true, **)
+    end
     def hline(value, label: nil, color: nil, dash: true)
       number = Data.number(value)
       raise ArgumentError, "horizontal rule value must be finite and numeric" unless number
@@ -351,6 +453,10 @@ module Inkplot
       @notes << { type: :vline, value:, label:, color: Theme.validate_color(color), dash: }
     end
+    def text(x, y, value, color: nil)
+      @notes << { type: :text, x:, y: Data.number(y), value: value.to_s, color: Theme.validate_color(color) }
+    end
     def add(type, points, label: nil, color: nil, **options)
       raise ArgumentError, "unsupported chart mark: #{type}" unless %i[line scatter bar area step].include?(type.to_sym)
       raise ArgumentError, "gaps must be :break or :connect" if options[:gaps] && !%i[break connect].include?(options[:gaps])
@@ -358,6 +464,28 @@ module Inkplot
       @series << Series.new(type: type.to_sym, points:, label: label&.to_s, color: Theme.validate_color(color), options:)
       self
     end
+    private
+    def histogram_edges(numbers, bins)
+      low, high = numbers.minmax
+      return [low - 0.5, high + 0.5] if low == high
+      if bins == :auto
+        q1 = numbers[(numbers.length * 0.25).floor]
+        q3 = numbers[(numbers.length * 0.75).floor]
+        width = 2 * (q3 - q1) / (numbers.length**(1.0 / 3))
+        count = width.positive? ? ((high - low) / width).ceil : (1 + Math.log2(numbers.length)).ceil
+        count = count.clamp(1, 512)
+        Array.new(count + 1) { |index| low + ((high - low) * index / count.to_f) }
+      elsif bins.is_a?(Integer) && bins.positive?
+        Array.new(bins + 1) { |index| low + ((high - low) * index / bins.to_f) }
+      elsif bins.is_a?(Array) && bins.length >= 2 && bins.all? { |value| Data.number(value) } && bins.each_cons(2).all? { |left, right| left < right }
+        bins.map(&:to_f)
+      else
+        raise ArgumentError, "bins must be :auto, a positive integer, or increasing edges"
+      end
+    end
   end
   class Chart
@@ -374,14 +502,34 @@ module Inkplot
       Renderers::SVG.render(SceneBuilder.call(self, width: width, height: height))
     end
-    def save(path, width: self.width, height: self.height)
+    def to_image(scale: 1)
+      require_relative "renderers/raster"
+      Renderers::Raster.render(SceneBuilder.call(self, width: width, height: height), scale: scale)
+    end
+    def to_png(width: self.width, height: self.height, scale: 1)
+      begin
+        require "tessel"
+      rescue LoadError => e
+        raise LoadError, "PNG output needs tessel; install it with `gem install tessel` (#{e.message})"
+      end
+      require_relative "renderers/raster"
+      Tessel::PNG.encode(Renderers::Raster.render(SceneBuilder.call(self, width:, height:), scale: scale))
+    end
+    def save(path, width: self.width, height: self.height, scale: 1)
       case File.extname(String(path)).downcase
       when ".svg" then File.write(path, to_svg(width:, height:))
-      else raise ArgumentError, "output path must end in .svg"
+      when ".png" then File.binwrite(path, to_png(width:, height:, scale:))
+      else raise ArgumentError, "output path must end in .svg or .png"
       end
       path
     end
+    def to_inlay
+      { svg: to_svg, png: -> { to_png } }
+    end
     private
     def series = builder.series
@@ -421,6 +569,14 @@ module Inkplot
       y_ticks = ticks(y_scale)
       left = (y_ticks.map { |tick| TextMetrics.width(y_scale.format(tick), 11) }.max.to_f.ceil + 14).clamp(42, 120)
       bottom = 34
+      rotate = x_scale.is_a?(Scales::Band) && x_ticks.any? && x_ticks.map { |tick| TextMetrics.width(x_scale.format(tick), 10) }.max > (width - left - 20) / x_ticks.length
+      if rotate
+        visible_count = [(width - left - 20) / 72, 1].max
+        stride = (x_ticks.length.to_f / visible_count).ceil
+        last_index = x_ticks.length - 1
+        x_ticks = x_ticks.each_with_index.filter_map { |tick, index| tick if (index % stride).zero? || index == last_index }
+      end
+      bottom += rotate ? 43 : 0
       bottom += 20 if builder.x_label_text
       left += 18 if builder.y_label_text
       top = builder.title_text ? 40 : 18
@@ -447,7 +603,7 @@ module Inkplot
         label = x_scale.format(tick)
         elements << { type: :line, class: "grid-line", points: [[x, top], [x, height - bottom]], stroke: colors[:grid], width: 1 } if x_scale.is_a?(Scales::Band)
-        elements << { type: :text, x:, y: height - bottom + 18, text: label, fill: colors[:axis], anchor: :middle, size: 10 }
+        elements << { type: :text, x:, y: height - bottom + (rotate ? 14 : 18), text: label, fill: colors[:axis], anchor: :middle, size: 10, rotate: (rotate ? -45 : nil) }
       end
       elements << { type: :line, class: "axis-line", points: [[left, top], [left, height - bottom], [width - right, height - bottom]], stroke: colors[:axis], width: 1 }
       elements << { type: :text, x: width / 2.0, y: 22, text: builder.title_text, fill: colors[:foreground], anchor: :middle, size: 15 } if builder.title_text
@@ -467,11 +623,11 @@ module Inkplot
         if item.type == :bar
           current_bar_index = bar_index
           bar_index += 1
-          total = [bars.length, 1].max
           points.each do |point|
             next unless point[:y] && point[:x]
             if item.options[:horizontal]
+              total = [bars.length, 1].max
               band = y_scale.bandwidth * 0.72
               value = point[:y]
               base = if item.options[:stacked]
@@ -491,7 +647,15 @@ module Inkplot
               offset = item.options[:stacked] ? 0 : (current_bar_index - ((total - 1) / 2.0)) * band
               marks << { type: :rect, class: "bar-mark", series_index: index, x: [value, zero].min, y: category_y - (band / 2) + offset, width: (value - zero).abs, height: band,
                          fill: color }
+            elsif item.options[:histogram]
+              left_edge = x_scale.map(point[:x])
+              right_edge = x_scale.map(point[:x2])
+              zero = y_scale.map(0)
+              value = y_scale.map(point[:y])
+              marks << { type: :rect, class: "bar-mark", series_index: index, x: left_edge, y: [zero, value].min, width: [right_edge - left_edge - 1, 1].max,
+                         height: (zero - value).abs, fill: color }
             else
+              total = [bars.length, 1].max
               band = x_scale.bandwidth * (item.options[:stacked] ? 0.78 : 0.82 / total)
               x = x_scale.map(point[:x])
               value = point[:y]
@@ -554,6 +718,10 @@ module Inkplot
         when :vline
           x = x_scale.map(note[:value])
           marks << { type: :line, class: "rule-line", points: [[x, top], [x, height - bottom]], stroke: color, width: 1.5, dash: note[:dash] } if x
+        when :text
+          x = x_scale.map(note[:x])
+          y = y_scale.map(note[:y])
+          marks << { type: :text, x:, y:, text: note[:value], fill: color, anchor: :start, size: 11 } if x && y
         end
       end
@@ -571,8 +739,10 @@ module Inkplot
     def build_scale(values, options, axis, series)
       explicit = options[:scale] || options[:type]
       horizontal_bar = series.any? { |item| item.type == :bar && item.options[:horizontal] }
-      bar_band = series.any? { |item| item.type == :bar && ((item.options[:horizontal] && axis == :y) || (!item.options[:horizontal] && axis == :x)) }
-      if explicit == :band || (explicit.nil? && (bar_band || values.any? { |value| !Data.number(value) }))
+      bar_band = series.any? { |item| item.type == :bar && !item.options[:histogram] && ((item.options[:horizontal] && axis == :y) || (!item.options[:horizontal] && axis == :x)) }
+      if explicit == :time || (explicit.nil? && values.any? { |value| Data.time(value) })
+        Scales::TimeScale.new(values, options)
+      elsif explicit == :band || (explicit.nil? && (bar_band || values.any? { |value| !Data.number(value) && !Data.time(value) }))
         Scales::Band.new(values, options)
       elsif explicit == :log
         warn "Inkplot ignores zero and negative values on a log axis." if values.any? { |value| (number = Data.number(value)) && !number.positive? }

data/lib/inkplot/renderers/raster.rb ADDED Viewed

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+module Inkplot
+  module Renderers
+    module Raster
+      module_function
+      def render(scene, scale: 1)
+        scale = Integer(scale)
+        raise ArgumentError, "scale must be a positive integer" unless scale.positive?
+        begin
+          require "tessel"
+        rescue LoadError => e
+          raise LoadError, "PNG output needs tessel; install it with `gem install tessel` (#{e.message})"
+        end
+        begin
+          require "glyphic"
+        rescue LoadError => e
+          raise LoadError, "PNG output needs glyphic; install it with `gem install glyphic` (#{e.message})"
+        end
+        factor = scale * 2 # ponytail: 2× coverage sampling; raise this if raster diffs show visible edge artifacts.
+        width = scene.width * scale
+        height = scene.height * scale
+        canvas = Tessel::Image.new(width * 2, height * 2, fill: color(scene.background))
+        scene.elements.each { |element| draw_shape(canvas, element, factor) }
+        clip = scene.clip.map { |value| value * factor }
+        seen = {}
+        scene.marks.each do |mark|
+          if mark[:type] == :circle
+            key = [mark[:series_index], (mark[:cx] * scale).round, (mark[:cy] * scale).round]
+            next if seen[key]
+            seen[key] = true
+          end
+          draw_shape(canvas, mark, factor, clip: clip)
+        end
+        image = downsample(canvas, width, height)
+        draw_labels(image, scene.elements + scene.marks.select { |mark| mark[:type] == :text }, scale)
+        image
+      end
+      def draw_shape(image, shape, factor, clip: nil)
+        case shape[:type]
+        when :rect
+          rectangle(image, shape, factor, clip)
+        when :line
+          Stroker.stroke(image, shape[:points], color(shape[:stroke]), factor, (shape[:width] || 1) * factor, dash: shape[:dash], clip: clip)
+        when :polygon
+          rgba = color(shape[:fill])
+          rgba[3] = (rgba[3] * (shape[:opacity] || 1)).round
+          PathFiller.fill(image, shape[:points].map { |x, y| [x * factor, y * factor] }, rgba, clip: clip)
+        when :circle
+          cx, cy, radius = shape.values_at(:cx, :cy, :r).map { |value| value * factor }
+          Circle.fill(image, cx, cy, radius, color(shape[:fill]), clip: clip)
+          Circle.stroke(image, cx, cy, radius, color(shape[:stroke]), [shape[:stroke_width].to_f * factor, 1].max, clip: clip) if shape[:stroke]
+        end
+      end
+      private_class_method :draw_shape
+      def rectangle(image, shape, factor, clip)
+        x, y, width, height = shape.values_at(:x, :y, :width, :height).map { |value| (value * factor).round }
+        x0 = x
+        y0 = y
+        x1 = x + width
+        y1 = y + height
+        if clip
+          x0 = [x0, clip[0].floor].max
+          y0 = [y0, clip[1].floor].max
+          x1 = [x1, clip[2].ceil].min
+          y1 = [y1, clip[3].ceil].min
+        end
+        image.fill_rect(x0, y0, [x1 - x0, 0].max, [y1 - y0, 0].max, color(shape[:fill]), blend: :alpha)
+      end
+      private_class_method :rectangle
+      def color(value)
+        named = {
+          "red" => [220, 40, 40], "blue" => [30, 90, 210], "green" => [0, 140, 80], "black" => [0, 0, 0], "white" => [255, 255, 255],
+          "orange" => [230, 145, 0], "gray" => [128, 128, 128], "grey" => [128, 128, 128], "purple" => [128, 0, 128], "yellow" => [255, 255, 0],
+          "cyan" => [0, 255, 255], "aqua" => [0, 255, 255], "magenta" => [255, 0, 255], "fuchsia" => [255, 0, 255], "pink" => [255, 192, 203],
+          "brown" => [165, 42, 42], "navy" => [0, 0, 128], "teal" => [0, 128, 128], "lime" => [0, 255, 0], "maroon" => [128, 0, 0],
+          "olive" => [128, 128, 0], "silver" => [192, 192, 192], "rebeccapurple" => [102, 51, 153], "transparent" => [0, 0, 0, 0]
+        }
+        return named.fetch(value.to_s.downcase) { [32, 36, 43] }.then { |channels| channels.length == 3 ? channels + [255] : channels } unless value.to_s.start_with?("#")
+        hex = value.delete_prefix("#")
+        hex = hex.chars.map { |digit| digit * 2 }.join if [3, 4].include?(hex.length)
+        channels = hex.scan(/../).map { |channel| channel.to_i(16) }
+        channels << 255 if channels.length == 3
+        channels
+      end
+      private_class_method :color
+      def downsample(source, width, height)
+        input = source.bytes
+        output = String.new(capacity: width * height * 4, encoding: Encoding::BINARY)
+        height.times do |y|
+          width.times do |x|
+            4.times do |channel|
+              total = 0
+              2.times do |dy|
+                2.times do |dx|
+                  total += input.getbyte((((((y * 2) + dy) * source.width) + (x * 2) + dx) * 4) + channel)
+                end
+              end
+              output << (total / 4).round
+            end
+          end
+        end
+        Tessel::Image.from_rgba(width, height, output)
+      end
+      private_class_method :downsample
+      def draw_labels(image, elements, scale)
+        font = TextMetrics.font_for(12 * scale)
+        bitmap = Inkplot.config.font.nil?
+        warned = false
+        elements.each do |element|
+          next unless element[:type] == :text
+          text = element[:text].to_s
+          if bitmap && !text.ascii_only? && !warned
+            warn "Inkplot's built-in bitmap font is ASCII-only; set Inkplot.config.font to a TrueType font for Unicode labels."
+            warned = true
+          end
+          label = text.encode("ASCII", invalid: :replace, undef: :replace, replace: "?") if bitmap
+          label ||= text
+          draw_text(image, font, label, element, scale)
+        end
+      end
+      private_class_method :draw_labels
+      def draw_text(image, font, text, element, scale)
+        fill = color(element[:fill])
+        anchor_x = (element[:x] * scale).round
+        baseline_y = (element[:y] * scale).round
+        glyph = font.render(text, color: fill)
+        bitmap = Inkplot.config.font.nil?
+        glyph = glyph.scale_nearest(glyph.width * scale, glyph.height * scale) if bitmap && scale > 1
+        ascent = font.ascent * (bitmap ? scale : 1)
+        pivot_x = case element[:anchor]
+                  when :middle then glyph.width / 2.0
+                  when :end then glyph.width.to_f
+                  else 0.0
+                  end
+        if element[:rotate]
+          pivot_y = ascent.to_f
+          radians = element[:rotate] * Math::PI / 180
+          source = glyph.bytes
+          glyph.height.times do |gy|
+            glyph.width.times do |gx|
+              offset = ((gy * glyph.width) + gx) * 4
+              alpha = source.getbyte(offset + 3)
+              next if alpha.zero?
+              dx = gx - pivot_x
+              dy = gy - pivot_y
+              px = (anchor_x + (dx * Math.cos(radians)) - (dy * Math.sin(radians))).round
+              py = (baseline_y + (dx * Math.sin(radians)) + (dy * Math.cos(radians))).round
+              blend_pixel(image, px, py, [fill[0], fill[1], fill[2], alpha])
+            end
+          end
+        else
+          image.blit(glyph, anchor_x - pivot_x.round, baseline_y - ascent, blend: :alpha)
+        end
+      end
+      private_class_method :draw_text
+      def blend_pixel(image, x, y, rgba)
+        return unless x.between?(0, image.width - 1) && y.between?(0, image.height - 1)
+        image.fill_rect(x, y, 1, 1, rgba, blend: :alpha)
+      end
+      private_class_method :blend_pixel
+      module PathFiller
+        module_function
+        def fill(image, points, rgba, clip: nil)
+          return if points.length < 3
+          low = [points.map { |point| point[1] }.min.floor, clip ? clip[1].floor : 0, 0].max
+          high = [points.map { |point| point[1] }.max.ceil, clip ? clip[3].ceil : image.height, image.height].min
+          (low...high).each do |y|
+            scan = y + 0.5
+            crossings = points.each_with_index.filter_map do |point, index|
+              next_point = points[(index + 1) % points.length]
+              x1, y1 = point
+              x2, y2 = next_point
+              next if (y1 <= scan && y2 <= scan) || (y1 > scan && y2 > scan)
+              [(x1 + ((scan - y1) * (x2 - x1) / (y2 - y1))), y2 > y1 ? 1 : -1]
+            end.sort_by(&:first)
+            winding = 0
+            previous_x = nil
+            crossings.each do |crossing_x, direction|
+              fill_span(image, previous_x, crossing_x, y, rgba, clip) if winding != 0 && previous_x
+              winding += direction
+              previous_x = crossing_x
+            end
+          end
+        end
+        def fill_span(image, x1, x2, y, rgba, clip)
+          left, right = [x1, x2].minmax
+          left = [left.ceil, clip ? clip[0].ceil : 0].max
+          right = [right.floor, clip ? clip[2].floor : image.width].min
+          (left...right).each { |x| image[x, y] = rgba if rgba[3] == 255 }
+          return if rgba[3] == 255
+          (left...right).each { |x| image.fill_rect(x, y, 1, 1, rgba, blend: :alpha) }
+        end
+        private_class_method :fill_span
+      end
+      module Stroker
+        module_function
+        def stroke(image, points, rgba, factor, width, dash: false, clip: nil)
+          return if points.length < 2
+          return stroke_dashed(image, points, rgba, factor, width, clip) if dash
+          scaled_points = points.map { |x, y| [(x * factor).round, (y * factor).round] }
+          scaled_points.each_cons(2) do |(x0, y0), (x1, y1)|
+            dx = x1 - x0
+            dy = y1 - y0
+            length = Math.hypot(dx, dy)
+            next if length.zero?
+            offset_x = -dy * width / (2 * length)
+            offset_y = dx * width / (2 * length)
+            polygon = [[x0 + offset_x, y0 + offset_y], [x1 + offset_x, y1 + offset_y], [x1 - offset_x, y1 - offset_y], [x0 - offset_x, y0 - offset_y]]
+            PathFiller.fill(image, polygon, rgba, clip: clip)
+          end
+          scaled_points.each { |x, y| Circle.fill(image, x, y, width / 2.0, rgba, clip: clip) }
+        end
+        def stroke_dashed(image, points, rgba, factor, width, clip)
+          dash_length = [width.round * 3, 6].max
+          distance = 0
+          points.each_cons(2) do |start_point, end_point|
+            x0, y0 = start_point.map { |value| (value * factor).round }
+            x1, y1 = end_point.map { |value| (value * factor).round }
+            dx = (x1 - x0).abs
+            dy = -(y1 - y0).abs
+            sx = x0 < x1 ? 1 : -1
+            sy = y0 < y1 ? 1 : -1
+            error = dx + dy
+            loop do
+              draw_brush(image, x0, y0, width, rgba, clip) unless (distance / dash_length).odd?
+              break if x0 == x1 && y0 == y1
+              twice = 2 * error
+              if twice >= dy
+                error += dy
+                x0 += sx
+              end
+              if twice <= dx
+                error += dx
+                y0 += sy
+              end
+              distance += 1
+            end
+          end
+        end
+        def draw_brush(image, x, y, width, rgba, clip)
+          radius = [width / 2.0, 0.5].max
+          (y - radius).floor.upto((y + radius).ceil) do |py|
+            (x - radius).floor.upto((x + radius).ceil) do |px|
+              next if ((px - x)**2) + ((py - y)**2) > radius**2
+              next unless px.between?(0, image.width - 1) && py.between?(0, image.height - 1)
+              next if clip && (px < clip[0] || px > clip[2] || py < clip[1] || py > clip[3])
+              image.fill_rect(px, py, 1, 1, rgba, blend: :alpha)
+            end
+          end
+        end
+        private_class_method :draw_brush
+      end
+      module Circle
+        module_function
+        def fill(image, cx, cy, radius, rgba, clip: nil)
+          low_y = [(cy - radius).floor, clip ? clip[1].floor : 0, 0].max
+          high_y = [(cy + radius).ceil, clip ? clip[3].ceil : image.height - 1, image.height - 1].min
+          (low_y..high_y).each do |y|
+            span = Math.sqrt([(radius**2) - ((y - cy)**2), 0].max)
+            left = [(cx - span).floor, clip ? clip[0].floor : 0, 0].max
+            right = [(cx + span).ceil, clip ? clip[2].ceil : image.width - 1, image.width - 1].min
+            image.fill_rect(left, y, right - left + 1, 1, rgba, blend: :alpha) if left <= right
+          end
+        end
+        def stroke(image, cx, cy, radius, rgba, width, clip: nil)
+          outer = radius + (width / 2.0)
+          inner = [radius - (width / 2.0), 0].max
+          low_y = [(cy - outer).floor, clip ? clip[1].floor : 0, 0].max
+          high_y = [(cy + outer).ceil, clip ? clip[3].ceil : image.height - 1, image.height - 1].min
+          (low_y..high_y).each do |y|
+            dy = y - cy
+            outer_span = Math.sqrt([(outer**2) - (dy**2), 0].max)
+            outer_left = [(cx - outer_span).floor, clip ? clip[0].floor : 0, 0].max
+            outer_right = [(cx + outer_span).ceil, clip ? clip[2].ceil : image.width - 1, image.width - 1].min
+            inner_span = inner.zero? || dy.abs >= inner ? 0 : Math.sqrt((inner**2) - (dy**2))
+            inner_left = (cx - inner_span).ceil
+            inner_right = (cx + inner_span).floor
+            left_width = [inner_left - outer_left, outer_right - outer_left + 1].min
+            image.fill_rect(outer_left, y, left_width, 1, rgba, blend: :alpha) if left_width.positive?
+            right_start = [inner_right + 1, outer_left].max
+            right_width = outer_right - right_start + 1
+            image.fill_rect(right_start, y, right_width, 1, rgba, blend: :alpha) if right_width.positive?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inkplot/version.rb CHANGED Viewed

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

data/lib/inkplot.rb CHANGED Viewed

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
+require "date"
 require_relative "inkplot/version"
 require_relative "inkplot/core"
 require_relative "inkplot/renderers/svg"
@@ -42,6 +43,13 @@ module Inkplot
       Chart.new(builder)
     end
+    def histogram(values, bins: :auto, x_label: nil, y_label: "Count", title: nil, **options)
+      chart_options, mark_options = options.partition { |key, _| %i[width height theme].include?(key) }.map(&:to_h)
+      builder = Builder.new(**chart_options, title:, x_label:, y_label:)
+      builder.histogram(values, bins:, **mark_options)
+      Chart.new(builder)
+    end
     def sparkline(values)
       values = values.filter_map { |value| Data.number(value) }
       return "" if values.empty?

data/sig/inkplot.rbs CHANGED Viewed

@@ -15,8 +15,10 @@ module Inkplot
     def area: (untyped x, ?untyped y, ?label: String?, ?color: String?, **untyped options) -> Builder
     def step: (untyped x, ?untyped y, ?label: String?, ?color: String?, **untyped options) -> Builder
     def bar: (untyped categories, ?untyped values, ?label: String?, ?color: String?, ?horizontal: bool, ?stacked: bool, **untyped options) -> Builder
+    def histogram: (untyped values, ?bins: untyped, ?label: String?, ?color: String?, **untyped options) -> Builder
     def hline: (Numeric value, ?label: String?, ?color: String?, ?dash: bool) -> Array[Hash[Symbol, untyped]]
     def vline: (untyped value, ?label: String?, ?color: String?, ?dash: bool) -> Array[Hash[Symbol, untyped]]
+    def text: (untyped x, Numeric y, String value, ?color: String?) -> Array[Hash[Symbol, untyped]]
   end
   class Chart
@@ -24,7 +26,10 @@ module Inkplot
     attr_reader width: Integer
     attr_reader height: Integer
     def to_svg: (?width: Integer, ?height: Integer) -> String
-    def save: (String | _Path path, ?width: Integer, ?height: Integer) -> String | _Path
+    def to_png: (?width: Integer, ?height: Integer, ?scale: Integer) -> String
+    def to_image: (?scale: Integer) -> untyped
+    def save: (String | _Path path, ?width: Integer, ?height: Integer, ?scale: Integer) -> String | _Path
+    def to_inlay: () -> Hash[Symbol, untyped]
   end
   def self.config: () -> Config
@@ -32,5 +37,6 @@ module Inkplot
   def self.line: (untyped data, ?untyped values, ?x: untyped, ?y: untyped, ?color: untyped, ?title: String?, ?x_label: String?, ?y_label: String?, **untyped options) -> Chart
   def self.scatter: (untyped data, ?untyped values, ?x: untyped, ?y: untyped, ?size: untyped, ?color: untyped, ?title: String?, ?x_label: String?, ?y_label: String?, **untyped options) -> Chart
   def self.bar: (untyped data, ?horizontal: bool, ?title: String?, ?x_label: String?, ?y_label: String?, **untyped options) -> Chart
+  def self.histogram: (untyped values, ?bins: untyped, ?x_label: String?, ?y_label: String?, ?title: String?, **untyped options) -> Chart
   def self.sparkline: (Array[untyped] values) -> String
 end

metadata CHANGED Viewed

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inkplot
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -65,7 +66,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Build line, bar, scatter, and other charts as standalone SVG.
+description: Build line, bar, scatter, and other charts as standalone SVG, with optional
+  PNG rendering.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -87,11 +89,22 @@ files:
 - examples/gallery/06-horizontal-bars.svg
 - examples/gallery/07-grouped-bars.svg
 - examples/gallery/08-stacked-bars.svg
+- examples/gallery/09-signed-stack.svg
 - examples/gallery/10-area.svg
 - examples/gallery/11-step.svg
+- examples/gallery/12-histogram.svg
+- examples/gallery/13-log-scale.svg
+- examples/gallery/14-time-axis.svg
+- examples/gallery/15-category-order.svg
+- examples/gallery/16-dark-theme.svg
+- examples/gallery/17-annotations.svg
+- examples/gallery/18-combo.svg
+- examples/gallery/19-legend-position.svg
+- examples/gallery/20-long-categories.svg
 - examples/gallery/README.md
 - lib/inkplot.rb
 - lib/inkplot/core.rb
+- lib/inkplot/renderers/raster.rb
 - lib/inkplot/renderers/svg.rb
 - lib/inkplot/version.rb
 - sig/inkplot.rbs
@@ -102,6 +115,7 @@ metadata:
   homepage_uri: https://github.com/rbgfx/inkplot
   source_code_uri: https://github.com/rbgfx/inkplot/tree/main
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -116,7 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
-summary: SVG charts for Ruby
+summary: Dependency-free SVG charts for Ruby
 test_files: []