model-preview 0.1.0

package/src/viewport/CustomControls.ts

@@ -0,0 +1,268 @@
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { MOUSE, Quaternion, Vector3, type Camera } from 'three';
+
+const _STATE_ROTATE = 0;
+const _CHANGE_EVENT = { type: 'change' } as const;
+
+const _offset = new Vector3();
+const _yAxis = new Vector3();
+const _xAxis = new Vector3();
+const _viewOffset = new Vector3();
+const _lookDirection = new Vector3();
+const _qStep = new Quaternion();
+
+const _yAxisUp = new Vector3(0, 1, 0);
+const _DAMPING_EPS = 0.00001;
+
+type OrbitControlsInternals = OrbitControls & {
+  _quat: Quaternion;
+  _quatInverse: Quaternion;
+  _spherical: { theta: number; phi: number; setFromVector3(v: Vector3): void };
+  _sphericalDelta: { theta: number; phi: number; set(x: number, y: number, z: number): void };
+  _panOffset: Vector3;
+  _scale: number;
+  state: number;
+};
+
+function internals(controls: CustomControls): OrbitControlsInternals {
+  return controls as unknown as OrbitControlsInternals;
+}
+
+/**
+ * Blender-style orbit controls used by UEditor and model preview viewports.
+ */
+export class CustomControls extends OrbitControls {
+  getOrbitPivot: () => Vector3 | null;
+
+  private _orbitPivotMode = false;
+  private _orbitPivotPendingEnd = false;
+  private _orbitPivot = new Vector3();
+
+  constructor(
+    object: Camera,
+    domElement: HTMLElement,
+    options: { getOrbitPivot?: () => Vector3 | null } = {},
+  ) {
+    super(object, domElement);
+
+    this.getOrbitPivot = options.getOrbitPivot ?? (() => null);
+
+    this.addEventListener('start', this._onControlStart.bind(this));
+    this.addEventListener('end', this._onControlEnd.bind(this));
+  }
+
+  getViewCenter() {
+    return this.target;
+  }
+
+  syncFromCamera() {
+    this._syncOrbitStateFromCamera();
+  }
+
+  syncOrbitState() {
+    const ctrl = internals(this);
+    _offset.copy(this.object.position).sub(this.target);
+    _offset.applyQuaternion(ctrl._quat);
+    ctrl._spherical.setFromVector3(_offset);
+    ctrl._sphericalDelta.set(0, 0, 0);
+    ctrl._panOffset.set(0, 0, 0);
+    ctrl._scale = 1;
+  }
+
+  updateOrbitUpBasis() {
+    const ctrl = internals(this);
+    ctrl._quat.setFromUnitVectors(this.object.up, _yAxisUp);
+    ctrl._quatInverse.copy(ctrl._quat).invert();
+  }
+
+  applyViewSnap(qDelta: Quaternion, pivot: Vector3) {
+    this.object.position.sub(pivot).applyQuaternion(qDelta).add(pivot);
+    this.target.sub(pivot).applyQuaternion(qDelta).add(pivot);
+    this.object.quaternion.premultiply(qDelta);
+  }
+
+  beginOrbitAroundPivot(pivot: Vector3) {
+    this._orbitPivotMode = true;
+    this._orbitPivotPendingEnd = false;
+    this._orbitPivot.copy(pivot);
+    internals(this)._sphericalDelta.set(0, 0, 0);
+  }
+
+  private _rotateAroundPivot(axis: Vector3, angle: number, pivot = this._orbitPivot) {
+    if (angle === 0) return;
+
+    _qStep.setFromAxisAngle(axis, angle);
+
+    this.object.position.sub(pivot);
+    this.object.position.applyQuaternion(_qStep);
+    this.object.position.add(pivot);
+
+    this.object.quaternion.premultiply(_qStep);
+    this.object.up.applyQuaternion(_qStep).normalize();
+
+    this.target.sub(pivot);
+    this.target.applyQuaternion(_qStep);
+    this.target.add(pivot);
+  }
+
+  private _getPitchAxis(pivot: Vector3) {
+    _viewOffset.copy(this.object.position).sub(pivot);
+    if (_viewOffset.lengthSq() <= 1e-10) return null;
+    _viewOffset.normalize();
+    _xAxis.crossVectors(_yAxis, _viewOffset);
+    if (_xAxis.lengthSq() <= 1e-10) return null;
+    return _xAxis.normalize();
+  }
+
+  commitViewRotation() {
+    this.updateOrbitUpBasis();
+    this._syncOrbitStateFromCamera();
+    this.dispatchEvent(_CHANGE_EVENT as never);
+  }
+
+  rotateViewAtPivot(pivot: Vector3, direction: 'up' | 'down' | 'left' | 'right', angleRadians: number) {
+    if (!angleRadians) return;
+
+    _yAxis.copy(this.object.up).normalize();
+
+    switch (direction) {
+      case 'left':
+        this._rotateAroundPivot(_yAxis, angleRadians, pivot);
+        break;
+      case 'right':
+        this._rotateAroundPivot(_yAxis, -angleRadians, pivot);
+        break;
+      case 'up':
+      case 'down': {
+        const pitchAxis = this._getPitchAxis(pivot);
+        if (!pitchAxis) break;
+        const pitch = direction === 'up' ? -angleRadians : angleRadians;
+        this._rotateAroundPivot(pitchAxis, pitch, pivot);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  flipViewAtPivot(pivot: Vector3) {
+    _yAxis.copy(this.object.up).normalize();
+    this._rotateAroundPivot(_yAxis, Math.PI, pivot);
+  }
+
+  private _consumeRotationDelta() {
+    const ctrl = internals(this);
+    let deltaTheta: number;
+    let deltaPhi: number;
+
+    if (this.enableDamping) {
+      deltaTheta = ctrl._sphericalDelta.theta * this.dampingFactor;
+      deltaPhi = ctrl._sphericalDelta.phi * this.dampingFactor;
+      ctrl._sphericalDelta.theta *= 1 - this.dampingFactor;
+      ctrl._sphericalDelta.phi *= 1 - this.dampingFactor;
+    } else {
+      deltaTheta = ctrl._sphericalDelta.theta;
+      deltaPhi = ctrl._sphericalDelta.phi;
+      ctrl._sphericalDelta.set(0, 0, 0);
+    }
+
+    return { deltaTheta, deltaPhi };
+  }
+
+  private _hasPendingRotation() {
+    const ctrl = internals(this);
+    return (
+      Math.abs(ctrl._sphericalDelta.theta) >= _DAMPING_EPS ||
+      Math.abs(ctrl._sphericalDelta.phi) >= _DAMPING_EPS
+    );
+  }
+
+  private _updatePivotOrbit() {
+    const { deltaTheta, deltaPhi } = this._consumeRotationDelta();
+
+    if (deltaTheta === 0 && deltaPhi === 0) {
+      return false;
+    }
+
+    _yAxis.copy(this.object.up).normalize();
+
+    if (deltaTheta !== 0) {
+      this._rotateAroundPivot(_yAxis, deltaTheta);
+    }
+
+    if (deltaPhi !== 0) {
+      const pitchAxis = this._getPitchAxis(this._orbitPivot);
+      if (pitchAxis) {
+        this._rotateAroundPivot(pitchAxis, deltaPhi);
+      }
+    }
+
+    return true;
+  }
+
+  private _syncOrbitStateFromCamera() {
+    const ctrl = internals(this);
+    this.object.getWorldDirection(_lookDirection);
+
+    let distance = this.object.position.distanceTo(this.target);
+    if (distance < 1e-4) {
+      distance = 10;
+    }
+
+    this.target.copy(this.object.position).addScaledVector(_lookDirection, distance);
+
+    _offset.copy(this.object.position).sub(this.target);
+    _offset.applyQuaternion(ctrl._quat);
+    ctrl._spherical.setFromVector3(_offset);
+    ctrl._sphericalDelta.set(0, 0, 0);
+    ctrl._panOffset.set(0, 0, 0);
+    ctrl._scale = 1;
+  }
+
+  endOrbitAroundPivot() {
+    if (!this._orbitPivotMode) return;
+
+    this._orbitPivotMode = false;
+    this._orbitPivotPendingEnd = false;
+    this.updateOrbitUpBasis();
+    this._syncOrbitStateFromCamera();
+  }
+
+  private _onControlStart() {
+    if (internals(this).state !== _STATE_ROTATE) return;
+
+    const pivot = this.getOrbitPivot();
+    if (!pivot) return;
+
+    this.beginOrbitAroundPivot(pivot);
+  }
+
+  private _onControlEnd() {
+    if (!this._orbitPivotMode) return;
+
+    this._orbitPivotPendingEnd = true;
+
+    if (!this.enableDamping || !this._hasPendingRotation()) {
+      this.endOrbitAroundPivot();
+    }
+  }
+
+  override update(deltaTime: number | null = null): boolean {
+    if (!this._orbitPivotMode) {
+      return super.update(deltaTime);
+    }
+
+    const changed = this._updatePivotOrbit();
+    if (changed) {
+      this.dispatchEvent(_CHANGE_EVENT as never);
+    }
+
+    if (this._orbitPivotPendingEnd && !this._hasPendingRotation()) {
+      this.endOrbitAroundPivot();
+    }
+
+    return changed;
+  }
+}
+
+export { MOUSE };

package/src/viewport/ViewGrid.ts

@@ -0,0 +1,268 @@
+import {
+  Color,
+  DoubleSide,
+  Mesh,
+  PlaneGeometry,
+  ShaderMaterial,
+  Vector3,
+  type Mesh as ThreeMesh,
+} from 'three';
+
+import { HELPER_OBJECT_TYPE } from '../constants.js';
+import { getViewAspect, getViewHeightAtDistance, type ViewCamera } from './ViewportUtils.js';
+import type { CustomControls } from './CustomControls.js';
+
+const GRID_VERTEX_SHADER = `
+varying vec3 vWorldPosition;
+
+void main() {
+  vec4 worldPosition = modelMatrix * vec4(position, 1.0);
+  vWorldPosition = worldPosition.xyz;
+  gl_Position = projectionMatrix * viewMatrix * worldPosition;
+}
+`;
+
+const GRID_FRAGMENT_SHADER = `
+varying vec3 vWorldPosition;
+
+uniform float uCellSize;
+uniform float uSubCellSize;
+uniform float uSectionSize;
+uniform float uSubBlend;
+uniform vec3 uCellColor;
+uniform vec3 uSectionColor;
+uniform vec3 uCenter;
+uniform float uFadeRadius;
+
+const float FW_EPSILON = 1.0e-7;
+
+float gridFactor(vec2 coord, float step) {
+  vec2 uv = coord / step;
+  vec2 grid = abs(fract(uv - 0.5) - 0.5);
+  vec2 fw = max(fwidth(uv), vec2(FW_EPSILON));
+  float distPx = min(grid.x / fw.x, grid.y / fw.y);
+  return 1.0 - smoothstep(0.0, 1.0, distPx);
+}
+
+float gridLineAlongX(vec2 coord, float step) {
+  float uv = coord.x / step;
+  float grid = abs(fract(uv - 0.5) - 0.5);
+  float fw = max(fwidth(uv), FW_EPSILON);
+  return 1.0 - smoothstep(0.0, 1.0, grid / fw);
+}
+
+float gridLineAlongZ(vec2 coord, float step) {
+  float uv = coord.y / step;
+  float grid = abs(fract(uv - 0.5) - 0.5);
+  float fw = max(fwidth(uv), FW_EPSILON);
+  return 1.0 - smoothstep(0.0, 1.0, grid / fw);
+}
+
+float subScreenFade(vec2 coord, float cellSize) {
+  float fw = max(fwidth(coord.x), FW_EPSILON);
+  float pixelWidth = cellSize / fw;
+  return smoothstep(3.0, 6.0, pixelWidth);
+}
+
+void main() {
+  vec2 coord = vWorldPosition.xz;
+  vec2 fadeCoord = vWorldPosition.xz - uCenter.xz;
+
+  float subMinor = gridFactor(coord, uSubCellSize);
+  float subMask = subMinor * 0.35 * uSubBlend * subScreenFade(coord, uSubCellSize);
+
+  float mainMinor = gridFactor(coord, uCellSize);
+  float mainMajor = gridFactor(coord, uSectionSize);
+  float mainMask = max(mainMinor * 0.35, mainMajor * 0.55);
+
+  float lineMask = max(subMask, mainMask);
+
+  float axisGap = uSubCellSize * 0.6;
+  bool onVertLine = gridLineAlongX(coord, uSubCellSize) > 0.01
+    || gridLineAlongX(coord, uCellSize) > 0.01
+    || gridLineAlongX(coord, uSectionSize) > 0.01;
+  bool onHorizLine = gridLineAlongZ(coord, uSubCellSize) > 0.01
+    || gridLineAlongZ(coord, uCellSize) > 0.01
+    || gridLineAlongZ(coord, uSectionSize) > 0.01;
+
+  if (abs(vWorldPosition.x) < axisGap && onVertLine) {
+    discard;
+  }
+  if (abs(vWorldPosition.z) < axisGap && onHorizLine) {
+    discard;
+  }
+
+  if (lineMask < 0.01) {
+    discard;
+  }
+
+  vec3 lineColor = mix(uCellColor, uSectionColor, mainMajor);
+
+  float dist = length(fadeCoord);
+  float fade = 1.0 - smoothstep(uFadeRadius * 0.65, uFadeRadius, dist);
+  float alpha = lineMask * fade;
+
+  if (alpha < 0.01) {
+    discard;
+  }
+
+  gl_FragColor = vec4(lineColor, alpha);
+}
+`;
+
+const NICE_STEPS = [1, 2, 5];
+const BASE_PLANE_SIZE = 1;
+
+function snapToNiceNumber(value: number) {
+  if (!Number.isFinite(value) || value <= 0) return 1;
+
+  const exponent = Math.floor(Math.log10(value));
+  const base = 10 ** exponent;
+  const normalized = value / base;
+
+  for (const step of NICE_STEPS) {
+    if (normalized <= step) {
+      return step * base;
+    }
+  }
+
+  return 10 * base;
+}
+
+function calcRawCellSize({
+  visibleHeight,
+  viewportHeight,
+  pixelsPerMinorLine = 64,
+}: {
+  visibleHeight: number;
+  viewportHeight: number;
+  pixelsPerMinorLine?: number;
+}) {
+  if (!Number.isFinite(visibleHeight) || visibleHeight <= 0) return 1;
+  if (!Number.isFinite(viewportHeight) || viewportHeight <= 0) return 1;
+
+  const worldPerPixel = visibleHeight / viewportHeight;
+  return worldPerPixel * pixelsPerMinorLine;
+}
+
+function calcScaleState(params: {
+  visibleHeight: number;
+  viewportHeight: number;
+  pixelsPerMinorLine?: number;
+}) {
+  const rawCell = calcRawCellSize(params);
+
+  if (!Number.isFinite(rawCell) || rawCell <= 0) {
+    return {
+      rawCell: 1,
+      cellSize: 1,
+      subCellSize: 0.1,
+      sectionSize: 10,
+      subBlend: 1,
+    };
+  }
+
+  const cellSize = snapToNiceNumber(rawCell);
+  const subCellSize = cellSize / 10;
+  let subBlend = 0;
+
+  if (cellSize > subCellSize) {
+    subBlend = (cellSize - rawCell) / (cellSize - subCellSize);
+    subBlend = Math.max(0, Math.min(1, subBlend));
+  }
+
+  return {
+    rawCell,
+    cellSize,
+    subCellSize,
+    sectionSize: cellSize * 10,
+    subBlend,
+  };
+}
+
+function calcPlaneSize({
+  visibleHeight,
+  aspect,
+  margin = 2.5,
+}: {
+  visibleHeight: number;
+  aspect: number;
+  margin?: number;
+}) {
+  if (!Number.isFinite(visibleHeight) || visibleHeight <= 0) return 20;
+
+  const safeAspect = Number.isFinite(aspect) && aspect > 0 ? aspect : 16 / 9;
+  const visibleWidth = visibleHeight * safeAspect;
+
+  return Math.max(visibleWidth, visibleHeight) * margin;
+}
+
+export class ViewGrid {
+  camera: ViewCamera | null = null;
+  controls: CustomControls | null = null;
+  grid: ThreeMesh | null = null;
+  uniforms: Record<string, { value: unknown }> | null = null;
+
+  create(camera: ViewCamera, controls: CustomControls) {
+    this.camera = camera;
+    this.controls = controls;
+
+    const geometry = new PlaneGeometry(BASE_PLANE_SIZE, BASE_PLANE_SIZE, 1, 1);
+    geometry.rotateX(-Math.PI / 2);
+
+    this.uniforms = {
+      uCellSize: { value: 1 },
+      uSubCellSize: { value: 0.1 },
+      uSectionSize: { value: 10 },
+      uSubBlend: { value: 1 },
+      uCellColor: { value: new Color(0xd0d0d0) },
+      uSectionColor: { value: new Color(0xaaaaaa) },
+      uCenter: { value: new Vector3() },
+      uFadeRadius: { value: 50 },
+    };
+
+    const material = new ShaderMaterial({
+      uniforms: this.uniforms,
+      vertexShader: GRID_VERTEX_SHADER,
+      fragmentShader: GRID_FRAGMENT_SHADER,
+      transparent: true,
+      depthWrite: false,
+      side: DoubleSide,
+    });
+
+    this.grid = new Mesh(geometry, material);
+    this.grid.frustumCulled = false;
+    this.grid.renderOrder = 1;
+    this.grid.raycast = () => {};
+    this.grid.userData.objectType = HELPER_OBJECT_TYPE;
+
+    return this.grid;
+  }
+
+  update(viewportHeight: number) {
+    if (!this.camera || !this.controls || !this.grid || !this.uniforms) return;
+
+    const target = this.controls.getViewCenter?.() ?? this.controls.target;
+    const distance = this.camera.position.distanceTo(target);
+    const visibleHeight = getViewHeightAtDistance(this.camera, distance);
+    const gridScale = calcScaleState({
+      visibleHeight,
+      viewportHeight: viewportHeight || 720,
+    });
+    const planeSize = calcPlaneSize({
+      visibleHeight,
+      aspect: getViewAspect(this.camera),
+    });
+
+    this.uniforms.uCellSize.value = gridScale.cellSize;
+    this.uniforms.uSubCellSize.value = gridScale.subCellSize;
+    this.uniforms.uSectionSize.value = gridScale.sectionSize;
+    this.uniforms.uSubBlend.value = gridScale.subBlend;
+    (this.uniforms.uCenter.value as Vector3).copy(target);
+    this.uniforms.uFadeRadius.value = planeSize * 0.5;
+
+    const scale = planeSize / BASE_PLANE_SIZE;
+    this.grid.position.set(target.x, 0, target.z);
+    this.grid.scale.set(scale, 1, scale);
+  }
+}

package/src/viewport/ViewportUtils.ts

@@ -0,0 +1,173 @@
+import {
+  CanvasTexture,
+  LinearFilter,
+  SRGBColorSpace,
+  Vector3,
+  type Box3,
+  type PerspectiveCamera,
+} from 'three';
+
+export type ViewCamera = {
+  fov?: number;
+  aspect?: number;
+  isOrthographicCamera?: boolean;
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+  zoom?: number;
+  far?: number;
+  position: { distanceTo(v: { x: number; y: number; z: number }): number };
+};
+
+export function degToRad(deg: number): number {
+  return (deg * Math.PI) / 180;
+}
+
+/**
+ * Compute camera placement from bounds and viewport parameters.
+ * Shared by the main editor and model preview viewports.
+ */
+export function computeCameraPlacement({
+  size,
+  center,
+  fov,
+  aspect,
+  padding = 1.6,
+  minDistance = 5,
+  direction = { x: 1, y: 0.8, z: 1 },
+}: {
+  size: Vector3;
+  center: Vector3;
+  fov: number;
+  aspect: number;
+  padding?: number;
+  minDistance?: number;
+  direction?: { x: number; y: number; z: number };
+}) {
+  const halfFov = degToRad(fov) / 2;
+  const fitHeightDistance = size.y / (2 * Math.tan(halfFov));
+  const fitWidthDistance = size.x / (2 * Math.tan(halfFov) * aspect);
+  const fitDepthDistance = size.z / 2;
+  const distance = Math.max(fitHeightDistance, fitWidthDistance, fitDepthDistance, minDistance) * padding;
+
+  const length = Math.hypot(direction.x, direction.y, direction.z) || 1;
+  const normalizedDirection = {
+    x: direction.x / length,
+    y: direction.y / length,
+    z: direction.z / length,
+  };
+
+  return {
+    distance,
+    position: {
+      x: center.x + normalizedDirection.x * distance,
+      y: center.y + normalizedDirection.y * distance,
+      z: center.z + normalizedDirection.z * distance,
+    },
+  };
+}
+
+/** Visible world height at a given distance from the camera target. */
+export function getViewHeightAtDistance(camera: ViewCamera, distance: number): number {
+  if (camera?.isOrthographicCamera) {
+    const zoom = camera.zoom || 1;
+    return ((camera.top ?? 0) - (camera.bottom ?? 0)) / zoom;
+  }
+
+  const fov = Number.isFinite(camera?.fov) && (camera.fov ?? 0) > 0 ? (camera.fov as number) : 50;
+  const halfFovRad = (fov * Math.PI) / 360;
+  const safeDistance = Number.isFinite(distance) && distance > 0 ? distance : 1;
+  return 2 * Math.tan(halfFovRad) * safeDistance;
+}
+
+/** Camera aspect ratio (perspective or orthographic). */
+export function getViewAspect(camera: ViewCamera): number {
+  if (camera?.isOrthographicCamera) {
+    const height = (camera.top ?? 0) - (camera.bottom ?? 0);
+    return height !== 0 ? ((camera.right ?? 0) - (camera.left ?? 0)) / height : 1;
+  }
+
+  return Number.isFinite(camera?.aspect) && (camera.aspect ?? 0) > 0 ? (camera.aspect as number) : 16 / 9;
+}
+
+/** Blender-style viewport background gradient. */
+export function createViewportBackground(topColor = '#454545', bottomColor = '#303030') {
+  const canvas = document.createElement('canvas');
+  canvas.width = 2;
+  canvas.height = 512;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to create viewport background canvas context');
+  }
+
+  const gradient = ctx.createLinearGradient(0, 0, 0, canvas.height);
+  gradient.addColorStop(0, topColor || '#454545');
+  gradient.addColorStop(1, bottomColor || '#303030');
+  ctx.fillStyle = gradient;
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+  const texture = new CanvasTexture(canvas);
+  texture.colorSpace = SRGBColorSpace;
+  texture.magFilter = LinearFilter;
+  texture.minFilter = LinearFilter;
+
+  return texture;
+}
+
+const _center = new Vector3();
+const _size = new Vector3();
+
+/** Frame the camera on object or animated bounds. */
+export function frameObjectInView({
+  camera,
+  controls,
+  getBounds,
+  fov,
+  aspect,
+  padding = 1.8,
+  direction = { x: 1, y: 0.55, z: 1 },
+}: {
+  camera: PerspectiveCamera;
+  controls?: { target: Vector3; maxDistance?: number; update(): void } | null;
+  getBounds: () => Box3;
+  fov: number;
+  aspect: number;
+  padding?: number;
+  direction?: { x: number; y: number; z: number };
+}) {
+  const box = getBounds();
+  if (!box || box.isEmpty()) {
+    return false;
+  }
+
+  box.getCenter(_center);
+  box.getSize(_size);
+
+  const placement = computeCameraPlacement({
+    size: _size,
+    center: _center,
+    fov,
+    aspect,
+    padding,
+    minDistance: 0.5,
+    direction,
+  });
+
+  camera.fov = fov;
+  camera.position.set(placement.position.x, placement.position.y, placement.position.z);
+  camera.near = Math.max(placement.distance / 200, 0.01);
+  camera.far = Math.max(placement.distance * 200, 1000);
+  camera.aspect = aspect;
+  camera.updateProjectionMatrix();
+  camera.lookAt(_center);
+
+  if (controls) {
+    controls.target.copy(_center);
+    controls.maxDistance = placement.distance * 20;
+    controls.update();
+  }
+
+  return true;
+}