Merge pull request #11 from lec-org/feat-api

Feat api
lec-org · Oct 11, 2023 · c0ad6db · c0ad6db
2 parents a90520c + 0cfb18b
commit c0ad6db
Show file tree

Hide file tree

Showing 11 changed files with 214 additions and 80 deletions.
diff --git a/examples/vue/src/App.vue b/examples/vue/src/App.vue
@@ -10,24 +10,32 @@
 
   const el = ref()
   onMounted(() => {
-    const { scene, renderer, camera, mountTo, refresh } = lec3d.init()
+    const { scene, renderer, camera, mountTo, refresh, addControls } = lec3d.init({})
     // el.value.appendChild(renderer.domElement)
 
+    addControls({
+      callback: (scene, camera) => {
+        console.log(scene, camera)
+      }
+    })
+
     lec3d.loadGLTF({ 
       modelPath: '3d_model/scene.gltf', 
-      options: { scale: 30  }, 
+      options: {
+        scale: 30,
+        position: {
+          x: 100,
+          y: 100
+        },
+        rotation: {
+          x: '30',
+          z: -0.5
+        },
+      }, 
       callback: (gltf, model) => {
         scene.add(model)
     }})
 
-    lec3d.createControls({
-      scene,
-      camera,
-      element: renderer.domElement,
-      callback: (scene, camera) => {
-        console.log(scene, camera)
-      }
-    })
 
     mountTo(el.value)
   })

diff --git a/index.d.ts b/index.d.ts
@@ -18644,6 +18644,11 @@ interface CommonModelOptions {
         y?: number;
         z?: number;
     };
+    rotation?: {
+        x?: number | string;
+        y?: number | string;
+        z?: number | string;
+    };
 }
 
 // Type definitions for three 0.156
@@ -19441,12 +19446,46 @@ interface Get3dClickEventTargetsParams {
     camera: Camera;
     event: MouseEvent;
 }
