sprites: Add sprites

Description

Adds a sprite set shape node to the scene.

Usage

sprites3d(x, y = NULL, z = NULL, radius = 1, 
          shapes = NULL, userMatrix, 
          fixedSize = FALSE, 
          adj = 0.5, pos = NULL, offset = 0.25, 
          rotating = FALSE, ...)
          
particles3d(x, y = NULL, z = NULL, radius = 1, ...)

Value

These functions are called for the side effect of displaying the sprites. The shape ID of the displayed object is returned.

Arguments

x, y, z: point coordinates. Any reasonable way of defining the coordinates is acceptable. See the function xyz.coords for details.
radius: vector or single value defining the sprite radius
shapes: NULL for a simple square, a vector of identifiers of shapes in the scene, or a list of such vectors. See Details.
userMatrix: if shape is not NULL, the transformation matrix for the shapes
fixedSize: should sprites remain at a fixed size, or resize with the scene?
adj, pos, offset: positioning arguments; see Details
rotating: should sprites remain at a fixed orientation, or rotate with the scene?
...: material properties when shapes = NULL, texture mapping is supported

Details

Simple sprites (used when shapes is NULL) are 1 by 1 squares that are directed towards the viewpoint. Their primary use is for fast (and faked) atmospherical effects, e.g. particles and clouds using alpha blended textures. Particles are sprites using an alpha-blended particle texture giving the illusion of clouds and gases. The centre of each square will by default be at the coordinates given by x, y, z. This may be adjusted using the adj or pos parameters.

adj and pos are treated similarly to the same parameters for text3d. adj has 3 entries, for adjustment to the x, y and z coordinates respectively. For x, a value of 0 puts the sprite to the right of the specified point, 0.5 centers it there, and 1 puts it to the left. The other coordinates are similar. By default, each value is 0.5 and the sprites are centered at the points given by (x, y, z).

The pos parameter overrides adj. It should be an integer or vector of integers (one per point), interpreted as in text3d to position the sprite relative to the (x, y, z) point: 0 is centered on it, 1 is below, 2 is to the left, 3 is above, 4 is to the right, 5 is in front, and 6 is behind. offset is the fraction of the sprite size to separate it from the point.

When shapes is not NULL, it should be a vector of identifiers of objects to plot in the scene (e.g. as returned by plotting functions or by ids3d), or a list of such vectors. The referenced objects will be removed from the scene and duplicated as sprite images in a constant orientation, as specified by userMatrix. By default the origin (0, 0, 0) will be plotted at the coordinates given by (x, y, z), perhaps modified by adj or pos.

If shapes is a vector all entries in it will be plotted at every location. If shapes is a list, different shapes will be plotted at each location. All entries in list entry 1 will be plotted at location 1, all entries in entry 2 at location 2, etc. Entries will be recycled as needed.

The userMatrix argument is ignored for shapes = NULL. For shapes, sprites3d defaults the matrix to r3dDefaults$userMatrix.

If any coordinate is NA, the sprite is not plotted.

The id values of the shapes may be retrieved after plotting using rgl.attrib(id, "ids"), the associated entry in shapes is retrievable in rgl.attrib(id, "shapenum"), and the user matrix is retrieved using rgl.attrib(id, "usermatrix").

Examples

Run this code

open3d()
particles3d( rnorm(100), rnorm(100), rnorm(100), color = rainbow(100) )
# is the same as
sprites3d( rnorm(100), rnorm(100), rnorm(100), color = rainbow(100),
  lit = FALSE, alpha = .2,
  textype = "alpha", texture = system.file("textures/particle.png", package = "rgl") )
sprites3d( rnorm(10) + 6, rnorm(10), rnorm(10), shape = shade3d(tetrahedron3d(), col = "red") )


open3d()

# Since the symbols are objects in the scene, they need
# to be added to the scene after calling plot3d()

plot3d(iris, type = "n")

# Use list(...) to apply different symbols to different points.

symbols <- list(shade3d(cube3d(), col = "red"),
                shade3d(tetrahedron3d(), col = "blue"),
                # Construct spheres
                shade3d(addNormals(subdivision3d(icosahedron3d(), 2)),
                        col = "yellow"))
                
sprites3d(iris, shape = symbols[iris$Species], radius = 0.1)