fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/exports.py

@@ -0,0 +1,153 @@
+"""Scene export behavior corresponding to fastPlotJs renderers/png.ts."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from base64 import b64decode
+from math import isfinite
+from typing import Any, Mapping
+
+from .defaults import get_defaults
+from .scene import plot
+from .native import rustCall, hasRustPlotEngine
+
+
+def _nonnegative(value: Any, fallback: float) -> float:
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value >= 0 else fallback
+
+
+def _title_height(options: Mapping) -> float:
+    title = options.get("title")
+    subtitle = options.get("subtitle")
+    has_title = isinstance(title, str) and bool(title.strip())
+    has_subtitle = isinstance(subtitle, str) and bool(subtitle.strip())
+    if not (has_title or has_subtitle):
+        return 0
+    defaults = get_defaults("layout")["decorations"]
+    style = options.get("style") or {}
+
+    def line_height(kind: str) -> float:
+        fallback = defaults[kind + "LineHeight"]
+        for source in (options.get(kind + "Style"), style.get(kind), style.get("text")):
+            if isinstance(source, Mapping) and "lineHeight" in source:
+                return _nonnegative(source["lineHeight"], fallback)
+        return fallback
+
+    height = defaults["topPadding"] + defaults["bottomGap"]
+    if has_title:
+        height += line_height("title")
+    if has_subtitle:
+        height += line_height("subtitle")
+        if has_title:
+            height += defaults["subtitleGap"]
+    return height
+
+
+def _export_bounds(options: Mapping) -> dict:
+    width, height = options["width"], options["height"]
+    margin_defaults = get_defaults("layout")["margin"]
+    margin_input = options.get("margin") or {}
+    margin = {side: _nonnegative(margin_input.get(key), margin_defaults[key]) for side, key in
+              (("left", "l"), ("right", "r"), ("top", "t"), ("bottom", "b"))}
+    axes = options.get("axes") or {}
+    axis_defaults = get_defaults("line-axes")["plotBounds"]
+    left, top = margin["left"], margin["top"] + _title_height(options)
+    right, bottom = margin["right"], margin["bottom"]
+    if axes.get("show") is True:
+        sides = get_defaults("layout")["axisSide"]
+        configured_x = {"x": {}}
+        configured_x.update(axes.get("xAxes") or {})
+        configured_y = {"y": {}}
+        configured_y.update(axes.get("yAxes") or {})
+        has_left = any(axis.get("show") is not False and axis.get("side", sides["y"]) == "left" for axis in configured_y.values())
+        has_right = any(axis.get("show") is not False and axis.get("side", sides["y"]) == "right" for axis in configured_y.values())
+        has_top = any(axis.get("show") is not False and axis.get("side", sides["x"]) == "top" for axis in configured_x.values())
+        has_bottom = any(axis.get("show") is not False and axis.get("side", sides["x"]) == "bottom" for axis in configured_x.values())
+        left += axis_defaults["left"] if has_left else axis_defaults["right"] if has_right else 0
+        right += axis_defaults["left"] if has_right else axis_defaults["right"] if has_left else 0
+        top += axis_defaults["bottom"] if has_top else axis_defaults["top"] if has_bottom else 0
+        bottom += axis_defaults["bottom"] if has_bottom else axis_defaults["top"] if has_top else 0
+    return {"left": left, "top": top, "right": max(left + 1, width - right), "bottom": max(top + 1, height - bottom)}
+
+
+def buildExportScene(options: Mapping[str, Any]) -> dict:
+    bounds = _export_bounds(options)
+    local = dict(options)
+    local["width"] = max(1, bounds["right"] - bounds["left"])
+    local["height"] = max(1, bounds["bottom"] - bounds["top"])
+    scene = deepcopy(plot(local))
+    scene["width"], scene["height"] = options["width"], options["height"]
+    for metadata in scene.get("scenes3d", []):
+        metadata["bounds"] = _translate_bounds(metadata["bounds"], bounds)
+    if scene.get("scene3d"):
+        scene["scene3d"]["bounds"] = _translate_bounds(scene["scene3d"]["bounds"], bounds)
+    for primitive in scene.get("primitives", []):
+        if primitive.get("bounds"):
+            primitive["bounds"] = _translate_bounds(primitive["bounds"], bounds)
+    return scene
+
+
+def _translate_bounds(bounds: Mapping, offset: Mapping) -> dict:
+    return {key: value + offset["left" if key in ("left", "right") else "top"] for key, value in bounds.items()}
+
+
+def renderToPNG(options: Mapping[str, Any]) -> bytes:
+    """Return source-compatible UTF-8 scene JSON bytes (the source API's name is historical)."""
+    from .js_serialize import js_json_stringify
+    return js_json_stringify(buildExportScene(options)).encode("utf-8")
+
+
+class Scene3dNodePngExportError(RuntimeError):
+    """Source-compatible typed failure for the optional native 3D PNG path."""
+
+    def __init__(self, code: str, message: str, cause: Exception | None = None):
+        super().__init__(message)
+        self.code = code
+        self.cause = cause
+
+
+def _validate_png(data: bytes, width: int, height: int) -> None:
+    valid = len(data) >= 45 and data[:8] == b"\x89PNG\r\n\x1a\n"
+    offset, chunk_index, saw_end = 8, 0, False
+    while valid and offset + 12 <= len(data):
+        length = int.from_bytes(data[offset:offset + 4], "big")
+        end = offset + 12 + length
+        if end > len(data):
+            valid = False
+            break
+        kind = data[offset + 4:offset + 8]
+        if chunk_index == 0:
+            valid = kind == b"IHDR" and length == 13 and int.from_bytes(data[offset + 8:offset + 12], "big") == width and int.from_bytes(data[offset + 12:offset + 16], "big") == height
+        if kind == b"IEND":
+            saw_end = valid and length == 0 and end == len(data)
+            break
+        offset, chunk_index = end, chunk_index + 1
+    if not valid or not saw_end:
+        raise Scene3dNodePngExportError("MALFORMED_NATIVE_OUTPUT", "The native rasterizer returned malformed PNG bytes or unexpected dimensions")
+
+
+def renderScene3dToPNG(options: Mapping[str, Any]) -> bytes:
+    """Render static Scene3D SVG through the source rasterizer's Rust implementation."""
+    if options.get("type") not in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+        raise Scene3dNodePngExportError("UNSUPPORTED_CHART_TYPE", "renderScene3dToPNG supports only experimental scatter3d, line3d, surface, mesh3d, and pie3d charts")
+    width, height = options.get("width"), options.get("height")
+    safe_limit = 2**53 - 1  # ECMAScript Number.MAX_SAFE_INTEGER from the source contract.
+    if any(isinstance(value, bool) or not isinstance(value, int) or value <= 0 or value > safe_limit for value in (width, height)):
+        raise Scene3dNodePngExportError("INVALID_DIMENSIONS", "renderScene3dToPNG requires positive integer width and height values")
+    pixels = width * height
+    max_pixels = get_defaults("scene3d")["nodePngMaxPixels"]
+    if pixels > safe_limit or pixels > max_pixels:
+        raise Scene3dNodePngExportError("PIXEL_LIMIT_EXCEEDED", f"renderScene3dToPNG rejects {pixels} pixels; the limit is {max_pixels}")
+    from .svg3d import renderScene3dToSVG
+    try:
+        svg = renderScene3dToSVG(options)
+    except Exception as error:
+        raise Scene3dNodePngExportError("SVG_RENDER_FAILED", "The renderer-neutral Scene3D SVG could not be generated", error) from error
+    if not hasRustPlotEngine():
+        raise Scene3dNodePngExportError("NODE_NATIVE_UNAVAILABLE", "renderScene3dToPNG requires the optional fastPlotPy Rust native library")
+    try:
+        result = b64decode(rustCall("raster_svg", svg=svg, width=width, height=height, maxPixels=max_pixels), validate=True)
+    except Exception as error:
+        raise Scene3dNodePngExportError("NATIVE_RASTER_FAILED", "The native Scene3D rasterizer failed without returning partial bytes", error) from error
+    _validate_png(result, width, height)
+    return result