ReactとThree.jsで、3Dの模型を回して見せる方法

​​React​drei,React Three Fiber,Three.js,TypeScript,Vite

React Three Fiber(R3F)を使うと、Three.js の 3D のシーンを React のコンポーネントとして書けます。glb 形式の 3D モデルを読み込み、自動でゆっくり回しながら、ドラッグで好きな向きから見られるようにする書き方を示します。商品の 3D ビューや、作品・フィギュアの紹介ページのように、模型をぐるりと見せたい場面で使えます。

回す処理は useFrame の中で、向き(rotation.y)に「経過した秒数 × 速さ」を足すだけです。ただし、秒数(delta)を使わずに決まった量を足すと、画面を描き直す回数が多い環境ほど速く回ります。検証ではその差がはっきり出たので、数字で示します。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。three 0.187.0、@react-three/fiber 9.8.2、@react-three/drei 10.7.9、@types/three 0.187.0、react / react-dom 19.3.1、typescript 7.0.2、vite 8.3.7 を使い、tsc で型チェックしてから Vite で動かしました。ブラウザは Playwright 1.63.0 で動かした Chromium 153(ヘッドレス)だけで、WebGL は、GPU の処理をソフトウェアで代わりに行う SwiftShader(Chromium に入っているもの)で描画されました。模型は、検証用に Three.js で直方体や円柱を組み合わせて作った glb ファイルです。Firefox・Safari・実機のスマートフォン、タッチ操作、本物の GPU での描画、Next.js などでのサーバーサイドレンダリングは試していません。

three と React Three Fiber、drei を入れる

R3F は Three.js を React から使うためのライブラリで、three 本体は自分で入れます。R3F のインストールの説明では、@react-three/fiber@9 は React 19 と組み合わせるものとされています。drei は、モデルの読み込みやカメラの操作など、よく使う部品をまとめた R3F 用のライブラリです。

sh
npm install three @react-three/fiber @react-three/drei
npm install -D @types/three

検証で使った @react-three/fiber 9.8.2 の peerDependencies は、react と react-dom が >=19 <19.4、three が >=0.156 でした。

TypeScript では、tsconfig.json に "skipLibCheck": true がないと、tsc が drei の依存パッケージ(three-stdlib 2.36.1)の型定義でエラーを出しました。

text
node_modules/three-stdlib/loaders/SVGLoader.d.ts(3,18): error TS2430: Interface 'SVGResultPaths' incorrectly extends interface 'ShapePath'.
node_modules/three-stdlib/loaders/TGALoader.d.ts(13,3): error TS2416: Property 'parse' in type 'TGALoader' is not assignable to the same property in base type 'DataTextureLoader'.

自分のコードではなく、three-stdlib の型定義と @types/three 0.187.0 の食い違いで起きているエラーです。"skipLibCheck": true を付けると、エラーは出なくなりました。

まず箱を1つ回してみる

モデルを読み込む前に、R3F で物を回す仕組みを、箱で確かめます。

tsx
// SpinningBox.tsx
import { useRef } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import type { Mesh } from 'three';

function Box() {
  const ref = useRef<Mesh>(null);
  useFrame((_, delta) => {
    if (ref.current) ref.current.rotation.y += delta;
  });
  return (
    <mesh ref={ref} name="box" rotation={[0.4, 0, 0]}>
      <boxGeometry args={[1.5, 1.5, 1.5]} />
      <meshStandardMaterial color="#00c8e8" />
    </mesh>
  );
}

export function SpinningBox() {
  return (
    <div style={{ height: 300 }}>
      <Canvas>
        <ambientLight intensity={0.5} />
        <directionalLight position={[2, 3, 4]} intensity={2} />
        <Box />
      </Canvas>
    </div>
  );
}

<Canvas> の中に書いた <mesh> は Three.js の Mesh として作られてシーンに加わり、その中の <boxGeometry> は、R3F のオブジェクトの説明のとおり、親の mesh の geometry として取り付けられます。useFrame に渡した関数は、R3F のフックの説明のとおり、画面を描く直前に毎回呼ばれます。2つ目の引数 delta は、前に描いたときからの経過時間(秒)です。

この関数の中では、ref で受け取った Three.js のオブジェクトを直接書き換えます。同じ説明には、useFrame の中で setState をしてはいけないとも書かれています。R3F のよくある落とし穴の説明によると、setState を使うと、値の更新が React のスケジューラーを通り、コンポーネントの再レンダリングまで起きてしまうためです。

