inkplot 0.3.0 → 0.3.2

data/lib/inkplot/core.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 module Inkplot
   module Data
     module_function
@@ -58,13 +60,82 @@ module Inkplot
     rescue NoMethodError
       nil
     end
+  end
 
-    def time(value)
-      case value
-      when Time then value
-      when Date then value.to_time
-      end
+  module Histogram
+    module_function
+
+    def points(values, bins)
+      values = Array(values).filter_map { |value| Data.number(value) }
+      raise ArgumentError, "histogram needs at least one finite numeric value" if values.empty?
+
+      edges = edges(values, bins)
+      counts = Array.new(edges.length - 1, 0)
+      values.each do |value|
+        upper = edges.bsearch_index { |edge| edge > value }
+        index = value == edges.last ? counts.length - 1 : upper && (upper - 1)
+        counts[index] += 1 if index&.between?(0, counts.length - 1)
+      end
+      counts.each_index.map do |index|
+        left, right = edges[index, 2]
+        span = right - left
+        center = span.finite? ? left + (span / 2.0) : (left / 2.0) + (right / 2.0)
+        { x: center, x0: left, x1: right, y: counts[index] }
+      end
+    end
+
+    def edges(values, bins)
+      return validate_edges(bins) if bins.is_a?(Array)
+
+      low, high = values.minmax
+      if low == high
+        lower = low - 0.5
+        upper = high + 0.5
+        low = lower.finite? && lower < low ? lower : low.prev_float
+        high = upper.finite? && upper > high ? upper : high.next_float
+        low = values.first unless low.finite?
+        high = values.first unless high.finite?
+      end
+      count = if bins == :auto
+                sturges = (Math.log2(values.length) + 1).ceil
+                width = 2 * (quantile(values, 0.75) - quantile(values, 0.25)) / (values.length**(1.0 / 3))
+                fd_count = ((high - low) / width).ceil if width.positive? && width.finite?
+                fd_count && fd_count <= values.length ? fd_count : sturges
+              elsif bins.is_a?(Integer) && bins.positive?
+                bins
+              else
+                raise ArgumentError, "bins must be :auto, a positive Integer, or an increasing edge Array"
+              end
+      count = count.clamp(1, values.length) if bins == :auto
+      span = high - low
+      Array.new(count + 1) do |index|
+        if index.zero?
+          low
+        elsif index == count
+          high
+        else
+          fraction = index.to_f / count
+          span.finite? ? low + (span * fraction) : (low * (1 - fraction)) + (high * fraction)
+        end
+      end.uniq
+    end
+    private_class_method :edges
+
+    def validate_edges(values)
+      edges = values.map { |value| Data.number(value) }
+      raise ArgumentError, "histogram bin edges must be finite and strictly increasing" unless edges.length >= 2 && edges.none?(&:nil?) && edges.each_cons(2).all? { |left, right| left < right }
+
+      edges
+    end
+    private_class_method :validate_edges
+
+    def quantile(values, probability)
+      sorted = values.sort
+      position = (sorted.length - 1) * probability
+      low = position.floor
+      sorted[low] + ((sorted[position.ceil] - sorted[low]) * (position - low))
     end
+    private_class_method :quantile
   end
 
   module Ticks
@@ -72,6 +143,7 @@ module Inkplot
 
     def linear(minimum, maximum, count: 5)
       return [minimum] if minimum >= maximum
+      return [minimum, 0.0, maximum] unless (maximum - minimum).finite?
 
       step = linear_step(minimum, maximum, count:)
       first = (minimum / step).ceil * step
@@ -88,8 +160,12 @@ module Inkplot
     def linear_step(minimum, maximum, count: 5)
       return 1.0 unless maximum > minimum
 
-      raw = (maximum - minimum).to_f / [count - 1, 1].max
+      span = (maximum - minimum).to_f
+      raw = span / [count - 1, 1].max
+      raw = span if raw.zero?
       power = 10.0**Math.log10(raw).floor
+      return raw if power.zero?
+
       fraction = raw / power
       (if fraction <= 1
          1
@@ -112,41 +188,83 @@ module Inkplot
     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 }
