Javascript class for querying materials from the Physically Based database and creating MaterialX materials. More...

Public Member Functions
	constructor (mtlx_module=null, mtlx_stdlib=null)
	Constructor for the PhysicallyBasedMaterialLoader.

	getJSON ()
	Get the Physically Based Materials as JSON.

	getJSONMaterialNames ()
	Get list of the Physically Based Material names.

	getMaterialXDocument ()
	Get the MaterialX document.

	validateDocument ()
	Validate the MaterialX document.

	getInputRemapping (shadingModel)
	Get the remapping keys for a given shading model.

	initializeInputRemapping ()
	Initialize the input remapping for different shading models.

	loadMaterialX ()
	Load the MaterialX module.

async	getPhysicallyBasedMaterials ()
	Get the Physically Based Materials from the API.

	loadStandardLibraries ()
	Load the MaterialX standard libraries.

	skipLibraryElement (element)
	Predicate to skip library elements.

	getMaterialXString ()
	Get the MaterialX document as a string.

	addComment (doc, commentString)
	Add a comment to the MaterialX document.

	convertToMaterialX (shaderCategory, addAllInputs=false, materialNames=[], remapKeys={}, shaderPreFix='')
	Convert the Physically Based Materials to MaterialX.

Public Attributes
	url = ''
	URL to fetch the Physically Based Materials.

	headers = {}
	Headers for the fetch operation.

	materials = null
	List of Physically Based Materials.

	materialNames = []
	List of Physically Based Material names.

	mxMaterialNames = []
	List of MaterialX Material names.

	mx = null
	MaterialX module.

	doc = null
	Working MaterialX document.

	stdlib = null
	MaterialX standard libraries.

	remapMap = {}
	Remap keys for input values for different shading models.

Detailed Description

Javascript class for querying materials from the Physically Based database and creating MaterialX materials.

Definition at line 8 of file JsMaterialXPhysicallyBased.js.

Member Function Documentation

◆ addComment()

JsPhysicallyBasedMaterialLoader::addComment	(		doc,
			commentString )

Add a comment to the MaterialX document.

Parameters

doc	- MaterialX document
commentString	- Comment string to add

Definition at line 298 of file JsMaterialXPhysicallyBased.js.

    {
        let comment = doc.addChildOfCategory('comment')
        comment.setDocString(commentString)
    }

◆ constructor()

JsPhysicallyBasedMaterialLoader::constructor	(		mtlx_module = null,
			mtlx_stdlib = null )

Constructor for the PhysicallyBasedMaterialLoader.

Returns: {void}

Definition at line 60 of file JsMaterialXPhysicallyBased.js.

    {
        this.url = 'https://api.physicallybased.info/materials';
        this.headers = { 'Accept': 'application/json' };
 
        this.materials = null;
        this.materialNames = [];
 
        this.mxMaterialNames = [];
        this.mx = null;
        if (mtlx_module) {
            this.mx = mtlx_module;
        }
        this.stdlib = null;
        if (mtlx_stdlib) {
            this.stdlib = mtlx_stdlib;
        }
        this.doc = null;
 
        this.initializeInputRemapping();
    }

◆ convertToMaterialX()

JsPhysicallyBasedMaterialLoader::convertToMaterialX	(	shaderCategory,
		addAllInputs = false,
		materialNames = [],
		remapKeys = {},
		shaderPreFix = '' )

Convert the Physically Based Materials to MaterialX.

Parameters

shaderCategory	- MaterialX shader category
addAllInputs	- Add all inputs from node definitions
materialNames	- List of material names to convert. If empty all materials are converted
remapKeys	- Remap keys to MaterialX shader inputs. If not specified the default remap keys are used if any.
shaderPreFix	- Prefix for the shader name. Default is empty

Returns: True if the conversion is successful. False otherwise

