@volter/blender-engine 0.1.8 → 0.1.9

package/browser/session.py

@@ -523,6 +523,10 @@ def draw_camera(obj):
         "shift_x": float(camera.shift_x),
         "shift_y": float(camera.shift_y),
         "matrix": [[float(v) for v in row] for row in obj.matrix_world],
+        # What the 3D View's camera view darkens outside the frame (`drawviewborder`).
+        "passepartout": float(camera.passepartout_alpha) if camera.show_passepartout else 0.0,
+        # The size the overlay draws the camera at (`Camera.display_size`, `cam->drawsize`).
+        "display_size": float(camera.display_size),
     }
 
 
@@ -732,6 +736,107 @@ def _refusal(node):
     return None
 
 
+
+def _empty_display(obj):
+    """An empty's display (`overlay_empty.hh`): its type and size, and for an image empty the
+    picture, where it sits on the object (`empty_image_offset`), how it meets depth, which side
+    shows, in which projections, its opacity when it blends, the object colour the picture is
+    multiplied by (`ucolor`) and whether the image stores premultiplied alpha."""
+    display = {"display": obj.empty_display_type, "size": float(obj.empty_display_size)}
+    if obj.empty_display_type == "IMAGE":
+        display["image"] = {
+            "name": obj.data.name if obj.data is not None else None,
+            "offset": [float(v) for v in obj.empty_image_offset],
+            "depth": obj.empty_image_depth,
+            "side": obj.empty_image_side,
+            "perspective": bool(obj.show_empty_image_perspective),
+            "orthographic": bool(obj.show_empty_image_orthographic),
+            "axis_aligned": bool(obj.show_empty_image_only_axis_aligned),
+            "opacity": float(obj.color[3]) if obj.use_empty_image_alpha else None,
+            "tint": [float(v) for v in obj.color[:3]],
+            "premultiplied": obj.data is not None and obj.data.alpha_mode == "PREMUL",
+        }
+    return display
+
+
+def _saved_view():
+    """The 3D View the file saved, which is where Blender opens it: the `Modeling` workspace's
+    (this editor's Model workspace is Blender's Modeling), else the first 3D View any screen
+    holds. `RegionView3D`'s pivot, rotation (view to world, `(w, x, y, z)`), distance and
+    projection (`PERSP`, `ORTHO`, or `CAMERA` for a view through the scene camera), and the
+    `View3D`'s lens."""
+    workspace = bpy.data.workspaces.get("Modeling")
+    screens = list(workspace.screens) if workspace is not None else []
+    screens.extend(bpy.data.screens)
+    for screen in screens:
+        for area in screen.areas:
+            if area.type != "VIEW_3D":
+                continue
+            space = area.spaces[0]
+            region = space.region_3d
+            return {
+                "lens": float(space.lens),
+                "location": [float(v) for v in region.view_location],
+                "rotation": [float(v) for v in region.view_rotation],
+                "distance": float(region.view_distance),
+                "perspective": region.view_perspective,
+            }
+    return None
+
+
+def _subject_line(scene, view_layer):
+    """The 3D Viewport's second overlay line, as `draw_selected_name` (`view3d_draw.cc`) writes it,
+    less the two parts that follow the playhead: the tab draws `(frame)` and the marker on it
+    from the frame it is showing, which during playback is not `frame_current` (written once, on
+    pause). Here: in Object Mode (or with nothing active) the active collection and a bar, then
+    the active object; outside Object Mode its data's name; the active edit or pose bone, or the
+    active shape key (` (Soloed)` when pinned). The scene's markers go with it, in list order,
+    for `BKE_scene_find_marker_name`. Blender tints the line on a keyframe; that colour is not
+    carried, and the ` (Viewer)` suffix belongs to a viewer path this tab does not show."""
+    parts = []
+    ob = view_layer.objects.active
+    if ob is None or ob.mode == "OBJECT":
+        # `BKE_collection_ui_name_get`: the master collection reads "Scene Collection", which is
+        # also what its RNA name returns.
+        parts.append(" " + view_layer.active_layer_collection.collection.name)
+        if ob is not None:
+            parts.append(" |")
+    if ob is not None:
+        parts.append(" " + ob.name)
+        if ob.mode != "OBJECT" and ob.data is not None:
+            parts.append(" | " + ob.data.name)
+        if ob.type == "ARMATURE":
+            arm = ob.data
+            if ob.mode == "EDIT":
+                if arm.edit_bones.active is not None:
+                    parts.append(" : " + arm.edit_bones.active.name)
+            elif ob.mode == "POSE" and arm.bones.active is not None and _bone_shown(arm.bones.active):
+                parts.append(" : " + arm.bones.active.name)
+        elif ob.type in ("MESH", "LATTICE", "CURVE"):
+            if ob.type == "MESH" and ob.mode == "WEIGHT_PAINT":
+                rig = ob.find_armature()
+                if rig is not None and rig.mode == "POSE":
+                    bone = rig.data.bones.active
+                    if bone is not None and _bone_shown(bone):
+                        parts.append(" : " + bone.name)
+            key = ob.active_shape_key if getattr(ob.data, "shape_keys", None) is not None else None
+            if key is not None:
+                parts.append(" : " + key.name)
+                if ob.show_only_shape_key:
+                    parts.append(" (Soloed)")
+    return {
+        "frame": int(scene.frame_current),
+        "body": "".join(parts),
+        "markers": [[int(m.frame), m.name] for m in scene.timeline_markers],
+    }
+
+
+def _bone_shown(bone):
+    """`ANIM_bonecoll_is_visible_actbone`: a bone in no collection, or in a visible one."""
+    collections = getattr(bone, "collections", None)
+    return not collections or any(c.is_visible for c in collections)
+
+
 class _GraphRefusal(Exception):
     pass
 
