Scilab Function

plot3d - 3D plot of a surface

### Calling Sequence

  `plot3d(x,y,z,[theta,alpha,leg,flag,ebox])`
  `plot3d(x,y,z,<opt_args>)`
  ``
  `plot3d(xf,yf,zf,[theta,alpha,leg,flag,ebox])`
  `plot3d(xf,yf,zf,<opt_args>)`
  ``
  `plot3d(xf,yf,list(zf,colors),[theta,alpha,leg,flag,ebox])`
  `plot3d(xf,yf,list(zf,colors),<opt_args>)`

### Parameters

- `x,y` : row vectors of sizes n1 and n2 (x-axis and y-axis coordinates). These coordinates must be monotone.
- `z` : matrix of size (n1,n2). `z(i,j)` is the value of the surface at the point (x(i),y(j)).
- `xf,yf,zf` : matrices of size (nf,n). They define the facets used to draw the surface. There are `n` facets. Each facet `i` is defined by a polygon with `nf` points. The x-axis, y-axis and z-axis coordinates of the points of the ith facet are given respectively by `xf(:,i)`, `yf(:,i)` and `zf(:,i)`.
- `colors` : a vector of size n giving the color of each facets or a matrix of size (nf,n) giving color near each facet boundary (facet color is interpolated )
- `<opt_args>` : This represents a sequence of statements `key1=value1, key2=value2`,... where `key1`, `key2,...` can be one of the following: theta, alpha ,leg,flag,ebox (see definition below)
- `theta, alpha` : real values giving in degree the spherical coordinates of the observation point.
- `leg` : string defining the captions for each axis with @ as a field separator, for example "X@Y@Z".
- `flag` : a real vector of size three `flag=[mode,type,box]`.

- `mode` : string (treatment of hidden parts).

- `mode>0` the hidden parts of the surface are removed and the surface is painted with color `mode`.
- `mode=0` the hidden parts of the surface are drawn.
- `mode<0` only the backward facing facets are painted with color or pattern id `-mode`. Use `xset()` to see the meaning of the ids.

- `type` : an integer (scaling).

- `type=0` the plot is made using the current 3D scaling (set by a previous call to `param3d`, `plot3d`, `contour` or `plot3d1`).
- `type=1` rescales automatically 3d boxes with extreme aspect ratios, the boundaries are specified by the value of the optional argument `ebox`.
- `type=2` rescales automatically 3d boxes with extreme aspect ratios, the boundaries are computed using the given data.
- `type=3` 3d isometric with box bounds given by optional `ebox`, similarily to `type=1`
- `type=4` 3d isometric bounds derived from the data, to similarily`type=2`
- `type=5` 3d expanded isometric bounds with box bounds given by optional `ebox`, similarily to `type=1`
- `type=6` 3d expanded isometric bounds derived from the data, similarily to `type=2`

- `box` : an integer (frame around the plot).

- `box=0` nothing is drawn around the plot.
- `box=1` unimplemented (like box=0).
- `box=2` only the axes behind the surface are drawn.
- `box=3` a box surrounding the surface is drawn and captions are added.
- `box=4` a box surrounding the surface is drawn, captions and axes are added.

- `ebox` : used when `type` in `flag` is 1. It specifies the boundaries of the plot as the vector `[xmin,xmax,ymin,ymax,zmin,zmax]`.

### Description

`plot3d(x,y,z,[theta,alpha,leg,flag,ebox])` draws the parametric surface `z=f(x,y)`.

`plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])` draws a surface defined by a set of facets. You can draw multiple plots by replacing `xf`, `yf` and `zf` by multiple matrices assembled by rows as `[xf1 xf2 ...]`, `[yf1 yf2 ...]` and `[zf1 zf2 ...]`.

You can give a specific color for each facet by using `list(zf,colors)` instead of `zf`, where `colors` is a vector of size `n`. If `colors(i)` is positive it gives the color of facet `i` and the boundary of the facet is drawn with current line style and color. If `colors(i)` is negative, color id `-colors(i)` is used and the boundary of the facet is not drawn. Use `xset()` to see the ids of the colors.

It is also possible to get interpolated color for facets. For that the color argument must be a matrix of size nfxn giving the color near each boundary of each facets. In this case positive values for colors mean that the boundary are not drawn.

The optional arguments `theta,alpha,leg ,flag,ebox`, can be passed by a sequence of statements `key1=value1, key2=value2`, ... In this case, the order has no special meaning.

You can use the function `genfac3d` to compute four sided facets from the surface `z=f(x,y)`. `eval3dp` can also be used.

Enter the command `plot3d()` to see a demo.

### Examples

    // simple plot using z=f(x,y)
    t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
    plot3d(t,t,z)
    // same plot using facets computed by genfac3d
    [xx,yy,zz]=genfac3d(t,t,z);
    xbasc()
    plot3d(xx,yy,zz)
    // multiple plots
    xbasc()
    plot3d([xx xx],[yy yy],[zz 4+zz])
    // multiple plots using colors
    xbasc()
    plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
    // simple plot with viewpoint and captions
    xbasc()
    plot3d(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3])
    // plot of a sphere using facets computed by eval3dp
    deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
      "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
      "z=r*sin(alp)+orig(3)*ones(tet)"]);
    r=1; orig=[0 0 0];
    [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
    xbasc();plot3d(xx,yy,zz)

    xbasc();xset('colormap',hotcolormap(128));
    r=0.3;orig=[1.5 0 0];
    [xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
    cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32;
    xbasc();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),70,80)

    xbasc();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])

### See Also

`eval3dp` `genfac3d` `geom3d` `param3d` `plot3d1` `xset`

### Author

J.Ph.C.