vizcore 1.0.0 → 1.2.0

data/lib/vizcore/renderer/snapshot_renderer.rb

@@ -8,6 +8,9 @@ module Vizcore
     class SnapshotRenderer
       DEFAULT_WIDTH = 1280
       DEFAULT_HEIGHT = 720
+      PATH_DEFAULT_MAX_SEGMENTS = 4096
+      PATH_HARD_MAX_SEGMENTS = 65_536
+      PATH_MAX_RECURSION = 12
       PALETTE = [
         [56, 189, 248],
         [225, 29, 72],
@@ -16,9 +19,10 @@ module Vizcore
         [250, 204, 21]
       ].freeze
 
-      def initialize(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT)
+      def initialize(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT, transparent: false)
         @width = normalize_dimension(width)
         @height = normalize_dimension(height)
+        @transparent = !!transparent
       end
 
       attr_reader :width, :height
@@ -27,8 +31,8 @@ module Vizcore
       # @param audio [Hash]
       # @return [String] PNG bytes
       def render(scene:, audio:)
-        canvas = Canvas.new(width: width, height: height)
-        canvas.fill_gradient(background_top(audio), background_bottom(audio))
+        canvas = Canvas.new(width: width, height: height, transparent: @transparent)
+        canvas.fill_gradient(background_top(audio), background_bottom(audio)) unless @transparent
         layers = Array(scene[:layers] || scene["layers"])
         layers = [default_layer] if layers.empty?
         layers.each_with_index { |layer, index| render_layer(canvas, layer, audio, index) }
@@ -156,6 +160,7 @@ module Vizcore
       def render_shape_layer(canvas, layer, audio, color)
         params = Hash(layer[:params] || layer["params"] || {})
         shapes = Array(params[:shapes] || params["shapes"])
+        context = shape_coordinate_context(params)
         pulse = clamp(audio[:beat_pulse])
         alpha = 0.58 + pulse * 0.24
 
@@ -163,34 +168,522 @@ module Vizcore
           shape_hash = Hash(shape)
           case (shape_hash[:kind] || shape_hash["kind"]).to_s
           when "circle"
-            render_circle_shape(canvas, shape_hash, color, alpha)
+            render_circle_shape(canvas, shape_hash, color, alpha, context)
           when "line"
-            render_line_shape(canvas, shape_hash, color, alpha)
+            render_line_shape(canvas, shape_hash, color, alpha, context)
+          when "rect"
+            render_rect_shape(canvas, shape_hash, color, alpha, context)
+          when "polygon", "polyline"
+            render_polygon_shape(canvas, shape_hash, color, alpha, context)
+          when "path"
+            render_path_shape(canvas, shape_hash, color, alpha, context)
+          when "star"
+            render_star_shape(canvas, shape_hash, color, alpha, context)
           end
         end
       rescue ArgumentError, TypeError
         nil
       end
 
-      def render_circle_shape(canvas, shape, color, alpha)
+      def render_circle_shape(canvas, shape, color, alpha, context)
         count = [[Integer(shape[:count] || shape["count"] || 1), 1].max, 32].min
-        radius = Float(shape[:radius] || shape["radius"] || 100).abs
-        x = Float(shape[:x] || shape["x"] || width * 0.5)
-        y = Float(shape[:y] || shape["y"] || height * 0.5)
-        x = width * 0.5 if x.abs <= 1.5
-        y = height * 0.5 if y.abs <= 1.5
+        radius = shape_length(shape[:radius] || shape["radius"] || 100, context, :radius)
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
 
         count.times do |index|
-          canvas.draw_circle_outline(x, y, radius * ((index + 1).to_f / count), color, alpha: alpha)
+          ring_radius = radius * ((index + 1).to_f / count)
+          render_polyline_shape(canvas, circle_points(center, ring_radius), shape, color, alpha, context, closed: true)
         end
       end
 
