kaolin.io.materials¶

API¶

Functions

API¶

class kaolin.io.materials.Material¶: Abstract material definition class. Defines material inputs and methods to export material properties.

class kaolin.io.materials.MaterialManager¶

Material management utility. Allows material reader functions to be mapped against specific shaders. This allows USD import functions to determine if a reader is available, which material reader to use and which material representation to wrap the output with.

Default registered readers:

UsdPreviewSurface: Import material with shader id UsdPreviewSurface. All parameters are supported, including textures. See https://graphics.pixar.com/usd/release/wp_usdpreviewsurface.html for more details on available material parameters.

Example

>>> # Register a new USD reader for mdl `MyCustomPBR`
>>> from kaolin.io import materials
>>> dummy_reader = lambda params, texture_path, time: UsdShade.Material()
>>> materials.MaterialManager.register_usd_reader('MyCustomPBR', dummy_reader)

classmethod read_from_file(file_path, scene_path=None, texture_path=None, time=None)¶

Read USD material and return a Material object. The shader used must have a corresponding registered reader function.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).
scene_path (str) – Required only for reading USD files. Absolute path of UsdShade.Material prim within the USD file scene. Must be a valid Sdf.Path.
texture_path (str, optional) – Path to textures directory. By default, the textures will be assumed to be under the same directory as the file specified by file_path.
time (convertible to float, optional) – Optional for reading USD files. Positive integer indicating the tim at which to retrieve parameters.

Returns

Material object determined by the corresponding reader function.

Return type

(Material)

classmethod read_usd_material(material, texture_path, time=None)¶

Read USD material and return a Material object. The shader used must have a corresponding registered reader function. If no available reader is found, the material parameters will be returned as a dictionary.

Parameters

material (UsdShade.Material) – Valid USD Material prim
texture_path (str, optional) – Path to textures directory. If the USD has absolute paths to textures, set to an empty string. By default, the textures will be assumed to be under the same directory as the USD specified by file_path.
time (convertible to float, optional) – Positive integer indicating the time at which to retrieve parameters.

Returns

Material object determined by the corresponding reader function.

Return type

(Material)

classmethod register_usd_reader(shader_name, reader_fn)¶

Register a shader reader function that will be used during USD material import.

Parameters

shader_name (str) – Name of the shader
reader_fn (Callable) – Function that will be called to read shader attributes. The function must take as input a dictionary of input parameters, a string representing the texture path, and a time (params, texture_path, time) and typically return a Material

exception kaolin.io.materials.MaterialNotSupportedError¶

exception kaolin.io.materials.MaterialWriteError¶

class kaolin.io.materials.PBRMaterial(diffuse_color=(0.5, 0.5, 0.5), roughness_value=0.5, metallic_value=0.0, clearcoat_value=0.0, clearcoat_roughness_value=0.01, opacity_value=1.0, opacity_threshold=0.0, ior_value=1.5, specular_color=(0.0, 0.0, 0.0), displacement_value=0.0, diffuse_texture=None, roughness_texture=None, metallic_texture=None, clearcoat_texture=None, clearcoat_roughness_texture=None, opacity_texture=None, ior_texture=None, specular_texture=None, normals_texture=None, displacement_texture=None, is_specular_workflow=False, diffuse_colorspace='auto', roughness_colorspace='auto', metallic_colorspace='auto', clearcoat_colorspace='auto', clearcoat_roughness_colorspace='auto', opacity_colorspace='auto', ior_colorspace='auto', specular_colorspace='auto', normals_colorspace='auto', displacement_colorspace='auto')¶

