ArcballControls.html 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469
  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <title>ArcballControls - Three.js Docs</title>
  6. <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
  7. <script src="../scripts/highlight.min.js"></script>
  8. <link type="text/css" rel="stylesheet" href="../styles/highlight-three.css">
  9. <link type="text/css" rel="stylesheet" href="../styles/page.css">
  10. </head>
  11. <body>
  12. <p class="inheritance" translate="no"><a href="EventDispatcher.html">EventDispatcher</a> → <a href="Controls.html">Controls</a> → </p>
  13. <h1 translate="no">ArcballControls</h1>
  14. <section>
  15. <header>
  16. <div class="class-description"><p>Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced navigation functionality.
  17. Cursor/finger positions and movements are mapped over a virtual trackball surface represented by a gizmo and mapped in intuitive and
  18. consistent camera movements. Dragging cursor/fingers will cause camera to orbit around the center of the trackball in a conservative
  19. way (returning to the starting point will make the camera return to its starting orientation).</p>
  20. <p>In addition to supporting pan, zoom and pinch gestures, Arcball controls provide focus&lt; functionality with a double click/tap for intuitively
  21. moving the object's point of interest in the center of the virtual trackball. Focus allows a much better inspection and navigation in complex
  22. environment. Moreover Arcball controls allow FOV manipulation (in a vertigo-style method) and z-rotation. Saving and restoring of Camera State
  23. is supported also through clipboard (use ctrl+c and ctrl+v shortcuts for copy and paste the state).</p>
  24. <p>Unlike <a href="OrbitControls.html">OrbitControls</a> and <a href="TrackballControls.html">TrackballControls</a>, <code>ArcballControls</code> doesn't require <code>update()</code> to be called externally in an
  25. animation loop when animations are on.</p></div>
  26. </header>
  27. <article>
  28. <h2 class="subsection-title">Import</h2>
  29. <p><span translate="no">ArcballControls</span> is an addon, and must be imported explicitly, see <a href="https://threejs.org/manual/#en/installation" target="_blank" rel="noopener">Installation#Addons</a>.</p>
  30. <pre><code class="language-js">import { ArcballControls } from 'three/addons/controls/ArcballControls.js';</code></pre>
  31. <div class="container-overview">
  32. <h2>Constructor</h2>
  33. <h3 class="name name-method" id="ArcballControls" translate="no">new <a href="#ArcballControls">ArcballControls</a><span class="signature">( camera : <span class="param-type"><a href="Camera.html">Camera</a></span>, domElement : <span class="param-type">HTMLElement</span>, scene : <span class="param-type"><a href="Scene.html">Scene</a></span> )</span> </h3>
  34. <div class="method">
  35. <div class="description">
  36. <p>Constructs a new controls instance.</p>
  37. </div>
  38. <table class="params">
  39. <tbody>
  40. <tr>
  41. <td class="name">
  42. <strong>camera</strong>
  43. </td>
  44. <td class="description last">
  45. <p>The camera to be controlled. The camera must not be a child of another object, unless that object is the scene itself.</p>
  46. </td>
  47. </tr>
  48. <tr>
  49. <td class="name">
  50. <strong>domElement</strong>
  51. </td>
  52. <td class="description last">
  53. <p>The HTML element used for event listeners.</p>
  54. <p>Default is <code>null</code>.</p>
  55. </td>
  56. </tr>
  57. <tr>
  58. <td class="name">
  59. <strong>scene</strong>
  60. </td>
  61. <td class="description last">
  62. <p>The scene rendered by the camera. If not given, gizmos cannot be shown.</p>
  63. <p>Default is <code>null</code>.</p>
  64. </td>
  65. </tr>
  66. </tbody>
  67. </table>
  68. </div>
  69. </div>
  70. <h2 class="subsection-title">Properties</h2>
  71. <div class="member">
  72. <h3 class="name" id="adjustNearFar" translate="no">.<a href="#adjustNearFar">adjustNearFar</a><span class="type-signature"> : boolean</span> </h3>
  73. <div class="description">
  74. <p>If set to <code>true</code>, the camera's near and far values will be adjusted every time zoom is
  75. performed trying to maintain the same visible portion given by initial near and far
  76. values. Only works with perspective cameras.</p>
  77. <p>Default is <code>false</code>.</p>
  78. </div>
  79. </div>
  80. <div class="member">
  81. <h3 class="name" id="cursorZoom" translate="no">.<a href="#cursorZoom">cursorZoom</a><span class="type-signature"> : boolean</span> </h3>
  82. <div class="description">
  83. <p>Set to <code>true</code> to make zoom become cursor centered.</p>
  84. <p>Default is <code>false</code>.</p>
  85. </div>
  86. </div>
  87. <div class="member">
  88. <h3 class="name" id="dampingFactor" translate="no">.<a href="#dampingFactor">dampingFactor</a><span class="type-signature"> : number</span> </h3>
  89. <div class="description">
  90. <p>The damping inertia used if 'enableAnimations<code>is set to</code>true`.</p>
  91. <p>Default is <code>25</code>.</p>
  92. </div>
  93. </div>
  94. <div class="member">
  95. <h3 class="name" id="enableAnimations" translate="no">.<a href="#enableAnimations">enableAnimations</a><span class="type-signature"> : boolean</span> </h3>
  96. <div class="description">
  97. <p>Set to <code>true</code> to enable animations for rotation (damping) and focus operation.</p>
  98. <p>Default is <code>true</code>.</p>
  99. </div>
  100. </div>
  101. <div class="member">
  102. <h3 class="name" id="enableFocus" translate="no">.<a href="#enableFocus">enableFocus</a><span class="type-signature"> : boolean</span> </h3>
  103. <div class="description">
  104. <p>Enable or disable camera focusing on double-tap (or click) operations.</p>
  105. <p>Default is <code>true</code>.</p>
  106. </div>
  107. </div>
  108. <div class="member">
  109. <h3 class="name" id="enableGizmos" translate="no">.<a href="#enableGizmos">enableGizmos</a><span class="type-signature"> : boolean</span> </h3>
  110. <div class="description">
  111. <p>Enable or disable gizmos.</p>
  112. <p>Default is <code>true</code>.</p>
  113. </div>
  114. </div>
  115. <div class="member">
  116. <h3 class="name" id="enableGrid" translate="no">.<a href="#enableGrid">enableGrid</a><span class="type-signature"> : boolean</span> </h3>
  117. <div class="description">
  118. <p>If set to <code>true</code>, a grid will appear when panning operation is being performed
  119. (desktop interaction only).</p>
  120. <p>Default is <code>false</code>.</p>
  121. </div>
  122. </div>
  123. <div class="member">
  124. <h3 class="name" id="enablePan" translate="no">.<a href="#enablePan">enablePan</a><span class="type-signature"> : boolean</span> </h3>
  125. <div class="description">
  126. <p>Enable or disable camera panning.</p>
  127. <p>Default is <code>true</code>.</p>
  128. </div>
  129. </div>
  130. <div class="member">
  131. <h3 class="name" id="enableRotate" translate="no">.<a href="#enableRotate">enableRotate</a><span class="type-signature"> : boolean</span> </h3>
  132. <div class="description">
  133. <p>Enable or disable camera rotation.</p>
  134. <p>Default is <code>true</code>.</p>
  135. </div>
  136. </div>
  137. <div class="member">
  138. <h3 class="name" id="enableZoom" translate="no">.<a href="#enableZoom">enableZoom</a><span class="type-signature"> : boolean</span> </h3>
  139. <div class="description">
  140. <p>Enable or disable camera zoom.</p>
  141. <p>Default is <code>true</code>.</p>
  142. </div>
  143. </div>
  144. <div class="member">
  145. <h3 class="name" id="focusAnimationTime" translate="no">.<a href="#focusAnimationTime">focusAnimationTime</a><span class="type-signature"> : number</span> </h3>
  146. <div class="description">
  147. <p>Duration of focus animations in ms.</p>
  148. <p>Default is <code>500</code>.</p>
  149. </div>
  150. </div>
  151. <div class="member">
  152. <h3 class="name" id="maxDistance" translate="no">.<a href="#maxDistance">maxDistance</a><span class="type-signature"> : number</span> </h3>
  153. <div class="description">
  154. <p>How far you can dolly out. For perspective cameras only.</p>
  155. <p>Default is <code>Infinity</code>.</p>
  156. </div>
  157. </div>
  158. <div class="member">
  159. <h3 class="name" id="maxFov" translate="no">.<a href="#maxFov">maxFov</a><span class="type-signature"> : number</span> </h3>
  160. <div class="description">
  161. <p>The maximum FOV in degrees.</p>
  162. <p>Default is <code>90</code>.</p>
  163. </div>
  164. </div>
  165. <div class="member">
  166. <h3 class="name" id="maxZoom" translate="no">.<a href="#maxZoom">maxZoom</a><span class="type-signature"> : number</span> </h3>
  167. <div class="description">
  168. <p>How far you can zoom out. For orthographic cameras only.</p>
  169. <p>Default is <code>Infinity</code>.</p>
  170. </div>
  171. </div>
  172. <div class="member">
  173. <h3 class="name" id="minDistance" translate="no">.<a href="#minDistance">minDistance</a><span class="type-signature"> : number</span> </h3>
  174. <div class="description">
  175. <p>How far you can dolly in. For perspective cameras only.</p>
  176. <p>Default is <code>0</code>.</p>
  177. </div>
  178. </div>
  179. <div class="member">
  180. <h3 class="name" id="minFov" translate="no">.<a href="#minFov">minFov</a><span class="type-signature"> : number</span> </h3>
  181. <div class="description">
  182. <p>The minimum FOV in degrees.</p>
  183. <p>Default is <code>5</code>.</p>
  184. </div>
  185. </div>
  186. <div class="member">
  187. <h3 class="name" id="minZoom" translate="no">.<a href="#minZoom">minZoom</a><span class="type-signature"> : number</span> </h3>
  188. <div class="description">
  189. <p>How far you can zoom in. For orthographic cameras only.</p>
  190. <p>Default is <code>0</code>.</p>
  191. </div>
  192. </div>
  193. <div class="member">
  194. <h3 class="name" id="mouseActions" translate="no">.<a href="#mouseActions">mouseActions</a><span class="type-signature"> : Array.&lt;Object></span> </h3>
  195. <div class="description">
  196. <p>Holds the mouse actions of this controls. This property is maintained by the methods
  197. <code>setMouseAction()</code> and <code>unsetMouseAction()</code>.</p>
  198. </div>
  199. </div>
  200. <div class="member">
  201. <h3 class="name" id="radiusFactor" translate="no">.<a href="#radiusFactor">radiusFactor</a><span class="type-signature"> : number</span> </h3>
  202. <div class="description">
  203. <p>The size of the gizmo relative to the screen width and height.</p>
  204. <p>Default is <code>0.67</code>.</p>
  205. </div>
  206. </div>
  207. <div class="member">
  208. <h3 class="name" id="rotateSpeed" translate="no">.<a href="#rotateSpeed">rotateSpeed</a><span class="type-signature"> : number</span> </h3>
  209. <div class="description">
  210. <p>Speed of rotation.</p>
  211. <p>Default is <code>1</code>.</p>
  212. </div>
  213. </div>
  214. <div class="member">
  215. <h3 class="name" id="scaleFactor" translate="no">.<a href="#scaleFactor">scaleFactor</a><span class="type-signature"> : number</span> </h3>
  216. <div class="description">
  217. <p>The scaling factor used when performing zoom operation.</p>
  218. <p>Default is <code>1.1</code>.</p>
  219. </div>
  220. </div>
  221. <div class="member">
  222. <h3 class="name" id="scene" translate="no">.<a href="#scene">scene</a><span class="type-signature"> : <a href="Scene.html">Scene</a></span> </h3>
  223. <div class="description">
  224. <p>The scene rendered by the camera. If not given, gizmos cannot be shown.</p>
  225. <p>Default is <code>null</code>.</p>
  226. </div>
  227. </div>
  228. <div class="member">
  229. <h3 class="name" id="target" translate="no">.<a href="#target">target</a><span class="type-signature"> : <a href="Vector3.html">Vector3</a></span> </h3>
  230. <div class="description">
  231. <p>The control's focus point.</p>
  232. </div>
  233. </div>
  234. <div class="member">
  235. <h3 class="name" id="wMax" translate="no">.<a href="#wMax">wMax</a><span class="type-signature"> : number</span> </h3>
  236. <div class="description">
  237. <p>Maximum angular velocity allowed on rotation animation start.</p>
  238. <p>Default is <code>20</code>.</p>
  239. </div>
  240. </div>
  241. <h2 class="subsection-title">Methods</h2>
  242. <h3 class="name name-method" id="activateGizmos" translate="no">.<a href="#activateGizmos">activateGizmos</a><span class="signature">( isActive : <span class="param-type">boolean</span> )</span> </h3>
  243. <div class="method">
  244. <div class="description">
  245. <p>Makes rotation gizmos more or less visible.</p>
  246. </div>
  247. <table class="params">
  248. <tbody>
  249. <tr>
  250. <td class="name">
  251. <strong>isActive</strong>
  252. </td>
  253. <td class="description last">
  254. <p>If set to <code>true</code>, gizmos are more visible.</p>
  255. </td>
  256. </tr>
  257. </tbody>
  258. </table>
  259. </div>
  260. <h3 class="name name-method" id="copyState" translate="no">.<a href="#copyState">copyState</a><span class="signature">()</span> </h3>
  261. <div class="method">
  262. <div class="description">
  263. <p>Copy the current state to clipboard (as a readable JSON text).</p>
  264. </div>
  265. </div>
  266. <h3 class="name name-method" id="disposeGrid" translate="no">.<a href="#disposeGrid">disposeGrid</a><span class="signature">()</span> </h3>
  267. <div class="method">
  268. <div class="description">
  269. <p>Removes the grid from the scene.</p>
  270. </div>
  271. </div>
  272. <h3 class="name name-method" id="getRaycaster" translate="no">.<a href="#getRaycaster">getRaycaster</a><span class="signature">()</span><span class="type-signature"> : <a href="Raycaster.html">Raycaster</a></span> </h3>
  273. <div class="method">
  274. <div class="description">
  275. <p>Returns the raycaster that is used for user interaction. This object is shared between all
  276. instances of <code>ArcballControls</code>.</p>
  277. </div>
  278. <dl class="details">
  279. <dt class="tag-returns"><strong>Returns:</strong> The internal raycaster.</dt>
  280. </dl>
  281. </div>
  282. <h3 class="name name-method" id="pasteState" translate="no">.<a href="#pasteState">pasteState</a><span class="signature">()</span> </h3>
  283. <div class="method">
  284. <div class="description">
  285. <p>Set the controls state from the clipboard, assumes that the clipboard stores a JSON
  286. text as saved from <code>copyState()</code>.</p>
  287. </div>
  288. </div>
  289. <h3 class="name name-method" id="reset" translate="no">.<a href="#reset">reset</a><span class="signature">()</span> </h3>
  290. <div class="method">
  291. <div class="description">
  292. <p>Resets the controls.</p>
  293. </div>
  294. </div>
  295. <h3 class="name name-method" id="saveState" translate="no">.<a href="#saveState">saveState</a><span class="signature">()</span> </h3>
  296. <div class="method">
  297. <div class="description">
  298. <p>Saves the current state of the control. This can later be recover with <code>reset()</code>.</p>
  299. </div>
  300. </div>
  301. <h3 class="name name-method" id="setCamera" translate="no">.<a href="#setCamera">setCamera</a><span class="signature">( camera : <span class="param-type"><a href="Camera.html">Camera</a></span> )</span> </h3>
  302. <div class="method">
  303. <div class="description">
  304. <p>Sets the camera to be controlled. Must be called in order to set a new camera to be controlled.</p>
  305. </div>
  306. <table class="params">
  307. <tbody>
  308. <tr>
  309. <td class="name">
  310. <strong>camera</strong>
  311. </td>
  312. <td class="description last">
  313. <p>The camera to be controlled.</p>
  314. </td>
  315. </tr>
  316. </tbody>
  317. </table>
  318. </div>
  319. <h3 class="name name-method" id="setGizmosVisible" translate="no">.<a href="#setGizmosVisible">setGizmosVisible</a><span class="signature">( value : <span class="param-type">boolean</span> )</span> </h3>
  320. <div class="method">
  321. <div class="description">
  322. <p>Sets gizmos visibility.</p>
  323. </div>
  324. <table class="params">
  325. <tbody>
  326. <tr>
  327. <td class="name">
  328. <strong>value</strong>
  329. </td>
  330. <td class="description last">
  331. <p>Value of gizmos visibility.</p>
  332. </td>
  333. </tr>
  334. </tbody>
  335. </table>
  336. </div>
  337. <h3 class="name name-method" id="setMouseAction" translate="no">.<a href="#setMouseAction">setMouseAction</a><span class="signature">( operation : <span class="param-type">'PAN' | 'ROTATE' | 'ZOOM' | 'FOV'</span>, mouse : <span class="param-type">0 | 1 | 2 | 'WHEEL'</span>, key : <span class="param-type">'CTRL' | 'SHIFT'</span> )</span><span class="type-signature"> : boolean</span> </h3>
  338. <div class="method">
  339. <div class="description">
  340. <p>Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of conflict, replaces the existing one.</p>
  341. </div>
  342. <table class="params">
  343. <tbody>
  344. <tr>
  345. <td class="name">
  346. <strong>operation</strong>
  347. </td>
  348. <td class="description last">
  349. <p>The operation to be performed ('PAN', 'ROTATE', 'ZOOM', 'FOV').</p>
  350. </td>
  351. </tr>
  352. <tr>
  353. <td class="name">
  354. <strong>mouse</strong>
  355. </td>
  356. <td class="description last">
  357. <p>A mouse button (0, 1, 2) or 'WHEEL' for wheel notches.</p>
  358. </td>
  359. </tr>
  360. <tr>
  361. <td class="name">
  362. <strong>key</strong>
  363. </td>
  364. <td class="description last">
  365. <p>The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed.</p>
  366. <p>Default is <code>null</code>.</p>
  367. </td>
  368. </tr>
  369. </tbody>
  370. </table>
  371. <dl class="details">
  372. <dt class="tag-returns"><strong>Returns:</strong> <code>true</code> if the mouse action has been successfully added, <code>false</code> otherwise.</dt>
  373. </dl>
  374. </div>
  375. <h3 class="name name-method" id="setTbRadius" translate="no">.<a href="#setTbRadius">setTbRadius</a><span class="signature">( value : <span class="param-type">number</span> )</span> </h3>
  376. <div class="method">
  377. <div class="description">
  378. <p>Sets gizmos radius factor and redraws gizmos.</p>
  379. </div>
  380. <table class="params">
  381. <tbody>
  382. <tr>
  383. <td class="name">
  384. <strong>value</strong>
  385. </td>
  386. <td class="description last">
  387. <p>Value of radius factor.</p>
  388. </td>
  389. </tr>
  390. </tbody>
  391. </table>
  392. </div>
  393. <h3 class="name name-method" id="unsetMouseAction" translate="no">.<a href="#unsetMouseAction">unsetMouseAction</a><span class="signature">( mouse : <span class="param-type">0 | 1 | 2 | 'WHEEL'</span>, key : <span class="param-type">'CTRL' | 'SHIFT'</span> )</span><span class="type-signature"> : boolean</span> </h3>
  394. <div class="method">
  395. <div class="description">
  396. <p>Remove a mouse action by specifying its mouse/key combination.</p>
  397. </div>
  398. <table class="params">
  399. <tbody>
  400. <tr>
  401. <td class="name">
  402. <strong>mouse</strong>
  403. </td>
  404. <td class="description last">
  405. <p>A mouse button (0, 1, 2) or 'WHEEL' for wheel notches.</p>
  406. </td>
  407. </tr>
  408. <tr>
  409. <td class="name">
  410. <strong>key</strong>
  411. </td>
  412. <td class="description last">
  413. <p>The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed.</p>
  414. <p>Default is <code>null</code>.</p>
  415. </td>
  416. </tr>
  417. </tbody>
  418. </table>
  419. <dl class="details">
  420. <dt class="tag-returns"><strong>Returns:</strong> <code>true</code> if the operation has been successfully removed, <code>false</code> otherwise.</dt>
  421. </dl>
  422. </div>
  423. <h2 class="subsection-title">Events</h2>
  424. <h3 class="name name-method" id="event:change" translate="no">.<a href="#event:change">change</a> </h3>
  425. <div class="method">
  426. <div class="description">
  427. <p>Fires when the camera has been transformed by the controls.</p>
  428. </div>
  429. <h5>Type:</h5>
  430. <ul>
  431. <li>
  432. <span class="param-type">Object</span>
  433. </li>
  434. </ul>
  435. </div>
  436. <h3 class="name name-method" id="event:end" translate="no">.<a href="#event:end">end</a> </h3>
  437. <div class="method">
  438. <div class="description">
  439. <p>Fires when an interaction has finished.</p>
  440. </div>
  441. <h5>Type:</h5>
  442. <ul>
  443. <li>
  444. <span class="param-type">Object</span>
  445. </li>
  446. </ul>
  447. </div>
  448. <h3 class="name name-method" id="event:start" translate="no">.<a href="#event:start">start</a> </h3>
  449. <div class="method">
  450. <div class="description">
  451. <p>Fires when an interaction was initiated.</p>
  452. </div>
  453. <h5>Type:</h5>
  454. <ul>
  455. <li>
  456. <span class="param-type">Object</span>
  457. </li>
  458. </ul>
  459. </div>
  460. <h2 class="subsection-title">Source</h2>
  461. <p>
  462. <a href="https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/ArcballControls.js" translate="no" target="_blank" rel="noopener">examples/jsm/controls/ArcballControls.js</a>
  463. </p>
  464. </article>
  465. </section>
  466. <script src="../scripts/linenumber.js"></script>
  467. <script src="../scripts/page.js"></script>
  468. </body>
  469. </html>
粤ICP备19079148号