JsPhysicallyBasedMaterialLoader Class Reference

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.
	getInputRemappingMap ()
	Get remmapping map.
	setDefaultRemapKeys ()
	Set the default remapping keys for different shading models : glTF, OpenPBR, and Autodesk Standard Surface.
	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.
	getReferenceList ()
	Return a sorted list reference names mapped reference images.
	convertToMaterialX (shaderCategory, references, 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 351 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,
			references,
			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
references	- List of references found. (returned). Each reference is a object: { name: string, reference: string }

Returns

True if the conversion is successful. False otherwise

Definition at line 395 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 (Object.keys(remapKeys).length === 0)
        {
            remapKeys = this.getInputRemapping(shaderCategory);
        }
        //console.log('Using remap keys for shading model:', shaderCategory, remapKeys);
 
        // 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);
        if (addAllInputs) {
            console.warn('MaterialX JS API missing addInputsFromNodeDef()');
            //refNode.addInputsFromNodeDef() -- This is missing from the JS API.
        }
        this.doc = this.mx.createDocument();
 
        // Add document level accreditation
        let docString = 'Physically Based Materials from https://api.physicallybased.info.\n'
        docString += '  Content Author: Anton Palmqvist, https://antonpalmqvist.com/ \n'
        docString += `  Content processsed via REST API and mapped to MaterialX V${this.mx.getVersionString()} \n`
        docString +=  `  Target Shading Model: ${shaderCategory} \n`
        docString +=  '  Utility Author: Bernard Kwok. kwokcb@gmail.com '  
        this.doc.setDocString(docString);
 
        // 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)
            let skipGeneration = materialNames.length > 0 && !materialNames.includes(matName);
 
            let shaderNode = null;
            if (!skipGeneration) 
            {
                if (shaderPreFix.length > 0) {
                    matName = shaderPreFix + '_' + matName;
                }
 
                const shaderName = this.doc.createValidChildName(matName + '_' + shaderCategory + '_SPB');
                this.addComment(this.doc, ' Generated shader: ' + matName + ' ');
                shaderNode = this.doc.addNode(shaderCategory, shaderName, this.mx.SURFACE_SHADER_TYPE_STRING);
 
                const category = mat['category'];
                const group = mat['group'];
                let uifolder = '';
                if (category && category.length > 0) {
                    uifolder = category[0];
                }
                if (group && group.length > 0) {
                    if (uifolder.length > 0) {
                        uifolder += '/';
                    }
                    uifolder += group[0];
                }
                if (uifolder.length > 0) {
                    shaderNode.setAttribute('uifolder', uifolder);
                }
 
                let docString = ''
                if (mat['description'].length > 0) {
                    docString += 'Description: ' + mat['description'];
                }
            }
 
            // Always want to build the ference
            const refString = mat['reference'];
            if (refString.length > 0) {
                if (docString.length > 0) {
                    docString += '. ';
                }
                docString += 'Reference: ' + refString[0];
 
                let referenceItem = { name: matName, reference: refString[0] };
                //console.log('Add Reference:', referenceItem);
                references.push(referenceItem);
            }
            // Sort references by name
            references.sort((a, b) => a.name.localeCompare(b.name));
 
            if (!shaderNode) {
                continue;
            }
            if (docString.length > 0) {
                shaderNode.setDocString(docString);
            }
 
            // Create a new material
            const materialName = this.doc.createValidChildName(matName + '_' + shaderCategory + '_MPB');
            this.addComment(this.doc, ' Generated material: ' + matName + ' ');
            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)) {
 
                    //console.log(`-- Processing key: "${key}" with value:`, value);
 
                    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);
                    }    
 
                    //console.log(`-- Remapping key "${key}" to "${remapKeys[key]}"`);
                    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('>> Could not map input:', key, 'to node definition')
                    }
                }
            });
 
            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];
        }
        else
        {
            console.warn('>> No remap keys for shading model:', shadingModel);
        }
        return {};
    }

getInputRemappingMap()

JsPhysicallyBasedMaterialLoader::getInputRemappingMap

(

)

Get remmapping map.

Returns

{object} - Remapping map

Definition at line 146 of file JsMaterialXPhysicallyBased.js.

    {
        return this.remapMap;
    }

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 328 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 261 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;
    }

getReferenceList()

JsPhysicallyBasedMaterialLoader::getReferenceList

(

)

Return a sorted list reference names mapped reference images.

Returns

{object[]} - List of references.

Definition at line 362 of file JsMaterialXPhysicallyBased.js.

    {
        let references = [];
        if (this.materials) {
            for (let i = 0; i < this.materials.length; i++) {
                const mat = this.materials[i];
                const matName = mat['name'];
                const refString = mat['reference']; 
                const tags = mat['tags'];
                const category = mat['category'];
                if (refString.length > 0)
                {
                    let referenceItem = { name: matName, reference: refString[0], tags: tags, category: category };
                    //console.log('Add Reference:', referenceItem);
                    references.push(referenceItem);
                }
            }
            // Sort references by name
            references.sort((a, b) => a.name.localeCompare(b.name));
        }
        return references;
    }

initializeInputRemapping()

