0-kinematic_model_creation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7908c095",
   "metadata": {},
   "source": [
    "# Creating a pure kinematic bioMod model\n",
    "This file shows how to create a `.bioMod` file, what should be declared, what it means, etc.\n",
    "Additionnally, we explore how to generate the file programmatically. \n",
    "Please note that nothing prevents you from writting the file by hand.\n",
    "\n",
    "In a nutshell a `.bioMod` file is a description of a rigid body kinematic chain. \n",
    "It therefore expects a serie of segments linked by degree of freedom, up to six (up to three translations and three rotations). \n",
    "Once loaded, if a degree of freedom is given to the model, then one can interact with it on this degree of freedom.\n",
    "\n",
    "If one is interested only by the kinematics, then the inertial parameters can be omitted (which we omit here). \n",
    "Otherwise, they have to be declared (see `2-dynamic_model_creation`)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e9109cd",
   "metadata": {},
   "source": [
    "## Make our life easier\n",
    "First of all, let's make our life easier by defining a class that we will fill for each of the segments and markers.\n",
    "\n",
    "This section helps automatically write the file. \n",
    "If you want to write it by hand, you can skip this section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1e696fd0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os \n",
    "\n",
    "# Prepare the name of the output file and create a 'models' folder if needed\n",
    "kinematic_model_file_path = \"models/SimpleBody.bioMod\"\n",
    "kinematic_chain_save_path_file = \"models/simple_body_kinematic_chain.kc\"\n",
    "\n",
    "if not os.path.isdir(\"models\"):\n",
    "    os.mkdir(\"models\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d948e40f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# First of all, let's make our life easier by defining a class that we will fill for each of the segment\n",
    "# Notice that mass, center_of_mass and inertia_xxyyzz are currently ignored. They will become relevant in \n",
    "# dynamics section below\n",
    "class Segment():\n",
    "    def __init__(\n",
    "        self, \n",
    "        name, \n",
    "        parent_name=\"\", \n",
    "        rt=\"\",\n",
    "        translations=\"\", \n",
    "        rotations=\"\",\n",
    "        mass=0,\n",
    "        center_of_mass=None,\n",
    "        inertia_xxyyzz=None,\n",
    "        mesh: tuple=None,\n",
    "        markers: tuple=None,\n",
    "    ):\n",
    "        self.name = name\n",
    "        self.parent_name = parent_name\n",
    "        self.rt = rt\n",
    "        self.translations = translations\n",
    "        self.rotations = rotations\n",
    "        self.mass = mass\n",
    "        self.center_of_mass=center_of_mass\n",
    "        self.inertia_xxyyzz=inertia_xxyyzz\n",
    "        self.mesh = mesh\n",
    "        self.markers = markers\n",
    "\n",
    "    def __str__(self):\n",
    "        # Define the print function so it automatically format things in the file properly<\n",
    "        out_string = f\"segment {self.name}\\n\"\n",
    "        if (self.parent_name):\n",
    "            out_string += f\"\\tparent {self.parent_name}\\n\"\n",
    "        if (self.rt):\n",
    "            out_string += f\"\\tRT {self.rt}\\n\"\n",
    "        if (self.translations):\n",
    "            out_string += f\"\\ttranslations {self.translations}\\n\"\n",
    "        if (self.rotations):\n",
    "            out_string += f\"\\trotations {self.rotations}\\n\"\n",
    "        if (self.mass):\n",
    "            out_string += f\"\\tmass {self.mass}\\n\"\n",
    "        if (self.center_of_mass):\n",
    "            out_string += f\"\\tcom {self.center_of_mass[0]} {self.center_of_mass[1]} {self.center_of_mass[2]}\\n\"\n",
    "        if (self.inertia_xxyyzz):\n",
    "            out_string += f\"\\tinertia {self.inertia_xxyyzz[0]} 0 0\\n\" + \\\n",
    "                          f\"\\t        0 {self.inertia_xxyyzz[1]} 0\\n\" + \\\n",
    "                          f\"\\t        0 0 {self.inertia_xxyyzz[2]}\\n\"\n",
    "        if (self.mesh):\n",
    "            for m in self.mesh:\n",
    "                out_string += f\"\\tmesh {m[0]} {m[1]} {m[2]}\\n\"\n",
    "        out_string += \"endsegment\\n\"\n",
    "        \n",
    "        # Also print the markers attached to the segment\n",
    "        if (self.markers):\n",
    "            for marker in self.markers:\n",
    "                out_string += str(marker)\n",
    "        return out_string\n",
    "\n",
    "\n",
    "# Here is an example on how to use this class\n",
    "my_new_segment = Segment(\n",
    "    name=\"my_new_semgent_name\", \n",
    "    parent_name=\"the_name_of_the_parent_segment\", \n",
    "    rt=\"0 0 0 xyz 0 0 0\",  # The transformation between the segment and its parent. The first three values are the three rotations about the given sequence (here xyz) and then the three translations\n",
    "    translations=\"yxz\",  # The degrees of fredom in translation\n",
    "    rotations=\"xyz\",  # The degrees of fredom in rotation\n",
    "    mesh=((0, 0, 0), (0, 0, 0.3))  # The list of mesh point to show to create the stick figure. All the points are link in order\n",
    ")\n",
    "print(my_new_segment)  # Later this print should be sent to a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c21bb5ec",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's do the same for the markers\n",
    "class Marker():\n",
    "    def __init__(\n",
    "        self, \n",
    "        name, \n",
    "        parent_name, \n",
    "        position,\n",
    "    ):\n",
    "        self.name = name\n",
    "        self.parent_name = parent_name\n",
    "        self.position = position\n",
    "\n",
    "    def __str__(self):\n",
    "        # Define the print function so it automatically format things in the file properly<\n",
    "        out_string = f\"marker {self.name}\\n\"\n",
    "        out_string += f\"\\tparent {self.parent_name}\\n\"\n",
    "        out_string += f\"\\tposition {self.position[0]} {self.position[1]} {self.position[2]}\\n\"\n",
    "        out_string += \"endmarker\\n\"\n",
    "        return out_string\n",
    "\n",
    "# Here is an example on how to use this class\n",
    "my_new_marker = Marker(\n",
    "    name=\"my_new_marker_name\",\n",
    "    parent_name=\"the_name_of_the_parent_segment\",\n",
    "    position=(0, 0, 1),\n",
    ")\n",
    "print(my_new_marker)  # Later this print should be sent to a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7aa693f7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# And why not creating a data structure that will collect all the segments and produce the a full\n",
    "# kinematic chain that can easily be printed\n",
    "class KinematicChain():\n",
    "    def __init__(self, segments):\n",
    "        self.segments = segments\n",
    "        \n",
    "    def __str__(self):\n",
    "        out_string = \"version 4\\n\\n\"\n",
    "        for segment in self.segments:\n",
    "            out_string += str(segment)\n",
    "            out_string += \"\\n\\n\\n\"  # Give some space between segments\n",
    "        return out_string\n",
    "    \n",
    "    def write(self, file_path):\n",
    "        # Method to write the current KinematicChain to a file\n",
    "        with open(file_path, \"w\") as file:\n",
    "            file.write(str(self))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7285e3d1",
   "metadata": {},
   "source": [
    "## Create the `SimpleBody.bioMod` kinematic chain\n",
    "Now we are ready to produce the kinematic chain.\n",
    "It is a 2D model made from the mean dimension of the adjusted De Leva model (see the doc folder):\n",
    "- A TRUNK segment that includes the HEAD (up to the ear) at $72cm$ that moves frontward and upward (translations y and z) and rotations about the medio-lateral axis (rotations x);\n",
    "- An ARM segment attached to the TRUNK at $53cm$ that includes the HAND at $61cm$. It rotates about the medio-lateral axis (rotations x);\n",
    "- An THIGH segment attached to the TRUNK. It rotates about the medio-lateral axis (rotations x)\n",
    "- An SHANK segment attached to the THIGH at $42cm$. It rotates about the medio-lateral axis (rotations x)\n",
    "- An FOOT segment attached to the SHANK at $43cm$ that includes a FOOT of $25cm$. It rotates about the medio-lateral axis (rotations x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4d0e87b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's define the segments and the skin markers attached to each segment \n",
    "# and collect all the values in the KinematicChain class\n",
    "\n",
    "# The trunk segment\n",
    "trunk_marker_pelvis = Marker(\n",
    "    name=\"PELVIS\", \n",
    "    parent_name=\"TRUNK\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "trunk = Segment(\n",
    "    name=\"TRUNK\",\n",
    "    translations=\"yz\", \n",
    "    rotations=\"x\", \n",
    "    mesh=((0, 0, 0), (0, 0, 0.53)),\n",
    "    markers=[trunk_marker_pelvis]\n",
    ")\n",
    "\n",
    "\n",
    "\n",
    "# The head segment\n",
    "top_head_marker_head = Marker(\n",
    "    name=\"TOP_HEAD\",\n",
    "    parent_name=\"HEAD\",\n",
    "    position=(0, 0, 0.24),\n",
    ")\n",
    "head = Segment(\n",
    "    name=\"HEAD\",\n",
    "    parent_name=\"TRUNK\",\n",
    "    rt=\"0 0 0 xyz 0 0 0.53\",\n",
    "    mesh=((0, 0, 0), (0, 0, 0.24)),\n",
    "    markers=[top_head_marker_head],\n",
    ")\n",
    "\n",
    "\n",
    "\n",
    "# The arm segment\n",
    "shoulder_marker = Marker(\n",
    "    name=\"SHOULDER\", \n",
    "    parent_name=\"UPPER_ARM\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "upper_arm = Segment(\n",
    "    name=\"UPPER_ARM\",\n",
    "    parent_name=trunk.name, \n",
    "    rt=\"0 0 0 xyz 0 0 0.53\", \n",
    "    rotations=\"x\", \n",
    "    mesh=((0, 0, 0), (0, 0, -0.28)),\n",
    "    markers=[shoulder_marker],\n",
    ")\n",
    "\n",
    "elbow_marker = Marker(\n",
    "    name=\"ELBOW\",\n",
    "    parent_name=\"LOWER_ARM\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "lower_arm = Segment(\n",
    "    name=\"LOWER_ARM\",\n",
    "    parent_name=upper_arm.name,\n",
    "    rt=\"0 0 0 xyz 0 0 -0.28\",\n",
    "    mesh=((0, 0, 0), (0, 0, -0.27)),\n",
    "    markers=[elbow_marker],\n",
    ")\n",
    "\n",
    "wrist_marker = Marker(\n",
    "    name=\"WRIST\",\n",
    "    parent_name=\"HAND\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "finger_marker = Marker(\n",
    "    name=\"FINGER\",\n",
    "    parent_name=\"HAND\",\n",
    "    position=(0, 0, -0.19),\n",
    ")\n",
    "hand = Segment(\n",
    "    name=\"HAND\",\n",
    "    parent_name=lower_arm.name,\n",
    "    rt=\"0 0 0 xyz 0 0 -0.27\",\n",
    "    mesh=((0, 0, 0), (0, 0, -0.19)),\n",
    "    markers=[wrist_marker, finger_marker]\n",
    ")\n",
    "\n",
    "\n",
    "\n",
    "# The thigh segment\n",
    "thigh = Segment(\n",
    "    name=\"THIGH\", \n",
    "    parent_name=trunk.name, \n",
    "    rotations=\"x\", \n",
    "    mesh=((0, 0, 0), (0, 0, -0.42)),\n",
    ")\n",
    "\n",
    "\n",
    "# The shank segment\n",
    "knee_marker = Marker(\n",
    "    name=\"KNEE\", \n",
    "    parent_name=\"SHANK\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "shank = Segment(\n",
    "    name=\"SHANK\", \n",
    "    parent_name=thigh.name, \n",
    "    rt=\"0 0 0 xyz 0 0 -0.42\", \n",
    "    rotations=\"x\", \n",
    "    mesh=((0, 0, 0), (0, 0, -0.43)),\n",
    "    markers=[knee_marker],\n",
    ")\n",
    "\n",
    "\n",
    "# The foot segment\n",
    "ankle_marker = Marker(\n",
    "    name=\"ANKLE\", \n",
    "    parent_name=\"FOOT\",\n",
    "    position=(0, 0, 0),\n",
    ")\n",
    "toe_marker = Marker(\n",
    "    name=\"TOE\", \n",
    "    parent_name=\"FOOT\",\n",
    "    position=(0, 0, 0.25),\n",
    ")\n",
    "foot = Segment(\n",
    "    name=\"FOOT\", \n",
    "    parent_name=shank.name, \n",
    "    rt=\"0 0 0 xyz 0 0 -0.43\", \n",
    "    rotations=\"x\", \n",
    "    mesh=((0, 0, 0), (0, 0, 0.25)),\n",
    "    markers=[ankle_marker, toe_marker],\n",
    ")\n",
    "\n",
    "# Put the model together, print it and print it to a bioMod file\n",
    "kinematic_chain = KinematicChain(segments=(trunk, head, upper_arm, lower_arm, hand, thigh, shank, foot))\n",
    "print(kinematic_chain)\n",
    "kinematic_chain.write(kinematic_model_file_path)\n",
    "\n",
    "# Let's also save the kinematic_chain as a python structure. This will be useful in `2-DynamicModelCreation`\n",
    "import pickle\n",
    "with open(kinematic_chain_save_path_file, \"wb\") as file:\n",
    "    pickle.dump(kinematic_chain, file)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe1f1ae7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run this cell to show the model you just created. \n",
    "# Please note that due to some jupyter limitations, you may have to restart after running this cell\n",
    "# Please also note that this cell will crash if runned from the binder\n",
    "\n",
    "import bioviz\n",
    "\n",
    "# Send the previously loaded model to the vizualizer\n",
    "viz = bioviz.Viz(kinematic_model_file_path)\n",
    "\n",
    "# Move the model to a recognizable position (arm raised and knee flexed)\n",
    "viz.set_q((0, 0, -0.15, 1.20, 0.7, -1, -1.11))\n",
    "\n",
    "# Halt the program so you can interact with the vizualiser. Closing the window should allow to continue\n",
    "viz.exec()\n",
    "\n",
    "# If nothing happens, check for background. Sometimes the window loads behind the current window"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}