Skip to main content

3D 模型

使用 three.add3dModel 建立 3D 模型後，開始操作 3D 模型。

新增 3D 模型後，即可進行屬性修改、路徑移動等操作：

const model = await map.three.add3dModel({
  id: '3d_model',
  url: 'https://example.com/model.gltf',
  type: 'gltf',
  coordinates: [121.5, 25.0, 0],
  // ......
});

屬性修改​

setCoordinates​

setCoordinates(coordinates)

設定 3D 物件座標。

參數

  • coordinates Array : 欲設定 3D 物件的座標。

範例

model.setCoordinates([121.5, 25.0, 0]);

setRotation​

setRotation(rotation)

設定 3D 物件旋轉角度。

warning

注意：是依照 three.add3dModel 時設定的 rotation 為基準，再去另行設定旋轉角。

參數

  • rotation Object : 欲設定 3D 物件的旋轉角度，格式為 { x: 0, y: 0, z: 0 }。

範例

const model = await map.three.add3dModel({
  // ......
  rotation: { x: 0, y: 0, z: 90 },
  // ......
});

/**
 * 以 add3dModel 設定的旋轉角度 { x: 0, y: 0, z: 90 } 為基準，
 * 再去另行旋轉角度 { x: 0, y: 0, z: 180 }，
 * 最終旋轉角度為 { x: 0, y: 0, z: 270 }。
 */
model.setRotation({ x: 0, y: 0, z: 180 });

setScale​

setScale(scale)

設定 3D 物件的縮放比例。

warning

注意：是依照 three.add3dModel 時設定的 scale 為基準，再去另行設定縮放比例。

參數

  • scale number | Object : 欲設定 3D 物件的縮放比例，格式可為數字或是 { x: 1, y: 1, z: 1 }。

範例

const model = await map.three.add3dModel({
  // ......
  scale: { x: 1, y: 1, z: 2 },
  // ......
});

/**
 * 以 add3dModel 設定的縮放比例 { x: 1, y: 1, z: 2 } 為基準，
 * 再去另行縮放 { x: 1, y: 1, z: 3 }，
 * 最終縮放比例為 { x: 1, y: 1, z: 6 }。
 */
model.setScale({ x: 1, y: 1, z: 3 });

路徑移動​

followPath​

followPath(options)

3D 物件沿著路徑移動。

參數

  • options Object : 路徑移動選項。

    名稱描述
    options.path Array路徑（必填）
    options.start number開始時間（選填），預設為 Date.now()
    options.duration number持續時間（必填），單位為毫秒
    options.trackHeading boolean模型是否面向路徑方向（選填），預設為 true
    options.curveOptions Object曲線選項，詳情參考 options.curveOptions
    options.onStart Function生命週期：開始時執行的回調函式
    options.onEnd Function生命週期：結束時執行的回調函式

  • options.curveOptions Object : 曲線選項。

    名稱描述
    curveOptions.closed boolean是否閉合（選填），預設為 false
    curveOptions.curveType string曲線類型（選填），可選值為 catmullrom、cubicbezier、quadraticbezier，預設為 catmullrom
    curveOptions.tension number張力，預設為 0.0

範例

model.followPath({
  path: [
    [121.5, 25.0, 0],
    [121.7, 25.0, 0],
    [121.7, 25.2, 0],
  ],
  start: Date.now(),
  duration: 10 * 1000,
  trackHeading: true,
  curveOptions: {
    closed: false,
    curveType: 'catmullrom',
    tension: 0.0,
  },
  onStart: () => {
    console.log('Animation Start');
  },
  onEnd: () => {
    console.log('Animation End');
  },
});

接續下一個路徑移動：

const path = [
  [121.5610, 25.0334, 0],
  [121.5690, 25.0334, 0],
];
const reversePath = [...path].reverse();

let isReverse = false;

async function run() {
  model.followPath({
    path: isReverse ? reversePath : path,
    start: Date.now(),
    duration: 3 * 1000,
    trackHeading: false,
    onEnd: () => {
      isReverse = !isReverse;
      run();
    },
  });
}

