fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/polar.py

@@ -0,0 +1,445 @@
+"""Native polar windrose scene geometry adapted from fastPlotJs core/polar.ts."""
+
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+from math import cos, floor, isfinite, log10, pi, sin
+from typing import Mapping
+
+from .defaults import DEFAULT_TRACE_COLORS, get_defaults
+from .native import rustCall
+
+
+def _finite(value, fallback):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) else fallback
+
+
+def _positive(value, fallback):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value > 0 else fallback
+
+
+def _nonnegative(value, fallback):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value >= 0 else fallback
+
+
+def _clamp(value, fallback, low, high):
+    return min(high, max(low, _finite(value, fallback)))
+
+
+def _integer(value, fallback, low, high):
+    return int(min(high, max(low, floor(_finite(value, fallback) + .5))))
+
+
+def _string(value, fallback):
+    return value if isinstance(value, str) and value.strip() else fallback
+
+
+def _angle(value):
+    return value % 360
+
+
+def _radians(value):
+    return value * pi / 180
+
+
+def _format(value, decimals, trim=False):
+    quantum = Decimal(1).scaleb(-decimals)
+    result = format(Decimal(str(value)).quantize(quantum, rounding=ROUND_HALF_UP), f".{decimals}f")
+    return result.rstrip("0").rstrip(".") if trim and decimals else result
+
+
+def _traces(options):
+    if options.get("traces"):
+        return list(options["traces"])
+    return [{"data": options["data"]}] if options.get("data") is not None else []
+
+
+def _angle_categories(raw, defaults):
+    if raw is None:
+        return list(defaults["angleCategories"])
+    if not isinstance(raw, list) or not raw:
+        raise ValueError("Polar angleCategories must be a non-empty array when provided")
+    if len(raw) > 360:
+        raise ValueError("Polar angleCategories must contain at most 360 entries")
+    if any(not isinstance(item, str) or not item.strip() for item in raw):
+        raise ValueError("Polar angleCategories must contain only non-empty strings")
+    if len(set(raw)) != len(raw):
+        raise ValueError("Polar angleCategories must contain unique strings")
+    return list(raw)
+
+
+def _resolve_angle(value, categories):
+    if categories:
+        if not isinstance(value, str):
+            raise ValueError("Categorical polar angles must be configured category strings")
+        if value not in categories:
+            raise ValueError(f"Unknown polar angle category '{value}'")
+        return categories.index(value) * 360 / len(categories)
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+        raise ValueError("Polar angles must be finite numbers")
+    return _angle(value)
+
+
+def _label_config(defaults, plot_raw, trace_raw):
+    labels = dict(defaults)
+    for raw in (plot_raw, trace_raw):
+        if raw is None:
+            continue
+        if isinstance(raw, bool):
+            labels["show"] = raw
+        elif isinstance(raw, Mapping):
+            labels["show"] = raw.get("show", True)
+            for key in ("color", "font"):
+                labels[key] = _string(raw.get(key), labels[key])
+            for key in ("lineHeight", "minSectorRadius", "minSectorAngleDegrees", "collisionPadding"):
+                labels[key] = _nonnegative(raw.get(key), labels[key])
+            labels["decimals"] = _integer(raw.get("decimals"), labels["decimals"], 0, 12)
+            labels["radiusRatio"] = _clamp(raw.get("radiusRatio"), labels["radiusRatio"], 0, 1)
+            for key in ("prefix", "suffix"):
+                if isinstance(raw.get(key), str):
+                    labels[key] = raw[key]
+    return labels
+
+
+def _sector_labels(sectors, labels):
+    if not labels["show"]:
+        return None
+    items = []
+    for index, sector in enumerate(sectors):
+        depth = sector["outerRadius"] - sector["innerRadius"]
+        span = abs(sector["endAngle"] - sector["startAngle"]) * 180 / pi
+        if depth < labels["minSectorRadius"] or span < labels["minSectorAngleDegrees"]:
+            continue
+        angle = (sector["startAngle"] + sector["endAngle"]) / 2
+        radius = sector["innerRadius"] + depth * labels["radiusRatio"]
+        items.append({"x": sector["centerX"] + cos(angle) * radius,
+                      "y": sector["centerY"] + sin(angle) * radius,
+                      "angle": sector["angle"], "value": sector["value"],
+                      "text": f"{labels['prefix']}{_format(sector['value'], labels['decimals'])}{labels['suffix']}",
+                      "color": labels["color"], "font": labels["font"],
+                      "lineHeight": labels["lineHeight"], "sectorIndex": index,
+                      "collisionPadding": labels["collisionPadding"]})
+    return items or None
+
+
+def _grid_primitive(raw, defaults, categories, low, high, scale, radius, width, height,
+                    center_x, center_y, outer_limit, start, clockwise, bounds):
+    grid_raw = raw.get("grid")
+    if grid_raw is None:
+        return None
+    grid = grid_raw if isinstance(grid_raw, Mapping) else {}
+    if grid.get("show", True) is False:
+        return None
+    settings = defaults["grid"]
+    rings_count = _integer(grid.get("rings"), settings["rings"], 0, 64)
+    spokes = _integer(grid.get("spokes"), len(categories) if categories else settings["spokes"], 0, 360)
+    explicit = grid.get("ringValues", settings["ringValues"])
+    if scale == "logarithmic" and any(isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value) or value <= 0 for value in explicit):
+        raise ValueError("Polar logarithmic ringValues must contain only finite values > 0")
+    ring_values = sorted({value for value in explicit if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value >= 0})
+    if ring_values:
+        ring_values = [value for value in ring_values if low <= value <= high]
+    elif rings_count:
+        if low == high:
+            ring_values = [high]
+        elif scale == "logarithmic":
+            ring_values = [10 ** (log10(low) + (index + 1) / rings_count * (log10(high) - log10(low))) for index in range(rings_count)]
+        else:
+            ring_values = [low + (index + 1) / rings_count * (high - low) for index in range(rings_count)]
+    label_raw = grid.get("labels")
+    angle_raw = grid.get("angleLabels")
+    base_label = settings["labels"]
+    base_angle = settings["angleLabels"]
+    label = {**base_label, **(label_raw if isinstance(label_raw, Mapping) else {})}
+    angle_label = {**base_angle, **(angle_raw if isinstance(angle_raw, Mapping) else {})}
+    label_show = label_raw if isinstance(label_raw, bool) else label.get("show", True) if label_raw is not None else base_label["show"]
+    angle_show = angle_raw if isinstance(angle_raw, bool) else angle_label.get("show", True) if angle_raw is not None else base_angle["show"]
+    if categories and angle_raw is not None and not isinstance(angle_raw, Mapping):
+        angle_label["labels"] = categories
+    elif categories and not isinstance(angle_raw, Mapping):
+        angle_label["labels"] = categories
+    ring_items, guide_items, labels, angle_labels = [], [], [], []
+    for value in ring_values:
+        r = radius(value)
+        ring_items.append({"centerX": center_x, "centerY": center_y, "radius": r, "value": value})
+        if label_show:
+            angle = _angle(_finite(label.get("angleDegrees"), base_label["angleDegrees"]))
+            theta = _radians(start + (angle if clockwise else -angle))
+            label_radius = r + _nonnegative(label.get("offset"), base_label["offset"])
+            decimals = _integer(label.get("decimals"), base_label["decimals"], 0, 12)
+            labels.append({"x": center_x + cos(theta) * label_radius,
+                           "y": center_y + sin(theta) * label_radius,
+                           "radius": r, "value": value,
+                           "text": f"{label.get('prefix', base_label['prefix'])}{_format(value, decimals, True)}{label.get('suffix', base_label['suffix'])}",
+                           "angle": angle})
+    for index in range(spokes):
+        angle = index * 360 / spokes
+        theta = _radians(start + (angle if clockwise else -angle))
+        guide_items.append({"centerX": center_x, "centerY": center_y,
+                            "endX": center_x + cos(theta) * outer_limit,
+                            "endY": center_y + sin(theta) * outer_limit, "angle": angle})
+        if angle_show:
+            label_radius = outer_limit + _nonnegative(angle_label.get("offset"), base_angle["offset"])
+            explicit_labels = angle_label.get("labels", categories if categories else base_angle["labels"])
+            text = explicit_labels[index] if index < len(explicit_labels) and isinstance(explicit_labels[index], str) and explicit_labels[index].strip() else f"{angle_label.get('prefix', base_angle['prefix'])}{_format(angle, _integer(angle_label.get('decimals'), base_angle['decimals'], 0, 12), True)}{angle_label.get('suffix', base_angle['suffix'])}"
+            angle_labels.append({"x": center_x + cos(theta) * label_radius,
+                                 "y": center_y + sin(theta) * label_radius, "angle": angle, "text": text})
+    if not ring_items and not guide_items:
+        return None
+    ring_color = _string(grid.get("ringColor"), settings["ringColor"])
+    spoke_color = _string(grid.get("spokeColor"), settings["spokeColor"])
+    ring_width = _nonnegative(grid.get("ringLineWidth"), settings["ringLineWidth"])
+    spoke_width = _nonnegative(grid.get("spokeLineWidth"), settings["spokeLineWidth"])
+    points = ([{"x": item["centerX"] + item["radius"], "y": item["centerY"]} for item in ring_items]
+              + [{"x": item["endX"], "y": item["endY"]} for item in guide_items]
+              + [{"x": item["x"], "y": item["y"]} for item in labels]
+              + [{"x": item["x"], "y": item["y"]} for item in angle_labels])
+    return {"type": "polar", "points": points, "color": ring_color, "lineWidth": ring_width,
+            "polarGrid": {"rings": ring_items, "angleGuides": guide_items, "labels": labels,
+                          "angleLabels": angle_labels, "ringColor": ring_color, "spokeColor": spoke_color,
+                          "labelColor": _string(label.get("color"), base_label["color"]),
+                          "labelFont": _string(label.get("font"), base_label["font"]),
+                          "angleLabelColor": _string(angle_label.get("color"), base_angle["color"]),
+                          "angleLabelFont": _string(angle_label.get("font"), base_angle["font"]),
+                          "ringLineWidth": ring_width, "spokeLineWidth": spoke_width},
+            "subplot": "main", "bounds": bounds}
+
+
+def _vector_style(defaults, raw, fallback=None):
+    base = dict(defaults if fallback is None else fallback)
+    if isinstance(raw, bool):
+        base["show"] = raw
+        base["directions"] = []
+        return base
+    if not isinstance(raw, Mapping):
+        return base
+    base["show"] = raw.get("show", True)
+    base["color"] = _string(raw.get("color"), base["color"])
+    for key in ("lineWidth", "headSize"):
+        base[key] = _nonnegative(raw.get(key), base[key])
+    base["headAngleDegrees"] = _clamp(_positive(raw.get("headAngleDegrees"), base["headAngleDegrees"]), base["headAngleDegrees"], 5, 85)
+    directions = []
+    for item in raw.get("directions") or []:
+        value = item if isinstance(item, (int, float)) and not isinstance(item, bool) else item.get("directionDegrees", item.get("direction")) if isinstance(item, Mapping) else None
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+            continue
+        direction = {**base, "angle": _angle(value)}
+        if isinstance(item, Mapping):
+            direction["color"] = _string(item.get("color"), base["color"])
+            for key in ("lineWidth", "headSize"):
+                direction[key] = _nonnegative(item.get(key), base[key])
+            direction["headAngleDegrees"] = _clamp(_positive(item.get("headAngleDegrees"), base["headAngleDegrees"]), base["headAngleDegrees"], 5, 85)
+        directions.append(direction)
+    base["directions"] = directions
+    return base
+
+
+def _vector_primitive(angles, style, color, value, center_x, center_y, outer_limit,
+                      start, clockwise, bounds):
+    if not style["show"] or not angles:
+        return None
+    vectors = []
+    for angle, number, selected in angles:
+        theta = _radians(start + (angle if clockwise else -angle))
+        vectors.append({"centerX": center_x, "centerY": center_y,
+                        "endX": center_x + cos(theta) * outer_limit,
+                        "endY": center_y + sin(theta) * outer_limit,
+                        "angle": angle, "value": number if number is not None else value,
+                        "color": selected.get("color") or color,
+                        "lineWidth": selected["lineWidth"], "headSize": selected["headSize"],
+                        "headAngle": _radians(selected["headAngleDegrees"])})
+    return {"type": "polar", "points": [{"x": item["endX"], "y": item["endY"]} for item in vectors],
+            "color": color, "lineWidth": style["lineWidth"], "polarVectors": vectors,
+            "subplot": "main", "bounds": bounds}
+
+
+def polar_scene(options: Mapping, width: float, height: float) -> dict:
+    defaults = get_defaults("polar")
+    raw = options.get("polar") or {}
+    renderer_style_fields = {"backgroundColor", "text", "title", "subtitle", "plotArea", "axes", "legend", "tooltip"}
+    style = options.get("style") or {}
+    trace_style = style.get("trace") or {}
+    style_line_color = (trace_style.get("line") or {}).get("color")
+    plot_line_color = (options.get("lineStyle") or {}).get("color")
+    if (options.get("engine") != "rust" and not options.get("traces") and not raw and not options.get("polarVector")
+            and not (isinstance(plot_line_color, str) and plot_line_color.strip())
+            and not (set(style) - renderer_style_fields - {"trace"})
+            and not (set(trace_style) - {"line", "marker"})
+            and not (isinstance(style_line_color, str) and style_line_color.strip())):
+        from .families2d import polar_scene as baseline_polar_scene
+        return baseline_polar_scene(options, width, height)
+    if raw.get("mode", defaults["mode"]) != "windrose":
+        raise ValueError("Only polar mode 'windrose' is supported")
+    scale = raw.get("radialScale", defaults["radialScale"])
+    if scale not in ("linear", "logarithmic"):
+        raise ValueError("Polar radialScale must be 'linear' or 'logarithmic'")
+    mode = raw.get("sectorMode", defaults["sectorMode"])
+    if mode not in ("grouped", "stacked"):
+        raise ValueError("Polar sectorMode must be 'grouped' or 'stacked'")
+    if mode == "stacked" and scale == "logarithmic":
+        raise ValueError("Polar stacked sectors require a linear radialScale")
+    for name in ("minRadius", "maxRadius"):
+        if scale == "logarithmic" and name in raw:
+            value = raw[name]
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value) or value <= 0:
+                raise ValueError(f"Polar logarithmic {name} must be finite and > 0")
+    if scale == "logarithmic" and "minRadius" in raw and "maxRadius" in raw and raw["maxRadius"] <= raw["minRadius"]:
+        raise ValueError("Polar logarithmic maxRadius must be greater than minRadius")
+    categories = _angle_categories(raw.get("angleCategories"), defaults)
+    traces = _traces(options)
+    parsed = []
+    running = {}
+    grouped = [index for index, trace in enumerate(traces) if trace.get("visible") is not False]
+    observed = []
+    for trace_index, trace in enumerate(traces):
+        points = []
+        if trace.get("visible") is not False:
+            for source_index, point in enumerate(trace.get("data", [])):
+                if point.get("x") is None or point.get("y") is None:
+                    continue
+                angle = _resolve_angle(point["x"], categories)
+                value = point["y"]
+                if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                    raise ValueError("Polar windrose values require finite y")
+                if scale == "logarithmic" and value <= 0:
+                    raise ValueError("Polar logarithmic radial scale requires y > 0")
+                if value < 0:
+                    raise ValueError("Polar windrose values require y >= 0")
+                base = running.get(angle, 0) if mode == "stacked" and value > 0 else 0
+                total = base + value
+                if mode == "stacked" and value > 0:
+                    running[angle] = total
+                points.append((source_index, angle, value, base, total))
+                observed.append(total)
+        parsed.append(points)
+    if not observed and not (raw.get("minRadius") is not None and raw.get("maxRadius") is not None):
+        return {"width": width, "height": height, "primitives": []}
+    if scale == "logarithmic":
+        low = raw.get("minRadius", min(observed))
+        high = raw.get("maxRadius", max(observed))
+        if "maxRadius" in raw and high < low:
+            raise ValueError("Polar logarithmic maxRadius must not be below the inferred radial minimum")
+        high = max(high, low)
+    else:
+        low = _nonnegative(raw.get("minRadius"), defaults["minRadius"])
+        configured_high = raw.get("maxRadius")
+        high = configured_high if isinstance(configured_high, (int, float)) and isfinite(configured_high) and configured_high > low else max(observed)
+        if high <= low:
+            high = low + 1
+    outer_ratio = _clamp(raw.get("outerRadiusRatio"), defaults["outerRadiusRatio"], .05, 1)
+    inner_ratio = _clamp(raw.get("innerRadiusRatio"), defaults["innerRadiusRatio"], 0, .95)
+    center_x, center_y = width / 2, height / 2
+    outer_limit = min(width, height) / 2 * outer_ratio
+    inner_limit = outer_limit * inner_ratio
+    available = max(0, outer_limit - inner_limit)
+    def radius(value):
+        if high == low:
+            return outer_limit if value >= high else inner_limit
+        selected, minimum, maximum = (log10(value), log10(low), log10(high)) if scale == "logarithmic" else (value, low, high)
+        ratio = max(0, min(1, (selected - minimum) / max(2.220446049250313e-16, maximum - minimum)))
+        return inner_limit + ratio * available
+    start = _finite(raw.get("startAngleDegrees"), defaults["startAngleDegrees"])
+    clockwise = raw.get("clockwise", defaults["clockwise"])
+    full_width = min(360, max(1, _positive(raw.get("sectorWidthDegrees"), defaults["sectorWidthDegrees"])))
+    group_count = 1 if mode == "stacked" else max(1, len(grouped))
+    sector_width = full_width / group_count
+    plot_gap = min(360, _nonnegative(raw.get("sectorGapDegrees"), defaults["sectorGapDegrees"]))
+    plot_opacity = _clamp(raw.get("sectorOpacity"), defaults["sectorOpacity"], 0, 1)
+    plot_border_width = _nonnegative(raw.get("borderWidth"), defaults["borderWidth"])
+    plot_border_color = _string(raw.get("borderColor"), defaults["borderColor"])
+    bounds = {"left": 0, "top": 0, "right": width, "bottom": height}
+    primitives = []
+    grid_primitive = _grid_primitive(raw, defaults, categories, low, high, scale, radius,
+                                     width, height, center_x, center_y, outer_limit, start, clockwise, bounds)
+    if grid_primitive is not None:
+        primitives.append(grid_primitive)
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        trace_raw = trace.get("polar") 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)]
+        opacity = _clamp(trace_raw.get("sectorOpacity"), plot_opacity, 0, 1)
+        border_width = _nonnegative(trace_raw.get("borderWidth"), plot_border_width)
+        border_color = _string(trace_raw.get("borderColor"), plot_border_color)
+        gap = min(360, _nonnegative(trace_raw.get("sectorGapDegrees"), plot_gap), sector_width * .95)
+        group_index = 0 if mode == "stacked" else grouped.index(trace_index)
+        if options.get("engine") == "rust":
+            active = [(source_index, angle, value, base, total) for source_index, angle, value, base, total in parsed[trace_index] if value > 0]
+            native = rustCall("polar", input={
+                "width": width, "height": height,
+                "traces": [{
+                    "points": [{"x": angle, "y": total} for _, angle, _, _, total in active],
+                    "innerValues": [base for _, _, _, base, _ in active] if mode == "stacked" else None,
+                    "values": [value for _, _, value, _, _ in active] if mode == "stacked" else None,
+                    "centerX": center_x, "centerY": center_y,
+                    "innerRadius": inner_limit, "availableRadius": available,
+                    "sectorWidthDegrees": full_width, "sectorGapDegrees": gap,
+                    "startAngleDegrees": start, "clockwise": clockwise,
+                    "radialScale": scale, "minRadius": low, "maxRadius": high,
+                    "groupIndex": group_index, "groupCount": group_count,
+                    "color": color, "lineWidth": border_width,
+                    "borderColor": border_color, "borderWidth": border_width,
+                    "subplot": "main", "bounds": bounds,
+                }],
+            })
+            if not native["primitives"]:
+                continue
+            primitive = native["primitives"][0]
+            for sector, (source_index, *_rest) in zip(primitive["polarSectors"], active):
+                sector["opacity"] = opacity
+                sector["sourceIndex"] = source_index
+            primitive["traceIndex"] = trace_index
+            labels = _sector_labels(primitive["polarSectors"], _label_config(defaults["sectorLabels"], raw.get("sectorLabels"), trace_raw.get("sectorLabels")))
+            if labels:
+                primitive["polarSectorLabels"] = labels
+            primitives.append(primitive)
+            continue
+        sectors = []
+        for source_index, angle, value, base, total in parsed[trace_index]:
+            if value == 0:
+                continue
+            oriented = start + (angle if clockwise else -angle)
+            begin = oriented - full_width / 2 + group_index * sector_width + gap / 2
+            end = begin + sector_width - gap
+            sectors.append({"centerX": center_x, "centerY": center_y,
+                            "innerRadius": radius(base) if mode == "stacked" else inner_limit,
+                            "outerRadius": radius(total), "startAngle": _radians(begin),
+                            "endAngle": _radians(end), "angle": angle, "value": value,
+                            "opacity": opacity, "sourceIndex": source_index})
+        if not sectors:
+            continue
+        points = [{"x": center_x + cos((sector["startAngle"] + sector["endAngle"]) / 2) * sector["outerRadius"],
+                   "y": center_y + sin((sector["startAngle"] + sector["endAngle"]) / 2) * sector["outerRadius"]} for sector in sectors]
+        primitive = {"type": "polar", "points": points, "polarSectors": sectors,
+                     "color": color, "lineWidth": border_width, "borderColor": border_color,
+                     "borderWidth": border_width, "traceIndex": trace_index, "subplot": "main", "bounds": bounds}
+        labels = _sector_labels(sectors, _label_config(defaults["sectorLabels"], raw.get("sectorLabels"), trace_raw.get("sectorLabels")))
+        if labels:
+            primitive["polarSectorLabels"] = labels
+        primitives.append(primitive)
+    global_vectors = _vector_style(defaults["vectors"], raw.get("vectors"))
+    if global_vectors["show"] and global_vectors["directions"]:
+        color = global_vectors["color"] or DEFAULT_TRACE_COLORS[0]
+        angles = [(item["angle"], None, item) for item in global_vectors["directions"]]
+        direction_primitive = _vector_primitive(angles, global_vectors, color, high, center_x, center_y,
+                                                outer_limit, start, clockwise, bounds)
+        if direction_primitive:
+            primitives.append(direction_primitive)
+    for trace_index, trace in enumerate(traces):
+        if trace.get("visible") is False:
+            continue
+        trace_raw = trace.get("polarVector")
+        vector_style = _vector_style(defaults["vectors"], trace_raw, global_vectors)
+        if not vector_style["show"] or trace_raw is None and global_vectors["directions"]:
+            continue
+        trace_color = (trace.get("lineStyle") or {}).get("color") or trace.get("color") or DEFAULT_TRACE_COLORS[trace_index % len(DEFAULT_TRACE_COLORS)]
+        color = vector_style["color"] or trace_color
+        if vector_style["directions"]:
+            angles = [(item["angle"], None, item) for item in vector_style["directions"]]
+        else:
+            angles = [(angle, value, vector_style) for _, angle, value, _, _ in parsed[trace_index] if value > 0]
+        vector_primitive = _vector_primitive(angles, vector_style, color, high, center_x, center_y,
+                                             outer_limit, start, clockwise, bounds)
+        if vector_primitive:
+            primitives.append(vector_primitive)
+    return {"width": width, "height": height, "primitives": primitives}

