feat: add variant

* feat: add variant

* docs: add docs for variant

Author: WoodNeck

demo/docs/options/model/dracoPath.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 import View3D from "@site/src/components/View3D";

demo/docs/options/model/ktxPath.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 import View3D from "@site/src/components/View3D";

demo/docs/options/model/meshoptPath.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 import View3D from "@site/src/components/View3D";

demo/docs/options/model/variant.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 3
+---
+
+import View3D from "@site/src/components/View3D";
+import Variant from "@site/src/components/demo/Variant";
+import OptionDescriptor from "@site/src/components/OptionDescriptor";
+import License from "@site/src/components/License";
+
+<OptionDescriptor type="string | number | null" defaultVal="null" />
+
+Set material variant of the model, which only can be used when using [glTF materials variants extension](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_variants/README.md)
+Either can be index of the variant(number), or the name of the variant(string)
+
+## Example
+<div className="columns">
+  <div className="column is-6">
+    <View3D
+      src="/egjs-view3d/model/MaterialsVariantsShoe.glb"
+      variant={null}
+      showExampleCode />
+  </div>
+  <div className="column is-6">
+    <View3D
+      src="/egjs-view3d/model/MaterialsVariantsShoe.glb"
+      variant={1}
+      showExampleCode />
+  </div>
+</div>
+<div className="columns">
+  <div className="column is-6">
+    <View3D
+      src="/egjs-view3d/model/MaterialsVariantsShoe.glb"
+      variant="street"
+      showExampleCode />
+  </div>
+  <div className="column is-6"></div>
+</div>
+
+## Changing Variant
+You can easily change variant by changing the option value.
+
+<Variant />
+
+```js
+// You can use index of the variant
+view3D.variant = 1;
+
+// Or the name of the variant
+view3D.variant = "beach";
+```
+
+<License items={[
+  {
+    name: "MaterialsVariantsShoe",
+    link: "https://github.com/pushmatrix/glTF-Sample-Models/tree/master/2.0/MaterialsVariantsShoe",
+    author: "Shopify",
+    authorLink: "https://github.com/Shopify",
+    license: "Creative Commons Attribution"
+  }
+]} />

demo/src/components/demo/Variant.tsx

@@ -0,0 +1,41 @@
+import React, { useRef, useState } from "react";
+import clsx from "clsx";
+import View3D, { TONE_MAPPING } from "../View3D";
+
+const variants = [
+  "midnight",
+  "beach",
+  "street"
+]
+
+export default () => {
+  const view3D = useRef<View3D>(null);
+
+  return <>
+    <section>
+      <div>
+        <table>
+          <tbody>
+            <tr>
+              <td className="mr-2">Variant:</td>
+              <td>
+                <div className={clsx({ select: true, "mr-1": true })}>
+                  <select defaultValue={0} onChange={e => {
+                    view3D.current!.view3D.variant = e.target.value;
+                  }}>
+                    { variants.map((name, idx) => (
+                      <option key={idx} value={name}>{name}</option>
+                    )) }
+                  </select>
+                </div>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+      <View3D
+        ref={view3D}
+        src="/egjs-view3d/model/MaterialsVariantsShoe.glb" />
+    </section>
+  </>;
+};

demo/static/model/MaterialsVariantsShoe.glb