JsPhysicallyBasedMaterialLoader::initializeInputRemapping

(

)

Initialize the input remapping for different shading models.

Returns

{void}

Definition at line 209 of file JsMaterialXPhysicallyBased.js.

    {
        console.log('Initializing input remapping for Physically Based Materials...');
        this.remapMap = null;
 
        const remapKeyURL = 'https://raw.githubusercontent.com/kwokcb/materialxMaterials/refs/heads/main/src/materialxMaterials/data/PhysicallyBasedMaterialX/PhysicallyBasedToMtlxMappings.json';
 
        fetch(remapKeyURL)
            .then((response) => 
            {
                if (!response.ok) {
                    console.warn(`HTTP error! Status: ${response.status}`);
                    return null;
                }
                return response.json();
            })
            .then((data) => {
                if (data) {
                    this.remapMap = data;
                    console.log('- Remap keys loaded from repo:', this.remapMap);
                } else {
                    console.warn('- No remap keys from repo. Using default remap keys.');
                    this.setDefaultRemapKeys();
                }
            })
            .catch((error) => {
                console.log('- Error loading remap keys:', error);
                this.setDefaultRemapKeys();
                console.warn('- Using default remap keys.', this.remapMap);
            });
    }

loadMaterialX()

JsPhysicallyBasedMaterialLoader::loadMaterialX

(

)

Load the MaterialX module.

Returns

{Promise} - Promise to load the MaterialX module

Definition at line 245 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 292 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.create();
                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);
            });
        }
    }

setDefaultRemapKeys()

JsPhysicallyBasedMaterialLoader::setDefaultRemapKeys

(

)

Set the default remapping keys for different shading models : glTF, OpenPBR, and Autodesk Standard Surface.

Returns

{void}

Definition at line 155 of file JsMaterialXPhysicallyBased.js.

    {
        const standard_surface_remapKeys = {
            "color": "base_color",
            "specularColor": "specular_color",
            "roughness": "specular_roughness",
            "metalness": "metalness",
            "ior": "specular_IOR",
            "subsurfaceRadius": "subsurface_radius",
            "transmission": "transmission",
            "transmission_color": "transmission_color",
            "transmissionDispersion": "transmission_dispersion",
            "thinFilmThickness": "thin_film_thickness",
            "thinFilmIor": "thin_film_IOR"
        };
 
        const openpbr_remapKeys = {
            "color": "base_color",
            "specularColor": "specular_color",
            "roughness": "specular_roughness",
            "metalness": "base_metalness",
            "ior": "specular_ior",
            "subsurfaceRadius": "subsurface_radius",
            "transmission": "transmission_weight",
            "transmission_color": "transmission_color",
            "transmissionDispersion": "transmission_dispersion_abbe_number",
            "thinFilmThickness": "thin_film_thickness",
            "thinFilmIor": "thin_film_ior"
        };
 
        const gltf_remapKeys = {
            "color": "base_color",
            "specularColor": "specular_color",
            "roughness": "roughness",
            "metalness": "metallic",
            "ior": "ior",
            "transmission": "transmission",
            "transmission_color": "attenuation_color",
            "thinFilmThickness": "iridescence_thickness",
            "thinFilmIor": "iridescence_ior"
        };
 
        this.remapMap = {
            'standard_surface': standard_surface_remapKeys,
            'gltf_pbr': gltf_remapKeys,
            'open_pbr_surface': openpbr_remapKeys
        };
    }

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 319 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'];
    }

Member Data Documentation

doc

JsPhysicallyBasedMaterialLoader::doc = null

Working MaterialX document.

Definition at line 43 of file JsMaterialXPhysicallyBased.js.

headers

JsPhysicallyBasedMaterialLoader::headers = {}

Headers for the fetch operation.

Definition at line 18 of file JsMaterialXPhysicallyBased.js.

{};

materialNames

JsPhysicallyBasedMaterialLoader::materialNames = []

List of Physically Based Material names.

Definition at line 28 of file JsMaterialXPhysicallyBased.js.

materials

JsPhysicallyBasedMaterialLoader::materials = null

List of Physically Based Materials.

Definition at line 23 of file JsMaterialXPhysicallyBased.js.

mx

JsPhysicallyBasedMaterialLoader::mx = null

MaterialX module.

Definition at line 38 of file JsMaterialXPhysicallyBased.js.

mxMaterialNames

JsPhysicallyBasedMaterialLoader::mxMaterialNames = []

List of MaterialX Material names.

Definition at line 33 of file JsMaterialXPhysicallyBased.js.

remapMap

JsPhysicallyBasedMaterialLoader::remapMap = {}

Remap keys for input values for different shading models.

Definition at line 53 of file JsMaterialXPhysicallyBased.js.

{};

stdlib

JsPhysicallyBasedMaterialLoader::stdlib = null

MaterialX standard libraries.

Definition at line 48 of file JsMaterialXPhysicallyBased.js.

url

JsPhysicallyBasedMaterialLoader::url = ''

URL to fetch the Physically Based Materials.

Definition at line 13 of file JsMaterialXPhysicallyBased.js.

---

The documentation for this class was generated from the following file:

• JsMaterialXPhysicallyBased.js