The R Project SVN R

Rev

Rev 68948 | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 68948 Rev 84795
Line 1... Line 1...
1 
% File src/library/grDevices/man/trans3d.Rd
 1 
% File src/library/grDevices/man/trans3d.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright 1995-2007 R Core Team
 3 
% Copyright 1995-2023 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{trans3d}
 6 
\name{trans3d}
7 
\alias{trans3d}
 7 
\alias{trans3d}
8 
\title{3D to 2D Transformation for Perspective Plots}
 8 
\title{3D to 2D Transformation for Perspective Plots}
Line 10... Line 10...
10 
  Projection of 3-dimensional to 2-dimensional points using a 4x4
 10 
  Projection of 3-dimensional to 2-dimensional points using a 4x4
11 
  viewing transformation matrix.  Mainly for adding to
 11 
  viewing transformation matrix.  Mainly for adding to
12 
  perspective plots such as \code{\link{persp}}.
 12 
  perspective plots such as \code{\link{persp}}.
13 
}
 13 
}
14 
\usage{
 14 
\usage{
15 
trans3d(x, y, z, pmat)
 15 
trans3d(x, y, z, pmat, continuous = FALSE, verbose = TRUE)
16 
}
 16 
}
17 
\arguments{
 17 
\arguments{
18 
  \item{x, y, z}{numeric vectors of equal length, specifying points in
 18 
  \item{x, y, z}{numeric vectors of equal length, specifying points in
19 
    3D space.}
 19 
    3D space.}
20 
  \item{pmat}{a \eqn{4 \times 4}{4 x 4} \emph{viewing transformation matrix},
 20 
  \item{pmat}{a \eqn{4 \times 4}{4 x 4} \emph{viewing transformation matrix},
21 
    suitable for projecting the 3D coordinates \eqn{(x,y,z)} into the 2D
 21 
    suitable for projecting the 3D coordinates \eqn{(x,y,z)} into the 2D
22 
    plane using homogeneous 4D coordinates \eqn{(x,y,z,t)};
 22 
    plane using homogeneous 4D coordinates \eqn{(x,y,z,t)};
23 
    such matrices are returned by \code{\link{persp}()}.}
 23 
    such matrices are returned by \code{\link{persp}()}.}
- 
 
 24 
  \item{continuous}{logical flag specifying if the transformation should
- 
 
 25 
    check if the transformed points are continuous in the sense that they
- 
 
 26 
    do not jump over \eqn{a/0} discontinuity.  As these assume
- 
 
 27 
    \code{(x,y,z)} to describe a continuous curve, the default must be
- 
 
 28 
    false.  In case of projecting such a curve however, setting
- 
 
 29 
    \code{continuous=TRUE} may be advisable.}
- 
 
 30 
  \item{verbose}{only for \code{continuous=TRUE}, indicates if a warning
- 
 
 31 
    should be issued when points are cut off.}
24 
}
 32 
}
25 
\value{
 33 
\value{
26 
  a list with two components
 34 
  a list with two components
27 
  \item{x,y}{the projected 2d coordinates of the 3d input \code{(x,y,z)}.}
 35 
  \item{x,y}{the projected 2d coordinates of the 3d input \code{(x,y,z)}.}
28 
}
 36 
}
29 
\seealso{ \code{\link{persp}} }
 37 
\seealso{ \code{\link{persp}} }
30 
\examples{
 38 
\examples{
31 
%% it would be nice to have an independent example
 - 
 
32 
## See  help(persp) {after attaching the 'graphics' package}
 39 
## See  help(persp) {after attaching the 'graphics' package}
33 
##      -----------
 40 
##      -----------
- 
 
 41 
 
- 
 
 42 
## Example for 'continuous = TRUE' (vs default):
- 
 
 43 
require(graphics)
- 
 
 44 
x <- -10:10/10 # [-1, 1]
- 
 
 45 
y <- -16:16/16 # [-1, 1] ==> z = fxy := outer(x,y) is also in [-1,1]
- 
 
 46 
 
- 
 
 47 
p <- persp(x, y, fxy <- outer(x,y), phi = 20, theta = 15, r = 3, ltheta = -75,
- 
 
 48 
           shade = 0.8, col = "green3", ticktype = "detailed")
- 
 
 49 
## 5 axis-parallel auxiliary lines in x-y  and y-z planes :
- 
 
 50 
lines(trans3d(-.5 , y=-1:1, z=min(fxy),  pmat=p), lty=2)
- 
 
 51 
lines(trans3d(  0 , y=-1:1, z=min(fxy),  pmat=p), lty=2)
- 
 
 52 
lines(trans3d(-1:1, y= -.7, z=min(fxy),  pmat=p), lty=2)
- 
 
 53 
lines(trans3d( -1,  y= -.7, z=c(-1,1) ,  pmat=p), lty=2)
- 
 
 54 
lines(trans3d( -1,  y=-1:1, z= -.5    ,  pmat=p), lty=2)
- 
 
 55 
## 2 pillars to carry the horizontals below:
- 
 
 56 
lines(trans3d(-.5 , y= -.7, z=c(-1,-.5), pmat=p), lwd=1.5, col="gray10")
- 
 
 57 
lines(trans3d( 0  , y= -.7, z=c(-1,-.5), pmat=p), lwd=1.5, col="gray10")
- 
 
 58 
## now some "horizontal rays" (going from center to very left or very right):
- 
 
 59 
doHor <- function(x1, x2, z, CNT=FALSE, ...)
- 
 
 60 
    lines(trans3d(x=seq(x1, x2, by=0.5), y= -0.7, z = z, pmat = p, continuous = CNT),
- 
 
 61 
          lwd = 3, type="b", xpd=NA, ...)
- 
 
 62 
doHor(-10,  0, z = -0.5, col = 2)  # x in [-10, 0] -- to the very left : fine
- 
 
 63 
doHor(-.5,  2, z = -0.52,col = 4) # x in [-0.5, 2] only {to the right} --> all fine
- 
 
 64 
## but now, x in [-0.5, 20] -- "too far" ==> "wrap around" problem (without 'continuous=TRUE'):
- 
 
 65 
doHor(-.5, 20, z = -0.58, col = "steelblue", lty=2)
- 
 
 66 
## but it is fixed with continuous = CNT = TRUE:
- 
 
 67 
doHor(-.5, 20, z = -0.55, CNT=TRUE, col = "skyblue")
34 
}
 68 
}
35 
\keyword{dplot}
 69 
\keyword{dplot}