Definition at line 314 of file JsMaterialXPhysicallyBased.js.

                                                                                             {}, shaderPreFix = '') 
    {
        if (!this.mx) {
            console.error('MaterialX module is not loaded');
            return false;
        }
 
        if (!this.materials) {
            console.warn('No Physically Based Materials to convert');
            return false;
        }
 
        if (remapKeys.length == 0) {
            remapKeys = this.getInputRemapping(shaderCategory);
        }
 
        // Create a dummy doc with the surface shader with all inputs
        // as reference
        let refDoc = this.mx.createDocument();
        refDoc.importLibrary(this.stdlib);
        const refNode = refDoc.addNode(shaderCategory, 'refShader', this.mx.SURFACE_SHADER_TYPE_STRING);
        //refNode.addInputsFromNodeDef() -- This is missing from the JS API.
        this.doc = this.mx.createDocument();
 
        // Add header comments
        this.addComment(this.doc, 'Physically Based Materials from https://api.physicallybased.info ');
        this.addComment(this.doc, '  Processed via API and converted to MaterialX ');
        this.addComment(this.doc, '  Target Shading Model: ' + shaderCategory);
        this.addComment(this.doc, '  Utility Author: Bernard Kwok. kwokcb@gmail.com ');
 
        // Add properties to the material
        for (let i = 0; i < this.materials.length; i++) {
            const mat = this.materials[i];
            let matName = mat['name'];
 
            // Filter by material name(s)
            if (materialNames.length > 0 && !materialNames.includes(matName)) {
                // Skip material
                console.log('Skipping material:', matName);
                continue;
            }
 
 
            if (shaderPreFix.length > 0) {
                matName = shaderPreFix + '_' + matName;
            }
 
            const shaderName = this.doc.createValidChildName('SPB_' + matName);
            this.addComment(this.doc, ' Generated shader: ' + shaderName + ' ');
            const shaderNode = this.doc.addNode(shaderCategory, shaderName, this.mx.SURFACE_SHADER_TYPE_STRING);
            let docString = mat['description'];
            const refString = mat['reference'];
            if (refString.length > 0) {
                if (docString.length > 0) {
                    docString += '. ';
                }
                docString += 'Reference: ' + refString[0];
            }
            if (docString.length > 0) {
                shaderNode.setDocString(docString);
            }
 
            // Create a new material
            const materialName = this.doc.createValidChildName('MPB_' + matName);
            this.addComment(this.doc, ' Generated material: ' + materialName + ' ');
            const materialNode = this.doc.addNode(this.mx.SURFACE_MATERIAL_NODE_STRING, materialName, this.mx.MATERIAL_TYPE_STRING);
            const shaderInput = materialNode.addInput(this.mx.SURFACE_SHADER_TYPE_STRING, this.mx.SURFACE_SHADER_TYPE_STRING);
            shaderInput.setAttribute(MTLX_NODE_NAME_ATTRIBUTE, shaderNode.getName());
 
            // Warning this is a bit bespoke for remapping keys
            // to Autodesk Standard Surface shader inputs
            const skipKeys = ['name', "density", "category", "description", "sources", "tags", "reference"];
 
            let metallness = null;
            let roughness = null;
            let transmission_color = null;
            let transmission = null;
            Object.entries(mat).forEach(([key, value]) => {
 
                if (!skipKeys.includes(key)) {
 
                    if (key == 'metalness') {
                        metallness = value;
                        //console.log('Metalness:', metallness);
                    }
                    if (key == 'roughness') {
                        roughness = value;
                        //console.log('Roughness:', roughness);
                    }
                    if (key == 'transmission') {
                        transmission = value;
                        //console.log('Transmission:', transmission);
                    }
                    if (key == 'color') {
                        transmission_color = value;
                        //console.log('Color:', color);
                    }    
 
                    if (remapKeys[key]) {
                        key = remapKeys[key];
                    }
 
                    let refInput = refNode.getInput(key);
                    if (!refInput)
                        refInput = refNode.addInputFromNodeDef(key);
                    if (refInput) {
                        const input = shaderNode.addInput(key);
                        input.copyContentFrom(refInput);
                        if (input) {
                            // Convert number vector to string
                            if (Array.isArray(value)) {
                                value = value.join(',');
                            }
                            // Convert number to string
                            else if (typeof value === 'number') {
                                value = value.toString();
                            }
                            // Note: This API has side-effects as the
                            // type is set to "string" when the value is set. Thus
                            // we must explicitly set the type here.
                            input.setValueString(value, refInput.getType());
                        }
                    }
                    else {
                        //console.log('>>> Cannot create input:', key)
                    }
                }
            });
 
            if (transmission !== null && metallness !== null && roughness !== null && transmission_color !== null) 
            {
                if (metallness == 0 && roughness == 0) 
                {
                    if (remapKeys['transmission_color']) {
                        let inputName = remapKeys['transmission_color'];
                        let input = shaderNode.addInput(inputName);
                        if (input) {
                            let value = transmission_color.join(',');
                            console.log(`Add "${inputName}": "${value}"`);
                            input.setValueString(value, 'color3');
                        }
                    }
                }
            };                
        }
        return true;
    }

