abstract-3d 3.1.2 → 4.0.0-beta.0

package/src/renderers/three/build/parts.ts

@@ -0,0 +1,277 @@
+import {
+  BatchedMesh,
+  type BufferGeometry,
+  FrontSide,
+  InstancedBufferAttribute,
+  InstancedMesh,
+  type InterleavedBuffer,
+  type InterleavedBufferAttribute,
+  type Intersection,
+  type Material,
+  Matrix4,
+  Mesh,
+  type MeshBasicMaterial,
+  PlaneGeometry,
+  ShaderMaterial,
+  Vector3,
+  type Vector4,
+} from "three";
+import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
+import type { Vec3 } from "../../../abstract-3d.js";
+import type { GlyphAtlas } from "../text/text.js";
+import { layoutText, SDF_EDGE } from "../text/text.js";
+
+/** The drawn objects: solids of a material class in one batch, all text in one instanced mesh, lines per thickness, images as meshes; each item a slot */
+
+export type Segment = {
+  readonly start: Vec3;
+  readonly end: Vec3;
+  /** The front facing direction of a culled line, hidden while it faces away from the camera */
+  readonly normal?: Vec3;
+};
+
+export type TextEntry = { readonly text: string; readonly fontSize: number; readonly local: Matrix4 };
+
+export type Part =
+  | { readonly kind: "solid"; readonly object: BatchedMesh; readonly locals: ReadonlyArray<Matrix4> }
+  | {
+      readonly kind: "text";
+      readonly object: InstancedMesh;
+      readonly locals: ReadonlyArray<Matrix4>;
+      readonly glyphs: ReadonlyArray<Matrix4>;
+      /** The first glyph of each slot, and one past the last */
+      readonly firsts: ReadonlyArray<number>;
+      readonly slotOfGlyph: Int32Array;
+      readonly colors: InstancedBufferAttribute;
+    }
+  | {
+      readonly kind: "line";
+      readonly object: LineSegments2;
+      readonly segments: ReadonlyArray<Segment>;
+      /** World start, end and normal of each segment, while the drawn positions collapse hidden ones */
+      readonly world: Float32Array;
+      readonly visible: Uint8Array;
+      readonly positions: InterleavedBuffer;
+      readonly colors: InterleavedBuffer;
+    }
+  | { readonly kind: "image"; readonly object: Mesh<BufferGeometry, MeshBasicMaterial>; readonly local: Matrix4 };
+
+/** Per-instance color for hover and selection, as three.js's BatchedMesh examples color instances */
+export function createSolidPart(entries: ReadonlyArray<{ readonly geometry: BufferGeometry; readonly local: Matrix4 }>, material: Material): Part {
+  const geometries = [...new Set(entries.map((e) => e.geometry))];
+  const vertexCount = geometries.reduce((sum, g) => sum + g.getAttribute("position").count, 0);
+  const batch = new BatchedMesh(
+    entries.length,
+    vertexCount,
+    geometries.reduce((sum, g) => sum + g.index!.count, 0),
+    material
+  );
+  const ids = new Map(geometries.map((g) => [g, batch.addGeometry(g)]));
+  entries.forEach((e) => batch.addInstance(ids.get(e.geometry)!));
+  return { kind: "solid", object: batch, locals: entries.map((e) => e.local) };
+}
+
+export function createTextPart(entries: ReadonlyArray<TextEntry>, atlas: GlyphAtlas): Part {
+  const layouts = entries.map((e) => layoutText(atlas, e.text, e.fontSize));
+  const quads = layouts.flat();
+  const geometry = new PlaneGeometry();
+  geometry.setAttribute("glyphRect", new InstancedBufferAttribute(Float32Array.from(quads.flatMap((q) => q.glyph.rect)), 4));
+  const colors = new InstancedBufferAttribute(new Float32Array(quads.length * 4), 4);
+  geometry.setAttribute("glyphColor", colors);
+  // Glyphs colored per instance, one draw call as troika's BatchedText; edges antialiased by the distance field's fwidth, as troika does
+  const material = new ShaderMaterial({
+    side: FrontSide,
+    transparent: true,
+    depthWrite: false,
+    uniforms: { atlas: { value: atlas.texture } },
+    defines: { SDF_EDGE },
+    vertexShader: textVertexShader,
+    fragmentShader: textFragmentShader,
+  });
+  const mesh = new InstancedMesh(geometry, material, quads.length);
+  // Drawn after the opaque batches, and never culled as a whole, as its glyphs move with their items
+  Object.assign(mesh, { renderOrder: 1, frustumCulled: false });
+  return {
+    kind: "text",
+    object: mesh,
+    locals: entries.map((e) => e.local),
+    glyphs: quads.map((q) => new Matrix4().makeTranslation(q.x, q.y, 0).scale(new Vector3(q.width, q.height, 1))),
+    firsts: layouts.reduce<ReadonlyArray<number>>((acc, l, i) => [...acc, acc[i]! + l.length], [0]),
+    slotOfGlyph: Int32Array.from(layouts.flatMap((l, slot) => l.map(() => slot))),
+    colors,
+  };
+}
+
+export function createLinePart(segments: ReadonlyArray<Segment>, thickness: number): Part {
+  const geometry = new LineSegmentsGeometry().setPositions(new Float32Array(segments.length * 6)).setColors(new Float32Array(segments.length * 6));
+  const line = new LineSegments2(geometry, new LineMaterial({ linewidth: thickness, vertexColors: true }));
+  // Positions change after the geometry's bounds were computed
+  line.frustumCulled = false;
+  return {
+    kind: "line",
+    object: line,
+    segments,
+    world: new Float32Array(segments.length * 9),
+    visible: new Uint8Array(segments.length).fill(1),
+    positions: (geometry.getAttribute("instanceStart") as InterleavedBufferAttribute).data,
+    colors: (geometry.getAttribute("instanceColorStart") as InterleavedBufferAttribute).data,
+  };
+}
+
+/** Hidden until its texture is set */
+export function createImagePart(geometry: BufferGeometry, local: Matrix4, material: MeshBasicMaterial): Extract<Part, { readonly kind: "image" }> {
+  const mesh = new Mesh(geometry, material);
+  Object.assign(mesh, { matrixAutoUpdate: false, visible: false });
+  return { kind: "image", object: mesh, local };
+}
+
+/** Places the slot's item by its world matrix */
+export function placeSlot(part: Part, slot: number, matrix: Matrix4): void {
+  switch (part.kind) {
+    case "solid":
+      part.object.setMatrixAt(slot, scratch.multiplyMatrices(matrix, part.locals[slot]!));
+      break;
+    case "text": {
+      const text = scratch.multiplyMatrices(matrix, part.locals[slot]!);
+      for (let i = part.firsts[slot]!; i < part.firsts[slot + 1]!; i++) {
+        part.object.setMatrixAt(i, glyph.multiplyMatrices(text, part.glyphs[i]!));
+      }
+      break;
+    }
+    case "line": {
+      const { start, end, normal } = part.segments[slot]!;
+      part.world.set(vector.set(start.x, start.y, start.z).applyMatrix4(matrix).toArray(), slot * 9);
+      part.world.set(vector.set(end.x, end.y, end.z).applyMatrix4(matrix).toArray(), slot * 9 + 3);
+      part.world.set(normal ? vector.set(normal.x, normal.y, normal.z).transformDirection(matrix).toArray() : [0, 0, 0], slot * 9 + 6);
+      writeSegment(part, slot);
+      break;
+    }
+    default:
+      part.object.matrix.multiplyMatrices(matrix, part.local);
+      part.object.matrixWorldNeedsUpdate = true;
+  }
+}
+
+export function paintSlot(part: Part, slot: number, rgba: Vector4): void {
+  switch (part.kind) {
+    case "solid":
+      part.object.setColorAt(slot, rgba);
+      break;
+    case "text":
+      for (let i = part.firsts[slot]!; i < part.firsts[slot + 1]!; i++) {
+        part.colors.setXYZW(i, rgba.x, rgba.y, rgba.z, rgba.w);
+      }
+      break;
+    case "line":
+      part.colors.array.set([rgba.x, rgba.y, rgba.z, rgba.x, rgba.y, rgba.z], slot * 6);
+      break;
+    default:
+      part.object.material.color.setRGB(rgba.x, rgba.y, rgba.z);
+      part.object.material.opacity = rgba.w;
+  }
+}
+
+/** Uploads what placing and painting changed, and the bounds for culling and picking when slots moved */
+export function flushPart(part: Part, moved: boolean): void {
+  switch (part.kind) {
+    case "solid":
+      if (moved) {
+        part.object.computeBoundingBox();
+        part.object.computeBoundingSphere();
+      }
+      break;
+    case "text":
+      part.object.instanceMatrix.needsUpdate = true;
+      part.colors.needsUpdate = true;
+      part.object.boundingSphere = null;
+      break;
+    case "line":
+      part.positions.needsUpdate = true;
+      part.colors.needsUpdate = true;
+      break;
+    default:
+  }
+}
+
+/** The slot of a hit on the part's object; lines aren't picked */
+export function getHitSlot(part: Part, hit: Intersection): number | undefined {
+  switch (part.kind) {
+    case "solid":
+      return hit.batchId;
+    case "text":
+      return hit.instanceId === undefined ? undefined : part.slotOfGlyph[hit.instanceId];
+    case "line":
+      return undefined;
+    default:
+      return 0;
+  }
+}
+
+/** Hides the culled lines facing away from a camera at `cameraPosition`; the r3f renderer's culled line shader's test, on the CPU per camera move */
+export function cullLines(part: Part, cameraPosition: Vector3): void {
+  if (part.kind !== "line") {
+    return;
+  }
+  part.segments.forEach((segment, slot) => {
+    const w = slot * 9;
+    const mid = vector
+      .fromArray(part.world, w)
+      .add(normal.fromArray(part.world, w + 3))
+      .multiplyScalar(0.5);
+    const facing = !segment.normal || normal.fromArray(part.world, w + 6).dot(mid.subVectors(cameraPosition, mid)) > 0 ? 1 : 0;
+    if (facing !== part.visible[slot]) {
+      part.visible[slot] = facing;
+      writeSegment(part, slot);
+      part.positions.needsUpdate = true;
+    }
+  });
+}
+
+export function disposePart(part: Part): void {
+  if (part.kind === "solid") {
+    part.object.dispose();
+  } else if (part.kind !== "image") {
+    part.object.geometry.dispose();
+  }
+  const materials = part.object.material;
+  (Array.isArray(materials) ? materials : [materials]).forEach((m: Material) => m.dispose());
+}
+
+/** A hidden segment collapses to its start */
+function writeSegment(part: Extract<Part, { readonly kind: "line" }>, slot: number): void {
+  const w = slot * 9;
+  part.positions.array.set(
+    part.visible[slot] ? part.world.subarray(w, w + 6) : [...part.world.subarray(w, w + 3), ...part.world.subarray(w, w + 3)],
+    slot * 6
+  );
+}
+
+const textVertexShader = /* glsl */ `
+attribute vec4 glyphRect;
+attribute vec4 glyphColor;
+varying vec2 vUv;
+varying vec4 vColor;
+void main() {
+  vUv = glyphRect.xy + uv * glyphRect.zw;
+  vColor = glyphColor;
+  gl_Position = projectionMatrix * modelViewMatrix * instanceMatrix * vec4(position, 1.0);
+}`;
+
+const textFragmentShader = /* glsl */ `
+uniform sampler2D atlas;
+varying vec2 vUv;
+varying vec4 vColor;
+void main() {
+  float distance = texture2D(atlas, vUv).r;
+  float edge = fwidth(distance) * 0.7;
+  gl_FragColor = vec4(vColor.rgb, vColor.a * smoothstep(SDF_EDGE - edge, SDF_EDGE + edge, distance));
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+
+const scratch = new Matrix4();
+const glyph = new Matrix4();
+const vector = new Vector3();
+const normal = new Vector3();

package/src/renderers/three/camera/camera.test.ts

@@ -0,0 +1,53 @@
+import { OrthographicCamera, PerspectiveCamera } from "three";
+import { describe, expect, it } from "vitest";
+import { vec3 } from "../../../abstract-3d.js";
+import type { FitInput } from "./camera.js";
+import { fitCamera } from "./camera.js";
+
+const input: FitInput = { view: "front", size: vec3(4000, 2000, 1000), canvas: { width: 800, height: 400 }, bufferZones: {}, fitPadding: 0 };
+const tan = Math.tan((45 * Math.PI) / 360);
+const fitPerspective = (partial: Partial<FitInput> = {}): readonly [PerspectiveCamera, ReturnType<typeof fitCamera>] => {
+  const camera = new PerspectiveCamera(45);
+  return [camera, fitCamera(camera, { ...input, ...partial })];
+};
+const fitOrthographic = (partial: Partial<FitInput> = {}): ReadonlyArray<number> => {
+  const camera = new OrthographicCamera();
+  fitCamera(camera, { ...input, ...partial });
+  return [camera.left, camera.right, camera.top, camera.bottom, camera.zoom];
+};
+
+describe("fitCamera", () => {
+  it("fits nothing into an empty canvas", () => {
+    expect(fitPerspective({ canvas: { width: 0, height: 400 } })[1]).toBeUndefined();
+  });
+
+  it("backs a perspective camera off until the scene's width and height fit, plus half its depth", () => {
+    const [camera, placement] = fitPerspective();
+    expect(placement!.distance).toBeCloseTo(Math.max(1000 / tan, 2000 / (tan * 2)) + 500);
+    expect(placement!.direction).toEqual(vec3(0, 0, 1));
+    expect(camera.aspect).toBe(2);
+  });
+
+  it("pads the distance", () => {
+    expect(fitPerspective({ fitPadding: 0.1 })[1]!.distance).toBeCloseTo(fitPerspective()[1]!.distance * 1.1);
+  });
+
+  it("fits into the area inside the buffer zones, and offsets the view to it", () => {
+    const [camera] = fitPerspective({ bufferZones: { left: 200, top: 100 } });
+    expect(camera.aspect).toBeCloseTo(600 / 300);
+    expect(camera.view).toMatchObject({ enabled: true, fullWidth: 600, fullHeight: 300, offsetX: -200, offsetY: -100, width: 800, height: 400 });
+  });
+
+  it("looks along each view, with the scene's size seen from it", () => {
+    expect(fitPerspective({ view: "top" })[1]!.direction).toEqual(vec3(0, 1, 0));
+    expect(fitPerspective({ view: "left" })[1]!.direction).toEqual(vec3(-1, 0, 0));
+    // From the top, the scene is 4000 wide and 1000 high on screen, and 2000 deep
+    expect(fitPerspective({ view: "top" })[1]!.distance).toBeCloseTo(Math.max(500 / tan, 2000 / (tan * 2)) + 1000);
+  });
+
+  it("frames orthographic cameras around the scene, extended by the buffer zones", () => {
+    expect(fitOrthographic()).toEqual([-2000, 2000, 1000, -1000, 1]);
+    // The usable area is 400 x 400, so the scene's 4000 width sets 10 world units per pixel
+    expect(fitOrthographic({ bufferZones: { right: 400 } })).toEqual([-2000, 6000, 2000, -2000, 1]);
+  });
+});

package/src/renderers/three/camera/camera.ts

@@ -0,0 +1,82 @@
+import type { OrthographicCamera, PerspectiveCamera } from "three";
+import { exhaustiveCheck } from "ts-exhaustive-check";
+import type { Vec3, View } from "../../../abstract-3d.js";
+import { vec3 } from "../../../abstract-3d.js";
+
+/** Fitting the camera to the scene, inside buffer zones of the canvas that UI covers; the fit math of the r3f renderer's react-camera.tsx */
+
+export type CameraOptions =
+  | { readonly type: "Perspective"; readonly near?: number; readonly far?: number; readonly fov?: number }
+  | { readonly type: "Orthographic"; readonly near?: number; readonly far?: number };
+
+/** Margins of the canvas, in CSS pixels, that the scene is fitted inside of */
+export type BufferZones = { readonly left?: number; readonly right?: number; readonly top?: number; readonly bottom?: number };
+
+export type FitInput = {
+  readonly view: View;
+  /** The scene's size */
+  readonly size: Vec3;
+  /** In CSS pixels */
+  readonly canvas: { readonly width: number; readonly height: number };
+  readonly bufferZones: BufferZones;
+  readonly fitPadding: number;
+};
+
+/** Where to place the camera: its distance from the target, and the direction from the target to it */
+export type Placement = { readonly distance: number; readonly direction: Vec3 };
+
+/** Sets the camera's projection to fit the scene into the usable area of the canvas, and returns where to place it */
+export function fitCamera(
+  camera: PerspectiveCamera | OrthographicCamera,
+  { view, size: sceneSize, canvas, bufferZones, fitPadding }: FitInput
+): Placement | undefined {
+  if (canvas.width === 0 || canvas.height === 0) {
+    return undefined;
+  }
+  const [direction, size, sceneAspect] = getViewTransform(view, sceneSize);
+  const { left = 0, right = 0, top = 0, bottom = 0 } = bufferZones;
+  const usableW = Math.max(1, canvas.width - left - right);
+  const usableH = Math.max(1, canvas.height - top - bottom);
+  const usableAspect = usableW / usableH;
+  camera.zoom = 1;
+
+  if ("isOrthographicCamera" in camera) {
+    const pad = 1 + fitPadding;
+    // Constrained by the scene's width when it's wider than the usable area, else by its height
+    const [halfW, halfH] =
+      sceneAspect > usableAspect
+        ? [(size.x / 2) * pad, (size.x / 2 / usableAspect) * pad]
+        : [((usableAspect * size.y) / 2) * pad, (size.y / 2) * pad];
+    // Extended by the buffer zones, at the world units per CSS pixel of the usable area
+    const [wpp, hpp] = [(halfW * 2) / usableW, (halfH * 2) / usableH];
+    Object.assign(camera, { left: -halfW - left * wpp, right: halfW + right * wpp, top: halfH + top * hpp, bottom: -halfH - bottom * hpp });
+    camera.updateProjectionMatrix();
+    const fovTan = Math.tan((45 * Math.PI) / 360);
+    return { distance: size.z * 0.5 + Math.max(size.x, size.y) * 2 * fovTan, direction };
+  }
+
+  // The field of view describes the usable area; the view offset extends the rendered frustum from it to the full canvas
+  const tan = Math.tan((camera.fov * Math.PI) / 360);
+  const distance = Math.max(size.y / 2 / tan, size.x / 2 / (tan * usableAspect)) + size.z * 0.5;
+  camera.aspect = usableAspect;
+  camera.setViewOffset(usableW, usableH, -left, -top, canvas.width, canvas.height);
+  camera.updateProjectionMatrix();
+  return { distance: distance * (1 + fitPadding), direction };
+}
+
+/** The direction to look from, the scene's size as seen on screen and its aspect */
+function getViewTransform(view: View, size: Vec3): readonly [Vec3, Vec3, number] {
+  switch (view) {
+    case "front":
+    case "back":
+      return [vec3(0, 0, view === "front" ? 1 : -1), size, size.x / size.y];
+    case "top":
+    case "bottom":
+      return [vec3(0, view === "top" ? 1 : -1, 0), vec3(size.x, size.z, size.y), size.x / size.z];
+    case "right":
+    case "left":
+      return [vec3(view === "right" ? 1 : -1, 0, 0), vec3(size.z, size.y, size.x), size.z / size.y];
+    default:
+      return exhaustiveCheck(view);
+  }
+}

package/src/renderers/three/camera/controls.ts

@@ -0,0 +1,65 @@
+import type { OrthographicCamera, PerspectiveCamera, Vector3 } from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+
+/** The r3f renderer's OrbitControls, with drei's damping default */
+
+export type ControlsOptions = Partial<Omit<OrbitControls, "object" | "domElement" | "target" | "cursor">> & {
+  readonly onStart?: () => void;
+  readonly onChange?: () => void;
+  readonly onEnd?: () => void;
+};
+
+export type Controls = {
+  readonly orbit: OrbitControls;
+  readonly current: { options: ControlsOptions };
+  /** The user drags the camera, and it moved since the drag started */
+  readonly drag: { active: boolean; moved: boolean };
+};
+
+export function createControls(
+  camera: PerspectiveCamera | OrthographicCamera,
+  element: HTMLElement,
+  options: ControlsOptions,
+  onInput: () => void
+): Controls {
+  const controls: Controls = { orbit: new OrbitControls(camera, element), current: { options }, drag: { active: false, moved: false } };
+  configureControls(controls, options);
+  controls.orbit.addEventListener("start", () => onDragStart(controls, onInput));
+  controls.orbit.addEventListener("change", () => onDragChange(controls, onInput));
+  controls.orbit.addEventListener("end", () => onDragEnd(controls));
+  return controls;
+}
+
+/** Sets the options that are defined, so ones left out keep their defaults */
+export function configureControls(controls: Controls, options: ControlsOptions): void {
+  controls.current.options = options;
+  controls.orbit.enableDamping = true;
+  Object.entries(options as Record<string, unknown>).forEach(([key, value]) => {
+    if (value !== undefined && typeof value !== "function") {
+      Object.assign(controls.orbit, { [key]: value });
+    }
+  });
+}
+
+export function setPose(controls: Controls, position: Vector3, target: Vector3): void {
+  controls.orbit.target.copy(target);
+  controls.orbit.object.position.copy(position);
+  controls.orbit.update();
+}
+
+function onDragStart(controls: Controls, onInput: () => void): void {
+  Object.assign(controls.drag, { active: true, moved: false });
+  controls.current.options.onStart?.();
+  onInput();
+}
+
+function onDragChange(controls: Controls, onInput: () => void): void {
+  controls.drag.moved = controls.drag.active;
+  controls.current.options.onChange?.();
+  onInput();
+}
+
+function onDragEnd(controls: Controls): void {
+  Object.assign(controls.drag, { active: false, moved: false });
+  controls.current.options.onEnd?.();
+}

package/src/renderers/three/camera/gizmo.ts

@@ -0,0 +1,93 @@
+import type { OrthographicCamera, PerspectiveCamera, WebGLRenderer } from "three";
+import type { GizmoAxisOptions, GizmoOptions } from "three-viewport-gizmo";
+import { ViewportGizmo } from "three-viewport-gizmo";
+
+/**
+ * A viewcube or axes in a corner of the canvas that turns with the camera; clicking it turns the camera to look from that side. three-viewport-gizmo,
+ * with the options of drei's GizmoViewcube and GizmoViewport that the r3f renderer took
+ */
+
+export type GizmoAlignment = `${"top" | "center" | "bottom"}-${"left" | "center" | "right"}`;
+
+export type ViewcubeOptions = {
+  /** A CSS font; its weight and family are used */
+  readonly font?: string;
+  readonly opacity?: number;
+  readonly color?: string;
+  readonly hoverColor?: string;
+  readonly textColor?: string;
+  readonly strokeColor?: string;
+  /** Labels of the +x, -x, +y, -y, +z and -z faces */
+  readonly faces?: ReadonlyArray<string>;
+  /** Clicking also moves the target back to the scene's center and fits the scene */
+  readonly resetZoomAndPanOnClick?: boolean;
+};
+
+export type AxesOptions = {
+  readonly axisColors?: readonly [string, string, string];
+  readonly labels?: readonly [string, string, string];
+  readonly labelColor?: string;
+  readonly hideNegativeAxes?: boolean;
+  readonly disabled?: boolean;
+  readonly font?: string;
+  readonly resetZoomAndPanOnClick?: boolean;
+};
+
+export type ControlsHelper = (
+  | { readonly type: "Viewcube"; readonly viewcubeProps?: ViewcubeOptions }
+  | { readonly type: "Viewport"; readonly viewportProps?: AxesOptions }
+) & {
+  /** The margin is from the canvas' corner to the gizmo's center, in CSS pixels */
+  readonly props?: { readonly alignment?: GizmoAlignment; readonly margin?: readonly [number, number] };
+};
+
+const size = 110;
+const axes = ["x", "nx", "y", "ny", "z", "nz"] as const;
+
+export function createGizmo(
+  camera: PerspectiveCamera | OrthographicCamera,
+  renderer: WebGLRenderer,
+  container: HTMLElement,
+  helper: ControlsHelper
+): ViewportGizmo {
+  const [mx, my] = helper.props?.margin ?? [80, 80];
+  const options = helper.type === "Viewcube" ? helper.viewcubeProps : helper.viewportProps;
+  // "600 24px Helvetica, Arial" is weight 600 of Helvetica, Arial
+  const [, weight = 600, family = "Helvetica, Arial, sans-serif"] = /^(?:(\S+)\s+)?[\d.]+px\s+(.+)$/.exec(options?.font ?? "") ?? [];
+  const gizmo = new ViewportGizmo(camera, renderer, {
+    container,
+    size,
+    placement: helper.props?.alignment ?? "bottom-right",
+    offset: { left: mx - size / 2, right: mx - size / 2, top: my - size / 2, bottom: my - size / 2 },
+    font: { family, weight },
+    ...(helper.type === "Viewcube" ? getViewcubeOptions(helper.viewcubeProps ?? {}) : getAxesOptions(helper.viewportProps ?? {})),
+  });
+  gizmo.enabled = !(helper.type === "Viewport" && helper.viewportProps?.disabled);
+  return gizmo;
+}
+
+function getViewcubeOptions(options: ViewcubeOptions): GizmoOptions {
+  const { opacity = 1, color = "#f4f5f7", hoverColor = "#cfe0ff", textColor = "#333", strokeColor = "#9aa0a6" } = options;
+  const labels = options.faces ?? ["Right", "Left", "Top", "Bottom", "Front", "Back"];
+  const face: GizmoAxisOptions = { color, opacity, labelColor: textColor, hover: { color: hoverColor, labelColor: textColor, opacity } };
+  return {
+    type: "cube",
+    background: { color: strokeColor, opacity, hover: { color: strokeColor, opacity } },
+    corners: { color, hover: { color: hoverColor } },
+    edges: { color, hover: { color: hoverColor } },
+    ...Object.fromEntries(axes.map((axis, i) => [axis, { ...face, label: (labels[i] ?? "").toUpperCase() }])),
+  };
+}
+
+function getAxesOptions(options: AxesOptions): GizmoOptions {
+  const { axisColors = ["#ff3653", "#8adb00", "#2c8fff"], labels = ["X", "Y", "Z"], labelColor = "#000" } = options;
+  return {
+    type: "sphere",
+    ...Object.fromEntries(
+      axes.map((axis, i) => [
+        axis,
+        { color: axisColors[Math.floor(i / 2)], labelColor, ...(i % 2 ? { enabled: !options.hideNegativeAxes } : { label: labels[i / 2] }) },
+      ])
+    ),
+  };
+}