material: Set material properties

In rgl: 3D Visualization Using OpenGL

Set material properties

Description

Set material properties for geometry appearance.

Usage

rgl.material(
  color        = "white",
  alpha        = 1.0,
  lit          = TRUE, 
  ambient      = "black",
  specular     = "white", 
  emission     = "black", 
  shininess    = 50.0, 
  smooth       = TRUE,
  texture      = NULL, 
  textype      = "rgb", 
  texmipmap    = FALSE, 
  texminfilter = "linear", 
  texmagfilter = "linear",
  texenvmap    = FALSE,
  front        = "filled", 
  back         = "filled",
  size         = 3.0, 
  lwd          = 1.0,
  fog          = TRUE,
  point_antialias = FALSE,
  line_antialias = FALSE,
  depth_mask   = TRUE,
  depth_test   = "less",
  polygon_offset = c(0.0, 0.0),
  margin       = "",
  floating     = FALSE,
  tag          = "",
  col,
  ...
)
material3d(...)

Arguments

color	vector of R color characters. Represents the diffuse component in case of lighting calculation (lit = TRUE), otherwise it describes the solid color characteristics.
lit	logical, specifying if lighting calculation should take place on geometry
ambient, specular, emission, shininess	properties for lighting calculation. ambient, specular, emission are R color character string values; shininess represents a numerical.
alpha	vector of alpha values between 0.0 (fully transparent) .. 1.0 (opaque).
smooth	logical, specifying whether Gouraud shading (smooth) or flat shading should be used.
texture	path to a texture image file. Supported formats: png.
textype	specifies what is defined with the pixmap "alpha" alpha values "luminance" luminance "luminance.alpha" luminance and alpha "rgb" color "rgba" color and alpha texture
texmipmap	Logical, specifies if the texture should be mipmapped.
texmagfilter	specifies the magnification filtering type (sorted by ascending quality): "nearest" texel nearest to the center of the pixel "linear" weighted linear average of a 2x2 array of texels
texminfilter	specifies the minification filtering type (sorted by ascending quality): "nearest" texel nearest to the center of the pixel "linear" weighted linear average of a 2x2 array of texels "nearest.mipmap.nearest" low quality mipmapping "nearest.mipmap.linear" medium quality mipmapping "linear.mipmap.nearest" medium quality mipmapping "linear.mipmap.linear" high quality mipmapping
texenvmap	logical, specifies if auto-generated texture coordinates for environment-mapping should be performed on geometry.
front, back	Determines the polygon mode for the specified side: "filled" filled polygon "lines" wireframed polygon "points" point polygon "culled" culled (hidden) polygon
size	numeric, specifying the size of points in pixels
lwd	numeric, specifying the line width in pixels
fog	logical, specifying if fog effect should be applied on the corresponding shape. Fog type is set in bg3d.
point_antialias, line_antialias	logical, specifying if points should be round and lines should be antialiased, but see Note below.
depth_mask	logical, specifying whether the object's depth should be stored.
depth_test	Determines which depth test is used to see if this object is visible, depending on its apparent depth in the scene compared to the stored depth. Possible values are "never", "less" (the default), "equal", "lequal" (less than or equal), "greater", "notequal", "gequal" (greater than or equal), "always".
polygon_offset	If non-zero, offsets are added to the recorded depth of filled polygons. See Details below.
margin, floating	Used mainly for text to draw annotations in the margins, but supported by most kinds of objects: see mtext3d.
tag	A length 1 string value. These may be used to identify objects, or encode other meta data about the object.
col	An allowed abbreviation of color.
...	Any of the arguments above can be passed to material3d; see Details below. rgl.material will ignore others.

Details

Values can be queried by specifying their names in a character vector, e.g. material3d("color"). There is one read-only property that can be queried but not set:

isTransparent

Is the current color transparent?

Only one side at a time can be culled.

Object display colors are determined as follows:

• If lit = FALSE, an element of the color vector property is displayed without modification. See documentation for individual objects for information on which element is chosen.

• If lit = TRUE, the color is determined as follows.

  1. The color is set to the emission property of the object.

  2. For each defined light, the following are added:

     • the product of the ambient color of the light and the ambient color of the object is added.

     • the color of the object is multiplied by the diffuse color of the light and by a constant depending on the angle between the surface and the direction to the light, and added.

     • the specular color of the object is multiplied by the specular color of the light and a constant depending on the shininess of the object and the direction to the light, and added. The shininess property mainly determines the size of the shiny highlight; adjust one or both of the specular colors to change its brightness.

The polygon_offset property is a two element vector giving the factor and units values to use in a glPolygonOffset() call in OpenGL. If only one value is given, it is used for both elements. The units value is added to the depth of all pixels in a filled polygon, and the factor value is multiplied by an estimate of the slope of the polygon and then added to the depth. Positive values “push” polygons back slightly for the purpose of depth testing, to allow points, lines or other polygons to be drawn on the surface without being obscured due to rounding error. Negative values pull the object forward. A typical value to use is 1 (which is automatically expanded to c(1,1)). If values are too large, objects which should be behind the polygon will show through, and if values are too small, the objects on the surface will be partially obscured. Experimentation may be needed to get it right. The first example in ?persp3d uses this property to add grid lines to a surface.

material3d is an alternate interface to the material properties, modelled after par3d: rather than setting defaults for parameters that are not specified, they will be left unchanged. material3d may also be used to query the material properties; see the examples below.

The current implementation does not return parameters for textures.

The material member of the r3dDefaults list may be used to set default values for material properties.

The ... parameter to rgl.material is ignored.

Value

rgl.material() is called for the side effect of setting the material properties. It returns a value invisibly which is not intended for use by the user.

Users should use material3d() to query material properties. It returns values similarly to par3d as follows: When setting properties, it returns the previous values in a named list. A named list is also returned when more than one value is queried. When a single value is queried it is returned directly.

Note

If point_antialias is TRUE, points will be drawn as circles in WebGL; otherwise, they will be drawn as squares. Within R, the behaviour depends on your graphics hardware: for example, I see circles for both settings on my laptop.

Within R, lines tend to appear heavier with line_antialias == TRUE. There's no difference at all in WebGL.

See Also

rgl.primitive, rgl.bbox, rgl.bg, rgl.light

Examples

save <- material3d("color")
material3d(color = "red")
material3d("color")
material3d(color = save)

# this illustrates the effect of depth_test
x <- c(1:3); xmid <- mean(x)
y <- c(2, 1, 3); ymid <- mean(y)
z <- 1
open3d()
tests <- c("never", "less", "equal", "lequal", "greater", 
                  "notequal", "gequal", "always")
for (i in 1:8) {
  triangles3d(x, y, z + i, col = heat.colors(8)[i])
  texts3d(xmid, ymid, z + i, paste(i, tests[i], sep = ". "), depth_test = tests[i]) 
}
highlevel()  # To trigger display

rgl documentation built on June 10, 2022, 9:05 a.m.