fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/scene3d_accessibility.py

@@ -0,0 +1,183 @@
+"""Source-shaped accessibility summaries for renderer-neutral 3D scenes."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Mapping
+
+from .defaults import get_defaults
+
+
+_MISSING = object()
+
+
+def _validate(value: Any, path: str) -> None:
+    if value is _MISSING or isinstance(value, bool):
+        return
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{path} must be a boolean or an object")
+    for field in ("enabled", "includeTable"):
+        if field in value and not isinstance(value[field], bool):
+            raise ValueError(f"{path}.{field} must be a boolean")
+    for field in ("label", "description"):
+        if field in value and (not isinstance(value[field], str) or not value[field].strip()):
+            raise ValueError(f"{path}.{field} must be a non-empty string")
+    if "maxRows" in value and (type(value["maxRows"]) is not int or not 1 <= value["maxRows"] <= 1000):
+        raise ValueError(f"{path}.maxRows must be an integer between 1 and 1000")
+
+
+def _resolve(root: Any, scoped: Any) -> dict | None:
+    if scoped is not None:
+        root = {**root, **scoped} if isinstance(root, Mapping) and isinstance(scoped, Mapping) else scoped
+    if root is None or root is False:
+        return None
+    if root is True:
+        root = {}
+    if root.get("enabled") is False:
+        return None
+    defaults = get_defaults("scene3d")
+    return {"label": root.get("label", "").strip(),
+            "description": root.get("description", "").strip(),
+            "maxRows": root.get("maxRows", defaults["accessibilityMaxRows"]),
+            "includeTable": root.get("includeTable", defaults["accessibilityIncludeTable"])}
+
+
+def _source_traces(options: Mapping) -> list[dict]:
+    return list(options.get("traces") or ([{"data": options["data"]}] if options.get("data") is not None else []))
+
+
+def _scalar(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return value.isoformat().replace("+00:00", "Z")
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day).isoformat() + "Z"
+    return value
+
+
+def _number(value: float) -> str:
+    if type(value) is int or isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return format(value, ".6g")
+
+
+def _domain_text(domains: Mapping) -> str:
+    return ", ".join(f"{axis} {_number(domains[axis]['min'])} to {_number(domains[axis]['max'])}"
+                     for axis in "xyz")
+
+
+def _label(options: Mapping, resolved: Mapping) -> str:
+    defaults = get_defaults("scene3d")
+    title = options.get("title")
+    if resolved["label"]:
+        return resolved["label"]
+    if isinstance(title, str) and title.strip():
+        return title.strip()
+    key = {"scatter3d": "accessibilityScatter3dLabel", "line3d": "accessibilityLine3dLabel",
+           "surface": "accessibilitySurfaceLabel", "mesh3d": "accessibilityMesh3dLabel"}
+    return defaults[key[options["type"]]] if options["type"] in key else "Pie3D chart"
+
+
+def _pie_summary(metadata: Mapping, options: Mapping, resolved: Mapping) -> dict:
+    from .scene import _pie_scene
+    pie = options.get("pie") or {}
+    sectors = (_pie_scene(options, options["width"], options["height"])["primitives"] or [{}])[0].get("pieSectors", [])
+    trace_inputs = pie.get("traces") or options.get("traces") or []
+    rows = []
+    for sector in sectors[:resolved["maxRows"]]:
+        index = sector["traceIndex"]
+        row = {"traceIndex": index, "sourceIndex": sector["sourceIndex"],
+               "x": sector["label"], "y": sector["value"], "z": None}
+        if index < len(trace_inputs) and trace_inputs[index].get("name"):
+            row["traceName"] = trace_inputs[index]["name"]
+        rows.append(row)
+    label = _label(options, resolved)
+    indexes = list(dict.fromkeys(sector["traceIndex"] for sector in sectors))
+    summaries = []
+    for index in indexes:
+        item = {"traceIndex": index, "rowCount": sum(sector["traceIndex"] == index for sector in sectors)}
+        if index < len(trace_inputs) and trace_inputs[index].get("name"):
+            item["name"] = trace_inputs[index]["name"]
+        summaries.append(item)
+    return {"label": label,
+            "description": resolved["description"] or f"{label}. Experimental pie3d scene with {len(sectors)} visible sectors.",
+            "domains": metadata["domains"], "maxRows": resolved["maxRows"],
+            "totalRowCount": len(sectors), "rows": rows, "truncated": len(sectors) > len(rows),
+            "includeTable": resolved["includeTable"], "traces": summaries}
+
+
+def validateScene3dAccessibility(options: Mapping) -> None:
+    scene_options = options.get("scene3d") or {}
+    root = scene_options.get("accessibility", _MISSING)
+    _validate(root, "scene3d.accessibility")
+    scoped_values = scene_options.get("subplots") or {}
+    for subplot_id, scoped in scoped_values.items():
+        _validate((scoped or {}).get("accessibility", _MISSING),
+                  f"scene3d.subplots.{subplot_id}.accessibility")
+
+
+def applyScene3dAccessibilitySummary(scene: dict, options: Mapping) -> dict:
+    """Decorate scene metadata after geometry construction, as in source plot()."""
+    validateScene3dAccessibility(options)
+    root = (options.get("scene3d") or {}).get("accessibility")
+    scoped_values = (options.get("scene3d") or {}).get("subplots") or {}
+    metadata_items = scene.get("scenes3d") or ([scene["scene3d"]] if scene.get("scene3d") else [])
+    if not metadata_items:
+        return scene
+    traces = _source_traces(options)
+    for metadata in metadata_items:
+        subplot_id = metadata["subplotId"]
+        scoped = (scoped_values.get(subplot_id) or {}).get("accessibility")
+        resolved = _resolve(root, scoped)
+        if resolved is None:
+            metadata.pop("accessibility", None)
+            continue
+        if options["type"] == "pie3d":
+            metadata["accessibility"] = _pie_summary(metadata, options, resolved)
+            continue
+        if options.get("subplots") is not None:
+            from .subplots import resolveTraceSubplotBindings
+            bindings = resolveTraceSubplotBindings(options)
+            indexes = [index for index, binding in enumerate(bindings) if binding["subplotId"] == subplot_id]
+        else:
+            indexes = list(range(len(traces)))
+        summaries = []
+        rows = []
+        for index in indexes:
+            trace = traces[index]
+            if trace.get("visible") is False:
+                continue
+            item = {"traceIndex": index, "rowCount": len(trace.get("data") or [])}
+            if trace.get("name"):
+                item["name"] = trace["name"]
+            if options["type"] == "mesh3d":
+                item["faceCount"] = len((trace.get("mesh3d") or {}).get("faces",
+                                       (options.get("mesh3d") or {}).get("faces") or []))
+            summaries.append(item)
+            for source_index, point in enumerate(trace.get("data") or []):
+                if len(rows) >= resolved["maxRows"]:
+                    break
+                row = {"traceIndex": index, "sourceIndex": source_index,
+                       **{axis: _scalar(point.get(axis)) for axis in "xyz"}}
+                if trace.get("name"):
+                    row["traceName"] = trace["name"]
+                rows.append(row)
+        total = sum(item["rowCount"] for item in summaries)
+        label = _label(options, resolved)
+        truncated = total > len(rows)
+        if resolved["description"]:
+            description = resolved["description"]
+        else:
+            description = (f"{label}. Experimental {options['type']} scene {subplot_id} with "
+                           f"{len(summaries)} visible {'trace' if len(summaries) == 1 else 'traces'} and "
+                           f"{total} source {'row' if total == 1 else 'rows'}.")
+            if options["type"] == "mesh3d":
+                count = sum(item.get("faceCount", 0) for item in summaries)
+                description += f" {count} source {'face' if count == 1 else 'faces'}."
+            description += f" Camera-independent domains: {_domain_text(metadata['domains'])}."
+            if truncated:
+                description += f" The data table shows the first {len(rows)} rows."
+        metadata["accessibility"] = {"label": label, "description": description,
+                                     "domains": metadata["domains"], "maxRows": resolved["maxRows"],
+                                     "totalRowCount": total, "rows": rows, "truncated": truncated,
+                                     "includeTable": resolved["includeTable"], "traces": summaries}
+    return scene

fastplotpy/scene3d_collection.py

@@ -0,0 +1,158 @@
+"""Named 3D subplot composition with source trace identity and local geometry."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Callable, Mapping
+
+from .defaults import DEFAULT_TRACE_COLORS
+from .defaults import get_defaults
+from .scene3d_accessibility import applyScene3dAccessibilitySummary, validateScene3dAccessibility
+from .subplots import resolveSubplots, resolveTraceSubplotBindings
+
+
+def _traces(options: Mapping) -> list[dict]:
+    return list(options.get("traces") or ([{"data": options["data"]}] if options.get("data") is not None else []))
+
+
+def _renderer_mode(options: Mapping) -> str:
+    requested = (options.get("scene3d") or {}).get("renderer")
+    if requested is None:
+        requested = get_defaults("scene3d")["renderer"]
+    if requested not in ("canvas", "webgl2", "auto"):
+        raise ValueError("scene3d.renderer must be 'canvas', 'webgl2', or 'auto'")
+    return requested
+
+
+def _attach_renderer(scene: dict, requested: str) -> dict:
+    metadata = scene.get("scenes3d") or ([scene["scene3d"]] if scene.get("scene3d") else [])
+    for item in metadata:
+        item["renderer"] = {"requested": requested, "resolved": "renderer-neutral"}
+    return scene
+
+
+def _merge_policy(root, scoped):
+    if scoped is None:
+        return root
+    if isinstance(root, Mapping) and isinstance(scoped, Mapping):
+        return {**root, **scoped}
+    return scoped
+
+
+def _overlap(left, right) -> bool:
+    # The epsilon is the pinned source resolveScene3dLayout predicate.
+    return (min(left["right"], right["right"]) - max(left["left"], right["left"]) > 1e-12
+            and min(left["bottom"], right["bottom"]) - max(left["top"], right["top"]) > 1e-12)
+
+
+def _local_options(options: Mapping, traces: list[dict], scoped: Mapping | None,
+                   local_width: float, local_height: float) -> dict:
+    scene = options.get("scene3d") or {}
+    scoped = scoped or {}
+    merged = {**scene, **scoped}
+    lighting = _merge_policy(scene.get("lighting"), scoped.get("lighting"))
+    if lighting is not None:
+        merged["lighting"] = lighting
+    else:
+        merged.pop("lighting", None)
+    merged.pop("subplots", None)
+    local = {**options, "width": local_width, "height": local_height,
+             "scene3d": merged, "traces": traces, "data": None}
+    local.pop("subplots", None)
+    return local
+
+
+def _remap_primitive(primitive: dict, trace: Mapping, original_index: int,
+                     family: str, subplot_id: str, bounds: Mapping,
+                     options: Mapping) -> None:
+    primitive["traceIndex"] = original_index
+    primitive["subplot"] = subplot_id
+    primitive["bounds"] = dict(bounds)
+    default_color = DEFAULT_TRACE_COLORS[original_index % len(DEFAULT_TRACE_COLORS)]
+    if family in ("scatter3d", "line3d"):
+        default_applies = ((trace.get("lineStyle") or {}).get("color") is None
+                           and trace.get("color") is None
+                           and (options.get("lineStyle") or {}).get("color") is None
+                           and ((((options.get("style") or {}).get("trace") or {}).get("line") or {}).get("color")) is None)
+    else:
+        default_applies = trace.get("color") is None
+    if not default_applies:
+        return
+    primitive["color"] = default_color
+    if family == "scatter3d":
+        for point in primitive.get("scatter3dPoints") or []:
+            if "colorValue" not in point:
+                point["fillColor"] = default_color
+    if family == "mesh3d":
+        mesh = trace.get("mesh3d") or {}
+        plot_mesh = options.get("mesh3d") or {}
+        if (mesh.get("faceColors") is None and mesh.get("vertexColors") is None
+                and plot_mesh.get("faceColors") is None and plot_mesh.get("vertexColors") is None):
+            for triangle in primitive.get("mesh3dTriangles") or []:
+                if triangle.get("lighting"):
+                    # Shading is recalculated only when the source has no
+                    # explicit trace or plot mesh color policy.
+                    from .lighting3d import shade_scene3d_color
+                    triangle["lighting"]["baseColor"] = default_color
+                    triangle["fillColor"] = shade_scene3d_color(
+                        default_color, triangle["lighting"]["intensity"],
+                        triangle["lighting"]["specularIntensity"])
+                else:
+                    triangle["fillColor"] = default_color
+
+
+def buildScene3dCollection(options: Mapping, builder: Callable[[Mapping, float, float], dict]) -> dict:
+    """Build each bound scene locally, then restore global source trace indexes."""
+    renderer = _renderer_mode(options)
+    validateScene3dAccessibility(options)
+    width, height = options["width"], options["height"]
+    if options.get("subplots") is None:
+        if options["type"] != "pie3d" and any("subplot" in trace for trace in _traces(options)):
+            raise ValueError(f"experimental {options['type']} subplot bindings require a subplots layout")
+        return _attach_renderer(applyScene3dAccessibilitySummary(builder(options, width, height), options), renderer)
+    family = options["type"]
+    if family == "pie3d":
+        raise ValueError("experimental pie3d currently requires one full-chart 3D scene")
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options)
+    traces = _traces(options)
+    target_ids = {binding["subplotId"] for binding in bindings}
+    if not target_ids and len(subplots) == 1:
+        target_ids.add(subplots[0]["id"])
+    if not target_ids:
+        raise ValueError(f"experimental {family} requires every trace to bind to exactly one shared 3D subplot")
+    targets = [subplot for subplot in subplots if subplot["id"] in target_ids]
+    if len(targets) == 1 and any(binding["subplotId"] != targets[0]["id"] for binding in bindings):
+        raise ValueError(f"experimental {family} requires every trace to bind to exactly one shared 3D subplot")
+    scenes = []
+    scene_scopes = (options.get("scene3d") or {}).get("subplots") or {}
+    for target in targets:
+        subplot_id, bounds = target["id"], target["bounds"]
+        overlap = next((other for other in subplots if other["id"] != subplot_id
+                        and _overlap(bounds, other["bounds"])), None)
+        if overlap is not None:
+            raise ValueError(f"experimental {family} subplot '{subplot_id}' overlaps subplot '{overlap['id']}'")
+        indexes = [index for index, binding in enumerate(bindings)
+                   if binding["subplotId"] == subplot_id]
+        local_width = max(1, bounds["right"] - bounds["left"])
+        local_height = max(1, bounds["bottom"] - bounds["top"])
+        local_traces = [deepcopy(traces[index]) for index in indexes]
+        for trace in local_traces:
+            trace.pop("subplot", None)
+        local = _local_options(options, local_traces, scene_scopes.get(subplot_id),
+                               local_width, local_height)
+        scene = builder(local, local_width, local_height)
+        scene["scene3d"]["subplotId"] = subplot_id
+        scene["scene3d"]["bounds"] = dict(bounds)
+        for primitive in scene["primitives"]:
+            original_index = indexes[primitive.get("traceIndex", 0)]
+            _remap_primitive(primitive, traces[original_index], original_index,
+                             family, subplot_id, bounds, options)
+        scenes.append(scene)
+    metadata = [scene["scene3d"] for scene in scenes]
+    result = {"width": width, "height": height,
+              "primitives": [primitive for scene in scenes for primitive in scene["primitives"]],
+              "scene3d": metadata[0]}
+    if len(scenes) > 1:
+        result["scenes3d"] = metadata
+    return _attach_renderer(applyScene3dAccessibilitySummary(result, options), renderer)

