@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 2007-2025 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Geometry
@chapter Geometry

Much of the geometry code in Octave is based on the Qhull
library@footnote{@nospell{Barber, C.B., Dobkin, D.P., and Huhdanpaa, H.T.},
@cite{The Quickhull Algorithm for Convex Hulls}, @nospell{ACM} Trans.@: on
Mathematical Software, 22(4):469--483, Dec 1996, @url{http://www.qhull.org}}.
Some of the documentation for Qhull, particularly for the options that
can be passed to @code{delaunay}, @code{voronoi} and @code{convhull},
etc., is relevant to Octave users.

@menu
* Delaunay Triangulation::
* Voronoi Diagrams::
* Convex Hull::
* Interpolation on Scattered Data::
* Vector Rotation Matrices::
@end menu

@node Delaunay Triangulation
@section Delaunay Triangulation

The Delaunay triangulation is constructed from a set of
circum-circles.  These circum-circles are chosen so that there are at
least three of the points in the set to triangulation on the
circumference of the circum-circle.  None of the points in the set of
points falls within any of the circum-circles.

In general there are only three points on the circumference of any
circum-circle.  However, in some cases, and in particular for the
case of a regular grid, 4 or more points can be on a single
circum-circle.  In this case the Delaunay triangulation is not unique.

@c delaunay scripts/geometry/delaunay.m
@anchor{XREFdelaunay}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tri} =} delaunay (@var{x}, @var{y})
@deftypefnx {} {@var{tetr} =} delaunay (@var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{tri} =} delaunay (@var{x})
@deftypefnx {} {@var{tri} =} delaunay (@dots{}, @var{options})
Compute the Delaunay triangulation for a 2-D or 3-D set of points.

For 2-D sets, the return value @var{tri} is a set of triangles which
satisfies the Delaunay circum-circle criterion, i.e., no data point from
[@var{x}, @var{y}] is within the circum-circle of the defining triangle.
The set of triangles @var{tri} is a matrix of size [n, 3].  Each row defines
a triangle and the three columns are the three vertices of the triangle.
The value of @code{@var{tri}(i,j)} is an index into @var{x} and @var{y} for
the location of the j-th vertex of the i-th triangle.

For 3-D sets, the return value @var{tetr} is a set of tetrahedrons which
satisfies the Delaunay circum-circle criterion, i.e., no data point from
[@var{x}, @var{y}, @var{z}] is within the circum-circle of the defining
tetrahedron.  The set of tetrahedrons is a matrix of size [n, 4].  Each row
defines a tetrahedron and the four columns are the four vertices of the
tetrahedron.  The value of @code{@var{tetr}(i,j)} is an index into @var{x},
@var{y}, @var{z} for the location of the j-th vertex of the i-th
tetrahedron.

The input @var{x} may also be a matrix with two or three columns where the
first column contains x-data, the second y-data, and the optional third
column contains z-data.

An optional final argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options are @code{@{"Qt", "Qbb", "Qc"@}}.
If Qhull fails for 2-D input the triangulation is attempted again with
the options @code{@{"Qt", "Qbb", "Qc", "Qz"@}} which may result in
reduced accuracy.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@example
@group
x = rand (1, 10);
y = rand (1, 10);
tri = delaunay (x, y);
triplot (tri, x, y);
hold on;
plot (x, y, "r*");
axis ([0,1,0,1]);
@end group
@end example
@xseealso{@ref{XREFdelaunayn,,delaunayn}, @ref{XREFconvhull,,convhull}, @ref{XREFvoronoi,,voronoi}, @ref{XREFtriplot,,triplot}, @ref{XREFtrimesh,,trimesh}, @ref{XREFtetramesh,,tetramesh}, @ref{XREFtrisurf,,trisurf}}
@end deftypefn


For 3-D inputs @code{delaunay} returns a set of tetrahedra that satisfy the
Delaunay circum-circle criteria.  Similarly, @code{delaunayn} returns the
N-dimensional simplex satisfying the Delaunay circum-circle criteria.
The N-dimensional extension of a triangulation is called a tessellation.

@c delaunayn scripts/geometry/delaunayn.m
@anchor{XREFdelaunayn}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{T} =} delaunayn (@var{pts})
@deftypefnx {} {@var{T} =} delaunayn (@var{pts}, @var{options})
Compute the Delaunay triangulation for an N-dimensional set of points.

The Delaunay triangulation is a tessellation of the convex hull of a set of
points such that no N-sphere defined by the N-triangles contains any other
points from the set.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.  The return matrix @var{T} has size [m, dim+1].  Each row of
@var{T} contains a set of indices back into the original set of points
@var{pts} which describes a simplex of dimension dim.  For example, a 2-D
simplex is a triangle and 3-D simplex is a tetrahedron.

An optional second argument, which must be a string or cell array of
strings, contains options passed to the underlying qhull command.  See the
documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options depend on the dimension of the input:

@itemize
@item 2-D and 3-D: @var{options} = @code{@{"Qt", "Qbb", "Qc"@}}

@item 4-D and higher: @var{options} = @code{@{"Qt", "Qbb", "Qc", "Qx"@}}
@end itemize

If Qhull fails for 2-D input the triangulation is attempted again with
the options @code{@{"Qt", "Qbb", "Qc", "Qz"@}} which may result in
reduced accuracy.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@xseealso{@ref{XREFdelaunay,,delaunay}, @ref{XREFconvhulln,,convhulln}, @ref{XREFvoronoin,,voronoin}, @ref{XREFtrimesh,,trimesh}, @ref{XREFtetramesh,,tetramesh}}
@end deftypefn


