3d-tiles-renderer 中文文档教程

Question

3d-tiles-renderer

3D Tiles 格式 的 Three.js 渲染器实现。 渲染器支持大多数 3D Tiles 规范功能，但有少数例外。 有关哪些功能尚未实现的信息，请参阅问题#15。

如果图块集或几何图形未正确加载或渲染，请提出问题！ 添加和测试功能需要示例数据。

示例

具有多个切片集的 Dingo Gap Mars 数据集！

这里有所有选项的厨房水槽示例！

此处为自定义材质示例！

在此处渲染屏幕外图块的阴影！

在此处渲染 VR 示例！

从铯离子加载 3D 瓷砖！

Use

Installation

npm install 3d-tiles-renderer --save

Basic TilesRenderer

使用 3D Tile Set 设置基本应用程序。

import { TilesRenderer } from '3d-tiles-renderer';

// ... initialize three scene ...

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.setCamera( camera );
tilesRenderer.setResolutionFromRenderer( camera, renderer );
scene.add( tilesRenderer.group );

renderLoop();

function renderLoop() {

    requestAnimationFrame( renderLoop );

    // The camera matrix is expected to be up to date
    // before calling tilesRenderer.update
    camera.updateMatrixWorld();
    tilesRenderer.update();
    renderer.render( camera, scene );

}

Custom Material

使用自定义材料设置 3D Tile Set。

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.setCamera( camera );
tilesRenderer.setResolutionFromRenderer( camera, renderer );
tilesRenderer.onLoadModel = function ( scene ) {

    // create a custom material for the tile
    scene.traverse( c => {

        if ( c.material ) {

            c.originalMaterial = c.material;
            c.material = new MeshBasicMaterial();

        }

    } );

};

tilesRenderer.onDisposeModel = function ( scene ) {

    // dispose of any manually created materials
    scene.traverse( c => {

        if ( c.material ) {

            c.material.dispose();

        }

    } );

};
scene.add( tilesRenderer.group );

Multiple TilesRenderers with Shared Caches and Queues

使用共享 LRUCache 和 PriorityQueue 实例的多个图块渲染器来减少内存并正确确定下载的优先级。

// create multiple tiles renderers
const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.setCamera( camera );
tilesRenderer.setResolutionFromRenderer( camera, renderer );

const tilesRenderer2 = new TilesRenderer( './path/to/tileset2.json' );
tilesRenderer2.setCamera( camera );
tilesRenderer2.setResolutionFromRenderer( camera, renderer );

// set the second renderer to share the cache and queues from the first
tilesRenderer2.lruCache = tilesRenderer.lruCache;
tilesRenderer2.downloadQueue = tilesRenderer.downloadQueue;
tilesRenderer2.parseQueue = tilesRenderer.parseQueue;

// add them to the scene
scene.add( tilesRenderer.group );
scene.add( tilesRenderer2.group );

Adding DRACO Decompression Support

在以 B3DM 和 I3DM 格式传输的 GLTF 文件中添加对 DRACO 解压缩的支持。 可以使用相同的方法来添加对 KTX2 和 DDS 纹理的支持。

// Note the DRACO compression files need to be supplied via an explicit source.
// We use unpkg here but in practice should be provided by the application.
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath( 'https://unpkg.com/three@0.123.0/examples/js/libs/draco/gltf/' );

const loader = new GLTFLoader( tiles.manager );
loader.setDRACOLoader( dracoLoader );

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.manager.addHandler( /\.gltf$/, loader );

Loading from Cesium Ion

从 Cesium Ion 加载需要一些额外的离子 url 端点，以及一个临时的承载访问令牌。 在示例文件夹中的 ionExample.js 文件中可以找到完整示例。

设置所需的 assetId 以及您的 Ion AccessToken。 Cesium REST API 文档提供了更多阅读内容。

// fetch a temporary token for the Cesium Ion asset
const url = new URL( `https://api.cesium.com/v1/assets/${ assetId }/endpoint` );
url.searchParams.append( 'access_token', accessToken );

fetch( url, { mode: 'cors' } )
    .then( res => res.json() )
    .then( json => {

        url = new URL( json.url );

        const version = url.searchParams.get( 'v' );
        tiles = new TilesRenderer( url );
        tiles.fetchOptions.headers = {};
        tiles.fetchOptions.headers.Authorization = `Bearer ${json.accessToken}`;

        // Prefilter each model fetch by setting the cesium Ion version to the search
        // parameters of the url.
        tiles.onPreprocessURL = uri => {

            uri = new URL( uri );
            uri.searchParams.append( 'v', version );
            return uri;

        };

    } );

