javascript
/
three.js
同期ミラー https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
							<!DOCTYPE html>
<html lang="ko">

<head>
    <meta charset="utf-8">
    <base href="../../../" />
    <script src="page.js"></script>
    <link type="text/css" rel="stylesheet" href="page.css" />
</head>

<body>
    <h1>설치([name])</h1>

    <p>
        three.js는 [link:https://www.npmjs.com/ npm]을 포함한 빌드 툴에서 설치가 가능하고, CDN이나 static 호스팅으로 빠르게 사용이 가능합니다. 대부분의 경우 npm을
        통한 설치가 가장 좋은 선택입니다.
    </p>

    <p>
        어떤 방식을 선택하든, 같은 버전의 라이브러리에서 모든 파일을 동일하게 불러와야 합니다. 여러 소스에서 파일을 혼합해 가져오면 코드 중복이 일어나거나 비정상적으로 앱이 종료될 수 있습니다.
    </p>

    <p>
        three.js의 모든 메서드들은 ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent
        JavaScript: ECMAScript Modules])에 기반하고 있으며, 마지막 프로젝트에 필요한 부분만 불러오도록 할 것입니다.
    </p>

    <h2>npm으로 설치하기</h2>

    <p>
        [link:https://www.npmjs.com/package/three three] npm 모듈을 설치하려면, 프로젝트 폴더의 터미널을 열고 다음을 실행합니다.
    </p>

    <code>
		npm install three
		</code>

    <p>
        패키지가 다운로드 및 설치 될 것이며, 다음과 같이 코드에서 불러올 수 있을 것입니다.
    </p>

    <code>
		///////////////////////////////////////////////////////
		// Option 1: Import the entire three.js core library.
		import * as THREE from 'three';

		const scene = new THREE.Scene();


		///////////////////////////////////////////////////////
		// Option 2: Import just the parts you need.
		import { Scene } from 'three';

		const scene = new Scene();
		</code>

    <p>
        npm을 통해 설치할 때, 아마 대부분의 경우 모든 패키지를 한 자바스크립트 파일에 결합시켜주는
        [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool]을 사용할텐데, three.js는 모든 자바스크립트
        번들러에 호환되지만, 가장 널리 쓰이는 것은 [link:https://webpack.js.org/ webpack]일 것입니다.
    </p>

    <p>
        모든 속성들이 <em>three</em> 모듈에서 바로 불러와지는 것은 아닙니다. ("bare import"라고도 불리는). 다른 자주 쓰이는 라이브러리들, controls, loaders, post-processing effects 같은 것들은
[link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] 의 하위폴더에서 불러와야 합니다. 더 자세한 내용을 알아보려면, 아래 <em>내용</em>을 참고하세요.
    </p>

    <p>
    npm 모듈 [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent
        JavaScript: Installing with npm]에 대해 더 알아보기.
    </p>

    <h2>static hosting 및 CDN을 통한 설치</h2>

    <p>
        three.js 라이브러리는 빌드 시스템 없이도, 본인의 웹서버나 기존의 CDN에 파일을 올리지 않고도 사용할 수 있습니다. three.js 라이브러리는 ES 모듈에 기반하고있기 때문에, 모든 스크립트는 참조할 때 아래처럼 <em>type="module"</em>을 사용해야합니다.
    </p>

    <code>
&lt;script type="importmap">
    {
    "imports": {
        "three": "https://cdn.jsdelivr.net/npm/three@&lt;version&gt;/build/three.module.js"
    }
    }
&lt;/script>

&lt;script type="module">

    import * as THREE from 'three';

    const scene = new THREE.Scene();

&lt;/script>
</code>

    <h2>Addons</h2>

    <p>
        three.js는 3D 엔진의 주요 컴포넌트들에 초점을 두고 있습니다. 다른 여러 유용한 컴포넌트들 —
        controls, loaders, post-processing effects — 은
        [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] 폴더에 있습니다. 이들은 "예제"로 불리는데, 그대로 사용할 수도 있고,
        재조합 및 커스터마이징이 가능하기 때문입니다. 이 컴포넌트들은 언제나 코어 라이브러리와 상응하게 이루어져있으며, 이는 다른 비슷한 서드파티 패키지들이 다양한 사람들에 의해 유지보수되고, 최신버전 반영이 안되는 점과는 대비되는 점입니다.
    </p>

    <p>
        예제들은 각각 따로 <em>설치할</em> 필요는 없지만, 각각 <em>import</em>를 해 주어야 합니다.
        three.js가 npm을 통해 설치되었다면, [page:OrbitControls] 컴포넌트를 다음과 같이 불러올 수 있습니다.
    </p>


    <code>
		import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

		const controls = new OrbitControls( camera, renderer.domElement );
		</code>

    <p>
        three.js를 CDN으로 설치했다면, 다른 컴포넌트들도 동일한 CDN에서 설치 가능합니다.
    </p>

    <code>
&lt;script type="importmap">
    {
    "imports": {
        "three": "https://cdn.jsdelivr.net/npm/three@&lt;version&gt;/build/three.module.js",
        "three/addons/": "https://cdn.jsdelivr.net/npm/three@&lt;version&gt;/examples/jsm/"
    }
    }
&lt;/script>

&lt;script type="module">

    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

    const controls = new OrbitControls( camera, renderer.domElement );

&lt;/script>
</code>

    <p>
        모든 파일들의 버전을 동일하게 맞추는것이 무엇보다 중요합니다. 서로 다른 버전에서 import를 하거나, three.js 라이브러리 자체가 아닌 다른 버전의 예제를 사용하지 마세요.
    </p>

    <h2>양립성</h2>

    <h3>CommonJS 불러오기</h3>

    <p>
        대부분의 자바스크립트 번들러는 이제 ES 모듈을 기본적으로 지원하지만, 오래된 빌드 도구들은 그렇지 않을 수 있습니다.
        이 경우에, 번들러에 ES 모듈을 인식할 수 있도록 설정해줄 수 있습니다. 예를들어 [link:http://browserify.org/ Browserify] 는 [link:https://github.com/babel/babelify babelify] 플러그인을 불러오기만 하면 됩니다.
    </p>

    <h3>maps 불러오기</h3>

    <p>
        npm을 통해 설치하는 경우, 호스팅 및 CDN으로 설치했을 때와 import 경로가 다릅니다. 이 점은 양쪽의 사용자 모두에게 불편한 문제가 될 것이라는 점을 알고 있습니다.
        빌드 도구나 번들러를 사용하는 개발자들은 상대경로보다 단순한 패키지 구분자(ex: 'three')로 사용하기를 선호하지만 <em>examples/</em> 폴더의 파일들은
        <em>three.module.js</em>에 상대 경로를 사용하기 때문에 예상을 빗나가게 됩니다. 빌드 도구를 사용하지 않는 사람들 — 빠른 프로토타입 제작, 학습용도, 개인적 취향 — 도 마찬가지로 이러한 상대 경로를 싫어할 텐데,
        특정 폴더 구조가 필요하고, 전역 <em>THREE.*</em>를 사용하는 것보다 엄격하기 때문입니다.
    </p>

    <p>
        [link:https://github.com/WICG/import-maps import maps] 이 후에 활발하게 지원된다면 이러한 상대 경로들을 npm 패키지 이름, 'three'처럼 단순한 패키지 식별자로 변경할 예정입니다.
        이는 npm 패키지에서 주로 쓰이는 경로 작성법과 일치하고, 두 사용자군 모두에게 파일을 불러오는 데에 동일한 코드를 사용할 수 있게 해 줄 것입니다.
        빌드 도구를 사용하지 않는 것을 선호하는 사용자들에게도, 간단한 JSON 맵핑을 통해 CDN이나 직접 파일 폴더에서 불러오는 것을 가능하게 해 줄 것입니다.
        실험적 방법으로, [link:https://glitch.com/edit/#!/three-import-map?path=index.html import map
        example]처럼 map polyfill과 함께 import 해서 더 간단하게 사용해볼 수도 있습니다.
    </p>

    <h3>Node.js</h3>

    <p>
        Three.js는 웹 환경을 위해 만들어졌기 때문에, Node.js환경에서는 존재하지 않는 browser 객체와 DOM API에 의존적입니다. Node.js환경에서 사용한다면, 일부 문제는 [link:https://github.com/stackgl/headless-gl headless-gl]과 같은 심을 사용해서 해결하거나 [page:TextureLoader]와 같은 컴포넌트로 대안으로 사용하여 해결할 수 있습니다. 다른 DOM API는 이를 사용하는 코드와 깊게 얽혀있을 수 있으며, 해결하기가 더 어려울 수 있습니다. 우리는 Node.js환경을 지원하기 위한 간단하고 유지보수 가능한 풀리퀘스트를 환영합니다만 이슈를 먼저 열어 당신이 요청하려고하는 개선 코드에 대해 토론하는 것을 추천드립니다.
    </p>

    <p>
        `package.json`에 `{ “type”: “module” }` 을 추가해서 노드 프로젝트에서도 ES6 모듈을 사용할 수 있도록 활성화하세요.
    </p>

</body>

</html>