Read and write Wavefront OBJ format files

writeOBJ writes OBJ files. This is a file format that is commonly used in 3D graphics applications. It does not represent text, but does represent points, lines, polygons (and many other types that RGL doesn't support). readOBJ reads only some parts of OBJ files.

writeOBJ(con, 
         pointRadius = 0.005, pointShape = icosahedron3d(), 
         lineRadius = pointRadius, lineSides = 20, 
         pointsAsPoints = FALSE, linesAsLines = FALSE, 
         withNormals = TRUE, withTextures = TRUE, 
         separateObjects = TRUE,
         ids = tagged3d(tags),
         tags = NULL)
readOBJ(con, ...)

Arguments

con: A connection or filename.
pointRadius, lineRadius: The radius of points and lines relative to the overall scale of the figure, if they are converted to polyhedra.
pointShape: A mesh shape to use for points if they are converted. It is scaled by the pointRadius.
lineSides: Lines are rendered as cylinders with this many sides.
pointsAsPoints, linesAsLines: Whether to convert points and lines to “point” and “line” records in the OBJ output.
withNormals: Whether to output vertex normals for smooth shading.
separateObjects: Whether to mark each RGL object as a separate object in the file.
withTextures: Whether to output texture coordinates.
ids: The identifiers (from ids3d) of the objects to write. If NULL, try to write everything.
tags: Alternate way to specify ids. Ignored if ids is given.
...: Additional arguments (typically just material) to pass to tmesh3d.

Details

The current writeOBJ implementation only outputs triangles, quads, planes, spheres, points, line segments, line strips and surfaces. It does not output material properties such as colors, since the OBJ format does not support the per-vertex colors that RGL uses.

The readOBJ implementation can read faces, normals, and textures coordinates, but ignores material properties (including the specification of the texture file to use). To read a file that uses a single texture, specify it in the material argument, e.g. readOBJ("model.OBJ", material = list(color = "white", texture = "texture.png")). There is no support for files that use multiple textures.

The defaults for pointsAsPoints and linesAsLines have been chosen because Blender (https://www.blender.org) does not import points or lines, only polygons. If you are exporting to other software you may want to change them.

If present, texture coordinates are output by default, but the textures themselves are not.

Individual RGL objects are output as separate objects in the file when separateObjects = TRUE, the default.

The output file should be readable by Blender and Meshlab; the latter can write in a number of other formats, including U3D, suitable for import into a PDF document.

Value

writeObj invisibly returns the name of the connection to which the data was written.

readObj returns a mesh object constructed from the input file.

References

The file format was found at http://www.martinreddy.net/gfx/3d/OBJ.spec on November 11, 2012.

Author

Duncan Murdoch

Examples

filename <- tempfile(fileext = ".obj")
open3d()
shade3d( icosahedron3d() )
3D plot

writeOBJ(filename)

# The motivation for writing readObj() was to read a shape
# file of Comet 67P/Churyumov-Gerasimenko, from the ESA.
# The file no longer appears to be online, but may still be
# available on archive.org.  Here was the original URL:
#   cometurl <- "http://sci.esa.int/science-e/www/object/doc.cfm?fobjectid=54726"
# This code would read and display it:
#   open3d()
#   shade3d(readOBJ(url(cometurl), 
#                   material = list(col = "gray")))


# Textures are used in a realistic hand image available from
# https://free3d.com/3d-model/freerealsichand-85561.html
# Thanks to Monte Shaffer for pointing this out.
# Decompress the files into the current directory, convert
# hand_mapNew.jpg to hand_mapNew.png, then use
if (FALSE) {
open3d()
shade3d(readOBJ("hand.OBJ", material = list(color = "white", 
shininess = 1, texture = "hand_mapNew.png")))
}