Render On Change

瓦片集和模型加载回调可用于检测数据何时更改以及需要新渲染的时间。

let needsRerender = true;
const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.onLoadTileSet = () => needsRerender = true;
tilesRenderer.onLoadModel = () => needsRerender = true;

function renderLoop() {

    requestAnimationFrame( renderLoop );
    if ( needsRerender ) {

        needsRerender = false;
        camera.updateMatrixWorld();
        tilesRenderer.update();
        renderer.render( camera, scene );

    }

}
renderLoop();

Read Batch Id and Batch Table Data

如何找到与网格关联的批次 ID 和批次表并读取数据。

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );

// ...checking intersections...

const intersects = raycaster.intersectObject( scene, true );
if ( intersects.length ) {

    const { face, object } = intersects[ 0 ];
    const batchidAttr = object.geometry.getAttribute( '_batchid' );

    if ( batchidAttr ) {

        // Traverse the parents to find the batch table.
        let batchTableObject = object;
        while ( ! batchTableObject.batchTable ) {

            batchTableObject = batchTableObject.parent;

        }

        // Log the batch data
        const batchTable = batchTableObject.batchTable;
        const hoveredBatchid = batchidAttr.getX( face.a );
        const batchData = batchTable.getData( 'BatchTableKey' );
        if ( batchData ) {

            console.log( batchData[ hoveredBatchid ] );

        }

    }

}

API

TilesRenderer

扩展 TilesRendererBase，可用于实现 3d其他引擎中的图块渲染器

.fetchOptions

fetchOptions = {} : Object

加载图块集和模型数据时传递给 fetch 的选项。

.errorTarget

errorTarget = 6 : Number

更新几何时要定位的目标屏幕空间错误（以像素为单位）。 如果图块具有低于此级别的屏幕空间错误，它们将不会呈现。 有关详细信息，请参阅 3d tiles 规范中的“几何错误”部分。

.errorThreshold

errorThreshold = Infinity : Number

用于计算阈值 errorTarget * errorThreshold 的值，高于该阈值的图块将不会加载或呈现。 这用于启用遍历以跳过加载和渲染远离相机当前屏幕空间错误要求的父图块。 如果 errorThreshold 设置为 Infinity，则将加载并渲染所有父图块。 如果将其设置为 0，则不会渲染任何父图块，只会加载正在渲染的图块。

请注意，如果相机位置显着放大或缩小，将此设置为 Infinity 以外的值可能会导致图块闪烁，如果渲染器更新以显示先前超出错误阈值的图块。 因此，此设置最适合相机移动受限的较小移动比例（例如真实世界移动速度）。

.maxDepth

maxDepth = Infinity : Number

瓦片将被加载和渲染的最大深度。 将其设置为 1 将只渲染根图块。 如果深度 maxDepth 处的图块是空图块，则将渲染下一组可见子图块。

.loadSiblings

loadSiblings = true : Boolean

如果为真，则所有同级图块也将被加载，以确保移动相机时的连贯性。 如果为 false，则只会加载当前查看的图块。

.displayActiveTiles

displayActiveTiles = false : Boolean

“活动磁贴”是那些已加载且可用但不一定可见的磁贴。 如果 loadSiblings 为真，则即使在相机视图之外，加载到图块集范围内的图块也将被视为活动。 这些图块可用于从相机投射光线或投射阴影。

作为优化，当前在相机视锥体中不可见的活动图块将从场景中移除。 将 displayActiveTiles 设置为 true 将使它们保持在场景中，以从不被 tiles 渲染器考虑的外部相机视图渲染。

.autoDisableRendererCulling

autoDisableRendererCulling = true : Boolean

如果为 true，则所有 tile 网格自动将其 frustumCulled 字段设置为 false。 这在使用一个相机时尤其有用，因为图块渲染器会自动在可见图块上执行它自己的视锥体剔除。 如果 displayActiveTiles 为 true 或正在使用多个摄像头，那么您可以考虑将其设置为 false。

.optimizeRaycast

optimizeRaycast = true : Boolean

如果为真，则加载的图块对象的 raycast 函数将被覆盖以禁用光线投射，并且 TilesRenderer.group 光线投射函数用于对所有可见图块执行光线投射。 这可以优化针对图块的光线投射遍历。 如果 raycaster.firstHitOnly = true 那么除了更优化的瓦片遍历外，一旦找到最近的交叉点，光线投射就会提前结束。

如果您想自己管理针对图块的光线投射，可以在需要时通过将 optizeRaycast 设置为 false 来禁用此行为。