An example of a Delaunay triangulation of a set of points is

@example
@group
rand ("state", 1);
x = rand (1, 10);
y = rand (1, 10);
T = delaunay (x, y);
X = [ x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1)) ];
Y = [ y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1)) ];
axis ([0, 1, 0, 1]);
plot (X, Y, "b", x, y, "r*");
@end group
@end example

@ifnotinfo
@noindent
The result of which can be seen in @ref{fig:delaunay}.

@float Figure,fig:delaunay
@center @image{delaunay,4in}
@caption{Delaunay triangulation of a random set of points}
@end float
@end ifnotinfo

@menu
* Plotting the Triangulation::
* Identifying Points in Triangulation::
@end menu

@node Plotting the Triangulation
@subsection Plotting the Triangulation

Octave has the functions @code{triplot}, @code{trimesh}, and @code{trisurf}
to plot the Delaunay triangulation of a 2-dimensional set of points.
@code{tetramesh} will plot the triangulation of a 3-dimensional set of points.

@c triplot scripts/plot/draw/triplot.m
@anchor{XREFtriplot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} triplot (@var{tri}, @var{x}, @var{y})
@deftypefnx {} {} triplot (@var{tri}, @var{x}, @var{y}, @var{linespec})
@deftypefnx {} {@var{h} =} triplot (@dots{})
Plot a 2-D triangular mesh.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.

The linestyle to use for the plot can be defined with the argument
@var{linespec} of the same format as the @code{plot} command.

The optional return value @var{h} is a graphics handle to the created
patch object.
@xseealso{@ref{XREFplot,,plot}, @ref{XREFtrimesh,,trimesh}, @ref{XREFtrisurf,,trisurf}, @ref{XREFdelaunay,,delaunay}}
@end deftypefn


@c trimesh scripts/plot/draw/trimesh.m
@anchor{XREFtrimesh}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {} {} trimesh (@var{tri}, @var{x}, @var{y})
@deftypefnx {} {} trimesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} trimesh (@dots{})
Plot a 3-D triangular wireframe mesh.

In contrast to @code{mesh}, which plots a mesh using rectangles,
@code{trimesh} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If no @var{z} input is given then
the triangles are plotted as a 2-D figure.

The color of the trimesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{clim} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying @var{c}, which is a vector for colormap data, or a matrix with
three columns for RGB data.  The number of colors specified in @var{c} must
either equal the number of vertices in @var{z} or the number of triangles
in @var{tri}.

Any property/value pairs are passed directly to the underlying patch object.
The full list of properties is documented at @ref{Patch Properties}.

The optional return value @var{h} is a graphics handle to the created patch
object.
@xseealso{@ref{XREFmesh,,mesh}, @ref{XREFtetramesh,,tetramesh}, @ref{XREFtriplot,,triplot}, @ref{XREFtrisurf,,trisurf}, @ref{XREFdelaunay,,delaunay}, @ref{XREFpatch,,patch}, @ref{XREFhidden,,hidden}}
@end deftypefn


@c trisurf scripts/plot/draw/trisurf.m
@anchor{XREFtrisurf}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {} {} trisurf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} trisurf (@dots{})
Plot a 3-D triangular surface.

In contrast to @code{surf}, which plots a surface mesh using rectangles,
@code{trisurf} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the vertices of
the triangles in the x-y plane.  @var{z} determines the height above the
plane of each vertex.

The color of the trisurf is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{clim} and/or change
the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying @var{c}, which is a vector for colormap data, or a matrix with
three columns for RGB data.  The number of colors specified in @var{c} must
either equal the number of vertices in @var{z} or the number of triangles
in @var{tri}.  When specifying the color at each vertex the triangle will
be colored according to the color of the first vertex only (see patch
documentation and the @qcode{"FaceColor"} property when set to
@qcode{"flat"}).

Any property/value pairs are passed directly to the underlying patch object.
 The full list of properties is documented at @ref{Patch Properties}.

The optional return value @var{h} is a graphics handle to the created patch
object.
@xseealso{@ref{XREFsurf,,surf}, @ref{XREFtriplot,,triplot}, @ref{XREFtrimesh,,trimesh}, @ref{XREFdelaunay,,delaunay}, @ref{XREFpatch,,patch}, @ref{XREFshading,,shading}}
@end deftypefn


@c tetramesh scripts/plot/draw/tetramesh.m
@anchor{XREFtetramesh}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} tetramesh (@var{T}, @var{X})
@deftypefnx {} {} tetramesh (@var{T}, @var{X}, @var{C})
@deftypefnx {} {} tetramesh (@dots{}, @var{property}, @var{val}, @dots{})
@deftypefnx {} {@var{h} =} tetramesh (@dots{})
Display the tetrahedrons defined in the m-by-4 matrix @var{T} as 3-D
patches.

@var{T} is typically the output of a Delaunay triangulation of a 3-D set
of points.  Every row of @var{T} contains four indices into the n-by-3
matrix @var{X} of the vertices of a tetrahedron.  Every row in @var{X}
represents one point in 3-D space.

The vector @var{C} specifies the color of each tetrahedron as an index
into the current colormap.  The default value is 1:m where m is the number
of tetrahedrons; the indices are scaled to map to the full range of the
colormap.  If there are more tetrahedrons than colors in the colormap then
the values in @var{C} are cyclically repeated.

