Update doco, add refs, examples, clarify.

Author: petercorke

PGraph.m

@@ -5,46 +5,73 @@
 %
 % Provides support for graphs that:
 %   - are directed
-%   - are embedded in a coordinate system
+%   - are embedded in a coordinate system (2D or 3D)
+%   - have multiple unconnected components
 %   - have symmetric cost edges (A to B is same cost as B to A)
 %   - have no loops (edges from A to A)
-%   - have vertices that are represented by integers VID
-%   - have edges that are represented by integers EID
+%
+% Graph representation:
+%   - vertices are represented by integer vertex ids (vid)
+%   - edges are represented by integer edge ids (eid)
+%   - each vertex can have arbitrary associated data
+%   - each edge can have arbitrary associated data
 %
 % Methods::
 %
 % Constructing the graph::
-%   g.add_node(coord)      add vertex, return vid
-%   g.add_edge(v1, v2)     add edge from v1 to v2, return eid
-%   g.setcost(e, c)        set cost for edge e
-%   g.setdata(v, u)        set user data for vertex v
-%   g.data(v)              get user data for vertex v
+%   g.add_node(coord)      add vertex
+%   g.add_edge(v1, v2)     add edge fbetween vertices
+%   g.setcost(e, c)        set cost for edge
+%   g.setedata(e, u)       set user data for edge
+%   g.setvdata(v, u)       set user data for vertex
+%
+% Modifying the graph::
 %   g.clear()              remove all vertices and edges from the graph
+%   g.delete_edge(e)       remove edge
+%   g.delete_node(v)       remove vertex
+%   g.setcoord(v)          set coordinate of vertex
 %
 % Information from graph::
-%   g.edges(v)             list of edges for vertex v
-%   g.cost(e)              cost of edge e
-%   g.neighbours(v)        neighbours of vertex v
-%   g.component(v)         component id for vertex v
-%   g.connectivity()       number of edges for all vertices
+%   g.about()                   summary information about node
+%   g.component(v)              component id for vertex
+%   g.componentnodes(c)         vertices in component
+%   g.connectivity()            number of edges for all vertices
+%   g.connectivity_in()         number of incoming edges for all vertices
+%   g.connectivity_out()        number of outgoing edges for all vertices
+%   g.coord(v)                  coordinate of vertex
+%   g.cost(e)                   cost of edge
+%   g.distance_metric(v1,v2)    distance between nodes
+%   g.edata(e)                  get edge user data
+%   g.edgedir(v1,v2)            direction of edge
+%   g.edges(v)                  list of edges for vertex
+%   g.edges_in(v)               list of edges into vertex
+%   g.edges_out(v)              list of edges from vertex
+%   g.lookup(name)              vertex from name
+%   g.name(v)                   name of vertex
+%   g.neighbours(v)             neighbours of vertex
+%   g.neighbours_d(v)           neighbours of vertex and edge directions
+%   g.neighbours_in(v)          neighbours with edges in
+%   g.neighbours_out(v)         neighbours with edges out
+%   g.samecomponent(v1,v2)      test if vertices in same component
+%   g.vdata(v)                  vertex user data
+%   g.vertices(e)               vertices for edge
 %
 % Display::
 %
-%   g.plot()                   set goal vertex for path planning
-%   g.highlight_node(v)        highlight vertex v
-%   g.highlight_edge(e)        highlight edge e
-%   g.highlight_component(c)   highlight all nodes in component c
-%   g.highlight_path(p)        highlight nodes and edge along path p
-%
-%   g.pick(coord)              vertex closest to coord
-%
 %   g.char()                   convert graph to string
 %   g.display()                display summary of graph
+%   g.highlight_node(v)        highlight vertex
+%   g.highlight_edge(e)        highlight edge
+%   g.highlight_component(c)   highlight all nodes in component
+%   g.highlight_path(p)        highlight nodes and edge along path
+%   g.pick(coord)              vertex closest to coord
+%   g.plot()                   plot graph
+%
 %
 % Matrix representations::
 %   g.adjacency()          adjacency matrix
-%   g.incidence()          incidence matrix
 %   g.degree()             degree matrix
+%   g.incidence()          incidence matrix
 %   g.laplacian()          Laplacian  matrix
 %
 % Planning paths through the graph::
@@ -53,17 +80,17 @@
 %   g.path(v)              list of vertices from v to goal
 %
 % Graph and world points::
+%   g.closest(coord)       vertex closest to coord
 %   g.coord(v)             coordinate of vertex v
 %   g.distance(v1, v2)     distance between v1 and v2
 %   g.distances(coord)     return sorted distances from coord to all vertices