◆ getInputRemapping()

JsPhysicallyBasedMaterialLoader::getInputRemapping ( shadingModel )

Get the remapping keys for a given shading model.

Parameters

shadingModel - Shading model to get the remapping keys

Returns: Remapping keys for the shading model. Empty object if not found

Definition at line 130 of file JsMaterialXPhysicallyBased.js.

    {
        if (shadingModel in this.remapMap) {
            return this.remapMap[shadingModel];
        }
        return {};
    }

◆ getJSON()

JsPhysicallyBasedMaterialLoader::getJSON ( )

Get the Physically Based Materials as JSON.

Returns: {object[]} - List of Physically Based Materials

Definition at line 86 of file JsMaterialXPhysicallyBased.js.

    {
        return this.materials
    }

◆ getJSONMaterialNames()

JsPhysicallyBasedMaterialLoader::getJSONMaterialNames ( )

Get list of the Physically Based Material names.

Definition at line 94 of file JsMaterialXPhysicallyBased.js.

    {
        return this.materialNames
    }

◆ getMaterialXDocument()

JsPhysicallyBasedMaterialLoader::getMaterialXDocument ( )

Get the MaterialX document.

Definition at line 102 of file JsMaterialXPhysicallyBased.js.

    {
        return this.doc;
    }

◆ getMaterialXString()

JsPhysicallyBasedMaterialLoader::getMaterialXString ( )

Get the MaterialX document as a string.

Returns: {string} - MaterialX document as a string. Empty string if no document

Definition at line 275 of file JsMaterialXPhysicallyBased.js.

    {
        if (!this.doc) {
            console.error('No MaterialX document to convert');
            return '';
        }
 
        // Create write options
        const writeOptions = new this.mx.XmlWriteOptions();
        writeOptions.writeXIncludeEnable = false;
        //writeOptions.writeXIncludes = false;
        writeOptions.elementPredicate = this.skipLibraryElement;
 
        // Convert the MaterialX document to a string
        const mtlx = this.mx.writeToXmlString(this.doc, writeOptions);
        return mtlx;
    }

◆ getPhysicallyBasedMaterials()

async JsPhysicallyBasedMaterialLoader::getPhysicallyBasedMaterials ( )

Get the Physically Based Materials from the API.

Returns: {object[]} - List of Physically Based Materials in JSON format

Definition at line 208 of file JsMaterialXPhysicallyBased.js.

    {
        try {
            this.materials = null
            this.materialNames = [];
 
            const response = await fetch(this.url, {
                method: 'GET',
                headers: this.headers
            });
 
            if (!response.ok) {
                throw new Error('Network response was not ok ' + response.statusText);
            }
 
            this.materials = await response.json();
            for (let i = 0; i < this.materials.length; i++) {
                this.materialNames.push(this.materials[i]['name']);
            }
            return this.materials;
        } catch (error) {
            console.error('There has been a problem with your fetch operation:', error);
        }
 
        return null;
    }

◆ initializeInputRemapping()

JsPhysicallyBasedMaterialLoader::initializeInputRemapping ( )

Initialize the input remapping for different shading models.

Returns: {void}