@@ -1231,9 +1336,13 @@ class Session:
         """
         scene = bpy.context.scene
         graphs = material_graphs(scene)
+        # An IMAGE EMPTY's picture travels with the graphs' images: the overlay draws it
+        # (`overlay_empty.hh` `image_sync`).
+        empty_images = {obj.data.name for obj in scene.objects
+                        if obj.type == "EMPTY" and obj.empty_display_type == "IMAGE" and obj.data is not None}
         options = {"session": self.session, "evaluate": True, "known": self._known,
                    "graph_materials": sorted(graphs),
-                   "graph_images": sorted({i for g in graphs.values() for i in g["images"]}),
+                   "graph_images": sorted({i for g in graphs.values() for i in g["images"]} | empty_images),
                    "graph_generated": sorted(n for n, g in graphs.items() if g["generated"])}
         # THE ARENA IS WRITTEN BEFORE THE ASK, and on a skew whose channel is
         # an ordered stream of filesystem patches that is the whole
@@ -1288,14 +1397,55 @@ class Session:
                 default_color = getattr(getattr(data, "color_attributes", None), "default_color_name", "")
                 if default_color:
                     row["default_color"] = default_color
+        # THE VIEWPORT DISPLAY of each material -- what Blender's Solid shading colours a surface
+        # by (`View3DShading.color_type` MATERIAL reads `Material.diffuse_color`, `roughness`,
+        # `metallic`; `workbench_world_light_lib.glsl`), not its node graph.
+        for entry in frame["materials"].values():
+            material = bpy.data.materials.get(entry.get("name", ""))
+            if material is not None:
+                entry["viewport"] = {
+                    "color": [float(v) for v in material.diffuse_color],
+                    "roughness": float(material.roughness),
+                    "metallic": float(material.metallic),
+                }
         frame["world"] = draw_world(scene)
         frame["cameras"] = {
             obj.name: draw_camera(obj) for obj in scene.objects if obj.type == "CAMERA"
         }
         frame["volumes"] = {}
+        # THE CAMERA A CAMERA VIEW LOOKS THROUGH (`view3d.view_camera`: the scene's, else a
+        # camera that is active, else the view layer's first) and the frame it draws, the
+        # render's shape with its pixel aspect.
+        render = scene.render
+        frame["camera_view"] = {
+            "scene_camera": scene.camera.name if scene.camera is not None else None,
+            "view_layer_cameras": [o.name for o in bpy.context.view_layer.objects if o.type == "CAMERA"],
+            "aspect": (render.resolution_x * render.pixel_aspect_x) / max(render.resolution_y * render.pixel_aspect_y, 1e-6),
+        }
+        # THE 3D CURSOR, `Scene.cursor`: where Blender's own "to 3D Cursor"
+        # operators place and snap, drawn by the tab as Blender's overlay does
+        # (`overlay_cursor.hh`). Its MATRIX, because the overlay's axis lines
+        # turn with the cursor's rotation in whichever `rotation_mode` it has.
+        frame["cursor"] = [[float(v) for v in row] for row in scene.cursor.matrix]
         # THE OVERLAYS, after the door's frame stands: `_weights` reads the
         # mesh's own revision out of it (see there), so it cannot run before.
         view_layer = bpy.context.view_layer
+        # THE VIEWPORT'S SUBJECT LINE and the units its grid step is named in: Blender composes
+        # both from the scene, so they come from here (`_subject_line`).
+        frame["subject"] = _subject_line(scene, view_layer)
+        # A LIGHT'S DISTANCES, for the overlay's direction line (`overlay_light.hh`: from
+        # `clipsta` to `att_dist` down the light's -Z, for a spot or an area light).
+        frame["light_distances"] = {
+            light.name: [float(light.shadow_buffer_clip_start), float(light.cutoff_distance)]
+            for light in bpy.data.lights
+        }
+        # WHAT THE OVERLAY DRAWS FOR AN EMPTY (`overlay_empty.hh`): its display type and size.
+        frame["empties"] = {obj.name: _empty_display(obj) for obj in scene.objects if obj.type == "EMPTY"}
+        frame["view"] = _saved_view()
+        frame["units"] = {
+            "system": scene.unit_settings.system,
+            "scale_length": float(scene.unit_settings.scale_length),
+        }
         frame["armatures"] = _armatures(view_layer)
         frame["weights"] = _weights(scene, view_layer, frame, self._known)
         warnings = list(frame.get("warnings", ()))
@@ -4625,7 +4775,32 @@ def outliner_set(path, column, value):
         % (column, target.bl_rna.identifier, path))
 
 
+# REQUESTS THAT CAN REMOVE OBJECTS, watched: a removal is reported with its cause, because an
+# object that disappears without a named act is the loss this session must never hide. A scene
+# was once found emptied and saved over its file by a burst of three edits at boot, with nothing
+# recording which requests they were.
+_WATCHED_OPS = ("execute", "rna-set", "outliner-set", "history-step")
+
+
 def dispatch(request):
+    op = request.get("op")
+    if op not in _WATCHED_OPS:
+        return _dispatch_request(request)
+    before = {o.name for o in bpy.data.objects}
+    try:
+        return _dispatch_request(request)
+    finally:
+        removed = before - {o.name for o in bpy.data.objects}
+        if removed:
+            cause = {k: request[k] for k in ("label", "property", "column", "direction", "token", "path")
+                     if k in request}
+            if op == "execute":
+                cause["code"] = str(request.get("code", ""))[:160]
+            _say("@@VGAI-WARN %s removed objects %s (%s); %d remain" % (
+                op, sorted(removed), json.dumps(cause), len(bpy.data.objects)))
+
+
+def _dispatch_request(request):
     op = request.get("op")
     if op == "history-begin":
         HISTORY.begin()

package/browser/three/blender-node-graph.ts

@@ -823,15 +823,24 @@ class Compiler {
           if (extension === 'CLIP')
             body.push(`if (any(lessThan(${co}.xy, vec2(0.0))) || any(greaterThan(${co}.xy, vec2(1.0)))) { ${color} = vec4(0.0); ${alpha} = 0.0; }`);
         }
-        // node_shader_gpu_tex_image's Color output, for three's straight-alpha
-        // upload: cleared for ignored/packed/data alpha; premultiplied (and
-        // cleared) when Alpha is used; straight otherwise.
+        // node_shader_gpu_tex_image's Color output over the file's own texels (straight, or
+        // premultiplied for a PREMUL image, as Blender's GPU texture holds them): alpha cleared for
+        // ignored, packed or data alpha; otherwise straight when Alpha is used, so a factor does
+        // not multiply it in twice, and premultiplied when it is not. Measured in Blender 5.2's
+        // EEVEE: a straight red texel at alpha 0.5 emits 0.502 with Alpha unused, 1.0 with it used.
+        // A PREMUL sRGB image differs: the sampler decodes the premultiplied bytes, `decode(r·a)`,
+        // where Blender's texture holds `linear(r)·a`, so its partly transparent texels read darker.
         const mode = prop<string>(node, 'image_alpha_mode');
         const alphaUsed = this.uses(key, 1);
-        if (mode === 'NONE' || mode === 'CHANNEL_PACKED' || prop<boolean>(node, 'image_is_data') || !alphaUsed)
-          body.push(`${outs([0])}.a = 1.0;`);
+        const c = outs([0]);
+        if (mode === 'NONE' || mode === 'CHANNEL_PACKED' || prop<boolean>(node, 'image_is_data'))
+          body.push(`${c}.a = 1.0;`);
+        else if (mode === 'PREMUL')
+          body.push(alphaUsed
+            ? `if (${c}.a != 0.0 && ${c}.a != 1.0) ${c}.rgb /= ${c}.a;`
+            : `${c}.a = 1.0;`);
         else
-          body.push(`${outs([0])} = vec4(${outs([0])}.rgb * ${outs([0])}.a, 1.0);`);
+          body.push(alphaUsed ? `${c}.a = 1.0;` : `${c}.rgb *= ${c}.a;`);
         break;
       }
     }

package/browser/three/blender-runtime-camera-view.ts

@@ -0,0 +1,137 @@
+/**
+ * BLENDER'S CAMERA VIEW — `view3d.view_camera`, the view through a scene camera — as a window
+ * and a frame for a region, transcribed from `BKE_camera_params_from_view3d` (the `RV3D_CAMOB`
+ * branch), `BKE_camera_params_compute_viewplane` and `ED_view3d_calc_camera_border`.
+ *
+ * THE REGION sees the camera's sensor, fitted to the REGION's shape (`AUTO` fits its larger
+ * side), at a zoom of `1 / fac`, where `fac` is the view's `BKE_screen_view3d_zoom_to_fac(
+ * camzoom)`: 0.5 at the factory `camzoom` of 0, so the region spans twice the sensor. THE
+ * FRAME is the same camera fitted to the RENDER's shape at zoom 1, so at `fac` 0.5 it spans
+ * half the region along the fitted side. The lens shift moves both alike (`shift × zoom` then
+ * divided back out). THE PAN is Blender's own `camdx`/`camdy` (`view_move`: `camdx += -dx /
+ * (winx * 2 * fac)`, held to ±1), which moves the region's window by `2 · camdx · fac` of its
+ * width — so a zoom scales a panned frame's distance from the centre, as Blender's does.
+ *
+ * A panoramic camera is drawn as a perspective one.
+ */
+import * as THREE from 'three';
+import { z } from 'zod';
+
+const scalar = z.number().finite();
+/** `session.py`'s `draw_camera`. */
+export const cameraDataSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  lens: scalar,
+  sensor_width: scalar,
+  sensor_height: scalar,
+  sensor_fit: z.enum(['AUTO', 'HORIZONTAL', 'VERTICAL']),
+  ortho_scale: scalar,
+  clip_start: scalar,
+  clip_end: scalar,
+  shift_x: scalar,
+  shift_y: scalar,
+  matrix: z.array(z.tuple([scalar, scalar, scalar, scalar])).length(4),
+  passepartout: scalar.default(0),
+  display_size: scalar.default(1),
+});
+export type CameraData = z.infer<typeof cameraDataSchema>;
+
+/** `RV3D_CAMZOOM_MIN_FACTOR` .. `RV3D_CAMZOOM_MAX_FACTOR`, and `camzoom` 0's factor. */
+export const CAMERA_ZOOM = { opening: 0.5, min: 0.1657359312880714853, max: 44.9852813742385702928 } as const;
+
+/** Blender 5.2's default theme, read back from the installed Blender: the passepartout
+ *  (`camera_passepartout`), the solid edge (the 3D View's `back`), the dashed one
+ *  (`view_overlay`) and a locked view's outer box (`TH_REDALERT`, the error state). */
+const THEME = { passepartout: '#000000', back: '#3d3d3d', overlay: '#000000', redalert: '#991616' } as const;
+
+/** `view_move` in a camera view: the pan after the pointer moves `dx`, `dy` (fractions of the
+ *  region, down and right positive) at zoom factor `zoom`. */
+export function panCameraView(
+  offset: readonly [number, number],
+  zoom: number,
+  dx: number,
+  dy: number,
+): readonly [number, number] {
+  const clamp = (value: number) => Math.min(1, Math.max(-1, value));
+  return [clamp(offset[0] - dx / (2 * zoom)), clamp(offset[1] + dy / (2 * zoom))];
+}
+
+/** Half the window along each side, for a camera fitted to a `width` × `height` shape. */
+function halfExtents(camera: CameraData, width: number, height: number, zoom: number): [number, number] {
+  const orthographic = camera.type === 'ORTHO';
+  const sensor = camera.sensor_fit === 'VERTICAL' ? camera.sensor_height : camera.sensor_width;
+  const horizontal = camera.sensor_fit === 'AUTO' ? width >= height : camera.sensor_fit === 'HORIZONTAL';
+  const half = ((orthographic ? camera.ortho_scale : sensor / camera.lens) / 2) * zoom;
+  return horizontal ? [half, (half * height) / width] : [(half * width) / height, half];
+}
+
+export interface BlenderCameraView {
+  readonly name: string;
+  readonly position: readonly [number, number, number];
+  readonly quaternion: readonly [number, number, number, number];
+  readonly projection: 'perspective' | 'orthographic';
+  readonly window: { readonly left: number; readonly right: number; readonly top: number; readonly bottom: number };
+  readonly near: number;
+  readonly far: number;
+  readonly frame: { readonly left: number; readonly top: number; readonly width: number; readonly height: number };
+  readonly passepartout: { readonly color: string; readonly opacity: number };
+  readonly border: { readonly solid: string; readonly dashed: string; readonly locked: string };
+}
+
+/**
+ * `camera`'s view on a region, with `toStage` the Blender → stage matrix. `zoom` is the view's
+ * `fac`; `offset` its `[camdx, camdy]`; `renderAspect` the render's width over its height,
+ * pixel aspect included.
+ */
+export function blenderCameraView(
+  camera: CameraData,
+  toStage: THREE.Matrix4,
+  region: { readonly width: number; readonly height: number },
+  zoom: number,
+  offset: readonly [number, number],
+  renderAspect: number,
+): BlenderCameraView {
+  const width = Math.max(region.width, 1);
+  const height = Math.max(region.height, 1);
+  const [regionHalfWidth, regionHalfHeight] = halfExtents(camera, width, height, 1 / zoom);
+  const [frameHalfWidth, frameHalfHeight] = halfExtents(camera, renderAspect, 1, 1);
+  // The shift is a share of the frame's fitted side, on both axes (`dx = shiftx * viewfac`).
+  const fitted = camera.sensor_fit === 'AUTO' ? renderAspect >= 1 : camera.sensor_fit === 'HORIZONTAL';
+  const fittedSide = 2 * (fitted ? frameHalfWidth : frameHalfHeight);
+  const frameWidth = frameHalfWidth / regionHalfWidth;
+  const frameHeight = frameHalfHeight / regionHalfHeight;
+  // The frame's movement on the region, in fractions of it (down and right positive).
+  const shiftRight = -2 * offset[0] * zoom;
+  const shiftDown = 2 * offset[1] * zoom;
+  const centerX = camera.shift_x * fittedSide - shiftRight * 2 * regionHalfWidth;
+  const centerY = camera.shift_y * fittedSide + shiftDown * 2 * regionHalfHeight;
+  const matrix = new THREE.Matrix4()
+    .set(...(camera.matrix.flat() as Parameters<THREE.Matrix4['set']>))
+    .premultiply(toStage);
+  const position = new THREE.Vector3();
+  const quaternion = new THREE.Quaternion();
+  matrix.decompose(position, quaternion, new THREE.Vector3());
+  return {
+    name: camera.name,
+    position: position.toArray(),
+    quaternion: [quaternion.x, quaternion.y, quaternion.z, quaternion.w],
+    projection: camera.type === 'ORTHO' ? 'orthographic' : 'perspective',
+    window: {
+      left: centerX - regionHalfWidth,
+      right: centerX + regionHalfWidth,
+      top: centerY + regionHalfHeight,
+      bottom: centerY - regionHalfHeight,
+    },
+    near: camera.clip_start,
+    far: camera.clip_end,
+    frame: {
+      left: 0.5 - frameWidth / 2 + shiftRight,
+      top: 0.5 - frameHeight / 2 + shiftDown,
+      width: frameWidth,
+      height: frameHeight,
+    },
+    passepartout: { color: THEME.passepartout, opacity: camera.passepartout },
+    border: { solid: THEME.back, dashed: THEME.overlay, locked: THEME.redalert },
+  };
+}

package/browser/three/blender-runtime-cursor.ts

@@ -0,0 +1,243 @@
+/**
+ * THE 3D CURSOR — `Scene.cursor`, drawn the way Blender's overlay engine draws
+ * it (`draw/engines/overlay/overlay_cursor.hh`, shapes in `overlay_shape.cc`
+ * "cursor circle" / "cursor lines", read at the engine's pin).
+ *
+ * TWO SHAPES, both one `U.widget_unit` (20 CSS px) across whatever the zoom:
+ *
+ * - THE RING is screen space: a 12-segment circle of radius 0.5, segments
+ *   alternating red `(1, 0, 0)` and white, one pixel wide.
+ * - THE AXIS LINES are drawn IN 3D along the cursor's own rotation, scaled by
+ *   the pixel size at the cursor (`ED_view3d_pixel_size_no_ui_scale`): per
+ *   axis, black (`TH_VIEW_OVERLAY`) from 0.25 to 0.85 and the theme's axis
+ *   colour from 0.85 to 1; the negative half's colour is the axis blended a
+ *   quarter to white and shaded −60 (`get_color_blend_shade_3fv`).
+ *
+ * Here the ring faces the camera at the cursor's depth rather than being
+ * drawn in pixel space; at a 20 px size the two are the same picture.
+ *
+ * PLACEMENT is `view3d.cursor3d` as Shift+Right-click runs it
+ * (`space_view3d/view3d_edit.cc`): `use_depth` projects onto the surface under
+ * the pointer and, with nothing there, onto the view plane through the current
+ * cursor; `orientation` VIEW turns the cursor to the view (`rv3d->viewquat`
+ * with its w negated — the view's own rotation). Blender pushes no undo step
+ * for it (the operator's `OPTYPE_UNDO` is commented out), and neither does
+ * the caller.
+ */
+import * as THREE from 'three';
+import { z } from 'zod';
+
+const scalar = z.number().finite();
+/** `session.py`'s `frame["cursor"]`: `Scene.cursor.matrix`, row-major. */
+export const cursorSchema = z.array(z.tuple([scalar, scalar, scalar, scalar])).length(4);
+export type BlenderCursor = z.infer<typeof cursorSchema>;
+
+/** `U.widget_unit` at a UI scale of 1, in CSS px. */
+const WIDGET_UNIT = 20;
+
+/** The default theme's axis colours (`userdef_default_theme.c` `xaxis`/`yaxis`/`zaxis`). */
+const AXES = [0xff3352, 0x8bdc00, 0x2890ff] as const;
+
+function negativeShade(hex: number): THREE.Color {
+  const channel = (value: number) => Math.min(255, Math.max(0, Math.floor(0.75 * value + 0.25 * 255) - 60)) / 255;
+  return new THREE.Color().setRGB(channel((hex >> 16) & 255), channel((hex >> 8) & 255), channel(hex & 255), THREE.SRGBColorSpace);
+}
+
+function lineMaterial(): THREE.LineBasicMaterial {
+  return new THREE.LineBasicMaterial({ vertexColors: true, depthTest: false, depthWrite: false, transparent: true, toneMapped: false });
+}
+
+function axisLines(): THREE.LineSegments {
+  const positions: number[] = [];
+  const colors: number[] = [];
+  const black = new THREE.Color(0, 0, 0);
+  const push = (from: number, to: number, axis: number, sign: number, color: THREE.Color) => {
+    for (const at of [from, to]) {
+      const point = [0, 0, 0];
+      point[axis] = at * sign;
+      positions.push(...point);
+      colors.push(color.r, color.g, color.b);
+    }
+  };
+  for (let axis = 0; axis < 3; axis++) {
+    const positive = new THREE.Color().setHex(AXES[axis]!, THREE.SRGBColorSpace);
+    push(1, 0.85, axis, 1, positive);
+    push(0.85, 0.25, axis, 1, black);
+    push(1, 0.85, axis, -1, negativeShade(AXES[axis]!));
+    push(0.85, 0.25, axis, -1, black);
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));
+  return new THREE.LineSegments(geometry, lineMaterial());
+}
+
+function ring(): THREE.LineSegments {
+  const segments = 12;
+  const positions: number[] = [];
+  const colors: number[] = [];
+  const red = new THREE.Color(1, 0, 0);
+  const white = new THREE.Color(1, 1, 1);
+  for (let i = 0; i < segments; i++) {
+    // Blender's strip is flat-coloured with the segment's SECOND vertex as the provoking one
+    // (`gpu_shader_3D_polyline_vert.glsl`, `FLAT`: `geom_in[1]`), so segment i wears vertex i+1's.
+    const color = (i + 1) % 2 === 0 ? white : red;
+    for (const k of [i, i + 1]) {
+      const angle = (2 * Math.PI * k) / segments;
+      positions.push(0.5 * Math.cos(angle), 0.5 * Math.sin(angle), 0);
+      colors.push(color.r, color.g, color.b);
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));
+  return new THREE.LineSegments(geometry, lineMaterial());
+}
+
+/** The cursor placed by a click, in Blender's own frame. */
+export interface CursorPlacement {
+  readonly location: readonly [number, number, number];
+  /** `(w, x, y, z)`. */
+  readonly rotation: readonly [number, number, number, number];
+}
+
+export class CursorOverlay {
+  /** Carries the Blender → document permutation from its parent; see the view.
+   *  Its `visible` is the view's (a render stands it down); whether there is a
+   *  cursor to draw is the shapes' own. */
+  readonly group = new THREE.Group();
+  private readonly anchor = new THREE.Group();
+  private readonly lines = axisLines();
+  private readonly circle = ring();
+  /** What the cursor was last drawn with: placement reads the view the person sees. */
+  private seen: { camera: THREE.Camera; canvas: HTMLCanvasElement } | null = null;
+  private readonly size = new THREE.Vector2();
+  private readonly scratch = new THREE.Vector3();
+  private readonly parentQuat = new THREE.Quaternion();
+
+  constructor() {
+    this.group.name = 'BlenderCursor';
+    this.present(false);
+    this.anchor.matrixAutoUpdate = false;
+    this.group.add(this.anchor, this.circle);
+    this.anchor.add(this.lines);
+    for (const shape of [this.lines, this.circle]) {
+      shape.renderOrder = 1001;
+      shape.frustumCulled = false;
+    }
+    this.lines.onBeforeRender = (renderer, _scene, camera) => this.fit(renderer, camera);
+    this.circle.onBeforeRender = (renderer, _scene, camera) => this.fit(renderer, camera);
+  }
+
+  /** Show the frame's cursor; an engine that sends none draws none. */
+  apply(cursor: BlenderCursor | undefined): void {
+    if (cursor === undefined) {
+      this.present(false);
+      return;
+    }
+    this.anchor.matrix.set(...(cursor.flat() as Parameters<THREE.Matrix4['set']>));
+    this.anchor.updateMatrixWorld(true);
+    this.present(true);
+  }
+
+  private present(shown: boolean): void {
+    this.anchor.visible = shown;
+    this.circle.visible = shown;
+  }
+
+  /** Move the drawn cursor ahead of the engine's frame, which then confirms it. */
+  show(placement: CursorPlacement): void {
+    const [w, x, y, z] = placement.rotation;
+    this.anchor.matrix.compose(
+      new THREE.Vector3(...placement.location),
+      new THREE.Quaternion(x, y, z, w),
+      new THREE.Vector3(1, 1, 1),
+    );
+    this.anchor.updateMatrixWorld(true);
+    this.present(true);
+  }
+
+  /** One widget unit at the cursor's depth, for the camera drawing it now. */
+  private fit(renderer: THREE.WebGLRenderer, camera: THREE.Camera): void {
+    this.seen = { camera, canvas: renderer.domElement };
+    renderer.getSize(this.size);
+    const height = Math.max(this.size.y, 1);
+    const at = this.scratch.setFromMatrixPosition(this.anchor.matrixWorld);
+    let perPixel: number;
+    if ((camera as THREE.OrthographicCamera).isOrthographicCamera) {
+      const ortho = camera as THREE.OrthographicCamera;
+      perPixel = (ortho.top - ortho.bottom) / ortho.zoom / height;
+    } else {
+      const perspective = camera as THREE.PerspectiveCamera;
+      const depth = Math.max(-at.applyMatrix4(camera.matrixWorldInverse).z, 1e-6);
+      perPixel = (2 * depth * Math.tan(THREE.MathUtils.degToRad(perspective.fov) / 2)) / perspective.zoom / height;
+    }
+    const scale = perPixel * WIDGET_UNIT;
+    this.lines.scale.setScalar(scale);
+    this.lines.updateMatrixWorld(true);
+    // The ring faces the camera: its world rotation is the camera's.
+    this.circle.position.setFromMatrixPosition(this.anchor.matrix);
+    this.group.getWorldQuaternion(this.parentQuat).invert();
+    camera.getWorldQuaternion(this.circle.quaternion).premultiply(this.parentQuat);
+    this.circle.scale.setScalar(scale);
+    this.circle.updateMatrixWorld(true);
+  }
+
+  /**
+   * Where Shift+Right-click at `clientX/clientY` puts the cursor, or null when
+   * the point is not on the view the cursor was last drawn in. `model` is the
+   * presented model root, whose local frame is Blender's; `isSurface` says which of its meshes
+   * are the scene's own geometry, the only thing Blender's depth pick sees.
+   */
+  placementAt(
+    clientX: number,
+    clientY: number,
+    target: EventTarget | null,
+    model: THREE.Object3D,
+    isSurface: (object: THREE.Object3D) => boolean,
+  ): CursorPlacement | null {
+    const seen = this.seen;
+    if (seen === null || target !== seen.canvas) return null;
+    const rect = seen.canvas.getBoundingClientRect();
+    const pointer = new THREE.Vector2(
+      ((clientX - rect.left) / Math.max(rect.width, 1)) * 2 - 1,
+      -((clientY - rect.top) / Math.max(rect.height, 1)) * 2 + 1,
+    );
+    const raycaster = new THREE.Raycaster();
+    raycaster.setFromCamera(pointer, seen.camera);
+    const shown = (object: THREE.Object3D | null): boolean => {
+      for (let at = object; at !== null; at = at.parent) if (!at.visible) return false;
+      return true;
+    };
+    const hit = raycaster
+      .intersectObject(model, true)
+      .find((one) => (one.object as THREE.Mesh).isMesh && isSurface(one.object) && shown(one.object));
+    let world: THREE.Vector3 | null = hit ? hit.point.clone() : null;
+    if (world === null) {
+      // No surface: the view plane through the current cursor. A cursor behind the view gives
+      // its depth in front instead, as `ED_view3d_win_to_3d` flips a negative `zfac`.
+      const through = new THREE.Vector3().setFromMatrixPosition(this.anchor.matrixWorld);
+      const normal = seen.camera.getWorldDirection(new THREE.Vector3());
+      const eye = seen.camera.getWorldPosition(new THREE.Vector3());
+      const depth = through.clone().sub(eye).dot(normal);
+      if (depth <= 0) through.addScaledVector(normal, -2 * depth + (depth === 0 ? 1 : 0));
+      world = raycaster.ray.intersectPlane(new THREE.Plane().setFromNormalAndCoplanarPoint(normal, through), new THREE.Vector3());
+    }
+    if (world === null) return null;
+    model.updateWorldMatrix(true, false);
+    const local = model.worldToLocal(world);
+    const rotation = model
+      .getWorldQuaternion(new THREE.Quaternion())
+      .invert()
+      .multiply(seen.camera.getWorldQuaternion(new THREE.Quaternion()));
+    return { location: [local.x, local.y, local.z], rotation: [rotation.w, rotation.x, rotation.y, rotation.z] };
+  }
+
+  dispose(): void {
+    for (const shape of [this.lines, this.circle]) {
+      shape.geometry.dispose();
+      (shape.material as THREE.Material).dispose();
+    }
+    this.seen = null;
+  }
+}