Calling @code{tetramesh (@dots{}, "property", "value", @dots{})} passes all
property/value pairs directly to the patch function as additional arguments.
The full list of properties is documented at @ref{Patch Properties}.

The optional return value @var{h} is a vector of patch handles where each
handle represents one tetrahedron in the order given by @var{T}.
A typical use case for @var{h} is to turn the respective patch
@qcode{"visible"} property @qcode{"on"} or @qcode{"off"}.

Type @code{demo tetramesh} to see examples on using @code{tetramesh}.
@xseealso{@ref{XREFtrimesh,,trimesh}, @ref{XREFdelaunay,,delaunay}, @ref{XREFdelaunayn,,delaunayn}, @ref{XREFpatch,,patch}}
@end deftypefn


The difference between @code{triplot}, and @code{trimesh} or @code{trisurf},
is that the former only plots the 2-dimensional triangulation itself, whereas
the second two plot the value of a function @code{f (@var{x}, @var{y})}.  An
example of the use of the @code{triplot} function is

@example
@group
rand ("state", 2)
x = rand (20, 1);
y = rand (20, 1);
tri = delaunay (x, y);
triplot (tri, x, y);
@end group
@end example

@noindent
which plots the Delaunay triangulation of a set of random points in
2-dimensions.
@ifnotinfo
The output of the above can be seen in @ref{fig:triplot}.

@float Figure,fig:triplot
@center @image{triplot,4in}
@caption{Delaunay triangulation of a random set of points}
@end float
@end ifnotinfo

@node Identifying Points in Triangulation
@subsection Identifying Points in Triangulation

It is often necessary to identify whether a particular point in the
N-dimensional space is within the Delaunay tessellation of a set of
points in this N-dimensional space, and if so which N-simplex contains
the point and which point in the tessellation is closest to the desired
point.  The function @code{tsearch} performs this function in a triangulation,
and the functions @code{tsearchn} and @code{dsearchn} in an N-dimensional
tessellation.

To identify whether a particular point represented by a vector @var{p}
falls within one of the simplices of an N-simplex, we can write the
Cartesian coordinates of the point in a parametric form with respect to
the N-simplex.  This parametric form is called the Barycentric
Coordinates of the point.  If the points defining the N-simplex are given
by @var{N} + 1 vectors @code{@var{t}(@var{i},:)}, then the Barycentric
coordinates defining the point @var{p} are given by

@example
@var{p} = @var{beta} * @var{t}
@end example

@noindent
where @var{beta} contains @var{N} + 1 values that together as a vector
represent the Barycentric coordinates of the point @var{p}.  To ensure a unique
solution for the values of @var{beta} an additional criteria of

@example
sum (@var{beta}) == 1
@end example

@noindent
is imposed, and we can therefore write the above as

@example
@group
@var{p} - @var{t}(end, :) = @var{beta}(1:end-1) * (@var{t}(1:end-1, :)
                - ones (@var{N}, 1) * @var{t}(end, :)
@end group
@end example

@noindent
Solving for @var{beta} we can then write

@example
@group
@var{beta}(1:end-1) = (@var{p} - @var{t}(end, :)) /
                (@var{t}(1:end-1, :) - ones (@var{N}, 1) * @var{t}(end, :))
@var{beta}(end) = sum (@var{beta}(1:end-1))
@end group
@end example

@noindent
which gives the formula for the conversion of the Cartesian coordinates
of the point @var{p} to the Barycentric coordinates @var{beta}.  An
important property of the Barycentric coordinates is that for all points
in the N-simplex

@example
0 <= @var{beta}(@var{i}) <= 1
@end example

@noindent
Therefore, the test in @code{tsearch} and @code{tsearchn} essentially
only needs to express each point in terms of the Barycentric coordinates
of each of the simplices of the N-simplex and test the values of
@var{beta}.  This is exactly the implementation used in
@code{tsearchn}.  @code{tsearch} is optimized for 2-dimensions and the
Barycentric coordinates are not explicitly formed.

@c tsearch libinterp/corefcn/tsearch.cc
@anchor{XREFtsearch}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{idx} =} tsearch (@var{x}, @var{y}, @var{t}, @var{xi}, @var{yi})
Search for the enclosing Delaunay convex hull.

For @code{@var{t} = delaunay (@var{x}, @var{y})}, finds the index in @var{t}
containing the points @code{(@var{xi}, @var{yi})}.  For points outside the
convex hull, @var{idx} is NaN.

Programming Note: The algorithm is @qcode{O}(@var{M}*@var{N}) for locating
@var{M} points in @var{N} triangles.  Performance is typically much faster if
the points to be located are in a single continuous path; a point is first
checked against the region its predecessor was found in, speeding up lookups
for points along a continuous path.

@xseealso{@ref{XREFdelaunay,,delaunay}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


@c tsearchn scripts/geometry/tsearchn.m
@anchor{XREFtsearchn}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{idx} =} tsearchn (@var{x}, @var{t}, @var{xi})
@deftypefnx {} {[@var{idx}, @var{p}] =} tsearchn (@var{x}, @var{t}, @var{xi})
Find the simplexes enclosing the given points.

@code{tsearchn} is typically used with @code{delaunayn}:
@code{@var{t} = delaunayn (@var{x})} returns a set of simplexes @code{t},
then @code{tsearchn} returns the row index of @var{t} containing each point
of @var{xi}.  For points outside the convex hull, @var{idx} is NaN.

