3D Graphic Functions

Three-dimension graphic commands enable the representation of objects defined in three dimensions x, y and z on the two-dimension screen. The transform from the 3D space to the screen is performed as if there were a virtual camera in the 3D space with a given position, orientation, and angle of view (related to the focal length in a real camera).

Projection

The projection is defined by the following parameters:

Target point: The target point is a 3D vector which defines the position where the camera is oriented to.
Projection kind: Two kinds of projections are supported: orthographic and perspective.
View point: The view point is a 3D vector which defines the position of the camera. For orthographic projection, it defines a direction independent from the target position; for perspective projection, it defines a position, and the view orientation is defined by the vector from view point to target point.
Up vector: The up vector is a 3D vector which fixes the orientation of the camera around the view direction. The projection is such that the up vector is in a plane which is vertical in the 2D projection. Changing it makes the projection rotate around the image of the target.
View angle: The view angle defines the part of the 3D space which is projected onto the image window in perspective projections. It is zero in orthographic mode.

All of these parameters can be set automatically. Here is how the whole projection and scaling process is performed:

Scale data separately along each direction according to daspect
Find bounding box of all displayed data, or use limits set with scale
Find radius of circumscribed sphere of bounding box
If the target point is automatic, set it to the center of the bounding box; otherwise, use position set with camtarget
If the view point is automatic, set it to direction [-3;-2;1] at infinity in orthographic mode, or in that direction with respect to the target point at a distance such that the view angle of the circumscribed sphere is about 6 degrees; otherwise, use position set with campos
If the up vector is automatic, set it to [0,0,1] (vertical, pointing upward); otherwise, use position set with camup
Compute the corresponding homogeneous matrix transform
Set the base scaling factor so that the circumscribed sphere fits the display area
Apply an additional zoom factor which depends on camva and camzoom

Surface shading

Surface and mesh colors add information to the image, helping the viewer in interpreting it. Colors specified by the style argument also accepted by 2D graphical commands are used unchanged. Colors specified by a single-component value, RGB colors, or implicit, are processed differently whether lightangle and/or material have been executed, or not. In the first case, colors depend directly on the colors specified or the default value; in the second case, the Blinn-Phong reflection model is used with flat shading. In both cases, single-color values are mapped to colors using the current color map (set with colormap). Commands which accept a color argument are mesh, surf, and plotpoly.

Direct colors

If neither lightangle nor material has been executed, colors depend only on the color argument provided with x, y, and z coordinates. If the this argument is missing, color is obtained by mapping linearly the z coordinates to the full range of the current color map.

Blinn-Phong reflection model

In the Blinn-Phong reflexion model, the color of a surface depends on the intrinsic object color, the surface reflexion properties, and the relative positions of the surface, the viewer, and light sources.

camdolly

Move view position and target.

Syntax

camdolly(d)

Description

camdolly(d) translates the camera by 3x1 or 1x3 vector d, moving the target and the view point by the same amount.

camorbit

Camera orbit around target.

Syntax

camorbit(dphi, dtheta)

Description

camorbit(dphi,dtheta) rotates the camera around the target point by angle dphi around the up vector, and by angle dtheta around the vector pointing to the right of the projection plane. Both angles are given in radians. A positive value of dphi makes the camera move to the right, and a positive value of dtheta makes the camera move down.

campan

Tilt and pan camera.

Syntax

campan(dphi, dtheta)

Description

campan(dphi,dtheta) pans the camera by angle dphi and tilts it by angle dtheta. Both angles are in radians. More precisely, the target point is changed so that the vector from view point to target is rotated by angle dphi around the up vector, then by angle dtheta around a "right" vector (a vector which is horizontal in view coordinates).

campos

Camera position.

Syntax

campos(p)
campos auto
campos manual
p = campos

Description

campos(p) sets the view position to p. p is a 3D vector.

campos auto sets the view position to automatic mode, so that it follows the target. campos manual sets the view position to manual mode.

With an output argument, campos gives the current view position.

camproj

Projection kind.

Syntax

camproj(str)
str = camproj

Description

camproj(str) sets the projection mode; string str can be either 'orthographic' (or 'o') for a parallel projection, or 'perspective' (or 'p') for a projection with a view point at a finite distance.

With an output argument, camproj gives the current projection mode.

camroll

Camera roll around view direction.

Syntax

camroll(dalpha)

Description

camroll(dalpha) rotates the up vector by angle dalpha around the vector from view position to target. dalpha is given in radians. A positive value makes the scene rotate counterclockwise.