fastplotpy/subplots.py

@@ -0,0 +1,115 @@
+"""Subplot layout and trace bindings from the source Rust/TypeScript contracts."""
+
+from __future__ import annotations
+
+from math import isfinite
+from typing import Mapping
+
+from .defaults import get_defaults
+from .native import hasRustPlotEngine, rustCall
+
+
+def _tracks(raw, fallback):
+    if isinstance(raw, list):
+        if not raw:
+            raise ValueError("Subplot track arrays must not be empty")
+        return [track.get("weight", 1) if isinstance(track, Mapping)
+                and isinstance(track.get("weight"), (int, float)) and not isinstance(track["weight"], bool)
+                and isfinite(track["weight"]) and track["weight"] > 0 else 1 for track in raw]
+    count = fallback if raw is None else raw
+    if isinstance(count, bool) or not isinstance(count, int) or count <= 0:
+        raise ValueError("Subplot layout rows and columns must be positive integers")
+    return [1] * count
+
+
+def _track_bounds(start, end, weights, gap):
+    available = max(1, end - start - gap * max(0, len(weights) - 1))
+    total = sum(weights)
+    cursor = start
+    bounds = []
+    for index, weight in enumerate(weights):
+        size = end - cursor if index == len(weights) - 1 else available * weight / total
+        bounds.append((cursor, max(cursor + 1, cursor + size)))
+        cursor += size + gap
+    return bounds
+
+
+def _python_layout(options, bounds):
+    items = ((options.get("subplots") or {}).get("items") or {})
+    if not items:
+        return [{"id": "main", "row": 0, "column": 0, "rowSpan": 1, "columnSpan": 1,
+                 "xAxisId": "x", "yAxisId": "y", "bounds": bounds}]
+    layout = (options.get("subplots") or {}).get("layout") or {}
+    fallback_rows = max(item["row"] + item.get("rowSpan", 1) for item in items.values())
+    fallback_columns = max(item["column"] + item.get("columnSpan", 1) for item in items.values())
+    rows = _tracks(layout.get("rows"), fallback_rows)
+    columns = _tracks(layout.get("columns"), fallback_columns)
+    defaults = get_defaults("layout")["subplots"]
+    def gap(key):
+        value = layout.get(key)
+        return max(0, value) if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) else defaults[key]
+    row_bounds = _track_bounds(bounds["top"], bounds["bottom"], rows, gap("rowGap"))
+    column_bounds = _track_bounds(bounds["left"], bounds["right"], columns, gap("columnGap"))
+    result = []
+    for name, item in items.items():
+        row, column = item["row"], item["column"]
+        row_span, column_span = item.get("rowSpan", 1), item.get("columnSpan", 1)
+        if any(isinstance(value, bool) or not isinstance(value, int) or value < 0 for value in (row, column)):
+            raise ValueError(f"Invalid position for subplot '{name}'")
+        if any(isinstance(value, bool) or not isinstance(value, int) or value <= 0 for value in (row_span, column_span)):
+            raise ValueError(f"Invalid span for subplot '{name}'")
+        if row + row_span > len(rows) or column + column_span > len(columns):
+            raise ValueError(f"Subplot '{name}' is outside the configured layout")
+        result.append({"id": name, "row": row, "column": column,
+                       "rowSpan": row_span, "columnSpan": column_span,
+                       "xAxisId": item.get("xAxis", "x"), "yAxisId": item.get("yAxis", "y"),
+                       "bounds": {"left": column_bounds[column][0], "top": row_bounds[row][0],
+                                  "right": column_bounds[column + column_span - 1][1],
+                                  "bottom": row_bounds[row + row_span - 1][1]}})
+    return result
+
+
+def resolveSubplots(options, outerBounds=None):
+    """Resolve source-named subplot layout, using the pinned Rust builder when available."""
+    bounds = outerBounds or {"left": 0, "top": 0, "right": options["width"], "bottom": options["height"]}
+    subplot = options.get("subplots") or {}
+    layout = subplot.get("layout") or {}
+    items = subplot.get("items") or {}
+    defaults = get_defaults("layout")["subplots"]
+    def tracks(raw):
+        if isinstance(raw, list):
+            return [{"weight": item.get("weight") if isinstance(item, Mapping) else None} for item in raw]
+        if isinstance(raw, int) and not isinstance(raw, bool):
+            return [{} for _ in range(raw)]
+        return None
+    payload = {"bounds": bounds, "rows": tracks(layout.get("rows")), "columns": tracks(layout.get("columns")),
+               "row_gap": max(0, layout["rowGap"]) if isinstance(layout.get("rowGap"), (int, float)) and isfinite(layout["rowGap"]) else defaults["rowGap"],
+               "column_gap": max(0, layout["columnGap"]) if isinstance(layout.get("columnGap"), (int, float)) and isfinite(layout["columnGap"]) else defaults["columnGap"],
+               "items": [{"id": name, "row": item["row"], "column": item["column"],
+                          "row_span": item.get("rowSpan"), "column_span": item.get("columnSpan"),
+                          "x_axis_id": item.get("xAxis"), "y_axis_id": item.get("yAxis")}
+                         for name, item in items.items()]}
+    if hasRustPlotEngine():
+        native = rustCall("subplot_layout", input=payload)
+        return [{"id": item["id"], "row": item["row"], "column": item["column"],
+                 "rowSpan": item["row_span"], "columnSpan": item["column_span"],
+                 "xAxisId": item["x_axis_id"], "yAxisId": item["y_axis_id"],
+                 "bounds": item["bounds"]} for item in native]
+    return _python_layout(options, bounds)
+
+
+def resolveTraceSubplotBindings(options):
+    traces = options.get("traces") or ([{"data": options["data"]}] if options.get("data") is not None else [])
+    subplots = resolveSubplots(options)
+    by_id = {item["id"]: item for item in subplots}
+    default_id = "main" if "main" in by_id else subplots[0]["id"] if len(subplots) == 1 else "main"
+    result = []
+    for trace in traces:
+        name = trace.get("subplot", default_id)
+        subplot = by_id.get(name)
+        if subplot is None:
+            raise ValueError(f"Unknown subplot id '{name}' for trace")
+        result.append({"trace": trace, "subplotId": name,
+                       "xAxisId": trace.get("xAxis", subplot["xAxisId"]),
+                       "yAxisId": trace.get("yAxis", subplot["yAxisId"])})
+    return result