-%   g.closest(coord)       vertex closest to coord
 %
 % Object properties (read only)::
 %   g.n            number of vertices
 %   g.ne           number of edges
 %   g.nc           number of components
 %
-% Examples::
+% Example::
 %         g = PGraph();
 %         g.add_node([1 2]');  % add node 1
 %         g.add_node([3 4]');  % add node 1
@@ -74,7 +101,8 @@
 %         g.plot()
 %
 % Notes::
-% - Support for edge direction is rudimentary.
+% - Support for edge direction is quite simple.
+% - The method distance_metric() could be redefined in a subclass.
 
 % Copyright (C) 1993-2019 Peter I. Corke
 %
@@ -462,7 +490,7 @@ function clear(g)
         function c = connectivity_in(g,n )
             %PGraph.connectivity Graph connectivity
             %
-            % C = G.connectivity() is a vector (Nx1) with the number of edges per
+            % C = G.connectivity() is a vector (Nx1) with the number of incoming edges per
             % vertex.
             %
             % The average vertex connectivity is
@@ -483,7 +511,7 @@ function clear(g)
         function c = connectivity_out(g,n )
             %PGraph.connectivity Graph connectivity
             %
-            % C = G.connectivity() is a vector (Nx1) with the number of edges per
+            % C = G.connectivity() is a vector (Nx1) with the number of outgoing edges per
             % vertex.
             %
             % The average vertex connectivity is
@@ -790,8 +818,7 @@ function colorComponent(g, v, l)
         function v = componentnodes(g, c)
             %PGraph.component Graph component
             %
-            % C = G.component(V) is the id of the graph component that contains vertex
-            % V.
+            % C = G.component(V) are the ids of all vertices in the graph component V.
             v = find(g.labels == c);
         end
 

SE3.m

@@ -220,8 +220,7 @@
                         % (T)
                         for i=1:length(a)
                             obj(i).data = a(i).data;
-                        end
-                        
+                        end                        
                     elseif numcols(a) == 3
                         % SE3( xyz )
                         for i=1:length(a)
@@ -359,9 +358,12 @@
         function T = increment(obj, v)
             %SE3.increment  Apply incremental motion to an SE3 pose
             %
-            % P1 = P.increment(d) is an SE3 pose object formed by applying the
-            % incremental motion vector d (1x6) in the frame associated with SE3 pose
-            % P.
+            % P1 = P.increment(D) is an SE3 pose object formed by compounding the 
+            % SE3 pose with the incremental motion described by D (6x1).
+            %
+            % The vector D=(dx, dy, dz, dRx, dRy, dRz) represents infinitessimal translation
+            % and rotation, and is an approximation to the instantaneous spatial velocity 
+            % multiplied by time step.
             %
             % See also SE3.todelta, DELTA2TR, TR2DELTA.
             T = obj .* SE3(delta2tr(v));
@@ -635,13 +637,17 @@ R            zeros(3,3)
         end
 
         function d = todelta(P1, P2)
-            %SE3.todelta Convert SE(3) object to differential motion vector
+            %SE3.todelta Convert SE3 object to differential motion vector
             %
-            % D = SE3.todelta(P0, P1) is the (6x1) differential motion vector (dx, dy,
-            % dz, dRx, dRy, dRz) corresponding to infinitessimal motion (in the P0
-            % frame) from SE(3) pose P0 to P1. .
+            % D = P0.todelta(P1) is the differential motion (6x1) corresponding to 
+            % infinitessimal motion (in the P0 frame) from SE3 pose P0 to P1.
             %
-            % D = SE3.todelta(P) as above but the motion is with respect to the world frame.
+            % The vector D=(dx, dy, dz, dRx, dRy, dRz) represents infinitessimal translation
+            % and rotation, and is an approximation to the instantaneous spatial velocity 
+            % multiplied by time step.
+            %
+            % D = P.todelta() as above but the motion is from the world frame to the SE3
+            % pose P.
             %
             % Notes::
             % - D is only an approximation to the motion, and assumes
@@ -890,12 +896,14 @@ R            zeros(3,3)
         end
 
         function obj = delta(d)
-            %SE3.delta SE3 object from differential motion vector
+            %SE3.delta Construct SE3 object from differential motion vector
             %
             % T = SE3.delta(D) is an SE3 pose object representing differential
-            % translation and rotation. The vector D=(dx, dy, dz, dRx, dRy, dRz)
-            % represents an infinitessimal motion, and is an approximation to the spatial
-            % velocity multiplied by time.
+            % motion D (6x1).
+            %
+            % The vector D=(dx, dy, dz, dRx, dRy, dRz) represents infinitessimal translation
+            % and rotation, and is an approximation to the instantaneous spatial velocity 
+            % multiplied by time step.
             %
             % See also SE3.todelta, SE3.increment, TR2DELTA.
 

angdiff.m

@@ -1,20 +1,23 @@
 %ANGDIFF Difference of two angles
 %
-% ANGDIFF(TH1, TH2) is the difference between angles TH1 and TH2
+% ANGDIFF(TH1, TH2) is the difference between angles TH1 and TH2, ie. TH1-TH2
 % on the circle.  The result is in the interval [-pi pi).  Either or both
 % arguments can be a vector:
 % - If TH1 is a vector, and TH2 a scalar then return a vector where TH2 is modulo 
 %   subtracted from the corresponding elements of TH1.
 % - If TH1 is a scalar, and TH2 a vector then return a vector where the
 %   corresponding elements of TH2 are modulo subtracted from TH1.
 % - If TH1 and TH2 are vectors then return a vector whose elements are the modulo 
-%   difference of the corresponding elements of TH1 and TH2.
+%   difference of the corresponding elements of TH1 and TH2, which must be the 
+%   same length.
 %
 % ANGDIFF(TH) as above but TH=[TH1 TH2].
 %
-% ANGDIFF(TH) is the equivalent angle to TH in the interval [-pi pi).
+% ANGDIFF(TH) is the equivalent angle to the scalar TH in the interval [-pi pi).
 %
 % Notes::
+% - The MathWorks Robotics Systems Toolbox defines a function with the same name
+%   which computes TH2-TH1 rather than TH1-TH2.
 % - If TH1 and TH2 are both vectors they should have the same
 %   orientation, which the output will assume.
 %

angvec2r.m

@@ -4,7 +4,8 @@
 % equivalent to a rotation of THETA about the vector V.
 %
 % Notes::
-% - If THETA == 0 then return identity matrix.
+% - Uses Rodrigues' formula
+% - If THETA == 0 then return identity matrix and ignore V.
 % - If THETA ~= 0 then V must have a finite length.
 %
 % See also angvec2tr, eul2r, rpy2r, tr2angvec, trexp, SO3.angvec.

angvec2tr.m

@@ -4,8 +4,9 @@
 % rotation of THETA about the vector V.
 %
 % Note::
+% - Uses Rodrigues' formula
 % - The translational part is zero.
-% - If THETA == 0 then return identity matrix.
+% - If THETA == 0 then return identity matrix and ignore V.
 % - If THETA ~= 0 then V must have a finite length.
 %
 % See also angvec2r, eul2tr, rpy2tr, angvec2r, tr2angvec, trexp, SO3.angvec.

chi2inv_rtb.m

@@ -1,6 +1,6 @@
 %CHI2INV_RTB Inverse chi-squared function
 %
-% X = CHI2INV_RTB(P, N) is the inverse chi-squared cdf function of N-degrees of freedom.
+% X = CHI2INV_RTB(P, N) is the inverse chi-squared CDF function of N-degrees of freedom.
 %
 % Notes::
 % - only works for N=2

circle.m

@@ -4,11 +4,11 @@
 % axes.
 %
 % X = CIRCLE(C, R, OPTIONS) is a matrix (2xN) whose columns define the 
-% coordinates [x,y] of points around the circumferance of a circle 
+% coordinates [x,y] of points around the circumference of a circle 
 % centred at C (1x2) and of radius R.
 %
-% C is normally 2x1 but if 3x1 then the circle is embedded in 3D, and X is Nx3,
-% but the circle is always in the xy-plane with a z-coordinate of C(3).
+% C is normally 2x1 but if 3x1 then the circle is embedded in 3D, and X is Nx3.
+% The circle is always in the xy-plane with a z-coordinate of C(3).
 %
 % Options::
 %  'n',N   Specify the number of points (default 50)

delta2tr.m

@@ -1,9 +1,14 @@
 %DELTA2TR Convert differential motion  to a homogeneous transform
 %
 % T = DELTA2TR(D) is a homogeneous transform (4x4) representing differential 
-% translation and rotation. The vector D=(dx, dy, dz, dRx, dRy, dRz)
-% represents an infinitessimal motion, and is an approximation to the spatial 
-% velocity multiplied by time.
+% motion D (6x1). 
+%
+% The vector D=(dx, dy, dz, dRx, dRy, dRz) represents infinitessimal translation
+% and rotation, and is an approximation to the instantaneous spatial velocity 
+% multiplied by time step.
+%
+% Reference::
+% - Robotics, Vision & Control: Second Edition, P. Corke, Springer 2016; p67.
 %
 % See also tr2delta, SE3.delta.
 

e2h.m

@@ -3,6 +3,9 @@
 % H = E2H(E) is the homogeneous version (K+1xN) of the Euclidean 
 % points E (KxN) where each column represents one point in R^K.
 %
+% Reference::
+% - Robotics, Vision & Control: Second Edition, P. Corke, Springer 2016; p604.
+%
 % See also H2E.
 
 % Copyright (C) 1993-2019 Peter I. Corke

eul2jac.m

@@ -1,14 +1,18 @@
 %EUL2JAC Euler angle rate Jacobian
 %
-% J = EUL2JAC(PHI, THETA, PSI) is a Jacobian matrix (3x3) that maps Euler angle rates to 
+% J = EUL2JAC(PHI, THETA, PSI) is a Jacobian matrix (3x3) that maps ZYZ Euler angle rates to 
 % angular velocity at the operating point specified by the Euler angles PHI, THETA, PSI.
 %
 % J = EUL2JAC(EUL)  as above but the Euler angles are passed as a vector EUL=[PHI, THETA, PSI]. 
 %
 % Notes::
 % - Used in the creation of an analytical Jacobian.
+% - Angles in radians, rates in radians/sec.
 %
-% See also rpy2jac, SerialLink.jacobe.
+% Reference::
+% - Robotics, Vision & Control: Second Edition, P. Corke, Springer 2016; p232-3.
+%
+% See also rpy2jac, eul2r, SerialLink.jacobe.
 
 % Copyright (C) 1993-2019 Peter I. Corke
 %

h2e.m

@@ -3,6 +3,9 @@
 % E = H2E(H) is the Euclidean version (K-1xN) of the homogeneous 
 % points H (KxN) where each column represents one point in P^K.
 %
+% Reference::
+% - Robotics, Vision & Control: Second Edition, P. Corke, Springer 2016; p604.
+%
 % See also E2H.
 
 % Copyright (C) 1993-2019 Peter I. Corke

homtrans.m

@@ -10,14 +10,18 @@
 %   - P is 3xN (3D points) they are considered Euclidean (R^3)
 %   - P is 4xN (3D points) they are considered projective (P^3)
 %
+% P2 and P have the same number of rows, ie. if Euclidean points are given
+% then Euclidean points are returned, if projective points are given then
+% projective points are returned.
+%
 % TP = HOMTRANS(T, T1) applies homogeneous transformation T to the 
 % homogeneous transformation T1, that is TP=T*T1.  If T1 is a 3-dimensional 
 % transformation then T is applied to each plane as defined by the first two 
-% dimensions, ie. if T = NxN and T1=NxNxM then the result is NxNxM.
+% dimensions, ie. if T is NxN and T1 is NxNxM then the result is NxNxM.
 %
 % Notes::
-% - T is a homogeneous transformation defining the pose of {B} with respect to {A}.
-% - The points are defined with respect to frame {B} and are transformed to be
+% - If T is a homogeneous transformation defining the pose of {B} with respect to {A},
+%   then the points are defined with respect to frame {B} and are transformed to be
 %   with respect to frame {A}.
 %
 % See also E2H, H2E, RTBPose.mtimes.

ishomog.m

@@ -3,10 +3,11 @@
 % ISHOMOG(T) is true (1) if the argument T is of dimension 4x4 or 4x4xN, else 
 % false (0).
 %
-% ISHOMOG(T, 'valid') as above, but also checks the validity of the rotation
+% ISHOMOG(T, 'check') as above, but also checks the validity of the rotation
 % sub-matrix.
 %
 % Notes::
+% - A valid rotation sub-matrix has determinant of 1.
 % - The first form is a fast, but incomplete, test for a transform is SE(3).
 %
 % See also ISROT, ISHOMOG2, ISVEC.

ishomog2.m

@@ -3,10 +3,11 @@
 % ISHOMOG2(T) is true (1) if the argument T is of dimension 3x3 or 3x3xN, else 
 % false (0).
 %
-% ISHOMOG2(T, 'valid') as above, but also checks the validity of the rotation
+% ISHOMOG2(T, 'check') as above, but also checks the validity of the rotation
 % sub-matrix.
 %
 % Notes::
+% - A valid rotation sub-matrix has determinant of 1.
 % - The first form is a fast, but incomplete, test for a transform in SE(3).
 %
 % See also ISHOMOG, ISROT2, ISVEC.