read.obj: Read a Wavefront OBJ 3D scene file into an R list

Description

Read a Wavefront OBJ 3D scene file into an R list

Usage

read.obj(f, materialspath = NULL, convert.rgl = FALSE, triangulate = TRUE)

Arguments

Path to an OBJ file

materialspath

Path to a folder containing materials files. This is optional and only required if materials files are in a different folder from the OBJ file defined by f.

convert.rgl

Whether to convert the returned list to a rgl::shapelist3d object containing rgl::mesh3d objects.

triangulate

(default TRUE) Whether to convert all mesh faces to triangles. Note that only meshes with triangular or quad faces are supported, so setting triangulate=FALSE will throw an error for more complex files.

Value

When convert.rgl=FALSE, the default, a named list with items shapes and materials, each containing sublists with one entry per object (shapes) or material (materials). Objects in the shapes list have the following structure

positions 3 x N matrix of 3D vertices
indices 3/4 x M matrix of indices into vertex array (trimesh/quadmesh) 0-indexed
normals 3 x N matrix of normal directions for each vertex (missing when there are no normals)
normindices 3/4 x M matrix of indices into normals array (trimesh/quadmesh) 0-indexed (missing when there are no normals)
texcoords 2 x N matrix of texture coordinates (missing when there are no texture coordinates)
texindices 3/4 x M matrix of indices into texcoords array (trimesh/quadmesh) 0-indexed (missing when there are no texture coordinates)
nvfaces Raw vector specifying the number of vertices per face (missing unless triangulate=FALSE and there are a mixture of different numbers of vertices per face.)
material_ids 0-indexed, -1 when not set (missing when no materials)

When convert.rgl=TRUE a list of class shapelist3d containing a mesh3d for each object or group element in the original OBJ file. See tinyobj2shapelist3d for details of rgl conversion.

Sample files

Note that at the request of the CRAN maintainers the sample files have the file extension .wavefront instead of the standard .obj because this triggers a false positive R CMD check NOTE.

Details

tinyobjloader made some substantial changes to its data structures after the first code snapshot was taken for the this package in 2015. In order to benefit from bug fixes, we updated the code in 2020 but we note that tinyobjloader now de-duplicates vertices more aggressively e.g. in the situation where there are normals or texture coordinates. We were forced when converting to rgl::shapelist3d objects to revert these de-duplications on the R side in order for display in rgl; note that this only happens when there are texture coordinates and/or normals in the obj file.

Note that some fields in the tinyobjloader return structure will be omitted when they are not relevant for a given obj file. In this case, as with any R list, the list element will have the value NULL when tested. See examples.

Examples

Run this code

# NOT RUN {
cube=read.obj(system.file("obj/cube.wavefront", package = "readobj"))
str(cube)
# elements will be NULL when not present in the obj file e.g. normals
is.null(cube$shapes[[1]]$texcoords)

# demonstrate direct conversion of result to rgl format
if(require('rgl')) {
  cuber=read.obj(system.file("obj/cube.wavefront", package = "readobj"),
    convert.rgl=TRUE)
  shade3d(cuber)
}
# }

Run the code above in your browser using DataCamp Workspace