# tiles

提供与 `3d-tiles-renderer` 和地理空间数据的集成。主要导出 `ArcgisTilesRenderer`，可流式加载 ArcGIS Online 3D 瓦片并将地球重新定向到指定地理位置。

```typescript
import { ArcgisTilesRenderer } from 'u-space/plugins/tiles';

const arcgisTilesRenderer = new ArcgisTilesRenderer(viewer);

// 设置原点为经度、纬度、高度
arcgisTilesRenderer.invalidate(120.002269, 30.284849, 4);

// 瓦片持续流式加载，使用 always 模式
viewer.frameloop = 'always';

arcgisTilesRenderer.enable();

// 经纬高转场景世界坐标
const position = arcgisTilesRenderer.lonLatHeightToPosition(120.002269, 30.284849, 8);

// 场景世界坐标转经纬高
const location = arcgisTilesRenderer.positionToLonLatHeight(position);
```

**方法：**

| 方法 | 说明 |
| :--- | :--- |
| `invalidate(lon, lat, alt)` | 将瓦片原点设置为指定的 WGS84 经纬高。`lon`、`lat` 使用度，`alt` 使用米。可多次调用。返回一个取消订阅的函数。 |
| `lonLatHeightToPosition(lon, lat, height?, target?)` | 将 WGS84 经纬高转换为当前场景的世界坐标。`lon`、`lat` 使用度，`height` 使用米，返回 `Vector3`。 |
| `positionToLonLatHeight(position, target?)` | 将当前场景的世界坐标转换为 WGS84 经纬高，返回 `{ lon, lat, height }`。`lon`、`lat` 使用度，`height` 使用米。 |
| `enable()` | 将瓦片添加到场景并启动更新循环。 |
| `disable()` | 从场景中移除瓦片并暂停更新循环。 |
| `dispose()` | 禁用并完全释放瓦片渲染器。 |

## 坐标转换

`invalidate(lon, lat, alt)` 会通过 `3d-tiles-renderer` 的 `ReorientationPlugin` 把指定 WGS84 经纬高移动到场景原点。重定位完成后，默认场景轴向为：

- `+Y`：高度方向（Up）
- `+Z`：北向（North）
- `+X`：西向（West），东向为 `-X`

`lonLatHeightToPosition()` 和 `positionToLonLatHeight()` 复用瓦片当前的 `group.matrixWorld` 与 WGS84 椭球坐标，适合在 GIS 点位、POI、业务模型和 Three.js 场景世界坐标之间互转。

```typescript
import { Vector3 } from 'three/webgpu';

const poiPosition = arcgisTilesRenderer.lonLatHeightToPosition(120.0024, 30.285, 12);
poi.position.copy(poiPosition);

const worldPosition = object.getWorldPosition(new Vector3());
const { lon, lat, height } = arcgisTilesRenderer.positionToLonLatHeight(worldPosition);
```

传给 `positionToLonLatHeight()` 的 `position` 必须是场景世界坐标。如果坐标来自某个对象的局部空间，先通过 `object.localToWorld(localPosition)` 或 `object.getWorldPosition()` 转成世界坐标。

如果在瓦片 root tileset 加载前调用 `invalidate()`，会先基于当前 WGS84 椭球立即应用一次重定位，保证后续坐标转换可用；root tileset 加载完成后会按最终 ellipsoid 再应用一次。