+      unit, amount = time_interval(maximum - minimum)
+      ticks = if %i[month year].include?(unit)
+                calendar_ticks(minimum, maximum, offset, unit, amount)
               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 }
+                time_ticks(minimum, maximum, offset, unit, amount)
               end
-      ticks.empty? ? [minimum, maximum].uniq : ticks
+      ticks.empty? ? [zoned_time(minimum, offset), zoned_time(maximum, offset)].uniq : ticks
+    end
+
+    def time_interval(span)
+      intervals = [
+        [:second, 1, 1], [:second, 5, 5], [:second, 15, 15], [:second, 30, 30],
+        [:minute, 1, 60], [:minute, 5, 300], [:minute, 15, 900], [:minute, 30, 1800],
+        [:hour, 1, 3600], [:hour, 3, 10_800], [:hour, 6, 21_600], [:hour, 12, 43_200],
+        [:day, 1, 86_400], [:day, 2, 172_800], [:week, 1, 604_800], [:week, 2, 1_209_600],
+        [:month, 1, 2_629_746], [:month, 2, 5_259_492], [:month, 3, 7_889_238], [:month, 6, 15_778_476],
+        [:year, 1, 31_556_952], [:year, 2, 63_113_904], [:year, 5, 157_784_760], [:year, 10, 315_569_520]
+      ]
+      unit, amount, = intervals.min_by { |_, _, seconds| Math.log(seconds / [span / 5.0, 1].max).abs }
+      [unit, amount]
+    end
+
+    def time_ticks(minimum, maximum, offset, unit, amount)
+      seconds = { second: 1, minute: 60, hour: 3600, day: 86_400, week: 604_800 }.fetch(unit) * amount
+      anchor = unit == :week ? 345_600 : 0 # 1970-01-05, a Monday.
+      zone_offset = offset || Time.at(minimum).localtime.utc_offset
+      first = (((minimum + zone_offset - anchor) / seconds).ceil * seconds) + anchor - zone_offset
+      values = []
+      value = first
+      while value <= maximum && values.length < 1000
+        values << zoned_time(value, offset)
+        value += seconds
+      end
+      values
+    end
+    private_class_method :time_ticks
+
+    def calendar_ticks(minimum, maximum, offset, unit, amount)
+      first = zoned_time(minimum, offset)
+      last = zoned_time(maximum, offset)
+      if unit == :month
+        month_index = (first.year * 12) + first.month - 1
+        month_index = (month_index.to_f / amount).ceil * amount
+        values = []
+        while month_index <= (last.year * 12) + last.month - 1 && values.length < 1000
+          year, month = month_index.divmod(12)
+          values << time_at(year, month + 1, 1, offset)
+          month_index += amount
+        end
+      else
+        year = ((first.year.to_f / amount).ceil * amount).to_i
+        values = []
+        while year <= last.year && values.length < 1000
+          values << time_at(year, 1, 1, offset)
+          year += amount
+        end
+      end
+      values
     end
+    private_class_method :calendar_ticks
 
-    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
+    def zoned_time(timestamp, offset)
+      time = Time.at(timestamp)
+      offset.nil? ? time.localtime : time.getlocal(offset)
+    end
+    private_class_method :zoned_time
+
+    def time_at(year, month, day, offset)
+      return Time.local(year, month, day) if offset.nil?
 
-      time.strftime("%H:%M:%S")
+      Time.new(year, month, day, 0, 0, 0, offset)
     end
+    private_class_method :time_at
 
     def number_label(value)
+      return format("%.8g", value) if !value.zero? && value.abs < 1e-6
+
       value.to_i == value ? value.to_i.to_s : format("%.8f", value).sub(/0+\z/, "").sub(/\.\z/, "")
     end
   end
@@ -175,9 +293,11 @@ module Inkplot
         raise ArgumentError, "linear axis minimum must be less than maximum" unless low < high
 
         @ticks = Ticks.linear(low, high)
-        step = Ticks.linear_step(low, high)
-        low = (low / step).floor * step if options[:min].nil?
-        high = (high / step).ceil * step if options[:max].nil?
+        if (high - low).finite?
+          step = Ticks.linear_step(low, high)
+          low = (low / step).floor * step if options[:min].nil?
+          high = (high / step).ceil * step if options[:max].nil?
+        end
         @domain = [low, high]
       end
 
