[Stpp-commits] r7 - in pkg: R man

[noreply at r-forge.r-project.org]

Author: barryrowlingson
Date: 2008-10-24 12:46:05 +0200 (Fri, 24 Oct 2008)
New Revision: 7

Modified:
   pkg/R/stani.R
   pkg/man/stani.Rd
Log:
stani now uses states for rendering, updated docs

Modified: pkg/R/stani.R
===================================================================
--- pkg/R/stani.R	2008-10-23 16:14:25 UTC (rev 6)
+++ pkg/R/stani.R	2008-10-24 10:46:05 UTC (rev 7)
@@ -4,12 +4,10 @@
   par3d(skipRedraw=TRUE)
   np=dim(o$xyt)[1]
 
-  ## what's in our window?
-  if(!o$persist){
-    tin=o$xyt[,3]>(o$t-o$width) & o$xyt[,3] < (o$t)
-  }else{
-    tin= o$xyt[,3] < (o$t+o$width)
-  }  
+  ## compute new states
+  tin = rep(1,np)
+  tin[o$xyt[,3]>(o$t-o$width)]=2
+  tin[o$xyt[,3]>o$t]=3
 
   ## which points have changed state since last time?
   changed = tin != o$xyt[,5]
@@ -21,15 +19,9 @@
 
   ## now add them back in their correct state:
   for(i in (1:np)[changed]){
-    if(tin[i]){
-      material3d(o$s2)
-      o$xyt[i,4]=spheres3d(x=o$xyt[i,1],y=o$xyt[i,2],z=o$xyt[i,3],radius=o$s2$radius)
-      o$xyt[i,5]=tin[i]
-    }else{
-      material3d(o$s1)
-      o$xyt[i,4]=spheres3d(x=o$xyt[i,1],y=o$xyt[i,2],z=o$xyt[i,3],radius=o$s1$radius)
-      o$xyt[i,5]=tin[i]
-    }
+    material3d(o$states[[tin[i]]])
+    o$xyt[i,4]=spheres3d(x=o$xyt[i,1],y=o$xyt[i,2],z=o$xyt[i,3],radius=o$states[[tin[i]]]$radius)
+    o$xyt[i,5]=tin[i]
   }
   ## start drawing again:
   par3d(skipRedraw=FALSE)
@@ -38,12 +30,11 @@
   return(o)
 }
 
-.rp.stan3d <- function(xyt,tlim,twid,persist,states) {
+.rp.stan3d <- function(xyt,tlim,twid,states) {
   t=tlim[1];width=twid
   stan.panel  <- rp.control(title="space-time animation",
-                            xyt=xyt, t=tlim[1], width=twid, persist=persist,
-                            s1=states$s1,
-                            s2=states$s2
+                            xyt=xyt, t=tlim[1], width=twid,
+                            states=states
                             )
   rp.slider(stan.panel, t, title = "time", from=tlim[1], to=tlim[2], action = .stan3d.redraw,showvalue=TRUE)
   rp.slider(stan.panel, width, title = "window", from=0, to=diff(tlim), action = .stan3d.redraw,showvalue=TRUE)
@@ -56,11 +47,16 @@
   require(rgl)
   require(rpanel)
   if(missing(states)){
+    ## default colouring scheme:
     states=list(
-      s1=list(col="blue",radius=1/80),
-      s2=list(col="red",radius=1/20),
-      s3=list(col="yellow",radius=1/40)
+      s1=list(col="blue",radius=1/80,alpha=1.0),
+      s2=list(col="red",radius=1/20,alpha=1.0),
+      ## still-to-come points are invisible (alpha=0)
+      s3=list(col="yellow",alpha=0.0,radius=1/80)
       )
+    if(persist){
+      states$s1=states$s2
+    }
   }
   xyt=data.frame(xyt)
   xyt$id=NA
@@ -81,7 +77,7 @@
   for(i in 1:(dim(xyt)[1])){
     xyt[i,4]=points3d(xyt[,1],xyt[,2],xyt[,3])
   }
-  .rp.stan3d(xyt,tlim,twid,persist,states)
+  .rp.stan3d(xyt,tlim,twid,states)
 }
 
 .ranger=function(x,margin=0.2){

Modified: pkg/man/stani.Rd
===================================================================
--- pkg/man/stani.Rd	2008-10-23 16:14:25 UTC (rev 6)
+++ pkg/man/stani.Rd	2008-10-24 10:46:05 UTC (rev 7)
@@ -12,15 +12,38 @@
   \item{tlim}{A two-element vector of upper and lower time limits}
   \item{twid}{The initial time window width}
   \item{persist}{Whether to display points before time window}
-  \item{states}{How to display points}
+  \item{states}{How to display points - see Details}
 }
 \details{
 This function requires the \code{rpanel} and \code{rgl} packages. It
 uses \code{rpanel} for the sliders to control the graphics, and
 \code{rgl} for its ability to do flicker-free graphics.
 
+The sliders set the position and width of the temporal highlight
+window. For 'time' slider set to time T and 'width' slider set to W,
+highlighted points are those with time coordinate t such that T-W < t <
+T.
 
+How points are shown is configured with the states parameter. This is a
+list of length 3 specifying how points before the time window, inside
+the time window, and after the time window are displayed. Each element
+is a list of parameters as would be passed to material3d() together with
+a radius element. Points are drawn as spheres with the corresponding
+material and radius as a fraction of the spatial span of the data.
 
+By default the third state is invisible, and the first two states are
+different. By calling with the default for states and persist=TRUE,
+then the first state is set to the same as the second state. This has
+the effect of showing all points at time < T with the same sphere type.
+
+If the user specifies the states parameter, then persist is ignored. The
+user can emulate the persist behaviour by specifying a states list with
+identical parameters for states 1 and 2.
+
+Note that each state element should specify all material3d parameters
+used in any of the state elements. This is to make sure the parameters
+are reset for each of the sets of points.
+
 }
 \value{
 None