kaolin.render.materials

API

class kaolin.render.materials.Material(name, shader_name)

Bases: ABC

Abstract material definition class. Defines material inputs and methods to export material properties.

abstract as_dict()
static from_dict(in_dict)
class kaolin.render.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, transmittance_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, transmittance_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', transmittance_colorspace='auto', material_name='', shader_name='UsdPreviewSurface')

Bases: Material

Defines a PBR material; allows storing rendering material properties imported from USD, gltf, obj, attempting to expose a consistent interface. 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_threshold (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. Note: The definition of opacity make conflict with the transmission field due to different shader conventions. Use either the one or the other according to your shader conventions.

  • 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

  • transmittance_value (float) – The percentage of light that is transmitted through the surface of the material. Default is None Note: The definition of transmission make conflict with the opacity field due to different shader conventions. Use either the one or the other according to your shader conventions.

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

  • transmittance_texture (torch.FloatTensor) – Texture for the percentage of light that is transmitted through the surface of the material, of shape (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’.

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

as_dict()

Convert the PBRMaterial to a dictionary representation.

Returns

Dictionary containing all material attributes

Return type

dict

chw()

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

Returns

The new material.

Return type

(PBRMaterial)

clearcoat_colorspace
clearcoat_roughness_colorspace
clearcoat_roughness_texture
clearcoat_roughness_value
clearcoat_texture
clearcoat_value
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)

describe_attribute(attr, print_stats=False, detailed=False)

Outputs an informative string about an attribute; the same method used for all attributes in to_string.

Args:

print_stats (bool): if to print statistics about values in each tensor detailed (bool): if to include additional information about each tensor

Returns

multi-line string with attribute information

Return type

(str)

diffuse_color
diffuse_colorspace
diffuse_texture
displacement_colorspace
displacement_texture
displacement_value
classmethod from_dict(in_dict)

Create a PBRMaterial from a dictionary representation.

Parameters

in_dict (dict) – Dictionary containing material attributes

Returns

New PBRMaterial instance

Return type

PBRMaterial

get_attributes(only_tensors=False)

Returns names of all attributes that are currently set.

Returns

list of string names

Return type

(list)

hwc()

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

Returns

The new material.

Return type

(PBRMaterial)

ior_colorspace
ior_texture
ior_value
is_specular_workflow
material_name
metallic_colorspace
metallic_texture
metallic_value
normals_colorspace
normals_texture
opacity_colorspace
opacity_texture
opacity_threshold
opacity_value
read_from_usd(file_path, scene_path, texture_path=None, time=None)
roughness_colorspace
roughness_texture
roughness_value
shader_name
specular_color
specular_colorspace
specular_texture
classmethod supported_tensor_attributes()
classmethod supported_texture_attributes()
to(device)

Returns a copy where all material attributes that are tensors are put on the provided device. Note that behavior of member tensors is consistent with PyTorch Tensor.to method.

Parameters

device – The destination GPU/CPU device.

to_string(print_stats=False, detailed=False)

Returns information about attributes as a multi-line string.

Parameters

  • print_stats (bool) – if to print statistics about values in each tensor

  • detailed (bool) – if to include additional information about each tensor

Returns

multi-line string with attribute information

Return type

(str)

transmittance_colorspace
transmittance_texture
transmittance_value
write_to_usd(file_path, scene_path, bound_prims=None, time=None, texture_dir='', texture_file_prefix='', shader='UsdPreviewSurface')
kaolin.render.materials.random_material_colorspaces()
kaolin.render.materials.random_material_textures(device=None)
kaolin.render.materials.random_material_values(device=None)