fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/scene3d.py

@@ -0,0 +1,1215 @@
+"""Native Python scene geometry for experimental 3D chart families.
+
+World coordinates, camera projection and source identities follow the pinned
+fastPlotJs scene3d implementation. Metadata decoration is built separately.
+"""
+
+from __future__ import annotations
+
+from math import acos, ceil, cos, floor, hypot, isfinite, log10, pi, radians, sin, tan
+from re import fullmatch
+from typing import Any, Mapping
+
+from .defaults import DEFAULT_TRACE_COLORS, get_defaults
+from .color_scale import interpolate as interpolate_color, legend_ticks, resolve_stops, scale_ratio
+from .lod3d import resolve_scatter_lod, select_scatter_lod
+from .line3d_lod import resolve_line_lod, select_line_lod, source_runs
+
+
+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 _subtract(a, b):
+    return tuple(a[i] - b[i] for i in range(3))
+
+
+def _dot(a, b):
+    return sum(a[i] * b[i] for i in range(3))
+
+
+def _cross(a, b):
+    return (a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0])
+
+
+def _normalize(vector):
+    magnitude = hypot(*vector)
+    if magnitude <= 1e-12:
+        raise ValueError("scene3d camera direction must not be degenerate")
+    return tuple(item / magnitude for item in vector)
+
+
+def _camera(options: Mapping) -> dict:
+    defaults = get_defaults("scene3d")
+    source = (options.get("scene3d") or {}).get("camera") or {}
+    fields = ("projection", "eye", "target", "up", "fieldOfViewDegrees", "orthographicScale", "near", "far")
+    camera = {key: source.get(key, defaults[key]) for key in fields}
+    if camera["projection"] not in ("perspective", "orthographic"):
+        raise ValueError("scene3d.camera.projection must be 'perspective' or 'orthographic'")
+    for vector in ("eye", "target", "up"):
+        value = camera[vector]
+        if not isinstance(value, (list, tuple)) or len(value) != 3 or any(not isinstance(item, (int, float)) or not isfinite(item) for item in value):
+            raise ValueError(f"scene3d.camera.{vector} must contain exactly three finite numbers")
+    if not 1 < camera["fieldOfViewDegrees"] < 179:
+        raise ValueError("scene3d.camera.fieldOfViewDegrees must be finite and between 1 and 179")
+    if not camera["orthographicScale"] > 0:
+        raise ValueError("scene3d.camera.orthographicScale must be a positive finite number")
+    if not 0 < camera["near"] < camera["far"]:
+        raise ValueError("scene3d.camera clipping requires 0 < near < far")
+    _normalize(_cross(_normalize(_subtract(camera["target"], camera["eye"])), _normalize(camera["up"])))
+    return camera
+
+
+def _source_points(options: Mapping) -> list[list[tuple[int, tuple[float, float, float], dict]]]:
+    parsed = []
+    for trace in _traces(options):
+        if trace.get("visible") is False:
+            parsed.append([])
+            continue
+        trace_points = []
+        for index, value in enumerate(trace.get("data") or []):
+            if any(value.get(axis) is None for axis in "xyz"):
+                continue
+            point = tuple(value[axis] for axis in "xyz")
+            if any(isinstance(item, bool) or not isinstance(item, (int, float)) or not isfinite(item) for item in point):
+                raise ValueError(f"scene3d requires finite numeric traces[].data[{index}] coordinates")
+            trace_points.append((index, point, value))
+        parsed.append(trace_points)
+    return parsed
+
+
+def _domains(parsed: list, scene_options: Mapping) -> dict:
+    output = {}
+    all_points = [point for trace in parsed for _, point, _ in trace]
+    defaults = get_defaults("scene3d")
+    for index, axis in enumerate("xyz"):
+        axis_options = scene_options.get(f"{axis}Axis") or {}
+        explicit = axis_options.get("range")
+        if explicit is not None:
+            low, high = explicit["min"], explicit["max"]
+            if low == high:
+                raise ValueError(f"scene3d.{axis}Axis.range must have distinct endpoints")
+        elif not all_points:
+            low, high = -1, 1
+        else:
+            values = [point[index] for point in all_points]
+            low, high = min(values), max(values)
+            if low == high:
+                half = max(.5, abs(low) * .05)
+                low, high = low - half, high + half
+            else:
+                padding = (high - low) * axis_options.get("padding", defaults["axisPadding"])
+                low, high = low - padding, high + padding
+        output[axis] = {"min": low, "max": high}
+    return output
+
+
+def _world(point, domains):
+    return tuple((point[index] - domains[axis]["min"]) / (domains[axis]["max"] - domains[axis]["min"]) - .5 for index, axis in enumerate("xyz"))
+
+
+class _Projector:
+    def __init__(self, camera: Mapping, width: float, height: float):
+        self.camera, self.width, self.height = camera, width, height
+        self.forward = _normalize(_subtract(camera["target"], camera["eye"]))
+        self.right = _normalize(_cross(self.forward, _normalize(camera["up"])))
+        self.up = _cross(self.right, self.forward)
+        self.aspect = width / max(1, height)
+        self.tangent = tan(radians(camera["fieldOfViewDegrees"] / 2))
+
+    def project(self, world) -> dict | None:
+        relative = _subtract(world, self.camera["eye"])
+        x, y, z = _dot(relative, self.right), _dot(relative, self.up), _dot(relative, self.forward)
+        camera = self.camera
+        if z < camera["near"] or z > camera["far"]:
+            return None
+        if camera["projection"] == "perspective":
+            half_x, half_y = z * self.tangent * self.aspect, z * self.tangent
+        else:
+            half_y = camera["orthographicScale"] / 2
+            half_x = half_y * self.aspect
+        if x < -half_x or x > half_x or y < -half_y or y > half_y:
+            return None
+        ndc_x, ndc_y = x / half_x, y / half_y
+        return {"x": (ndc_x + 1) * self.width / 2,
+                "y": (1 - ndc_y) * self.height / 2,
+                "depth": (z - camera["near"]) / (camera["far"] - camera["near"])}
+
+    def project_segment(self, first_world, second_world):
+        def to_camera(world):
+            relative = _subtract(world, self.camera["eye"])
+            return (_dot(relative, self.right), _dot(relative, self.up), _dot(relative, self.forward))
+        first, second = to_camera(first_world), to_camera(second_world)
+        camera = self.camera
+        if camera["projection"] == "perspective":
+            planes = (lambda point: point[2] - camera["near"],
+                      lambda point: camera["far"] - point[2],
+                      lambda point: point[0] + point[2] * self.tangent * self.aspect,
+                      lambda point: point[2] * self.tangent * self.aspect - point[0],
+                      lambda point: point[1] + point[2] * self.tangent,
+                      lambda point: point[2] * self.tangent - point[1])
+        else:
+            half_height = camera["orthographicScale"] / 2
+            half_width = half_height * self.aspect
+            planes = (lambda point: point[2] - camera["near"],
+                      lambda point: camera["far"] - point[2],
+                      lambda point: point[0] + half_width,
+                      lambda point: half_width - point[0],
+                      lambda point: point[1] + half_height,
+                      lambda point: half_height - point[1])
+        start_ratio, end_ratio = 0, 1
+        for plane in planes:
+            first_distance, second_distance = plane(first), plane(second)
+            if first_distance < 0 and second_distance < 0:
+                return None
+            if first_distance >= 0 and second_distance >= 0:
+                continue
+            crossing = -first_distance / (second_distance - first_distance)
+            if first_distance < 0:
+                start_ratio = max(start_ratio, crossing)
+            else:
+                end_ratio = min(end_ratio, crossing)
+            if start_ratio > end_ratio:
+                return None
+        def project_camera(point):
+            if camera["projection"] == "perspective":
+                ndc_x = point[0] / (point[2] * self.tangent * self.aspect)
+                ndc_y = point[1] / (point[2] * self.tangent)
+            else:
+                ndc_x = point[0] / half_width
+                ndc_y = point[1] / half_height
+            return {"x": (max(-1, min(1, ndc_x)) + 1) * self.width / 2,
+                    "y": (1 - max(-1, min(1, ndc_y))) * self.height / 2,
+                    "depth": max(0, min(1, (point[2] - camera["near"]) / (camera["far"] - camera["near"])))}
+        return {"from": project_camera(_interpolate3(first, second, start_ratio)),
+                "to": project_camera(_interpolate3(first, second, end_ratio)),
+                "startRatio": start_ratio, "endRatio": end_ratio}
+
+
+def _interpolate3(first, second, ratio):
+    return tuple(first[index] + (second[index] - first[index]) * ratio for index in range(3))
+
+
+def _clip_domain_segment(first, second):
+    start_ratio, end_ratio = 0, 1
+    delta = _subtract(second, first)
+    for axis in range(3):
+        origin, direction = first[axis], delta[axis]
+        if abs(direction) < 1e-12:
+            if origin < -.5 or origin > .5:
+                return None
+            continue
+        lower = (-.5 - origin) / direction
+        upper = (.5 - origin) / direction
+        start_ratio = max(start_ratio, min(lower, upper))
+        end_ratio = min(end_ratio, max(lower, upper))
+        if start_ratio > end_ratio:
+            return None
+    return {"from": _interpolate3(first, second, start_ratio),
+            "to": _interpolate3(first, second, end_ratio),
+            "startRatio": start_ratio, "endRatio": end_ratio}
+
+
+def _smooth_line_point(start_control, start, end, end_control, ratio):
+    if ratio <= 0:
+        return start
+    if ratio >= 1:
+        return end
+    squared, cubed = ratio * ratio, ratio * ratio * ratio
+    def coordinate(axis):
+        value = .5 * (2 * start[axis]
+                      + (-start_control[axis] + end[axis]) * ratio
+                      + (2 * start_control[axis] - 5 * start[axis] + 4 * end[axis] - end_control[axis]) * squared
+                      + (-start_control[axis] + 3 * start[axis] - 3 * end[axis] + end_control[axis]) * cubed)
+        return min(max(value, min(start[axis], end[axis])), max(start[axis], end[axis]))
+    return tuple(coordinate(axis) for axis in range(3))
+
+
+def _segment(projector, kind, start, end, axis=None):
+    first, second = projector.project(start), projector.project(end)
+    if first is None or second is None:
+        return None
+    result = {"kind": kind}
+    if axis is not None:
+        result["axis"] = axis
+    result.update({"x1": first["x"], "y1": first["y"], "depth1": first["depth"],
+                   "x2": second["x"], "y2": second["y"], "depth2": second["depth"]})
+    return result
+
+
+def _guides(options, projector):
+    defaults = get_defaults("scene3d")
+    scene = options.get("scene3d") or {}
+    segments, labels = [], []
+    steps = scene.get("gridSteps", defaults["gridSteps"])
+    if not isinstance(steps, int) or not 1 <= steps <= 20:
+        raise ValueError("scene3d.gridSteps must be an integer between 1 and 20")
+    if scene.get("showGrid", defaults["showGrid"]):
+        for step in range(steps + 1):
+            coordinate = -.5 + step / steps
+            for start, end in (((coordinate, -.5, -.5), (coordinate, -.5, .5)),
+                               ((-.5, -.5, coordinate), (.5, -.5, coordinate))):
+                segment = _segment(projector, "grid", start, end)
+                if segment is not None:
+                    segments.append(segment)
+    if scene.get("showAxes", defaults["showAxes"]):
+        for axis, endpoint in (("x", (.5, -.5, -.5)), ("y", (-.5, .5, -.5)), ("z", (-.5, -.5, .5))):
+            axis_options = scene.get(f"{axis}Axis") or {}
+            if axis_options.get("show") is False:
+                continue
+            segment = _segment(projector, "axis", (-.5, -.5, -.5), endpoint, axis)
+            projected = projector.project(endpoint)
+            if segment is not None:
+                segments.append(segment)
+            if projected is not None:
+                labels.append({"axis": axis, "text": axis_options.get("title") or axis.upper(), **projected})
+    return segments, labels
+
+
+def _tick_text(value, step, decimals, defaults):
+    normalized = 0 if abs(value) < max(defaults["axisTickZeroToleranceFloor"], abs(step) * defaults["axisTickStepFloor"]) else value
+    if decimals is not None:
+        return f"{normalized:.{decimals}f}"
+    magnitude = abs(normalized)
+    if magnitude >= defaults["axisTickScientificUpperMagnitude"] or 0 < magnitude < defaults["axisTickScientificLowerMagnitude"]:
+        return f"{normalized:.{defaults['axisTickScientificDecimals']}e}"
+    precision = max(0, min(defaults["axisTickAutoMaxDecimals"], ceil(-log10(max(abs(step), defaults["axisTickStepFloor"]))) + 1))
+    return f"{normalized:.{precision}f}".rstrip("0").rstrip(".")
+
+
+def _ticks(options, domains, projector):
+    defaults = get_defaults("scene3d")
+    scene = options.get("scene3d") or {}
+    if scene.get("showAxes") is False:
+        return [], []
+    segments, candidates = [], []
+    for axis in "xyz":
+        axis_options = scene.get(f"{axis}Axis") or {}
+        if axis_options.get("show") is False:
+            continue
+        count = axis_options.get("tickCount", defaults["axisTickCount"])
+        if not isinstance(count, int) or count < defaults["axisTickMinCount"] or count > defaults["axisTickMaxCount"]:
+            raise ValueError("scene3d axis tickCount out of range")
+        low, high = domains[axis]["min"], domains[axis]["max"]
+        step = (high - low) / (count - 1)
+        for index in range(count):
+            ratio = index / (count - 1)
+            coordinate = -.5 + ratio
+            offset = defaults["axisTickWorldLength"]
+            if axis == "x":
+                start, end = (coordinate, -.5, -.5), (coordinate, -.5 - offset, -.5)
+                screen_offset = (0, defaults["axisTickLabelOffset"])
+            elif axis == "y":
+                start, end = (-.5, coordinate, -.5), (-.5 - offset, coordinate, -.5)
+                screen_offset = (-defaults["axisTickLabelOffset"], 0)
+            else:
+                start, end = (-.5, -.5, coordinate), (-.5 - offset, -.5, coordinate)
+                screen_offset = (defaults["axisTickLabelOffset"], defaults["axisTickLabelOffset"] / 2)
+            segment, anchor = _segment(projector, "tick", start, end, axis), projector.project(end)
+            if segment is None or anchor is None:
+                continue
+            segments.append(segment)
+            if axis_options.get("showTickLabels") is False:
+                continue
+            value = low + (high - low) * ratio
+            candidates.append({"axis": axis, "value": value,
+                               "text": _tick_text(value, step, axis_options.get("tickDecimals"), defaults),
+                               "x": anchor["x"] + screen_offset[0], "y": anchor["y"] + screen_offset[1],
+                               "depth": anchor["depth"]})
+    labels, occupied = [], []
+    for candidate in candidates:
+        label_width = max(defaults["axisTickLabelMinWidth"], len(candidate["text"]) * defaults["axisTickLabelGlyphWidth"])
+        half_height = defaults["axisTickLabelLineHeight"] / 2
+        box = (candidate["x"] - label_width / 2, candidate["y"] - half_height,
+               candidate["x"] + label_width / 2, candidate["y"] + half_height)
+        inset = defaults["axisTickLabelBoundsInset"]
+        gap = defaults["axisTickLabelMinGap"]
+        if box[0] < inset or box[2] > options["width"] - inset or box[1] < inset or box[3] > options["height"] - inset:
+            continue
+        if any(box[0] < current[2] + gap and box[2] + gap > current[0] and box[1] < current[3] + gap and box[3] + gap > current[1] for current in occupied):
+            continue
+        occupied.append(box)
+        labels.append(candidate)
+    return segments, labels
+
+
+def _metadata(options, camera, domains, count, interaction_count, width, height):
+    defaults = get_defaults("scene3d")
+    scene_options = options.get("scene3d") or {}
+    projector = _Projector(camera, width, height)
+    segments, labels = _guides(options, projector)
+    tick_segments, tick_labels = _ticks(options, domains, projector)
+    segments.extend(tick_segments)
+    return {"experimental": True, "subplotId": "scene3d", "handedness": "right-handed",
+            "depthOrder": "far-to-near", "sourcePointCount": count,
+            "interactionItemCount": interaction_count, "projection": camera["projection"],
+            "camera": camera, "domains": domains,
+            "bounds": {"left": 0, "top": 0, "right": width, "bottom": height},
+            "segments": segments, "labels": labels, "tickLabels": tick_labels,
+            "tickLabelFont": defaults["axisTickLabelFont"],
+            "axisColor": scene_options.get("axisColor", defaults["axisColor"]),
+            "gridColor": scene_options.get("gridColor", defaults["gridColor"]),
+            "axisLineWidth": scene_options.get("axisLineWidth", defaults["axisLineWidth"]),
+            "gridLineWidth": scene_options.get("gridLineWidth", defaults["gridLineWidth"]),
+            "renderer": {"requested": scene_options.get("renderer", defaults["renderer"]), "resolved": "renderer-neutral"}}
+
+
+def _scatter_encoding(options, parsed):
+    settings = options.get("scatter3d") or {}
+    defaults = get_defaults("scatter3d")
+    all_inputs = [item for trace in parsed for _, _, item in trace]
+    result = {}
+    for name, field in (("colorScale", "value"), ("sizeScale", "size"),
+                        ("opacityScale", "opacity")):
+        raw = settings.get(name)
+        if name == "colorScale":
+            if raw is None:
+                continue
+            if not isinstance(raw, Mapping):
+                raise ValueError("scatter3d.colorScale must be an object")
+            enabled = True
+        else:
+            source = raw if isinstance(raw, Mapping) else {}
+            enabled = raw if isinstance(raw, bool) else source.get("enabled", True) if raw is not None else defaults[name]["enabled"]
+            if not enabled:
+                continue
+            raw = source
+        label = f"scatter3d.{name}"
+        if name == "colorScale":
+            value_scale = raw.get("valueScale", defaults["valueScale"])
+            if value_scale not in ("linear", "logarithmic"):
+                raise ValueError(f"{label}.valueScale must be 'linear' or 'logarithmic'")
+            low_color = raw.get("lowColor", defaults["lowColor"])
+            high_color = raw.get("highColor", defaults["highColor"])
+            for key, value in (("lowColor", low_color), ("highColor", high_color)):
+                if not isinstance(value, str) or not value.strip():
+                    raise ValueError(f"{label}.{key} must be a non-empty string")
+            stops = resolve_stops(raw.get("colorStops"), low_color.strip(), high_color.strip(),
+                                  f"{label}.colorStops")
+        elif name == "sizeScale":
+            minimum = raw.get("minSize", defaults[name]["minSize"])
+            maximum = raw.get("maxSize", defaults[name]["maxSize"])
+            if not isinstance(minimum, (int, float)) or not isfinite(minimum) or minimum < get_defaults("markers")["minSize"]:
+                raise ValueError(f"{label}.minSize must be >= {get_defaults('markers')['minSize']}")
+            if not isinstance(maximum, (int, float)) or not isfinite(maximum) or maximum < minimum:
+                raise ValueError(f"{label}.maxSize must be >= minSize")
+        else:
+            minimum = raw.get("minOpacity", defaults[name]["minOpacity"])
+            maximum = raw.get("maxOpacity", defaults[name]["maxOpacity"])
+            for key, value in (("minOpacity", minimum), ("maxOpacity", maximum)):
+                if not isinstance(value, (int, float)) or not isfinite(value) or not 0 <= value <= 1:
+                    raise ValueError(f"{label}.{key} must be finite and between 0 and 1")
+            if maximum < minimum:
+                raise ValueError(f"{label}.maxOpacity must be >= minOpacity")
+        low, high = raw.get("minValue"), raw.get("maxValue")
+        for key, value in (("minValue", low), ("maxValue", high)):
+            if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value)):
+                raise ValueError(f"{label}.{key} must be finite")
+        if low is not None and high is not None and low > high:
+            raise ValueError(f"{label}.minValue must be <= maxValue")
+        if name == "colorScale" and value_scale == "logarithmic" and (
+                low is not None and low <= 0 or high is not None and high <= 0):
+            raise ValueError(f"{label} logarithmic values and bounds must be > 0")
+        values = []
+        for item in all_inputs:
+            value = item.get(field)
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                raise ValueError(f"{label} points require a finite numeric '{field}' field")
+            values.append(value)
+        if not values:
+            continue
+        domain = {"min": min(values) if low is None else low,
+                  "max": max(values) if high is None else high}
+        if domain["min"] > domain["max"]:
+            raise ValueError(f"{label}.minValue must be <= maxValue")
+        if name == "colorScale" and value_scale == "logarithmic" and (
+                domain["min"] <= 0 or domain["max"] <= 0 or any(value <= 0 for value in values)):
+            raise ValueError(f"{label} logarithmic values and bounds must be > 0")
+        entry = {"domain": domain}
+        if name == "colorScale":
+            entry.update({"valueScale": value_scale, "stops": stops})
+        else:
+            entry.update({"min": minimum, "max": maximum})
+        result[name] = entry
+    return result
+
+
+def _scatter_legend(width, height, scale):
+    defaults = get_defaults("scatter3d")
+    domain = scale["domain"]
+    low, high = domain["min"], domain["max"]
+    values = legend_ticks(low, high, defaults["legendTickCount"], [], scale["valueScale"])
+    ticks = []
+    for index, value in enumerate(values):
+        text = str(int(value)) if float(value).is_integer() else format(value, ".4g")
+        ratio = index / (len(values) - 1) if low == high else scale_ratio(value, low, high, scale["valueScale"])
+        ticks.append({"value": value, "text": text, "y": ratio})
+    label_width = max(len(defaults["legendTitle"]), *(len(tick["text"]) for tick in ticks)) * defaults["legendGlyphWidth"]
+    labels_visible = width >= (defaults["legendOffset"] * 2 + defaults["legendWidth"] +
+                               defaults["legendLabelGap"] + label_width) and height >= defaults["legendMinimumLabelHeight"]
+    horizontal = min(defaults["legendOffset"], max(0, width - defaults["legendWidth"]))
+    vertical = min(defaults["legendOffset"], max(0, (height - 1) / 2))
+    x = (width - defaults["legendOffset"] - defaults["legendWidth"] - defaults["legendLabelGap"] - label_width
+         if labels_visible else max(0, width - horizontal - defaults["legendWidth"]))
+    return {"x": x, "y": vertical, "width": min(defaults["legendWidth"], width),
+            "height": min(defaults["legendHeight"], max(1, height - vertical * 2)),
+            "minValue": low, "maxValue": high, "lowColor": scale["stops"][0]["color"],
+            "highColor": scale["stops"][-1]["color"], "colorStops": scale["stops"],
+            "title": defaults["legendTitle"], "ticks": ticks, "font": defaults["legendFont"],
+            "color": defaults["legendColor"], "labelGap": defaults["legendLabelGap"],
+            "labelWidth": label_width, "labelsVisible": labels_visible}
+
+
+def scatter3d_scene(options: Mapping, width: float, height: float) -> dict:
+    from .lighting3d import resolve_scene3d_lighting
+    if resolve_scene3d_lighting((options.get("scene3d") or {}).get("lighting", ...)) is not None:
+        raise ValueError("scene3d.lighting is currently supported only for surface and mesh3d")
+    camera = _camera(options)
+    scene_options = options.get("scene3d") or {}
+    parsed = _source_points(options)
+    encodings = _scatter_encoding(options, parsed)
+    count = sum(len(trace) for trace in parsed)
+    max_points = scene_options.get("maxPoints", get_defaults("scene3d")["maxPoints"])
+    if count > max_points:
+        raise ValueError(f"scatter3d visible point count {count} exceeds scene3d.maxPoints {max_points}")
+    domains = _domains(parsed, scene_options)
+    lod = resolve_scatter_lod((options.get("scatter3d") or {}).get("lod", ...))
+    selected, candidate_count = select_scatter_lod(parsed, domains, lod["maxPoints"]) if lod else (None, None)
+    projector = _Projector(camera, width, height)
+    traces = _traces(options)
+    primitives = []
+    legend_assigned = False
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        settings = dict(get_defaults("scatter3d"))
+        settings.update(options.get("scatter3d") or {})
+        settings.update(trace.get("scatter3d") or {})
+        color = ((trace.get("lineStyle") or {}).get("color") or trace.get("color")
+                 or (options.get("lineStyle") or {}).get("color")
+                 or ((((options.get("style") or {}).get("trace") or {}).get("line") or {}).get("color"))
+                 or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)])
+        shape = settings["markerShape"]
+        if shape not in ("circle", "square", "diamond", "triangle", "pentagon", "hexagon"):
+            raise ValueError("scatter3d.markerShape must be 'circle', 'square', 'diamond', 'triangle', 'pentagon', or 'hexagon'")
+        marker_size = settings["markerSize"]
+        if isinstance(marker_size, bool) or not isinstance(marker_size, (int, float)) or not isfinite(marker_size) or marker_size <= 0:
+            raise ValueError("scatter3d.markerSize must be a positive finite number")
+        marker_opacity = settings["markerOpacity"]
+        if isinstance(marker_opacity, bool) or not isinstance(marker_opacity, (int, float)) or not isfinite(marker_opacity) or not 0 <= marker_opacity <= 1:
+            raise ValueError("scatter3d.markerOpacity must be finite and between 0 and 1")
+        points = []
+        for source_index, source, source_input in parsed[trace_index]:
+            if selected is not None and (trace_index, source_index) not in selected:
+                continue
+            if any(source[axis_index] < min(domains[axis]["min"], domains[axis]["max"])
+                   or source[axis_index] > max(domains[axis]["min"], domains[axis]["max"])
+                   for axis_index, axis in enumerate("xyz")):
+                continue
+            projected = projector.project(_world(source, domains))
+            if projected is None:
+                continue
+            point = {**projected, "sourceIndex": source_index,
+                           "sourceX": source[0], "sourceY": source[1], "sourceZ": source[2],
+                           "radius": marker_size, "opacity": marker_opacity,
+                           "fillColor": color, "markerShape": shape}
+            for name, field, target in (("colorScale", "value", "colorValue"),
+                                        ("sizeScale", "size", "sizeValue"),
+                                        ("opacityScale", "opacity", "opacityValue")):
+                scale = encodings.get(name)
+                if scale is None:
+                    continue
+                value = source_input[field]
+                point[target] = value
+                domain = scale["domain"]
+                if name == "colorScale":
+                    point["fillColor"] = interpolate_color(value, domain["min"], domain["max"],
+                                                            scale["stops"], scale["valueScale"])
+                else:
+                    if domain["min"] == domain["max"]:
+                        value_out = (scale["min"] + scale["max"]) / 2
+                    else:
+                        ratio = max(0, min(1, (value - domain["min"]) / (domain["max"] - domain["min"])))
+                        value_out = scale["min"] + (scale["max"] - scale["min"]) * ratio
+                    point["radius" if name == "sizeScale" else "opacity"] = value_out
+            points.append(point)
+        points.sort(key=lambda point: (-point["depth"], point["sourceIndex"]))
+        primitive = {"type": "scatter3d", "points": [{"x": point["x"], "y": point["y"]} for point in points],
+                           "scatter3dPoints": points, "color": color, "lineWidth": 0,
+                           "traceIndex": trace_index, "subplot": "scene3d",
+                           "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}}
+        if encodings.get("colorScale") and settings.get("colorScaleLegend", get_defaults("scatter3d")["colorScaleLegend"]) and not legend_assigned:
+            primitive["scene3dColorScaleLegend"] = _scatter_legend(width, height, encodings["colorScale"])
+            legend_assigned = True
+        primitives.append(primitive)
+    metadata = _metadata(options, camera, domains, count, len(selected) if selected is not None else count, width, height)
+    if lod is not None:
+        metadata["scatter3dLod"] = {"strategy": lod["strategy"], "maxPoints": lod["maxPoints"],
+                                    "candidatePointCount": candidate_count, "sampledPointCount": len(selected)}
+    return {"width": width, "height": height, "primitives": primitives, "scene3d": metadata}
+
+
+def line3d_scene(options: Mapping, width: float, height: float) -> dict:
+    from .lighting3d import resolve_scene3d_lighting
+    if resolve_scene3d_lighting((options.get("scene3d") or {}).get("lighting", ...)) is not None:
+        raise ValueError("scene3d.lighting is currently supported only for surface and mesh3d")
+    camera = _camera(options)
+    parsed = _source_points(options)
+    domains = _domains(parsed, options.get("scene3d") or {})
+    projector = _Projector(camera, width, height)
+    count = sum(len(trace) for trace in parsed)
+    max_points = (options.get("scene3d") or {}).get("maxPoints", get_defaults("scene3d")["maxPoints"])
+    if count > max_points:
+        raise ValueError(f"line3d visible point count {count} exceeds scene3d.maxPoints {max_points}")
+    line_options = options.get("line3d") or {}
+    maximum = line_options.get("maxSegments", get_defaults("line3d")["maxSegments"])
+    if type(maximum) is not int or maximum < 1 or maximum > 2_000_000:
+        raise ValueError("line3d.maxSegments must be an integer between 1 and 2000000")
+    lod = resolve_line_lod(line_options.get("lod", ...))
+    runs = source_runs(parsed)
+    if lod:
+        selected_runs, candidate_segments, sampled_segments, sampled_points = select_line_lod(
+            runs, domains, lod["maxSourceSegments"])
+    else:
+        selected_runs, candidate_segments, sampled_segments, sampled_points = runs, None, None, None
+    traces = _traces(options)
+    interpolations = []
+    for trace in traces:
+        interpolation = (trace.get("line3d") or {}).get("interpolation", line_options.get(
+            "interpolation", get_defaults("line3d")["interpolation"]))
+        if interpolation not in ("linear", "smooth"):
+            raise ValueError("line3d.interpolation must be 'linear' or 'smooth'")
+        interpolations.append(interpolation)
+    samples = get_defaults("line3d")["smoothSamplesPerSegment"]
+    prepared_segments = sum((len(run["points"]) - 1) * (samples if interpolations[trace_index] == "smooth" else 1)
+                            for trace_index, trace_runs in enumerate(selected_runs)
+                            if traces[trace_index].get("visible") is not False for run in trace_runs)
+    smooth_enabled = any(interpolation == "smooth" and traces[index].get("visible") is not False
+                         for index, interpolation in enumerate(interpolations))
+    if prepared_segments > maximum:
+        raise ValueError(f"line3d prepared segment count {prepared_segments} exceeds line3d.maxSegments {maximum}")
+    primitives = []
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        settings = dict(get_defaults("line3d"))
+        settings.update(options.get("line3d") or {})
+        settings.update(trace.get("line3d") or {})
+        if (isinstance(settings["lineWidth"], bool) or not isinstance(settings["lineWidth"], (int, float))
+                or not isfinite(settings["lineWidth"]) or settings["lineWidth"] <= 0):
+            raise ValueError("line3d.lineWidth must be a positive finite number")
+        if (isinstance(settings["lineOpacity"], bool) or not isinstance(settings["lineOpacity"], (int, float))
+                or not isfinite(settings["lineOpacity"]) or not 0 <= settings["lineOpacity"] <= 1):
+            raise ValueError("line3d.lineOpacity must be finite and between 0 and 1")
+        color = ((trace.get("lineStyle") or {}).get("color") or trace.get("color")
+                 or (options.get("lineStyle") or {}).get("color")
+                 or ((((options.get("style") or {}).get("trace") or {}).get("line") or {}).get("color"))
+                 or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)])
+        interpolation = interpolations[trace_index]
+        sample_count = samples if interpolation == "smooth" else 1
+        segments = []
+        for run in selected_runs[trace_index]:
+            run_points = run["points"]
+            for pair_index, (left, right) in enumerate(zip(run_points, run_points[1:])):
+                source_index_1, source_1, _ = left
+                source_index_2, source_2, _ = right
+                start_control = run_points[pair_index - 1][1] if pair_index > 0 else source_1
+                end_control = run_points[pair_index + 2][1] if pair_index + 2 < len(run_points) else source_2
+                for sample in range(sample_count):
+                    sample_start, sample_end = sample / sample_count, (sample + 1) / sample_count
+                    sampled_from = (_smooth_line_point(start_control, source_1, source_2, end_control, sample_start)
+                                    if interpolation == "smooth" else source_1)
+                    sampled_to = (_smooth_line_point(start_control, source_1, source_2, end_control, sample_end)
+                                  if interpolation == "smooth" else source_2)
+                    clipped = _clip_domain_segment(_world(sampled_from, domains), _world(sampled_to, domains))
+                    if clipped is None:
+                        continue
+                    projected = projector.project_segment(clipped["from"], clipped["to"])
+                    if projected is None:
+                        continue
+                    raw_start = clipped["startRatio"] + (clipped["endRatio"] - clipped["startRatio"]) * projected["startRatio"]
+                    raw_end = clipped["startRatio"] + (clipped["endRatio"] - clipped["startRatio"]) * projected["endRatio"]
+                    first, second = projected["from"], projected["to"]
+                    source_from = _interpolate3(sampled_from, sampled_to, raw_start)
+                    source_to = _interpolate3(sampled_from, sampled_to, raw_end)
+                    segment = {"x1": first["x"], "y1": first["y"], "depth1": first["depth"],
+                               "x2": second["x"], "y2": second["y"], "depth2": second["depth"],
+                               "sourceIndex1": source_index_1, "sourceIndex2": source_index_2,
+                               "sourceX1": source_from[0], "sourceY1": source_from[1], "sourceZ1": source_from[2],
+                               "sourceX2": source_to[0], "sourceY2": source_to[1], "sourceZ2": source_to[2],
+                               "opacity": settings["lineOpacity"]}
+                    if interpolation == "smooth":
+                        segment["sourceRatio1"] = sample_start + (sample_end - sample_start) * raw_start
+                        segment["sourceRatio2"] = sample_start + (sample_end - sample_start) * raw_end
+                    segments.append(segment)
+        segments.sort(key=lambda segment: (-max(segment["depth1"], segment["depth2"]), segment["sourceIndex1"],
+                                           segment.get("sourceRatio1", 0)))
+        primitive = {"type": "line3d", "points": [point for segment in segments for point in ({"x": segment["x1"], "y": segment["y1"]}, {"x": segment["x2"], "y": segment["y2"]})],
+                     "line3dSegments": segments, "color": color, "lineWidth": settings["lineWidth"],
+                     "lineOpacity": settings["lineOpacity"], "traceIndex": trace_index,
+                     "subplot": "scene3d", "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}}
+        if interpolation == "smooth":
+            primitive["interpolation"] = "smooth"
+        primitives.append(primitive)
+    interaction_count = (sampled_points if lod else count) + prepared_segments if smooth_enabled else (sampled_points if lod else count)
+    metadata = _metadata(options, camera, domains, count, interaction_count, width, height)
+    if smooth_enabled:
+        metadata["preparedLineSegmentCount"] = prepared_segments
+    if lod:
+        metadata["line3dLod"] = {"strategy": lod["strategy"], "maxSourceSegments": lod["maxSourceSegments"],
+                                 "candidateSourceSegmentCount": candidate_segments,
+                                 "sampledSourceSegmentCount": sampled_segments,
+                                 "sampledPointCount": sampled_points,
+                                 "preparedSegmentCount": prepared_segments}
+    return {"width": width, "height": height, "primitives": primitives, "scene3d": metadata}
+
+
+def _triangle(source_vertices, projector, fill_color, opacity, source_key, source_identity, camera, mesh=False):
+    world = [vertex[1] for vertex in source_vertices]
+    raw_normal = _cross(_subtract(world[1], world[0]), _subtract(world[2], world[0]))
+    magnitude = hypot(*raw_normal)
+    if magnitude <= 2.220446049250313e-16:
+        return None
+    normal = [value / magnitude for value in raw_normal]
+    vertices = []
+    for source_index, point, source in source_vertices:
+        projected = projector.project(point)
+        if projected is None:
+            return None
+        vertices.append({**projected, "sourceIndex": source_index,
+                         "sourceX": source[0], "sourceY": source[1], "sourceZ": source[2]})
+    centroid = tuple(sum(point[index] / 3 for point in world) for index in range(3))
+    view = _subtract(camera["eye"], camera["target"] if camera["projection"] == "orthographic" else centroid)
+    output = {"vertices": vertices, source_key: source_identity, "normal": normal,
+              "fillColor": fill_color, "opacity": opacity,
+              "depth": sum(vertex["depth"] for vertex in vertices) / 3}
+    if mesh:
+        output["frontFacing"] = _dot(normal, view) > 1e-12
+    return output
+
+
+def _triangle_fragments(source_vertices, domains, projector, fill_color, opacity,
+                        source_key, source_identity, camera, mesh=False):
+    from .polygon_clip3d import clip_domain_triangle, project_polygon
+
+    world = [vertex[1] for vertex in source_vertices]
+    raw_normal = _cross(_subtract(world[1], world[0]), _subtract(world[2], world[0]))
+    magnitude = hypot(*raw_normal)
+    if magnitude <= 2.220446049250313e-16:
+        return []
+    normal = [value / magnitude for value in raw_normal]
+    source = [{"world": position, "sourceIndex": source_index,
+               "sourceX": point[0], "sourceY": point[1], "sourceZ": point[2]}
+              for source_index, position, point in source_vertices]
+    projected = project_polygon(clip_domain_triangle(source, domains), projector)
+    centroid = tuple(sum(point[index] / 3 for point in world) for index in range(3))
+    view = _subtract(camera["eye"], camera["target"] if camera["projection"] == "orthographic" else centroid)
+    result = []
+    for item in projected:
+        vertices = item["vertices"]
+        triangle = {"vertices": vertices, source_key: source_identity, "normal": normal,
+                    "fillColor": fill_color, "opacity": opacity,
+                    "depth": sum(vertex["depth"] for vertex in vertices) / 3,
+                    "_boundaryEdges": item["boundaryEdges"]}
+        if mesh:
+            triangle["frontFacing"] = _dot(normal, view) > 1e-12
+        result.append(triangle)
+    return result
+
+
+def _color(value, low, high, start, end):
+    def parse(color):
+        if len(color) == 7 and color.startswith("#"):
+            return [int(color[index:index + 2], 16) for index in (1, 3, 5)]
+        return None
+    first, last = parse(start), parse(end)
+    if first is None or last is None:
+        return end if value >= high else start
+    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(first, last)]
+    return f"rgb({channels[0]}, {channels[1]}, {channels[2]})"
+
+
+def _hex_channels(value, label):
+    if not isinstance(value, str):
+        raise ValueError(f"{label} must be a hexadecimal color string")
+    match = fullmatch(r"#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})", value.strip())
+    if match is None:
+        raise ValueError(f"{label} must use #rgb or #rrggbb hexadecimal syntax")
+    body = "".join(digit * 2 for digit in match.group(1)) if len(match.group(1)) == 3 else match.group(1)
+    return [int(body[index:index + 2], 16) for index in (0, 2, 4)]
+
+
+def _surface_legend(width, height, low, high, settings, color_stops=None):
+    defaults = get_defaults("surface")
+    color_stops = color_stops or [{"offset": 0, "color": settings["lowColor"]},
+                                  {"offset": 1, "color": settings["highColor"]}]
+    count = defaults["legendTickCount"]
+    values = [low + (high - low) * index / (count - 1) for index in range(count)]
+    ticks = [{"value": value, "text": format(float(f"{value:.4g}"), "g"),
+              "y": index / (count - 1)} for index, value in enumerate(values)]
+    label_width = max(len(defaults["legendTitle"]), *(len(item["text"]) for item in ticks)) * defaults["legendGlyphWidth"]
+    visible = width >= (defaults["legendOffset"] * 2 + defaults["legendWidth"] + defaults["legendLabelGap"] + label_width) and height >= defaults["legendMinimumLabelHeight"]
+    horizontal_offset = min(defaults["legendOffset"], max(0, width - defaults["legendWidth"]))
+    vertical_offset = min(defaults["legendOffset"], max(0, (height - 1) / 2))
+    x = (width - defaults["legendOffset"] - defaults["legendWidth"] - defaults["legendLabelGap"] - label_width) if visible else max(0, width - horizontal_offset - defaults["legendWidth"])
+    return {"x": x, "y": vertical_offset, "width": min(defaults["legendWidth"], width),
+            "height": min(defaults["legendHeight"], max(1, height - vertical_offset * 2)),
+            "minValue": low, "maxValue": high, "lowColor": color_stops[0]["color"],
+            "highColor": color_stops[-1]["color"],
+            "colorStops": color_stops,
+            "title": defaults["legendTitle"], "ticks": ticks, "font": defaults["legendFont"],
+            "color": defaults["legendColor"], "labelGap": defaults["legendLabelGap"],
+            "labelWidth": label_width, "labelsVisible": visible}
+
+
+def surface_scene(options: Mapping, width: float, height: float) -> dict:
+    from .surface_lod import resolve_surface_lod, select_surface_lod_grids
+    from .triangle_wireframe import resolve_triangle_wireframe
+    from .lighting3d import resolve_scene3d_lighting, resolve_triangle_lighting
+    from .surface_contours import (resolve_surface_contours, contour_source_segment,
+                                   contour_segment_key, project_contour_segment)
+
+    camera = _camera(options)
+    lighting = resolve_scene3d_lighting((options.get("scene3d") or {}).get("lighting", ...))
+    settings = dict(get_defaults("surface"))
+    settings.update(options.get("surface") or {})
+    lod = resolve_surface_lod((options.get("surface") or {}).get("lod", ...))
+    color_stops = resolve_stops(settings.get("colorStops"), settings["lowColor"],
+                                settings["highColor"], "surface.colorStops")
+    max_points = (options.get("scene3d") or {}).get("maxPoints", get_defaults("scene3d")["maxPoints"])
+    if type(max_points) is not int or not 1 <= max_points <= 1_000_000:
+        raise ValueError("scene3d.maxPoints must be an integer between 1 and 1000000")
+    max_triangles = settings["maxTriangles"]
+    if type(max_triangles) is not int or not 1 <= max_triangles <= 2_000_000:
+        raise ValueError("surface.maxTriangles must be an integer between 1 and 2000000")
+    max_contours = settings["maxContourSegments"]
+    if type(max_contours) is not int or not 1 <= max_contours <= 2_000_000:
+        raise ValueError("surface.maxContourSegments must be an integer between 1 and 2000000")
+    missing = settings["missingCells"]
+    if missing not in ("gap", "zero"):
+        raise ValueError("surface.missingCells must be 'gap' or 'zero'")
+    parsed = []
+    prepared_count = count = 0
+    for trace in _traces(options):
+        if trace.get("visible") is False:
+            parsed.append([])
+            continue
+        values = []
+        for index, value in enumerate(trace.get("data") or []):
+            prepared_count += 1
+            if prepared_count > max_points:
+                raise ValueError(f"surface grid point count {prepared_count} exceeds scene3d.maxPoints {max_points}")
+            if value.get("x") is None or value.get("y") is None:
+                raise ValueError(f"surface regular grid requires x and y at traces[].data[{index}]")
+            x, y = value["x"], value["y"]
+            z = 0 if value.get("z") is None and missing == "zero" else value.get("z")
+            for axis, coordinate in (("x", x), ("y", y), ("z", z)):
+                if coordinate is not None and (type(coordinate) not in (int, float) or not isfinite(coordinate)):
+                    raise ValueError(f"traces[].data[{index}].{axis} must be a finite number")
+            if z is not None:
+                count += 1
+                if count > max_points:
+                    raise ValueError(f"surface visible point count {count} exceeds scene3d.maxPoints {max_points}")
+            values.append((index, (x, y, z), value))
+        xs = {point[0] for _, point, _ in values}
+        ys = {point[1] for _, point, _ in values}
+        if len(values) != len(xs) * len(ys):
+            raise ValueError("surface data must provide exactly one point for every regular x/y grid coordinate")
+        if len({(point[0], point[1]) for _, point, _ in values}) != len(values):
+            raise ValueError("surface data must not contain duplicate x/y grid coordinates")
+        parsed.append(values)
+    visible = [[item for item in trace if item[1][2] is not None] for trace in parsed]
+    domains = _domains(visible, options.get("scene3d") or {})
+    projector = _Projector(camera, width, height)
+    lod_points = []
+    for trace in parsed:
+        lod_points.append([{"sourceIndex": index, "x": source[0], "y": source[1], "z": source[2]}
+                           for index, source, _ in trace])
+    lod_selection = select_surface_lod_grids(lod_points, lod["maxCells"]) if lod else None
+    z_values = [point[2] for trace in visible for _, point, _ in trace]
+    z_low, z_high = (min(z_values), max(z_values)) if z_values else (0, 0)
+    if not z_values:
+        z_high = 1
+    for name in ("minValue", "maxValue"):
+        if name in (options.get("surface") or {}):
+            value = settings[name]
+            if type(value) not in (int, float) or not isfinite(value):
+                raise ValueError(f"scene3d requires finite numeric surface.{name}")
+    z_low = settings.get("minValue", z_low)
+    z_high = settings.get("maxValue", z_high)
+    if z_low > z_high:
+        raise ValueError("surface color scale requires minValue <= maxValue")
+    contours_by_trace = [resolve_surface_contours((options.get("surface") or {}).get("contours", ...),
+                                                  (trace.get("surface") or {}).get("contours", ...),
+                                                  (z_low, z_high)) for trace in _traces(options)]
+    primitives = []
+    triangle_count = 0
+    sampled_cells = 0
+    sampled_points = set()
+    legend_assigned = False
+    contour_count = 0
+    for trace_index, trace in enumerate(_traces(options)):
+        if trace.get("visible") is False:
+            continue
+        trace_settings = {**settings, **(trace.get("surface") or {})}
+        wireframe = resolve_triangle_wireframe((options.get("surface") or {}).get("wireframe", ...),
+                                               (trace.get("surface") or {}).get("wireframe", ...),
+                                               get_defaults("surface"), "surface.wireframe")
+        color = trace.get("color") or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)]
+        points_by_grid = {(source[0], source[1]): (source_index, source) for source_index, source, _ in parsed[trace_index]}
+        xs = sorted({coordinate[0] for coordinate in points_by_grid})
+        ys = sorted({coordinate[1] for coordinate in points_by_grid})
+        selected_grid = lod_selection["byTrace"][trace_index] if lod_selection else None
+        x_indexes = selected_grid["xIndexes"] if selected_grid else list(range(len(xs)))
+        y_indexes = selected_grid["yIndexes"] if selected_grid else list(range(len(ys)))
+        triangles = []
+        contour_segments = []
+        contour_keys = set()
+        contours = contours_by_trace[trace_index]
+        for row in range(max(0, len(y_indexes) - 1)):
+            for column in range(max(0, len(x_indexes) - 1)):
+                if selected_grid and (row, column) not in selected_grid["renderable"]:
+                    continue
+                source_row, source_column = y_indexes[row], x_indexes[column]
+                corners = [points_by_grid.get((xs[source_column], ys[source_row])),
+                           points_by_grid.get((xs[x_indexes[column + 1]], ys[source_row])),
+                           points_by_grid.get((xs[source_column], ys[y_indexes[row + 1]])),
+                           points_by_grid.get((xs[x_indexes[column + 1]], ys[y_indexes[row + 1]]))]
+                if lod_selection:
+                    sampled_cells += 1
+                    sampled_points.update((trace_index, corner[0]) for corner in corners if corner is not None)
+                for triangle_index, positions in enumerate(((0, 1, 2), (1, 3, 2))):
+                    selected = [corners[position] for position in positions]
+                    if any(corner is None for corner in selected):
+                        continue
+                    source_points = [(source_index, _world(source, domains), source) for source_index, source in selected]
+                    color_value = sum(source[2] for _, source in selected) / 3
+                    fill_color = interpolate_color(color_value, z_low, z_high, color_stops)
+                    source_cell = {"index": (source_row * max(0, len(xs) - 1) + source_column) * 2 + triangle_index,
+                                   "row": source_row, "column": source_column, "triangle": triangle_index}
+                    if contours:
+                        source_vertices = [{"world": world, "sourceX": source[0], "sourceY": source[1], "sourceZ": source[2]}
+                                           for _, world, source in source_points]
+                        for level in contours["levels"]:
+                            segment = contour_source_segment(source_vertices, level)
+                            if segment is None:
+                                continue
+                            key = contour_segment_key(level, segment)
+                            if key in contour_keys:
+                                continue
+                            contour_keys.add(key)
+                            contour_count += 1
+                            if contour_count > max_contours:
+                                raise ValueError(f"surface contour segment count {contour_count} exceeds surface.maxContourSegments {max_contours}")
+                            projected = project_contour_segment(segment, projector, _clip_domain_segment)
+                            if projected is not None:
+                                contour_segments.append({**projected, "level": level, "sourceCell": source_cell,
+                                                         "style": contours["style"]})
+                    triangle_count += 1
+                    if triangle_count > max_triangles:
+                        raise ValueError(f"surface triangle count {triangle_count} exceeds surface.maxTriangles {max_triangles}")
+                    for triangle in _triangle_fragments(source_points, domains, projector, fill_color,
+                                                        trace_settings["opacity"], "sourceCell", source_cell, camera):
+                        triangle.update(resolve_triangle_lighting(fill_color, triangle["normal"], lighting,
+                                                                 [point[1] for point in source_points], camera))
+                        boundary_edges = triangle.pop("_boundaryEdges")
+                        if wireframe:
+                            triangle["wireframe"] = wireframe
+                            triangle["wireframeEdges"] = boundary_edges
+                        triangles.append(triangle)
+        triangles.sort(key=lambda triangle: (-triangle["depth"], triangle["sourceCell"]["row"],
+                                           triangle["sourceCell"]["column"], triangle["sourceCell"]["triangle"]))
+        contour_segments.sort(key=lambda segment: (-max(segment["depth1"], segment["depth2"]),
+                                                   segment["level"], segment["sourceCell"]["index"]))
+        primitive = {"type": "surface", "points": [point for triangle in triangles for point in ({"x": vertex["x"], "y": vertex["y"]} for vertex in triangle["vertices"])], "surface3dTriangles": triangles}
+        if contours:
+            primitive["surface3dContourSegments"] = contour_segments
+            primitive["surface3dContourLevels"] = list(contours["levels"])
+        if options.get("surface", {}).get("colorScaleLegend", settings["colorScaleLegend"]) and not legend_assigned:
+            primitive["surface3dColorScaleLegend"] = _surface_legend(width, height, z_low, z_high, trace_settings, color_stops)
+            legend_assigned = True
+        primitive.update({"color": color, "lineWidth": 0, "traceIndex": trace_index,
+                          "subplot": "scene3d", "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}})
+        primitives.append(primitive)
+    metadata = _metadata(options, camera, domains, count, count, width, height)
+    if lighting:
+        metadata["lighting"] = lighting
+    if lod_selection:
+        metadata["surface3dLod"] = {"strategy": lod["strategy"], "maxCells": lod["maxCells"],
+                                    "candidateCellCount": lod_selection["candidateCellCount"],
+                                    "sampledCellCount": sampled_cells,
+                                    "sampledPointCount": len(sampled_points),
+                                    "preparedTriangleCount": triangle_count}
+        metadata["interactionItemCount"] = len(sampled_points) + triangle_count
+    return {"width": width, "height": height, "primitives": primitives, "scene3d": metadata}
+
+
+def mesh3d_scene(options: Mapping, width: float, height: float) -> dict:
+    from .triangle_wireframe import resolve_triangle_wireframe
+    from .lighting3d import resolve_scene3d_lighting, resolve_triangle_lighting
+    from .mesh3d_lod import resolve_mesh_lod, select_mesh_lod_faces
+
+    camera = _camera(options)
+    lighting = resolve_scene3d_lighting((options.get("scene3d") or {}).get("lighting", ...))
+    traces = _traces(options)
+    settings = dict(get_defaults("mesh3d"))
+    settings.update(options.get("mesh3d") or {})
+    max_points = (options.get("scene3d") or {}).get("maxPoints", get_defaults("scene3d")["maxPoints"])
+    if type(max_points) is not int or not 1 <= max_points <= 1_000_000:
+        raise ValueError("scene3d.maxPoints must be an integer between 1 and 1000000")
+    max_faces = settings["maxFaces"]
+    if type(max_faces) is not int or not 1 <= max_faces <= 2_000_000:
+        raise ValueError("mesh3d.maxFaces must be an integer between 1 and 2000000")
+    if "faceColors" in (options.get("mesh3d") or {}) and "vertexColors" in (options.get("mesh3d") or {}):
+        raise ValueError("mesh3d cannot configure both faceColors and vertexColors")
+    lod = resolve_mesh_lod((options.get("mesh3d") or {}).get("lod", ...))
+    parsed = []
+    count = 0
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            parsed.append([])
+            continue
+        values = trace.get("data") or []
+        if not isinstance(values, list):
+            raise ValueError(f"mesh3d vertex data for trace {trace_index} must be a dense array")
+        parsed_trace = []
+        for source_index, value in enumerate(values):
+            count += 1
+            if count > max_points:
+                raise ValueError(f"mesh3d vertex count {count} exceeds scene3d.maxPoints {max_points}")
+            if any(axis in value and value[axis] is None for axis in ("x", "y")) or value.get("z") is None:
+                raise ValueError(f"mesh3d requires x, y, and z at traces[{trace_index}].data[{source_index}]")
+            point = []
+            for axis in "xyz":
+                coordinate = value.get(axis)
+                if type(coordinate) not in (int, float) or not isfinite(coordinate):
+                    raise ValueError(f"scene3d requires finite numeric traces[{trace_index}].data[{source_index}].{axis}")
+                point.append(coordinate)
+            parsed_trace.append((source_index, tuple(point), value))
+        parsed.append(parsed_trace)
+    domains = _domains(parsed, options.get("scene3d") or {})
+    projector = _Projector(camera, width, height)
+    parsed_faces = []
+    source_face_count = 0
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            parsed_faces.append({"vertices": [], "faces": []})
+            continue
+        faces = (trace.get("mesh3d") or {}).get("faces", (options.get("mesh3d") or {}).get("faces", []))
+        if not isinstance(faces, list):
+            raise ValueError(f"mesh3d faces for trace {trace_index} must be a dense array")
+        source_face_count += len(faces)
+        if source_face_count > max_faces:
+            raise ValueError(f"mesh3d face count {source_face_count} exceeds mesh3d.maxFaces {max_faces}")
+        vertices = {index: point for index, point, _ in parsed[trace_index]}
+        for face_index, face in enumerate(faces):
+            if not isinstance(face, list) or len(face) != 3:
+                raise ValueError(f"mesh3d face {face_index} for trace {trace_index} must contain exactly three vertex indexes")
+            for vertex_index, value in enumerate(face):
+                if type(value) is not int or value < 0 or value not in vertices:
+                    raise ValueError(f"mesh3d face {face_index} index {vertex_index} for trace {trace_index} must reference an existing vertex")
+            if len(set(face)) != 3:
+                raise ValueError(f"mesh3d face {face_index} for trace {trace_index} must reference three distinct vertices")
+        trace_mesh = trace.get("mesh3d") or {}
+        plot_mesh = options.get("mesh3d") or {}
+        if "faceColors" in trace_mesh and "vertexColors" in trace_mesh:
+            raise ValueError(f"mesh3d trace {trace_index} cannot configure both faceColors and vertexColors")
+        policy = trace_mesh if "faceColors" in trace_mesh or "vertexColors" in trace_mesh else plot_mesh
+        face_colors = policy.get("faceColors", ...)
+        vertex_colors = policy.get("vertexColors", ...)
+        if face_colors is not ...:
+            if not isinstance(face_colors, list) or len(face_colors) != len(faces):
+                raise ValueError(f"mesh3d.faceColors for trace {trace_index} must match the face count")
+            for index, color in enumerate(face_colors):
+                _hex_channels(color, f"mesh3d.faceColors[{index}] for trace {trace_index}")
+        vertex_channels = None
+        if vertex_colors is not ...:
+            if not isinstance(vertex_colors, list) or len(vertex_colors) != len(vertices):
+                raise ValueError(f"mesh3d.vertexColors for trace {trace_index} must match the vertex count")
+            vertex_channels = [_hex_channels(color, f"mesh3d.vertexColors[{index}] for trace {trace_index}")
+                               for index, color in enumerate(vertex_colors)]
+        parsed_faces.append({"vertices": vertices, "faces": faces,
+                             "faceColors": face_colors, "vertexChannels": vertex_channels})
+    lod_selection = select_mesh_lod_faces(parsed_faces, domains, lod["maxFaces"]) if lod else None
+    primitives = []
+    face_count = 0
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        trace_settings = {**settings, **(trace.get("mesh3d") or {})}
+        wireframe = resolve_triangle_wireframe((options.get("mesh3d") or {}).get("wireframe", ...),
+                                               (trace.get("mesh3d") or {}).get("wireframe", ...),
+                                               get_defaults("mesh3d"), "mesh3d.wireframe")
+        color = trace.get("color") or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)]
+        colors = parsed_faces[trace_index]["faceColors"]
+        vertex_channels = parsed_faces[trace_index]["vertexChannels"]
+        culling = trace_settings.get("backfaceCulling", get_defaults("mesh3d")["backfaceCulling"])
+        if type(culling) is not bool:
+            raise ValueError("mesh3d.backfaceCulling must be boolean")
+        lookup = parsed_faces[trace_index]["vertices"]
+        triangles = []
+        for face_index, face in enumerate(parsed_faces[trace_index]["faces"]):
+            if lod_selection and face_index not in lod_selection["selectedFaceIndexesByTrace"][trace_index]:
+                continue
+            vertices = [(vertex, _world(lookup[vertex], domains), lookup[vertex]) for vertex in face]
+            if colors is not ...:
+                face_color = colors[face_index]
+            elif vertex_channels is not None:
+                channels = [floor(sum(vertex_channels[index][channel] for index in face) / 3 + .5)
+                            for channel in range(3)]
+                face_color = "#" + "".join(f"{channel:02x}" for channel in channels)
+            else:
+                face_color = color
+            for triangle in _triangle_fragments(vertices, domains, projector, face_color,
+                                                trace_settings["opacity"], "sourceFace",
+                                                {"index": face_index, "vertexIndexes": list(face)}, camera, mesh=True):
+                if culling and not triangle["frontFacing"]:
+                    continue
+                triangle.update(resolve_triangle_lighting(triangle["fillColor"], triangle["normal"], lighting,
+                                                         [vertex[1] for vertex in vertices], camera))
+                boundary_edges = triangle.pop("_boundaryEdges")
+                if wireframe:
+                    triangle["wireframe"] = wireframe
+                    triangle["wireframeEdges"] = boundary_edges
+                triangles.append(triangle)
+                face_count += 1
+        triangles.sort(key=lambda triangle: (-triangle["depth"], triangle["sourceFace"]["index"]))
+        primitives.append({"type": "mesh3d", "points": [point for triangle in triangles for point in ({"x": vertex["x"], "y": vertex["y"]} for vertex in triangle["vertices"])], "mesh3dTriangles": triangles,
+                           "color": color, "lineWidth": 0, "traceIndex": trace_index,
+                           "subplot": "scene3d", "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}})
+    metadata = _metadata(options, camera, domains, count,
+                         (lod_selection["sampledVertexCount"] + lod_selection["sampledFaceCount"]
+                          if lod_selection else count + source_face_count), width, height)
+    if lighting:
+        metadata["lighting"] = lighting
+    metadata["sourceFaceCount"] = source_face_count
+    if lod_selection:
+        metadata["mesh3dLod"] = {"strategy": lod["strategy"], "maxFaces": lod["maxFaces"],
+                                 "candidateFaceCount": lod_selection["candidateFaceCount"],
+                                 "sampledFaceCount": lod_selection["sampledFaceCount"],
+                                 "sampledVertexCount": lod_selection["sampledVertexCount"],
+                                 "preparedTriangleCount": face_count}
+    return {"width": width, "height": height, "primitives": primitives, "scene3d": metadata}
+
+
+def _shade(color: str, intensity: float) -> str:
+    if not color.startswith("#") or len(color) != 7:
+        return color
+    channels = [int(color[index:index + 2], 16) for index in (1, 3, 5)]
+    return "#" + "".join(f"{max(0, min(255, int(channel * intensity + .5))):02x}" for channel in channels)
+
+
+def pie3d_scene(options: Mapping, width: float, height: float) -> dict:
+    from .scene import _pie_scene
+    from .lighting3d import resolve_scene3d_lighting, resolve_triangle_lighting
+
+    if "subplots" in options or (options.get("scene3d") or {}).get("subplots"):
+        raise ValueError("experimental pie3d currently requires one full-chart 3D scene")
+    pie = options.get("pie") or {}
+    if "borderColor" in pie or "borderWidth" in pie:
+        raise ValueError("pie3d does not support 2D pie.borderColor or pie.borderWidth; 3D face boundaries use projected geometry")
+    scene3d = options.get("scene3d") or {}
+    if any(f"{axis}Axis" in scene3d and scene3d[f"{axis}Axis"] is not None for axis in "xyz"):
+        raise ValueError("pie3d does not support Cartesian scene3d axis options")
+    pie_settings = get_defaults("pie")
+    settings = {**get_defaults("pie3d"), **(options.get("pie3d") or {})}
+    tolerance = settings["curveTolerance"]
+    if type(tolerance) not in (int, float) or not isfinite(tolerance) or tolerance <= 0:
+        raise ValueError("pie3d.curveTolerance must be a positive finite number")
+    depth = settings["extrusionDepth"]
+    if type(depth) not in (int, float) or not isfinite(depth) or not 0 < depth <= 1:
+        raise ValueError("pie3d.extrusionDepth must be finite and in (0, 1]")
+    max_triangles = scene3d.get("maxPoints", get_defaults("scene3d")["maxPoints"])
+    if type(max_triangles) is not int or not 1 <= max_triangles <= 1_000_000:
+        raise ValueError("scene3d.maxPoints must be an integer between 1 and 1000000")
+    camera = _camera(options)
+    lighting = resolve_scene3d_lighting(scene3d.get("lighting", ...))
+    sectors = (_pie_scene(options, width, height)["primitives"] or [{}])[0].get("pieSectors", [])
+    projector = _Projector(camera, width, height)
+    radius = pie.get("outerRadiusRatio", pie_settings["outerRadiusRatio"]) / 2
+    inner_radius = radius * pie.get("innerRadiusRatio", pie_settings["innerRadiusRatio"])
+    top, bottom = depth / 2, -depth / 2
+    primitives, prepared = [], 0
+    for sector in sectors:
+        triangles = []
+        source_index, trace_index = sector["sourceIndex"], sector["traceIndex"]
+        start_angle, sweep = sector["startAngle"], sector["sweep"]
+
+        def point(angle, distance, elevation):
+            return (cos(angle) * distance, elevation, sin(angle) * distance)
+
+        def add_triangle(face, verts, intensity):
+            nonlocal prepared
+            prepared += 1
+            if prepared > max_triangles:
+                raise ValueError(f"pie3d triangle count exceeds scene3d.maxPoints {max_triangles}")
+            world = list(verts)
+            raw = _cross(_subtract(world[1], world[0]), _subtract(world[2], world[0]))
+            radial_angle = start_angle if face == "start" else start_angle + sweep
+            direction = 1 if sweep >= 0 else -1
+            if face == "top": desired = (0, 1, 0)
+            elif face == "bottom": desired = (0, -1, 0)
+            elif face in ("outer", "inner"):
+                sign = 1 if face == "outer" else -1
+                desired = (sum(vertex[0] for vertex in world) * sign, 0, sum(vertex[2] for vertex in world) * sign)
+            elif face == "start": desired = (sin(radial_angle) * direction, 0, -cos(radial_angle) * direction)
+            else: desired = (-sin(radial_angle) * direction, 0, cos(radial_angle) * direction)
+            if _dot(raw, desired) < 0:
+                world[1], world[2] = world[2], world[1]
+            if hypot(*_cross(_subtract(world[1], world[0]), _subtract(world[2], world[0]))) <= 2.220446049250313e-16:
+                return
+            vertices = [(source_index, vertex, vertex) for vertex in world]
+            triangle = _triangle(vertices, projector, sector["color"] if face == "top" else _shade(sector["color"], intensity),
+                                 sector["opacity"], "sourceFace", {"index": source_index, "vertexIndexes": [0, 1, 2]}, camera, mesh=True)
+            if triangle is not None:
+                if lighting is not None:
+                    resolved_fill = resolve_triangle_lighting(triangle["fillColor"], triangle["normal"],
+                                                              lighting, world, camera)
+                    triangle.update(resolved_fill)
+                triangle["pie3d"] = {"label": sector["label"], "value": sector["value"],
+                                     "fraction": sector["fraction"], "color": sector["color"], "face": face}
+                triangles.append(triangle)
+
+        def add_quad(face, a, b, c, d, intensity):
+            add_triangle(face, (a, b, c), intensity)
+            add_triangle(face, (a, c, d), intensity)
+
+        pixel_radius = max(1, min(width, height) * radius / 2)
+        step = min(radians(get_defaults("pie3d")["maxCurveStepDegrees"]), 2 * acos(max(-1, 1 - tolerance / pixel_radius)))
+        segments = max(1, ceil(abs(sweep) / step))
+        for index in range(segments):
+            a = start_angle + sweep * index / segments
+            b = start_angle + sweep * (index + 1) / segments
+            os_top, oe_top = point(a, radius, top), point(b, radius, top)
+            is_top, ie_top = point(a, inner_radius, top), point(b, inner_radius, top)
+            os_bottom, oe_bottom = point(a, radius, bottom), point(b, radius, bottom)
+            is_bottom, ie_bottom = point(a, inner_radius, bottom), point(b, inner_radius, bottom)
+            add_quad("top", is_top, os_top, oe_top, ie_top, 1)
+            add_quad("bottom", ie_bottom, oe_bottom, os_bottom, is_bottom, .62)
+            add_quad("outer", os_top, os_bottom, oe_bottom, oe_top, .76)
+            if inner_radius > 0:
+                add_quad("inner", ie_top, ie_bottom, is_bottom, is_top, .68)
+        if abs(sweep) < 2 * pi - 2.220446049250313e-16:
+            add_quad("start", point(start_angle, inner_radius, top), point(start_angle, inner_radius, bottom),
+                     point(start_angle, radius, bottom), point(start_angle, radius, top), .7)
+            end = start_angle + sweep
+            add_quad("end", point(end, radius, top), point(end, radius, bottom),
+                     point(end, inner_radius, bottom), point(end, inner_radius, top), .7)
+        primitives.append({"type": "pie3d", "points": [], "color": sector["color"], "lineWidth": 0,
+                           "traceIndex": trace_index, "subplot": "scene3d",
+                           "bounds": {"left": 0, "top": 0, "right": width, "bottom": height},
+                           "mesh3dTriangles": triangles})
+    metadata_options = dict(options)
+    metadata_options["scene3d"] = {**(options.get("scene3d") or {}),
+                                   "showAxes": (options.get("scene3d") or {}).get("showAxes", False),
+                                   "showGrid": (options.get("scene3d") or {}).get("showGrid", False)}
+    domains = {axis: {"min": -.5, "max": .5} for axis in "xyz"}
+    metadata = _metadata(metadata_options, camera, domains, len(sectors), len(sectors) + prepared, width, height)
+    metadata["sourceFaceCount"] = prepared
+    if lighting is not None:
+        metadata["lighting"] = lighting
+    metadata["tickLabels"] = []
+    return {"width": width, "height": height, "primitives": primitives, "scene3d": metadata}