Feat/geojson draping (#169)

* GeoJSON Draping: experimental feature.
Also fixes #162

* Shader options optinal

* added attribution

* Remove a comment

* Update examples and README

* Changelog for new version

* 1.2.4

Author: Avnerus

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## v1.2
 
+## v1.2.4
+- Experimental feature: real time draping of GeoJSON overlays (see example).
+- Add a `Viewport` structure required on initial load and updated via the `setViewport()` function. Contains `width`, `height`, and `devicePixelRatio`.
+
 ## v1.2.3
  - runtime.update() now takes `viewportSize:Vector2` rather than `viewportHeight:number` (for future features that will require viewport width).
  - Preliminary support and example for loading GeoJSON and overlaying on Google 3D Tiles.

README.md

@@ -25,6 +25,7 @@ Development of this library started at The New York Times R&D as an effort to cr
 * [LiDAR Point Cloud hosted as 3D Tiles in Cesium ION](https://nytimes.github.io/three-loader-3dtiles/dist/web/examples/demos/cesium)
 * [Map overlay with OpenStreetMap](https://nytimes.github.io/three-loader-3dtiles/dist/web/examples/demos/map-overlay)
 * [Google Maps Photorealistic 3D Tiles (requires API key)](https://nytimes.github.io/three-loader-3dtiles/dist/web/examples/demos/google-3dtiles)
+* [Google 3D Tiles with GeoJSON Draping (experimental, requires API key)](https://nytimes.github.io/three-loader-3dtiles/dist/web/examples/demos/google-3dtiles)
 
 ---
 
@@ -53,7 +54,11 @@ let tilesRuntime = null;
 async function loadTileset() {
   const result = await Loader3DTiles.load(
       url: 'https://<TILESET URL>/tileset.json',
-      renderer: renderer,
+      viewport: {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio
+      }
       options: {
         dracoDecoderPath: 'https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/libs/draco',
         basisTranscoderPath: 'https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/libs/basis',

docs/three-loader-3dtiles.drapingshaderoptions.blendingtype.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [blendingType](./three-loader-3dtiles.drapingshaderoptions.blendingtype.md)
+
+## DrapingShaderOptions.blendingType property
+
+Blending algoritum of the draped colors. Default: `THREE.NormalBlending`
+
+**Signature:**
+
+```typescript
+blendingType: Blending;
+```

docs/three-loader-3dtiles.drapingshaderoptions.maxheight.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [maxHeight](./three-loader-3dtiles.drapingshaderoptions.maxheight.md)
+
+## DrapingShaderOptions.maxHeight property
+
+Maximum terrain height when searching for a matching vertex to the GEOJson overlay. Default: `300`
+
+**Signature:**
+
+```typescript
+maxHeight: number;
+```

docs/three-loader-3dtiles.drapingshaderoptions.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md)
+
+## DrapingShaderOptions interface
+
+**Signature:**
+
+```typescript
+interface DrapingShaderOptions 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [blendingType](./three-loader-3dtiles.drapingshaderoptions.blendingtype.md) |  | Blending | Blending algoritum of the draped colors. Default: <code>THREE.NormalBlending</code> |
+|  [maxHeight](./three-loader-3dtiles.drapingshaderoptions.maxheight.md) |  | number | Maximum terrain height when searching for a matching vertex to the GEOJson overlay. Default: <code>300</code> |
+|  [minHeight](./three-loader-3dtiles.drapingshaderoptions.minheight.md) |  | number | Minimum terrain height when searching for a matching vertex to the GEOJson overlay. Default: <code>0</code> |
+|  [opacity](./three-loader-3dtiles.drapingshaderoptions.opacity.md) |  | number | Opacity of the draped colors. Default: <code>0.5</code> |
+|  [samples](./three-loader-3dtiles.drapingshaderoptions.samples.md) |  | number | Number of samples to average around the render target cordinate when draping the GEOJson overlay. Default: <code>4</code> |
+|  [sampleStep](./three-loader-3dtiles.drapingshaderoptions.samplestep.md) |  | number | Number of pixels to step toward each sample when averaging the samples. Default: 4.0 |
+

docs/three-loader-3dtiles.drapingshaderoptions.minheight.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [minHeight](./three-loader-3dtiles.drapingshaderoptions.minheight.md)
+
+## DrapingShaderOptions.minHeight property
+
+Minimum terrain height when searching for a matching vertex to the GEOJson overlay. Default: `0`
+
+**Signature:**
+
+```typescript
+minHeight: number;
+```

docs/three-loader-3dtiles.drapingshaderoptions.opacity.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [opacity](./three-loader-3dtiles.drapingshaderoptions.opacity.md)
+
+## DrapingShaderOptions.opacity property
+
+Opacity of the draped colors. Default: `0.5`
+
+**Signature:**
+
+```typescript
+opacity: number;
+```

docs/three-loader-3dtiles.drapingshaderoptions.samples.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [samples](./three-loader-3dtiles.drapingshaderoptions.samples.md)
+
+## DrapingShaderOptions.samples property
+
+Number of samples to average around the render target cordinate when draping the GEOJson overlay. Default: `4`
+
+**Signature:**
+
+```typescript
+samples: number;
+```

docs/three-loader-3dtiles.drapingshaderoptions.samplestep.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [three-loader-3dtiles](./three-loader-3dtiles.md) &gt; [DrapingShaderOptions](./three-loader-3dtiles.drapingshaderoptions.md) &gt; [sampleStep](./three-loader-3dtiles.drapingshaderoptions.samplestep.md)
+
+## DrapingShaderOptions.sampleStep property
+
+Number of pixels to step toward each sample when averaging the samples. Default: 4.0
+
+**Signature:**
+
+```typescript
+sampleStep: number;
+```

docs/three-loader-3dtiles.loaderprops.md

@@ -18,8 +18,9 @@ interface LoaderProps
 |  --- | --- | --- | --- |
 |  [loadingManager?](./three-loader-3dtiles.loaderprops.loadingmanager.md) |  | LoadingManager | _(Optional)_ Use a Three JS loading manager |
 |  [options?](./three-loader-3dtiles.loaderprops.options.md) |  | [LoaderOptions](./three-loader-3dtiles.loaderoptions.md) | _(Optional)_ Advanced options for loading the tileset ([LoaderOptions](./three-loader-3dtiles.loaderoptions.md)<!-- -->) |
-|  [renderer?](./three-loader-3dtiles.loaderprops.renderer.md) |  | WebGLRenderer | _(Optional)_ Required when using compressed textures (basis universal) for GPU feature detection. |
+|  [renderer?](./three-loader-3dtiles.loaderprops.renderer.md) |  | WebGLRenderer | _(Optional)_ An existing renderer reference. Required for shader processing. |
 |  [url](./three-loader-3dtiles.loaderprops.url.md) |  | string | The URL of the tileset. For example if using Cesium ION, it would have the form: <code>https://assets.cesium.com/[ASSET_ID]/tileset.json</code>. |
+|  [viewport](./three-loader-3dtiles.loaderprops.viewport.md) |  | Viewport | Viewport properties. Use <code>setViewport()</code> to update |
 
 ## Methods