検証環境で試したところ、2.011 秒で rotation.y が 2.016 増えました。Three.js の Euler の説明のとおり rotation.y の単位はラジアンなので、+= delta は「1秒に1ラジアン(約57度)」回すという意味になります。

delta を使わないと、描画の回数しだいで速さが変わる

rotation.y += 1 / 60 のように、1回の描画ごとに決まった量を足す書き方と比べました。ふつうに起動した Chromium は1秒に60回描いたので、どちらも1秒に約1ラジアンで、差はありません。ところが、Chromium を --disable-gpu-vsync --disable-frame-rate-limit を付けて起動し、描画の回数の上限を外すと、結果が分かれました。

書き方 1秒に描いた回数 1秒に回った角度
+= delta(経過時間を足す) 329回 1.000 rad
+= 1 / 60(決まった量を足す) 321回 5.342 rad

経過時間を足す書き方は、描く回数が5倍以上に増えても同じ速さで回りました。決まった量を足す書き方は、描く回数に比例して速くなっています。R3F のフックの説明によると、useFrame の関数は画面のリフレッシュレートに合わせて呼ばれます。落とし穴の説明でも、決まった値ではなく delta を使うよう勧めています。そうすればリフレッシュレートに左右されず、どの環境でも同じ速さで動きます。

glb のモデルを読み込んで回す

ここからが本題です。3D モデルを public/models/robot.glb に置き、drei の useGLTF で読み込みます。glb は、glTF の JSON とバイナリデータを1つのファイルにまとめた形式で、glTF の仕様で定められています。

tsx
// ModelViewer.tsx
import { Suspense, useRef, type RefObject } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import { Center, OrbitControls, useGLTF } from '@react-three/drei';
import type { Group } from 'three';

const MODEL_URL = '/models/robot.glb';

function Model({ paused }: { paused: RefObject<boolean> }) {
  const { scene } = useGLTF(MODEL_URL);
  const turntable = useRef<Group>(null);

  // 1フレームごとに呼ばれる。delta は前のフレームからの経過秒数
  useFrame((_, delta) => {
    if (!turntable.current || paused.current) return;
    turntable.current.rotation.y += delta * 0.8; // 1秒に0.8ラジアン
  });

  return (
    <group ref={turntable} name="turntable">
      <Center>
        <primitive object={scene} />
      </Center>
    </group>
  );
}

export function ModelViewer() {
  const paused = useRef(false);

  return (
    <div style={{ height: 400 }}>
      <Canvas camera={{ position: [0, 1.5, 5], fov: 45 }}>
        <ambientLight intensity={0.6} />
        <directionalLight position={[3, 5, 4]} intensity={2} />
        <Suspense fallback={null}>
          <Model paused={paused} />
        </Suspense>
        <OrbitControls
          enablePan={false}
          minDistance={3}
          maxDistance={8}
          onStart={() => { paused.current = true; }}
          onEnd={() => { paused.current = false; }}
        />
      </Canvas>
    </div>
  );
}

useGLTF.preload(MODEL_URL);

コードの各部分は、次のように働きます。

  • useGLTF:drei のフックで、Three.js の GLTFLoader でモデルを読み込む。戻り値の scene が、モデル全体の入った Group
  • <primitive object={scene} />:すでにある Three.js のオブジェクトを、そのままシーンに置く(R3F のオブジェクトの説明によると、同じオブジェクトを2か所に置くことはできない)
  • <Center>:中に入れたものを包む箱(バウンディングボックス)の中心が、原点に来るようにずらす
  • <group ref={turntable}>:回転台。モデルではなく、この入れ物を回す
  • <Suspense>:読み込みが終わるまで fallback を表示する。useGLTF のもとになっている R3F の useLoader は、読み込みが終わるまでコンポーネントをサスペンドさせる(その間は <Suspense> の fallback が表示される)
  • useGLTF.preload:コンポーネントが表示される前に、読み込みを始めておく

モデルを <Center> で原点に置いてから外側の group を回すので、模型は自分の中心を軸にして、その場で回ります。

読み込みの書き方は、R3F のモデルの読み込みの説明と、drei の useGLTF の説明にあるものです。検証環境で開発サーバーのページを開くと、ブラウザは /models/robot.glb を1回だけ取得し、模型が表示されて回り始めました。測ったところ、3.01 秒で turntable の rotation.y が 2.408 増え、1秒あたり 0.799 ラジアンでした。