Definition at line 142 of file JsMaterialXPhysicallyBased.js.

    {
        // Remap keys for Autodesk Standard Surface shader. How to verify this?
        const standard_surface_remapKeys = {
            'color': 'base_color',
            'specularColor': 'specular_color',
            'roughness': 'specular_roughness',
            //'metalness': 'metalness',
            'ior': 'specular_IOR',
            //'transmission': 'transmission',
            'transmission_color': 'transmission_color',
            'thinFilmIor': 'thin_film_IOR',
            'thinFilmThickness': 'thin_film_thickness',
            'transmissionDispersion': 'transmission_dispersion',
        }
        // Remap keys for OpenPBR shading model.
        const openpbr_remapKeys = {
            'color': 'base_color',
            'specularColor': 'specular_color',
            'roughness': 'specular_roughness', // 'base_diffuse_roughness',
            'metalness': 'base_metalness',
            'ior': 'specular_ior',
            'transmission': 'transmission_weight',
            'transmission_color': 'transmission_color',
            'subsurfaceRadius': 'subsurface_radius',
            'thinFilmIor': 'thin_film_ior',
            'thinFilmThickness': 'thin_film_thickness',
            'transmissionDispersion': 'transmission_dispersion_scale',
        }
        // Remap keys for Khronos glTF shading model.
        const gltf_remapKeys = {
            'color': 'base_color',
            'specularColor': 'specular_color',
            'roughness': 'roughness',
            'metalness': 'metallic',
            'transmission_color': 'attenuation_color',
            //'ior': 'ior',
            //'transmission': 'transmission',
        }
 
        this.remapMap = {}
        this.remapMap['standard_surface'] = standard_surface_remapKeys;
        this.remapMap['gltf_pbr'] = gltf_remapKeys;
        this.remapMap['open_pbr_surface'] = openpbr_remapKeys;
    }

◆ loadMaterialX()

JsPhysicallyBasedMaterialLoader::loadMaterialX ( )

Load the MaterialX module.

Returns: {Promise} - Promise to load the MaterialX module

Definition at line 192 of file JsMaterialXPhysicallyBased.js.

    {
        return new Promise((resolve, reject) => {
            MaterialX().then((mtlx) => {
                this.mx = mtlx;
                resolve();
            }).catch((error) => {
                reject(error);
            });
        });
    }

◆ loadStandardLibraries()

JsPhysicallyBasedMaterialLoader::loadStandardLibraries ( )

Load the MaterialX standard libraries.

Returns: {void}

Definition at line 239 of file JsMaterialXPhysicallyBased.js.

    {
        if (!this.mx) {
            // Call the asynchronous function and then perform additional logic
            this.loadMaterialX().then(() => {
 
                this.esslgenerator = new this.mx.EsslShaderGenerator();
                this.esslgenContext = new this.mx.GenContext(this.esslgenerator);
                this.stdlib = this.mx.loadStandardLibraries(this.esslgenContext);
                let children = this.stdlib.getChildren();
                for (let i = 0; i < children.length; i++) {
                    let child = children[i];
                    child.setSourceUri('STDLIB_ELEMENT');
                }
 
                console.log("MaterialX is loaded");
            }).catch((error) => {
                console.error("Error loading MaterialX:", error);
            });
        }
    }

◆ skipLibraryElement()

JsPhysicallyBasedMaterialLoader::skipLibraryElement ( element )

Predicate to skip library elements.

Parameters

element - MaterialX element

Returns: True if the element is a library element. False otherwise

Definition at line 266 of file JsMaterialXPhysicallyBased.js.

    {
        return !elem.hasSourceUri()
    }

◆ validateDocument()

JsPhysicallyBasedMaterialLoader::validateDocument ( )

Validate the MaterialX document.

Returns: {[boolean, errors]} - True if the document is valid. False otherwise

Definition at line 111 of file JsMaterialXPhysicallyBased.js.

    {
        if (this.doc) {
            let errors = {}
            let errorString = ''
            var valid = this.doc.validate(errors);
            if (!valid) {
                errorString = errors.message;
            }
            return [valid, errorString]
        }
        return [false, 'No MaterialX document'];
    }