R: Write HTML/Javascript code to control a WebGL display.

propertySetter {rgl} | R Documentation

## Write HTML/Javascript code to control a WebGL display.

### Description

`propertySlider` writes out HTML code to control WebGL displays on the same page via a slider; `par3dinterpSetter` and `propertySetter` return Javascript code to be used in HTML controls.

### Usage

    propertySlider(setter = propertySetter,
                 minS = NULL, maxS = NULL, step = 1, init = NULL,
    	     labels,
    	     id = basename(tempfile("input")), name = id,
    	     outputid = paste0(id, "text"),
    	     index = NULL,
    	     ...)

    propertySetter(values = NULL, entries, properties, objids, prefixes = "",
                   param = seq_len(NROW(values)), interp = TRUE, digits = 7)

    par3dinterpSetter(fn, from, to, steps, subscene, omitConstant = TRUE,
                      rename = character(), ...)

    matrixSetter(fns, from, to, steps, subscene = currentSubscene3d(),
                 matrix = "userMatrix", omitConstant = TRUE, prefix = "", ...)

    vertexSetter(values, vertices = 1, attributes, objid, prefix = "",
    	     param = seq_len(NROW(values)), interp = TRUE,
    	     digits = 7)

### Arguments

`setter` | A function to write Javascript code, or its output, or a list containing several of these.
`minS, maxS, step, init` | Slider values to be displayed. Reasonable defaults are used if missing.
`labels` | Labels to display for each slider value. The defaults are calculated using internal variables. If `NULL`, no labels will be shown.
`id` | The `id` of the input control that will be generated.
`name` | The name of the input control that will be generated.
`outputid` | The `id` of the output control that will display the slider value, or `NULL` for none.
`index` | The 1-based index of this slider: it controls the corresponding entry in an indexed setter such as `matrixSetter`.
`...` | See Details below.
`values` | An array of values; rows correspond to slider positions. Alternatively, `NULL`; the generated function takes a single value or array of values and applies them directly.
`entries, properties, objids, prefixes` | Vectors describing the columns of `values`. See the details below.
`param` | Parameter values corresponding to each row of `values`.
`interp` | Whether to interpolate values. If `FALSE`, the Javascript function will expect non-negative integer values. Ignored if `values` is `NULL`.
`digits` | How many significant digits to emit in the Javascript code.
`fn` | A function returned from `par3dinterp`.
`from, to, steps` | Values where `fn` should be evaluated.
`subscene` | Which subscene's properties should be modified?
`omitConstant` | If `TRUE`, do not set values that are constant across the range.
`rename` | A named character vector of names of Javascript properties to modify. See the details.
`fns` | A list containing functions returned from `par3dinterp`.
`matrix` | A character string giving the Javascript property name of the matrix to modify.
`prefix` | The prefix of the scene containing `matrix`.
`vertices` | A vector of vertex numbers (1-based) within an object.
`attributes` | A vector of attributes of a vertex, from `c("x", "y", "z", "r", "g", "b", "a", "nx", "ny", "nz", "radius", "ox", "oy", "oz", "ts", "tt")`. See Details.
`objid` | The object containing the vertices to be modified.

### Details

The `...` parameters to `propertySlider` will be passed to `setter` if the latter is a function, otherwise ignored.

The `...` parameters to `par3dinterpSetter` will be passed to `propertySetter`.

The `...` parameters to `matrixSetter` will be passed to the `par3dinterpSetter` functions used for each of the functions in `fns`.

`propertySetter` is a low-level general purpose function for modifying properties of objects in the scene. It is mainly for internal use. `propertySlider` uses it to generate Javascript for a slider control to manipulate those properties.

`vertexSetter` modifies attributes of vertices in a single object. The `attributes` are properties of each vertex in a scene; not all are applicable to all objects. In order, the are: coordinates of the vertex `"x", "y", "z"`, color of the vertex `"r", "g", "b", "a"`, normal at the vertex `"nx", "ny", "nz"`, radius of a sphere at the vertex `"radius"`, origin within a texture `"ox", "oy"` and perhaps `"oz"`, texture coordinates `"ts", "tt"`.