If requested, @code{tsearchn} also returns the barycentric coordinates
@var{p} of the enclosing simplexes.

@xseealso{@ref{XREFtsearch,,tsearch}, @ref{XREFdsearchn,,dsearchn}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


An example of the use of @code{tsearch} can be seen with the simple
triangulation

@example
@group
@var{x} = [-1; -1; 1; 1];
@var{y} = [-1; 1; -1; 1];
@var{tri} = [1, 2, 3; 2, 3, 4];
@end group
@end example

@noindent
consisting of two triangles defined by @var{tri}.  We can then identify
which triangle a point falls in like

@example
@group
tsearch (@var{x}, @var{y}, @var{tri}, -0.5, -0.5)
@result{} 1
tsearch (@var{x}, @var{y}, @var{tri}, 0.5, 0.5)
@result{} 2
@end group
@end example

@noindent
and we can confirm that a point doesn't lie within one of the triangles like

@example
@group
tsearch (@var{x}, @var{y}, @var{tri}, 2, 2)
@result{} NaN
@end group
@end example

The @code{dsearchn} function finds the closest point in a tessellation to the
desired point.  The desired point does not necessarily have to be in the
tessellation, and even if it the returned point of the tessellation does not
have to be one of the vertices of the N-simplex within which the desired point
is found.

@c dsearchn scripts/geometry/dsearchn.m
@anchor{XREFdsearchn}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi})
@deftypefnx {} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi}, @var{outval})
@deftypefnx {} {@var{idx} =} dsearchn (@var{x}, @var{xi})
@deftypefnx {} {[@var{idx}, @var{d}] =} dsearchn (@dots{})
Return the index @var{idx} of the closest point in @var{x} to the elements
@var{xi}.

If @var{outval} is supplied, then the values of @var{xi} that are not
contained within one of the simplices @var{tri} are set to @var{outval}.
Generally, @var{tri} is returned from @code{delaunayn (@var{x})}.

The optional output @var{d} contains a column vector of distances between
the query points @var{xi} and the nearest simplex points @var{x}.

Compatibility note: The @code{dsearchn} algorithm only uses the input
@var{tri} when @var{outdim} is specified to determine if any points lie
outside of the triangulation region.  For compatibility, @var{tri} is
accepted as an input even when @var{outdim} is not specified, but it is not
used or checked to be a valid triangulation, and providing it will not
affect either the output @var{idx} or the calculation efficiency.

@xseealso{@ref{XREFtsearchn,,tsearchn}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


An example of the use of @code{dsearchn}, using the above values of @var{x},
@var{y} and @var{tri} is

@example
@group
dsearchn ([@var{x}, @var{y}], @var{tri}, [-2, -2])
@result{} 1
@end group
@end example

If you wish the points that are outside the tessellation to be flagged,
then @code{dsearchn} can be used as

@example
@group
dsearchn ([@var{x}, @var{y}], @var{tri}, [-2, -2], NaN)
@result{} NaN
dsearchn ([@var{x}, @var{y}], @var{tri}, [-0.5, -0.5], NaN)
@result{} 1
@end group
@end example

@noindent
where the point outside the tessellation are then flagged with @code{NaN}.

@node Voronoi Diagrams
@section Voronoi Diagrams

A Voronoi diagram or Voronoi tessellation of a set of points @var{s} in
an N-dimensional space, is the tessellation of the N-dimensional space
such that all points in @code{@var{v}(@var{p})}, a partitions of the
tessellation where @var{p} is a member of @var{s}, are closer to @var{p}
than any other point in @var{s}.  The Voronoi diagram is related to the
Delaunay triangulation of a set of points, in that the vertices of the
Voronoi tessellation are the centers of the circum-circles of the
simplices of the Delaunay tessellation.

@c voronoi scripts/geometry/voronoi.m
@anchor{XREFvoronoi}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} voronoi (@var{x}, @var{y})
@deftypefnx {} {} voronoi (@var{x}, @var{y}, @var{options})
@deftypefnx {} {} voronoi (@dots{}, "linespec")
@deftypefnx {} {} voronoi (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} voronoi (@dots{})
@deftypefnx {} {[@var{vx}, @var{vy}] =} voronoi (@dots{})
Plot the Voronoi diagram of points @code{(@var{x}, @var{y})}.

The Voronoi facets with points at infinity are not drawn.

The @var{options} argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.

If @qcode{"linespec"} is given it is used to set the color and line style of
the plot.

If an axes graphics handle @var{hax} is supplied then the Voronoi diagram is
drawn on the specified axes rather than in a new figure.

If a single output argument is requested then the Voronoi diagram will be
plotted and a graphics handle @var{h} to the plot is returned.

[@var{vx}, @var{vy}] = voronoi (@dots{}) returns the Voronoi vertices
instead of plotting the diagram.

@example
@group
x = rand (10, 1);
y = rand (size (x));
h = convhull (x, y);
[vx, vy] = voronoi (x, y);
plot (vx, vy, "-b", x, y, "o", x(h), y(h), "-g");
legend ("", "points", "hull");
@end group
@end example

@xseealso{@ref{XREFvoronoin,,voronoin}, @ref{XREFdelaunay,,delaunay}, @ref{XREFconvhull,,convhull}}
@end deftypefn


@c voronoin scripts/geometry/voronoin.m
@anchor{XREFvoronoin}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{C}, @var{F}] =} voronoin (@var{pts})
@deftypefnx {} {[@var{C}, @var{F}] =} voronoin (@var{pts}, @var{options})
Compute N-dimensional Voronoi facets.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.