@@ -185,7 +305,14 @@ module Inkplot
         value = Data.number(value)
         return nil unless value
 
-        @range[0] + ((value - @domain[0]) * (@range[1] - @range[0]) / (@domain[1] - @domain[0]))
+        span = @domain[1] - @domain[0]
+        fraction = (value - @domain[0]) / span
+        unless span.finite?
+          numerator = (value / 2.0) - (@domain[0] / 2.0)
+          denominator = (@domain[1] / 2.0) - (@domain[0] / 2.0)
+          fraction = numerator / denominator
+        end
+        @range[0] + (fraction * (@range[1] - @range[0]))
       end
 
       def format(value) = Ticks.number_label(value)
@@ -266,48 +393,127 @@ module Inkplot
       def format(value) = value.to_s
     end
 
-    class TimeScale
-      attr_reader :domain, :ticks, :offset
+    class Time
+      attr_reader :domain, :ticks
       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
+        values = values.compact
+        raise ArgumentError, "time axis needs Time or Date values" unless values.all? { |value| value.is_a?(::Time) || value.is_a?(Date) }
 
-        @offset = offsets.first || 0
-        numbers = times.map(&:to_f)
+        times = values.grep(::Time)
+        zone_names = times.map(&:zone).uniq
+        offsets = values.filter_map { |value| time_offset(value) }.uniq
+        @local_time = !times.empty? && values.none?(DateTime) && times.all? { |value| local_time?(value) }
+        raise ArgumentError, "time axis values must use the same time zone" if !@local_time && (offsets.length > 1 || zone_names.length > 1)
+
+        @offset = @local_time ? nil : offsets.first || 0
+        numbers = values.map { |value| timestamp(value) }
         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 needs at least one date or time value" unless low
+
+        if options[:min]
+          validate_bound(options[:min], "minimum")
+
+          low = timestamp(options[:min])
+          raise ArgumentError, "time axis minimum must be a Time or Date" unless low
+        end
+        if options[:max]
+          validate_bound(options[:max], "maximum")
+
+          high = timestamp(options[:max])
+          raise ArgumentError, "time axis maximum must be a Time or Date" unless high
+        end
+        if low == high
+          raise ArgumentError, "time axis minimum must be less than maximum" if options[:min] && options[:max]
+
+          if options[:min]
+            high += 3600
+          elsif options[:max]
+            low -= 3600
+          else
+            low -= 1800
+            high += 1800
+          end
+        end
         raise ArgumentError, "time axis minimum must be less than maximum" unless low < high
 
-        @ticks = Ticks.time(low, high, offset: @offset)
         @domain = [low, high]
+        @tick_unit, = Ticks.time_interval(high - low)
+        @ticks = Ticks.time(low, high, offset: @offset)
       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
+        number = timestamp(value)
+        return nil unless number
+
+        @range[0] + ((number - @domain[0]) * (@range[1] - @range[0]) / (@domain[1] - @domain[0]))
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def format(value)
+        time = if value.is_a?(::Time)
+                 @local_time ? value.localtime : value.getlocal(@offset)
+               else
+                 as_time(value)
+               end
+        format_string = case @tick_unit
+                        when :second then "%H:%M:%S"
+                        when :minute, :hour then "%H:%M"
+                        when :day, :week then "%Y-%m-%d"
+                        when :month then "%Y-%m"
+                        when :year then "%Y"
+                        end
+        time.strftime(format_string)
+      end
+
+      private
 
-        @range[0] + ((time - @domain[0]) * (@range[1] - @range[0]) / (@domain[1] - @domain[0]))
+      def time_offset(value)
+        return value.utc_offset if value.is_a?(::Time)
+        return (value.offset * 86_400).to_i if value.is_a?(DateTime)
+
+        nil
       end
 
-      def format(value) = Ticks.time_label(value, @domain[1] - @domain[0], offset: @offset)
+      def local_time?(value)
+        ::Time.at(value.to_r).localtime.zone == value.zone
+      end
 