`propertySetter` and `vertexSetter` allow values to be specified in two ways. The normal way when used with a slider is to interpolate between specified values indexed by the slider. If `values = NULL`, the value of the slider is used directly (and only one entry can be set). Multiple entries can be set directly by passing an array of values in custom Javascript code.

`par3dinterpSetter` uses `propertySetter` to set parameters corresponding to values produced by the result of `par3dinterp`. Its `rename` argument allows translation of names, e.g. `rename = c(userMatrix = "myMatrix")` would cause the `"userMatrix"` result from `par3dinterp` to be used to modify the Javascript `myMatrix` property.

`matrixSetter` is used in the situation where multiple controls (e.g. sliders) are used to determine the value of a matrix, typically `"userMatrix"`. It will generate one `par3dinterpSetter` function for each of the entries in `fns`; these will be called when a `propertySlider` with the corresponding (1-based) index is changed, and the results multiplied together from right to left to produce a new value for whichever property is named in `matrix`.

The rows of the `values` matrix correspond to different settings for numeric properties. The columns are values to insert into those properties.

Argument `entries` gives the numeric (zero based) index into the Javascript property named by `properties`, for the object id `objids`, in the display with prefix `prefixes`. All of these may be vectors, corresponding to the columns of `values`. All but `entries` will be recycled to the appropriate length; its length needs to match the number of columns in `values`.

There are two modes for determining the values to substitute. In the simplest mode (`interp = FALSE` in `propertySetter`), each row of `values` corresponds to a location for the slider, and the values are simply copied into place. This requires that `param`, `min`, `max` and `step` take on their default values.

In other cases, linear interpolation is used between successive rows of `values`, with extrapolation outside the range of `param` repeating the first or last row. `param` should then contain the values that correspond to exact rows.

In both cases, `param` must be a strictly increasing vector.

### Value

`propertySlider` prints the full code to generate the control, and returns the `id` of the control that was generated.

`propertySetter` returns a single element character vector containing the Javascript source for a function to set the appropriate properties. It does not assign the function to a variable or include any of the HTML wrapper text that `propertySlider` adds.

The character vector has class `"propertySetter"`, and an attribute named `"env"` which gives access to the local environment where it was created, so for example `attr(value, "env")$prefixes` will give access to the `prefixes` argument if `value` was produced by `"propertySetter"`.

`par3dinterpSetter` returns a `propertySetter` result.

`matrixSetter` is similar to `propertySetter`, but the Javascript function takes arguments `value, index`, and the class of the result is `c("matrixSetter", "indexedSetter", "propertySetter")`.

`vertexSetter` is similar to `propertySetter`, but the class of the result is `c("vertexSetter", "propertySetter")`.

### Author(s)

Duncan Murdoch

### See Also

`writeWebGL`. `clipplaneSlider` makes use of `propertySlider`.

`ageSetter` can be used as the `setter` argument to `propertySlider` to modify objects according to a linear (age) scale.

### Examples

      # Just the setter function
      cat(propertySetter(1:4, entries = 12, properties = "values", objids = 13))

      # A 4-position slider
      propertySlider(values = 1:4, entries = 12, properties = "values", objids = 13, interp = FALSE)

      # A 10-position slider interpolating the 4-position slider
      propertySlider(values = 1:4, entries = 12, properties = "values", objids = 13,
                   step = (4-1)/9)

      # The userMatrix interpolation from example(play3d)
      M <- r3dDefaults$userMatrix
      fn <- par3dinterp(time = (0:2)*0.75, userMatrix = list(M,
                                         rotate3d(M, pi/2, 1, 0, 0),
                                         rotate3d(M, pi/2, 0, 1, 0) ) )
      cat(par3dinterpSetter(fn, 0, 3, steps=10))

[Package rgl version 0.99.9 Index]