Modify README's and update docs

README.md

@@ -1,7 +1,13 @@
 # Modern Robotics:  Mechanics, Planning, and Control
 # Code Library
 
-This repository contains the code library accompanying _Modern Robotics:  Mechanics, Planning, and Control_. The functions are available in:
+This repository contains the code library accompanying [_Modern Robotics: 
+Mechanics, Planning, and Control_](http://modernrobotics.org) (Kevin Lynch 
+and Frank Park, Cambridge University Press 2017). The 
+[user manual](/doc/MRlib.pdf) is in the doc directory.
+
+The functions are available in:
+
 * Python
 * MATLAB
 * Mathematica

doc/MRlib.tex

@@ -74,7 +74,9 @@ July 6, 2018 \\
 
 This is the documentation for the code library accompanying \emph{Modern Robotics:  Mechanics, Planning, and Control}, by Kevin M. Lynch and Frank C. Park, Cambridge University Press, 2017, \url{http://modernrobotics.org}.  The code is written for MATLAB, Mathematica, and Python, and originates from students' solutions to programming assignments in courses using material from the book.  The current version of the code is largely the work of Huan Weng, based on contributions from Bill Hunt, Jarvis Schultz, Mikhail Todes, Matthew Collins, Mojtaba Mozaffar, Chang Liu, and Wentao Chen.  
 
-The code is commented and mostly self-explanatory in conjunction with the book.  An example use is provided with each function.  The primary purpose of the software is to be easy to read and educational, reinforcing the concepts in the book.  The code is optimized neither for efficiency nor robustness (it does not perform error-checking on its inputs).  This is to keep the code as simple and unintimidating as possible.  Users are encouraged to use and modify the code however they wish; the process of using and modifying the code certainly aids in understanding the concepts in the book.  Bug reports or documentation errors are appreciated via the issue tracker at \url{https://github.com/NxRLab/ModernRobotics}.
+The code is commented and mostly self-explanatory in conjunction with the book.  An example use is provided with each function.  The primary purpose of the software is to be easy to read and educational, reinforcing the concepts in the book.  The code is optimized neither for efficiency nor robustness (it does not perform error-checking on its inputs).  This is to keep the code as simple and unintimidating as possible.  Users are encouraged to use and modify the code however they wish; the process of using and modifying the code certainly aids in understanding the concepts in the book.
+
+Information on installing and using the library is available at the code website, \url{https://github.com/NxRLab/ModernRobotics}.  Your feedback on bugs or documentation errors are appreciated via the issue tracker at the same site.
 
 This document provides an overview of the available functions using MATLAB syntax.  Functions are organized according to the relevant chapter in the book.  Basic functions, such as functions to calculate the magnitude of a vector, normalize a vector, test if a value is near zero, and perform matrix operations such as multiplication and inverses, are not documented here.
 
@@ -193,22 +195,22 @@ $K_d$ & {\tt Kd} & A scalar feedback derivative gain.\\
 
 \begin{function}			%DistanceToSO3
 {d = DistanceToSO3(mat)}
-{\item \verb~mat~: A $3 \times 3$ matrix $mat$.}
+{\item \verb~mat~: A $3 \times 3$ matrix $M$.}
-{\item \verb~d~: A measure of the distance from $mat$ to $SO(3)$, the space of rotation matrices.  If ${\rm det}(mat)>0$ (the determinant of $mat$ should be $1$ if $mat \in SO(3)$), this distance is calculated as $\|mat^\trans mat -I\|_F$, where $\| \cdot \|_F$ is the Frobenius norm of a matrix, the square root of the sum of the squares of the absolute values of the elements of the matrix.  If the determinant is not positive, a large value is returned. }
+{\item \verb~d~: A measure of the distance from $M$ to $SO(3)$, the space of rotation matrices.  If ${\rm det}(M)>0$ (the determinant of $M$ should be $1$ if $M \in SO(3)$), this distance is calculated as $\|M^\trans M -I\|_F$, since $M^\trans M$ should be the identity matrix if $M\in SO(3)$.  The Frobenius norm $\| \cdot \|_F$ of a matrix is the square root of the sum of the squares of the absolute values of the elements of the matrix.  If the determinant is not positive, a large value is returned. }
 {}
 \end{function}
 
 \begin{function}			%TestIfSO3
 {judge = TestIfSO3(mat)}
-{\item \verb~mat~: A $3 \times 3$ matrix $mat$.}
+{\item \verb~mat~: A $3 \times 3$ matrix $M$.}
-{\item \verb~judge~:  $1$ (True) if $mat$ is a rotation matrix (an element of $SO(3)$) and $0$ (False) otherwise.  This function calls \verb~DistanceToSO3(mat)~ and tests if the returned distance is smaller than a small value (which you should feel free to change to suit your purposes).}
+{\item \verb~judge~:  $1$ (True) if $M$ is a rotation matrix (an element of $SO(3)$) and $0$ (False) otherwise.  This function calls \verb~DistanceToSO3(mat)~ and tests if the returned distance is smaller than a small value (which you should feel free to change to suit your purposes).}
 {}
 \end{function}
 
 \begin{function}			%ProjectToSO3
 {R = ProjectToSO3(mat)}
-{\item \verb~mat~: A $3 \times 3$ matrix $mat$.}
+{\item \verb~mat~: A $3 \times 3$ matrix $M$.}
-{\item \verb~R~:  The closest rotation matrix (element of $SO(3)$) to $mat$.  This function is only appropriate for matrices $mat$ that are ``close'' to $SO(3)$.  For example, $mat$ could be the result of a long series of multiplications of rotation matrices, which has caused the result to drift slightly away from satisfying the conditions of $SO(3)$ (${\rm det}(mat) = 1, mat^\trans mat = I$) due to roundoff errors.}
+{\item \verb~R~:  The closest rotation matrix (element of $SO(3)$) to $M$.  This function is only appropriate for matrices $M$ that are ``close'' to $SO(3)$.  For example, $M$ could be the result of a long series of multiplications of rotation matrices, which has caused the result to drift slightly away from satisfying the conditions of $SO(3)$ (${\rm det}(M) = 1, M^\trans M = I$) due to roundoff errors.}
 {}
 \end{function}
 
@@ -297,22 +299,23 @@ $K_d$ & {\tt Kd} & A scalar feedback derivative gain.\\
 
 \begin{function}			%DistanceToSE3
 {d = DistanceToSE3(mat)}
-{\item \verb~mat~: A $4 \times 4$ matrix $mat$.}
+{\item \verb~mat~: A $4 \times 4$ matrix $M$.}
-{\item \verb~d~: A measure of the distance from $mat$ to $SE(3)$, the space of transformation matrices.  Let $matR$ be the top $3 \times 3$ submatrix of $mat$, i.e., the portion of $mat$ expected to represent a rotation matrix.  If ${\rm det}(matR)>0$ (the determinant of $matR$ should be $1$ if $matR \in SO(3)$), the distance is calculated as $\|mat^{\prime\trans} mat^\prime -I\|_F$, where $mat^\prime$ is equivalent to $mat$ except the elements in $mat^\prime$, which are $mat^\prime_{14}$, $mat^\prime_{24}$, and $mat^\prime_{34}$, are zero.  The Frobenius norm $\| \cdot \|_F$ of a matrix is the the square root of the sum of the squares of the absolute values of the elements of the matrix.  If the determinant of $matR$ is not positive, a large value is returned. }
+{\item \verb~d~: A measure of the distance from $M$ to $SE(3)$, the
+  space of transformation matrices.  Let $R$ be the top-left $3 \times 3$ submatrix of $M$, i.e., the portion of $M$ expected to represent a rotation matrix.  If ${\rm det}(R)>0$ (the determinant of $R$ should be $1$ if $R \in SO(3)$), the distance is calculated as $\|M^\prime -I\|_F$, where the top-left $3 \times 3$ submatrix of $M^\prime$ is $R^\trans R$ (which should be the identity matrix if $R \in SO(3)$), the $1 \times 4$ bottom row of $M^\prime$ is the same as the bottom row of $M$, and the elements $M^\prime_{14}$, $M^\prime_{24}$, and $M^\prime_{34}$ are zero.  The Frobenius norm $\| \cdot \|_F$ of a matrix is the the square root of the sum of the squares of the absolute values of the elements of the matrix.  If the determinant of $R$ is not positive, a large value is returned. }
 {}
 \end{function}
 
 \begin{function}			%TestIfSE3
 {judge = TestIfSE3(mat)}
-{\item \verb~mat~: A $4 \times 4$ matrix $mat$.}
+{\item \verb~mat~: A $4 \times 4$ matrix $M$.}
-{\item \verb~judge~:  $1$ if $mat$ is a transformation matrix (an element of $SE(3)$) and $0$ otherwise.  This function calls \verb~DistanceToSE3(mat)~ and tests if the returned distance is smaller than a small value (which you should feel free to change to suit your purposes).}
+{\item \verb~judge~:  $1$ if $M$ is a transformation matrix (an element of $SE(3)$) and $0$ otherwise.  This function calls \verb~DistanceToSE3(mat)~ and tests if the returned distance is smaller than a small value (which you should feel free to change to suit your purposes).}
 {}
 \end{function}
 
 \begin{function}			%ProjectToSE3
 {T = ProjectToSE3(mat)}
-{\item \verb~mat~: A $4 \times 4$ matrix $mat$.}
+{\item \verb~mat~: A $4 \times 4$ matrix $M$.}
-{\item \verb~T~:  The closest transformation matrix (element of $SE(3)$) to $mat$.  This function is only appropriate for matrices $mat$ that are ``close'' to $SE(3)$.  For example, $mat$ could be the result of a long series of multiplications of transformation matrices, which has caused the result to drift slightly away from satisfying the conditions of $SE(3)$ (top left $3\times 3$ submatrix is in $SO(3)$ and the bottom row is $[0 \; 0\; 0 \; 1]$) due to roundoff errors.}
+{\item \verb~T~:  The closest transformation matrix (element of $SE(3)$) to $M$.  This function is only appropriate for matrices $M$ that are ``close'' to $SE(3)$.  For example, $M$ could be the result of a long series of multiplications of transformation matrices, which has caused the result to drift slightly away from satisfying the conditions of $SE(3)$ (top-left $3\times 3$ submatrix is in $SO(3)$ and the bottom row is $[0 \; 0\; 0 \; 1]$) due to roundoff errors.  The top-left $3 \times 3$ submatrix of $T$ is the $SO(3)$ matrix closest to the top-left $3 \times 3$ submatrix of $M$, the bottom row of $T$ is $[0 \; 0\; 0\; 1]$, and the elements $T_{14}$, $T_{24}$, and $T_{34}$ are equivalent to the elements  $M_{14}$, $M_{24}$, and $M_{34}$, respectively.  }
 {}
 \end{function}
 

packages/Mathematica/README.md

@@ -1,9 +1,5 @@
 # "ModernRobotics" Mathematica Package Instructions #
 
-This package is the code library for _Modern Robotics: Mechanics, Planning, 
-and Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more 
-details please see the [website](http://modernrobotics.org/).
-
 ## Installing the Package ##
 
 ### Recommended Installation Instructions ###
@@ -16,10 +12,10 @@ Mathematica's front end to install this package. Use the following steps:
 2. Click `File -> Install...`
 3. Select `Package` for the _Type of Item to Install_
 4. Chose `From File...` for the _Source_
-5. Navigate to the `ModernRobotics.m` and select it as the source for the 
+5. Navigate to `ModernRobotics.m` and select it as the source for the 
    package
 6. The _Install Name_ should default to `ModernRobotics`; if it doesn't then
-   fill in the install name to be `ModernRobotics`.
+   fill in the install name to be `ModernRobotics`
 7. Choose whether you want the package installed for a single user or for all
    users (may require administrative privileges)
 8. Click `OK`
@@ -28,7 +24,7 @@ Mathematica's front end to install this package. Use the following steps:
 
 If you have any troubles with the front-end installation described above, try
 manually installing the package by copying the `ModernRobotics.m` file into 
-the following director.
+the following directory.
 
 ```sh
 $MATHPATH/Applications/ModernRobotics/

packages/Matlab/README.md

@@ -1,12 +1,9 @@
-# "mr" Matlab Code Library Instructions #
+# "mr" MATLAB Code Library Instructions #
-
-This is the code library for _Modern Robotics: Mechanics, Planning, and 
-Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more details 
-please see the [website](http://modernrobotics.org/).
 
 ## Installing the Library ##
 
-This code library does not need installation.
+Copy the "mr" folder to a known location on your computer. We will call the
+path to this folder `$FOLDER_PATH/mr`.
 
 ## Importing the Library ##
 
@@ -16,8 +13,7 @@ To import the library, use `addpath` as
 addpath('$FOLDER_PATH/mr')
 ```
 
-where `$FOLDER_PATH` is the path to "mr" folder. This process is required for
+This process is required for any program using this package.
-any program using this package.
 
 ## Using the Package ##
 
@@ -40,7 +36,7 @@ invR = RotInv(R);
 You should get the the variable `invR` whose value is the same as the output
 shown in the function usage example.
 
-To check the function list and which chapter in the book do those functions 
+To check the function list and which chapter in the book those functions 
 belong to, use `help` as 
 
 ```

packages/Python/README.md

@@ -1,9 +1,5 @@
 # "modern_robotics" Python Package Instructions #
 
-This package is the code library for _Modern Robotics: Mechanics, Planning, 
-and Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more 
-details please see the [website](http://modernrobotics.org/).
-
 ## Installing the Package ##
 
 ### Recommended Method ###
@@ -16,7 +12,7 @@ pip install modern_robotics
 ``` 
 
 If pip is not preinstalled, check 
-[here](https://pip.pypa.io/en/stable/installing/) for help of installing pip. 
+[here](https://pip.pypa.io/en/stable/installing/) for help installing pip. 
 
 ### Alternative Method ###
 
@@ -53,7 +49,7 @@ R = np.array([[0, 0, 1],
 invR = mr.RotInv(R)
 ```
 
-You should get the the variable `invR` whose value is the same as the output
+You should get the variable `invR` whose value is the same as the output 
 shown in the function usage example.
 
 ## Using the Package Locally ##