Add README

README.md

@@ -0,0 +1,73 @@
+# Robot Kinematics Library
+
+This library calculates the forward and inverse kinematics for an arbitrary
+robot arm in an arbitrary number of dimensions.
+
+## Install
+
+This library depends on [NumIdr](https://github.com/kiana-S/numidr), which
+must be installed first.
+
+To install:
+
+``` shell
+git clone https://github.com/kiana-S/idris2-robotlib
+cd idris2-robotlib
+idris2 --install robotlib.ipkg
+```
+
+## Tutorial
+
+``` idris
+import Kinematics.Forward
+import Kinematics.Inverse
+```
+
+<!-- idris
+import Data.Vect
+import Data.Fuel
+-->
+
+A robot arm is a value of type `ArmElement n`, where *n* is the number of
+dimensions the robot operates in. An arm is constructed by chaining together
+arm elements left-to-right using the `<+>` operator. Some examples of arm elements are:
+
+- `link`, a link in a direction given by a vector
+- `linkX`, a link in the +X direction given its length
+- `revolute2D`, a 2D revolute joint
+- `revoluteX, revoluteY, revoluteZ`, 3D revolute joints along the corresponding axis
+
+For example, here is a simple SCARA robot arm in 2D space:
+
+``` idris
+scara : ArmElement 2
+scara = revolute2D (-pi/2) (pi/2) <+> linkX 5
+    <+> revolute2D (-pi/2) (pi/2) <+> linkX 7
+```
+
+The joint constructors take as arguments their limit angles. All angles are
+given in radians.
+
+To calculate the forward kinematics of a robot arm, use the function `forward`,
+which takes in an arm and a vector of joint values. For example:
+
+``` idris
+endPos : Maybe (Point 2 Double)
+endPos = forward scara (vector [2.1, 1.6])
+```
+
+If any of the joint values are outside of the respective joint's limits, the
+function will return `Nothing`.
+
+To numerically calculate the inverse kinematics of a robot arm, use the
+function `inverse`. It takes in the robot arm and an endpoint, along with a
+"fuel" value that limits how many iterations the algorithm performs, one of
+`forever` or `(limit n)`.
+
+``` idris
+calcInverse : Maybe (Vector 2 Double)
+calcInverse = inverse forever scara (point [9, 4])
+```
+
+If the algorithm cannot find any solutions within the joint limits, it will
+return `Nothing`.

robotlib.ipkg

@@ -6,6 +6,9 @@ license = "MIT"
 
 langversion >= 0.5.1
 
+sourcedir = "src"
+readme = "README.md"
+
 depends = numidr >= 0.2.1
 
 modules = Kinematics.Joint,