camtarget

Target position.

Syntax

camtarget(p)
camtarget auto
camtarget manual
p = camtarget

Description

camtarget(p) sets the target to p. p is a 3D vector.

camtarget auto sets the target to automatic mode, so that it follows the center of the objects which are drawn. camtarget manual sets the target to manual mode.

With an output argument, camtarget gives the current target.

camup

Up vector.

Syntax

camup(p)
camup auto
camup manual
p = camup

Description

camup(p) sets the up vector to p. p is a 3D vector.

camup auto sets the up vector to [0,0,1]. camup manual does nothing.

With an output argument, camup gives the current up vector.

camva

View angle.

Syntax

camva(va)
va = camva

Description

camva(va) sets the view angle to va, which is expressed in degrees. The projection mode is set to 'perspective'. The scale is adjusted so that the graphics have about the same size.

With an output argument, camva gives the view angle in degrees, which is 0 for an orthographic projection.

camzoom

Zoom in or out.

Syntax

camzoom(f)

Description

camzoom(f) scales the projection by a factor f. The image grows if f is larger than one, and shrinks if it is smaller.

contour3

Level curves in 3D space.

Syntax

contour3(z)
contour3(z, [xmin, xmax, ymin, ymax])
contour3(z, [xmin, xmax, ymin, ymax], levels)
contour3(z, [xmin, xmax, ymin, ymax], levels, style)

Description

contour3(z) plots in 3D space seven contour lines corresponding to the surface whose samples at equidistant points 1:size(z,2) in the x direction and 1:size(z,1) on the y direction are given by z. Contour lines are at equidistant levels. With a second non-empty argument [xmin, xmax, ymin, ymax], the samples are at equidistant points between xmin and xmax in the x direction and between ymin and ymax in the y direction.

The optional third argument levels, if non-empty, gives the number of contour lines if it is a scalar or the levels themselves if it is a vector.

The optional fourth argument is the style of each line, from the minimum to the maximum level (styles are recycled if necessary). The default style is 'kbrmgcy'.

daspect

Scale ratios along x, y and z axis.

Syntax

daspect([rx,ry,rz])
daspect([])
R = daspect

Description

daspect(R) specifies the scale ratios along x, y and z axis. Argument R is a vector of 3 elements rx, ry and rz. Coordinates in the 3D space are divided by rx along the x axis, and so on, before the projection is performed. For example, a box whose size is [2;5;3] would be displayed as a cube with daspect([2;5;3]).

daspect([]) sets the scale ratios so that the bounding box of 3D elements is displayed as a cube.

With an output argument, R=daspect gives the current scale ratios as a vector of 3 elements.

lightangle

Set light sources in 3D world.

Syntax

lightangle
lightangle(az, el)

Description

lightangle(az,el) set lighting source(s) at infinity, with asimuth az and elevation el, both in radians. With missing input argument, the default azimuth is 4 and the default elevation is 1. If az and el are vectors, they must have the same size (except if one of them is a scalar, then it is replicated as needed); lightangle sets multiple light sources.

line3

Plot straight lines in 3D space.

Syntax

line3(A, b)
line3(V, P0)
line3(A, b, style)
line3(A, b, style, id)

Description

line3 displays one or several straight line(s) in the 3D space. Each line is defined by two implicit equations or one explicit, parametric equation.

Implicit equation: Lines are defined by two equations of the form a1 x + a2 y + a3 z = b. The first argument of line3 is a matrix which contains the coefficients a1 in the first column, a2 in the second column, and a3 in the third column; two rows define a different line. The second argument is a column vector which contains the coefficients b. If one of these arguments has two rows and the other has several pairs, the same rows are reused multiple times.

Explicit equations: Lines are defined by equations of the form P=P0+lambda*V where P0 is a point of the line, V a vector which defines its direction, and lambda a real parameter. The first argument of line3 is a matrix which contains the coefficients vx in the first column, vy in the second column and vz in the third column. The second argument is a matrix which contains the coefficients x0 in the first column, y0 in the second column and z0 in the third column.

The optional third and fourth arguments are the same as for all graphical commands.

Example

Implicit or parametric forms of a vertical line at x=5, y=6:

line3([1,0,0;0,1,0], [5;6])
line3([0, 0, 1], [5, 6, 0])

material

Surface reflexion properties.

Syntax

material(p)

Description

