Package: materialxgltf
materialxgltfContentsIntroductionInstallationUsageDocumentationIntroductionThis package supports the bi-directional translation between MaterialX materials and glTF materials. The minimum version of MaterialX required is 1.38 8 and the target glTF version is 2.0.1.See thehome pagefor this project.Below is an example of converting the "Damaged Helmet" asset (found in theglTF Sample Model repository) to MaterialX and previewing.The functionality found here is equivalent to the C++ module available inthis repository. Note that additional documentation can be found on that site.InstallationThe minimum version of Python is assumed to be 3.9.The package hosted onPyPican be installed usingpip:pipinstallmaterialxgltfor thesource repositorycan be cloned and the package built from the command line:py-mbuildThis will build a distribution folder calleddistwhich contains
a zip file which can be installed using:pip--install<nameofzip>RequirementsRequires the installation of the following packages:materialxversion 1.38.8 or higher: For editing MaterialX documents.pygltflib: For conversion fromglTFtoglbincluding packaging dependent geometry and image resources.DocumentationFor more detailed information about the workflow this package supports, please refer to thisdocumentation.For API usage, refer tothis documentation.Usage<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.js"></script>The following shows is a set of progressive examples to convert from a glTF file to MaterialX and then to a new glTF file for "shader ball" preview of
extracted materials.Note that the sample data is included as part of the package for convenience.The sample input file is the "BoomBox with Axes" file from the glTF sample repository foundhere.This is converted from glTF to a MaterialX document which can be previewed / modified using an integration which supports MaterialX. Here the file is loaded into the "MaterialX Graph Editor" which comes withMaterialX releases.The converted materials are then used to create a new glTF file using sample "shaderball" data with each material found assigned to different instances of the "shaderball"Interactive ExampleAJupyternotebook which performs the same steps is availablehere.This or any other notebook can be used if the user wishes to test the package in an interactive environment.Import the packageimportmaterialxgltf.coreascoreCheck Available Sample Dataimportpkg_resourcesdirectory_name="data"files=pkg_resources.resource_listdir('materialxgltf',directory_name)forfileinfiles:print('Data file: ',file)Convert from glTF to MaterialXimportpkg_resourcesimportMaterialXasmxgltfFileName=pkg_resources.resource_filename('materialxgltf','data/BoomBoxWithAxes.gltf')print(gltfFileName)# Instantiate a the reader class. Read in sample  glTF file# and output a MaterialX documentgltf2MtlxReader=core.GLTF2MtlxReader()doc=gltf2MtlxReader.convert(gltfFileName)ifnotdoc:print('Existing due to error')else:status,err=doc.validate()ifnotstatus:print('Generated MaterialX document has validation errors: ',err)else:print('Generated MaterialX document is valid')# Write the document to a stringprint('Resulting MaterialX document:\n')result=core.Util.writeMaterialXDocString(doc)print(result)Using glTF to MaterialX Options# Set option to write material assignmentsoptions=core.GLTF2MtlxOptions()options['createAssignments']=Truegltf2MtlxReader.setOptions(options)doc=gltf2MtlxReader.convert(gltfFileName)ifnotdoc:print('Existing due to error')else:status,err=doc.validate()ifnotstatus:print('Generated MaterialX document has validation errors: ',err)else:print('Generated MaterialX document is valid')# Write the document to a stringprint('Resulting MaterialX document:\n')result=core.Util.writeMaterialXDocString(doc)print(result)Conversion from MaterialX to glTFmaterialXFileName=pkg_resources.resource_filename('materialxgltf','data/BoomBoxWithAxes.mtlx')print('> Load MaterialX document:%s'%materialXFileName)mtlx2glTFWriter=core.MTLX2GLTFWriter()doc,libFiles=core.Util.createMaterialXDoc()mx.readFromXmlFile(doc,materialXFileName,mx.FileSearchPath())options=core.MTLX2GLTFOptions()options['debugOutput']=Truemtlx2glTFWriter.setOptions(options)gltfString=mtlx2glTFWriter.convert(doc)iflen(gltfString)>0:print('> Resulting glTF:\n')print(gltfString)else:print('> Failed to convert MaterialX document to glTF')Embedding GeometrygltfGeometryFile=pkg_resources.resource_filename('materialxgltf','data/shaderBall.gltf')print('> Load glTF geometry file:%s'%gltfGeometryFile)options=core.MTLX2GLTFOptions()options['geometryFile']=gltfGeometryFileoptions['primsPerMaterial']=Falsemtlx2glTFWriter.setOptions(options)gltfString=mtlx2glTFWriter.convert(doc)iflen(gltfString)>0:print('> Resulting glTF:\n')print(gltfString)else:print('> Failed to convert MaterialX document to glTF')Creating Primitives Per MaterialgltfGeometryFile=pkg_resources.resource_filename('materialxgltf','data/shaderBall.gltf')print('> Load glTF geometry file:%s'%gltfGeometryFile)options=core.MTLX2GLTFOptions()options['geometryFile']=gltfGeometryFileoptions['primsPerMaterial']=Truemtlx2glTFWriter.setOptions(options)gltfString=mtlx2glTFWriter.convert(doc)iflen(gltfString)>0:print('> Resulting glTF:\n')print(gltfString)else:print('> Failed to convert MaterialX document to glTF')Packaging A Binary FilegltfFileName=pkg_resources.resource_filename('materialxgltf','data/BoomBoxWithAxes_primMaterials.gltf')print('> Load glTF geometry file:%s'%gltfGeometryFile)binaryFileName=str()binaryFileName=gltfFileName.replace('.gltf','.glb')print('Packaging GLB...')try:saved,images,buffers=mtlx2glTFWriter.packageGLTF(gltfFileName,binaryFileName)print('Save GLB file:'+binaryFileName+'. Status:'+str(saved))forimageinimages:print('- Embedded image:%s'%image)forbufferinbuffers:print('  - Embedded buffer:%s'%buffer)print('Packaging GLB...Done')exceptExceptionaserr:print('Failed to package GLB file:%s'%err)Translate Shader and Bake TexturesAll materials are assumed to use glTF PBR surface shaders.
Conversion to this shading model can be performed via MaterialX
utilities, which includes texture baking.Please refer to thesample Jupyter notebookfor an example of shader
translation and baking using some convenience functions included with the package.
Note that they do not need to be used as the core MaterialX distribution provides
access to the APIs used in this package.AuthorLinkedIn:Bernard KwokGitHub:kwokcbEmail:kwokcb@gmail.com