TypeDefinitions for ModelViewer.ts (WIP)

[subhankar-trisetra]

import { Vector3 } from 'three';
import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader';
// Add model-viewer to the IntrinsicElements list
declare global {
    namespace JSX {
        interface IntrinsicElements {
            'model-viewer': ModelViewerElement;
        }
    }
}
export interface ModelViewerElement extends Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>, 'ref'> {
    /**
     * The URL to the 3D model. Only glTF/GLB models are supported.
     */
    src?: string;

    'ios-src'?: string;
    /**
     * Configures the model with custom text that will be used to describe the model to viewers who use a screen reader or otherwise
     * depend on additional semantic context to understand what they are viewing.
     */
    alt?: string;
    /**
     * Displays an image instead of the model, useful for showing the user something before a model is loaded and ready to render.
     * If you use a poster with transparency, you may also want to set --poster-color to transparent so that the background shows through.
     */
    poster?: string;
    /**
     * If you're using a seamless poster as generated by toBlob({idealAspect: true}) with --poster-color transparent (which is recommended),
     * then enable this attribute to turn off the poster's transition. This keeps the shadow from blinking, and the transition is no longer necessary anyway since the poster matches the rendering.
     */
    'seamless-poster'?: boolean;
    /**
     * An enumerable attribute describing under what conditions the model should be preloaded. The supported values are "auto", "lazy" and "eager". Auto is equivalent to lazy, which loads the model
     * when it is near the viewport for reveal="auto", and when interacted with for reveal="interaction". Eager loads the model immediately.
     */
    loading?: 'eager' | 'lazy' | 'auto';
    /**
     * This attribute controls when the model should be revealed. It currently supports three values: "auto", "interaction", and "manual".
     * If reveal is set to "interaction", <model-viewer> will wait until the user interacts with the poster before loading and revealing the model.
     * If reveal is set to "auto", the model will be revealed as soon as it is done loading and rendering. If reveal is set to "manual",
     * the model will remain hidden until dismissPoster() is called.
     *
     * @example: https://modelviewer.dev/examples/loading#preload
     */
    reveal?: 'auto' | 'interaction' | 'manual';
    /**
     * This attribute makes the browser include credentials (cookies, authorization headers or TLS client certificates) in the request to fetch the 3D model. It's useful if the 3D model file is stored on another server that require authentication. By default the file will be fetch without credentials. Note that this has no effect if you are loading files locally or from the same domain.
     */
    'with-credentials'?: boolean;
    /**
     * Controls the environmental reflection of the model. Normally if skybox-image is set, that image will also be used for the environment-image. Use environment-image to only set the reflection without affecting the background. If neither is specified, default lighting will be applied. If 'neutral' is specified without a skybox, then a more evenly-lit environment is applied instead.
     */
    'environment-image'?: string;
    'camera-controls'?: boolean;
    'disable-zoom'?: boolean;
    'auto-rotate'?: boolean;
    ar?: boolean;
    autoplay?: boolean;
    'shadow-intensity'?: number | string;
    'ar-scale'?: number | string;
    bounds?: string;
    style?: React.CSSProperties;
    ref?: React.MutableRefObject<ModelViewer | undefined>;
}

