*Disponible uniquement en anglais*

Sysquake Pro – Table of Contents

Sysquake for LaTeX – Table of Contents

# 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.

#### See also

`campan`,
`camorbit`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`campan`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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).

#### See also

`camdolly`,
`camorbit`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camroll`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camproj`,
`camtarget`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camproj`,
`camroll`,
`camup`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camva`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camzoom`

### 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.

#### See also

`camdolly`,
`camorbit`,
`campan`,
`campos`,
`camproj`,
`camroll`,
`camtarget`,
`camup`,
`camva`

### 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'`.

#### See also

### 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.

#### See also

### 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.

#### See also

### 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
`line3` is a matrix which contains the coefficients

**Explicit equations:**
Lines are defined by equations of the form
`line3` is a matrix which contains the coefficients

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])

#### See also

### 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.

#### See also

### 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);

#### See also

### 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]);

#### See also

### 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.

#### See also

### 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)

#### See also

### 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');