@var{C} contains the points of the Voronoi facets.  The list @var{F}
contains, for each facet, the indices of the Voronoi points.

An optional second argument, which must be a string or cell array of
strings, contains options passed to the underlying qhull command.  See the
documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.

The default options depend on the dimension of the input:

@itemize
@item 2-D and 3-D: @var{options} = @code{@{"Qbb"@}}

@item 4-D and higher: @var{options} = @code{@{"Qbb", "Qx"@}}
@end itemize

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@xseealso{@ref{XREFvoronoi,,voronoi}, @ref{XREFconvhulln,,convhulln}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


An example of the use of @code{voronoi} is

@example
@group
rand ("state",9);
x = rand (10,1);
y = rand (10,1);
tri = delaunay (x, y);
[vx, vy] = voronoi (x, y, tri);
triplot (tri, x, y, "b");
hold on;
plot (vx, vy, "r");
@end group
@end example

@ifnotinfo
@noindent
The result of which can be seen in @ref{fig:voronoi}.  Note that the
circum-circle of one of the triangles has been added to this figure, to
make the relationship between the Delaunay tessellation and the Voronoi
diagram clearer.

@float Figure,fig:voronoi
@center @image{voronoi,4in}
@caption{Delaunay triangulation (blue lines) and Voronoi diagram (red lines)
of a random set of points}
@end float
@end ifnotinfo

Additional information about the size of the facets of a Voronoi
diagram, and which points of a set of points is in a polygon can be had
with the @code{polyarea} and @code{inpolygon} functions respectively.

@c polyarea scripts/general/polyarea.m
@anchor{XREFpolyarea}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{a} =} polyarea (@var{x}, @var{y})
@deftypefnx {} {@var{a} =} polyarea (@var{x}, @var{y}, @var{dim})

Determine area of a polygon by triangle method.

The variables @var{x} and @var{y} define the vertex pairs, and must
therefore have the same shape.  They can be either vectors or arrays.  If
they are arrays then the columns of @var{x} and @var{y} are treated
separately and an area returned for each.

If the optional @var{dim} argument is given, then @code{polyarea} works
along this dimension of the arrays @var{x} and @var{y}.

@end deftypefn


An example of the use of @code{polyarea} might be

@example
@group
rand ("state", 2);
x = rand (10, 1);
y = rand (10, 1);
[c, f] = voronoin ([x, y]);
af = zeros (size (f));
for i = 1 : length (f)
  af(i) = polyarea (c (f @{i, :@}, 1), c (f @{i, :@}, 2));
endfor
@end group
@end example

Facets of the Voronoi diagram with a vertex at infinity have infinity
area.  A simplified version of @code{polyarea} for rectangles is
available with @code{rectint}

@c rectint scripts/geometry/rectint.m
@anchor{XREFrectint}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{area} =} rectint (@var{a}, @var{b})
Compute area or volume of intersection of rectangles or N-D boxes.

Compute the area of intersection of rectangles in @var{a} and rectangles in
@var{b}.  N-dimensional boxes are supported in which case the volume, or
hypervolume is computed according to the number of dimensions.

2-dimensional rectangles are defined as @code{[xpos ypos width height]}
where xpos and ypos are the position of the bottom left corner.  Higher
dimensions are supported where the coordinates for the minimum value of each
dimension follow the length of the box in that dimension, e.g.,
@code{[xpos ypos zpos kpos @dots{} width height depth k_length @dots{}]}.

Each row of @var{a} and @var{b} define a rectangle, and if both define
multiple rectangles, then the output, @var{area}, is a matrix where the i-th
row corresponds to the i-th row of a and the j-th column corresponds to the
j-th row of b.

@xseealso{@ref{XREFpolyarea,,polyarea}}
@end deftypefn


@c inpolygon scripts/geometry/inpolygon.m
@anchor{XREFinpolygon}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{in} =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})
@deftypefnx {} {[@var{in}, @var{on}] =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})

For a polygon defined by vertex points @code{(@var{xv}, @var{yv})}, return
true if the points @code{(@var{x}, @var{y})} are inside (or on the boundary)
of the polygon; Otherwise, return false.

The input variables @var{x} and @var{y}, must have the same dimension.

The optional output @var{on} returns true if the points are exactly on the
polygon edge, and false otherwise.
@xseealso{@ref{XREFdelaunay,,delaunay}}
@end deftypefn


An example of the use of @code{inpolygon} might be

@example
@group
randn ("state", 2);
x = randn (100, 1);
y = randn (100, 1);
vx = cos (pi * [-1 : 0.1: 1]);
vy = sin (pi * [-1 : 0.1 : 1]);
in = inpolygon (x, y, vx, vy);
plot (vx, vy, x(in), y(in), "r+", x(!in), y(!in), "bo");
axis ([-2, 2, -2, 2]);
@end group
@end example

@ifnotinfo
@noindent
The result of which can be seen in @ref{fig:inpolygon}.

@float Figure,fig:inpolygon
@center @image{inpolygon,4in}
@caption{Demonstration of the @code{inpolygon} function to determine the
points inside a polygon}
@end float
@end ifnotinfo

@node Convex Hull
@section Convex Hull

The convex hull of a set of points is the minimum convex envelope
containing all of the points.  Octave has the functions @code{convhull}
and @code{convhulln} to calculate the convex hull of 2-dimensional and
N-dimensional sets of points.

