Add polar

Author: kojix2

examples/polarplot.cr

@@ -0,0 +1,32 @@
+require "../src/unicode_plot"
+
+include UnicodePlot
+
+# Basic spiral-like polar line
+theta = (0...40).map { |i| 4.0 * Math::PI * i.to_f64 / 39.0 }
+r = theta.map { |angle| angle / (2.0 * Math::PI) }
+
+p1 = polarplot(theta, r, title: "Polar line", color: :green)
+puts p1
+puts
+
+# Polar scatter mode (lines: false)
+theta2 = (0...20).map { |i| 2.0 * Math::PI * i.to_f64 / 19.0 }
+r2 = (0...20).map { |i| 1.0 + 0.2 * Math.sin(i.to_f64) }
+
+p2 = polarplot(theta2, r2,
+  lines: false,
+  color: :red,
+  marker: :circle,
+  border: :solid,
+  title: "Polar scatter")
+puts p2
+puts
+
+# Explicit radial limit and callable radius
+theta3 = (0...50).map { |i| 3.0 * Math::PI * i.to_f64 / 49.0 }
+p3 = polarplot(theta3,
+  ->(angle : Float64) { 1.0 + 0.5 * Math.cos(3.0 * angle) },
+  rlim: {0.0, 2.0},
+  title: "Callable radius with rlim")
+puts p3

spec/fixtures/README.md

@@ -1,25 +1,47 @@
 # Fixtures for reference specs
 
-This directory contains generated fixture data used by Crystal specs.
+This directory contains Julia-generated fixture data consumed by Crystal specs.
+Fixtures are intended to be generated, not hand-edited.
 
-## Heatmap fixture
-
-- File: `julia_heatmap_data.json`
-- Generator: `generate_julia_heatmap_data.jl`
-- Purpose: keep heatmap input matrices identical to UnicodePlots.jl reference data.
-
-The heatmap fixture is intentionally generated by Julia (not hand-edited) so Crystal reference tests can compare output with the same numeric input.
-
-## Regenerate
+## Quick regenerate
 
 Run from repository root:
 
 ```bash
 julia spec/fixtures/generate_julia_heatmap_data.jl
+julia spec/fixtures/generate_julia_densityplot_data.jl
+julia spec/fixtures/generate_julia_spy_data.jl
+julia spec/fixtures/generate_julia_polarplot_data.jl
 ```
 
-This rewrites `julia_heatmap_data.json` with deterministic data using seed `1337`.
+## Heatmap
+
+- Data file: `julia_heatmap_data.json`
+- Generator: `generate_julia_heatmap_data.jl`
+- Purpose: keep heatmap input matrices aligned with UnicodePlots.jl reference inputs.
+- Notes: deterministic output (seed `1337`).
+- Consumer: `spec/reference_spec.cr`
+
+## Densityplot
+
+- Data file: `julia_densityplot_data.json`
+- Generator: `generate_julia_densityplot_data.jl`
+- Purpose: keep `x` and `y` samples aligned with UnicodePlots.jl densityplot tests.
+- Notes: deterministic output (seed `1337`).
+- Consumer: `spec/reference_spec.cr`
+
+## Spy
+
+- Data file: `julia_spy_data.json`
+- Generator: `generate_julia_spy_data.jl`
+- Purpose: keep sparse matrix fixtures aligned with UnicodePlots.jl spy tests.
+- Notes: generated from stable sparse sampling logic in Julia.
+- Consumer: `spec/reference_spec.cr`
 
-## Consumer
+## Polarplot
 
-- `spec/reference_spec.cr` loads this JSON and caches decoded matrices per key.
+- Data file: `julia_polarplot_data.json`
+- Generator: `generate_julia_polarplot_data.jl`
+- Purpose: keep polarplot input parameters aligned with UnicodePlots.jl tests.
+- Notes: stores deterministic linspace parameters (`start`, `stop`, `length`) for `theta` and `r`.
+- Consumer: `spec/reference_spec.cr`

spec/fixtures/generate_julia_polarplot_data.jl

