kaolin.io.obj

API

Functions

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

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 handles errors that can be raised (see raised errors, except NonHomogeneousMeshError handled separately), with the signature error_handler(error: Exception, **kwargs). Handler can provide special treatment of MaterialNotFoundError, returning a dummy material dictionary instead (if this is not the case, assignments to non-existent materials will be lost). For options see: create_missing_materials_error_handler(), skip_error_handler(), ignore_error_handler(), and default_error_handler() (Default is to raise all errors).

  • heterogeneous_mesh_handler (Callable, optional) – function that handles a heterogeneous mesh, homogenizing, returning None or throwing error, with the following signature: heterogeneous_mesh_handler(vertices, face_vertex_counts, *args, face_assignments) for example, see mesh_handler_naive_triangulate and heterogeneous_mesh_handler_skip. Default: will raise a NonHomogeneousMeshError.

  • triangulate – if True, will triangulate all non-triangular meshes using same logic as mesh_handler_naive_triangulate.

Returns

namedtuple of:

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

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

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

  • face_uvs_idx (torch.LongTensor): indices into UVmap for every vertex of every face of shape \((\text{num_faces}, \text{face_size})\).

  • materials (list of dict): a list of materials (see return values of load_mtl()) sorted by their material_name.

  • material_assignments (dict of torch.LongTensor): (torch.ShortTensor): of shape (text{num_faces},)

    containing index of the material (in the materials list) assigned to the corresponding face, or -1 if no material was assigned.

  • normals (torch.Tensor): normal values of shape \((\text{num_normals}, 3)\).

  • face_normals_idx (torch.LongTensor): indices into the normal array for every vertex of every face, of shape \((\text{num_faces}, \text{face_size})\).

Return type

(obj.return_type)

Raises

  • MaterialNotFoundError – The .obj is using a material not parsed from material libraries (set error_handler to skip).

  • MaterialFileError – From load_mtl(): Failed to open material path (set error_handler to skip).

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

  • NonHomogeneousMeshError – The number of vertices were not equal for all faces (set heterogeneous_mesh_handler to handle).

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.

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

Error error_handler to be provided to obj.read_mesh that can handle MaterialNotFound error, returning a dummy material with a random diffuse color instead. Material will contain an additional “error” field. MaterialFileError and MaterialLoadError will print a warning and be ignored.