material(p) sets the reflexion properties of the Blinn-Phong model of following surfaces drawn with surf and plotpoly. Argument p is a scalar or a vector of two real values between 0 and 1. The first or only element, ka, is the weight of ambiant light; the second element, kd, is the weight of diffuse light reflected from all light sources.

mesh

Plot a mesh in 3D space.

Syntax

mesh(x, y, z)
mesh(z)
mesh(x, y, z, color)
mesh(z, color)
mesh(..., kind)
mesh(..., kind, style)
mesh(..., kind, style, id)

Description

mesh(x,y,z) plots a mesh defined by 2-D arrays x, y and z. Arguments x and y must have the same size as z or be vectors of size(z,2) and size(z,1) elements, respectively. If x and y are missing, their default values are coordinates from 1 to size(z,2) along x axis and from 1 to size(z,1) along y axis. Color is obtained by mapping the full range of z values to the color map.

mesh(x,y,z,color) maps values of array color to the color map. color must have the same size as z and contain values between 0 and 1, which are mapped to the color map.

mesh(...,kind) specifies which side of the mesh is visible. kind is a string of 1 or 2 characters: 'f' if the front side is visible (the side where increasing y are on the left of increasing x coordinates), and 'b' if the back side is visible. Default '' is equivalent to 'fb'.

mesh(...,style) specifies the line or symbol style of the mesh. The default '' is to map z or color values to the color map.

mesh(...,id) specifies the ID used for interactivity in Sysquake.

Example

(X, Y) = meshgrid([-2:0.2:2]);
Z = X.*exp(-X.^2-Y.^2);
mesh(X, Y, Z);

plot3

Generic 3D plot.

Syntax

plot3(x, y, z)
plot3(x, y, z, style)
plot3(x, y, z, style, id)

Description

The command plot3 displays 3D graphical data in the current figure. The data are given as three vectors of coordinates x, y and z. Depending on the style, the points are displayed as individual marks or are linked with lines.

If x, y and z are matrices, each row is considered as a separate line or set of marks; row or column vectors are replicated to match the size of matrix arguments if required.

plot3(...,id) specifies the ID used for interactivity in Sysquake.

Example

Chaotic attractor of the Shimizu-Morioka system:

(t,x) = ode45(@(t,x) [x(2); (1-x(3))*x(1)-0.75*x(2); x(1)^2-0.45*x(3)],
	[0,300], [1;1;1]);