-      private
+      def validate_bound(value, name)
+        raise ArgumentError, "time axis #{name} must be a Time or Date" unless value.is_a?(::Time) || value.is_a?(Date)
 
-      def time_limit(value, fallback, name)
-        return fallback if value.nil?
+        if @local_time
+          valid = value.is_a?(::Time) ? local_time?(value) : value.is_a?(Date) && !value.is_a?(DateTime)
+          raise ArgumentError, "time axis values must use the same time zone" unless valid
+        else
+          bound_offset = time_offset(value)
+          raise ArgumentError, "time axis values must use the same time zone" if bound_offset && bound_offset != @offset
+        end
+      end
+
+      def timestamp(value)
+        return value.to_f if value.is_a?(::Time)
+        return value.to_time.to_f if value.is_a?(DateTime)
+        return date_time(value).to_f if value.is_a?(Date)
+
+        nil
+      end
+
+      def as_time(value)
+        return ::Time.at(value.to_time.to_f).localtime if @local_time && value.is_a?(DateTime)
+        return ::Time.at(value.to_time.to_f).getlocal(@offset) if value.is_a?(DateTime)
+        return date_time(value) if value.is_a?(Date)
+
+        local_zone = ::Time.at(timestamp(value))
+        @local_time ? local_zone.localtime : local_zone.getlocal(@offset)
+      end
 
-        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
+      def date_time(value)
+        return ::Time.local(value.year, value.month, value.day) if @local_time
 
-        time.to_f
+        ::Time.new(value.year, value.month, value.day, 0, 0, 0, @offset)
       end
     end
   end
@@ -330,11 +536,14 @@ module Inkplot
 
     def font_for(size = 12)
       require "glyphic"
-      return Glyphic.load(Inkplot.config.font, size: size) if Inkplot.config.font
+      if Inkplot.config.font
+        @fonts ||= {}
+        return @fonts[[Inkplot.config.font, size]] ||= Glyphic.load(Inkplot.config.font, size: size)
+      end
 
       Glyphic.default
     rescue LoadError => e
-      raise LoadError, "PNG output needs glyphic; install it with `gem install glyphic` (#{e.message})"
+      raise LoadError, "font metrics need glyphic; install it with `gem install glyphic` (#{e.message})"
     end
   end
 
@@ -406,8 +615,8 @@ module Inkplot
 
     def legend(position: :top_right) = @legend_options = { position: position.to_sym }
 
-    def line(x, y = nil, label: nil, color: nil, dash: false, gaps: :break, **)
-      add(:line, Data.points(x, y), label:, color:, dash:, gaps:, **)
+    def line(x, y = nil, label: nil, color: nil, dash: false, gaps: :break, cap: :butt, join: :miter, **)
+      add(:line, Data.points(x, y), label:, color:, dash:, gaps:, cap:, join:, **)
     end
 
     def scatter(x, y = nil, label: nil, color: nil, size: nil, **)
@@ -427,19 +636,8 @@ 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, **)
+    def histogram(values, bins: :auto, label: nil, color: nil)
+      add(:histogram, Histogram.points(values, bins), label:, color:)
     end
 
     def hline(value, label: nil, color: nil, dash: true)
@@ -453,38 +651,30 @@ 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) }
+    def annotate(x, y, text, color: nil, anchor: :start)
+      raise ArgumentError, "annotation text must not be empty" if text.to_s.empty?
+      raise ArgumentError, "annotation anchor must be :start, :middle, or :end" unless %i[start middle end].include?(anchor.to_sym)
+
+      @notes << { type: :text, x:, y:, text: text.to_s, color: Theme.validate_color(color), anchor: anchor.to_sym }
     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)
+      type = type.to_sym
+      raise ArgumentError, "unsupported chart mark: #{type}" unless %i[line scatter bar area step histogram].include?(type)
       raise ArgumentError, "gaps must be :break or :connect" if options[:gaps] && !%i[break connect].include?(options[:gaps])
 
