kaolin.io.materials

API

Functions


API

class kaolin.io.materials.Material(name)

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:

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=None, roughness_value=None, metallic_value=None, clearcoat_value=None, clearcoat_roughness_value=None, opacity_value=None, opacity_threshold=None, ior_value=None, specular_color=None, displacement_value=None, 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', name='')

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 None.

  • roughness_value (float) – Roughness value of specular lobe in range 0.0 to 1.0. Default value is None.

  • 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 None.

  • clearcoat_value (float) – Second specular lobe amount. Color is hardcoded to white. Default value is None.

  • clearcoat_roughness_value (float) – Roughness for the clearcoat specular lobe in the range 0.0 to 1.0. The default value is None.

  • 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 None.

  • 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 None.

  • ior_value (float) – Index of Refraction used with translucent objects and objects with specular components. Default value is None.

  • specular_color (tuple of floats) – RGB values for Specular lobe. Ignored if is_specular_workflow is False. Default value is None.

  • displacement_value (float) – Displacement in the direction of the normal. Default is None

  • 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).

chw()

Returns a copy where all the image attributes are in CHW layout.

Returns

The new material.

Return type

(PBRMaterial)

contiguous(memory_format=torch.contiguous_format)

Returns a copy where all the attributes are contiguous in memory.

Parameters

memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.contiguous_format.

Returns

The new material.

Return type

(PBRMaterial)

cpu(memory_format=torch.preserve_format)

Returns a copy where all the attributes are on CPU memory.

Parameters

memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.preserve_format.

Returns

The new material.

Return type

(PBRMaterial)

cuda(device=None, non_blocking=False, memory_format=torch.preserve_format)

Returns a copy where all the attributes are on CUDA memory.

Parameters
  • device (torch.device) – The destination GPU device. Defaults to the current CUDA device.

  • non_blocking (bool) – If True and the source is in pinned memory, the copy will be asynchronous with respect to the host.

  • memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.preserve_format.

Returns

The new material.

Return type

(PBRMaterial)

hwc()

Returns a copy where all the image attributes are in HWC layout.

Returns

The new material.

Return type

(PBRMaterial)

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.

kaolin.io.materials.process_materials_and_assignments(materials_dict, material_assignments_dict, error_handler, num_faces, error_context_str='')

Converts dictionary style materials and assignments to final format (see args/return values).

Parameters
  • materials_dict (dict of str to dict) – mapping from material name to material parameters

  • material_assignments_dict (dict of str to torch.LongTensor) – mapping from material name to either 1) a K x 2 tensor with start and end face indices of the face ranges assigned to that material or 2) a K, tensor with face indices assigned to that material

  • error_handler – handler able to handle MaterialNotFound error - error can be thrown, ignored, or the handler can return a dummy material for material not found (if this is not the case, assignments to non-existent materials will be lost), e.g. obj.create_missing_materials_error_handler.

  • num_faces – total number of faces in the model

  • error_context_str (str) – any extra info to attach to thrown errors

Returns

  • materials (list): list of material parameters, sorted alphabetically by their name

  • material_assignments (torch.ShortTensor): of shape ( ext{num_faces},) containing index of the

    material (in the above list) assigned to the corresponding face, or -1 if no material was assigned.

Return type

(tuple) of

Exceptions

class kaolin.io.materials.MaterialError
class kaolin.io.materials.MaterialLoadError
class kaolin.io.materials.MaterialFileError
class kaolin.io.materials.MaterialNotFoundError