AmbientCGLoader Class Reference

Public Member Functions
	constructor ()
	Class to load materials from the AmbientCG site.
	loadMaterialsFromCache ()
	setDebugging (debug=true)
	getMaterialNames (key='assetId')
	writeMaterialList (materialList, filename)
	buildDownloadAttribute (imageFormat='PNG', imageResolution='1')
	splitDownloadAttribute (downloadAttribute)
	getDownloadedMaterialInformation ()
	clearDownloadMaterial ()
	writeDownloadedMaterialToFile (path='')
async	downloadMaterialAsset (assetId, imageFormat='PNG', imageResolution='1', downloadAttributeKey='downloadAttribute', downloadLinkKey='downloadLink')
	findMaterial (assetId, key='assetId')
	loadMaterialsList (fileName)
async	downloadMaterialsList ()
	getDataBase ()
async	downloadAssetDatabase ()
	writeDatabaseToFile (filename)
	readDatabaseFromFile (filename)
	validateMaterialXDocument (doc)
	addComment (doc, commentString)
	getMaterialXString (doc)

Detailed Description

Definition at line 10 of file JsAmbientCGLoader.js.

Member Function Documentation

addComment()

AmbientCGLoader::addComment	(		doc,
			commentString )

Add a comment to the MaterialX document.

Parameters

{Object}	doc - The MaterialX document to add the comment to.
{string}	commentString - The comment string to add.

Definition at line 446 of file JsAmbientCGLoader.js.

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

buildDownloadAttribute()

AmbientCGLoader::buildDownloadAttribute	(		imageFormat = 'PNG',
			imageResolution = '1' )

Build the download attribute string for a given image format and resolution.

Parameters

{string}	imageFormat - The image format to download.
{string}	imageResolution - The image resolution to download.

Returns

{string} The download attribute string.

Definition at line 80 of file JsAmbientCGLoader.js.

                                                                   {
        return `${imageResolution}K-${imageFormat}`;
    }

clearDownloadMaterial()

AmbientCGLoader::clearDownloadMaterial

(

)

Clear any cached current material asset.

Definition at line 111 of file JsAmbientCGLoader.js.

                            {
        if (this.downloadMaterial) {
            this.downloadMaterial = null;
        }
        this.downloadMaterialFileName = '';
    }

constructor()

AmbientCGLoader::constructor

(

)

Class to load materials from the AmbientCG site.

The class can convert the materials to MaterialX format for given target shading models.

Parameters

{Object}	mxModule - The MaterialX module. Required.
{Object}	mxStdlib - The MaterialX standard library. Optional.

Definition at line 17 of file JsAmbientCGLoader.js.

                  {
        if (AmbientCGLoader.instance) {
            return AmbientCGLoader.instance;
        }
 
        this.logger = console;
        this.database = {};
        this.materials = null;
        this.materialNames = [];
        this.csvMaterials = null;
        this.downloadMaterial = null;
        this.downloadMaterialFileName = '';
 
        // Cache the instance
        AmbientCGLoader.instance = this;
    }

downloadAssetDatabase()

async AmbientCGLoader::downloadAssetDatabase

(

)

Download the asset database for materials from the ambientCG site.

Returns

{Object} The downloaded database.

Definition at line 306 of file JsAmbientCGLoader.js.

                                  {
        this.database = {};
 
        haveDatabase = false;
        const MATERIALS_DATABASE_FILE = 'ambientcg_database.json';
        if (fs.existsSync(MATERIALS_DATABASE_FILE)) {
            try {
                const data = fs.readFileSync(MATERIALS_DATABASE_FILE, 'utf8');
                this.database = JSON.parse(data);
                this.logger.info(`Loaded AmbientCG database from file: ${MATERIALS_DATABASE_FILE}`);
                haveDatabase = true;
            } catch (e) {
                this.logger.warn(`Failed to load AmbientCG database from file: ${e.message}`);
            }
        }
 
        if (!haveDatabase) {
 
            const limit = 500
            //https://ambientcg.com/api/v2/full_json?type=material
            const headers = { Accept: 'application/json' };
            let url = new URL('https://ambientcg.com/api/v2/full_json');
            url.searchParams.append('method', 'PBRPhotogrammetry');
            url.searchParams.append('type', 'Material');
            url.searchParams.append('sort', 'Alphabet');        
            url.searchParams.append('limit', limit);
            url.searchParams.append('offset', 0);
            url.searchParams.append('include', 'tagData,previewData')
 
            let numberOfResults = -1;
            let offset = 0
 
            //let data_list = []
            let asset_list = []
            while (numberOfResults === -1 || offset < numberOfResults) {
                this.logger.info(`Downloading asset database from: ${url.toString()}`);
 
                try {
                    const response = await fetch(url, { headers });
                    if (response.status === 200) {
                        const data = await response.json();
                        this.logger.info(`Downloaded data at offset ${offset}. ${data.foundAssets.length} assets found.`);
                        //data_list.push(data);
 
                        // Only keep desired fiels: displayCategory, previewImage, tags and assetId from each entry
                        let reduced_assets = data.foundAssets.map(asset => {
                            return {
                                assetId: asset.assetId,
                                displayCategory: asset.displayCategory,
                                previewImage: asset.previewImage,
                                tags: asset.tags
                            }
                        });
                        asset_list = asset_list.concat(reduced_assets);
 
                        if (numberOfResults === -1) {
                            numberOfResults = data.numberOfResults;
                        }
                        // Update offset for next page
                        if (!data.nextPageHttp) 
                        {
                            break;
                        }
                        offset = offset + limit;
                        
                        url.searchParams.set('offset', offset);
                    } else {
                        this.logger.error(`Status: ${response.status}, ${response.data}`);
                    }
                }
                catch (error) {
                    this.logger.error(`Error downloading asset database: ${error}`);
                }
            }
 
            this.database = asset_list;
 
            // Pull out the preview image link from database and put it
            // into the materials. 
        }
 
        return this.database;
    }

