fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/surface_lod.py

@@ -0,0 +1,109 @@
+"""Source-compatible regular-grid allocation for experimental surface LOD."""
+
+from __future__ import annotations
+
+from math import floor, log
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def resolve_surface_lod(value) -> dict | None:
+    if value is ... or value is False:
+        return None
+    if value is None or value is not True and not isinstance(value, Mapping):
+        raise ValueError("surface.lod must be a boolean or an options object")
+    source = {} if value is True else value
+    enabled = source.get("enabled", True)
+    if type(enabled) is not bool:
+        raise ValueError("surface.lod.enabled must be a boolean")
+    defaults = get_defaults("surface")["lod"]
+    strategy = source.get("strategy", defaults["strategy"])
+    if strategy != "grid-stride":
+        raise ValueError("surface.lod.strategy must be 'grid-stride'")
+    max_cells = source.get("maxCells", defaults["maxCells"])
+    if type(max_cells) is not int or not 1 <= max_cells <= 1_000_000:
+        raise ValueError("surface.lod.maxCells must be an integer between 1 and 1000000")
+    return {"strategy": strategy, "maxCells": max_cells} if enabled else None
+
+
+def _allocate(grids: list[dict], max_cells: int) -> list[int]:
+    allocations = [0] * len(grids)
+    active = [grid for grid in grids if grid["allocatable"] > 0]
+    candidates = sum(grid["allocatable"] for grid in active)
+    if candidates <= max_cells:
+        for grid in active:
+            allocations[grid["traceIndex"]] = grid["allocatable"]
+        return allocations
+    if max_cells < len(active):
+        for grid in active[:max_cells]:
+            allocations[grid["traceIndex"]] = 1
+        return allocations
+    for grid in active:
+        allocations[grid["traceIndex"]] = 1
+    remaining = max_cells - len(active)
+    available_extras = sum(grid["allocatable"] - 1 for grid in active)
+    remainders = []
+    for grid in active:
+        exact = remaining * (grid["allocatable"] - 1) / available_extras
+        allocated = floor(exact)
+        allocations[grid["traceIndex"]] += allocated
+        remainders.append((-(exact - allocated), grid["traceIndex"]))
+    undistributed = max_cells - sum(allocations)
+    for _, index in sorted(remainders):
+        if undistributed == 0:
+            break
+        if allocations[index] < grids[index]["allocatable"]:
+            allocations[index] += 1
+            undistributed -= 1
+    return allocations
+
+
+def _dimensions(x_count: int, y_count: int, max_cells: int) -> tuple[int, int]:
+    selected_x = selected_y = selected_cells = 1
+    selected_error = float("inf")
+    source_aspect = x_count / y_count
+    for x in range(1, min(x_count, max_cells) + 1):
+        y = min(y_count, max_cells // x)
+        if y < 1:
+            continue
+        cells = x * y
+        aspect_error = abs(log((x / y) / source_aspect))
+        if cells > selected_cells or cells == selected_cells and (
+                aspect_error < selected_error or aspect_error == selected_error and x < selected_x):
+            selected_x, selected_y, selected_cells, selected_error = x, y, cells, aspect_error
+    return selected_x, selected_y
+
+
+def select_surface_lod_grids(parsed: list[list[dict]], max_cells: int) -> dict:
+    grids = []
+    for index, points in enumerate(parsed):
+        xs = sorted({point["x"] for point in points})
+        ys = sorted({point["y"] for point in points})
+        candidates = max(0, len(xs) - 1) * max(0, len(ys) - 1)
+        lookup = {(point["x"], point["y"]): point for point in points}
+        renderable = any(all(lookup[(xs[column + dx], ys[row + dy])]["z"] is not None
+                             for dx, dy in ((0, 0), (1, 0), (0, 1), (1, 1)))
+                         for row in range(max(0, len(ys) - 1))
+                         for column in range(max(0, len(xs) - 1)))
+        grids.append({"traceIndex": index, "xs": xs, "ys": ys, "candidate": candidates,
+                      "allocatable": candidates if renderable else 0, "lookup": lookup})
+    allocations = _allocate(grids, max_cells)
+    selected = []
+    for grid, allocation in zip(grids, allocations):
+        if not allocation:
+            selected.append({"xIndexes": [], "yIndexes": [], "renderable": set()})
+            continue
+        x_cells, y_cells = _dimensions(len(grid["xs"]) - 1, len(grid["ys"]) - 1, allocation)
+        x_indexes = [floor(index * (len(grid["xs"]) - 1) / x_cells + .5) for index in range(x_cells + 1)]
+        y_indexes = [floor(index * (len(grid["ys"]) - 1) / y_cells + .5) for index in range(y_cells + 1)]
+        renderable = set()
+        for row in range(y_cells):
+            for column in range(x_cells):
+                contains_gap = any(grid["lookup"][(grid["xs"][source_column], grid["ys"][source_row])]["z"] is None
+                                   for source_row in range(y_indexes[row], y_indexes[row + 1] + 1)
+                                   for source_column in range(x_indexes[column], x_indexes[column + 1] + 1))
+                if not contains_gap:
+                    renderable.add((row, column))
+        selected.append({"xIndexes": x_indexes, "yIndexes": y_indexes, "renderable": renderable})
+    return {"byTrace": selected, "candidateCellCount": sum(grid["candidate"] for grid in grids)}

fastplotpy/svg3d.py

@@ -0,0 +1,235 @@
+"""Static SVG export of Python-built three-dimensional scenes."""
+
+from __future__ import annotations
+
+from html import escape
+from math import cos, isfinite, pi, sin, sqrt
+import re
+from typing import Mapping
+
+from .defaults import get_defaults
+from .exports import buildExportScene
+
+
+_TYPES = frozenset({"scatter3d", "line3d", "surface", "mesh3d", "pie3d"})
+_HEX = re.compile(r"^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$", re.I)
+_FUNCTION = re.compile(r"^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch)\([0-9eE+\-.,%/\sdegatrun]*\)$", re.I)
+_COLOR_SPACE = re.compile(r"^color\((?:srgb|srgb-linear|display-p3|a98-rgb|prophoto-rgb|rec2020|xyz|xyz-d50|xyz-d65)\s+[0-9eE+\-.,%/\s]+\)$", re.I)
+_FONTS = re.compile(r"^[a-zA-Z0-9\s,.'\"/-]+$")
+_NAMED = set("""
+aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown
+burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan
+darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred
+darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue
+dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray
+green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon
+lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon
+lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta
+maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen
+mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive
+olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru
+pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell
+sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato transparent
+turquoise violet wheat white whitesmoke yellow yellowgreen
+""".split())
+
+
+def _xml(value: object) -> str:
+    valid = "".join(char if ord(char) in (9, 10, 13) or 32 <= ord(char) <= 0xD7FF or 0xE000 <= ord(char) <= 0xFFFD or 0x10000 <= ord(char) <= 0x10FFFF else "\ufffd" for char in str(value))
+    return escape(valid, quote=True).replace("'", "&apos;")
+
+
+def _paint(value: str) -> str:
+    value = value.strip()
+    if not (_HEX.fullmatch(value) or _FUNCTION.fullmatch(value) or _COLOR_SPACE.fullmatch(value) or value.lower() in _NAMED):
+        raise ValueError(f'3D SVG fallback does not support unsafe paint value "{value}"')
+    return _xml(value)
+
+
+def _font(value: str) -> str:
+    value = value.strip()
+    if not value or not _FONTS.fullmatch(value):
+        raise ValueError(f'3D SVG fallback does not support unsafe font value "{value}"')
+    return _xml(value)
+
+
+def _n(value: float) -> str:
+    if not isfinite(value):
+        raise ValueError("3D SVG fallback coordinates must remain finite")
+    decimals = get_defaults("scene3d")["staticFallbackDecimals"]
+    rounded = round(value, decimals)
+    return str(int(rounded)) if rounded == int(rounded) else f"{rounded:.{decimals}f}".rstrip("0").rstrip(".")
+
+
+def _opacity(value: float) -> str:
+    return _n(max(0, min(1, value)))
+
+
+def _line(x1, y1, x2, y2, color, width, alpha=1, attrs=""):
+    return f'<line x1="{_n(x1)}" y1="{_n(y1)}" x2="{_n(x2)}" y2="{_n(y2)}" stroke="{_paint(color)}" stroke-width="{_n(width)}" stroke-opacity="{_opacity(alpha)}"{attrs}/>'
+
+
+def _polygon(points, color, alpha, attrs=""):
+    coordinates = " ".join(f'{_n(point["x"])},{_n(point["y"])}' for point in points)
+    return f'<polygon points="{coordinates}" fill="{_paint(color)}" fill-opacity="{_opacity(alpha)}"{attrs}/>'
+
+
+def _marker(x, y, radius, shape, color, alpha, attrs):
+    if shape == "circle":
+        return f'<circle cx="{_n(x)}" cy="{_n(y)}" r="{_n(radius)}" fill="{_paint(color)}" fill-opacity="{_opacity(alpha)}"{attrs}/>'
+    if shape == "square":
+        half = radius / sqrt(2)
+        return f'<rect x="{_n(x-half)}" y="{_n(y-half)}" width="{_n(2*half)}" height="{_n(2*half)}" fill="{_paint(color)}" fill-opacity="{_opacity(alpha)}"{attrs}/>'
+    sides = {"diamond": 4, "triangle": 3, "pentagon": 5}.get(shape, 6)
+    points = [{"x": x + cos(-pi/2 + i*2*pi/sides)*radius,
+               "y": y + sin(-pi/2 + i*2*pi/sides)*radius} for i in range(sides)]
+    return _polygon(points, color, alpha, attrs)
+
+
+def _hash(scene: dict, label: str, description: str) -> str:
+    from .js_serialize import js_json_stringify
+    source = js_json_stringify(scene) + "\0" + label + "\0" + description
+    value = 0x811C9DC5
+    units = source.encode("utf-16-le", errors="surrogatepass")
+    for index in range(0, len(units), 2):
+        code_unit = units[index] | (units[index + 1] << 8)
+        value = ((value ^ code_unit) * 0x01000193) & 0xFFFFFFFF
+    return f"scene3d-{value:08x}"
+
+
+def _text(x, y, color, font, content, extra=' text-anchor="middle" dominant-baseline="middle"'):
+    return f'<text x="{_n(x)}" y="{_n(y)}" fill="{_paint(color)}" style="font:{_font(font)}"{extra}>{_xml(content)}</text>'
+
+
+def renderScene3dToSVG(options: Mapping) -> str:
+    """Render a Python scene to an accessible, self-contained static SVG."""
+    if options.get("type") not in _TYPES:
+        raise ValueError("renderScene3dToSVG supports only experimental scatter3d, line3d, surface, mesh3d, and pie3d charts")
+    scene = buildExportScene(options)
+    metadata_items = scene.get("scenes3d") or ([scene["scene3d"]] if scene.get("scene3d") else [])
+    defaults = get_defaults("scene3d")
+    labels = list(dict.fromkeys(str(metadata.get("accessibility", {}).get("label") or "").strip() for metadata in metadata_items))
+    descriptions = list(dict.fromkeys(str(metadata.get("accessibility", {}).get("description") or "").strip() for metadata in metadata_items))
+    label = "; ".join(item for item in labels if item) or str(options.get("title") or "").strip() or {
+        "scatter3d": defaults["accessibilityScatter3dLabel"], "line3d": defaults["accessibilityLine3dLabel"],
+        "surface": defaults["accessibilitySurfaceLabel"], "pie3d": "Pie3D chart",
+        "mesh3d": defaults["accessibilityMesh3dLabel"]}[options["type"]]
+    description = " ".join(item for item in descriptions if item) or str(options.get("subtitle") or "").strip() or defaults["staticFallbackDescription"]
+    prefix = _hash(scene, label, description)
+    definitions, body = [], []
+    gradients = {}
+    for i, primitive in enumerate(scene["primitives"]):
+        legend = primitive.get("scene3dColorScaleLegend") or primitive.get("surface3dColorScaleLegend")
+        if legend:
+            identifier = f"{prefix}-gradient-{i}"
+            gradients[i] = identifier
+            stops = "".join(f'<stop offset="{_n(stop["offset"])}" stop-color="{_paint(stop["color"])}"/>' for stop in legend["colorStops"])
+            definitions.append(f'<linearGradient id="{identifier}" x1="0" y1="1" x2="0" y2="0">{stops}</linearGradient>')
+    for i, metadata in enumerate(metadata_items):
+        bounds = metadata["bounds"]
+        definitions.append(f'<clipPath id="{prefix}-clip-{i}"><rect x="{_n(bounds["left"])}" y="{_n(bounds["top"])}" width="{_n(bounds["right"]-bounds["left"])}" height="{_n(bounds["bottom"]-bounds["top"])}"/></clipPath>')
+    style = options.get("style") or {}
+    background = options.get("backgroundColor") or style.get("backgroundColor")
+    if background:
+        body.append(f'<rect width="{_n(scene["width"])}" height="{_n(scene["height"])}" fill="{_paint(background)}"/>')
+    plot_background = options.get("plotAreaBackgroundColor") or (style.get("plotArea") or {}).get("backgroundColor")
+    if plot_background:
+        for metadata in metadata_items:
+            bounds = metadata["bounds"]
+            body.append(f'<rect x="{_n(bounds["left"])}" y="{_n(bounds["top"])}" width="{_n(bounds["right"]-bounds["left"])}" height="{_n(bounds["bottom"]-bounds["top"])}" fill="{_paint(plot_background)}"/>')
+    title_y = get_defaults("layout")["decorations"]["topPadding"]
+    for kind in ("title", "subtitle"):
+        value = options.get(kind)
+        if not isinstance(value, str) or not value.strip():
+            continue
+        if kind == "subtitle" and isinstance(options.get("title"), str) and options["title"].strip():
+            title_y += get_defaults("layout")["decorations"]["subtitleGap"]
+        text_defaults = get_defaults("layout")["decorations"]
+        style_options = {**(style.get("text") or {}), **(style.get(kind) or {}), **(options.get(kind + "Style") or {})}
+        color = style_options.get("color", text_defaults[kind + "Color"])
+        font = style_options.get("font", text_defaults[kind + "Font"])
+        body.append(_text(scene["width"]/2, title_y, color, font, value.strip(), ' text-anchor="middle" dominant-baseline="hanging"'))
+        title_y += style_options.get("lineHeight", text_defaults[kind + "LineHeight"])
+    for index, metadata in enumerate(metadata_items):
+        bounds = metadata["bounds"]
+        ox, oy = bounds["left"], bounds["top"]
+        parts = []
+        for kind in ("grid", "axis", "tick"):
+            segments = [segment for segment in metadata.get("segments", []) if segment["kind"] == kind]
+            if kind == "grid":
+                segments.sort(key=lambda item: -max(item["depth1"], item["depth2"]))
+            for segment in segments:
+                color = metadata["gridColor"] if kind == "grid" else metadata["axisColor"]
+                width = metadata["gridLineWidth"] if kind == "grid" else metadata["axisLineWidth"]
+                if kind == "tick":
+                    width = max(defaults["axisTickMinLineWidth"], width * defaults["axisTickLineWidthScale"])
+                parts.append(_line(ox+segment["x1"], oy+segment["y1"], ox+segment["x2"], oy+segment["y2"], color, width))
+        entries = []
+        for primitive in scene["primitives"]:
+            if primitive.get("subplot") != metadata["subplotId"]:
+                continue
+            trace = primitive.get("traceIndex", 0)
+            for triangle in primitive.get("surface3dTriangles") or primitive.get("mesh3dTriangles") or []:
+                if triangle.get("pie3d") and triangle.get("opacity") == 1 and triangle.get("frontFacing") is False:
+                    continue
+                source = (triangle.get("sourceCell") or triangle.get("sourceFace") or {})["index"]
+                entries.append((triangle["depth"], trace, source, "triangle", triangle))
+            for contour in primitive.get("surface3dContourSegments") or []:
+                source = contour["sourceCell"]["index"]
+                entries.append(((contour["depth1"]+contour["depth2"])/2, trace, source, "contour", contour))
+        entries.sort(key=lambda item: (-item[0], item[1], item[2], 0 if item[3] == "triangle" else 1))
+        for _, trace, source, kind, item in entries:
+            attrs = f' data-trace-index="{trace}" data-source-index="{source}"'
+            if kind == "contour":
+                parts.append(_line(ox+item["x1"], oy+item["y1"], ox+item["x2"], oy+item["y2"], item["style"]["color"], item["style"]["width"], item["style"]["opacity"], attrs))
+            else:
+                points = [{"x": ox+vertex["x"], "y": oy+vertex["y"]} for vertex in item["vertices"]]
+                pie = item.get("pie3d")
+                if pie:
+                    attrs += f' data-pie3d-face="{_xml(pie["face"])}"'
+                    if item["opacity"] == 1:
+                        attrs += f' stroke="{_paint(item["fillColor"])}" stroke-width="1"'
+                parts.append(_polygon(points, item["fillColor"], item["opacity"], attrs))
+                for edge_index, visible in enumerate(item.get("wireframeEdges") or []):
+                    if visible and item.get("wireframe"):
+                        left, right = points[edge_index], points[(edge_index+1) % len(points)]
+                        wire = item["wireframe"]
+                        parts.append(_line(left["x"], left["y"], right["x"], right["y"], wire["color"], wire["width"], wire["opacity"], attrs))
+        line_entries, points = [], []
+        for primitive in scene["primitives"]:
+            if primitive.get("subplot") != metadata["subplotId"]:
+                continue
+            trace = primitive.get("traceIndex", 0)
+            for segment in primitive.get("line3dSegments") or []:
+                line_entries.append((segment, primitive, trace))
+            for point in primitive.get("scatter3dPoints") or []:
+                points.append((point, trace))
+        line_entries.sort(key=lambda entry: (-max(entry[0]["depth1"], entry[0]["depth2"]), entry[2], entry[0]["sourceIndex1"], entry[0].get("sourceRatio1", 0)))
+        for segment, primitive, trace in line_entries:
+            attrs = f' data-trace-index="{trace}" data-source-index="{segment["sourceIndex1"]}"'
+            parts.append(_line(ox+segment["x1"], oy+segment["y1"], ox+segment["x2"], oy+segment["y2"], primitive["color"], primitive["lineWidth"], segment["opacity"], attrs))
+        points.sort(key=lambda item: (-item[0]["depth"], item[1], item[0]["sourceIndex"]))
+        for point, trace in points:
+            attrs = f' data-trace-index="{trace}" data-source-index="{point["sourceIndex"]}"'
+            parts.append(_marker(ox+point["x"], oy+point["y"], point["radius"], point["markerShape"], point["fillColor"], point["opacity"], attrs))
+        for tick in metadata.get("tickLabels", []):
+            parts.append(_text(ox+tick["x"], oy+tick["y"], metadata["axisColor"], metadata["tickLabelFont"], tick["text"]))
+        for axis in metadata.get("labels", []):
+            parts.append(_text(ox+axis["x"], oy+axis["y"]-defaults["axisLabelOffset"], metadata["axisColor"], defaults["axisLabelFont"], axis["text"]))
+        for primitive in scene["primitives"]:
+            if primitive.get("subplot") != metadata["subplotId"]:
+                continue
+            for point in primitive.get("pie3dLabels") or []:
+                parts.append(_text(ox+point["x"], oy+point["y"], point["color"], point["font"], point["text"]))
+            legend = primitive.get("scene3dColorScaleLegend") or primitive.get("surface3dColorScaleLegend")
+            identifier = gradients.get(scene["primitives"].index(primitive))
+            if legend and identifier:
+                parts.append(f'<rect x="{_n(ox+legend["x"])}" y="{_n(oy+legend["y"])}" width="{_n(legend["width"])}" height="{_n(legend["height"])}" fill="url(#{identifier})"/>')
+                if legend.get("labelsVisible"):
+                    parts.append(_text(ox+legend["x"], oy+max(0, legend["y"]-7), legend["color"], legend["font"], legend["title"], ""))
+                    for tick in legend["ticks"]:
+                        y = oy+legend["y"]+legend["height"]*(1-tick["y"])
+                        parts.append(_text(ox+legend["x"]+legend["width"]+legend["labelGap"], y, legend["color"], legend["font"], tick["text"], ' dominant-baseline="middle"'))
+        scene_label = (metadata.get("accessibility") or {}).get("label") or label
+        body.append(f'<g clip-path="url(#{prefix}-clip-{index})" role="group" aria-label="{_xml(scene_label)}" data-subplot="{_xml(metadata["subplotId"])}">{"".join(parts)}</g>')
+    return f'<svg xmlns="http://www.w3.org/2000/svg" width="{_n(scene["width"])}" height="{_n(scene["height"])}" viewBox="0 0 {_n(scene["width"])} {_n(scene["height"])}" role="img" aria-labelledby="{prefix}-title {prefix}-description"><title id="{prefix}-title">{_xml(label)}</title><desc id="{prefix}-description">{_xml(description)}</desc><defs>{"".join(definitions)}</defs>{"".join(body)}</svg>'

fastplotpy/trendline.py

@@ -0,0 +1,236 @@
+"""Python port of fastPlotJs line trend fitting and sampling."""
+
+from __future__ import annotations
+
+from math import exp, isfinite, log, sqrt
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+_METHODS = {"linear", "polynomial", "exponential", "logarithmic", "power", "gaussian", "cauchyLorentz"}
+
+
+def resolve_trendline(plot_value, trace_value):
+    defaults = get_defaults("trace-options")["trendline"]
+    source = trace_value if trace_value is not None else plot_value
+    if source is None or isinstance(source, bool):
+        return {"show": defaults["show"] if source is None else source,
+                "method": defaults["method"], "degree": defaults["degree"], "samples": defaults["samples"]}
+    source = source if isinstance(source, Mapping) else {}
+    def bounded_integer(key):
+        value = source.get(key)
+        if isinstance(value, bool) or not isinstance(value, int):
+            value = defaults[key]
+        return max(defaults["min" + key.capitalize()], min(defaults["max" + key.capitalize()], value))
+    result = {"show": source.get("show", True),
+              "method": source.get("method") if source.get("method") in _METHODS else defaults["method"],
+              "degree": bounded_integer("degree"), "samples": bounded_integer("samples")}
+    if "color" in source:
+        result["color"] = source["color"]
+    return result
+
+
+def _solve(matrix, values):
+    size = len(values)
+    augmented = [row[:] + [value] for row, value in zip(matrix, values)]
+    for column in range(size):
+        pivot_row = max(range(column, size), key=lambda row: abs(augmented[row][column]))
+        if abs(augmented[pivot_row][column]) <= 1e-12:  # Source singularity tolerance.
+            return None
+        augmented[column], augmented[pivot_row] = augmented[pivot_row], augmented[column]
+        pivot = augmented[column][column]
+        for index in range(column, size + 1):
+            augmented[column][index] /= pivot
+        for row in range(size):
+            if row == column:
+                continue
+            factor = augmented[row][column]
+            if factor == 0:
+                continue
+            for index in range(column, size + 1):
+                augmented[row][index] -= factor * augmented[column][index]
+    return [row[size] for row in augmented]
+
+
+def _least_squares(rows, values):
+    if not rows or len(rows) != len(values):
+        return None
+    size = len(rows[0])
+    matrix = [[0.0] * size for _ in range(size)]
+    vector = [0.0] * size
+    for row, value in zip(rows, values):
+        for i in range(size):
+            vector[i] += row[i] * value
+            for j in range(size):
+                matrix[i][j] += row[i] * row[j]
+    return _solve(matrix, vector)
+
+
+def _polynomial(points, degree):
+    minimum, maximum = min(point["x"] for point in points), max(point["x"] for point in points)
+    degree = min(degree, len(points) - 1)
+    center, span = (minimum + maximum) / 2, maximum - minimum
+    rows = []
+    for point in points:
+        x = (point["x"] - center) / span * 2
+        row = [1.0]
+        for _ in range(degree):
+            row.append(row[-1] * x)
+        rows.append(row)
+    coefficients = _least_squares(rows, [point["y"] for point in points])
+    if coefficients is None:
+        return None
+    def evaluate(x):
+        scaled = (x - center) / span * 2
+        value = 0.0
+        for coefficient in reversed(coefficients):
+            value = value * scaled + coefficient
+        return value if isfinite(value) else None
+    return evaluate, degree
+
+
+def _transformed(points, x_transform, y_transform, inverse):
+    rows, values = [], []
+    for point in points:
+        x, y = x_transform(point["x"]), y_transform(point["y"])
+        if x is None or y is None or not isfinite(x) or not isfinite(y):
+            continue
+        rows.append([1, x])
+        values.append(y)
+    if len(rows) < 2:
+        return None
+    coefficients = _least_squares(rows, values)
+    if coefficients is None:
+        return None
+    def evaluate(x):
+        transformed = x_transform(x)
+        if transformed is None or not isfinite(transformed):
+            return None
+        try:
+            value = inverse(coefficients[0] + coefficients[1] * transformed)
+        except OverflowError:
+            return None
+        return value if isfinite(value) else None
+    return evaluate, None
+
+
+def _peak(points, method):
+    xs = [point["x"] for point in points]
+    ys = [point["y"] for point in points]
+    if len(points) < 3 or min(ys) == max(ys):
+        return None
+    mean_y = sum(ys) / len(ys)
+    peak_mode = max(ys) - mean_y >= mean_y - min(ys)
+    baseline = min(ys) if peak_mode else max(ys)
+    extreme = max(points, key=lambda point: point["y"]) if peak_mode else min(points, key=lambda point: point["y"])
+    amplitude = extreme["y"] - baseline
+    span = max(xs) - min(xs)
+    if abs(amplitude) <= 2.220446049250313e-16:
+        return None
+    weights = [max(0, (point["y"] - baseline) / amplitude) for point in points]
+    weight_sum = sum(weights)
+    center = sum(point["x"] * weight for point, weight in zip(points, weights)) / weight_sum if weight_sum else extreme["x"]
+    variance = sum((point["x"] - center) ** 2 * weight for point, weight in zip(points, weights)) / weight_sum if weight_sum else (span / 6) ** 2
+    width = sqrt(variance) if variance > 0 else span / 6
+    if method == "cauchyLorentz":
+        crossings = []
+        sorted_points = sorted(points, key=lambda point: point["x"])
+        for a, b in zip(sorted_points, sorted_points[1:]):
+            av = (a["y"] - baseline) / amplitude - .5
+            bv = (b["y"] - baseline) / amplitude - .5
+            if av == 0:
+                crossings.append(a["x"])
+            elif av * bv <= 0 and av != bv:
+                crossings.append(a["x"] + (b["x"] - a["x"]) * av / (av - bv))
+        left = min((center - x for x in crossings if x < center), default=None)
+        right = min((x - center for x in crossings if x > center), default=None)
+        if left is not None and right is not None:
+            width = (left + right) / 2
+        elif left is not None or right is not None:
+            width = left if left is not None else right
+    width = max(2.220446049250313e-16, span / 1_000_000, width)
+    def evaluate(x):
+        z = (x - center) / width
+        value = baseline + amplitude * exp(-.5 * z * z) if method == "gaussian" else baseline + amplitude / (1 + z * z)
+        return value if isfinite(value) else None
+    return evaluate, None
+
+
+def sample_trendline(points, resolved):
+    points = [point for point in points if point is not None and isfinite(point["x"]) and isfinite(point["y"])]
+    if not resolved["show"] or len(points) < 2:
+        return None
+    minimum, maximum = min(point["x"] for point in points), max(point["x"] for point in points)
+    if not minimum < maximum:
+        return None
+    method = resolved["method"]
+    if method in ("linear", "polynomial"):
+        model = _polynomial(points, 1 if method == "linear" else resolved["degree"])
+    elif method == "exponential":
+        center, span = (minimum + maximum) / 2, maximum - minimum
+        model = _transformed(points, lambda x: (x - center) / span * 2,
+                             lambda y: log(y) if y > 0 else None, exp)
+    elif method == "logarithmic":
+        model = _transformed(points, lambda x: log(x) if x > 0 else None,
+                             lambda y: y, lambda value: value)
+    elif method == "power":
+        model = _transformed(points, lambda x: log(x) if x > 0 else None,
+                             lambda y: log(y) if y > 0 else None, exp)
+    else:
+        model = _peak(points, method)
+    if model is None:
+        return None
+    evaluate, degree = model
+    samples = get_defaults("trace-options")["trendline"]["minSamples"] if method == "linear" else resolved["samples"]
+    result = []
+    for index in range(samples):
+        x = minimum + (maximum - minimum) * index / (samples - 1)
+        y = evaluate(x)
+        if y is not None and isfinite(y):
+            result.append({"x": x, "y": y})
+    return (result, degree) if len(result) >= 2 else None
+
+
+def clip_polyline(points, width, height):
+    """Liang-Barsky clipping with the source continuity threshold."""
+    segments, current = [], []
+    for a, b in zip(points, points[1:]):
+        dx, dy = b["x"] - a["x"], b["y"] - a["y"]
+        start, end = 0.0, 1.0
+        clipped = True
+        for p, q in ((-dx, a["x"]), (dx, width - a["x"]), (-dy, a["y"]), (dy, height - a["y"])):
+            if p == 0:
+                if q < 0:
+                    clipped = False
+                    break
+                continue
+            ratio = q / p
+            if p < 0:
+                if ratio > end:
+                    clipped = False
+                    break
+                start = max(start, ratio)
+            else:
+                if ratio < start:
+                    clipped = False
+                    break
+                end = min(end, ratio)
+        if not clipped:
+            if len(current) > 1:
+                segments.append(current)
+            current = []
+            continue
+        left = {"x": a["x"] + start * dx, "y": a["y"] + start * dy}
+        right = {"x": a["x"] + end * dx, "y": a["y"] + end * dy}
+        if not current:
+            current = [left, right]
+        elif abs(current[-1]["x"] - left["x"]) < 1e-9 and abs(current[-1]["y"] - left["y"]) < 1e-9:
+            current.append(right)
+        else:
+            if len(current) > 1:
+                segments.append(current)
+            current = [left, right]
+    if len(current) > 1:
+        segments.append(current)
+    return segments

fastplotpy/triangle_wireframe.py

@@ -0,0 +1,51 @@
+"""Source-named triangle wireframe resolution for surface and mesh3d."""
+
+from __future__ import annotations
+
+from math import isfinite
+from re import fullmatch
+from typing import Mapping
+
+
+def _color(value, name):
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a hexadecimal color string")
+    if fullmatch(r"#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})", value.strip()) is None:
+        raise ValueError(f"{name} must use #rgb or #rrggbb hexadecimal syntax")
+    return value.strip()
+
+
+def _validate(value, name):
+    if value is ... or type(value) is bool:
+        return None
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{name} must be boolean or an object")
+    if "show" in value and type(value["show"]) is not bool:
+        raise ValueError(f"{name}.show must be boolean")
+    if "color" in value:
+        _color(value["color"], f"{name}.color")
+    if "width" in value and (type(value["width"]) not in (int, float)
+                             or not isfinite(value["width"]) or value["width"] <= 0):
+        raise ValueError(f"{name}.width must be a positive finite number")
+    if "opacity" in value and (type(value["opacity"]) not in (int, float)
+                               or not isfinite(value["opacity"]) or not 0 <= value["opacity"] <= 1):
+        raise ValueError(f"{name}.opacity must be a finite number between 0 and 1")
+    return value
+
+
+def resolve_triangle_wireframe(plot_value, trace_value, defaults, label):
+    plot_options = _validate(plot_value, label)
+    trace_options = _validate(trace_value, f"trace.{label}")
+    selected = trace_value if trace_value is not ... else plot_value
+    if selected is ...:
+        show = defaults["wireframeShow"]
+    elif type(selected) is bool:
+        show = selected
+    else:
+        show = selected.get("show", True)
+    if not show:
+        return None
+    color = (trace_options or {}).get("color", (plot_options or {}).get("color", defaults["wireframeColor"]))
+    width = (trace_options or {}).get("width", (plot_options or {}).get("width", defaults["wireframeWidth"]))
+    opacity = (trace_options or {}).get("opacity", (plot_options or {}).get("opacity", defaults["wireframeOpacity"]))
+    return {"color": _color(color, f"{label}.color"), "width": width, "opacity": opacity}