-      def render_line_shape(canvas, shape, color, alpha)
-        x1 = Float(shape[:x1] || shape["x1"] || width * 0.2)
-        y1 = Float(shape[:y1] || shape["y1"] || height * 0.5)
-        x2 = Float(shape[:x2] || shape["x2"] || width * 0.8)
-        y2 = Float(shape[:y2] || shape["y2"] || height * 0.5)
-        canvas.draw_line(x1, y1, x2, y2, color, alpha: alpha)
+      def render_line_shape(canvas, shape, color, alpha, context)
+        defaults = context[:units] == :legacy || context[:units] == :ndc ? [-0.8, 0, 0.8, 0] : [-100, 0, 100, 0]
+        from = shape_point(shape[:x1] || shape["x1"] || defaults[0], shape[:y1] || shape["y1"] || defaults[1], context)
+        to = shape_point(shape[:x2] || shape["x2"] || defaults[2], shape[:y2] || shape["y2"] || defaults[3], context)
+        draw_shape_segment(canvas, from, to, shape, color, alpha, context)
+      end
+
+      def render_rect_shape(canvas, shape, color, alpha, context)
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
+        half_width = shape_length(shape[:width] || shape["width"] || 100, context, :x) / 2.0
+        half_height = shape_length(shape[:height] || shape["height"] || 100, context, :y) / 2.0
+        points = [
+          [center[0] - half_width, center[1] - half_height],
+          [center[0] + half_width, center[1] - half_height],
+          [center[0] + half_width, center[1] + half_height],
+          [center[0] - half_width, center[1] + half_height]
+        ]
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: true)
+      end
+
+      def render_polygon_shape(canvas, shape, color, alpha, context)
+        points = Array(shape[:points] || shape["points"]).filter_map do |point|
+          values = Array(point)
+          next if values.length < 2
+
+          shape_point(values[0], values[1], context)
+        end
+        closed = (shape[:kind] || shape["kind"]).to_s == "polygon" ? shape.fetch(:closed, shape.fetch("closed", true)) : false
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: closed)
+      end
+
+      def render_star_shape(canvas, shape, color, alpha, context)
+        tips = [[Integer(shape[:points] || shape["points"] || 5), 3].max, 128].min
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
+        radius = shape_length(shape[:radius] || shape["radius"] || 100, context, :radius)
+        inner_radius = shape_length(shape[:inner_radius] || shape["inner_radius"] || Float(shape[:radius] || shape["radius"] || 100) * 0.5, context, :radius)
+        rotation = Float(shape[:rotation] || shape["rotation"] || -90) * Math::PI / 180.0
+        points = (tips * 2).times.map do |index|
+          angle = rotation + (index.to_f / (tips * 2)) * Math::PI * 2
+          point_radius = index.even? ? radius : inner_radius
+          [center[0] + Math.cos(angle) * point_radius, center[1] - Math.sin(angle) * point_radius]
+        end
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: true)
+      end
+
+      def render_path_shape(canvas, shape, color, alpha, context)
+        detail = [[Integer(shape[:detail] || shape["detail"] || 32), 4].max, 128].min
+        tolerance = path_tolerance(shape)
+        segment_budget = { remaining: path_segment_limit(shape) }
+        current = nil
+        subpath_start = nil
+        Array(shape[:commands] || shape["commands"]).each do |entry|
+          command, *values = Array(entry)
+          values = values.map { |value| Float(value) }
+          case command.to_s.upcase
+          when "M"
+            current = values.first(2)
+            subpath_start = current
+          when "L"
+            next unless current && values.length >= 2
+
+            current = draw_raw_path_segment(canvas, current, values.first(2), shape, color, alpha, context, segment_budget)
+          when "H"
+            next unless current && values.length >= 1
+
+            current = draw_raw_path_segment(canvas, current, [values[0], current[1]], shape, color, alpha, context, segment_budget)
+          when "V"
+            next unless current && values.length >= 1
+
+            current = draw_raw_path_segment(canvas, current, [current[0], values[0]], shape, color, alpha, context, segment_budget)
+          when "Q"
+            next unless current && values.length >= 4
+
+            current = draw_quadratic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget)
+          when "C"
+            next unless current && values.length >= 6
+
+            current = draw_cubic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget)
+          when "A"
+            next unless current && values.length >= 7
+
+            current = draw_arc_path(canvas, current, values, detail, shape, color, alpha, context, segment_budget)
+          when "Z"
+            if current && subpath_start
+              current = draw_raw_path_segment(canvas, current, subpath_start, shape, color, alpha, context, segment_budget)
+            end
+          end
+        end
+      end
+
+      def render_polyline_shape(canvas, points, shape, color, alpha, context, closed:)
+        return if points.length < 2
+
+        points.each_cons(2) { |from, to| draw_shape_segment(canvas, from, to, shape, color, alpha, context) }
+        draw_shape_segment(canvas, points.last, points.first, shape, color, alpha, context) if closed && points.length > 2
+      end
+
+      def draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget = nil)
+        return to if segment_budget && segment_budget[:remaining] <= 0
+
+        draw_shape_segment(canvas, shape_point(from[0], from[1], context), shape_point(to[0], to[1], context), shape, color, alpha, context)
+        segment_budget[:remaining] -= 1 if segment_budget
+        to
+      end
+
+      def draw_quadratic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget = nil)
+        previous = current
+        control = values.first(2)
+        endpoint = values.last(2)
+        if tolerance
+          draw_adaptive_quadratic_path(canvas, current, control, endpoint, tolerance, shape, color, alpha, context, segment_budget)
+          return endpoint
+        end
+
+        1.upto(detail) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          t = step.to_f / detail
+          point = [
+            quadratic_point(current[0], control[0], endpoint[0], t),
+            quadratic_point(current[1], control[1], endpoint[1], t)
+          ]
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def draw_cubic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget = nil)
+        previous = current
+        c1 = values[0, 2]
+        c2 = values[2, 2]
+        endpoint = values[4, 2]
+        if tolerance
+          draw_adaptive_cubic_path(canvas, current, c1, c2, endpoint, tolerance, shape, color, alpha, context, segment_budget)
+          return endpoint
+        end
+
+        1.upto(detail) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          t = step.to_f / detail
+          point = [
+            cubic_point(current[0], c1[0], c2[0], endpoint[0], t),
+            cubic_point(current[1], c1[1], c2[1], endpoint[1], t)
+          ]
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def draw_arc_path(canvas, current, values, detail, shape, color, alpha, context, segment_budget = nil)
+        endpoint = values[5, 2]
+        arc = svg_arc_description(
+          from: current,
+          to: endpoint,
+          rx: values[0],
+          ry: values[1],
+          x_axis_rotation: values[2],
+          large_arc: arc_flag(values[3]),
+          sweep: arc_flag(values[4])
+        )
+        unless arc
+          return draw_raw_path_segment(canvas, current, endpoint, shape, color, alpha, context, segment_budget)
+        end
+
+        previous = current
+        segments = svg_arc_segment_count(arc, detail)
+        1.upto(segments) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          point = svg_arc_point(arc, step.to_f / segments)
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def path_segment_limit(shape)
+        raw_value = shape[:max_segments] || shape["max_segments"] || PATH_DEFAULT_MAX_SEGMENTS
+        [[Integer(raw_value), 1].max, PATH_HARD_MAX_SEGMENTS].min
+      rescue ArgumentError, TypeError
+        PATH_DEFAULT_MAX_SEGMENTS
+      end
+
+      def path_tolerance(shape)
+        return unless shape.key?(:tolerance) || shape.key?("tolerance")
+
+        value = Float(shape[:tolerance] || shape["tolerance"])
+        value if value.finite? && value >= 0
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def draw_adaptive_quadratic_path(canvas, from, control, to, tolerance, shape, color, alpha, context, segment_budget, depth = 0)
+        return if segment_budget && segment_budget[:remaining] <= 0
+
+        if depth >= PATH_MAX_RECURSION || point_line_distance(control, from, to) <= tolerance
+          draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget)
+          return
+        end
+
+        left_control = midpoint(from, control)
+        right_control = midpoint(control, to)
+        center = midpoint(left_control, right_control)
+        draw_adaptive_quadratic_path(canvas, from, left_control, center, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+        draw_adaptive_quadratic_path(canvas, center, right_control, to, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+      end
+
+      def draw_adaptive_cubic_path(canvas, from, c1, c2, to, tolerance, shape, color, alpha, context, segment_budget, depth = 0)
+        return if segment_budget && segment_budget[:remaining] <= 0
+
+        flatness = [point_line_distance(c1, from, to), point_line_distance(c2, from, to)].max
+        if depth >= PATH_MAX_RECURSION || flatness <= tolerance
+          draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget)
+          return
+        end
+
+        p01 = midpoint(from, c1)
+        p12 = midpoint(c1, c2)
+        p23 = midpoint(c2, to)
+        p012 = midpoint(p01, p12)
+        p123 = midpoint(p12, p23)
+        center = midpoint(p012, p123)
+        draw_adaptive_cubic_path(canvas, from, p01, p012, center, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+        draw_adaptive_cubic_path(canvas, center, p123, p23, to, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+      end
+
+      def midpoint(from, to)
+        [(from[0] + to[0]) * 0.5, (from[1] + to[1]) * 0.5]
+      end
+
+      def point_line_distance(point, from, to)
+        dx = to[0] - from[0]
+        dy = to[1] - from[1]
+        length = Math.sqrt((dx * dx) + (dy * dy))
+        return Math.sqrt(((point[0] - from[0])**2) + ((point[1] - from[1])**2)) if length <= 0
+
+        ((dy * point[0]) - (dx * point[1]) + (to[0] * from[1]) - (to[1] * from[0])).abs / length
+      end
+
+      def draw_shape_segment(canvas, from, to, shape, color, alpha, context)
+        from = apply_shape_transform(from, shape, context)
+        to = apply_shape_transform(to, shape, context)
+        canvas.draw_line(from[0], from[1], to[0], to[1], color, alpha: alpha * shape_opacity(shape))
+      end
+
+      def shape_coordinate_context(params)
+        units = (params[:units] || params["units"]).to_s.strip.downcase
+        version = Integer(params[:shape_schema_version] || params["shape_schema_version"] || 1)
+        { units: (units.empty? ? (version >= 2 ? :logical : :legacy) : units.to_sym) }
+      rescue ArgumentError, TypeError
+        { units: :legacy }
+      end
+
+      def shape_point(x, y, context)
+        [shape_coordinate(x, context, :x), shape_coordinate(y, context, :y)]
+      end
+
+      def shape_coordinate(value, context, axis)
+        numeric = Float(value || 0)
+        case context[:units]
+        when :ndc
+          axis == :x ? width * 0.5 + numeric * width * 0.5 : height * 0.5 - numeric * height * 0.5
+        when :logical, :center, :center_origin, :px
+          axis == :x ? width * 0.5 + numeric : height * 0.5 - numeric
+        when :screen, :canvas, :viewport
+          numeric
+        else
+          legacy_shape_coordinate(numeric, axis)
+        end
+      end
+
+      def legacy_shape_coordinate(value, axis)
+        return axis == :x ? width * 0.5 + value * width * 0.5 : height * 0.5 - value * height * 0.5 if value.abs <= 1.5
+
+        value
+      end
+
+      def shape_length(value, context, _axis)
+        numeric = Float(value || 0).abs
+        return numeric * [width, height].min * 0.5 if context[:units] == :ndc || numeric <= 2
+
+        numeric
+      end
+
+      def circle_points(center, radius)
+        segments = 96
+        segments.times.map do |index|
+          angle = (index.to_f / segments) * Math::PI * 2
+          [center[0] + Math.cos(angle) * radius, center[1] + Math.sin(angle) * radius]
+        end
+      end
+
+      def apply_shape_transform(point, shape, context)
+        transform = shape_transform(shape, context)
+        shifted_x = (point[0] - transform[:origin][0]) * transform[:scale][:x]
+        shifted_y = (point[1] - transform[:origin][1]) * transform[:scale][:y]
+        radians = -transform[:rotate] * Math::PI / 180.0
+        cos = Math.cos(radians)
+        sin = Math.sin(radians)
+        rotated_x = shifted_x * cos - shifted_y * sin
+        rotated_y = shifted_x * sin + shifted_y * cos
+
+        [
+          rotated_x + transform[:origin][0] + transform[:translate][:x],
+          rotated_y + transform[:origin][1] + transform[:translate][:y]
+        ]
+      end
+
+      def shape_transform(shape, context)
+        transform = Hash(shape[:transform] || shape["transform"] || {})
+        {
+          translate: shape_vector_pair(shape_hash_value(transform, :translate) || shape_hash_value(shape, :translate), context),
+          origin: shape_origin_pair(shape_hash_value(transform, :origin) || shape_hash_value(shape, :origin), context),
+          rotate: Float(shape_hash_value(transform, :rotate) || shape_hash_value(shape, :rotate) || shape_hash_value(shape, :rotation) || 0),
+          scale: shape_scale(shape_hash_value(transform, :scale) || shape_hash_value(shape, :scale))
+        }
+      end
+
+      def shape_vector_pair(value, context)
+        if value.is_a?(Array)
+          return { x: shape_vector(value[0], context, :x), y: shape_vector(value[1], context, :y) }
+        end
+
+        values = value.is_a?(Hash) ? value : {}
+        { x: shape_vector(shape_hash_value(values, :x) || 0, context, :x), y: shape_vector(shape_hash_value(values, :y) || 0, context, :y) }
+      end
+
+      def shape_origin_pair(value, context)
+        if value.is_a?(Array)
+          return shape_point(value[0], value[1], context)
+        end
+
+        values = value.is_a?(Hash) ? value : {}
+        shape_point(shape_hash_value(values, :x) || 0, shape_hash_value(values, :y) || 0, context)
+      end
+
+      def shape_vector(value, context, axis)
+        numeric = Float(value || 0)
+        case context[:units]
+        when :ndc
+          axis == :x ? numeric * width * 0.5 : -numeric * height * 0.5
+        else
+          axis == :x ? numeric : -numeric
+        end
+      end
+
+      def shape_scale(value)
+        if value.is_a?(Hash)
+          return {
+            x: Float(shape_hash_value(value, :x) || 1).clamp(-8.0, 8.0),
+            y: Float(shape_hash_value(value, :y) || 1).clamp(-8.0, 8.0)
+          }
+        end
+
+        scale = Float(value || 1).clamp(-8.0, 8.0)
+        { x: scale, y: scale }
+      end
+
+      def shape_opacity(shape)
+        Float(shape[:opacity] || shape["opacity"] || 1).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        1.0
+      end
+
+      def shape_hash_value(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def quadratic_point(from, control, to, t)
+        inv = 1.0 - t
+        inv * inv * from + 2 * inv * t * control + t * t * to
+      end
+
+      def cubic_point(from, c1, c2, to, t)
+        inv = 1.0 - t
+        inv * inv * inv * from + 3 * inv * inv * t * c1 + 3 * inv * t * t * c2 + t * t * t * to
+      end
+
+      def svg_arc_description(from:, to:, rx:, ry:, x_axis_rotation:, large_arc:, sweep:)
+        return if same_point?(from, to)
+
+        radius_x = Float(rx || 0).abs
+        radius_y = Float(ry || 0).abs
+        return if radius_x <= 0 || radius_y <= 0
+
+        rotation = Float(x_axis_rotation || 0) * Math::PI / 180.0
+        cos = Math.cos(rotation)
+        sin = Math.sin(rotation)
+        dx = (from[0] - to[0]) / 2.0
+        dy = (from[1] - to[1]) / 2.0
+        x1p = cos * dx + sin * dy
+        y1p = -sin * dx + cos * dy
+
+        scale = (x1p * x1p / (radius_x * radius_x)) + (y1p * y1p / (radius_y * radius_y))
+        if scale > 1
+          multiplier = Math.sqrt(scale)
+          radius_x *= multiplier
+          radius_y *= multiplier
+        end
+
+        center = svg_arc_center(
+          from: from,
+          to: to,
+          radius_x: radius_x,
+          radius_y: radius_y,
+          x1p: x1p,
+          y1p: y1p,
+          rotation_cos: cos,
+          rotation_sin: sin,
+          large_arc: large_arc,
+          sweep: sweep
+        )
+        return unless center
+
+        start_vector = [(x1p - center[:cxp]) / radius_x, (y1p - center[:cyp]) / radius_y]
+        end_vector = [(-x1p - center[:cxp]) / radius_x, (-y1p - center[:cyp]) / radius_y]
+        start_angle = vector_angle([1.0, 0.0], start_vector)
+        delta_angle = vector_angle(start_vector, end_vector)
+        delta_angle -= Math::PI * 2 if !sweep && delta_angle.positive?
+        delta_angle += Math::PI * 2 if sweep && delta_angle.negative?
+
+        {
+          cx: center[:cx],
+          cy: center[:cy],
+          rx: radius_x,
+          ry: radius_y,
+          rotation: rotation,
+          start_angle: start_angle,
+          delta_angle: delta_angle
+        }
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def svg_arc_center(from:, to:, radius_x:, radius_y:, x1p:, y1p:, rotation_cos:, rotation_sin:, large_arc:, sweep:)
+        rx2 = radius_x * radius_x
+        ry2 = radius_y * radius_y
+        x1p2 = x1p * x1p
+        y1p2 = y1p * y1p
+        denominator = rx2 * y1p2 + ry2 * x1p2
+        return if denominator.zero?
+
+        numerator = [rx2 * ry2 - rx2 * y1p2 - ry2 * x1p2, 0.0].max
+        sign = large_arc == sweep ? -1.0 : 1.0
+        coefficient = sign * Math.sqrt(numerator / denominator)
+        cxp = coefficient * ((radius_x * y1p) / radius_y)
+        cyp = coefficient * (-(radius_y * x1p) / radius_x)
+        {
+          cxp: cxp,
+          cyp: cyp,
+          cx: rotation_cos * cxp - rotation_sin * cyp + (from[0] + to[0]) / 2.0,
+          cy: rotation_sin * cxp + rotation_cos * cyp + (from[1] + to[1]) / 2.0
+        }
+      end
+
+      def svg_arc_point(arc, progress)
+        angle = arc[:start_angle] + arc[:delta_angle] * progress
+        cos_rotation = Math.cos(arc[:rotation])
+        sin_rotation = Math.sin(arc[:rotation])
+        x = Math.cos(angle) * arc[:rx]
+        y = Math.sin(angle) * arc[:ry]
+        [
+          arc[:cx] + cos_rotation * x - sin_rotation * y,
+          arc[:cy] + sin_rotation * x + cos_rotation * y
+        ]
+      end
+
+      def svg_arc_segment_count(arc, detail)
+        [((arc[:delta_angle].abs / (Math::PI * 2)) * detail).ceil, 1].max
+      end
+
+      def vector_angle(from, to)
+        cross = from[0] * to[1] - from[1] * to[0]
+        dot = from[0] * to[0] + from[1] * to[1]
+        Math.atan2(cross, dot)
+      end
+
+      def same_point?(from, to)
+        (from[0] - to[0]).abs < 1e-9 && (from[1] - to[1]).abs < 1e-9
+      end
+
+      def arc_flag(value)
+        !Float(value || 0).zero?
+      rescue ArgumentError, TypeError
+        false
       end
 
       def render_mesh_layer(canvas, layer, audio, color, index)
@@ -267,14 +760,115 @@ module Vizcore
       end
 
       def configured_color(params)
-        [params[:color], params["color"]].map { |value| value.to_s.strip }.find { |value| !value.empty? }
+        value = params[:color]
+        value = params["color"] unless value
+        resolved = resolve_color_value(value)
+        return resolved.to_s.strip unless resolved.to_s.strip.empty?
+
+        nil
+      end
+
+      def resolve_color_value(value)
+        return value if value.is_a?(String)
+        return resolve_gradient_color(value) if value.is_a?(Hash)
+
+        value
+      end
+
+      def resolve_gradient_color(value)
+        gradient = value[:gradient] || value["gradient"]
+        return nil unless gradient.is_a?(Hash)
+
+        colors = normalize_colors(gradient[:colors] || gradient["colors"])
+        return nil if colors.empty?
+
+        return colors[0] if colors.length == 1
+
+        position = normalize_position(gradient[:position] || gradient["position"])
+        stops = normalize_gradient_stops(gradient[:stops] || gradient["stops"], colors.length)
+
+        if stops
+          resolve_gradient_color_with_stops(colors, position, stops)
+        else
+          resolve_gradient_color_with_position(colors, position)
+        end
+      end
+
+      def normalize_gradient_stops(stops, color_count)
+        return nil unless stops
+
+        values = Array(stops).filter_map { |entry| Float(entry, exception: false) }
+        return nil if values.length != color_count
+
+        values.sort.map { |value| value.to_f.clamp(0.0, 1.0) }
+      end
+
+      def resolve_gradient_color_with_position(colors, position)
+        segment_length = 1.0 / (colors.length - 1)
+        segment = [(position / segment_length).floor, colors.length - 2].min
+        blend = (position % segment_length) / segment_length
+
+        left_color = parse_hex_color(colors[segment])
+        right_color = parse_hex_color(colors[segment + 1])
+        return colors[segment] if left_color.nil? || right_color.nil?
+
+        interpolate_hex_color(left_color, right_color, blend)
+      end
+
+      def resolve_gradient_color_with_stops(colors, position, stops)
+        index = Array.new(colors.length - 1) { |offset| offset }.index do |offset|
+          position <= stops[offset + 1]
+        end
+
+        return colors.last if index.nil?
+
+        return colors[0] if index == 0 && position <= stops[0]
+
+        left_index = [index, colors.length - 2].min
+        right_index = left_index + 1
+        start = stops[left_index]
+        stop = stops[right_index]
+        blend = ((position - start) / (stop - start)).clamp(0.0, 1.0)
+
+        left_color = parse_hex_color(colors[left_index])
+        right_color = parse_hex_color(colors[right_index])
+        return colors[left_index] if left_color.nil? || right_color.nil?
+
+        interpolate_hex_color(left_color, right_color, blend)
+      end
+
+      def normalize_colors(value)
+        Array(value).map { |entry| entry.to_s.strip }.reject(&:empty?)
+      end
+
+      def normalize_position(value)
+        position = Float(value)
+        position = 0.0 unless position.finite?
+
+        position % 1.0
+      rescue ArgumentError, TypeError
+        0.0
       end
 
       def palette_color(params, index)
         palette = Array(params[:palette] || params["palette"]).map { |color| color.to_s.strip }.reject(&:empty?)
         return nil if palette.empty?
 
-        palette[index % palette.length]
+        position = normalize_palette_position(index, palette.length)
+        return palette[0] if position.nil?
+
+        lower_index = position.floor
+        upper_index = (lower_index + 1) % palette.length
+        blend = position - lower_index
+
+        base_color = palette[lower_index]
+        return base_color unless blend.positive? && blend < 1.0
+
+        lower_rgb = parse_hex_color(base_color)
+        upper_rgb = parse_hex_color(palette[upper_index])
+        return base_color if lower_rgb.nil? || upper_rgb.nil?
+
+        interpolate_hex_color(lower_rgb, upper_rgb, blend)
       end
 
       def parse_hex_color(value)
@@ -286,6 +880,28 @@ module Vizcore
         [hex[0, 2], hex[2, 2], hex[4, 2]].map { |component| component.to_i(16) }
       end
 
+      def normalize_palette_position(value, palette_length)
+        return nil unless palette_length.positive?
+
+        numeric = Float(value)
+        return nil unless numeric.finite?
+
+        position = numeric % palette_length
+        return nil if position.nan?
+
+        position
+      rescue StandardError
+        nil
+      end
+
+      def interpolate_hex_color(left_rgb, right_rgb, blend)
+        blend = blend.to_f.clamp(0.0, 1.0)
+        rgb = left_rgb.zip(right_rgb).map do |left, right|
+          (left + (right - left) * blend).round.clamp(0, 255)
+        end
+        format("##{rgb.map { |value| format('%02x', value) }.join}")
+      end
+
       def default_layer
         { type: "geometry", name: "snapshot" }
       end
@@ -316,11 +932,12 @@ module Vizcore
 
       # Tiny RGBA canvas with alpha blending and a few primitive drawing helpers.
       class Canvas
-        def initialize(width:, height:)
+        def initialize(width:, height:, transparent: false)
           @width = width
           @height = height
           @bytes = String.new(capacity: width * height * 4, encoding: Encoding::BINARY)
-          @bytes << ([0, 0, 0, 255].pack("C4") * (width * height))
+          alpha = transparent ? 0 : 255
+          @bytes << ([0, 0, 0, alpha].pack("C4") * (width * height))
         end
 
         attr_reader :width, :height, :bytes
@@ -426,7 +1043,8 @@ module Vizcore
             current = bytes.getbyte(offset + index)
             bytes.setbyte(offset + index, interpolate(current, color[index], amount).round)
           end
-          bytes.setbyte(offset + 3, 255)
+          alpha = bytes.getbyte(offset + 3)
+          bytes.setbyte(offset + 3, [alpha + (255 - alpha) * amount, 255].min.round)
         end
 
         def set_pixel(x, y, color, alpha)