downloadMaterialAsset()

async AmbientCGLoader::downloadMaterialAsset	(		assetId,
			imageFormat = 'PNG',
			imageResolution = '1',
			downloadAttributeKey = 'downloadAttribute',
			downloadLinkKey = 'downloadLink' )

Download a material with a given id and format + resolution for images.

Parameters

{string}	assetId - The string id of the material.
{string}	imageFormat - The image format to download. Default is PNG.
{string}	imageResolution - The image resolution to download. Default is 1.
{string}	downloadAttributeKey - The download attribute key. Default is 'downloadAttribute'.
{string}	downloadLinkKey - The download link key. Default is 'downloadLink'.

Returns

{string} File name of downloaded content.

Definition at line 137 of file JsAmbientCGLoader.js.

                                                                                                                                                           {
        this.clearDownloadMaterial();
 
        const items = this.findMaterial(assetId);
        const target = this.buildDownloadAttribute(imageFormat, imageResolution);
        let url = '';
        let downloadAttribute = '';
 
        items.forEach(item => {
            downloadAttribute = item[downloadAttributeKey];
            if (downloadAttribute === target) {
                url = item[downloadLinkKey];
                this.logger.info(`Found Asset: ${assetId}. Download Attribute: ${downloadAttribute} -> ${url}`);
            }
        });
 
        if (!url) {
            this.logger.error(`No download link found for asset: ${assetId}, attribute: ${target}`);
            return '';
        }
 
        this.downloadMaterialFileName = url.split('file=')[1];
 
        try {
            const response = await fetch(url);
            if (!response.ok) {
                throw new Error(`HTTP error! Status: ${response.status}`);
            }
        
            // Get the response as an ArrayBuffer
            const arrayBuffer = await response.arrayBuffer();
        
            // Convert ArrayBuffer to Buffer
            this.downloadMaterial = Buffer.from(arrayBuffer);
            this.logger.info(`Material file downloaded: ${this.downloadMaterialFileName}`);
 
        } catch (error) {
            this.downloadMaterialFileName = '';
            this.logger.error(`Error occurred while downloading the file: ${error}`);
        }
 
        return this.downloadMaterialFileName;
    }

downloadMaterialsList()

async AmbientCGLoader::downloadMaterialsList

(

)

Download the list of materials from the ambientCG site.

Returns

{Array} Materials list.