-interface CreateControlsParams {
-    scene: Scene;
-    camera: Camera;
-    element: HTMLElement | null;
+interface AddControlsParams {
     callback?: (scene: Scene, camera: Camera) => void;
 }
+interface CreateAxesHelperParams {
+    length?: number;
+}
+interface CreateLightParams {
+    color?: number | string;
+    colorOpacity?: number;
+    ambientLightColor?: number | string;
+    ambientLightColorOpacity?: number;
+    directLightColor?: number | string;
+    directLightColorOpacity?: number;
+}
+interface CreateCameraParams {
+    width?: number;
+    height?: number;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lookAt?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+interface CreateRendererParams {
+    width?: number;
+    height?: number;
+    backgroundColor?: number | string;
+    backgroundColorOpacity?: number;
+}
+type InitParams = {
+    lightConfigs?: CreateLightParams;
+    cameraConfigs?: CreateCameraParams;
+    axesHelperConfigs?: CreateAxesHelperParams;
+    rendererConfigs?: CreateRendererParams;
+} | null;
 
 declare class KTX2Loader extends CompressedTextureLoader {
     constructor(manager?: LoadingManager);
@@ -19565,21 +19604,21 @@ interface GLTFLoaderPlugin {
 
 interface LoadGLTFParams {
     modelPath: string;
-    options: CommonModelOptions;
+    options?: CommonModelOptions;
     callback?: (gltf: GLTF, model: THREE.Group<THREE.Object3DEventMap>) => void;
 }
 
 declare const lec3d: {
     THREE: typeof THREE$1;
     loadGLTF: ({ modelPath, options, callback }: LoadGLTFParams) => void;
     get3dClickEventTargets: ({ scene, camera, event, }: Get3dClickEventTargetsParams) => Intersection<Object3D<Object3DEventMap>>[];
-    createControls: ({ scene, camera, element, callback, }: CreateControlsParams) => void;
-    init: () => {
+    init: (params: InitParams) => {
         renderer: WebGLRenderer;
         camera: PerspectiveCamera;
         scene: Scene;
         mountTo: (element: HTMLElement) => void;
         refresh: () => void;
+        addControls: ({ callback }: AddControlsParams) => void;
     };
 };
 

diff --git a/package.json b/package.json
@@ -29,8 +29,9 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lec-org/lec3d.git"
+    "url": "https://github.com/lec-org/lec3d.git"
   },
+  "homepage": "https://github.com/lec-org/lec3d",
   "license": "ISC",
   "devDependencies": {
     "@babel/core": "^7.23.0",

diff --git a/src/index.ts b/src/index.ts
@@ -1,13 +1,11 @@
-// 暂时先从这里导出
 import { loadGLTF } from "./model/index.js";
-import { get3dClickEventTargets, createControls, init } from "./scene/index.js";
+import { get3dClickEventTargets, init } from "./scene/index.js";
 import * as THREE from "three";
 
 const lec3d = {
   THREE,
   loadGLTF,
   get3dClickEventTargets,
-  createControls,
   init,
 };
 

diff --git a/src/model/index.ts b/src/model/index.ts
@@ -1,11 +1,12 @@
 import { GLTF } from "three/examples/jsm/loaders/GLTFLoader";
-// TODO: 当前先只实现导入 GLTF 文件，后面要用别的类型再加
-import * as THREE from "three";
+import { transferRotationValue } from "./utils.js";
+// TODO: 当前先只实现导入 GLTF 文件，后续再实现其他类型的文件
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { LoadGLTFParams } from "./type";
 // import { FBXLoader } from "three/examples/jsm/loaders/FBXLoader";
 // import { MTLLoader } from "three/examples/jsm/loaders/MTLLoader";
 // import { OBJLoader } from "three/examples/jsm/loaders/OBJLoader";
+import * as THREE from "three";
 
 /** 导入 GLTF 文件 */
 export const loadGLTF = ({ modelPath, options, callback }: LoadGLTFParams) => {
@@ -16,13 +17,19 @@ export const loadGLTF = ({ modelPath, options, callback }: LoadGLTFParams) => {
   gltfLoader.load(modelPath, (gltf: GLTF) => {
     const model = gltf.scene;
 
-    const x = options?.position?.x ?? 0;
-    const y = options?.position?.y ?? 0;
-    const z = options?.position?.z ?? 0;
+    const posX = options?.position?.x ?? 0;
+    const posY = options?.position?.y ?? 0;
+    const posZ = options?.position?.z ?? 0;
     const scale = options?.scale ?? 1;
+    const rotX = transferRotationValue(options?.rotation?.x);
+    const rotY = transferRotationValue(options?.rotation?.y);
+    const rotZ = transferRotationValue(options?.rotation?.z);
 
-    model.position.set(x, y, z);
+    model.position.set(posX, posY, posZ);
     model.scale.set(scale, scale, scale);
+    model.rotateX(rotX);
+    model.rotateY(rotY);
+    model.rotateZ(rotZ);
 
     callback?.(gltf, model);
   });

diff --git a/src/model/type.ts b/src/model/type.ts
@@ -3,6 +3,6 @@ import { CommonModelOptions } from "./../type";
 
 export interface LoadGLTFParams {
   modelPath: string;
-  options: CommonModelOptions;
+  options?: CommonModelOptions;
   callback?: (gltf: GLTF, model: THREE.Group<THREE.Object3DEventMap>) => void;
 }
diff --git a/src/model/utils.ts b/src/model/utils.ts
@@ -0,0 +1,13 @@
+/** 转换旋转参数:
+ *  1. 参数类型为 number -> 直接使用
+ *  2. 参数类型为 string -> 转换为角度, 然后再使用
+ */
+export const transferRotationValue = (param?: string | number): number => {
+  if (typeof param === "string") {
+    return (Math.PI / 180) * +param;
+  }
+  if (typeof param === "number") {
+    return param;
+  }
+  return 0;
+};
diff --git a/src/scene/index.ts b/src/scene/index.ts
@@ -1,4 +1,8 @@
-import { CreateControlsParams, Get3dClickEventTargetsParams } from "./type";
+import {
+  AddControlsParams,
+  Get3dClickEventTargetsParams,
+  InitParams,
+} from "./type";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 import * as THREE from "three";
 import {
@@ -11,22 +15,23 @@ import {
 } from "./utils.js";
 
 /** 创建基本三维场景 */
-export const init = () => {
+export const init = (params: InitParams) => {
+  // TODO: 完善 createScene 的自定义参数支持
   // 创建场景
   const scene = createScene();
   // 创建并添加光源
-  const light = createLight();
+  const light = createLight({ ...params?.lightConfigs });
   scene.add(light.ambientLight);
   // 创建辅助坐标轴
-  const axesHelper = createAxesHelper();
+  const axesHelper = createAxesHelper({ ...params?.axesHelperConfigs });
   // 创建透视相机
-  const camera = createCamera();
+  const camera = createCamera({ ...params?.cameraConfigs });
   // 创建渲染器
-  const renderer = createRenderer();
-  // 将所有内容加入场景
+  const renderer = createRenderer({ ...params?.rendererConfigs });
+  // 将上述创建的所有内容加入场景
   sceneAdd({
     scene,
-    content: [light.ambientLight, light.dirLight, axesHelper],
+    content: [light.ambientLight, light.directLight, axesHelper],
   });
 
   // 挂载
@@ -39,11 +44,20 @@ export const init = () => {
     renderer.render(scene, camera);
   };
 
+  // 添加控制, 使鼠标能够控制相机视角
+  const addControls = ({ callback }: AddControlsParams) => {
+    const controls = new OrbitControls(camera, renderer.domElement);
+    controls.addEventListener("change", () => {
+      callback?.(scene, camera);
+    });
+  };
+
   // 内部方法, 每一帧自动刷新
   const __autoRefresh = () => {
     refresh();
     window.requestAnimationFrame(__autoRefresh);
   };
+
   __autoRefresh();
 
   return {
@@ -52,6 +66,7 @@ export const init = () => {
     scene,
     mountTo,
     refresh,
+    addControls,
   };
 };
 
@@ -113,20 +128,3 @@ export const get3dClickEventTargets = ({
   // callback?.(targets);
   return targets;
 };
-
-/** 创建控制，如鼠标操作等 */
-export const createControls = ({
-  scene,
-  camera,
-  element,
-  callback,
-}: CreateControlsParams) => {
-  if (!element) {
-    throw "error: no container element!";
-  }
-  const controls = new OrbitControls(camera, element);
-  controls.addEventListener("change", () => {
-    // renderer.render(scene, camera);
-    callback?.(scene, camera);
-  });
-};
diff --git a/src/scene/type.ts b/src/scene/type.ts
@@ -21,14 +21,53 @@ export interface Get3dClickEventTargetsParams {
   event: MouseEvent;
 }
 
-export interface CreateControlsParams {
-  scene: Scene;
-  camera: Camera;
-  element: HTMLElement | null;
+export interface AddControlsParams {
   callback?: (scene: Scene, camera: Camera) => void;
 }
 
 export interface SceneAddParams {
   scene: Scene;
   content: Array<SceneItem> | SceneItem;
 }
+
+export interface CreateAxesHelperParams {
+  length?: number;
+}
+
+export interface CreateLightParams {
+  color?: number | string;
+  colorOpacity?: number;
+  ambientLightColor?: number | string;
+  ambientLightColorOpacity?: number;
+  directLightColor?: number | string;
+  directLightColorOpacity?: number;
+}
+
+export interface CreateCameraParams {
+  width?: number;
+  height?: number;
+  position?: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  lookAt?: {
+    x: number;
+    y: number;
+    z: number;
+  };
+}
+
+export interface CreateRendererParams {
+  width?: number;
+  height?: number;
+  backgroundColor?: number | string;
+  backgroundColorOpacity?: number;
+}
+
+export type InitParams = {
+  lightConfigs?: CreateLightParams;
+  cameraConfigs?: CreateCameraParams;
+  axesHelperConfigs?: CreateAxesHelperParams;
+  rendererConfigs?: CreateRendererParams;
+} | null;