.onPreprocessURL

onPreprocessURL = null : ( uri : string | URL ) => string | URL;

为每个单独的图块几何图形或要加载的子图块集预处理 url 的函数。 如果为 null，则直接使用 url。

.lruCache

lruCache = new LRUCache() : LRUCache

注意：update 第一次调用后，无法设置。

.downloadQueue

downloadQueue = new PriorityQueue : PriorityQueue

注意：update 是第一次调用。

.parseQueue

parseQueue = new PriorityQueue : PriorityQueue

注意：一旦 update 是第一次调用，就不能修改了.

.group

group : Group

3d tile 的容器组。 将其添加到 three.js 场景以渲染它。

当光线投射时，使用更高性能的遍历方法（参见 optimizeRaycast）。

.manager

manager : LoadingManager

加载图块几何体时使用的管理器。

.constructor

constructor( url : String )

获取要呈现的图块集的 tileset.json 的 url。

.update

update() : void

更新要渲染的图块并启动 3d 图块集中相应图块的加载。

group.matrixWorld 和所有相机世界矩阵都应在调用之前保持最新。

.getBounds

getBounds( box : Box3 ) : boolean

将 box 设置为在 group 框架中设置的图块的轴对齐根边界框。 如果未加载图块根，则返回 false。

.getOrientedBounds

getOrientedBounds( box : Box3, boxTransform : Matrix4 ) : boolean;

将 box 和 boxTransform 设置为描述封装瓦片集根的定向边界框的边界和矩阵。 如果未加载图块根，则返回 false。

.hasCamera

hasCamera( camera : Camera ) : boolean

如果已在渲染器上设置相机，则返回 true。

.setCamera

setCamera( camera : Camera ) : boolean

将摄像机添加到要在遍历图块集时考虑的摄像机。 如果相机已经被跟踪，则返回 false。 否则返回 true。

.deleteCamera

deleteCamera( camera : Camera ) : boolean

在遍历图块集时，将给定的相机从计算中移除。 如果未跟踪相机，则返回 false。

.setResolution

setResolution( camera : Camera, resolution : Vector2 ) : boolean
setResolution( camera : Camera, x : number, y : number ) : boolean

为给定相机设置正在渲染的分辨率。 如果未跟踪相机，则返回 false。

.setResolutionFromRenderer

setResolutionFromRenderer( camera : Camera, renderer : WebGLRenderer ) : boolean

通过渲染器为给定的相机设置正在渲染的分辨率，渲染器考虑画布大小和当前像素比。 如果未跟踪相机，则返回 false。

.forEachLoadedModel

forEachLoadedModel( callback : ( scene : Object3D, tile : object ) => void ) : void

为层次结构中的每个加载场景触发回调，并将关联的图块作为第二个参数。 这可用于更新图块集中所有已加载网格的材质。

.onLoadTileSet

onLoadTileSet = null : ( tileSet : Tileset ) => void

每当加载图块集时调用的回调。

.onLoadModel

onLoadModel = null : ( scene : Object3D, tile : Tile ) => void

每次加载模型时调用的回调。 这可以与 .forEachLoadedModel 结合使用，以设置所有负载的材质，但仍未加载 tile 集中的网格。

.onDisposeModel

onDisposeModel = null : ( scene : Object3D, tile : Tile ) => void

每次处理模型时调用的回调。 这应该与 .onLoadModel 结合使用，以处理为图块创建的任何自定义材料。 请注意，即使已从瓷砖网格中移除，瓷砖加载的纹理、材质和几何图形也会自动处理掉。

.onTileVisibilityChange

onTileVisibilityChange = null : ( scene : Object3D, tile : Tile, visible : boolean ) => void

当 tile 的可见性改变时调用的回调。 当图块可见时，参数 visible 为 true

.dispose

dispose() : void

处理渲染器中的所有图块。 调用处理渲染器加载的所有材质、纹理和几何图形，随后为任何加载的图块模型调用 onDisposeModel。

DebugTilesRenderer

扩展 TilesRenderer

TilesRenderer 的特殊变体，包括用于调试和可视化图块集中各种图块的帮助程序。 材质覆盖不会像预期的那样与该渲染器一起工作。

.colorMode

colorMode = NONE : ColorMode

渲染图块集时使用哪种颜色模式。 可以使用以下导出的枚举：

// No special color mode. Uses the default materials.
NONE

// Render the screenspace error from black to white with errorTarget
// being the maximum value.
SCREEN_ERROR

