points3d {rgl} | R Documentation

## add primitive set shape

### Description

Adds a shape node to the current scene

### Usage

    points3d(x, y = NULL, z = NULL,  ...)
    lines3d(x, y = NULL, z = NULL,  ...)
    segments3d(x, y = NULL, z = NULL, ...)
    triangles3d(x, y = NULL, z = NULL, ...)
    quads3d(x, y = NULL, z = NULL, ...)

### Arguments

`x, y, z` | coordinates. Any reasonable way of defining the coordinates is acceptable. See the function `xyz.coords` for details.
`...` | Material properties (see `rgl.material`). For normals use `normals` and for texture coordinates use `texcoords`; see `rgl.primitive` for details.

### Details

The functions `points3d`, `lines3d`, `segments3d`, `triangles3d` and `quads3d` add points, joined lines, line segments, filled triangles or quadrilaterals to the plots. They correspond to the OpenGL types `GL_POINTS, GL_LINE_STRIP, GL_LINES, GL_TRIANGLES` and `GL_QUADS` respectively.

Points are taken in pairs by `segments3d`, triplets as the vertices of the triangles, and quadruplets for the quadrilaterals. Colors are applied vertex by vertex; if different at each end of a line segment, or each vertex of a polygon, the colors are blended over the extent of the object. Polygons must be non-degenerate and quadrilaterals must be entirely in one plane and convex, or the results are undefined.

These functions call the lower level functions `rgl.points`, `rgl.linestrips`, and so on, and are provided for convenience.

The appearance of the new objects are defined by the material properties. See `rgl.material` for details.

The two principal differences between the `rgl.*` functions and the `*3d` functions are that the former set all unspecified material properties to defaults, whereas the latter use current values as defaults; the former make persistent changes to material properties with each call, whereas the latter make temporary changes only for the duration of the call.

### Value

Each function returns the integer object ID of the shape that was added to the scene. These can be passed to `rgl.pop` to remove the object from the scene.

### Author(s)

Ming Chen and Duncan Murdoch

### Examples

    # Show 12 random vertices in various ways.

    M <- matrix(rnorm(36), 3, 12, dimnames = list(c('x', 'y', 'z'),
                                           rep(LETTERS[1:4], 3)))

    # Force 4-tuples to be convex in planes so that quads3d works.

    for (i in c(1, 5, 9)) {
        quad <- as.data.frame(M[, i + 0:3])
        coeffs <- runif(2, 0, 3)
        if (mean(coeffs) < 1) coeffs <- coeffs + 1 - mean(coeffs)
        quad$C <- with(quad, coeffs[1]*(B - A) + coeffs[2]*(D - A) + A)
        M[, i + 0:3] <- as.matrix(quad)
    }

    open3d()

    # Rows of M are x, y, z coords; transpose to plot

    M <- t(M)
    shift <- matrix(c(-3, 3, 0), 12, 3, byrow = TRUE)

    points3d(M)
    lines3d(M + shift)
    segments3d(M + 2*shift)
    triangles3d(M + 3*shift, col = 'red')
    quads3d(M + 4*shift, col = 'green')
    text3d(M + 5*shift, texts = 1:12)

    # Add labels

    shift <- outer(0:5, shift[1, ])
    shift[, 1] <- shift[, 1] + 3
    text3d(shift,
           texts = c('points3d', 'lines3d', 'segments3d',
             'triangles3d', 'quads3d', 'text3d'),
           adj = 0)
     rgl.bringtotop()

[Package rgl version 0.100.19 Index]