@c convhull scripts/geometry/convhull.m
@anchor{XREFconvhull}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{H} =} convhull (@var{x}, @var{y})
@deftypefnx {} {@var{H} =} convhull (@var{x}, @var{y}, @var{z})
@deftypefnx {} {@var{H} =} convhull (@var{x})
@deftypefnx {} {@var{H} =} convhull (@dots{}, @var{options})
@deftypefnx {} {[@var{H}, @var{V}] =} convhull (@dots{})
Compute the convex hull of a 2-D or 3-D set of points.

The hull @var{H} is a linear index vector into the original set of points
that specifies which points form the enclosing hull.  For 2-D inputs only,
the output is ordered in a counterclockwise manner around the hull.

The input @var{x} may also be a matrix with two or three columns where the
first column contains x-data, the second y-data, and the optional third
column contains z-data.

An optional final argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default option is @code{@{"Qt"@}}.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

If the second output @var{V} is requested the volume of the enclosing
convex hull is calculated.

@xseealso{@ref{XREFconvhulln,,convhulln}, @ref{XREFdelaunay,,delaunay}, @ref{XREFvoronoi,,voronoi}}
@end deftypefn


@c convhulln libinterp/dldfcn/convhulln.cc
@anchor{XREFconvhulln}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} convhulln (@var{pts})
@deftypefnx {} {@var{h} =} convhulln (@var{pts}, @var{options})
@deftypefnx {} {[@var{h}, @var{v}] =} convhulln (@dots{})
Compute the convex hull of the set of points @var{pts}.

@var{pts} is a matrix of size [n, dim] containing n points in a space of
dimension dim.

The hull @var{h} is an index vector into the set of points and specifies
which points form the enclosing hull.

An optional second argument, which must be a string or cell array of
strings, contains options passed to the underlying qhull command.  See the
documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options depend on the dimension of the input:

@itemize
@item 2D, 3D, 4D: @var{options} = @code{@{"Qt"@}}

@item 5D and higher: @var{options} = @code{@{"Qt", "Qx"@}}
@end itemize

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

If the second output @var{v} is requested the volume of the enclosing
convex hull is calculated.
@xseealso{@ref{XREFconvhull,,convhull}, @ref{XREFdelaunayn,,delaunayn}, @ref{XREFvoronoin,,voronoin}}
@end deftypefn


An example of the use of @code{convhull} is

@example
@group
x = -3:0.05:3;
y = abs (sin (x));
k = convhull (x, y);
plot (x(k), y(k), "r-", x, y, "b+");
axis ([-3.05, 3.05, -0.05, 1.05]);
@end group
@end example

@ifnotinfo
@noindent
The output of the above can be seen in @ref{fig:convhull}.

@float Figure,fig:convhull
@center @image{convhull,4in}
@caption{The convex hull of a simple set of points}
@end float
@end ifnotinfo

@node Interpolation on Scattered Data
@section Interpolation on Scattered Data

An important use of the Delaunay tessellation is that it can be used to
interpolate from scattered data to an arbitrary set of points.  To do
this the N-simplex of the known set of points is calculated with
@code{delaunay} or @code{delaunayn}.  Then the simplices in to which the
desired points are found are identified.  Finally the vertices of the simplices
are used to interpolate to the desired points.  The functions that perform this
interpolation are @code{griddata}, @code{griddata3} and @code{griddatan}.

@c griddata scripts/geometry/griddata.m
@anchor{XREFgriddata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})
@deftypefnx {} {[@var{xi}, @var{yi}, @var{zi}] =} griddata (@dots{})
@deftypefnx {} {@var{vi} =} griddata (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {@var{vi} =} griddata (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method})
@deftypefnx {} {@var{vi} =} griddata (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method}, @var{options})

Interpolate irregular 2-D and 3-D source data at specified points.

For 2-D interpolation, the inputs @var{x} and @var{y} define the points
where the function @code{@var{z} = f (@var{x}, @var{y})} is evaluated.
The inputs @var{x}, @var{y}, @var{z} are either vectors of the same length,
or the unequal vectors @var{x}, @var{y} are expanded to a 2-D grid with
@code{meshgrid} and @var{z} is a 2-D matrix matching the resulting size of
the X-Y grid.

The interpolation points are (@var{xi}, @var{yi}).  If either @var{xi} or
@var{y} is a row vector and the other is a column vector, then
@code{meshgrid (@var{xi}, @var{yi})} will be used to create a mesh of
interpolation points.

For 3-D interpolation, the inputs @var{x}, @var{y}, and @var{z} define the
points where the function @code{@var{v} = f (@var{x}, @var{y}, @var{z})}
is evaluated.  The inputs @var{x}, @var{y}, @var{z} are either vectors of
the same length, or if they are of unequal length, then they are expanded to
a 3-D grid with @code{meshgrid}.  The size of the input @var{v} must match
the size of the original data, either as a vector or a matrix.

The outputs @var{zi} (for 2-D) or @var{vi} (for 3-D) will contain the
interpolated values of @var{z} or @var{v}, respectively, with the output
size matching that of the interpolation points.

The optional input interpolation @var{method} can be @qcode{"nearest"},
@qcode{"linear"}, or for 2-D data @qcode{"v4"}.  When the method is
@qcode{"nearest"}, the output @var{vi} will be the closest point in the
original data (@var{x}, @var{y}, @var{z}) to the query point (@var{xi},
@var{yi}, @var{zi}).  When the method is @qcode{"linear"}, the output
@var{vi} will be a linear interpolation between the two closest points in
the original source data in each dimension.  For 2-D cases only, the
@qcode{"v4"} method is also available which implements a biharmonic spline
interpolation.  If @var{method} is omitted or empty, it defaults to
@qcode{"linear"}.