setPathScheduler​

setPathScheduler(options)

設定 3D 物件路徑的時程表。

參數

  • options Object : 路徑時程表選項。

    名稱描述
    options.schedule Array<Task>任務時程（必填），詳情參考 Task
    options.trackHeading boolean模型是否面向路徑方向（選填），預設為 true
    options.curveOptions Object曲線選項，詳情參考 options.curveOptions
    options.taskOnStart Function生命週期：每個任務開始時執行的回調函式
    options.taskOnEnd Function生命週期：每個任務結束時執行的回調函式
    options.scheduleOnStart Function生命週期：時程表開始時執行的回調函式
    options.scheduleOnEnd Function生命週期：時程表結束時執行的回調函式

  • options.curveOptions Object : 曲線選項。

    名稱描述
    curveOptions.closed boolean是否閉合（選填），預設為 false
    curveOptions.curveType string曲線類型（選填），可選值為 catmullrom、cubicbezier、quadraticbezier，預設為 catmullrom
    curveOptions.tension number張力，預設為 0.0

  • Task Object : 任務。

    名稱描述
    Task.id string任務 ID（選填），若是有需修改任務時程，則需要使用 Task.id
    Task.departure string出發時間（必填），格式為 'HH:mm:ss' 或是 'HH:mm'
    Task.arrival string到達時間（必填），格式為 'HH:mm:ss' 或是 'HH:mm'
    Task.path Array路徑（必填）

範例

function run(hour, minute) {
  model.setPathScheduler({
    trackHeading: false,
    schedule: [
      {
        id: 'task_1',
        departure: `${hour}:${minute}:00`,
        arrival: `${hour}:${minute}:10`,
        path: [
          [121.5610, 25.0334, 0],
          [121.5690, 25.0334, 0],
        ],
      },
      {
        id: 'task_2',
        departure: `${hour}:${minute}:15`,
        arrival: `${hour}:${minute}:25`,
        path: [
          [121.5690, 25.0334, 0],
          [121.5690, 25.0334, 500],
        ],
      },
      {
        id: 'task_3',
        departure: `${hour}:${minute}:30`,
        arrival: `${hour}:${minute}:40`,
        path: [
          [121.5690, 25.0334, 500],
          [121.5610, 25.0334, 500],
        ],
      },
      {
        id: 'task_4',
        departure: `${hour}:${minute}:45`,
        arrival: `${hour}:${minute}:55`,
        path: [
          [121.5610, 25.0334, 500],
          [121.5610, 25.0334, 0],
        ],
      },
    ],
    scheduleOnEnd: () => {
      const now = new Date();
      now.setMinutes(now.getMinutes() + 1);
      const hour = now.getHours().toString().padStart(2, '0');
      const minute = now.getMinutes().toString().padStart(2, '0');
      run(hour, minute);
    },
  }); 
}

const hour = new Date().getHours().toString().padStart(2, '0');
const minute = new Date().getMinutes().toString().padStart(2, '0');
run(hour, minute);

updatePathScheduler​

updatePathScheduler(schedule)

更新 3D 物件路徑時程。

參數

  • schedule Array<UpdatedTask> : 欲修改的路徑時程。

    名稱描述
    UpdatedTask.id string任務 ID（必填）
    UpdatedTask.departure string出發時間（必填），格式為 'HH:mm:ss' 或是 'HH:mm'
    UpdatedTask.arrival string到達時間（必填），格式為 'HH:mm:ss' 或是 'HH:mm'

範例

model.setPathScheduler({
  scheduler: [
    // ......
    {
      id: 'task_3',
      departure: '10:15:00',
      arrival: '10:20:00',
      path: [
        [121.5, 25.0, 0],
        [121.6, 25.0, 0],
      ],
    },
    // ......
  ],
  // ......
});

model.updatePathScheduler([
  {
    id: 'task_3',
    departure: '10:15:00',
    arrival: '10:22:00',
  },
]);