Definition at line 214 of file JsAmbientCGLoader.js.

                                  {
        let haveMaterials = false;
        const MATERIALS_CACHE_FILE = 'ambientcg_materials.json';
        // 1. Try to load from cache file
        if (fs.existsSync(MATERIALS_CACHE_FILE)) {
            try {
                const data = fs.readFileSync(MATERIALS_CACHE_FILE, 'utf8');
                this.materials = JSON.parse(data);
                this.logger.info(`Loaded AmbientCG materials from cache: ${MATERIALS_CACHE_FILE}`);
                haveMaterials = true;   
            } catch (e) {
                this.logger.warn(`Failed to load AmbientCG materials cache: ${e.message}`);
            }
        }
 
        // 2. If not in cache, fetch from network
        if (!haveMaterials)
        {
            const headers = { Accept: 'application/csv' };
            const url = new URL('https://ambientCG.com/api/v2/downloads_csv');
            url.searchParams.append('method', 'PBRPhotogrammetry');
            url.searchParams.append('type', 'Material');
            url.searchParams.append('sort', 'Alphabet');
 
            this.logger.info('Downloading materials CSV list from network...');
            try {
                const response = await fetch(url, { headers });
                if (response.status === 200) {
                    const csvContent = await response.text();
                    this.csvMaterials = csvContent;
                    this.materials = parse(csvContent, { columns: true });
                    this.logger.info('Downloaded CSV material list as JSON.');
                } else {
                    this.materials = null;
                    this.logger.warning(`Failed to fetch the CSV material content. HTTP status code: ${response.status}`);
                }
            } catch (error) {
                this.materials = null;
                this.logger.error(`Error downloading materials list: ${error}`);
            }
 
            // Read database list from file.
            this.readDatabaseFromFile('ambientcg_database.json');
            const have_database = this.database && Object.keys(this.database).length > 0;
            if (have_database) {
                for (let material of this.materials) {
                    const assetId = material.assetId;
                    const databaseEntry = this.database.find(entry => entry.assetId === assetId);
                    if (databaseEntry) {
                        // Get "256-PNG" from previewImage (object, not Map)
                        let preview = '';
                        if (databaseEntry.previewImage && typeof databaseEntry.previewImage === 'object') {
                            preview = databaseEntry.previewImage['256-PNG'] || '';
                        }
                        material.displayCategory = databaseEntry.displayCategory;
                        material.previewImage = preview;
                        material.tags = databaseEntry.tags;
                    }
                    else {
                        this.logger.warn('No database entry found for assetId:', assetId);
                    }
            
                }
            }
 
            // Save to cache file after fetching
            try {
                fs.writeFileSync(MATERIALS_CACHE_FILE, JSON.stringify(this.materials, null, 2));
                this.logger.info(`Saved AmbientCG materials to cache: ${MATERIALS_CACHE_FILE}`);
            } catch (e) {
                this.logger.warn(`Failed to write AmbientCG materials cache: ${e.message}`);
            }
        }
 
        //console.log('>>> WRITE MATERIALS TO FILE:', this.materials.length);
        //this.writeMaterialList(this.materials, 'ambientcg_materials.json');
 
        return this.materials;
    }

findMaterial()

AmbientCGLoader::findMaterial	(		assetId,
			key = 'assetId' )

Get the list of materials matching a material identifier.

Parameters

{string}	assetId - Material string identifier.
{string}	key - The key to lookup asset identifiers. Default is 'assetId'.

Returns

{Array} List of materials, or empty array if not found.

Definition at line 190 of file JsAmbientCGLoader.js.

                                         {
        if (this.materials) {
            return this.materials.filter(item => item[key] === assetId);
        }
        return [];
    }

getDataBase()

AmbientCGLoader::getDataBase

(

)

Get asset database.

Returns

{Object} Asset database.

Definition at line 298 of file JsAmbientCGLoader.js.

                  {
        return this.database;
    }

getDownloadedMaterialInformation()

AmbientCGLoader::getDownloadedMaterialInformation

(

)

Get the current downloaded material information.

Returns

{Object} The downloaded material information.

Definition at line 100 of file JsAmbientCGLoader.js.

                                       {
        return {
            filename: this.downloadMaterialFileName,
            content: this.downloadMaterial
        };
    }

getMaterialNames()

AmbientCGLoader::getMaterialNames

(

key = 'assetId'

)

Get the list of material names.

Parameters

{string}

key - The key to use for the material name. Default is 'assetId'.

Returns

{Array} The list of material names.

Definition at line 55 of file JsAmbientCGLoader.js.

                                    {
        this.materialNames = [];
        const uniqueNames = new Set();
        if (this.materials) {
            this.materials.forEach(item => uniqueNames.add(item[key]));
        }
        this.materialNames = Array.from(uniqueNames).sort();
        return this.materialNames;
    }

getMaterialXString()

AmbientCGLoader::getMaterialXString

(

doc

)

Convert the MaterialX document to a string.

Parameters

{Object}

doc - The MaterialX document to convert.

Returns

{string} The MaterialX document as a string.

Definition at line 456 of file JsAmbientCGLoader.js.

                            {
        if (!this.mx) {
            this.logger.error('MaterialX module is required');
            return;
        }
 
        const writeOptions = this.mx.XmlWriteOptions();
        writeOptions.writeXIncludeEnable = false;
        writeOptions.elementPredicate = this.skipLibraryElement;
        return this.mx.writeToXmlString(doc, writeOptions);
    }

loadMaterialsFromCache()

AmbientCGLoader::loadMaterialsFromCache

(

)