fastplotpy/polygon_clip3d.py

@@ -0,0 +1,148 @@
+"""Source-compatible domain and camera clipping for 3D triangle fragments."""
+
+from __future__ import annotations
+
+from math import fabs
+
+
+# Pinned scene3d.ts constants: coordinate deduplication, plane tolerance,
+# and maximum possible fragments after clipping a triangle by six planes.
+_CLIP_EPSILON = 1e-12
+_MAX_FRAGMENTS = 13
+_BINARY64_EPSILON = 2.220446049250313e-16
+
+
+def _interpolate(first, second, ratio, position_key):
+    source_index = (first["sourceIndex"] if ratio < .5 else
+                    second["sourceIndex"] if ratio > .5 else
+                    min(first["sourceIndex"], second["sourceIndex"]))
+    return {position_key: tuple(first[position_key][axis] +
+                                (second[position_key][axis] - first[position_key][axis]) * ratio
+                                for axis in range(3)),
+            "sourceIndex": source_index,
+            **{key: first[key] + (second[key] - first[key]) * ratio
+               for key in ("sourceX", "sourceY", "sourceZ")}}
+
+
+def _same(first, second, position_key):
+    return all(abs(first[position_key][axis] - second[position_key][axis]) <= _CLIP_EPSILON
+               for axis in range(3))
+
+
+def _deduplicate(vertices, position_key):
+    result = []
+    for vertex in vertices:
+        if not result or not _same(result[-1], vertex, position_key):
+            result.append(vertex)
+    if len(result) > 1 and _same(result[0], result[-1], position_key):
+        result.pop()
+    return result
+
+
+def _clip_polygon(vertices, planes, position_key):
+    polygon = list(vertices)
+    for plane in planes:
+        if len(polygon) < 3:
+            return []
+        clipped = []
+        previous = polygon[-1]
+        previous_distance = plane(previous[position_key])
+        previous_inside = previous_distance >= -_CLIP_EPSILON
+        for current in polygon:
+            current_distance = plane(current[position_key])
+            current_inside = current_distance >= -_CLIP_EPSILON
+            if previous_inside != current_inside:
+                denominator = previous_distance - current_distance
+                ratio = (0 if abs(denominator) <= _CLIP_EPSILON else
+                         max(0, min(1, previous_distance / denominator)))
+                clipped.append(_interpolate(previous, current, ratio, position_key))
+            if current_inside:
+                clipped.append(current)
+            previous, previous_distance, previous_inside = current, current_distance, current_inside
+        polygon = _deduplicate(clipped, position_key)
+    return polygon if len(polygon) >= 3 else []
+
+
+def clip_domain_triangle(vertices, domains):
+    planes = (lambda point: point[0] + .5, lambda point: .5 - point[0],
+              lambda point: point[1] + .5, lambda point: .5 - point[1],
+              lambda point: point[2] + .5, lambda point: .5 - point[2])
+    polygon = _clip_polygon(vertices, planes, "world")
+    if not polygon:
+        return []
+    result = []
+    for vertex in polygon:
+        vertex = {**vertex, "world": list(vertex["world"])}
+        for axis, name in enumerate("xyz"):
+            world = vertex["world"][axis]
+            if abs(world + .5) <= _CLIP_EPSILON:
+                vertex["world"][axis] = -.5
+                vertex[f"source{name.upper()}"] = domains[name]["min"]
+            elif abs(world - .5) <= _CLIP_EPSILON:
+                vertex["world"][axis] = .5
+                vertex[f"source{name.upper()}"] = domains[name]["max"]
+        vertex["world"] = tuple(vertex["world"])
+        result.append(vertex)
+    return result
+
+
+def project_polygon(vertices, projector):
+    if not vertices:
+        return []
+    camera = projector.camera
+    def to_camera(world):
+        from .scene3d import _subtract, _dot
+        relative = _subtract(world, camera["eye"])
+        return (_dot(relative, projector.right), _dot(relative, projector.up),
+                _dot(relative, projector.forward))
+    polygon = [{"camera": to_camera(vertex["world"]),
+                **{key: vertex[key] for key in ("sourceIndex", "sourceX", "sourceY", "sourceZ")}}
+               for vertex in vertices]
+    if camera["projection"] == "perspective":
+        planes = (lambda point: point[2] - camera["near"],
+                  lambda point: camera["far"] - point[2],
+                  lambda point: point[0] + point[2] * projector.tangent * projector.aspect,
+                  lambda point: point[2] * projector.tangent * projector.aspect - point[0],
+                  lambda point: point[1] + point[2] * projector.tangent,
+                  lambda point: point[2] * projector.tangent - point[1])
+    else:
+        half_height = camera["orthographicScale"] / 2
+        half_width = half_height * projector.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])
+    polygon = _clip_polygon(polygon, planes, "camera")
+    if not polygon:
+        return []
+    projected = []
+    for vertex in polygon:
+        point = vertex["camera"]
+        if camera["projection"] == "perspective":
+            ndc_x = point[0] / (point[2] * projector.tangent * projector.aspect)
+            ndc_y = point[1] / (point[2] * projector.tangent)
+        else:
+            ndc_x = point[0] / half_width
+            ndc_y = point[1] / half_height
+        projected.append({"x": (max(-1, min(1, ndc_x)) + 1) * projector.width / 2,
+                          "y": (1 - max(-1, min(1, ndc_y))) * projector.height / 2,
+                          "depth": max(0, min(1, (point[2] - camera["near"]) /
+                                                (camera["far"] - camera["near"]))),
+                          **{key: vertex[key] for key in ("sourceIndex", "sourceX", "sourceY", "sourceZ")}})
+    result = []
+    for index in range(1, len(projected) - 1):
+        first, second, third = projected[0], projected[index], projected[index + 1]
+        twice_area = ((second["x"] - first["x"]) * (third["y"] - first["y"])
+                      - (second["y"] - first["y"]) * (third["x"] - first["x"]))
+        max_delta = max(abs(second["x"] - first["x"]), abs(second["y"] - first["y"]),
+                        abs(third["x"] - first["x"]), abs(third["y"] - first["y"]))
+        tolerance = _BINARY64_EPSILON * max(1, max_delta * max_delta) * 64
+        if abs(twice_area) <= tolerance:
+            continue
+        result.append({"vertices": [first, second, third],
+                       "boundaryEdges": [index == 1, True, index == len(projected) - 2]})
+    if len(result) > _MAX_FRAGMENTS:
+        raise ValueError("scene3d triangle clipping exceeded its bounded fragment limit")
+    return result