kaolin.io.obj

API

Functions

kaolin.io.obj.import_mesh(path, with_materials=False, with_normals=False, error_handler=None, heterogeneous_mesh_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, optional) – function that handle errors that may happen during file processing, with following signature: error_handler(error: Exception, material_name: Optional[str], materials: Optional[list[dict]], materials_order: Optional[list]). Default: raise all errors.

  • heterogeneous_mesh_handler (Callable, optional) – function that handles the import of heterogeneous mesh, with following signature: heterogeneous_mesh_handler(vertices, face_vertex_counts, *args)

  • Default – Heterogenenous mesh will raise a NonHomogeneousError.

Returns

nametuple of:

  • vertices (torch.Tensor): of shape \((\text{num_vertices}, 3)\).

  • faces (torch.LongTensor): of shape \((\text{num_faces}, \text{face_size})\).

  • uvs (torch.Tensor): of shape \((\text{num_uvs}, 2)\).

  • face_uvs_idx (torch.LongTensor): of shape \((\text{num_faces}, \text{face_size})\).

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

  • materials_order (torch.LongTensor): of shape \((\text{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 \((\text{num_vertices}, 3)\).

  • face_normals (torch.LongTensor): of shape \((\text{num_faces}, \text{face_size})\).

Return type

(obj.return_type)

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.

Error Handler

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

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

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.