@@ -0,0 +1,30 @@
+# Generates deterministic polarplot fixtures matching UnicodePlots.jl test inputs.
+# This stores linspace parameters so Crystal specs can reconstruct exact arrays.
+
+function write_json(path::String)
+    open(path, "w") do io
+        write(io, "{\n")
+        write(io, "  \"simple\": {\n")
+        write(io, "    \"theta\": {\"start\": 0.0, \"stop\": $(repr(2pi)), \"length\": 20},\n")
+        write(io, "    \"r\": {\"start\": 0.0, \"stop\": 2.0, \"length\": 20}\n")
+        write(io, "  },\n")
+        write(io, "  \"simple_with_rlim\": {\n")
+        write(io, "    \"theta\": {\"start\": 0.0, \"stop\": $(repr(2pi)), \"length\": 20},\n")
+        write(io, "    \"r\": {\"start\": 0.0, \"stop\": 2.0, \"length\": 20},\n")
+        write(io, "    \"rlim\": [0.0, 3.0]\n")
+        write(io, "  },\n")
+        write(io, "  \"callable\": {\n")
+        write(io, "    \"theta\": {\"start\": 0.0, \"stop\": $(repr(4pi)), \"length\": 40}\n")
+        write(io, "  },\n")
+        write(io, "  \"kwargs\": {\n")
+        write(io, "    \"theta\": {\"start\": 0.0, \"stop\": $(repr(2pi)), \"length\": 20},\n")
+        write(io, "    \"r\": {\"start\": 0.0, \"stop\": 1.0, \"length\": 20},\n")
+        write(io, "    \"size_scale\": 1.5\n")
+        write(io, "  }\n")
+        write(io, "}\n")
+    end
+end
+
+out = joinpath(@__DIR__, "julia_polarplot_data.json")
+write_json(out)
+println("Written: $out")

spec/fixtures/julia_polarplot_data.json

@@ -0,0 +1,19 @@
+{
+  "simple": {
+    "theta": {"start": 0.0, "stop": 6.283185307179586, "length": 20},
+    "r": {"start": 0.0, "stop": 2.0, "length": 20}
+  },
+  "simple_with_rlim": {
+    "theta": {"start": 0.0, "stop": 6.283185307179586, "length": 20},
+    "r": {"start": 0.0, "stop": 2.0, "length": 20},
+    "rlim": [0.0, 3.0]
+  },
+  "callable": {
+    "theta": {"start": 0.0, "stop": 12.566370614359172, "length": 40}
+  },
+  "kwargs": {
+    "theta": {"start": 0.0, "stop": 6.283185307179586, "length": 20},
+    "r": {"start": 0.0, "stop": 1.0, "length": 20},
+    "size_scale": 1.5
+  }
+}

spec/reference_spec.cr

@@ -16,6 +16,9 @@ DENSITYPLOT_Y            = DENSITYPLOT_FIXTURE_JSON["y"].as_a.map(&.as_f)
 SPY_FIXTURE_PATH = File.join(__DIR__, "fixtures", "julia_spy_data.json")
 SPY_FIXTURE_JSON = JSON.parse(File.read(SPY_FIXTURE_PATH))
 
+POLARPLOT_FIXTURE_PATH = File.join(__DIR__, "fixtures", "julia_polarplot_data.json")
+POLARPLOT_FIXTURE_JSON = JSON.parse(File.read(POLARPLOT_FIXTURE_PATH))
+
 # Returns a matrix fixture by key ("60x60", "10x10", "10x11").
 # The parsed matrix is cached because multiple examples reuse the same payload.
 def heatmap_fixture_matrix(key : String) : Array(Array(Float64))
@@ -74,6 +77,14 @@ def spy_flip_matrix : Array(Array(Float64))
   a
 end
 
+def polarplot_fixture_linspace(case_key : String, axis : String) : Array(Float64)
+  entry = POLARPLOT_FIXTURE_JSON[case_key][axis]
+  start_v = entry["start"].as_f
+  stop_v = entry["stop"].as_f
+  length = entry["length"].as_i
+  linspace(start_v, stop_v, length)
+end
+
 def linspace(start_v : Float64, end_v : Float64, length : Int32) : Array(Float64)
   return [] of Float64 if length <= 0
   return [start_v] if length == 1
@@ -1239,4 +1250,46 @@ describe "Julia reference output compatibility" do
       end
     end
   end
