Skip to main content

實例方法

使用 mapThree.prototype.three 創建 3D 圖層。

3D圖層操作

實例方法描述
add3dLayer新增 3D 圖層。
remove3dLayer移除 3D 圖層。

3D物件操作

實例方法描述
add3dModel新增 3D 模型。注意：模型新增為非同步操作。
add3dLine新增 3D 線條。
add3dDashLine新增 3D 虛線。
add3dMeasureLine新增 3D 測量線。
get3dObjectById使用 ID 獲取 3D 物件。
remove3dObjectById使用 ID 移除 3D 物件。
remove3dObject移除 3D 物件。
detect3dObject偵測 3D 物件。

鏡頭操作

實例方法描述
fixedCameraToModel將鏡頭鎖定在模型上。
releaseCamera釋放鏡頭。

3D圖層操作​

add3dLayer​

add3dLayer(options, beforeLayerId)

新增 3D 圖層。

參數

  • options Object: 要設定的圖層參數。

    參數描述
    options.id string圖層 ID（必填）。
    options.minzoom number最小縮放 (0-24)（選填），當縮放級別小於 minzoom，圖層將隱藏，預設為 12
    options.maxzoom number最大縮放 (0-24)（選填），當縮放級別大於 maxzoom，圖層將隱藏，預設為 24

  • beforeLayerId string : 插入在指定圖層之前（選填），預設為 undefined。

範例

map.three.add3dLayer({
  id: '3d_layer',
  minzoom: 0,
  maxzoom: 24,
}, 'ohter_layer');

remove3dLayer​

remove3dLayer(id)

移除 3D 圖層。

參數

  • id string : 欲移除的圖層 ID。

範例

map.three.remove3dLayer('3d_layer');

3D物件操作​

add3dModel​

add3dModel(options)

新增 3D 模型。注意：模型新增為非同步操作。

參數

  • options Object：要設定的模型參數。

    名稱描述
    options.layerId string圖層 ID（選填），預設為 'kw_3d_layer'。如果找不到對應的圖層，將自動新增。若需自訂 minzoom、maxzoom 或 beforeLayerId，請使用 three.add3dLayer() 手動建立圖層
    options.id string模型 ID（選填），預設使用 UUID
    options.obj string模型檔案（必填），可使用 URL 或是 Three.js Object3D
    options.type string模型檔案類型（選填），可設定為 'gltf'、'fbx'、'dae'，若使用 Three.js Object3D 則免填，預設為 'gltf'
    options.coordinates array三維座標（必填）
    options.anchor string錨點（選填），可設定為 'auto'、'top'、'bottom'、'left'、'right'、'center'、'top-left'、'top-right'、'bottom-left'、'bottom-right'，預設為 'auto'
    options.scale Object縮放比例（選填），可填數字或是物件，預設為 { x: 1, y: 1, z: 1 }
    options.rotation Object旋轉角度（選填），預設為 { x: 0, y: 0, z: 0 }
    options.adjustment Object位置調整（選填），預設為 { x: 0, y: 0, z: 0 }
    options.hideWhenOutOfBounds boolean超出視窗時隱藏（選填），預設為 false

回傳

Promise<Object> : 3D 模型，為非同步操作，詳情請看 3D 模型。

範例

const model = await map.three.add3dModel({
  layerId: '3d_layer',
  id: '3d_model',
  obj: 'https://kw3dmap.autoking.com.tw/kwmap/assets/demo/gltf/tw01.glb',
  type: 'gltf',
  coordinates: [121.565067045142, 25.0334249633834, 0],
  anchor: 'auto',
  scale: { x: 1, y: 1, z: 1 },
  rotation: { x: 0, y: 0, z: 180 },
  adjustment: { x: 0, y: 0, z: 0 },
  hideWhenOutOfBounds: true,
});

使用 URL 新增 3D 模型：

const model = await map.three.add3dModel({
  // ......
  obj: 'https://example.com/model.gltf',
  type: 'gltf',
  // ......
});

使用 Three.js Object3D 新增 3D 模型：

const geometry = new THREE.BoxGeometry(20, 20, 20);
const material = new THREE.MeshBasicMaterial({ color: '#DD0000' });
const mesh = new THREE.Mesh(geometry, material);

const model = await map.three.add3dModel({
  // ......
  obj: mesh,
  // ......
});

add3dLine​

add3dLine(options)

新增 3D 線條。

參數

  • options Object：要設定的線條參數。

    名稱描述
    options.layerId string圖層 ID（選填），預設為 'kw_3d_layer'。如果找不到對應的圖層，將自動新增。若需自訂 minzoom、maxzoom 或 beforeLayerId，請使用 three.add3dLayer() 手動建立圖層
    options.id string線條 ID（選填），預設使用 UUID
    options.coordinates array線條的三維座標（必填）
    options.color string顏色（選填），預設為 '#000000'
    options.opacity number透明度（選填），預設為 1
    options.width number寬度（選填），預設為 3
    options.zCoordinate numberZ 座標（選填），若填入則會將所有座標的 Z 座標設為此值，預設為 undefined
    options.hideWhenOutOfBounds boolean超出視窗時隱藏（選填），預設為 false

回傳

Object : 3D 線條。

範例

const line = map.three.add3dLine({
  layerId: '3d_layer',
  id: '3d_line',
  coordinates: [
    [121.5594, 25.0400, 100],
    [121.5694, 25.0400, 300],
    [121.5644, 25.0370, 0],
  ],
  color: '#DD0000',
  opacity: 1,
  width: 10,
  hideWhenOutOfBounds: true,
});

