read.obj: Read a Wavefront OBJ 3D scene file into an R list
In readobj: Fast Reader for 'Wavefront' OBJ 3D Scene Files

Description Usage Arguments Details Value Sample files See Also Examples

View source: R/loadobj.R

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

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

`f`	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.

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.

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.

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.

tinyobj2shapelist3d, rgl::readOBJ for simpler, pure R implementation.

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)
}