fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/references.py

@@ -0,0 +1,72 @@
+"""Source-shaped Cartesian reference validation; references render as overlays."""
+
+from __future__ import annotations
+
+from math import isfinite
+from typing import Mapping
+
+from .subplots import resolveSubplots, resolveTraceSubplotBindings
+
+
+def validateCartesianReferences(options: Mapping) -> None:
+    references = options.get("references")
+    if references is None:
+        return
+    if options.get("type") not in ("line", "bar", "wonderplot"):
+        raise ValueError("references are supported only for 'line', 'bar', and 'wonderplot' charts")
+    if not isinstance(references, Mapping):
+        raise TypeError("references must be an object")
+    for kind in ("lines", "bands"):
+        if kind in references and not isinstance(references[kind], list):
+            raise ValueError(f"references.{kind} must be an array")
+
+    # Import after scene is initialized: the same normalization governs chart data.
+    from .scene import _axis, _number, _scaled
+
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options)
+    for kind in ("lines", "bands"):
+        for index, reference in enumerate(references.get(kind) or []):
+            label = f"references.{kind}[{index}]"
+            if not isinstance(reference, Mapping):
+                raise TypeError(f"{label} must be an object")
+            dimension = reference.get("axis")
+            if dimension not in ("x", "y"):
+                raise ValueError(f"{label}.axis must be 'x' or 'y'")
+            scoped_id = reference.get("subplot")
+            subplot = next((item for item in subplots if item["id"] == scoped_id), None)
+            if "subplot" in reference and subplot is None:
+                raise ValueError(f"{label}.subplot references unknown subplot '{scoped_id}'")
+            axis_id = reference.get("axisId")
+            axis_map = ((options.get("axes") or {}).get(f"{dimension}Axes") or {})
+            known_axes = {dimension, *axis_map.keys()}
+            if axis_id is not None and axis_id not in known_axes:
+                raise ValueError(f"{label}.axisId references unknown {dimension}-axis '{axis_id}'")
+            candidates = [subplot] if subplot is not None else subplots
+            targets = []
+            for item in candidates:
+                fallback = item[f"{dimension}AxisId"]
+                selected = axis_id if axis_id is not None else fallback
+                bound = [binding for binding in bindings if binding["subplotId"] == item["id"]]
+                used = {binding[f"{dimension}AxisId"] for binding in bound} if bound else {fallback}
+                if selected in used and selected in known_axes:
+                    targets.append(_axis(options, dimension, selected))
+            if not targets:
+                selected = axis_id or (subplot[f"{dimension}AxisId"] if subplot else dimension)
+                scope = f"subplot '{subplot['id']}'" if subplot else "any subplot"
+                raise ValueError(f"{label}.axisId '{selected}' is not used by {scope}")
+            fields = ("value",) if kind == "lines" else ("from", "to")
+            for axis in targets:
+                for field in fields:
+                    value = reference.get(field)
+                    if value is None:
+                        raise ValueError(f"{label}.{field} is required")
+                    _scaled(_number(value, axis), axis)
+            if kind == "lines":
+                line_width = reference.get("lineWidth")
+                if "lineWidth" in reference and (isinstance(line_width, bool)
+                                                 or not isinstance(line_width, (int, float))
+                                                 or not isfinite(line_width) or line_width < 0):
+                    raise ValueError(f"{label}.lineWidth must be finite and >= 0")
+                if reference.get("pattern") not in (None, "solid", "dashed", "dotted", "dash-dot"):
+                    raise ValueError("lineStyle.pattern must be 'solid', 'dashed', 'dotted', or 'dash-dot'")

fastplotpy/rendering.py