plot3(x(:,1)', x(:,2)', x(:,3)', 'r');
label x y z;
campos([-1.5; -1.4; 3.1]);

plotpoly

Plot polygons in 3D space.

Syntax

plotpoly(x, y, z, ind)
plotpoly(x, y, z, 'strip')
plotpoly(x, y, z, 'fan')
plotpoly(x, y, z, color, ind)
plotpoly(x, y, z, color, 'strip')
plotpoly(x, y, z, color, 'fan')
plotpoly(..., vis)
plotpoly(..., vis, style)
plotpoly(..., vis, style, id)

Description

plotpoly(x,y,z,ind) plots polygons whose vertices are given by vectors x, y and z. Rows of argument ind contain the indices of each polygon in arrays x, y, and z. Vertices can be shared by several polygons. Color of each polygon is mapped linearly from the z coordinate of the center of gravity of its vertices to the color map. Each polygon can be concave, but must be planar and must not self-intersect (different polygons may intersect).

plotpoly(x,y,z,'strip') plots a strip of triangles. Triangles are made of three consecutive vertices; their indices could be defined by the following array ind_strip:

ind_strip = ...
[ 1 2 3
  3 2 4
  3 4 5
  5 4 6
  5 6 7
  etc. ];

Ordering is such that triangles on the same side of the strip have the same orientation.

plotpoly(x,y,z,'fan') plots triangles which share the first vertex and form a fan. Their indices could be defined by the following array ind_fan:

ind_fan = ...
[ 1 2 3
  1 3 4
  1 4 5
  etc. ];

plotpoly(x,y,z,color,...) uses color instead of z to set the filling color of each polygon. color is always a real double array (or scalar) whose elements are between 0 and 1. How it is interpreted depends on its size:

A scalar defines the color of all polygons; it is mapped to the color map.
A vector of three elements defines the RGB color of all polygons (row vector if there are 3 vertices to avoid ambiguity).
A vector with as many elements as x, y and z defines the color of each vertex (column vector if there are 3 vertices to avoid ambiguity). Polygons have the mean value of all their vertices, which is mapped to the color map.
An array with as many columns as elements in x, y and z defines the RGB color of each vertex. Polygons have the mean value of all their vertices.

plotpoly(...,vis) uses string vis to specify which side of the surface is visible: 'f' for front only, 'b' for back only, or 'fb' or 'bf' for both sides. The front side is defined as the one where vertices have an anticlockwise orientation. The default is 'f'.

plotpoly(...,vis,style) uses string style to specify the style of edges.

plotpoly(...,id) specifies the ID used for interactivity in Sysquake.

sensor3

Make graphical element sensitivive to 3D interactive displacement.

Syntax

sensor3(type, param, id)
sensor3(type, param, typeAlt, paramAlt, id)

Description

sensor3(type,param,id) specifies how a 3D element can be dragged interactively. Contrary to 2D graphics where the mapping between the mouse cursor and the graphical coordinates depends on two separate scaling factors, manipulation in 3D space must use a surface as an additional constraint. sensor3 specifies this surface for a graphical object whose ID is the same as argument id.

The constraint surface is specified with string type and numeric array param. It always contains the selected point. For instance, if the user clicks the second point of plot3([1,2],[5,3],[2,4],'',1) and sensor3 defines a horizontal plane, the move lies in horizontal plane z=4. In addition to position _p1, parameters specific to the constraint surface are provided in special variable _q, a vector of two elements.

type = 'plane': The constraint surface is the plane defined by the selected point _p0 and two vectors [vx1;vy1;vz1] and [vx2;vy2;vz2] given in argument param = [vx1,vy1,vz1; vx2,vy2,vz2]. During the drag, _q contains the coefficients of these two vectors, such that _p1 = _p0+_q'*param'.
type = 'sphere': The constraint surface is a sphere whose center is defined by a point param = [px,py,pz]. Its R is such that the surface contains the selected point _p0. During the drag, _q contains the spherical coordinates phi and theta, such that _p1 = param' + R * [cos(q_(1))*cos(q_(2)); sin(q_(1))*cos(q_(2)); sin(q_(2))].

With five input arguments, sensor3(type,param,typeAlt,paramAlt,id) specifies an alternative constraint surface used when the modifier key is held down.

Examples

(simple XY plane...)

(phi/theta without modifier, R with modifier with plane and ignored 2nd param)

surf

Plot a surface defined by a grid in 3D space.

Syntax

surf(x, y, z)
surf(z)
surf(x, y, z, color)
surf(z, color)
surf(..., vis)
surf(..., vis, style)
surf(..., vis, style, id)

Description

surf(x,y,z) plots a surface defined by 2-D arrays x, y and z. Arguments x and y must have the same size as z or be vectors of size(z,2) and size(z,1) elements, respectively. If x and y are missing, their default values are coordinates from 1 to size(z,2) along x axis and from 1 to size(z,1) along y axis. Color of each surface cell is obtained by mapping the average z values to the color map.

surf(x,y,z,color) maps values of array color to the color map. color must have the same size as z and contain values between 0 and 1.

surf(...,vis) specifies which side of the surface is visible. vis is a string of 1 or 2 characters: 'f' if the front side is visible (the side where increasing y are on the left of increasing x coordinates), and 'b' if the back side is visible. Default '' is equivalent to 'fb'.

surf(...,style) specifies the line or symbol style of the mesh between surface cells, or the fill style of the surface. The default '' is to map z or color values to the color map for the surface cells and not to draw cell bounds.

mesh(...,id) specifies the ID used for interactivity in Sysquake.

Example

(X, Y) = meshgrid([-2:0.2:2]);
Z = X.*exp(-X.^2-Y.^2);
surf(X, Y, Z, 'k');

3D Graphic Functions

Projection

Surface shading

Direct colors

Blinn-Phong reflection model

camdolly

Syntax

Description

See also

camorbit

Syntax

Description

See also

campan

Syntax

Description

See also

campos

Syntax

Description

See also

camproj

Syntax

Description

See also

camroll

Syntax

Description

See also

camtarget

Syntax

Description

See also

camup

Syntax

Description

See also

camva

Syntax

Description

See also

camzoom

Syntax

Description

See also

contour3

Syntax

Description

See also

daspect

Syntax

Description

See also

lightangle

Syntax

Description

See also

line3

Syntax

Description

Example

See also

material

Syntax

Description

See also

mesh

Syntax

Description

Example

See also

plot3

Syntax

Description

Example

See also

plotpoly

Syntax

Description

See also