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).
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 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.
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.
Move view position and target.
camdolly(d) translates the camera by 3x1 or 1x3 vector d, moving the target and the view point by the same amount.
Camera orbit around target.
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.
Tilt and pan camera.
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(p) campos auto campos manual p = campos
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(str) str = camproj
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.
Camera roll around view direction.
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(p) camtarget auto camtarget manual p = camtarget
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(p) camup auto camup manual p = camup
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(va) va = camva
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.
Zoom in or out.
camzoom(f) scales the projection by a factor f. The image grows if f is larger than one, and shrinks if it is smaller.
Level curves in 3D space.
contour3(z) contour3(z, [xmin, xmax, ymin, ymax]) contour3(z, [xmin, xmax, ymin, ymax], levels) contour3(z, [xmin, xmax, ymin, ymax], levels, style)
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'.
Scale ratios along x, y and z axis.
daspect([rx,ry,rz]) daspect() R = daspect
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.
Set light sources in 3D world.
lightangle lightangle(az, el)
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.
Plot straight lines in 3D space.
line3(A, b) line3(V, P0) line3(A, b, style) line3(A, b, style, id)
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.
Lines are defined by two equations of the form
Lines are defined by equations of the form
The optional third and fourth arguments are the same as for all graphical commands.
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])
Surface reflexion properties.
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.
Plot a mesh in 3D space.
mesh(x, y, z) mesh(z) mesh(x, y, z, color) mesh(z, color) mesh(..., kind) mesh(..., kind, style) mesh(..., kind, style, id)
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.
(X, Y) = meshgrid([-2:0.2:2]); Z = X.*exp(-X.^2-Y.^2); mesh(X, Y, Z);
Generic 3D plot.
plot3(x, y, z) plot3(x, y, z, style) plot3(x, y, z, style, id)
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.
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]);
Plot polygons in 3D space.
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)
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.
Make graphical element sensitivive to 3D interactive displacement.
sensor3(type, param, id) sensor3(type, param, typeAlt, paramAlt, id)
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.
(simple XY plane...)
(phi/theta without modifier, R with modifier with plane and ignored 2nd param)
Plot a surface defined by a grid in 3D space.
surf(x, y, z) surf(z) surf(x, y, z, color) surf(z, color) surf(..., vis) surf(..., vis, style) surf(..., vis, style, id)
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.
(X, Y) = meshgrid([-2:0.2:2]); Z = X.*exp(-X.^2-Y.^2); surf(X, Y, Z, 'k');