+
+  describe "polarplot" do
+    it "matches polarplot/simple" do
+      theta = polarplot_fixture_linspace("simple", "theta")
+      r = polarplot_fixture_linspace("simple", "r")
+      p = UnicodePlot.polarplot(theta, r)
+      test_ref("polarplot/simple.txt", p)
+    end
+
+    it "matches polarplot/simple_with_rlim" do
+      theta = polarplot_fixture_linspace("simple_with_rlim", "theta")
+      r = polarplot_fixture_linspace("simple_with_rlim", "r")
+      rlim_json = POLARPLOT_FIXTURE_JSON["simple_with_rlim"]["rlim"].as_a
+      rlim = {rlim_json[0].as_f, rlim_json[1].as_f}
+      p = UnicodePlot.polarplot(theta, r, rlim: rlim)
+      test_ref("polarplot/simple_with_rlim.txt", p)
+    end
+
+    it "matches polarplot/callable" do
+      theta = polarplot_fixture_linspace("callable", "theta")
+      p = UnicodePlot.polarplot(theta, ->(angle : Float64) { angle / (2.0 * Math::PI) })
+      test_ref("polarplot/callable.txt", p)
+    end
+
+    it "matches polarplot/kwargs" do
+      scale = POLARPLOT_FIXTURE_JSON["kwargs"]["size_scale"].as_f
+      h = (UnicodePlot.default_height * scale).round.to_i
+      w = (UnicodePlot.default_width * scale).round.to_i
+      theta = polarplot_fixture_linspace("kwargs", "theta")
+      r = polarplot_fixture_linspace("kwargs", "r")
+      p = UnicodePlot.polarplot(
+        theta,
+        r,
+        lines: false,
+        border: :solid,
+        color: :red,
+        height: h,
+        width: w,
+      )
+      test_ref("polarplot/kwargs.txt", p)
+    end
+  end
 end

spec/unicode_plot_spec.cr

@@ -476,6 +476,53 @@ describe UnicodePlot do
     end
   end
 
+  describe "polarplot" do
+    it "returns a Plot" do
+      theta = [0.0, Math::PI / 2.0, Math::PI]
+      r = [0.5, 1.0, 1.5]
+      p = UnicodePlot.polarplot(theta, r)
+      p.should be_a(UnicodePlot::Plot)
+    end
+
+    it "raises on mismatched theta/r lengths" do
+      expect_raises(ArgumentError, /same length/) do
+        UnicodePlot.polarplot([0.0, Math::PI], [1.0])
+      end
+    end
+
+    it "accepts numeric overloads" do
+      p = UnicodePlot.polarplot([0_i64, 1_i64, 2_i64], [1_i32, 2_i32, 3_i32])
+      p.to_s.should be_a(String)
+    end
+
+    it "accepts callable radius" do
+      theta = [0.0, Math::PI / 2.0, Math::PI]
+      p = UnicodePlot.polarplot(theta, ->(angle : Float64) { angle + 1.0 })
+      p.to_s.should be_a(String)
+    end
+
+    it "supports scatter mode with lines: false" do
+      theta = [0.0, Math::PI / 2.0, Math::PI, 3.0 * Math::PI / 2.0]
+      r = [1.0, 1.0, 1.0, 1.0]
+      p = UnicodePlot.polarplot(theta, r, lines: false)
+      p.to_s.should contain("0°")
+      p.to_s.should contain("90°")
+      p.to_s.should contain("180°")
+      p.to_s.should contain("270°")
+    end
+
+    it "uses 3π / 2 label when degrees is false" do
+      theta = [0.0, Math::PI / 2.0, Math::PI, 3.0 * Math::PI / 2.0]
+      r = [1.0, 1.0, 1.0, 1.0]
+      p = UnicodePlot.polarplot(theta, r, degrees: false)
+      p.to_s.should contain("0")
+      p.to_s.should contain("π / 2")
+      p.to_s.should contain("π")
+      p.to_s.should contain("3π / 2")
+      p.to_s.should_not contain("3π / 4")
+    end
+  end
+
   describe "stairs" do
     it "raises on mismatched x/y lengths" do
       expect_raises(ArgumentError, /same length/) do

src/unicode_plot.cr

@@ -22,6 +22,7 @@ require "./unicode_plot/interface/boxplot"
 require "./unicode_plot/interface/densityplot"
 require "./unicode_plot/interface/heatmap"
 require "./unicode_plot/interface/spy"
+require "./unicode_plot/interface/polarplot"
 require "./unicode_plot/interface/stairs"
 
 module UnicodePlot