From 93beffe52e60a7c6eb014587dce9fab06dc88ba8 Mon Sep 17 00:00:00 2001 From: Kiana Sheibani 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 +``` + + + +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