fastplotpy/surface_contours.py

@@ -0,0 +1,122 @@
+"""Source Surface3D contour levels and triangle intersections."""
+
+from __future__ import annotations
+
+from math import isfinite
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def _validate(value, label):
+    if value is ... or type(value) is bool:
+        return None
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be boolean or an object")
+    if "show" in value and type(value["show"]) is not bool:
+        raise ValueError(f"{label}.show must be boolean")
+    if "color" in value:
+        from .scene3d import _hex_channels
+        _hex_channels(value["color"], f"{label}.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"{label}.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"{label}.opacity must be a finite number between 0 and 1")
+    defaults = get_defaults("surface")
+    if "count" in value and (type(value["count"]) is not int or not 1 <= value["count"] <= defaults["maxContourLevels"]):
+        raise ValueError(f"{label}.count must be an integer between 1 and {defaults['maxContourLevels']}")
+    if "values" in value:
+        values = value["values"]
+        if not isinstance(values, list) or not 1 <= len(values) <= defaults["maxContourLevels"]:
+            raise ValueError(f"{label}.values must contain between 1 and {defaults['maxContourLevels']} values")
+        if any(type(item) not in (int, float) or not isfinite(item) for item in values):
+            raise ValueError(f"{label}.values must be a dense array of finite numbers")
+    if "values" in value and "count" in value:
+        raise ValueError(f"{label} cannot configure both values and count")
+    return value
+
+
+def resolve_surface_contours(plot_value, trace_value, color_domain):
+    plot_options = _validate(plot_value, "surface.contours")
+    trace_options = _validate(trace_value, "trace.surface.contours")
+    defaults = get_defaults("surface")
+    selected = trace_value if trace_value is not ... else plot_value
+    if selected is ...:
+        show = defaults["contourShow"]
+    elif type(selected) is bool:
+        show = selected
+    else:
+        show = selected.get("show", True)
+    if not show:
+        return None
+    level_source = (trace_options if trace_options and ("values" in trace_options or "count" in trace_options)
+                    else plot_options)
+    if level_source and "values" in level_source:
+        levels = sorted(set(level_source["values"]))
+    elif color_domain[0] == color_domain[1]:
+        levels = []
+    else:
+        count = level_source.get("count", defaults["contourCount"]) if level_source else defaults["contourCount"]
+        levels = [color_domain[0] + (color_domain[1] - color_domain[0]) * ((index + 1) / (count + 1))
+                  for index in range(count)]
+    color = (trace_options or {}).get("color", (plot_options or {}).get("color", defaults["contourColor"]))
+    from .scene3d import _hex_channels
+    _hex_channels(color, "surface.contours.color")
+    return {"levels": levels, "style": {"color": color.strip(),
+            "width": (trace_options or {}).get("width", (plot_options or {}).get("width", defaults["contourWidth"])),
+            "opacity": (trace_options or {}).get("opacity", (plot_options or {}).get("opacity", defaults["contourOpacity"]))}}
+
+
+def _interpolate(first, second, ratio):
+    return {key: first[key] + (second[key] - first[key]) * ratio
+            for key in ("sourceX", "sourceY", "sourceZ")}
+
+
+def contour_source_segment(vertices, level):
+    intersections = []
+    def append(vertex):
+        if not any(all(abs(current["world"][axis] - vertex["world"][axis]) <= 1e-12
+                       for axis in range(3)) for current in intersections):
+            intersections.append(vertex)
+    for index, first in enumerate(vertices):
+        second = vertices[(index + 1) % 3]
+        first_delta, second_delta = first["sourceZ"] - level, second["sourceZ"] - level
+        if first_delta == 0 and second_delta == 0:
+            append(first)
+            append(second)
+        elif first_delta == 0:
+            append(first)
+        elif second_delta == 0:
+            append(second)
+        elif first_delta < 0 < second_delta or first_delta > 0 > second_delta:
+            ratio = -first_delta / (second_delta - first_delta)
+            interpolated = _interpolate(first, second, ratio)
+            interpolated["world"] = tuple(first["world"][axis] + (second["world"][axis] - first["world"][axis]) * ratio
+                                          for axis in range(3))
+            append(interpolated)
+    return intersections if len(intersections) == 2 else None
+
+
+def contour_segment_key(level, segment):
+    keys = [tuple(vertex[name] for name in ("sourceX", "sourceY", "sourceZ")) for vertex in segment]
+    return level, *sorted(keys)
+
+
+def project_contour_segment(segment, projector, clip_domain_segment):
+    first, second = segment
+    clipped = clip_domain_segment(first["world"], second["world"])
+    if clipped is None:
+        return None
+    projected = projector.project_segment(clipped["from"], clipped["to"])
+    if projected is None:
+        return None
+    start_ratio = clipped["startRatio"] + (clipped["endRatio"] - clipped["startRatio"]) * projected["startRatio"]
+    end_ratio = clipped["startRatio"] + (clipped["endRatio"] - clipped["startRatio"]) * projected["endRatio"]
+    source_from = _interpolate(first, second, start_ratio)
+    source_to = _interpolate(first, second, end_ratio)
+    return {"x1": projected["from"]["x"], "y1": projected["from"]["y"], "depth1": projected["from"]["depth"],
+            "x2": projected["to"]["x"], "y2": projected["to"]["y"], "depth2": projected["to"]["depth"],
+            "sourceX1": source_from["sourceX"], "sourceY1": source_from["sourceY"], "sourceZ1": source_from["sourceZ"],
+            "sourceX2": source_to["sourceX"], "sourceY2": source_to["sourceY"], "sourceZ2": source_to["sourceZ"]}