idris2-robotlib/README.md

74 lines
2 KiB
Markdown
Raw Normal View History

2022-12-12 19:30:00 -05:00
# 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`.