-      @series << Series.new(type: type.to_sym, points:, label: label&.to_s, color: Theme.validate_color(color), options:)
-      self
-    end
-
-    private
+      if type == :line
+        options[:cap] = (options[:cap] || :butt).to_sym
+        options[:join] = (options[:join] || :miter).to_sym
+        raise ArgumentError, "line cap must be :butt or :round" unless %i[butt round].include?(options[:cap])
+        raise ArgumentError, "line join must be :miter, :round, or :bevel" unless %i[miter round bevel].include?(options[:join])
 
-    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"
+        options[:width] = Data.number(options[:width] || 2)
+        raise ArgumentError, "line width must be finite and positive" unless options[:width]&.positive?
       end
+
+      @series << Series.new(type:, points:, label: label&.to_s, color: Theme.validate_color(color), options:)
+      self
     end
   end
 
@@ -502,19 +692,18 @@ module Inkplot
       Renderers::SVG.render(SceneBuilder.call(self, width: width, height: height))
     end
 
-    def to_image(scale: 1)
-      require_relative "renderers/raster"
-      Renderers::Raster.render(SceneBuilder.call(self, width: width, height: height), scale: scale)
+    def to_image(width: self.width, height: self.height, scale: 1)
+      Renderers::PNG.render(SceneBuilder.call(self, width: width, height: height), 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))
+      Renderers::PNG.encode(to_image(width:, height:, scale:))
+    end
+
+    def _repr_svg_ = to_svg
+
+    def to_inlay
+      { svg: to_svg, png: -> { to_png } }
     end
 
     def save(path, width: self.width, height: self.height, scale: 1)
@@ -526,10 +715,6 @@ module Inkplot
       path
     end
 
-    def to_inlay
-      { svg: to_svg, png: -> { to_png } }
-    end
-
     private
 
     def series = builder.series
@@ -549,7 +734,7 @@ module Inkplot
 
       warn "Inkplot cycles its eight-color palette after eight series." if series.length > Theme::PALETTE.length
       colors = Theme.colors(builder.theme)
-      x_values = series.flat_map { |item| item.points.flat_map { |point| [point[:x], point[:x2]].compact } }
+      x_values = series.flat_map { |item| item.points.flat_map { |point| [point[:x], point[:x0], point[:x1], point[:x2]].compact } }
       y_values = series.flat_map { |item| item.points.map { |point| point[:y] } }
       if series.any? { |item| item.options[:stacked] }
         totals = stacked_totals(series)
@@ -569,14 +754,6 @@ 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
@@ -584,6 +761,16 @@ module Inkplot
       legend_items.uniq!(&:first)
       legend_width = [legend_items.map { |label, _| TextMetrics.width(label, 11) }.max.to_f.ceil + 30, 120].max
       right = builder.legend_options[:position].to_s.end_with?("right") && legend_items.length > 1 ? legend_width + 18 : 18
+      plot_width = width - right - left
+      tick_gap = plot_width.to_f / [x_ticks.length - 1, 1].max
+      longest_tick = x_ticks.map { |tick| TextMetrics.width(x_scale.format(tick), 10) }.max.to_f
+      tick_stride = [(longest_tick / [tick_gap, 1].max).ceil, 1].max
+      shown_ticks = x_ticks.each_index.select { |index| (index % tick_stride).zero? || index == x_ticks.length - 1 }
+      shown_gap = plot_width.to_f / [shown_ticks.length - 1, 1].max
+      rotate_ticks = height >= 180 && shown_ticks.any? { |index| TextMetrics.width(x_scale.format(x_ticks[index]), 10) > shown_gap * 0.75 }
+      bottom += 42 if rotate_ticks
+      raise ArgumentError, "chart dimensions are too small for labels or legend" if plot_width <= 0 || height - top - bottom <= 0
+
       x_scale.range = [left, width - right]
       y_scale.range = [height - bottom, top]
       clip = [left, top, width - right, height - bottom]
@@ -597,13 +784,16 @@ module Inkplot
         elements << { type: :line, class: "grid-line", points: [[left, y], [width - right, y]], stroke: colors[:grid], width: 1 }
         elements << { type: :text, x: left - 8, y: y + 4, text: y_scale.format(tick), fill: colors[:axis], anchor: :end, size: 11 }
       end