npx vite build でビルドし、npx vite preview で開いた場合も、public/models/robot.glb は dist/models/robot.glb にコピーされ、同じように表示されました。ModelViewer だけのページをビルドすると、JavaScript は 1,228.87 kB(gzip で 337.30 kB)になり、Vite が「500 kB を超えるチャンクがある」と警告しました。

drei の説明によると、useGLTF は既定で、Draco で圧縮されたモデルを展開するデコーダーを https://www.gstatic.com/draco/v1/decoders/ から読み込みます。読み込むのは圧縮されたモデルを開くときだけ、とされています。検証で使った glb は圧縮していないもので、gstatic への通信は起きませんでした。

ドラッグで見回す間は、自動の回転を止める

drei の <OrbitControls> を置くと、ドラッグでカメラを模型のまわりに動かし、ホイールで寄ったり離れたりできます。中身は、drei が使っている three-stdlib というパッケージの OrbitControls です。three-stdlib は、Three.js の examples にあるコードを単独のライブラリとしてまとめたものです。

見たい向きでじっくり見られるように、操作している間は自動の回転を止め、操作が終わったら再び回します。three-stdlib の OrbitControls は、元になった Three.js の OrbitControls と同じく、操作の始まりに start、終わりに end のイベントを出します。drei の <OrbitControls> では、それぞれ onStart と onEnd で受け取れます。

止めているかどうかは、useState ではなく useRef で持ちます。useFrame の中で毎回読むだけの値なので、変わるたびに再レンダリングする必要がありません。

ロボットの模型が自動で回る。カーソルでドラッグすると上の帯がピンクの「ドラッグ中:自動の回転は止まる」に変わり、見る向きが変わる。ボタンを離すと帯が白に戻って「離すと、また自動で回る」になり、再び回る
自動で回る様子と、ドラッグして見回す間は回転が止まる様子(上の帯とカーソルは撮影用に重ねた表示)

検証環境で、模型の上でマウスのボタンを押してドラッグし、押したまま1秒待ったところ、rotation.y は 5.129 のまま変わりませんでした。ボタンを離してから1秒後には 5.929 になり、0.800 増えていました。上の GIF のように、ドラッグの間は見る向きだけが変わり、模型自体は回りません。

ほかの props の働きも確かめました。

  • minDistance={3} と maxDistance={8}:ホイールで寄り続けるとカメラと中心の距離は 3.000 で止まり、離れ続けると 8.000 で止まった(最初は 5.220)
  • enablePan={false}:右ボタンでドラッグしても、カメラの位置は変わらなかった

enablePan は、カメラを上下左右に平行移動する操作を許すかどうかの設定で、既定は true です。模型を回して見せるだけなら平行移動は使わないので、今回は無効にしました。

真っ黒になるとき、高さが足りないとき

光を置かないと、模型が真っ黒になる

<ambientLight> と <directionalLight> を置かずに同じ模型を描くと、真っ黒な影絵のようになりました。今回の glb のマテリアルは、Three.js の MeshStandardMaterial として読み込まれていました。Three.js のリファレンスで「物理ベース」と説明されているマテリアルです。光が1つもないシーンでは、水色やピンクの色を付けた部分も黒く描かれました。

上は光を置かずに描いたロボットで、全体が真っ黒。下は ambientLight と directionalLight を置いたもので、水色の体とピンクの胸の板、黒い目が見える
光を置かない場合(上)と、2つの光を置いた場合(下)

Three.js のリファレンスによると、AmbientLight(<ambientLight>)はシーンのすべての物を同じように照らす光、DirectionalLight(<directionalLight>)は太陽の光のように、決まった方向から平行に差す光です。今回は2つを組み合わせました。

Canvas の親に高さがないと、150px になる

<Canvas> は、親の要素の大きさに合わせて広がります。高さ 300px の div に置いた箱の例では、canvas も幅 768px・高さ 300px になりました。ところが、親の div に高さを付けずに置くと、canvas の高さは 150px になりました(幅は 768px)。150px は、MDN の canvas 要素の説明にある、高さの既定値と同じです。模型を大きく見せたいときは、上のコードの style={{ height: 400 }} のように、親に高さを付けます。

THREE.Clock の警告が出る

検証の間、ブラウザのコンソールに次の警告が出ました。

text
THREE.Clock: This module has been deprecated. Please use THREE.Timer instead.

three は r183 から THREE.Clock を非推奨にしていて、@react-three/fiber 9.8.2 が内部で new THREE.Clock() を作っているために出る警告です。記事のコードは THREE.Clock を使っていません。この警告が出ている状態で、ここまでに書いた動きはすべて確かめました。

​Posted by 86