From 93beffe52e60a7c6eb014587dce9fab06dc88ba8 Mon Sep 17 00:00:00 2001
From: Kiana Sheibani <kiana.a.sheibani@gmail.com>
Date: Mon, 12 Dec 2022 19:30:00 -0500
Subject: [PATCH] Add README

---
 README.md                                  | 73 ++++++++++++++++++++++
 robotlib.ipkg                              |  3 +
 {Kinematics => src/Kinematics}/Arm.idr     |  0
 {Kinematics => src/Kinematics}/Forward.idr |  0
 {Kinematics => src/Kinematics}/Inverse.idr |  0
 {Kinematics => src/Kinematics}/Joint.idr   |  0
 6 files changed, 76 insertions(+)
 create mode 100644 README.md
 rename {Kinematics => src/Kinematics}/Arm.idr (100%)
 rename {Kinematics => src/Kinematics}/Forward.idr (100%)
 rename {Kinematics => src/Kinematics}/Inverse.idr (100%)
 rename {Kinematics => src/Kinematics}/Joint.idr (100%)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0a6451d
--- /dev/null
+++ b/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`.
diff --git a/robotlib.ipkg b/robotlib.ipkg
index 89cd784..32f50f7 100644
--- a/robotlib.ipkg
+++ b/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,
diff --git a/Kinematics/Arm.idr b/src/Kinematics/Arm.idr
similarity index 100%
rename from Kinematics/Arm.idr
rename to src/Kinematics/Arm.idr
diff --git a/Kinematics/Forward.idr b/src/Kinematics/Forward.idr
similarity index 100%
rename from Kinematics/Forward.idr
rename to src/Kinematics/Forward.idr
diff --git a/Kinematics/Inverse.idr b/src/Kinematics/Inverse.idr
similarity index 100%
rename from Kinematics/Inverse.idr
rename to src/Kinematics/Inverse.idr
diff --git a/Kinematics/Joint.idr b/src/Kinematics/Joint.idr
similarity index 100%
rename from Kinematics/Joint.idr
rename to src/Kinematics/Joint.idr