// Render the geometric error from black to white with maxDebugError
// being the maximum value.
GEOMETRIC_ERROR

// Render the distance from the camera to the tile as black to white
// with maxDebugDistance being the maximum value.
DISTANCE

// Render the depth of the tile relative to the root as black to white
// with maxDebugDepth being the maximum value.
DEPTH

// Render the depth of the tile relative to the nearest rendered parent
// as black to white with maxDebugDepth being the maximum value.
RELATIVE_DEPTH

// Render leaf nodes as white and parent nodes as black.
IS_LEAF

// Render the tiles with a random color to show tile edges clearly.
RANDOM_COLOR

// Render every individual mesh in the scene with a random color.
RANDOM_NODE_COLOR

// Sets a custom color using the customColorCallback call back.
CUSTOM_COLOR

.customColorCallback

customColorCallback: (tile: Tile, child: Object3D) => void

debugColor 设置为 CUSTOM_COLOR 时使用的回调。 值默认为 null 并且必须明确设置。

.displayBoxBounds

displayBoxBounds = false : Boolean

为每个可见的图块显示图块 boundingVolume.box 中的线框边界框。

.displaySphereBounds

displaySphereBounds = false : Boolean

为每个可见的图块显示来自图块 boundingVolume.sphere（或从边界框派生）的线框边界框。

.maxDebugDepth

maxDebugDepth = - 1 : Number

使用 DEPTH 或 RELATIVE_DEPTH colorMode 渲染时代表白色的深度值。 如果 maxDebugDepth 为 -1，则使用图块集的最大深度。

.maxDebugError

maxDebugError = - 1 : Number

使用 GEOMETRIC_ERROR colorMode 渲染时代表白色的错误值。 如果 maxDebugError 为 -1，则使用图块集中的最大几何误差。

.maxDebugDistance

maxDebugDistance = - 1 : Number

使用 DISTANCE colorMode 渲染时代表白色的距离值。 如果 maxDebugDistance 为 -1，则使用图块集的半径。

.getDebugColor

getDebugColor : ( val : Number, target : Color ) => void

用于将 [0, 1] 值映射到调试可视化颜色的函数。 默认情况下，颜色从黑色映射到白色。

PriorityQueue

优先级排序队列，用于确定文件下载和解析的优先级。

.maxJobs

maxJobs = 6 : number

一次要处理的最大作业数。

.priorityCallback

priorityCallback = null : ( itemA, itemB ) => Number

导出给定项目的作业优先级的函数。 优先级较高的值首先得到处理。

.schedulingCallback

schedulingCallback = requestAnimationFrame : ( cb : Function ) => void

用于安排下一次运行作业的时间的函数，因此在单个帧中不会发生比可用时间更多的工作 -- 默认为下一帧。 这应该在 requestAnimationFrame 不可靠的情况下被覆盖，例如在 WebXR 中运行时。 有关如何使用 WebXR 处理此问题的示例，请参阅 VR 演示。

LRUCache

TilesRenderer 的实用程序类，用于跟踪当前使用的项目，因此渲染的项目不会被卸载。

.maxSize

maxSize = 800 : number

最大缓存大小。 如果当前缓存项的数量等于此值，则无法缓存更多项。

.minSize

minSize = 600 : number

最小缓存大小。 上面的缓存数据如果未使用，将被卸载。

.unloadPercent

unloadPercent = 0.05 : number

在给定帧期间要卸载的 minSize 的最大百分比。

.unloadPriorityCallback

unloadPriorityCallback = null : ( item ) => Number

导出给定项目的卸载优先级的函数。 较高优先级的值首先被卸载。

BatchTable

.getKeys

getKeys() : Array<String>

返回批处理表中所有数据的键。

.getData

getData(
    key : String,
    defaultComponentType = null : String | null,
    defaultType = null : String | null,
) : Array | TypedArray | null

返回与传递给函数的 key 关联的数据。 如果在批处理表内容中指定了组件和类型，则使用这些值，否则使用 defaultComponentType 和 defaultType 中的值。 如果键不在表中，则返回 null。

defaultComponentType可以设置为BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT、UNSIGNED_INT、FLOAT 或 DOUBLE。 defaultType 可以设置为 SCALAR、VEC2、VEC3 或 VEC4。

LICENSE

该软件在 Apache V2.0 许可证 下可用。

版权所有 © 2020 加州理工学院。 所有权利 预订的。 美国政府赞助确认。 无论是加州理工学院的名称还是其运营部门， 喷气推进实验室及其贡献者的名字可能 用于认可或推广源自该软件的产品 未经事先书面许可。