Definition at line 34 of file JsAmbientCGLoader.js.

                             {
        const MATERIALS_CACHE_FILE = 'ambientcg_materials.json';
        if (fs.existsSync(MATERIALS_CACHE_FILE)) {
            try {
                const data = fs.readFileSync(MATERIALS_CACHE_FILE, 'utf8');
                this.materials = JSON.parse(data);
                this.logger.info(`Loaded AmbientCG materials from cache: ${MATERIALS_CACHE_FILE}`);
            } catch (e) {
                this.logger.warn(`Failed to load AmbientCG materials cache: ${e.message}`);
            }
        }
    }

loadMaterialsList()

AmbientCGLoader::loadMaterialsList

(

fileName

)

Load in the list of downloadable materials from file.

Parameters

{string}

fileName - Name of JSON containing list.

Returns

{Array} Materials list.

Definition at line 203 of file JsAmbientCGLoader.js.

                                {
        this.materials = JSON.parse(fs.readFileSync(fileName, 'utf8'));
        this.logger.info(`Loaded materials list from: ${fileName}`);
        return this.materials;
    }

readDatabaseFromFile()

AmbientCGLoader::readDatabaseFromFile

(

filename

)

Read the database file.

Parameters

{string}

filename - The filename to read the JSON file from.

Returns

{Object} The database object, or null if there was an error.

Definition at line 410 of file JsAmbientCGLoader.js.

                                   {
        try {
            const data = fs.readFileSync(filename, 'utf8');
            this.database = JSON.parse(data);
            return this.database;
        } catch (e) {
            this.logger.error(`Failed to read database from file: ${e.message}`);
            return null;
        }
    }

setDebugging()

AmbientCGLoader::setDebugging

(

debug = true

)

Set the debugging level for the logger.

Parameters

{boolean}

debug - True to set the logger to debug level, otherwise False.

Definition at line 47 of file JsAmbientCGLoader.js.

                             {
        this.logger.level = debug ? 'debug' : 'info';
    }

splitDownloadAttribute()

AmbientCGLoader::splitDownloadAttribute

(

downloadAttribute

)

Split the download attribute into image format and resolution.

Parameters

{string}

downloadAttribute - The download attribute string.

Returns

{Array} A tuple of (imageFormat, imageResolution).

Note

The download attribute is in the format: '1K-PNG'.

Definition at line 90 of file JsAmbientCGLoader.js.

                                              {
        const parts = downloadAttribute.split('-');
    }

validateMaterialXDocument()

AmbientCGLoader::validateMaterialXDocument

(

doc

)

Validate the MaterialX document.

Parameters

{Object}

doc - The MaterialX document to validate.

Returns

{Array} A tuple of (valid, errors) where valid is True if the document is valid, and errors is a list of errors if the document is invalid.

Definition at line 426 of file JsAmbientCGLoader.js.

                                   {
        if (!this.mx) {
            this.logger.error('MaterialX module is required');
            return [false, ''];
        }
 
        if (!doc) {
            this.logger.warning('MaterialX document is required');
            return [false, ''];
        }
 
        const valid = doc.validate();
        return [valid, valid ? '' : 'Validation failed'];
    }

writeDatabaseToFile()

AmbientCGLoader::writeDatabaseToFile

(

filename

)

Write the database file.

Parameters

{string}

filename - The filename to write the JSON file to.

Returns

{boolean} True if the file was written successfully, otherwise False.

Definition at line 394 of file JsAmbientCGLoader.js.

                                  {
        if (!this.database) {
            this.logger.info('No database to write');
            return false;
        }
 
        this.logger.info(`Writing database to file: ${filename}`);
        fs.writeFileSync(filename, JSON.stringify(this.database, null, 4));
        return true;
    }

writeDownloadedMaterialToFile()

AmbientCGLoader::writeDownloadedMaterialToFile

(

path = ''

)

Write the currently downloaded file to file.

Parameters

{string}

path - The output path for the material. Default is empty.

Definition at line 121 of file JsAmbientCGLoader.js.

                                           {
        const haveDownload = this.downloadMaterialFileName && this.downloadMaterial;
        if (!haveDownload) {
            this.logger.warning('No current material downloaded');
            return;
        }
 
        const filename = `${path}/${this.downloadMaterialFileName}`;
        fs.writeFileSync(filename, this.downloadMaterial);
        this.logger.info(`Saved downloaded material to: ${filename}`);
    }

writeMaterialList()

AmbientCGLoader::writeMaterialList	(		materialList,
			filename )

Write the material list in JSON format to a file.

Parameters

{Array}	materialList - The list of materials to write.
{string}	filename - The file path to write the list to.

Definition at line 70 of file JsAmbientCGLoader.js.

                                              {
        this.logger.info(`Writing material list to file: ${filename}`);
        fs.writeFileSync(filename, JSON.stringify(materialList, null, 4));
    }

---

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

• JsAmbientCGLoader.js