-      x_ticks.each_with_index do |tick, _index|
+      x_ticks.each_with_index do |tick, index|
+        next unless shown_ticks.include?(index)
+
         x = x_scale.map(tick)
         next unless x
 
         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 + (rotate ? 14 : 18), text: label, fill: colors[:axis], anchor: :middle, size: 10, rotate: (rotate ? -45 : nil) }
+        elements << { type: :text, x:, y: height - bottom + 18, text: label, fill: colors[:axis], anchor: rotate_ticks ? :end : :middle, size: 10,
+                      rotate: rotate_ticks ? -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
@@ -620,14 +810,27 @@ module Inkplot
       series.each_with_index do |item, index|
         color = item.color || Theme.series_color(index, builder.theme)
         points = item.points
+        if item.type == :histogram
+          points.each do |point|
+            x0 = x_scale.map(point[:x0])
+            x1 = x_scale.map(point[:x1])
+            y0 = y_scale.map(0)
+            y1 = y_scale.map(point[:y])
+            next unless x0 && x1 && y0 && y1
+
+            marks << { type: :rect, class: "histogram-mark", series_index: index, x: x0, y: [y0, y1].min, width: x1 - x0,
+                       height: (y0 - y1).abs, fill: color }
+          end
+          next
+        end
         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]
@@ -647,15 +850,7 @@ 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]
@@ -687,7 +882,8 @@ module Inkplot
                 [[px, py]]
               end
             end
-            marks << { type: :line, class: "mark-line", series_index: index, points: coordinates, stroke: color, width: item.options[:width] || 2, dash: item.options[:dash] }
+            marks << { type: :line, class: "mark-line", series_index: index, points: coordinates, stroke: color, width: item.options[:width] || 2,
+                       dash: item.options[:dash], cap: item.options[:cap], join: item.options[:join] }
           end
         when :area
           drawable_segments(drawable, false).each do |segment|
@@ -714,14 +910,20 @@ module Inkplot
         case note[:type]
         when :hline
           y = y_scale.map(note[:value])
-          marks << { type: :line, class: "rule-line", points: [[left, y], [width - right, y]], stroke: color, width: 1.5, dash: note[:dash], label: note[:label] } if y
+          if y
+            marks << { type: :line, class: "rule-line", points: [[left, y], [width - right, y]], stroke: color, width: 1.5, dash: note[:dash] }
+            marks << { type: :text, x: width - right - 4, y: y - 4, text: note[:label], fill: color, anchor: :end, size: 11 } if note[:label]
+          end
         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
+          if x
+            marks << { type: :line, class: "rule-line", points: [[x, top], [x, height - bottom]], stroke: color, width: 1.5, dash: note[:dash] }
+            marks << { type: :text, x: x + 4, y: top + 12, text: note[:label], fill: color, anchor: :start, size: 11 } if note[:label]
+          end
         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
+          marks << { type: :text, x:, y:, text: note[:text], fill: color, anchor: note[:anchor], size: 11 } if x && y
         end
       end
 
@@ -739,10 +941,13 @@ 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[: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) }))
+      bar_band = series.any? { |item| item.type == :bar && ((item.options[:horizontal] && axis == :y) || (!item.options[:horizontal] && axis == :x)) }
+      histogram_axis = axis == :x && series.any? { |item| item.type == :histogram }
+      if histogram_axis && explicit == :band
+        raise ArgumentError, "histogram x axis must use a numeric scale"
+      elsif explicit == :time || explicit == "time" || (explicit.nil? && values.any? { |value| value.is_a?(::Time) || value.is_a?(Date) })
+        Scales::Time.new(values, options)
+      elsif explicit == :band || (explicit.nil? && !histogram_axis && (bar_band || values.any? { |value| !Data.number(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? }
@@ -751,7 +956,7 @@ module Inkplot
         raise ArgumentError, "unknown #{axis}-axis scale: #{explicit}" if explicit && explicit != :linear
 
         include_zero = series.any? do |item|
-          (axis == :y && %i[bar area].include?(item.type) && !item.options[:horizontal]) ||
+          (axis == :y && %i[bar area histogram].include?(item.type) && !item.options[:horizontal]) ||
             (horizontal_bar && axis == :x && item.options[:horizontal])
         end
         Scales::Linear.new(values, options, include_zero: include_zero)