@@ -0,0 +1,65 @@
+"""Python/browser rendering adapters for source-named DOM exports."""
+from copy import deepcopy
+from threading import RLock
+from typing import Mapping
+
+_diagnostics_lock = RLock()
+_last_line_axis_diagnostics: list[dict] = []
+
+
+def _set_last_line_axis_diagnostics(values) -> None:
+    if not isinstance(values, list) or any(not isinstance(item, Mapping) for item in values):
+        return
+    with _diagnostics_lock:
+        _last_line_axis_diagnostics[:] = deepcopy(values)
+
+
+def getLastLineAxisLayoutDiagnostics() -> list[dict]:
+    """Return the last diagnostics received from an attached browser canvas."""
+    with _diagnostics_lock:
+        return deepcopy(_last_line_axis_diagnostics)
+
+
+class Scene3dWebgl2CapabilityError(RuntimeError):
+    """Browser WebGL2 capability error with the source failure-code vocabulary."""
+
+    def __init__(self, code: str, message: str, cause: Exception | None = None):
+        super().__init__(message)
+        self.code = code
+        self.cause = cause
+
+
+def renderToCanvas(canvas, options: Mapping, style: Mapping | None = None) -> dict:
+    """Render on a Chart-owned browser/Jupyter canvas and return its host scene.
+
+    The Python ``canvas`` argument is a Chart because CPython has no DOM canvas.
+    The attached frontend performs the actual Canvas/WebGL drawing.
+    """
+    from .interactive import Chart
+
+    if not isinstance(canvas, Chart):
+        raise TypeError("canvas must be a fastplotpy Chart browser/Jupyter surface")
+    if not isinstance(options, Mapping) or not isinstance(style, Mapping | type(None)):
+        raise TypeError("options and style must be mappings")
+    with canvas._changed:
+        if canvas._closed:
+            raise RuntimeError("chart is destroyed")
+        if "ready" not in canvas._latest:
+            raise RuntimeError("browser canvas is not ready; display or serve the Chart first")
+        identifier = canvas.call("__renderToCanvas__", deepcopy(dict(options)), deepcopy(dict(style or {})))
+        while identifier not in canvas._command_results and not canvas._closed and "bridgeError" not in canvas._latest:
+            canvas._changed.wait()
+        if canvas._closed:
+            raise RuntimeError("chart was destroyed during renderToCanvas")
+        if "bridgeError" in canvas._latest:
+            raise RuntimeError(f"browser bridge failed: {canvas._latest['bridgeError']}")
+        outcome = canvas._command_results.pop(identifier)
+        payload = outcome["payload"]
+        if outcome["kind"] == "commandError":
+            if payload.get("name") == "Scene3dWebgl2CapabilityError":
+                raise Scene3dWebgl2CapabilityError(payload.get("code", "draw-failed"), payload.get("message", "WebGL2 rendering failed"))
+            raise RuntimeError(payload.get("message", "browser renderToCanvas failed"))
+        result = payload.get("result")
+        if not isinstance(result, Mapping) or "primitives" not in result:
+            raise RuntimeError("browser renderToCanvas returned an invalid scene")
+        return deepcopy(dict(result))

fastplotpy/rust_scenes.py