For 3-D interpolation, the optional argument @var{options} is passed
directly to Qhull when computing the Delaunay triangulation used for
interpolation.  For more information on the defaults and how to pass
different values, @pxref{XREFdelaunayn,,@code{delaunayn}}.

Programming Notes: If the input is complex the real and imaginary parts
are interpolated separately.  Interpolation is normally based on a
Delaunay triangulation.  Any query values outside the convex hull of the
input points will return @code{NaN}.  However, the @qcode{"v4"} method does
not use the triangulation and will return values outside the original data
(extrapolation).
@xseealso{@ref{XREFgriddata3,,griddata3}, @ref{XREFgriddatan,,griddatan}, @ref{XREFdelaunay,,delaunay}}
@end deftypefn


@c griddata3 scripts/geometry/griddata3.m
@anchor{XREFgriddata3}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method})
@deftypefnx {} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method}, @var{options})

Interpolate irregular 3-D source data at specified points.

The inputs @var{x}, @var{y}, and @var{z} define the points where the
function @code{@var{v} = f (@var{x}, @var{y}, @var{z})} is evaluated.  The
inputs @var{x}, @var{y}, @var{z} are either vectors of the same length, or
if they are of unequal length, then they are expanded to a 3-D grid with
@code{meshgrid}.  The size of the input @var{v} must match the size of the
original data, either as a vector or a matrix.

The interpolation points are specified by @var{xi}, @var{yi}, @var{zi}.

The optional input interpolation @var{method} can be @qcode{"nearest"} or
@qcode{"linear"}.  When the method is @qcode{"nearest"}, the output @var{vi}
will be the closest point in the original data (@var{x}, @var{y}, @var{z})
to the query point (@var{xi}, @var{yi}, @var{zi}).  When the method is
@qcode{"linear"}, the output @var{vi} will be a linear interpolation between
the two closest points in the original source data in each dimension.
If @var{method} is omitted or empty, it defaults to @qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.

Programming Notes: If the input is complex the real and imaginary parts
are interpolated separately.  Interpolation is based on a Delaunay
triangulation and any query values outside the convex hull of the input
points will return @code{NaN}.
@xseealso{@ref{XREFgriddata,,griddata}, @ref{XREFgriddatan,,griddatan}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


@c griddatan scripts/geometry/griddatan.m
@anchor{XREFgriddatan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi})
@deftypefnx {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method})
@deftypefnx {} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method}, @var{options})

Interpolate irregular source data @var{x}, @var{y} at points specified by
@var{xi}.

The input @var{x} is an MxN matrix representing M points in an N-dimensional
space.  The input @var{y} is a single-valued column vector (Mx1)
representing a function evaluated at the points @var{x}, i.e.,
@code{@var{y} = fcn (@var{x})}.  The input @var{xi} is a list of points
for which the function output @var{yi} should be approximated through
interpolation.  @var{xi} must have the same number of columns (@var{N})
as @var{x} so that the dimensionality matches.

The optional input interpolation @var{method} can be @qcode{"nearest"} or
@qcode{"linear"}.  When the method is @qcode{"nearest"}, the output @var{yi}
will be the closest point in the original data @var{x} to the query point
@var{xi}.  When the method is @qcode{"linear"}, the output @var{yi} will
be a linear interpolation between the two closest points in the original
source data.  If @var{method} is omitted or empty, it defaults to
@qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.

Example

@example
@group
## Evaluate sombrero() function at irregular data points
x = 16*gallery ("uniformdata", [200,1], 1) - 8;
y = 16*gallery ("uniformdata", [200,1], 11) - 8;
z = sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2);
## Create a regular grid and interpolate data
[xi, yi] = ndgrid (linspace (-8, 8, 50));
zi = griddatan ([x, y], z, [xi(:), yi(:)]);
zi = reshape (zi, size (xi));
## Plot results
clf ();
plot3 (x, y, z, "or");
hold on
surf (xi, yi, zi);
legend ("Original Data", "Interpolated Data");
@end group
@end example

Programming Notes: If the input is complex the real and imaginary parts
are interpolated separately.  Interpolation is based on a Delaunay
triangulation and any query values outside the convex hull of the input
points will return @code{NaN}.  For 2-D and 3-D data additional
interpolation methods are available by using the @code{griddata} function.
@xseealso{@ref{XREFgriddata,,griddata}, @ref{XREFgriddata3,,griddata3}, @ref{XREFdelaunayn,,delaunayn}}
@end deftypefn


An example of the use of the @code{griddata} function is

@example
@group
rand ("state", 1);
x = 2*rand (1000,1) - 1;
y = 2*rand (size (x)) - 1;
z = sin (2*(x.^2+y.^2));
[xx,yy] = meshgrid (linspace (-1,1,32));
zz = griddata (x, y, z, xx, yy);
mesh (xx, yy, zz);
@end group
@end example

@noindent
that interpolates from a random scattering of points, to a uniform grid.
@ifnotinfo
The output of the above can be seen in @ref{fig:griddata}.

@float Figure,fig:griddata
@center @image{griddata,4in}
@caption{Interpolation from a scattered data to a regular grid}
@end float
@end ifnotinfo

@node Vector Rotation Matrices
@section Vector Rotation Matrices

