rgl (version 1.3.1)

writeOBJ: Read and write Wavefront OBJ format files

Description

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.

Usage

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, ...)

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.

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.

Author

Duncan Murdoch

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.

References

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

See Also

scene3d saves a copy of a scene to an R variable; rglwidget, writeASY, writePLY and writeSTL write the scene to a file in various other formats.

Examples

filename <- tempfile(fileext = ".obj")
open3d()
shade3d( icosahedron3d() )
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")))
}