@@ -71,6 +71,7 @@ export interface View3DOptions {
   // Model
   src: string | string[] | null;
   iosSrc: string | null;
+  variant: number | string | null;
   dracoPath: string;
   ktxPath: string;
   meshoptPath: string | null;
@@ -167,6 +168,7 @@ class View3D extends Component<View3DEvents> implements OptionGetters<Omit<View3
   // Options
   private _src: View3DOptions["src"];
   private _iosSrc: View3DOptions["iosSrc"];
+  private _variant: View3DOptions["variant"];
   private _dracoPath: View3DOptions["dracoPath"];
   private _ktxPath: View3DOptions["ktxPath"];
   private _meshoptPath: View3DOptions["meshoptPath"];
@@ -313,6 +315,14 @@ class View3D extends Component<View3DEvents> implements OptionGetters<Omit<View3
    * @default null
    */
   public get iosSrc() { return this._iosSrc; }
+  /**
+   * Active material variant of the model.
+   * Either can be index of the variant(number), or the name of the variant(string)
+   * Changing this value will change the material of the model
+   * @default null
+   * @see https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_variants/README.md
+   */
+  public get variant() { return this._variant; }
   /**
    * URL to {@link https://github.com/google/draco Draco} decoder location.
    * @type {string}
@@ -624,6 +634,15 @@ class View3D extends Component<View3DEvents> implements OptionGetters<Omit<View3
    */
   public get maxDeltaTime() { return this._maxDeltaTime; }
 
+  public set variant(val: View3DOptions["variant"]) {
+    if (this._model) {
+      this._model.selectVariant(val)
+        .then(() => {
+          this.renderer.renderSingleFrame();
+        });
+    }
+    this._variant = val;
+  }
   public set defaultAnimationIndex(val: View3DOptions["defaultAnimationIndex"]) { this._defaultAnimationIndex = val; }
   public set initialZoom(val: View3DOptions["initialZoom"]) { this._initialZoom = val; }
 
@@ -704,6 +723,7 @@ class View3D extends Component<View3DEvents> implements OptionGetters<Omit<View3
   public constructor(root: string | HTMLElement, {
     src = null,
     iosSrc = null,
+    variant = null,
     dracoPath = DEFAULT.DRACO_DECODER_URL,
     ktxPath = DEFAULT.KTX_TRANSCODER_URL,
     meshoptPath = null,
@@ -758,6 +778,7 @@ class View3D extends Component<View3DEvents> implements OptionGetters<Omit<View3
     // Bind options
     this._src = src;
     this._iosSrc = iosSrc;
+    this._variant = variant;
     this._dracoPath = dracoPath;
     this._ktxPath = ktxPath;
     this._meshoptPath = meshoptPath;

packages/view3d/src/View3D.ts

@@ -44,6 +44,8 @@ export enum GESTURE {
   PINCH = 16,
 }
 
+export const VARIANT_EXTENSION = "KHR_materials_variants";
+
 export const CUSTOM_TEXTURE_LOD_EXTENSION = "EXT_View3D_texture_LOD";
 export const TEXTURE_LOD_EXTRA = "view3d-lod";
 export const ANNOTATION_EXTRA = "view3d-annotation";

packages/view3d/src/const/internal.ts

@@ -4,8 +4,10 @@
  */
 
 import * as THREE from "three";
+import { GLTFParser } from "three/examples/jsm/loaders/GLTFLoader";
 
-import { getAttributeScale, getSkinnedVertex, parseAsBboxRatio } from "../utils";
+import { getAttributeScale, getSkinnedVertex, parseAsBboxRatio, isString } from "../utils";
+import { VARIANT_EXTENSION } from "../const/internal";
 
 import { Annotation } from "../annotation";
 import { AUTO } from "../const/external";
@@ -16,10 +18,12 @@ import { AUTO } from "../const/external";
 class Model {
   private _src: string;
   private _scene: THREE.Group;
+  private _parser: GLTFParser | null;
   private _bbox: THREE.Box3;
   private _center: THREE.Vector3;
   private _animations: THREE.AnimationClip[];
   private _annotations: Annotation[];
+  private _variants: Array<{ name: string }>;
   private _fixSkinnedBbox: boolean;
 
   /**
@@ -96,17 +100,21 @@ class Model {
     src,
     scenes,
     center = AUTO,
+    parser = null,
     animations = [],
     annotations = [],
+    variants = [],
     fixSkinnedBbox = false,
     castShadow = true,
     receiveShadow = false
   }: {
     src: string;
     scenes: THREE.Object3D[];
     center?: typeof AUTO | Array<number | string>;
+    parser?: GLTFParser | null,
     animations?: THREE.AnimationClip[];
     annotations?: Annotation[];
+    variants?: Array<{ name: string }>;
     fixSkinnedBbox?: boolean;
     castShadow?: boolean;
     receiveShadow?: boolean;
@@ -116,9 +124,11 @@ class Model {
     const scene = new THREE.Group();
     scene.add(...scenes);
 
+    this._scene = scene;
+    this._parser = parser;
     this._animations = animations;
     this._annotations = annotations;
-    this._scene = scene;
+    this._variants = variants;
     const bbox = this._getInitialBbox(fixSkinnedBbox);
 
     // Move to position where bbox.min.y = 0
@@ -136,6 +146,52 @@ class Model {
     this.receiveShadow = receiveShadow;
   }
 
+  public async selectVariant(variant: number | string | null) {
+    const variants = this._variants;
+    const parser = this._parser;
+
+    if (variants.length <= 0 || !parser) return;
+
+    let variantIndex = 0;
+    if (variant != null) {
+      if (isString(variant)) {
+        variantIndex = variants.findIndex(({ name }) => name === variant);
+      } else {
+        variantIndex = variant
+      }
+    }
+
+    const scene = this._scene;
+    const matLoadPromises: Promise<any>[] = [];
+
+    scene.traverse(async (obj: THREE.Mesh) => {
+      if (!obj.isMesh || !obj.userData.gltfExtensions) return;
+
+      const meshVariantDef = obj.userData.gltfExtensions[VARIANT_EXTENSION];
+
+      if (!meshVariantDef) return;
+
+      if (!obj.userData.originalMaterial) {
+        obj.userData.originalMaterial = obj.material;
+      }
+
+      const mapping = meshVariantDef.mappings
+        .find(mapping => mapping.variants.includes(variantIndex));
+
+      if (mapping) {
+        const loadMat = parser.getDependency("material", mapping.material);
+        matLoadPromises.push(loadMat);
+
+        obj.material = await loadMat;
+        parser.assignFinalMaterial(obj);
+      } else {
+        obj.material = obj.userData.originalMaterial;
+      }
+    });
+
+    return Promise.all(matLoadPromises);
+  }
+
   /**
    * Executes a user-supplied "reducer" callback function on each vertex of the model, in order, passing in the return value from the calculation on the preceding element.
    */

packages/view3d/src/core/Model.ts

@@ -11,7 +11,7 @@ import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader";
 import View3D from "../View3D";
 import Model from "../core/Model";
 import Annotation from "../annotation/Annotation";
-import { ANNOTATION_EXTRA, CUSTOM_TEXTURE_LOD_EXTENSION, STANDARD_MAPS, TEXTURE_LOD_EXTRA } from "../const/internal";
+import { ANNOTATION_EXTRA, CUSTOM_TEXTURE_LOD_EXTENSION, STANDARD_MAPS, TEXTURE_LOD_EXTRA, VARIANT_EXTENSION } from "../const/internal";
 import { createLoadingContext } from "../utils";
 
 import Loader from "./Loader";
@@ -84,8 +84,8 @@ class GLTFLoader extends Loader {
 
     return new Promise((resolve, reject) => {
       try {
-        loader.load(url, gltf => {
-          const model = this._parseToModel(gltf, url);
+        loader.load(url, async gltf => {
+          const model = await this._parseToModel(gltf, url);
           resolve(model);
         }, evt => this._onLoadingProgress(evt, url, loadingContext), err => {
           loadingContext.initialized = true;
@@ -161,8 +161,8 @@ class GLTFLoader extends Loader {
       const loadingContext = createLoadingContext(view3D, gltfURL);
 
       loader.manager = manager;
-      loader.load(gltfURL, gltf => {
-        const model = this._parseToModel(gltf, gltfFile.name);
+      loader.load(gltfURL, async gltf => {
+        const model = await this._parseToModel(gltf, gltfFile.name);
         revokeURLs();
         resolve(model);
       }, evt => this._onLoadingProgress(evt, gltfURL, loadingContext), err => {
@@ -173,7 +173,7 @@ class GLTFLoader extends Loader {
     });
   }
 
-  private _parseToModel(gltf: GLTF, src: string): Model {
+  private async _parseToModel(gltf: GLTF, src: string): Promise<Model> {
     const view3D = this._view3D;
     const fixSkinnedBbox = view3D.fixSkinnedBbox;
 
@@ -267,15 +267,26 @@ class GLTFLoader extends Loader {
       annotations.push(...view3D.annotation.parse(data));
     }
 
+    const userData = gltf.userData ?? {};
+    const extensions = userData.gltfExtensions ?? {};
+    const variants = extensions[VARIANT_EXTENSION] ? extensions[VARIANT_EXTENSION].variants : [];
+
     const model = new Model({
       src,
       scenes: gltf.scenes,
       center: view3D.center,
       annotations,
+      parser: gltf.parser,
       animations: gltf.animations,
+      annotations,
+      variants,
       fixSkinnedBbox
     });
 
+    if (view3D.variant) {
+      await model.selectVariant(view3D.variant);
+    }
+
     return model;
   }
 }