Photo Sphere Viewer 中实现3D Marker拖拽功能的技术解析

背景介绍

Photo Sphere Viewer 是一个功能强大的全景图片查看器，它允许开发者在360度全景环境中放置标记点（Marker）。在实际应用中，我们经常需要实现Marker的拖拽功能，让用户能够自由调整标记点的位置。

二维坐标与三维空间的转换挑战

许多开发者初次尝试实现Marker拖拽时，会直接监听DOM元素的鼠标事件，获取二维平面坐标后进行移动。这种方法虽然简单，但存在明显问题：

1. 全景环境是三维球面投影到二维平面
2. 简单的平面坐标转换会导致Marker位置偏移
3. 无法正确处理全景图片的边缘和极点区域

正确的实现方案

核心思路

1. 拦截拖拽事件获取屏幕坐标
2. 使用内置工具将屏幕坐标转换为球面坐标
3. 更新Marker的三维位置

关键技术点

1. 坐标系统转换

Photo Sphere Viewer 提供了 dataHelper 工具类，其中包含多种坐标转换方法：

• viewerCoordsToSphericalCoords：将屏幕坐标转换为球面坐标（yaw/pitch）
• sphericalCoordsToViewerCoords：将球面坐标转换为屏幕坐标

2. 拖拽事件处理

建议使用以下事件处理流程：

1. 监听 pointerdown 事件开始拖拽
2. 在 pointermove 事件中计算新位置
3. 在 pointerup 事件结束拖拽

3. Marker位置更新

使用 markersPlugin.updateMarker 方法更新Marker的实际位置，而不是直接修改DOM元素的样式。

完整实现示例

function setupMarkerDrag(viewer, markerId) {
  const markersPlugin = viewer.getPlugin('markers');
  const markerElement = document.getElementById(`psv-marker-${markerId}`);
  
  let isDragging = false;
  let startX, startY;
  
  markerElement.addEventListener('pointerdown', (e) => {
    isDragging = true;
    startX = e.clientX;
    startY = e.clientY;
    e.stopPropagation();
    e.preventDefault();
  });
  
  document.addEventListener('pointermove', (e) => {
    if (!isDragging) return;
    
    const dx = e.clientX - startX;
    const dy = e.clientY - startY;
    
    // 获取当前Marker位置
    const marker = markersPlugin.getMarker(markerId);
    const currentPos = marker.position;
    
    // 转换为屏幕坐标
    const screenPos = viewer.dataHelper.sphericalCoordsToViewerCoords(currentPos);
    
    // 计算新位置
    const newScreenPos = {
      x: screenPos.x + dx,
      y: screenPos.y + dy
    };
    
    // 转换回球面坐标
    const newSphericalPos = viewer.dataHelper.viewerCoordsToSphericalCoords(newScreenPos);
    
    // 更新Marker位置
    markersPlugin.updateMarker({
      id: markerId,
      position: newSphericalPos
    });
    
    startX = e.clientX;
    startY = e.clientY;
    
    e.preventDefault();
  });
  
  document.addEventListener('pointerup', () => {
    isDragging = false;
  });
}

注意事项

1. 边界处理：需要考虑全景图片的边缘情况，防止Marker位置异常
2. 性能优化：频繁的坐标转换和更新可能影响性能，建议适当节流
3. 用户体验：可以添加拖拽时的视觉反馈，如改变光标样式或Marker外观

总结

在Photo Sphere Viewer中实现Marker拖拽功能，关键在于正确处理二维屏幕坐标与三维球面坐标之间的转换。通过使用viewer提供的内置工具方法，我们可以避免复杂的数学计算，实现准确、流畅的拖拽体验。这种方法不仅适用于简单的标记点移动，也可扩展用于更复杂的交互场景。