docs/1-basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 1\n",
    "\n",
    "other doc sources:\n",
    "https://github.com/MarcToussaint/rai-maintenance/tree/master/help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "sys.path.append('../rai/rai/ry')\n",
    "import numpy as np\n",
    "import libry as ry"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting up a basic Config\n",
    "\n",
    "The starting point is to create a `Configuration`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C = ry.Config()\n",
    "D = C.view()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This shows an empty configuration. Tip: Make the view window appear \"Always On Top\" (right click on the window bar)\n",
    "\n",
    "You can add things (objects, scene models, robots) to a configuration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.clear()\n",
    "C.addFile('../rai-robotModels/pr2/pr2.g')\n",
    "C.addFile('../rai-robotModels/objects/kitchen.g')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the view was updated automatically. (Internally, the view 'subscribes' to updates of the shared memory of Config)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ball = C.addFrame(name=\"ball\")\n",
    "ball.setShape(ry.ST.sphere, [.1])\n",
    "ball.setPosition([.8,.8,1.5])\n",
    "ball.setColor([1,1,0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One can also add convex meshes (just passing the vertex array), or use sphere-swept convex meshes (ssBox, capsule, sphere, etc)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hand = C.addFrame(name=\"hand\", parent=\"pr2L\")\n",
    "hand.setShape(ry.ST.ssBox, size=[.2,.2,.1,.02]),\n",
    "hand.setRelativePosition([0,0,-.1])\n",
    "hand.setColor([1,1,0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this last example, the new object has another frame (pr2L) as *parent*. This means that it is permanently attached to this parent. pos and quat/rot are interpreted relative to the parent."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Joint and Frame State\n",
    "\n",
    "A configuration is a tree of n frames. Every frame has a pose (position & quaternion), which is represented as a 7D vector (x,y,z, qw,qx,qy,qz). The frame state is the $n\\times 7$ matrix, where the i-th row is the pose of the i-th frame.\n",
    "\n",
    "A configuration also defines joints, which means that the relative transfromation from a parent to a child frame is parameterized by degrees-of-freedoms (DOFs). If the configuration has in total n DOFs, the joint state is a n-dimensional vector.\n",
    "\n",
    "Setting the joint state implies computing all relative transformations, and then forward chaining all transformations to compute all frame poses. So setting the joint state also sets the frame state.\n",
    "     \n",
    "Setting the frame state allows you to set frame poses that are inconsistent/impossible w.r.t. the joints! Setting the frame state implies computing all relative transformations from the frame poses, and then assigning the joint state to the *projection* onto the actual DOFs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "q = C.getJointState()\n",
    "print('joint names: ', C.getJointNames() )\n",
    "print('joint state: ', q)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's move the configuration by adding to the joint configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "q[2] = q[2] + 1.\n",
    "C.setJointState(q)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The *frame state* is a $n\\times 7$ matrix, which contains for all of $n$ frames the 7D pose. A pose is stored as [p_x, p_y, p_z, q_w, q_x, q_y, q_z], with position p and quaternion q."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "X0 = C.getFrameState()\n",
    "print('frame state: ', X0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's do a questionable thing: adding .1 to all numbers in the frame matrix!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "X = X0 + .1\n",
    "C.setFrameState(X)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The rows of X have non-normalized quaternions! These are normalized when setting the frame state.\n",
    "\n",
    "Also, the frame poses are now *inconsistent* to the joint constraints! We can read out the projected joint state, set the joint state, and get a consistent state again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.setJointState( C.getJointState() )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's bring the configuration back into the state before the harsh *setFrame*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.setFrameState(X0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Selecting joints\n",
    "\n",
    "Often one would like to choose which joints are actually active, that is, which joints are referred to in q. This allows one to sub-select joints and work only with projections of the full configuration state. This changes the joint state dimensionality, including ordering of entries in q.\n",
    "\n",
    "The frame state is not affected by such a selection of active joints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.selectJointsByTag([\"armL\",\"base\"])\n",
    "q = C.getJointState()\n",
    "print('joint state: ', q)\n",
    "print('joint names: ', C.getJointNames() )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Features & Jacobians\n",
    "\n",
    "A core part of rai defines features over configurations. A feature is a differentiable mapping from a configuration (or set of configurations) to a vector. Starndard features are \"position-of-endeffector-X\" or \"distance/penetration-between-convex-shapes-A-and-B\", etc. But there are many, many more features defined in rai, like error of Newton-Euler-equations for an object, total energy of the system, etc. Defining differentiable features is the core of many functionalities in the rai code.\n",
    "\n",
    "Let's define a basic feature over C: the 3D (world coordinate) position of pr2L (left hand)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "F = C.feature(ry.FS.position, [\"pr2L\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now evaluate the feature, and also get the Jacobian:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(F.description(C))\n",
    "\n",
    "[y,J] = F.eval(C)\n",
    "print('hand position =', y)\n",
    "print('Jacobian =', J)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "F2 = C.feature(ry.FS.distance, [\"hand\", \"ball\"])\n",
    "print(F2.description(C))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "F2.eval(C)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you call a feature on a *tuple* of configurations, by default it computes the difference, acceleration, etc, w.r.t. these configurations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C2 = ry.Config()\n",
    "C2.copy(C)  #this replicates the whole structure\n",
    "V2 = C2.view()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "F.eval((C,C2))[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This should be zero. To see a difference, let's move the 2nd configuration:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# just to see a difference between the two:\n",
    "q = C2.getJointState()\n",
    "q = q - .1\n",
    "C2.setJointState(q)\n",
    "y = F.eval((C,C2))[0]\n",
    "print('hand difference (y(C2) - y(K)) =', y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An acceleration example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C3 = ry.Config()\n",
    "C3.copy(C);\n",
    "C3.setJointState(q + .2);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(y,J) = F.eval((C, C2, C3))\n",
    "print('hand acceleration = ', y)\n",
    "print('shape of Jacobian =', J.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the Jacobian is now w.r.t. all three configurations! It is of size 3x3xdim(q). Let's retrieve the Jacobian w.r.t. C3 only:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "J = J.reshape((3,3,q.size))\n",
    "print('shape of Jacobian =', J.shape)\n",
    "J[:,1,:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example, when the dimensions of C and C2 are different:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C2.selectJointsByTag(['armL'])\n",
    "(y,J) = F.eval((C,C2))\n",
    "print('shape of Jacobian =', J.shape)\n",
    "print('dimensions of configurations =', (C.getJointDimension(), C2.getJointDimension()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can linearly transform features by setting 'scale' and 'target':"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#F.scale = 10.\n",
    "#F.target = [0., 0., 1.];\n",
    "#  y = F(C);\n",
    "#  //.. now y = F.scale * (f(C) - F.target), which means y is zero if\n",
    "#  //the feature f(C) is equal to the target (here, if the hand is in world\n",
    "#  //position (0,0,1) )\n",
    "#\n",
    "#  //F.scale can also be a matrix, which can transform the feature also to lower dimensionality\n",
    "#  F.scale = arr(1,3,{0., 0., 1.}); //defines the 1-times-3 matrix (0 0 1)\n",
    "#  y = F(C);\n",
    "#  //.. now y is 1-dimensional and captures only the z-position "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# THE REST IS PRELIM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also add a frame, attached to the head, which has no shape associated to it, but create a view is associated with that frame:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.addFrame(name='camera', parent='head_tilt_link', args='Q:<d(-90 1 0 0) d(180 0 0 1)> focalLength:.3')\n",
    "V = C.view(frame='camera')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we move the robot, that view moves with it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "C.setJointState(q=np.asarray([0.5]), joints=['head_pan_joint'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To close a view (or destroy a handle to a computational module), we reassign it to zero. We can also remove a frame from the configuration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "V = 0\n",
    "C.delFrame('camera')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This solves a simple IK problem, defined by an equality constraint on the difference in position of 'ball' and 'hand'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "TODO demos:\n",
    "\n",
    "* rename Camera -> View\n",
    "* copy configurations\n",
    "* have multiple configurations and views in parallel\n",
    "* selecting/modifying DOFs (i.e., which joints are considered DOFs)\n",
    "* I/O with other file formats"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}