export interface ModelViewer extends ModelViewerElement {
    /**
     * This property is read-only. It returns true if the load event below has fired since the last src change.
     */
    readonly loaded: boolean;
    /**
     * This property, pronounced model-is-visible, is read-only. It returns true if the element is visible on the page (assuming there is an IntersectionObserver) and the poster has been dismissed. This property is related to the model-visibility event.
     */
    readonly modelIsVisible: boolean;
    /**
     * This object contains all the methods for the materials API. See examples for usage.
     */
    readonly model: Model;
    /**
     * This property reports an array of strings, corresponding to variants in the loaded model that can be selected with variant-name.
     */
    readonly availableVariants: string[];
    /**
     * Returns a readonly copy of the GLTF JSON object as loaded. Changing this object has no affect on the scene and changes made through
     * the materials API are not reflected here. This object is useful for reverting individual changes made through the materials API.
     */
    readonly originalGltfJson: GLTF;
    /**
     * This static, writable property sets <model-viewer>'s DRACO decoder location URL. By default, the DRACO decoder will be loaded from a Google CDN.
     * @example https://modelviewer.dev/examples/loading/#dracoSupport
     */
    dracoDecoderLocation: string;
    /**
     * This static, writable property sets <model-viewer>'s KTX2 transcoder location URL. By default, the KTX2 transcoder will be loaded from a Google CDN.
     * @example https://modelviewer.dev/examples/loading/#ktx2Support
     */
    ktx2TranscoderLocation: string;
    /**
     * Rotates the model to the orientation specified by roll, pitch, yaw Euler angles, where yaw is first applied about the Y-axis, then pitch about the new local X-axis (positive is front-down), then roll about the new local Z-axis. If specified before the model loads, automatic camera framing will take this change into account; otherwise the updateFraming() method must be called manually.
     * Default Value: 0deg 0deg 0deg
     * Options: $roll $pitch $yaw
     */
    orientation: string;
    /**
     * Scales the model as specified in the X, Y, and Z directions. Scale is applied before orientation. If specified before the model loads, automatic camera framing will take this change into account; otherwise the updateFraming() method must be called manually.
     * Default Value: 1 1 1
     * Options: $x $y $z
     */
    scale: string;
    /**
     *
     */
    cameraOrbit: string;
    /**
     * Dismisses the poster, causing the model to load and render if necessary. This is currently effectively the same as interacting with the poster via user input.
     */
    dismissPoster(): void;
    /**
     * Shows the poster, hiding the model. If this is called after the 3D model has been revealed, then it will behave as though reveal='interaction', being dismissed either by a user click or a call to dismissPoster().
     */
    showPoster(): void;
    /**
     * Returns the model's bounding box dimensions in meters, independent of turntable rotation. The returned object has x, y, and z properties along with a toString() method.
     */
    getDimensions(): {
        x: number;
        y: number;
        z: number;
        toString(): string;
    };
    /**
     * Create your own Texture object.
     */
    createTexture(uri: string, type?: 'image/png' | 'image/jpeg' | 'image/webp'): Promise<Texture>;
    /**
     *
     * @param clientX
     * @param clientY
     * @return Material
     * Returns a material whose mesh primitive intersects with a ray created from the input pixel coordinates relative to the screen.
     * Returns the material whose mesh is nearest the camera.
     */
    materialFromPoint(clientX: Vector3, clientY: Vector3): Material;
    /**
     * Exports the glTF scene as a Blob object
     */
    exportScene(): Promise<Blob>;
    /**
     * Returns a screenshot of the current model render in the format specified by type (defaults to image/png). The screenshot is encoded
     * as a data URL string. In formats that support a sliding scale of quality (such as image/jpeg and image/webp) you can also specify a
     * value for encoderOptions between 0 and 1 (encoderOptions defaults to 0.92 otherwise).
     */
    toDataURL(type?: 'image/png' | 'image/jpeg' | 'image/webp', encoderOptions?: number): string;
    /**
     * Returns a promise that resolves into a Blob object in the format specified by the mimeType (defaults to image/png). A Blob object
     * represents a file-like object of immutable, raw data. You can also specify a value between 0 and 1 for qualityArgument (Currently
     * only available on Chrome desktop and Firefox) which defaults to 0.92 and 0.8 for image/png and image/webp respectively. By setting
     * idealAspect to true, the blob will be captured at the ideal poster aspect ratio instead of the canvas aspect ratio. This allows for
     * easy poster creation, where a single poster will match the render seamlessly at any canvas aspect ratio.
     * It is recommended to use a seamless webp poster image and set --poster-color to transparent and enable seamless-poster.
     */
    toBlob(options?: {
        mimeType?: 'image/png' | 'image/jpeg' | 'image/webp';
        qualityArgument?: number;
        idealAspect?: boolean;
    }): Promise<Blob>;
    /**
     * Recalculates the camera defaults in case the model has been changed, for instance by the orientation or scale attributes.
     */
    updateFraming(): void;
    /**
     * Resets the turntable that rotates the model when auto-rotate is enabled. The new value of the turntable rotation will be theta radians after this method is invoked, but the model may not update until the next render frame. If no argument is supplied, theta defaults to zero.
     */
    resetTurntableRotation(theta?: number): void;
    /**
     * Get the current camera phi, theta & radius
     */
    getCameraOrbit(): {
        phi: number;
        radius: number;
        theta: number;
        toString(): string;
    };
}

