kaolin.io.obj

API

Functions

kaolin.io.obj.ignore_error_handler(error, **kwargs)

Simple error handler to use in load_obj() that ignore all errors

kaolin.io.obj.import_mesh(path, with_materials=False, with_normals=False, error_handler=None)

Load data from an obj file as a single mesh.

With limited materials support to Kd, Ka, Ks, map_Kd, map_Ka and map_Ks. Followed format described in: http://paulbourke.net/dataformats/obj/

Parameters

• path (str) – path to the obj file (with extension).

• with_materials (bool) – if True, load materials. Default: False.

• with_normals (bool) – if True, load vertex normals. Default: False.

• error_handler (Callable) – function that handle errors that may happen during file processing. Take (error (Exception), material_name (str, optional), materials (list of dict, optional), materials_order (list, optional)) as input. Default: raise all errors.

Returns:

nametuple of:

• vertices (torch.Tensor): of shape (num_vertices, 3)

• faces (torch.LongTensor): of shape (num_faces, face_size)

• uvs (torch.Tensor): of shape (num_uvs, 2)

• face_uvs_idx (torch.LongTensor): of shape (num_faces, face_size)

• materials (list of dict): a list of materials (see return values of load_mtl())

• materials_orders (torch.LongTensor): of shape (num_same_material_groups, 2) showing the order in which materials are used over face_uvs_idx and the first indices in which they start to be used. A material can be used multiple times.

• vertex_normals (torch.Tensor): of shape (num_vertices, 3)

• face_normals (torch.LongTensor): of shape (num_faces, face_size)

Raises

• MaterialNotFoundError – The .obj is using a material that haven’t be found in the material files

• MaterialLoadError – From load_mtl(): Failed to load material, very often due to path to map_Kd/map_Ka/map_ks being invalid.

kaolin.io.obj.load_mtl(mtl_path, error_handler)

Load and parse a Material file.

Followed format described in: https://people.sc.fsu.edu/~jburkardt/data/mtl/mtl.html. Currently only support diffuse, ambient and specular parameters (Kd, Ka, Ks) through single RGB values or texture maps.

Parameters

mtl_path (str) – Path to the mtl file.

Returns

Dictionary of materials, which are dictionary of properties with optional torch.Tensor values:

• Kd: diffuse color of shape (3)

• map_Kd: diffuse texture map of shape (H, W, 3)

• Ks: specular color of shape (3)

• map_Ks: specular texture map of shape (H’, W’, 3)

• Ka: ambient color of shape (3)

• map_Ka: ambient texture map of shape (H’’, W’’, 3)

Return type

(dict)

Raises

MaterialLoadError – Failed to load material, very often due to path to map_Kd/map_Ka/map_Ks being invalid.

Error Handler

kaolin.io.obj.skip_error_handler(error, **kwargs)

Simple error handler to use in load_obj() that skips all errors and logs them as warnings.

kaolin.io.obj.default_error_handler(error, **kwargs)

Simple error handle to use in load_obj() that raises all errors.

Exceptions

class kaolin.io.obj.MaterialError

class kaolin.io.obj.MaterialLoadError

class kaolin.io.obj.MaterialFileError

class kaolin.io.obj.MaterialNotFoundError