@@ -0,0 +1,314 @@
+"""Source-pinned Rust scene construction with Python-owned presentation state."""
+
+from __future__ import annotations
+
+from math import isfinite, log10
+from typing import Any, Mapping
+
+from .defaults import get_defaults
+from .native import rustCall
+
+
+def _bar_axis_value(value, axis):
+    categories = axis.get("categories") or []
+    if categories and isinstance(value, str):
+        return float(categories.index(value) + 1)
+    return float(value)
+
+
+def _bar_domain(values, axis, *, slot=False):
+    from .scene import _domain
+    if axis.get("range"):
+        result = _domain([], axis)
+    else:
+        result = _domain(values, axis)
+    if result is None:
+        return None
+    low, high = result
+    if not slot or axis.get("range"):
+        return {"min": low, "max": high}
+    transformed = sorted({_bar_scale(value, axis) for value in values})
+    differences = [right - left for left, right in zip(transformed, transformed[1:]) if right > left]
+    padding = min(differences) / 2 if differences else .5
+    return {"min": low - padding, "max": high + padding}
+
+
+def _bar_scale(value, axis):
+    return log10(value) if axis.get("scale") == "logarithmic" else value
+
+
+def bar_scene_rust(options: Mapping[str, Any], python_scene: dict) -> dict:
+    """Pass Python-normalized bar groups and domains to the source Rust core."""
+    from .families2d import _bar_labels, _bar_value_labels, _traces, resolve_bar_line_style
+    from .error_bars import error_domain_values, resolve_error_bars
+
+    bar = options.get("bar") or {}
+    defaults = get_defaults("bar")
+    traces = _traces(options)
+    mode = bar.get("mode", defaults["mode"])
+    orientation = bar.get("orientation", defaults["orientation"])
+    x_axis = ((options.get("axes") or {}).get("xAxes") or {}).get("x") or {}
+    y_axis = ((options.get("axes") or {}).get("yAxes") or {}).get("y") or {}
+    visible = [(index, trace) for index, trace in enumerate(traces) if trace.get("visible") is not False]
+    normalized = []
+    x_values, y_values, slot_values = [], [], []
+    stacked = {}
+    for index, trace in visible:
+        items = []
+        for source_index, point in enumerate(trace.get("data", [])):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            x = _bar_axis_value(point["x"], x_axis)
+            y = _bar_axis_value(point["y"], y_axis)
+            value = y if orientation == "vertical" else x
+            slot = x if orientation == "vertical" else y
+            base = _bar_axis_value(point["base"], y_axis if orientation == "vertical" else x_axis) if point.get("base") is not None else 0.0
+            items.append((source_index, x, y, base, point.get("base") is not None))
+            slot_values.append(slot)
+            if orientation == "vertical":
+                x_values.append(x)
+            else:
+                y_values.append(y)
+            if mode == "grouped":
+                (y_values if orientation == "vertical" else x_values).extend((base, value))
+            elif mode == "stacked":
+                side = "positive" if value >= 0 else "negative"
+                running = stacked.setdefault((slot, side), 0.0) + value
+                stacked[(slot, side)] = running
+                (y_values if orientation == "vertical" else x_values).extend((0.0, running))
+            else:
+                (y_values if orientation == "vertical" else x_values).extend((0.0, 100.0 if value > 0 else -100.0 if value < 0 else 0.0))
+        normalized.append((index, trace, items))
+    slot_axis = x_axis if orientation == "vertical" else y_axis
+    if mode == "grouped":
+        for _, trace in visible:
+            resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), "")
+            extra_x, extra_y = error_domain_values(trace, resolved, x_axis, y_axis)
+            x_values.extend(extra_x)
+            y_values.extend(extra_y)
+    if slot_axis.get("categories"):
+        (x_values if orientation == "vertical" else y_values).extend(range(1, len(slot_axis["categories"]) + 1))
+    if not slot_values:
+        return python_scene
+    x_domain = _bar_domain(x_values, x_axis, slot=orientation == "vertical")
+    y_domain = _bar_domain(y_values, y_axis, slot=orientation == "horizontal")
+    domain = x_domain if orientation == "vertical" else y_domain
+    unique = sorted({_bar_scale(value, slot_axis) for value in slot_values})
+    delta = min((right - left for left, right in zip(unique, unique[1:]) if right > left), default=None)
+    slot_size = python_scene["width"] if orientation == "vertical" else python_scene["height"]
+    if slot_axis.get("categories") and len(slot_axis["categories"]) > 1:
+        delta = 1.0
+    slot_width = (delta / max(domain["max"] - domain["min"], 2.220446049250313e-16) * slot_size) if delta is not None else slot_size
+    rust_traces = []
+    for index, trace, items in normalized:
+        if not items:
+            continue
+        trace_bar = trace.get("bar") or {}
+        from .defaults import DEFAULT_TRACE_COLORS
+        color, line_width = resolve_bar_line_style(options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])
+        rust_traces.append({
+            "points": [{"x": x, "y": y} for _, x, y, _, _ in items],
+            "baselines": [base for _, _, _, base, _ in items] if any(explicit for *_, explicit in items) else None,
+            "sourceIndexes": [source_index for source_index, *_ in items],
+            "groupKey": "main\0x\0y", "groupIndex": 0 if mode != "grouped" else [number for number, _ in visible].index(index),
+            "groupCount": 1 if mode != "grouped" else len(visible),
+            "slotWidth": slot_width, "subplotWidth": python_scene["width"], "subplotHeight": python_scene["height"],
+            "xDomain": x_domain, "yDomain": y_domain,
+            "xScale": x_axis.get("scale", "linear"), "yScale": y_axis.get("scale", "linear"),
+            "color": color,
+            "lineWidth": line_width,
+            "borderColor": trace_bar.get("borderColor", bar.get("borderColor", defaults["borderColor"])),
+            "borderWidth": trace_bar.get("borderWidth", bar.get("borderWidth", defaults["borderWidth"])),
+            "traceIndex": index, "subplot": "main",
+            "bounds": {"left": 0, "top": 0, "right": python_scene["width"], "bottom": python_scene["height"]},
+        })
+    native = rustCall("bar", input={
+        "width": python_scene["width"], "height": python_scene["height"],
+        "mode": mode, "orientation": orientation,
+        "barWidthRatio": bar.get("barWidthRatio", defaults["barWidthRatio"]),
+        "minBarWidth": defaults["minBarWidth"],
+        "borderColor": bar.get("borderColor", defaults["borderColor"]),
+        "borderWidth": bar.get("borderWidth", defaults["borderWidth"]),
+        "traces": rust_traces,
+    })
+    python_by_trace = {primitive["traceIndex"]: primitive for primitive in python_scene["primitives"]}
+    for primitive in native["primitives"]:
+        index = primitive["traceIndex"]
+        trace = traces[index]
+        trace_bar = trace.get("bar") or {}
+        radius = trace_bar.get("cornerRadius", bar.get("cornerRadius", defaults["cornerRadius"]))
+        for rect in primitive["bars"]:
+            if orientation == "vertical":
+                axis_domain, size = y_domain, python_scene["height"]
+            else:
+                axis_domain, size = x_domain, python_scene["width"]
+            baseline = rect["baseline"]
+            rendered = rect.get("normalizedValue", rect["value"])
+            end = rendered if mode == "grouped" else baseline + rendered
+            def position(value):
+                transformed = _bar_scale(value, y_axis if orientation == "vertical" else x_axis)
+                coordinate = ((transformed - axis_domain["min"]) /
+                              max(axis_domain["max"] - axis_domain["min"], 2.220446049250313e-16)) * size
+                return size - coordinate if orientation == "vertical" else coordinate
+            lower, upper = sorted((position(baseline), position(end)))
+            clipped_lower, clipped_upper = max(0.0, lower), min(size, upper)
+            if orientation == "vertical":
+                rect["height"] = clipped_upper - clipped_lower
+            else:
+                rect["width"] = clipped_upper - clipped_lower
+            corner = min(radius, rect["width"] / 2, rect["height"] / 2)
+            if corner > 0:
+                rect["cornerRadius"] = corner
+        labels = _bar_labels(defaults, bar.get("valueLabels"), trace_bar.get("valueLabels"))
+        items = _bar_value_labels(primitive["bars"], labels, orientation, mode)
+        if items:
+            primitive["barValueLabels"] = items
+        original = python_by_trace.get(index) or {}
+        for field in ("errorBars", "errorBarStyle"):
+            if field in original:
+                primitive[field] = original[field]
+    return native
+
+
+def heatmap_scene_rust(options: Mapping[str, Any], python_scene: dict) -> dict:
+    """Use the Rust grid geometry and retain the source's Python-built overlays.
+
+    fastPlotJs likewise resolves colors, labels, and grid presentation before
+    passing its normalized cells to the Rust core.
+    """
+    from .families2d import _traces
+
+    heatmap = options.get("heatmap") or {}
+    defaults = get_defaults("heatmap")
+    traces = _traces(options)
+    x_categories = heatmap.get("xCategories") or defaults["xCategories"]
+    y_categories = heatmap.get("yCategories") or defaults["yCategories"]
+    x_coordinates = (set(range(len(x_categories))) if x_categories else set())
+    y_coordinates = (set(range(len(y_categories))) if y_categories else set())
+    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
+            x_coordinates.add(x_categories.index(point["x"]) if x_categories else point["x"])
+            y_coordinates.add(y_categories.index(point["y"]) if y_categories else point["y"])
+    x_count, y_count = len(x_coordinates), len(y_coordinates)
+    output = {"width": python_scene["width"], "height": python_scene["height"], "primitives": []}
+    for primitive in python_scene["primitives"]:
+        trace_index = primitive["traceIndex"]
+        trace_heatmap = traces[trace_index].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
+        gap = nonnegative(trace_heatmap.get("cellGap"), nonnegative(heatmap.get("cellGap"), defaults["cellGap"]))
+        gap = min(gap, python_scene["width"] / x_count, python_scene["height"] / y_count)
+        native_cells = []
+        for item in primitive["heatmapCells"]:
+            native_cells.append({
+                "value": None if item.get("missing") else item["value"],
+                "xValue": item["xValue"], "yValue": item["yValue"],
+                "row": item["row"], "column": item["column"],
+                "fillColor": item["fillColor"], "missing": item.get("missing", False),
+                "borderColor": item.get("borderColor"), "borderWidth": item.get("borderWidth"),
+            })
+        native = rustCall("heatmap", input={
+            "width": python_scene["width"], "height": python_scene["height"],
+            "traces": [{
+                "cells": native_cells, "xCount": x_count, "yCount": y_count,
+                "subplotWidth": python_scene["width"], "subplotHeight": python_scene["height"],
+                "cellGap": gap, "color": primitive["color"],
+                "lineWidth": primitive["lineWidth"],
+                "borderColor": primitive["borderColor"], "borderWidth": primitive["borderWidth"],
+                "subplot": primitive["subplot"], "bounds": primitive["bounds"],
+            }],
+        })
+        if not native["primitives"]:
+            continue
+        rust_primitive = native["primitives"][0]
+        for rust_cell, source_cell in zip(rust_primitive["heatmapCells"], primitive["heatmapCells"]):
+            for field in ("sourceIndex", "xCategory", "yCategory", "cornerRadius"):
+                if field in source_cell:
+                    rust_cell[field] = source_cell[field]
+        # The source Node build and the Python ABI can emit a one-ULP
+        # centroid difference under their respective optimized Rust builds.
+        # Reconstructing from the Rust cells matches the source scene's
+        # serialized centroid and keeps Rust responsible for cell geometry.
+        rust_primitive["points"] = [
+            {"x": cell["x"] + cell["width"] / 2, "y": cell["y"] + cell["height"] / 2}
+            for cell in rust_primitive["heatmapCells"]
+        ]
+        for field in ("heatmapCellLabels", "heatmapGrid", "heatmapColorScaleLegend"):
+            if field in primitive:
+                rust_primitive[field] = primitive[field]
+        rust_primitive["traceIndex"] = trace_index
+        output["primitives"].append(rust_primitive)
+    return output
+
+
+def wonderplot_scene_rust(options: Mapping[str, Any], python_scene: dict) -> dict:
+    """Build marker positions in the source Rust core from Python-prepared values."""
+    from .families2d import _traces
+    from .error_bars import error_domain_values, resolve_error_bars
+
+    traces = _traces(options)
+    points = [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 points:
+        return python_scene
+    x_axis = ((options.get("axes") or {}).get("xAxes") or {}).get("x") or {}
+    y_axis = ((options.get("axes") or {}).get("yAxes") or {}).get("y") or {}
+    x_values = [float(point["x"]) for point in points]
+    y_values = [float(point["y"]) for point in points]
+    for trace in traces:
+        if trace.get("visible") is False:
+            continue
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), "")
+        extra_x, extra_y = error_domain_values(trace, resolved, x_axis, y_axis)
+        x_values.extend(extra_x)
+        y_values.extend(extra_y)
+    x_min, x_max = min(x_values), max(x_values)
+    y_min, y_max = min(y_values), max(y_values)
+    if x_axis.get("range"):
+        x_min, x_max = float(x_axis["range"]["min"]), float(x_axis["range"]["max"])
+    if y_axis.get("range"):
+        y_min, y_max = float(y_axis["range"]["min"]), float(y_axis["range"]["max"])
+    output = {"width": python_scene["width"], "height": python_scene["height"], "primitives": []}
+    for primitive in python_scene["primitives"]:
+        trace_index = primitive["traceIndex"]
+        data = traces[trace_index]["data"]
+        rust_points = []
+        for marker in primitive["wonderPoints"]:
+            original = data[marker["sourceIndex"]]
+            item = {
+                "x": float(original["x"]), "y": float(original["y"]),
+                "value": marker["value"], "sourceIndex": marker["sourceIndex"],
+                "size": marker["size"], "opacity": marker["opacity"],
+                "fillColor": marker["fillColor"],
+                "sizeValue": marker.get("sizeValue"),
+                "opacityValue": marker.get("opacityValue"),
+            }
+            rust_points.append(item)
+        native = rustCall("wonderplot", input={
+            "width": python_scene["width"], "height": python_scene["height"],
+            "traces": [{
+                "points": rust_points,
+                "subplotWidth": python_scene["width"], "subplotHeight": python_scene["height"],
+                "xDomain": {"min": x_min, "max": x_max},
+                "yDomain": {"min": y_min, "max": y_max},
+                "xScale": x_axis.get("scale", "linear"),
+                "yScale": y_axis.get("scale", "linear"),
+                "color": primitive["color"], "lineWidth": primitive["lineWidth"],
+                "borderColor": primitive["borderColor"], "borderWidth": primitive["borderWidth"],
+                "subplot": primitive["subplot"], "bounds": primitive["bounds"],
+            }],
+        })
+        if not native["primitives"]:
+            continue
+        rust_primitive = native["primitives"][0]
+        rust_primitive["traceIndex"] = trace_index
+        rust_primitive["markerShape"] = primitive["markerShape"]
+        for field in ("wonderplotMarkerLabels", "wonderplotColorScaleLegend", "errorBars", "errorBarStyle"):
+            if field in primitive:
+                rust_primitive[field] = primitive[field]
+        output["primitives"].append(rust_primitive)
+    return output