interface Model {
    /**
     * An ordered set of unique Materials found in this model. The Materials
     * correspond to the listing of materials in the glTF, with the possible
     * addition of a default material at the end.
     */
    readonly materials: Material[];

    // Returns the first material to whose name matches 'name'.
    getMaterialByName(name: string): Material | null;
}

interface Material {
    name: string;

    // Returns the glTF index of this material.
    readonly index: number;
    readonly normalTexture: TextureInfo | null;
    readonly occlusionTexture: TextureInfo | null;
    readonly emissiveTexture: TextureInfo | null;
    readonly emissiveFactor: RGB;
    readonly pbrMetallicRoughness: PBRMetallicRoughness;

    setEmissiveFactor(rgb: RGB): void;
    setAlphaCutoff(cutoff: number): void;
    getAlphaCutoff(): number;
    setDoubleSided(doubleSided: boolean): void;
    getDoubleSided(): boolean;
    setAlphaMode(alphaMode: AlphaMode): void;
    getAlphaMode(): AlphaMode;
}

interface PBRMetallicRoughness {
    readonly baseColorFactor: RGBA;
    readonly metallicFactor: number;
    readonly roughnessFactor: number;
    readonly baseColorTexture: TextureInfo | null;
    readonly metallicRoughnessTexture: TextureInfo | null;

    setBaseColorFactor(rgba: RGBA): void;
    setMetallicFactor(value: number): void;
    setRoughnessFactor(value: number): void;
}

interface TextureInfo {
    readonly texture: Texture | null;

    /**
     * Sets the texture, or removes it if argument is null. Note you cannot build
     * your own Texture object, but must either use one from another TextureInfo,
     * or create one with the createTexture method.
     */
    setTexture(texture: Texture | null): void;
}

interface Texture {
    name: string;
    readonly sampler: Sampler;
    readonly source: Image;
}

interface Sampler {
    readonly name: string;
    readonly minFilter: MinFilter;
    readonly maxFilter: MaxFilter;
    readonly wrapS: WrapMode;
    readonly wrapT: WrapMode;

    setMinFilter(filter: MinFilter): void;
    setMaxFilter(filter: MaxFilter): void;
    setWrapS(mode: WrapMode): void;
    setWrapT(mode: WrapMode): void;
}

interface Image {
    readonly name: string;

    /**
     * The type is 'external' if the image has a configured URI. Otherwise, it is
     * considered to be 'embedded'. Note: this distinction is only implied by the
     * glTF spec, and is made explicit here for convenience.
     */
    readonly type: 'embedded' | 'external';

    // The URI of the image, if it is external.
    readonly uri?: string;

    // The bufferView of the image, if it is embedded.
    readonly bufferView?: number;

    /**
     * A method to create an object URL of this image at the desired
     * resolution. Especially useful for KTX2 textures which are GPU compressed,
     * and so are unreadable on the CPU without a method like this.
     */
    createThumbnail(width: number, height: number): Promise<string>;
}

export type RGBA = [number, number, number, number];
export type RGB = [number, number, number];
type AlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';

enum WrapMode {
    ClampToEdge = 33071,
    MirroredRepeat = 33648,
    Repeat = 10497
}

enum MinFilter {
    Nearest = 9728,
    Linear = 9729,
    NearestMipmapNearest = 9984,
    LinearMipmapNearest = 9985,
    NearestMipmapLinear = 9986,
    LinearMipmapLinear = 9987
}

enum MaxFilter {
    Nearest = 9728,
    Linear = 9729
}