Override materials during model conversion
The material settings in the source model define the PBR materials used by the renderer. Sometimes the default conversion doesn't give the desired results and you need to make changes. For more information, see Material mapping for model formats.
When a triangular mesh is converted for use in Azure Remote Rendering, you can provide a material override file to customize how material conversion is done on a per-material basis. If a file called <modelName>.MaterialOverrides.json is found in the input container with the input model <modelName>.<ext>, it's used as the material override file.
The override file used during conversion
As a simple example, take a box model that has a single material, called Default.
Its albedo color needs to be adjusted for use in Remote Rendering.
In this case, a box.MaterialOverrides.json file can be created as follows:
[
{
"name": "Default",
"albedoColor": {
"r": 0.33,
"g": 0.33,
"b": 0.33,
"a": 1.0
}
}
]
The box.MaterialOverrides.json file is placed in the input container with box.fbx, which tells the conversion service to apply the new settings.
Color materials
The color material model describes a constantly shaded surface that is independent of lighting.
Color materials are useful for assets made by Photogrammetry algorithms, for example. For more information, see Color materials.
In material override files, a material can be declared to be a color material by setting unlit to true.
[
{
"name": "Photogrametry_mat1",
"unlit" : true
},
{
"name": "Photogrametry_mat2",
"unlit" : true
}
]
Ignore specific texture maps
Sometimes you might want the conversion process to ignore specific texture maps. This situation might happen when your model was generated by a tool that generates special maps not understood by the renderer. For example, an "OpacityMap" might be used to define something other than opacity, or the "NormalMap" is stored as "BumpMap". In the latter case you want to ignore "NormalMap", which causes the converter to use "BumpMap" as "NormalMap".
Add a property called ignoreTextureMaps and add any texture map you want to ignore:
[
{
"name": "Default",
"ignoreTextureMaps": ["OpacityMap", "NormalMap"]
}
]
For the full list of texture maps you can ignore, see the JSON schema.
Applying the same overrides to multiple materials
By default, an entry in the material overrides file applies when its name matches the material name exactly.
Since it's common that the same override should apply to multiple materials, you can optionally provide a regular expression as the entry name.
The field nameMatching has a default value exact, but it can be set to regex to state that the entry should apply to every matching material.
The syntax of the regex is the same syntax used for JavaScript.
Tip
There are free regex testing websites available to test and debug a regular expression against arbitrary strings.
The following example shows an override that applies to materials with names like Material2, Material01 and Material999.
[
{
"name": "Material[0-9]+",
"nameMatching": "regex",
"albedoColor": {
"r": 0.0,
"g": 0.0,
"b": 1.0,
"a": 1.0
}
}
]
This example shows an override that is applied to all materials:
[
{
"name": ".*",
"nameMatching": "regex",
"albedoColor": {
"r": 0.0,
"g": 0.0,
"b": 1.0,
"a": 1.0
}
}
]
The order in which every material finds a matching override is as follows:
- First, it tests for exact name match (that is, it checks all overrides where
nameMatchingis absent or equalsexact). - If no override is found, it tests all overrides with
regexname matching mode and uses the first override that matches.
A single material never gets more than one override applied, even if multiple regex expressions apply to the material name.
Getting information about which entries applied
The info file written to the output container carries information about the number of overrides provided, and the number of materials that were overridden. For more information, see Information about a converted model.
JSON schema
The full JSON schema for materials files is given here. Except for unlit and ignoreTextureMaps, the properties available are a subset of the properties described in the sections on the color material and PBR material models.
{
"definitions" :
{
"color":
{
"type" : "object",
"description" : "Color as 4 components vector",
"properties":
{
"r": {"type":"number"},
"g": {"type":"number"},
"b": {"type":"number"},
"a": {"type":"number"}
},
"required": ["r", "g", "b"]
},
"alpha":
{
"type" : "object",
"description" : "Alpha channel for color",
"properties":
{
"a": {"type":"number"}
},
"required": ["a"]
},
"colorOrAlpha":
{
"anyOf": [
{"$ref": "#/definitions/color"},
{"$ref": "#/definitions/alpha"}
]
},
"listOfMaps":
{
"type": "array",
"items": {
"type": "string",
"enum": ["AlbedoMap",
"EmissiveMap",
"NormalMap",
"OcclusionMap",
"RoughnessMap",
"MetalnessMap",
"ReflectivityMap",
"BumpMap",
"OpacityMap",
"DiffuseMap",
"SpecularMap",
"ShininessMap",
"MetallicRoughnessMap",
"SpecularGlossinessMap"]
}
}
},
"type" : "array",
"description" : "List of materials to override",
"items":
{
"type" : "object",
"description" : "List of parameters to override",
"properties":
{
"name": { "type" : "string"},
"nameMatching" : { "type" : "string", "enum" : ["exact", "regex"] },
"unlit": { "type" : "boolean" },
"albedoColor": { "$ref": "#/definitions/colorOrAlpha" },
"roughness": { "type": "number" },
"metalness": { "type": "number" },
"normalMapScale": { "type": "number" },
"transparent": { "type" : "boolean" },
"alphaClipEnabled": { "type" : "boolean" },
"alphaClipThreshold": { "type": "number" },
"useVertexColor": { "type" : "boolean" },
"isDoubleSided": { "type" : "boolean" },
"ignoreTextureMaps": { "$ref" : "#/definitions/listOfMaps" },
"transparencyWritesDepth": {"type" : "boolean" }
},
"required": ["name"],
"additionalProperties" : false
}
}
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for