個別設定 Z 座標：

const line = map.three.add3dLine({
  // ......
  coordinates: [
    [121.5, 25.0, 50],
    [121.6, 25.1, 100],
    [121.7, 25.2, 50],
  ],
  // ......
});

使用統一 Z 座標：

const line = map.three.add3dLine({
  // ......
  coordinates: [
    [121.5, 25.0],
    [121.6, 25.1],
    [121.7, 25.2],
  ],
  zCoordinate: 200,
  // ......
});

add3dDashLine​

add3dDashLine(options)

新增 3D 虛線。

參數

  • options Object：要設定的虛線參數。

    名稱描述
    options.layerId string圖層 ID（選填），預設為 'kw_3d_layer'。如果找不到對應的圖層，將自動新增。若需自訂 minzoom、maxzoom 或 beforeLayerId，請使用 three.add3dLayer() 手動建立圖層
    options.id string虛線 ID（選填），預設使用 UUID
    options.coordinates array虛線的三維座標（必填）
    options.color string顏色（選填），預設為 '#000000'
    options.opacity number透明度（選填），預設為 1
    options.width number寬度（選填），預設為 3
    options.zCoordinate numberZ 座標（選填），若填入則會將所有座標的 Z 座標設為此值，預設為 undefined
    options.dashSize number虛線大小（選填），預設為 1
    options.gapSize number虛線間隔（選填），預設為 1
    options.hideWhenOutOfBounds boolean超出視窗時隱藏（選填），預設為 false

回傳

Object : 3D 虛線。

範例

const line = map.three.add3dDashLine({
  layerId: '3d_layer',
  id: '3d_line',
  coordinates: [
    [121.5594, 25.0400, 100],
    [121.5694, 25.0400, 300],
    [121.5644, 25.0370, 0],
  ],
  color: '#DD0000',
  opacity: 1,
  width: 10,
  dashSize: 1.0,
  gapSize: 1.0,
  hideWhenOutOfBounds: true,
});

個別設定 Z 座標：

const line = map.three.add3dDashLine({
  // ......
  coordinates: [
    [121.5, 25.0, 50],
    [121.6, 25.1, 100],
    [121.7, 25.2, 50],
  ],
  // ......
});

使用統一 Z 座標：

const line = map.three.add3dDashLine({
  // ......
  coordinates: [
    [121.5, 25.0],
    [121.6, 25.1],
    [121.7, 25.2],
  ],
  zCoordinate: 200,
  // ......
});

add3dMeasureLine​

add3dMeasureLine(options)

新增 3D 測量線。

參數

  • options Object：要設定的虛線參數。

    名稱描述
    options.layerId string圖層 ID（選填），預設為 'kw_3d_layer'。如果找不到對應的圖層，將自動新增。若需自訂 minzoom、maxzoom 或 beforeLayerId，請使用 three.add3dLayer() 手動建立圖層
    options.id string測量線 ID（選填），預設使用 UUID
    options.start Array起點三維座標（必填）
    options.end Array終點三維座標（必填）
    options.lineColor string線條顏色（選填），預設為 '#613BFB'
    options.lineOpacity number線條透明度（選填），預設為 1
    options.lineWidth number線條寬度（選填），預設為 5
    options.labelColor string標籤顏色（選填），預設為 '#FC2B5F'
    options.labelFontSize string標籤字型大小（選填），預設為 '16px'
    options.hideWhenOutOfBounds boolean超出視窗時隱藏（選填），預設為 false

回傳

Object : 3D 測量線。

範例

const line = map.three.add3dMeasureLine({
  layerId: '3d_layer',
  id: '3d_measure_line',
  start: [121.5544, 25.0400, 50],
  end: [121.5744, 25.0400, 400],
  lineColor: '#613BFB',
  lineOpacity: 1,
  lineWidth: 5,
  labelColor: '#FC2B5F',
  labelFontSize: '16px',
  hideWhenOutOfBounds: false,
});

get3dObjectById​

get3dObjectById(id)

使用 ID 獲取 3D 物件。

參數

  • id string : 3D 物件 ID。

回傳

Object | null : 3D 物件或是空值。

範例

const object = map.three.get3dObjectById('3d_model');

remove3dObjectById​

remove3dObjectById(id)

使用 ID 移除 3D 物件。

參數

  • id string : 3D 物件 ID。

範例

map.three.remove3dObjectById('3d_model');

remove3dObject​

remove3dObject(object)

移除 3D 物件。

參數

  • object Object : 3D 物件。

範例

const model = await map.three.add3dModel({
  // ......
});

map.three.remove3dObject(model);

detect3dObject​

detect3dObject(point)

偵測 3D 物件。

參數

  • point Array：canvas 座標。

回傳

Object | null：3D 物件或是空值。

範例

function mapOnClick({ point }) {
  const object = map.three.detect3dObject(point);
  if (object) {
    alert(`Click on 3D model`);
  }
}

map.on('click', mapOnClick);

鏡頭操作​

fixedCameraToModel​

fixedCameraToModel(options)

將鏡頭鎖定在模型上。

參數

  • options Object：設定的參數。

    名稱描述
    options.model Object模型（必填）
    options.rotateWithDirection boolean是否隨著運動方向旋轉（選填），預設為 false
    options.releaseCameraOnClick boolean點選地圖後釋放鏡頭（選填），預設為 false

範例

map.three.fixedCameraToModel({
  model: model,
  rotateWithDirection: false,
  releaseCameraOnClick: false,
});

releaseCamera​

releaseCamera()

釋放鏡頭。

範例

map.three.releaseCamera();