fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/families2d.py

@@ -0,0 +1,896 @@
+"""Python geometry for cartesian bars, heatmaps, marker plots and polar sectors."""
+
+from __future__ import annotations
+
+from math import cos, floor, isfinite, log10, pi, radians, sin
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any, Mapping
+
+from .defaults import DEFAULT_TRACE_COLORS, get_defaults
+from .error_bars import endpoints, error_domain_values, error_geometry, resolve_error_bars
+from .color_scale import interpolate, legend_ticks, resolve_stops, scale_ratio
+
+
+def resolve_heatmap_wonderplot_color(options, trace, trace_index, family):
+    """Resolve pinned source heatmap/wonderplot color-scale high-color precedence."""
+    scale = (options.get("heatmap") or {}) if family == "heatmap" else ((options.get("wonderplot") or {}).get("colorScale") or {})
+    values = (DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)],
+              (((options.get("style") or {}).get("trace") or {}).get("line") or {}).get("color"),
+              (options.get("lineStyle") or {}).get("color"), scale.get("highColor"),
+              trace.get("color"), (trace.get("lineStyle") or {}).get("color"))
+    return next((value for value in reversed(values) if isinstance(value, str) and value.strip()),
+                DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)])
+
+
+def resolve_bar_line_style(options, trace, default_color):
+    """Resolve source line-style color/width cascade used by bar primitives."""
+    style = (((options.get("style") or {}).get("trace") or {}).get("line") or {})
+    plot_line = options.get("lineStyle") or {}
+    trace_line = trace.get("lineStyle") or {}
+    def text(*values):
+        return next((value for value in reversed(values)
+                     if isinstance(value, str) and value.strip()), default_color)
+    def width(*values):
+        selected = next((value for value in reversed(values)
+                         if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value)),
+                        get_defaults("trace-options")["lineWidth"])
+        return max(0, selected)
+    return (text(style.get("color"), plot_line.get("color"), trace.get("color"), trace_line.get("color")),
+            width(style.get("lineWidth"), plot_line.get("lineWidth"), trace_line.get("lineWidth")))
+from .heatmap_labels import build_cell_labels, resolve_labels
+
+
+def _traces(options: Mapping) -> list[dict]:
+    if options.get("traces"):
+        return list(options["traces"])
+    return [{"data": options["data"]}] if options.get("data") is not None else []
+
+
+def _bounds(width: float, height: float) -> dict:
+    return {"left": 0, "top": 0, "right": width, "bottom": height}
+
+
+def _rgb(value: float, low: float, high: float, low_color: str, high_color: str) -> str:
+    def parse(color):
+        if len(color) == 4 and color.startswith("#"):
+            return [int(color[index] * 2, 16) for index in (1, 2, 3)]
+        if len(color) == 7 and color.startswith("#"):
+            return [int(color[index:index + 2], 16) for index in (1, 3, 5)]
+        return None
+    colors = parse(low_color), parse(high_color)
+    if None in colors:
+        return high_color if value >= high else low_color
+    ratio = max(0, min(1, (value - low) / (high - low))) if high > low else 1
+    channels = [floor(a + (b - a) * ratio + .5) for a, b in zip(*colors)]
+    return f"rgb({channels[0]}, {channels[1]}, {channels[2]})"
+
+
+def _bar_labels(defaults: Mapping, plot_value: Any, trace_value: Any) -> dict:
+    resolved = dict(defaults["valueLabels"])
+    for source in (plot_value, trace_value):
+        if source is None:
+            continue
+        if isinstance(source, bool):
+            resolved["show"] = source
+        elif isinstance(source, Mapping):
+            resolved.update({key: value for key, value in source.items() if value is not None})
+            resolved["show"] = source.get("show", True)
+        else:
+            raise TypeError("bar.valueLabels must be a boolean or an object")
+    if resolved["position"] not in ("center", "inside-end", "outside-end"):
+        raise ValueError("bar.valueLabels.position must be 'center', 'inside-end', or 'outside-end'")
+    return resolved
+
+
+def _bar_value_labels(rects: list[dict], labels: Mapping, orientation: str, mode: str) -> list[dict]:
+    if not labels["show"]:
+        return []
+    output = []
+    for rect in rects:
+        if rect["width"] < labels["minBarWidth"] or rect["height"] < labels["minBarHeight"]:
+            continue
+        position = labels["position"]
+        positive = rect["value"] >= rect["baseline"] if mode == "grouped" else rect.get("normalizedValue", rect["value"]) >= 0
+        inside = position == "inside-end"
+        if position == "center":
+            x, y = rect["x"] + rect["width"] / 2, rect["y"] + rect["height"] / 2
+            align, baseline = "center", "middle"
+        elif orientation == "horizontal":
+            offset = min(labels["offset"], rect["width"] / 2) if inside else labels["offset"]
+            x = rect["x"] + rect["width"] + (-offset if inside else offset) if positive else rect["x"] + (offset if inside else -offset)
+            y = rect["y"] + rect["height"] / 2
+            align, baseline = ("right" if positive == inside else "left"), "middle"
+        else:
+            offset = min(labels["offset"], rect["height"] / 2) if inside else labels["offset"]
+            x = rect["x"] + rect["width"] / 2
+            y = rect["y"] + (offset if inside else -offset) if positive else rect["y"] + rect["height"] + (-offset if inside else offset)
+            align, baseline = "center", ("top" if positive == inside else "bottom")
+        value = rect["value"]
+        text = str(floor(value + .5)) if labels["decimals"] <= 0 else f"{value:.{labels['decimals']}f}"
+        output.append({"x": x, "y": y, "position": position, "textAlign": align,
+                       "textBaseline": baseline, "value": value,
+                       "text": f"{labels['prefix']}{text}{labels['suffix']}",
+                       "color": labels["color"], "font": labels["font"],
+                       "sourceIndex": rect["sourceIndex"]})
+    return output
+
+
+def bar_scene(options: Mapping, width: float, height: float,
+              forced_slots=None, forced_value_domain=None, forced_slot_domain=None,
+              forced_slot_scale="linear", forced_slot_categorical=False,
+              forced_value_domain_scaled=False) -> dict:
+    defaults = get_defaults("bar")
+    bar = options.get("bar") or {}
+    mode = bar.get("mode", defaults["mode"])
+    if mode not in ("grouped", "stacked", "normalized"):
+        raise ValueError("bar.mode must be 'grouped', 'stacked', or 'normalized'")
+    orientation = bar.get("orientation", defaults["orientation"])
+    if orientation not in ("vertical", "horizontal"):
+        raise ValueError("bar.orientation must be 'vertical' or 'horizontal'")
+    traces = _traces(options)
+    visible = [(index, trace) for index, trace in enumerate(traces) if trace.get("visible") is not False]
+    slots = (list(forced_slots) if forced_slots is not None else
+             sorted({point["x" if orientation == "vertical" else "y"]
+                     for _, trace in visible for point in trace.get("data", [])
+                     if point.get("x") is not None and point.get("y") is not None}))
+    if not slots:
+        return {"width": width, "height": height, "primitives": []}
+    slot_axis = width if orientation == "vertical" else height
+    value_axis = height if orientation == "vertical" else width
+    if forced_slot_domain is None:
+        slot_width = slot_axis / len(slots)
+    else:
+        def transformed_slot(value):
+            return log10(value) if forced_slot_scale == "logarithmic" else value
+
+        span = max(forced_slot_domain[1] - forced_slot_domain[0], 2.220446049250313e-16)
+        transformed_slots = sorted(set(transformed_slot(value) for value in slots))
+        deltas = [right - left for left, right in zip(transformed_slots, transformed_slots[1:])
+                  if right > left]
+        slot_width = ((1 / span * slot_axis) if forced_slot_categorical else
+                      (min(deltas) / span * slot_axis) if deltas else slot_axis)
+    ratio = bar.get("barWidthRatio", defaults["barWidthRatio"])
+    group_width = slot_width * ratio
+    values = [float(point["y" if orientation == "vertical" else "x"]) for _, trace in visible for point in trace.get("data", []) if point.get("x") is not None and point.get("y") is not None]
+    if mode == "grouped":
+        values.extend(float(point.get("base") or 0) for _, trace in visible for point in trace.get("data", []) if point.get("x") is not None and point.get("y") is not None)
+    slot_dimension = "x" if orientation == "vertical" else "y"
+    value_dimension = "y" if orientation == "vertical" else "x"
+    x_axis = ((options.get("axes") or {}).get("xAxes") or {}).get("x") or {}
+    y_axis = ((options.get("axes") or {}).get("yAxes") or {}).get("y") or {}
+    for _, trace in visible:
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), "")
+        if not resolved["show"]:
+            continue
+        for source_index, point in enumerate(trace.get("data", [])):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            if resolved[slot_dimension] and point.get(slot_dimension + "Error") is not None:
+                raise ValueError(f"{slot_dimension}Error is not supported on the slot axis of {orientation} bar charts")
+            if resolved[value_dimension] and point.get(value_dimension + "Error") is not None:
+                if mode != "grouped":
+                    raise ValueError("errorBars are supported only for grouped bar charts")
+                values.extend(endpoints(point, value_dimension, y_axis if orientation == "vertical" else x_axis, source_index))
+    totals = {slot: {"positive": 0.0, "negative": 0.0} for slot in slots}
+    for _, trace in visible:
+        for point in trace.get("data", []):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            slot = point["x" if orientation == "vertical" else "y"]
+            value = float(point["y" if orientation == "vertical" else "x"])
+            totals[slot]["positive" if value >= 0 else "negative"] += value
+    if mode == "grouped":
+        low, high = min(values), max(values)
+    elif mode == "normalized":
+        low = -100.0 if any(total["negative"] < 0 for total in totals.values()) else 0.0
+        high = 100.0 if any(total["positive"] > 0 for total in totals.values()) else 0.0
+    else:
+        low = min(0.0, *(total["negative"] for total in totals.values()))
+        high = max(0.0, *(total["positive"] for total in totals.values()))
+    value_axis_option = (options.get("axes") or {}).get("yAxes" if orientation == "vertical" else "xAxes") or {}
+    value_axis_settings = value_axis_option.get("y" if orientation == "vertical" else "x") or {}
+    explicit_range = value_axis_settings.get("range")
+    if explicit_range:
+        low, high = float(explicit_range["min"]), float(explicit_range["max"])
+    if forced_value_domain is not None:
+        low, high = forced_value_domain
+    if high == low:
+        high = low + 1
+    scale = value_axis_settings.get("scale", "linear")
+    if mode != "grouped" and scale != "linear":
+        raise ValueError(f"Bar mode '{mode}' requires a linear value axis")
+    if scale not in ("linear", "datetime", "logarithmic"):
+        raise ValueError(f"Unknown axis scale: {scale}")
+    def scaled(value):
+        if scale == "logarithmic":
+            if value <= 0:
+                raise ValueError("Logarithmic scale requires values > 0")
+            return log10(value)
+        return value
+    if not forced_value_domain_scaled:
+        low, high = scaled(low), scaled(high)
+    running = {slot: {"positive": 0.0, "negative": 0.0} for slot in slots}
+    primitives = []
+    for index, trace in visible:
+        color, line_width = resolve_bar_line_style(options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])
+        trace_bar = trace.get("bar") or {}
+        border_width = trace_bar.get("borderWidth", bar.get("borderWidth", defaults["borderWidth"]))
+        border_color = trace_bar.get("borderColor", bar.get("borderColor", defaults["borderColor"]))
+        corner_radius = trace_bar.get("cornerRadius", bar.get("cornerRadius", defaults["cornerRadius"]))
+        labels = _bar_labels(defaults, bar.get("valueLabels"), trace_bar.get("valueLabels"))
+        points, rects, anchors = [], [], {}
+        for source_index, point in enumerate(trace.get("data", [])):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            slot_value = point["x" if orientation == "vertical" else "y"]
+            value = float(point["y" if orientation == "vertical" else "x"])
+            if mode != "grouped" and point.get("base") is not None:
+                raise ValueError("Bar point base is only supported in grouped mode")
+            if scale != "linear" and point.get("base") is None:
+                raise ValueError(f"Grouped bars on a {scale} value axis require an explicit point base")
+            baseline = float(point.get("base") or 0)
+            normalized_value = None
+            rendered = value
+            if mode == "normalized":
+                total = totals[slot_value]["positive" if value >= 0 else "negative"]
+                normalized_value = value / abs(total) * 100 if total else 0.0
+                rendered = normalized_value
+            if mode != "grouped":
+                side = "positive" if rendered >= 0 else "negative"
+                baseline = running[slot_value][side]
+                running[slot_value][side] += rendered
+                end = running[slot_value][side]
+            else:
+                end = value
+            slot_center = ((slots.index(slot_value) + .5) * slot_width
+                           if forced_slot_domain is None else
+                           (transformed_slot(slot_value) - forced_slot_domain[0]) /
+                           max(forced_slot_domain[1] - forced_slot_domain[0],
+                               2.220446049250313e-16) * slot_axis)
+            if orientation == "horizontal":
+                slot_center = height - slot_center
+            group_count = len(visible) if mode == "grouped" else 1
+            rect_width = max(defaults["minBarWidth"], group_width / group_count)
+            group_index = [number for number, _ in visible].index(index) if mode == "grouped" else 0
+            slot_start = slot_center - group_width / 2 + group_index * rect_width
+            if orientation == "vertical":
+                end_pixel = value_axis - ((scaled(end) - low) / (high - low)) * value_axis
+                baseline_pixel = value_axis - ((scaled(baseline) - low) / (high - low)) * value_axis
+                rect = {"x": slot_start, "y": min(end_pixel, baseline_pixel), "width": rect_width,
+                        "height": abs(end_pixel - baseline_pixel), "value": value, "baseline": baseline, "sourceIndex": source_index}
+            else:
+                end_pixel = (scaled(end) - low) / (high - low) * value_axis
+                baseline_pixel = (scaled(baseline) - low) / (high - low) * value_axis
+                rect = {"x": min(end_pixel, baseline_pixel), "y": slot_start, "width": abs(end_pixel - baseline_pixel),
+                        "height": rect_width, "value": value, "baseline": baseline, "sourceIndex": source_index}
+            if normalized_value is not None:
+                rect["normalizedValue"] = normalized_value
+            left, right = max(0, rect["x"]), min(width, rect["x"] + rect["width"])
+            top, bottom = max(0, rect["y"]), min(height, rect["y"] + rect["height"])
+            if right <= left or bottom <= top:
+                continue
+            rect.update({"x": left, "y": top, "width": right - left, "height": bottom - top})
+            radius = min(corner_radius, rect["width"] / 2, rect["height"] / 2)
+            if radius > 0:
+                rect["cornerRadius"] = radius
+            if orientation == "vertical":
+                points.append({"x": rect["x"] + rect["width"] / 2,
+                               "y": rect["y"] if end >= baseline else rect["y"] + rect["height"]})
+            else:
+                points.append({"x": rect["x"] + rect["width"] if end >= baseline else rect["x"],
+                               "y": rect["y"] + rect["height"] / 2})
+            if forced_slot_domain is not None:
+                anchors[source_index] = ({"x": slot_center, "y": points[-1]["y"]}
+                                         if orientation == "vertical" else
+                                         {"x": points[-1]["x"], "y": slot_center})
+            else:
+                anchors[source_index] = points[-1]
+            rects.append(rect)
+        if not rects:
+            continue
+        primitive = {"type": "bar", "points": points, "bars": rects, "color": color,
+                           "lineWidth": line_width,
+                           "borderColor": border_color, "borderWidth": border_width,
+                           "subplot": "main", "bounds": _bounds(width, height), "traceIndex": index}
+        label_items = _bar_value_labels(rects, labels, orientation, mode)
+        if label_items:
+            primitive["barValueLabels"] = label_items
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), color)
+        value_only = {**resolved, "x": orientation == "horizontal" and resolved["x"],
+                      "y": orientation == "vertical" and resolved["y"]}
+        bars = error_geometry(trace, value_only, x_axis, y_axis,
+                              (low, high) if orientation == "horizontal" else (0, width),
+                              (low, high) if orientation == "vertical" else (0, height),
+                              width, height, anchors)
+        if bars:
+            primitive["errorBars"] = bars
+            primitive["errorBarStyle"] = resolved["style"]
+        primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def heatmap_scene(options: Mapping, width: float, height: float) -> dict:
+    defaults = get_defaults("heatmap")
+    heatmap = options.get("heatmap") or {}
+    traces = _traces(options)
+    scale = heatmap.get("valueScale", defaults["valueScale"])
+    if scale not in ("linear", "logarithmic"):
+        raise ValueError("heatmap.valueScale must be 'linear' or 'logarithmic'")
+
+    def categories(axis):
+        name = f"{axis}Categories"
+        supplied = name in heatmap
+        values = heatmap.get(name) if supplied else defaults[name]
+        if supplied and not values:
+            raise ValueError(f"heatmap.{name} must contain at least one category when provided")
+        if not values:
+            return None
+        if any(not isinstance(value, str) or not value.strip() for value in values):
+            raise ValueError(f"heatmap.{name} must contain only non-empty strings")
+        if len(set(values)) != len(values):
+            raise ValueError(f"heatmap.{name} must not contain duplicate categories")
+        return list(values)
+
+    x_categories, y_categories = categories("x"), categories("y")
+
+    def coordinate(value, axis, category_values):
+        if category_values is None:
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                raise ValueError(f"{axis} must be a finite number")
+            return value
+        name = f"heatmap.{axis}Categories"
+        if not isinstance(value, str):
+            raise ValueError(f"{name} requires string data coordinates")
+        if value not in category_values:
+            raise ValueError(f"{name} does not contain data category '{value}'")
+        return category_values.index(value)
+
+    points_by_trace = []
+    xs = set(range(len(x_categories))) if x_categories else set()
+    ys = set(range(len(y_categories))) if y_categories else set()
+    values = []
+    for trace in traces:
+        normalized = []
+        if trace.get("visible") is not False:
+            for source_index, point in enumerate(trace.get("data", [])):
+                if point.get("x") is None or point.get("y") is None:
+                    continue
+                value = point.get("value") if point.get("value") is not None else point.get("z")
+                if value is None:
+                    raise ValueError("Heatmap points require a numeric 'value' or 'z' field")
+                if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                    raise ValueError("Heatmap points require a numeric 'value' or 'z' field")
+                if scale == "logarithmic" and value <= 0:
+                    raise ValueError("Heatmap logarithmic valueScale requires value/z > 0")
+                x = coordinate(point["x"], "x", x_categories)
+                y = coordinate(point["y"], "y", y_categories)
+                normalized.append((source_index, x, y, value))
+                xs.add(x)
+                ys.add(y)
+                values.append(value)
+        points_by_trace.append(normalized)
+    if not values:
+        return {"width": width, "height": height, "primitives": []}
+    xs, ys = sorted(xs), sorted(ys)
+    for name in ("minValue", "maxValue"):
+        bound = heatmap.get(name)
+        if scale == "logarithmic" and name in heatmap and (isinstance(bound, bool) or not isinstance(bound, (int, float)) or not isfinite(bound) or bound <= 0):
+            raise ValueError(f"Heatmap logarithmic {name} must be finite and > 0")
+    low = heatmap.get("minValue") if isinstance(heatmap.get("minValue"), (int, float)) and isfinite(heatmap["minValue"]) else min(values)
+    high = heatmap.get("maxValue") if isinstance(heatmap.get("maxValue"), (int, float)) and isfinite(heatmap["maxValue"]) else max(values)
+    if low > high:
+        raise ValueError("Heatmap minValue must be <= maxValue")
+    cell_width, cell_height = width / len(xs), height / len(ys)
+    def grid_overlay():
+        def label_options(axis):
+            raw = heatmap.get(f"{axis}Labels")
+            default = defaults["labels"]
+            value = {**default}
+            if isinstance(raw, bool):
+                value["show"] = raw
+            elif isinstance(raw, list):
+                value["show"] = True
+                value["labels"] = [item for item in raw if isinstance(item, str)]
+            elif isinstance(raw, Mapping):
+                value.update(raw)
+                value["show"] = raw.get("show", True)
+            return value
+
+        x_label, y_label = label_options("x"), label_options("y")
+        guide = {**defaults["guides"]}
+        raw_guide = heatmap.get("guides")
+        if isinstance(raw_guide, bool):
+            guide["show"] = raw_guide
+        elif isinstance(raw_guide, Mapping):
+            guide.update(raw_guide)
+            guide["show"] = raw_guide.get("show", True)
+        if not (x_label["show"] or y_label["show"] or guide["show"] and guide["lineWidth"] > 0):
+            return None
+        overlay = {"xLabels": [], "yLabels": [], "guides": [],
+                   "guideColor": guide["color"], "guideLineWidth": guide["lineWidth"]}
+        if guide["show"] and guide["lineWidth"] > 0:
+            for index in range(len(xs) + 1):
+                x = index * cell_width
+                overlay["guides"].append({"axis": "x", "x1": x, "y1": 0, "x2": x, "y2": height, "index": index})
+            for index in range(len(ys) + 1):
+                y = index * cell_height
+                overlay["guides"].append({"axis": "y", "x1": 0, "y1": y, "x2": width, "y2": y, "index": index})
+        def axis_text(value, index, config, category_values):
+            labels = config.get("labels")
+            if isinstance(labels, list) and index < len(labels):
+                return labels[index]
+            if category_values:
+                return category_values[index]
+            return str(round(value, 6)).removesuffix(".0")
+        if x_label["show"]:
+            for index, value in enumerate(xs):
+                overlay["xLabels"].append({"axis": "x", "x": (index + .5) * cell_width,
+                                            "y": height + x_label["offset"], "value": value,
+                                            "index": index, "text": axis_text(value, index, x_label, x_categories),
+                                            "color": x_label["color"], "font": x_label["font"]})
+        if y_label["show"]:
+            for index, value in enumerate(ys):
+                overlay["yLabels"].append({"axis": "y", "x": -y_label["offset"],
+                                            "y": height - (index + .5) * cell_height, "value": value,
+                                            "index": index, "text": axis_text(value, index, y_label, y_categories),
+                                            "color": y_label["color"], "font": y_label["font"]})
+        return overlay
+
+    def color_legend(stops):
+        raw = heatmap.get("colorScaleLegend")
+        config = raw if isinstance(raw, Mapping) else {}
+        show = raw if isinstance(raw, bool) else config.get("show", True) if isinstance(raw, Mapping) else defaults["colorScaleLegend"]["show"]
+        if not show:
+            return None
+        base = defaults["colorScaleLegend"]
+        position = config.get("position", base["position"])
+        if position not in ("top", "bottom", "left", "right"):
+            position = base["position"]
+        horizontal = position in ("top", "bottom")
+        title = config.get("title", base["title"])
+        title = title.strip() if isinstance(title, str) and title.strip() else None
+        legend_width = config.get("width", base["height"] if horizontal else base["width"])
+        legend_height = config.get("height", base["width"] if horizontal else base["height"])
+        offset = config.get("offset", base["offset"])
+        tick_size = config.get("tickSize", base["tickSize"])
+        label_gap = config.get("labelGap", base["labelGap"])
+        line_height = config.get("lineHeight", base["lineHeight"])
+        title_gap = config.get("titleGap", base["titleGap"])
+        tick_count = max(2, min(8, round(config.get("tickCount", base["tickCount"]))))
+        specified = sorted({value for value in config.get("tickValues", base["tickValues"])
+                            if isinstance(value, (int, float)) and isfinite(value)})
+        if scale == "logarithmic" and any(value <= 0 for value in specified):
+            raise ValueError("heatmap.colorScaleLegend.tickValues must contain only finite values > 0 for logarithmic scales")
+        ticks = legend_ticks(low, high, tick_count, specified, scale)
+        decimals = max(0, min(6, round(config.get("decimals", base["decimals"]))))
+        prefix = config.get("labelPrefix", base["labelPrefix"])
+        suffix = config.get("labelSuffix", base["labelSuffix"])
+        def tick_text(value):
+            return f"{prefix}{value:.{decimals}f}{suffix}"
+        common = {"valueScale": scale, "position": position, "minValue": low, "maxValue": high,
+                  "lowColor": stops[0]["color"], "highColor": stops[-1]["color"], "colorStops": stops,
+                  "ticks": [], "tickSize": tick_size, "labelGap": label_gap,
+                  "labelPrefix": prefix, "labelSuffix": suffix,
+                  "color": config.get("color", base["color"]), "font": config.get("font", base["font"]),
+                  "lineHeight": line_height, "titleGap": title_gap,
+                  "borderColor": config.get("borderColor", base["borderColor"]),
+                  "borderWidth": config.get("borderWidth", base["borderWidth"])}
+        if title is not None:
+            common["title"] = title
+        title_block = line_height + title_gap if title is not None else 0
+        if horizontal:
+            legend_width = min(legend_width, max(1, width))
+            x = max(0, (width - legend_width) / 2)
+            total_height = title_block + legend_height + tick_size + label_gap + line_height
+            top = -(offset + total_height) if position == "top" else height + offset
+            y = top + title_block
+            for index, value in enumerate(ticks):
+                ratio = scale_ratio(value, low, high, scale) if low != high else index / (len(ticks) - 1)
+                common["ticks"].append({"value": value, "text": tick_text(value), "x": x + ratio * legend_width,
+                                        "y": y + legend_height})
+            common.update({"x": x, "y": y, "width": legend_width, "height": legend_height})
+        else:
+            legend_height = min(legend_height, max(1, height - title_block))
+            y = max(0, (height - legend_height - title_block) / 2) + title_block
+            x = -(offset + legend_width) if position == "left" else width + offset
+            for index, value in enumerate(ticks):
+                ratio = scale_ratio(value, low, high, scale) if low != high else index / (len(ticks) - 1)
+                common["ticks"].append({"value": value, "text": tick_text(value),
+                                        "y": y + legend_height - ratio * legend_height})
+            common.update({"x": x, "y": y, "width": legend_width, "height": legend_height})
+        return common
+
+    primitives = []
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        color = resolve_heatmap_wonderplot_color(options, trace, trace_index, "heatmap")
+        low_color = heatmap.get("lowColor") or defaults["lowColor"]
+        stops = resolve_stops(heatmap.get("colorStops"), low_color, color, "heatmap.colorStops")
+        trace_options = trace.get("heatmap") or {}
+        def nonnegative(value, fallback):
+            return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value >= 0 else fallback
+        plot_gap = nonnegative(heatmap.get("cellGap"), defaults["cellGap"])
+        plot_border = nonnegative(heatmap.get("borderWidth"), defaults["borderWidth"])
+        plot_radius = nonnegative(heatmap.get("cornerRadius"), defaults["cornerRadius"])
+        gap = min(nonnegative(trace_options.get("cellGap"), plot_gap), cell_width, cell_height)
+        border_width = nonnegative(trace_options.get("borderWidth"), plot_border)
+        border_color = trace_options.get("borderColor", heatmap.get("borderColor", defaults["borderColor"]))
+        corner_radius = nonnegative(trace_options.get("cornerRadius"), plot_radius)
+        points, cells = [], []
+        occupied = set()
+
+        def geometry(column, row):
+            left, right = width * column / len(xs), width * (column + 1) / len(xs)
+            reverse_row = len(ys) - row - 1
+            top, bottom = height * reverse_row / len(ys), height * (reverse_row + 1) / len(ys)
+            item = {"x": left + gap / 2, "y": top + gap / 2,
+                    "width": max(0, right - left - gap), "height": max(0, bottom - top - gap),
+                    "row": row, "column": column}
+            radius = min(corner_radius, item["width"] / 2, item["height"] / 2)
+            if radius > 0:
+                item["cornerRadius"] = radius
+            return item
+
+        for source_index, x_value, y_value, value in points_by_trace[trace_index]:
+            column, row = xs.index(x_value), ys.index(y_value)
+            cell = {**geometry(column, row), "value": value, "xValue": x_value,
+                    "yValue": y_value, "sourceIndex": source_index,
+                    "fillColor": interpolate(value, low, high, stops, scale)}
+            if x_categories:
+                cell["xCategory"] = x_categories[x_value]
+            if y_categories:
+                cell["yCategory"] = y_categories[y_value]
+            cells.append(cell)
+            occupied.add((x_value, y_value))
+        missing = dict(defaults["missingCells"])
+        for source in (heatmap.get("missingCells"), trace_options.get("missingCells")):
+            if isinstance(source, bool):
+                missing["show"] = source
+            elif isinstance(source, Mapping):
+                missing.update(source)
+                missing["show"] = source.get("show", True)
+        if cells and missing["show"]:
+            for row, y_value in enumerate(ys):
+                for column, x_value in enumerate(xs):
+                    if (x_value, y_value) in occupied:
+                        continue
+                    cell = {**geometry(column, row), "value": float("nan"), "xValue": x_value,
+                            "yValue": y_value, "fillColor": missing["fillColor"], "missing": True,
+                            "borderColor": missing["borderColor"], "borderWidth": missing["borderWidth"]}
+                    if x_categories:
+                        cell["xCategory"] = x_categories[column]
+                    if y_categories:
+                        cell["yCategory"] = y_categories[row]
+                    cells.append(cell)
+        points = [{"x": cell["x"] + cell["width"] / 2,
+                   "y": cell["y"] + cell["height"] / 2} for cell in cells]
+        if cells:
+            primitive = {"type": "heatmap", "points": points, "heatmapCells": cells,
+                               "color": color, "lineWidth": 0, "borderColor": border_color,
+                               "borderWidth": border_width, "subplot": "main", "bounds": _bounds(width, height),
+                               "traceIndex": trace_index}
+            label_items = build_cell_labels(cells, resolve_labels(heatmap.get("cellLabels"), trace_options.get("cellLabels")), border_width)
+            if label_items is not None:
+                primitive["heatmapCellLabels"] = label_items
+            if not primitives:
+                overlay = grid_overlay()
+                if overlay is not None:
+                    primitive["heatmapGrid"] = overlay
+                legend = color_legend(stops)
+                if legend is not None:
+                    primitive["heatmapColorScaleLegend"] = legend
+            primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def _wonder_scale(options: Mapping, traces: list[dict], defaults: Mapping, kind: str) -> dict | None:
+    raw = options.get(kind)
+    config = raw if isinstance(raw, Mapping) else {}
+    enabled = raw if isinstance(raw, bool) else config.get("enabled", True) if isinstance(raw, Mapping) else defaults[kind]["enabled"]
+    if not enabled:
+        return None
+    if kind == "sizeScale":
+        lower_name, upper_name = "minSize", "maxSize"
+        lower = config.get(lower_name, defaults[kind][lower_name])
+        upper = config.get(upper_name, defaults[kind][upper_name])
+        if not isinstance(lower, (int, float)) or not isfinite(lower) or lower < get_defaults("markers")["minSize"]:
+            raise ValueError(f"wonderplot.sizeScale.minSize must be >= {get_defaults('markers')['minSize']}")
+        if not isinstance(upper, (int, float)) or not isfinite(upper) or upper < lower:
+            raise ValueError("wonderplot.sizeScale.maxSize must be >= minSize")
+        field, message = "size", "Wonderplot sizeScale points require a finite numeric 'size' field"
+    else:
+        lower_name, upper_name = "minOpacity", "maxOpacity"
+        lower = config.get(lower_name, defaults[kind][lower_name])
+        upper = config.get(upper_name, defaults[kind][upper_name])
+        if not isinstance(lower, (int, float)) or not isfinite(lower):
+            raise ValueError("wonderplot.opacityScale.minOpacity must be finite")
+        if not isinstance(upper, (int, float)) or not isfinite(upper):
+            raise ValueError("wonderplot.opacityScale.maxOpacity must be finite")
+        lower, upper = max(0, min(1, lower)), max(0, min(1, upper))
+        if upper < lower:
+            raise ValueError("wonderplot.opacityScale.maxOpacity must be >= minOpacity")
+        field, message = "opacity", "Wonderplot opacityScale points require a finite numeric 'opacity' field"
+    values = []
+    for trace in traces:
+        if trace.get("visible") is False:
+            continue
+        for point in trace.get("data", []):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            value = point.get(field)
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                raise ValueError(message)
+            values.append(value)
+    if not values:
+        return None
+    minimum = config.get("minValue") if config.get("minValue") is not None else min(values)
+    maximum = config.get("maxValue") if config.get("maxValue") is not None else max(values)
+    for name, value in (("minValue", minimum), ("maxValue", maximum)):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+            raise ValueError(f"wonderplot.{kind}.{name} must be finite")
+    if minimum > maximum:
+        raise ValueError(f"wonderplot.{kind}.minValue must be <= maxValue")
+    return {"min": minimum, "max": maximum, "low": lower, "high": upper, "field": field}
+
+
+def _wonder_scaled_value(value: float, scale: Mapping) -> float:
+    if scale["min"] == scale["max"]:
+        return (scale["low"] + scale["high"]) / 2
+    ratio = max(0, min(1, (value - scale["min"]) / (scale["max"] - scale["min"])))
+    return scale["low"] + (scale["high"] - scale["low"]) * ratio
+
+
+def _wonder_labels(markers: list[dict], defaults: Mapping, plot_input, trace_input) -> list[dict] | None:
+    resolved = dict(defaults["markerLabels"])
+    for source in (plot_input, trace_input):
+        if source is None:
+            continue
+        if isinstance(source, bool):
+            resolved["show"] = source
+        elif isinstance(source, Mapping):
+            resolved.update({key: value for key, value in source.items() if value is not None and key != "formatter"})
+            resolved["show"] = source.get("show", True)
+    if not resolved["show"]:
+        return None
+    decimals = resolved["decimals"]
+    if not isinstance(decimals, (int, float)) or not isfinite(decimals):
+        decimals = defaults["markerLabels"]["decimals"]
+    decimals = max(0, min(6, floor(decimals + .5)))
+    result = []
+    for marker in markers:
+        value = marker["value"]
+        if decimals == 0:
+            number = str(floor(value + .5))
+        else:
+            number = format(Decimal(str(value)).quantize(Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP), f".{decimals}f")
+        result.append({"x": marker["x"], "y": marker["y"] - marker["size"] - resolved["offsetY"],
+                       "value": value, "sourceIndex": marker["sourceIndex"],
+                       "text": f"{resolved['prefix']}{number}{resolved['suffix']}",
+                       "color": resolved["color"], "font": resolved["font"],
+                       "lineHeight": resolved["lineHeight"], "collisionPadding": resolved["collisionPadding"]})
+    return result or None
+
+
+def _wonder_legend(raw, defaults: Mapping, stops: list[dict], low: float, high: float,
+                   value_scale: str, width: float, height: float) -> dict | None:
+    source = raw if isinstance(raw, Mapping) else {}
+    show = raw if isinstance(raw, bool) else source.get("show", True) if isinstance(raw, Mapping) else defaults["colorScaleLegend"]["show"]
+    if not show:
+        return None
+    settings = {**defaults["colorScaleLegend"], **{key: value for key, value in source.items() if value is not None}}
+    position = settings["position"] if settings["position"] in ("left", "right", "top", "bottom") else defaults["colorScaleLegend"]["position"]
+    horizontal = position in ("top", "bottom")
+    def nonnegative(name):
+        value = settings[name]
+        return value if isinstance(value, (int, float)) and isfinite(value) and value >= 0 else defaults["colorScaleLegend"][name]
+    def positive(name, fallback):
+        value = settings[name]
+        return value if isinstance(value, (int, float)) and isfinite(value) and value > 0 else fallback
+    legend_width = positive("width", defaults["colorScaleLegend"]["height"] if horizontal else defaults["colorScaleLegend"]["width"])
+    legend_height = positive("height", defaults["colorScaleLegend"]["width"] if horizontal else defaults["colorScaleLegend"]["height"])
+    title = settings["title"].strip() if isinstance(settings["title"], str) and settings["title"].strip() else None
+    count = settings["tickCount"]
+    if not isinstance(count, (int, float)) or not isfinite(count):
+        count = defaults["colorScaleLegend"]["tickCount"]
+    count = max(2, min(8, floor(count + .5)))
+    decimals = settings["decimals"]
+    if not isinstance(decimals, (int, float)) or not isfinite(decimals):
+        decimals = defaults["colorScaleLegend"]["decimals"]
+    decimals = max(0, min(6, floor(decimals + .5)))
+    explicit = settings["tickValues"] if isinstance(settings["tickValues"], list) else []
+    if value_scale == "logarithmic" and any(isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value) or value <= 0 for value in explicit):
+        raise ValueError("wonderplot.colorScaleLegend.tickValues must contain only finite values > 0 for logarithmic scales")
+    explicit = sorted({value for value in explicit if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value)})
+    tick_values = legend_ticks(low, high, count, explicit, value_scale)
+    line_height = positive("lineHeight", defaults["colorScaleLegend"]["lineHeight"])
+    title_gap = nonnegative("titleGap")
+    title_block = line_height + title_gap if title else 0
+    if horizontal:
+        legend_width = min(legend_width, max(1, width))
+        x = max(0, (width - legend_width) / 2)
+        total_height = title_block + legend_height + nonnegative("tickSize") + nonnegative("labelGap") + line_height
+        group_top = -(nonnegative("offset") + total_height) if position == "top" else height + nonnegative("offset")
+        y = group_top + title_block
+    else:
+        available = max(1, height - title_block)
+        legend_height = min(legend_height, available)
+        y = max(0, (height - legend_height - title_block) / 2) + title_block
+        x = -(nonnegative("offset") + legend_width) if position == "left" else width + nonnegative("offset")
+    ticks = []
+    for index, value in enumerate(tick_values):
+        ratio = index / (len(tick_values) - 1) if low == high and len(tick_values) > 1 else scale_ratio(value, low, high, value_scale)
+        number = str(floor(value + .5)) if decimals == 0 else format(Decimal(str(value)).quantize(Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP), f".{decimals}f")
+        tick = {"value": value, "text": f"{settings['labelPrefix']}{number}{settings['labelSuffix']}"}
+        if horizontal:
+            tick.update({"x": x + ratio * legend_width, "y": y + legend_height})
+        else:
+            tick["y"] = y + legend_height - ratio * legend_height
+        ticks.append(tick)
+    legend = {"valueScale": value_scale, "position": position, "x": x, "y": y,
+            "width": legend_width, "height": legend_height, "minValue": low, "maxValue": high,
+            "lowColor": stops[0]["color"], "highColor": stops[-1]["color"], "colorStops": stops,
+            "title": title, "ticks": ticks, "tickSize": nonnegative("tickSize"),
+            "labelGap": nonnegative("labelGap"), "labelPrefix": settings["labelPrefix"],
+            "labelSuffix": settings["labelSuffix"], "color": settings["color"],
+            "font": settings["font"], "lineHeight": line_height, "titleGap": title_gap,
+            "borderColor": settings["borderColor"], "borderWidth": nonnegative("borderWidth")}
+    if title is None:
+        legend.pop("title")
+    return legend
+
+
+def wonderplot_scene(options: Mapping, width: float, height: float) -> dict:
+    defaults = get_defaults("wonderplot")
+    wonderplot = options.get("wonderplot") or {}
+    traces = _traces(options)
+    size_scale = _wonder_scale(wonderplot, traces, defaults, "sizeScale")
+    opacity_scale = _wonder_scale(wonderplot, traces, defaults, "opacityScale")
+    all_data = [point for trace in traces if trace.get("visible") is not False for point in trace.get("data", []) if point.get("x") is not None and point.get("y") is not None]
+    if not all_data:
+        return {"width": width, "height": height, "primitives": []}
+    color_config = wonderplot.get("colorScale") or {}
+    value_scale = color_config.get("valueScale", defaults["valueScale"])
+    if value_scale not in ("linear", "logarithmic"):
+        raise ValueError("wonderplot.colorScale.valueScale must be 'linear' or 'logarithmic'")
+    color_values = []
+    for point in all_data:
+        value = point.get("value", point.get("z"))
+        if value is None:
+            raise ValueError("Wonderplot points require a numeric 'value' or 'z' field for color-scale markers")
+        value = float(value)
+        if value_scale == "logarithmic" and value <= 0:
+            raise ValueError("Wonderplot logarithmic colorScale requires value/z > 0")
+        color_values.append(value)
+    for bound in ("minValue", "maxValue"):
+        configured = color_config.get(bound)
+        if value_scale == "logarithmic" and configured is not None and (isinstance(configured, bool) or not isinstance(configured, (int, float)) or not isfinite(configured) or configured <= 0):
+            raise ValueError(f"Wonderplot logarithmic colorScale.{bound} must be finite and > 0")
+    color_low = color_config.get("minValue") if isinstance(color_config.get("minValue"), (int, float)) and isfinite(color_config["minValue"]) else min(color_values)
+    color_high = color_config.get("maxValue") if isinstance(color_config.get("maxValue"), (int, float)) and isfinite(color_config["maxValue"]) else max(color_values)
+    if color_low > color_high:
+        raise ValueError("Wonderplot colorScale minValue must be <= maxValue")
+    xs = [float(point["x"]) for point in all_data]
+    ys = [float(point["y"]) for point in all_data]
+    values = [float(point.get("value", point.get("z"))) for point in all_data if point.get("value", point.get("z")) is not None]
+    xmin, xmax, ymin, ymax = min(xs), max(xs), min(ys), max(ys)
+    x_axis = ((options.get("axes") or {}).get("xAxes") or {}).get("x") or {}
+    y_axis = ((options.get("axes") or {}).get("yAxes") or {}).get("y") or {}
+    for trace in traces:
+        if trace.get("visible") is False:
+            continue
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), "")
+        error_x, error_y = error_domain_values(trace, resolved, x_axis, y_axis)
+        xs.extend(error_x)
+        ys.extend(error_y)
+    if xs and not x_axis.get("range"):
+        xmin, xmax = min(xs), max(xs)
+    if ys and not y_axis.get("range"):
+        ymin, ymax = min(ys), max(ys)
+    if x_axis.get("range"):
+        xmin, xmax = float(x_axis["range"]["min"]), float(x_axis["range"]["max"])
+    if y_axis.get("range"):
+        ymin, ymax = float(y_axis["range"]["min"]), float(y_axis["range"]["max"])
+    low, high = color_low, color_high
+    primitives = []
+    legend_used = False
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        trace_options = trace.get("wonderplot") or {}
+        color = resolve_heatmap_wonderplot_color(options, trace, trace_index, "wonderplot")
+        low_color = color_config.get("lowColor") or defaults["lowColor"]
+        stops = resolve_stops(color_config.get("colorStops"), low_color, color, "wonderplot.colorScale.colorStops")
+        points, markers = [], []
+        for source_index, point in enumerate(trace.get("data", [])):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            x = (float(point["x"]) - xmin) / max(xmax - xmin, 2.220446049250313e-16) * width
+            y = height - ((float(point["y"]) - ymin) / max(ymax - ymin, 2.220446049250313e-16)) * height
+            if x < 0 or x > width or y < 0 or y > height:
+                continue
+            value = point.get("value", point.get("z"))
+            if value is None:
+                raise ValueError("Wonderplot points require a numeric 'value' or 'z' field for color-scale markers")
+            fixed_opacity = trace_options.get("markerOpacity", wonderplot.get("markerOpacity", defaults["markerOpacity"]))
+            if not isinstance(fixed_opacity, (int, float)) or not isfinite(fixed_opacity):
+                raise ValueError("trace.wonderplot.markerOpacity must be finite" if "markerOpacity" in trace_options else "wonderplot.markerOpacity must be finite")
+            marker = {"x": x, "y": y, "value": value, "sourceIndex": source_index,
+                      "size": max(get_defaults("markers")["minSize"], trace_options.get("markerSize", wonderplot.get("markerSize", defaults["markerSize"])))}
+            if size_scale:
+                marker["sizeValue"] = point["size"]
+                marker["size"] = _wonder_scaled_value(point["size"], size_scale)
+            marker["opacity"] = max(0, min(1, fixed_opacity))
+            if opacity_scale:
+                marker["opacityValue"] = point["opacity"]
+                marker["opacity"] = _wonder_scaled_value(point["opacity"], opacity_scale)
+            if value is not None:
+                marker["fillColor"] = interpolate(float(value), low, high, stops, value_scale)
+            points.append({"x": x, "y": y})
+            markers.append(marker)
+        if markers:
+            primitive = {"type": "wonderplot", "points": points, "wonderPoints": markers,
+                               "traceIndex": trace_index, "markerShape": trace_options.get("markerShape", wonderplot.get("markerShape", defaults["markerShape"])),
+                               "color": color, "lineWidth": 0, "borderColor": trace_options.get("borderColor", wonderplot.get("borderColor", defaults["borderColor"])),
+                               "borderWidth": trace_options.get("borderWidth", wonderplot.get("borderWidth", defaults["borderWidth"])),
+                               "subplot": "main", "bounds": _bounds(width, height)}
+            resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), color)
+            bars = error_geometry(trace, resolved, x_axis, y_axis, (xmin, xmax), (ymin, ymax), width, height)
+            if bars:
+                primitive["errorBars"] = bars
+                primitive["errorBarStyle"] = resolved["style"]
+            labels = _wonder_labels(markers, defaults, wonderplot.get("markerLabels"), trace_options.get("markerLabels"))
+            if labels:
+                primitive["wonderplotMarkerLabels"] = labels
+            if not legend_used:
+                legend = _wonder_legend(wonderplot.get("colorScaleLegend"), defaults, stops,
+                                        low, high, value_scale, width, height)
+                if legend:
+                    primitive["wonderplotColorScaleLegend"] = legend
+                    legend_used = True
+            primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def polar_scene(options: Mapping, width: float, height: float) -> dict:
+    defaults = get_defaults("polar")
+    polar = options.get("polar") or {}
+    traces = _traces(options)
+    all_data = [point for trace in traces if trace.get("visible") is not False for point in trace.get("data", []) if point.get("x") is not None and point.get("y") is not None]
+    if not all_data:
+        return {"width": width, "height": height, "primitives": []}
+    max_value = polar.get("maxRadius") or max(float(point["y"]) for point in all_data)
+    min_value = polar.get("minRadius", defaults["minRadius"])
+    max_radius = min(width, height) / 2 * polar.get("outerRadiusRatio", defaults["outerRadiusRatio"])
+    center_x, center_y = width / 2, height / 2
+    start = radians(polar.get("startAngleDegrees", defaults["startAngleDegrees"]))
+    direction = 1 if polar.get("clockwise", defaults["clockwise"]) else -1
+    width_radians = radians(polar.get("sectorWidthDegrees", defaults["sectorWidthDegrees"]))
+    gap_radians = radians(polar.get("sectorGapDegrees", defaults["sectorGapDegrees"]))
+    primitives = []
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        color = trace.get("color") or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)]
+        trace_polar = trace.get("polar") or {}
+        points, sectors = [], []
+        for source_index, point in enumerate(trace.get("data", [])):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            angle = float(point["x"])
+            value = float(point["y"])
+            theta = start + radians(angle) * direction
+            radius = (value - min_value) / max(max_value - min_value, 2.220446049250313e-16) * max_radius
+            points.append({"x": center_x + cos(theta) * radius, "y": center_y + sin(theta) * radius})
+            half = (width_radians - gap_radians) / 2
+            sectors.append({"centerX": center_x, "centerY": center_y, "innerRadius": 0,
+                            "outerRadius": radius, "startAngle": theta - half, "endAngle": theta + half,
+                            "angle": angle, "value": value, "opacity": trace_polar.get("sectorOpacity", polar.get("sectorOpacity", defaults["sectorOpacity"])),
+                            "sourceIndex": source_index})
+        if sectors:
+            primitives.append({"type": "polar", "points": points, "polarSectors": sectors,
+                               "color": color, "lineWidth": trace_polar.get("borderWidth", polar.get("borderWidth", defaults["borderWidth"])),
+                               "borderColor": trace_polar.get("borderColor", polar.get("borderColor", defaults["borderColor"])),
+                               "borderWidth": trace_polar.get("borderWidth", polar.get("borderWidth", defaults["borderWidth"])),
+                               "traceIndex": trace_index, "subplot": "main", "bounds": _bounds(width, height)})
+    return {"width": width, "height": height, "primitives": primitives}