Define a PBR material Supports USD Preview Surface (https://graphics.pixar.com/usd/docs/UsdPreviewSurface-Proposal.html), a physically based surface material definition.

Parameters

diffuse_color (tuple of floats) – RGB values for Diffuse parameter (typically referred to as Albedo in a metallic workflow) in the range of (0.0, 0.0, 0.0) to (1.0, 1.0, 1.0). Default value is grey (0.5, 0.5, 0.5).
roughness_value (float) – Roughness value of specular lobe in range 0.0 to 1.0. Default value is 0.5.
metallic_value (float) – Metallic value, typically set to 0.0 for non-metallic and 1.0 for metallic materials. Ignored if is_specular_workflow is True. Default value is 0.0.
clearcoat_value (float) – Second specular lobe amount. Color is hardcoded to white. Default value is 0.0.
clearcoat_roughness_value (float) – Roughness for the clearcoat specular lobe in the range 0.0 to 1.0. The default value is 0.01.
opacity_value (float) – Opacity, with 1.0 fully opaque and 0.0 as transparent with values within this range defining a translucent surface. Default value is 1.0.
opacity_treshold (float) – Used to create cutouts based on the opacity_value. Surfaces with an opacity smaller than the opacity_threshold will be fully transparent. Default value is 0.0.
ior_value (float) – Index of Refraction used with translucent objects and objects with specular components. Default value is 1.5.
specular_color (tuple of floats) – RGB values for Specular lobe. Ignored if is_specular_workflow is False. Default value is white (0.0, 0.0, 0.0).
displacement_value (float) – Displacement in the direction of the normal. Default is 0.0
diffuse_texture (torch.FloatTensor) – Texture for diffuse parameter, of shape (3, height, width).
roughness_texture (torch.FloatTensor) – Texture for roughness parameter, of shape (1, height, width).
metallic_texture (torch.FloatTensor) – Texture for metallic parameter, of shape (1, height, width). Ignored if is_specular_workflow is True.
clearcoat_texture (torch.FloatTensor) – Texture for clearcoat parameter, of shape (1, height, width).
clearcoat_roughness_texture (torch.FloatTensor) – Texture for clearcoat_roughness parameter, of shape (1, height, width).
opacity_texture (torch.FloatTensor) – Texture for opacity parameter, of shape (1, height, width).
ior_texture (torch.FloatTensor) – Texture for opacity parameter, of shape (1, height, width).
specular_texture (torch.FloatTensor) – Texture for specular parameter, of shape (3, height, width). Ignored if is_specular_workflow is False.
normals_texture (torch.FloatTensor) – Texture for normal mapping of shape (3, height, width). Normals maps create the illusion of fine three-dimensional detail without increasing the number of polygons. Tensor values must be in the range of [(-1.0, -1.0, -1.0), (1.0, 1.0, 1.0)].
displacement_texture (torch.FloatTensor) – Texture for displacement in the direction of the normal (1, height, width).
is_specular_workflow (bool) – Determines whether or not to use a specular workflow. Default is False (use a metallic workflow).
diffuse_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw, sRGB]. Default is ‘auto’.
roughness_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
metallic_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
clearcoat_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
clearcoat_roughness_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
opacity_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
ior_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
specular_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw, sRGB]. Default is ‘auto’.
normals_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw, sRGB]. Default is ‘auto’.
displacement_colorspace (string) – Colorspace of texture, if provided. Select from [auto, raw]. Default is ‘auto’.
shaders (dict) – Dictionary mapping a shader name to a reader and writer function. (Currently cannot be set).

read_from_usd(file_path, scene_path, texture_path=None, time=None)¶

Read material from USD.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).
scene_path (str) – Absolute path of UsdShade.Material prim within the USD file scene. Must be a valid Sdf.Path.
texture_path (str, optional) – Path to textures directory. If the USD has absolute paths to textures, set to an empty string. By default, the textures will be assumed to be under the same directory as the USD specified by file_path.
time (convertible to float, optional) – Positive integer indicating the time at which to retrieve parameters.

write_to_usd(file_path, scene_path, bound_prims=None, time=None, texture_dir='', texture_file_prefix='', shader='UsdPreviewSurface')¶

Write material to USD. Textures will be written to disk in with filename in the form: {usd_file_path}/{texture_dir}/{texture_file_prefix}{attr}.png where attr is one of [diffuse, roughness, metallic, specular, normals].

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).
scene_path (str) – Absolute path of material within the USD file scene. Must be a valid Sdf.Path.
bound_prims (list of Usd.Prim, optional) – If provided, bind material to each prim.
time (convertible to float, optional) – Positive integer defining the time at which the supplied parameters correspond to.
texture_dir (str, optional) – Subdirectory to store texture files. If not provided, texture files will be saved in the same directory as the USD file specified by file_path.
texture_file_prefix (str, optional) – String to be prepended to the filename of each texture file.
shader (str, optional) – Name of shader to write. If not provided, use UsdPreviewSurface.

Exceptions¶

class kaolin.io.materials.MaterialError¶

class kaolin.io.materials.MaterialLoadError¶

class kaolin.io.materials.MaterialFileError¶

class kaolin.io.materials.MaterialNotFoundError¶