ladybug_geometry.interop.obj module

A class that supports the import and export of OBJ data to/from ladybug_geometry.

class ladybug_geometry.interop.obj.OBJ(vertices, faces, vertex_texture_map=None, vertex_normals=None, vertex_colors=None, material_structure=None)[source]

Bases: object

A class that supports the import and export of OBJ data to/from ladybug_geometry.

Note that ladybug_geometry Mesh3D can be easily created from this OBJ by taking the vertices and normals.

Parameters:

  • vertices – A list or tuple of Point3D objects for vertices.

  • faces – A list of tuples with each tuple having either 3 or 4 integers. These integers correspond to indices within the list of vertices.

  • vertex_texture_map – An optional list or tuple of Point2D that align with the vertices input. All coordinate values of the Point2D should be between 0 and 1 and are intended to map to the XY system of images to be mapped onto the OBJ mesh. If None, the OBJ file is written without textures. (Default: None).

  • vertex_normals – An optional list or tuple of Vector3D that align with the vertices input and describe the normal vector to be used at each vertex. If None, the OBJ file is written without normals. (Default: None).

  • vertex_colors – An optional list of colors that align with the vertices input. Note that these are written into the OBJ alongside the vertex coordinates separately from the texture map. Not all programs support importing OBJs with this color information but Rhino does. (Default: None).

  • material_structure – A list of tuples where each tuple contains two elements. The first is the identifier of a material that is used in the OBJ and the second is the index of the face where the application of the new material begins. If None, everything will be assumed to have the same diffuse material. (Default: None).

Properties:

  • vertices

  • faces

  • vertex_texture_map

  • vertex_normals

  • vertex_colors

  • material_structure

classmethod from_file(file_path)[source]

Create an OBJ object from a .obj file.

Parameters:

file_path – Path to an OBJ file as a text string. Note that, if the file includes texture mapping coordinates or vertex normals, the number of texture coordinates and normals must align with the number of vertices to be importable. Nearly all OBJ files follow this standard. If any of the OBJ mesh faces contain more than 4 vertices, only the first 4 vertices will be counted.

classmethod from_mesh3d(mesh, include_colors=True, include_normals=False)[source]

Create an OBJ object from a ladybug_geometry Mesh3D.

If colors are specified on the Mesh3D, they will be correctly transferred to the resulting OBJ object as long as include_colors is True.

Parameters:

  • mesh – A ladybug_geometry Mesh3D object to be converted to an OBJ object.

  • include_colors – Boolean to note whether the Mesh3D colors should be transferred to the OBJ object. (Default: True).

  • include_normals – Boolean to note whether the vertex normals should be included in the resulting OBJ object. (Default: False).

classmethod from_mesh3ds(meshes, material_ids=None, include_normals=False)[source]

Create an OBJ object from a list of ladybug_geometry Mesh3D.

Mesh3D colors are ignored when using this method with the assumption that materials are used to specify how the meshes should be rendered.

Parameters:

  • meshes – A list of ladybug_geometry Mesh3D objects to be converted into an OBJ object.

  • material_ids – An optional list of strings that aligns with the input meshes and denote materials assigned to each mesh. This list of material IDs will be automatically converted into an efficient material_structure for the OBJ object where materials used for multiple meshes only include one reference to the material. If None, the OBJ will have no material structure. (Default: None).

  • include_normals – Boolean to note whether the vertex normals should be included in the resulting OBJ object. (Default: False).

to_file(folder, name, triangulate_quads=False, include_mtl=False)[source]

Write the OBJ object to an ASCII text file.

Parameters:

  • folder – A text string for the directory where the OBJ will be written.

  • name – A text string for the name of the OBJ file. Note that, if an image texture is meant to be assigned to this OBJ, the image should have the same name as the one input here except with the .mtl extension instead of the .obj extension.

  • triangulate_quads – Boolean to note whether quad faces should be triangulated upon export to OBJ. This may be needed for certain software platforms that require the mesh to be composed entirely of triangles (eg. Radiance). (Default: False).

  • include_mtl – Boolean to note whether an .mtl file should be automatically generated from the material structure written next to the .obj file in the output folder. All materials in the mtl file will be diffuse white, with the assumption that these will be customized later. (Default: False).

property faces

Tuple of tuples for all faces in the OBJ.

property material_structure

Get or set a tuple of tuples that specify the material structure of the obj.

Each sub-tuple contains two elements. The first is the identifier of a material that is used in the OBJ and the second is the index of the face where the application of the new material begins. If None, everything will be assumed to have the same diffuse material.

property vertex_colors

Get or set a list of colors for the OBJ. Will be None if no colors assigned.

property vertex_normals

Get or set a tuple of Vector3D for vertex normals.

Will be None if no vertex normals are assigned.

property vertex_texture_map

Get or set a tuple of Point2D for texture image coordinates for each vertex.

Will be None if no texture map is assigned.

property vertices

Tuple of Point3D for all vertices in the OBJ.