Skip to content

Commit

Permalink
Merge a90135f into 62764f0
Browse files Browse the repository at this point in the history
  • Loading branch information
@ibgreen
ibgreen committed Sep 16, 2019
2 parents 62764f0 + a90135f commit 529a5c3
Show file tree
Hide file tree
Showing 50 changed files with 509 additions and 518 deletions.
4 changes: 2 additions & 2 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ To quickly get up to speed on how the loaders.gl API works, please see [Get Star

## Major Components

- **Loaders** - A suite of *loaders* for parsing various file formats into well-defined JavaScript data strucutures.
- **Writers** - *writers* allowing data to be encoded and saved to certain formats.
- **Loaders** - A suite of _loaders_ for parsing various file formats into well-defined JavaScript data strucutures.
- **Writers** - _writers_ allowing data to be encoded and saved to certain formats.
- **Core Functions** - A set of functions that make it easier to work with loaders and writers.

## Why loaders.gl?
Expand Down
2 changes: 2 additions & 0 deletions docs/api-reference/3d-tiles/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@ npm install @loaders.gl/core @loaders.gl/3d-tiles
## Roadmap

The plan is to provide the following loaders/writers:

- `Tile3DLoader` for individual tiles
- `Tileset3DLoader` for the tileset
- `Tile3DWriter` for individual tiles

And the following helper classes

- `Tileset3D` to help access the loaded tileset.
- `Tile3D` to help access a loaded tile.
- `Tileset3DTraversal` class that accepts view frustum parameters and returns a culled, prioritized list of tiles to show.
Expand Down
41 changes: 20 additions & 21 deletions docs/api-reference/3d-tiles/tile-3d-loader.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
Parses a [3D tile](https://github.com/AnalyticalGraphicsInc/3d-tiles). glTF file into a hirearchical scenegraph description that can be used to instantiate an actual Scenegraph in most WebGL libraries. Can load both binary `.glb` files and JSON `.gltf` files.

| Loader | Characteristic |
| --------------------- | --------------- |
| File Extensions | `.b3dm`,`.i3dm`, `.pnts`, `.cmpt` |
| File Type | Binary (with linked assets) |
| File Format | [glTF](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#tile-format-specifications) |
| Data Format | [Scenegraph](/docs/specifications/category-scenegraph) |
| Decoder Type | Synchronous (limited), Asynchronous |
| Worker Thread Support | No |
| Streaming Support | No \* |
| Loader | Characteristic |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| File Extensions | `.b3dm`,`.i3dm`, `.pnts`, `.cmpt` |
| File Type | Binary (with linked assets) |
| File Format | [glTF](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#tile-format-specifications) |
| Data Format | [Scenegraph](/docs/specifications/category-scenegraph) |
| Decoder Type | Synchronous (limited), Asynchronous |
| Worker Thread Support | No |
| Streaming Support | No \* |

\* Streaming is not supported for invididual tiles, however tilesets are streamed by loading only the tiles needed for the current view.

Expand All @@ -37,18 +37,17 @@ const gltf = await load(url, Tile3DLoader, {DracoLoader, decompress: true});

Point cloud options

| Option | Type | Default | Description |
| ------------- | --------- | ----------- | ----------------- |
| `DracoLoader` | [DracoLoader](/docs/api-reference/draco/draco-loader) | `null` |

| Option | Type | Default | Description |
| ------------- | ----------------------------------------------------- | ------- | ----------- |
| `DracoLoader` | [DracoLoader](/docs/api-reference/draco/draco-loader) | `null` |

glTF tile options

| Option | Type | Default | Description |
| ------------- | --------- | ----------- | ----------------- |
| `DracoLoader` | [DracoLoader](/docs/api-reference/draco/draco-loader) | `null` | Supply to enable decoding of Draco compressed meshes. |
| `fetchLinkedResources` | Boolean | `true` | Fetch any linked .BIN files, decode base64 encoded URIS. Only supported in asynchronous parsing. |
| `fetch` | Function | `fetch` | Function used to fetch linked resources. |
| `decompress` | Boolean | `true` | Decompress Draco compressed meshes (if DracoLoader available). |
| `postProcess` | Boolean | `false` | Perform additional post processing to simplify use in WebGL libraries. |
| `createImages` | Boolean | `false` | Create image objects from loaded image data. |
| Option | Type | Default | Description |
| ---------------------- | ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `DracoLoader` | [DracoLoader](/docs/api-reference/draco/draco-loader) | `null` | Supply to enable decoding of Draco compressed meshes. |
| `fetchLinkedResources` | Boolean | `true` | Fetch any linked .BIN files, decode base64 encoded URIS. Only supported in asynchronous parsing. |
| `fetch` | Function | `fetch` | Function used to fetch linked resources. |
| `decompress` | Boolean | `true` | Decompress Draco compressed meshes (if DracoLoader available). |
| `postProcess` | Boolean | `false` | Perform additional post processing to simplify use in WebGL libraries. |
| `createImages` | Boolean | `false` | Create image objects from loaded image data. |
26 changes: 15 additions & 11 deletions docs/api-reference/3d-tiles/tileset-3d-loader.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,29 @@
Parses a main tileset JSON file as the entry point to define a 3D tileset.

| Loader | Characteristic |
| --------------------- | ---------------- |
| File Extensions | `.json` |
| File Type | JSON |
| Loader | Characteristic |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| File Extensions | `.json` |
| File Type | JSON |
| File Format | [3D Tileset JSON](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#tileset-json) |
| Data Format | JSON |
| Decoder Type | Synchronous |
| Worker Thread Support | No |
| Streaming Support | No |
| Data Format | JSON |
| Decoder Type | Synchronous |
| Worker Thread Support | No |
| Streaming Support | No |

## Usage

```js
import {Tileset3DLoader, Tileset3D} from '^loaders.gl/3d-tiles';
const tilesetJson = await load('http://localhost:8002/tilesets/Seattle/tileset.json', Tileset3DLoader);
const tilesetJson = await load(
'http://localhost:8002/tilesets/Seattle/tileset.json',
Tileset3DLoader
);
const tileset = new Tileset3D(tilesetJson);
```

## Options

| Option | Type | Default | Description |
| ------------- | --------- | ----------- | ----------------- |
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |

70 changes: 28 additions & 42 deletions docs/api-reference/3d-tiles/tileset-3d.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
This class can be instantiated with tileset data formatted according to the [3D Tiles Category](docs/specifications/3d-tiles), which is supported by the [Tileset3DLoader](docs/api-reference/3d-tiles/tileset-3d-loader).

References

- [3D Tiles](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification).

## Usage
Expand All @@ -15,7 +16,7 @@ Loading a tileset and instantiating a `Tileset3D` instance.
import {Tileset3DLoader, Tileset3D} from '@loaders.gl/3d-tiles';
import {parse} from '@loaders.gl/core';

const tilesetJSON = await parse(fetch(tileset))
const tilesetJSON = await parse(fetch(tileset));
const tileset = new Tileset3D(tilesetJson);

console.log(`Maximum building height: ${tileset.properties.height.maximum}`);
Expand All @@ -30,7 +31,7 @@ import {Tileset3D} from '@loaders.gl/3d-tiles';
const tileset = new Tileset3D(tilesetJson, {
url: 'http://localhost:8002/tilesets/Seattle/tileset.json',
baseScreenSpaceError: 1024,
skipScreenSpaceErrorFactor: 16,
skipScreenSpaceErrorFactor: 16
});
```

Expand All @@ -54,22 +55,19 @@ Gets the tileset's asset object property, which contains metadata about the tile

See the [asset schema reference](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#reference-asset) in the 3D Tiles spec for the full set of properties.


### properties : Object (readonly)

Gets the tileset's properties dictionary object, which contains metadata about per-feature properties.

See the [properties schema reference](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#reference-properties) in the 3D Tiles spec for the full set of properties.


### tilesLoaded : boolean (readonly)

When `true`, all tiles that meet the screen space error this frame are loaded. The tileset is
completely loaded for this view.

See Tileset3D#allTilesLoaded


### url : String (readonly)

The url to a tileset JSON file.
Expand All @@ -82,59 +80,54 @@ The base path that non-absolute paths in tileset JSON file are relative to.

The maximum screen space error used to drive level of detail refinement. This value helps determine when a tile refines to its descendants, and therefore plays a major role in balancing performance with visual quality.


A tile's screen space error is roughly equivalent to the number of pixels wide that would be drawn if a sphere with a
radius equal to the tile's <b>geometric error</b> were rendered at the tile's position. If this value exceeds
`maximumScreenSpaceError` the tile refines to its descendants.

Depending on the tileset, `maximumScreenSpaceError` may need to be tweaked to achieve the right balance. Higher values provide better performance but lower visual quality.
*
Depending on the tileset, `maximumScreenSpaceError` may need to be tweaked to achieve the right balance. Higher values provide better performance but lower visual quality. \*

### maximumMemoryUsage : Number

^default 16
*
^default 16 \*
^exception `maximumScreenSpaceError` must be greater than or equal to zero.

The maximum amount of GPU memory (in MB) that may be used to cache tiles. This value is estimated from
geometry, textures, and batch table textures of loaded tiles. For point clouds, this value also
includes per-point metadata.


Tiles not in view are unloaded to enforce this.

If decreasing this value results in unloading tiles, the tiles are unloaded the next frame.

If tiles sized more than `maximumMemoryUsage` are needed
to meet the desired screen space error, determined by `Tileset3D.maximumScreenSpaceError `,
to meet the desired screen space error, determined by `Tileset3D.maximumScreenSpaceError`,
for the current view, then the memory usage of the tiles loaded will exceed
`maximumMemoryUsage`. For example, if the maximum is 256 MB, but
300 MB of tiles are needed to meet the screen space error, then 300 MB of tiles may be loaded. When
`maximumMemoryUsage`. For example, if the maximum is 256 MB, but
300 MB of tiles are needed to meet the screen space error, then 300 MB of tiles may be loaded. When
these tiles go out of view, they will be unloaded.

^default 512
*
^default 512 \*
^exception `maximumMemoryUsage` must be greater than or equal to zero.
^see Tileset3D#totalMemoryUsageInBytes

### root : Tile3DHeader

The root tile header.


### boundingSphere : BoundingSphere

The tileset's bounding sphere.


```js
var tileset = viewer.scene.primitives.add(new Tileset3D({
url : 'http://localhost:8002/tilesets/Seattle/tileset.json'
}));
var tileset = viewer.scene.primitives.add(
new Tileset3D({
url: 'http://localhost:8002/tilesets/Seattle/tileset.json'
})
);

tileset.readyPromise.then(function(tileset) {
// Set the camera to view the newly added tileset
viewer.camera.viewBoundingSphere(tileset.boundingSphere, new HeadingPitchRange(0, -0.5, 0));
// Set the camera to view the newly added tileset
viewer.camera.viewBoundingSphere(tileset.boundingSphere, new HeadingPitchRange(0, -0.5, 0));
});
```

Expand Down Expand Up @@ -165,7 +158,6 @@ includes per-point metadata.

An instance of a probe.gl `Stats` object that contains information on how many tiles have been loaded etc. Easy to display using a probe.gl `StatsWidget`.


### ellipsoid : Ellipsoid

Gets an ellipsoid describing the shape of the globe.
Expand All @@ -177,7 +169,6 @@ Exception The tileset is not loaded. Use Tileset3D.readyPromise or wait for Tile

See [Extras](https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification#specifying-extensions-and-application-specific-extras) in the 3D Tiles specification.}


### unloadTileset

Unloads all tiles that weren't selected the previous frame. This can be used to
Expand Down Expand Up @@ -205,7 +196,6 @@ Once an object is destroyed, it should not be used; calling any function other t

Wxception This object was destroyed, i.e., destroy() was called.


## Methods

### constructor(tileset : Object, url : String [, options : Object])
Expand All @@ -215,16 +205,15 @@ Wxception This object was destroyed, i.e., destroy() was called.
- `options`: Options object, see the options section below for available options.

Notes:
- The `version` tileset must be 3D Tiles version 0.0 or 1.0.

- The `version` tileset must be 3D Tiles version 0.0 or 1.0.

### hasExtension(extensionName : String) : Boolean

`true` if the tileset JSON file lists the extension in extensionsUsed; otherwise, `false`.
^param {String} extensionName The name of the extension to check. \*
^returns {Boolean} `true` if the tileset JSON file lists the extension in extensionsUsed; otherwise, `false`.


## Options

> Tileset3D class is still being developed, not all options are guaranteed to be working.
Expand All @@ -244,11 +233,11 @@ The `Tileset3D` class supports a number of options
- `options.ellipsoid`=`Ellipsoid.WGS84` (`Ellipsoid`) - The ellipsoid determining the size and shape of the globe.

Callbacks

- `options.onTileLoad` (`(tileHeader : Tile3DHeader) : void`) -
- `options.onTileUnload` (`(tileHeader : Tile3DHeader) :void`) -
- `options.onTileLoadFailed` (`void(tileHeader : Tile3DHeader, message : String) : void`) -


### dynamicScreenSpaceError

=`false`
Expand All @@ -265,7 +254,6 @@ A scalar that determines the density used to adjust the dynamic screen space err

The error starts at 0.0 and increases exponentially until a midpoint is reached, and then approaches 1.0 asymptotically. This has the effect of keeping high detail in the closer tiles and lower detail in the further tiles, with all tiles beyond a certain distance all roughly having an error of 1.0.


The dynamic error is in the range [0.0, 1.0) and is multiplied by `dynamicScreenSpaceErrorFactor` to produce the
final dynamic error. This dynamic error is then subtracted from the tile's actual screen space error.

Expand All @@ -287,7 +275,6 @@ A ratio of the tileset's height at which the density starts to falloff. If the c
full computed density is applied, otherwise the density falls off. This has the effect of higher density at
street level views.


Valid values are between 0.0 and 1.0.

### onTileLoad(tileHeader : Tile3DHeader) : void
Expand All @@ -297,7 +284,7 @@ Indicate ssthat a tile's content was loaded.
The loaded `Tile3DHeader` is passed to the event listener.

This event is fired during the tileset traversal while the frame is being rendered
so that updates to the tile take effect in the same frame. Do not create or modify
so that updates to the tile take effect in the same frame. Do not create or modify
entities or primitives during the event listener.

```js
Expand All @@ -313,7 +300,7 @@ Indicates that a tile's content was unloaded.
The unloaded `Tile3DHeaders` is passed to the event listener.

This event is fired immediately before the tile's content is unloaded while the frame is being
rendered so that the event listener has access to the tile's content. Do not create
rendered so that the event listener has access to the tile's content. Do not create
or modify entities or primitives during the event listener.

```js
Expand All @@ -323,28 +310,28 @@ or modify entities or primitives during the event listener.
```

See

- Tileset3D#maximumMemoryUsage
- Tileset3D#trimLoadedTiles


### onTileLoadFail(tileHeader : Tile3DHeader) : void

Called to indicate that a tile's content failed to load. By default, error messages will be logged to the console.

The error object passed to the listener contains two properties:

- `url`: the url of the failed tile.
- `message`: the error message.

```js
new Tileset3D({
onTileFailed(tileHeader, url, message) {
console.log('An error occurred loading tile: ', url);
console.log('Error: ', message);
}
});
new Tileset3D({
onTileFailed(tileHeader, url, message) {
console.log('An error occurred loading tile: ', url);
console.log('Error: ', message);
}
});
```


### skipLevelOfDetail : Boolean

Default: true
Expand All @@ -356,7 +343,6 @@ all children to be loaded before the parent can refine. With this optimization l
entirely and children can be rendered alongside their parents. The tileset requires significantly less memory when
using this optimization.


### baseScreenSpaceError : Number

Default: 1024
Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/arrow/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# @loaders.gl/arrow

This module handles [Apache Arrow](https://arrow.apache.org/), an emerging standard for large in-memory columnar data.
This module handles [Apache Arrow](https://arrow.apache.org/), an emerging standard for large in-memory columnar data.

## Installation

Expand Down
Loading

0 comments on commit 529a5c3

Please sign in to comment.