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 ()
	getDataBaseMaterialList ()
async	downloadAssetDatabase ()
	writeDatabaseToFile (filename)
	validateMaterialXDocument (doc)
	addComment (doc, commentString)
	getMaterialXString (doc)

Detailed Description

Definition at line 12 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 352 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 83 of file JsAmbientCGLoader.js.

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

clearDownloadMaterial()

AmbientCGLoader::clearDownloadMaterial

(

)

Clear any cached current material asset.

Definition at line 114 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 19 of file JsAmbientCGLoader.js.

                  {
        if (AmbientCGLoader.instance) {
            return AmbientCGLoader.instance;
        }
 
        this.logger = console;
        this.database = {};
        this.assets = {};
        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 286 of file JsAmbientCGLoader.js.

                                  {
 
        this.database = {};
        this.assets = null;
 
        const url = 'https://ambientcg.com/api/v2/full_json';
        const headers = { Accept: 'application/json' };
        const params = {
            method: 'PBRPhotogrammetry',
            type: 'Material',
            sort: 'Alphabet',
        };
 
        try {
            const response = await axios.get(url, { headers, params });
            if (response.status === 200) {
                this.database = response.data;
                this.assets = this.database.foundAssets;
            } else {
                this.logger.error(`Status: ${response.status}, ${response.data}`);
            }
        } catch (error) {
            this.logger.error(`Error downloading asset database: ${error}`);
        }
 
        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 140 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];
        console.log('>>>> URL:', url, 'Filename:', this.downloadMaterialFileName);
 
        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 218 of file JsAmbientCGLoader.js.

                                  {
 
        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}`);
                return this.materials;
            } catch (e) {
                this.logger.warn(`Failed to load AmbientCG materials cache: ${e.message}`);
            }
        }
 
        // 2. If not in cache, fetch from network
        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.');
                // 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}`);
                }
            } 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}`);
        }
 
        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 194 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 270 of file JsAmbientCGLoader.js.

                  {
 
        return this.database;
    }

getDataBaseMaterialList()

AmbientCGLoader::getDataBaseMaterialList

(

)

Get asset database material list.

Returns

{Array} Material list.

Definition at line 278 of file JsAmbientCGLoader.js.

                              {
 
        return this.assets;
    }

getDownloadedMaterialInformation()

AmbientCGLoader::getDownloadedMaterialInformation

(

)

Get the current downloaded material information.

Returns

{Object} The downloaded material information.

Definition at line 103 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 58 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 362 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 37 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 207 of file JsAmbientCGLoader.js.

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

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 50 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 93 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 332 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 317 of file JsAmbientCGLoader.js.

                                  {
 
        if (!this.database) {
            this.logger.warning('No database to write');
            return false;
        }
 
        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 124 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 73 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