Also included in Octave's geometry functions are primitive functions to enable
vector rotations in 3-dimensional space.  Separate functions are provided for
rotation about each of the principle axes, @var{x}, @var{y}, and @var{z}.
According to Euler's rotation theorem, any arbitrary rotation, @var{R}, of any
vector, @var{p}, can be expressed as a product of the three principle
rotations:

@tex
$p' = R \cdot p = R_z \cdot R_y \cdot R_x \cdot p$
@end tex
@ifnottex

@example
p' = Rp = Rz*Ry*Rx*p
@end example
@end ifnottex

@c rotx scripts/geometry/rotx.m
@anchor{XREFrotx}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{T} =} rotx (@var{angle})

@code{rotx} returns the 3x3 transformation matrix corresponding to an active
rotation of a vector about the x-axis by the specified @var{angle}, given in
degrees, where a positive angle corresponds to a counterclockwise
rotation when viewing the y-z plane from the positive x side.

The form of the transformation matrix is:
@tex
$$
T = \left[\matrix{ 1 & 0 & 0 \cr
                   0 & \cos(angle) & -\sin(angle)\cr
                   0 & \sin(angle) & \cos(angle)}\right].
$$
@end tex
@ifnottex

@example
@group
     | 1      0           0      |
 T = | 0  cos(@var{angle}) -sin(@var{angle}) |
     | 0  sin(@var{angle})  cos(@var{angle}) |
@end group
@end example
@end ifnottex

This rotation matrix is intended to be used as a left-multiplying matrix
when acting on a column vector, using the notation
@code{@var{v} = @var{T}*@var{u}}.
For example, a vector, @var{u}, pointing along the positive y-axis, rotated
90-degrees about the x-axis, will result in a vector pointing along the
positive z-axis:

@example
@group
>> u = [0 1 0]'
u =
   0
   1
   0

>> T = rotx (90)
T =
   1.00000   0.00000   0.00000
   0.00000   0.00000  -1.00000
   0.00000   1.00000   0.00000

>> v = T*u
v =
   0.00000
   0.00000
   1.00000
@end group
@end example

@xseealso{@ref{XREFroty,,roty}, @ref{XREFrotz,,rotz}}
@end deftypefn


@c roty scripts/geometry/roty.m
@anchor{XREFroty}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{T} =} roty (@var{angle})

@code{roty} returns the 3x3 transformation matrix corresponding to an active
rotation of a vector about the y-axis by the specified @var{angle}, given in
degrees, where a positive angle corresponds to a counterclockwise
rotation when viewing the z-x plane from the positive y side.

The form of the transformation matrix is:
@tex
$$
T = \left[\matrix{ \cos(angle) & 0 & \sin(angle) \cr
                   0 & 1 & 0 \cr
                   -\sin(angle) & 0 & \cos(angle)}\right].
$$
@end tex
@ifnottex

@example
@group
     |  cos(@var{angle})  0  sin(@var{angle}) |
 T = |      0       1      0      |
     | -sin(@var{angle})  0  cos(@var{angle}) |
@end group
@end example
@end ifnottex

This rotation matrix is intended to be used as a left-multiplying matrix
when acting on a column vector, using the notation
@code{@var{v} = @var{T}*@var{u}}.
For example, a vector, @var{u}, pointing along the positive z-axis, rotated
90-degrees about the y-axis, will result in a vector pointing along the
positive x-axis:

@example
@group
  >> u = [0 0 1]'
   u =
      0
      0
      1

   >> T = roty (90)
   T =
      0.00000   0.00000   1.00000
      0.00000   1.00000   0.00000
     -1.00000   0.00000   0.00000

   >> v = T*u
   v =
      1.00000
      0.00000
      0.00000
@end group
@end example

@xseealso{@ref{XREFrotx,,rotx}, @ref{XREFrotz,,rotz}}
@end deftypefn


@c rotz scripts/geometry/rotz.m
@anchor{XREFrotz}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{T} =} rotz (@var{angle})

@code{rotz} returns the 3x3 transformation matrix corresponding to an active
rotation of a vector about the z-axis by the specified @var{angle}, given in
degrees, where a positive angle corresponds to a counterclockwise
rotation when viewing the x-y plane from the positive z side.

The form of the transformation matrix is:
@tex
$$
T = \left[\matrix{ \cos(angle) & -\sin(angle) & 0 \cr
                   \sin(angle) & \cos(angle) & 0 \cr
                   0 & 0 & 1}\right].
$$
@end tex
@ifnottex

@example
@group
     | cos(@var{angle}) -sin(@var{angle}) 0 |
 T = | sin(@var{angle})  cos(@var{angle}) 0 |
     |     0           0      1 |
@end group
@end example
@end ifnottex

This rotation matrix is intended to be used as a left-multiplying matrix
when acting on a column vector, using the notation
@code{@var{v} = @var{T}*@var{u}}.
For example, a vector, @var{u}, pointing along the positive x-axis, rotated
90-degrees about the z-axis, will result in a vector pointing along the
positive y-axis:

@example
@group
  >> u = [1 0 0]'
   u =
      1
      0
      0

   >> T = rotz (90)
   T =
      0.00000  -1.00000   0.00000
      1.00000   0.00000   0.00000
      0.00000   0.00000   1.00000

   >> v = T*u
   v =
      0.00000
      1.00000
      0.00000
@end group
@end example

@xseealso{@ref{XREFrotx,,rotx}, @ref{XREFroty,,roty}}
@end deftypefn