mithi / hexapod-robot-simulator

A hexapod robot simulator built from first principles

🌸 ✊

I'm a frontend web engineer - building performant, high-quality user interfaces. Formerly, a robotics teacher.

Aeronology Luxor Datature

Above stats generated with: tipsy/profile-summary-for-github

hexapod-robot-simulator's Issues

Improve code quality

hexapod.Linkage

• Format this better
  

  hexapod-robot-simulator/hexapod/linkage.py

  Line 158 in 35cac5c

  leg_string = f"""\nLinkage(a={self._a}, b={self._b}, c={self._c}, alpha={self._alpha}, beta={self._beta},gamma={self._gamma}, new_origin={self._new_origin}, new_axis={self._coxia_axis}, id_number={self.id}, name={self.name})\n"""

• Use a for loop instead
  

  hexapod-robot-simulator/hexapod/linkage.py

  Line 142 in 35cac5c

  self.p0.update_point_wrt(frame, height)

Ideas to improve code quality

The variable trio isn't being used at all, should we even return it, or should we just return the n axis and the height?

hexapod-robot-simulator/hexapod/ground_contact_solver/ground_contact_solver.py

Line 39 in 531fbb3

trio, n, height = find_ground_plane_properties(legs)

Implementation improvements

While porting this to javascript I have discovered so many ways to improve the code structure and algorithms found in this project

Take a look at the following files on the new project
https://github.com/mithi/hexapod/blob/master/src/hexapod/Linkage.js
https://github.com/mithi/hexapod/blob/master/src/hexapod/VirtualHexapod.js
https://github.com/mithi/hexapod/blob/master/src/hexapod/basicObjects.js

Most plotter instance methods should be static methods

hexapod-robot-simulator/hexapod/plotter.py

Line 13 in 5c1f8a1

def _draw_hexapod(self, fig, hexapod):

def _draw_hexapod(self, fig, hexapod)
def _draw_scene(self, fig, hexapod)
def change_camera_view(self, fig, camera)

See also: Introduction to Static Methods for Dummies

❗Some unstable poses are marked as stable

❗ Some unstable poses are not marked as unstable

Optimize to make updating the graph faster

Live on https://hexapod-robot-simulator.herokuapp.com
Convert this to to be a fully client-side JavaScript app?

Improve code quality of 4 specific modules

• hexapod.models
• hexapod.linkage
• hexapod.ik_solver.ik_solver
• hexapod.ground_contact_solver

https://github.com/mithi/hexapod-robot-simulator/blob/master/hexapod/models.py
https://github.com/mithi/hexapod-robot-simulator/blob/master/hexapod/linkage.py
https://github.com/mithi/hexapod-robot-simulator/blob/master/hexapod/ground_contact_solver.py
https://github.com/mithi/hexapod-robot-simulator/blob/master/hexapod/ik_solver/ik_solver.py

Minor refactoring suggestions to improve code quality

Should be poses.key() not poses.items()

hexapod-robot-simulator/pages/helpers.py

Line 22 in 5d0d7be

for k, _ in poses.items():

Legs on ground must be on the xy plane

Currently the legs on ground is tilted with respect to the hexagon which is in the xy plane

the polygon defined by the legs on ground must be parallel to the xy plane,
it's the polygon which must be tilted

Draw the projection of the center of gravity on the ground plane

You'd need to update the following
1. The model VirtualHexapod to have an attribute that stores this point

hexapod-robot-simulator/hexapod/models.py

Line 95 in 531fbb3

class VirtualHexapod:

You can compute this point as outlined by the algorithm here, you should inject the point calculation to a different function and update the attribute of the VirtualHexapod when this is called in the two compute_orientation_properties of the hexapod.ground_contact_solver module.

hexapod-robot-simulator/hexapod/ground_contact_solver/helpers.py

Line 14 in 531fbb3

def is_stable(p1, p2, p3, tol=0.001):

2. In figure template, you should append a new point trace at the end of the data list

hexapod-robot-simulator/hexapod/templates/figure_template.py

Line 226 in 531fbb3

HEXAPOD_FIGURE = {

The trace has the following format

    {
        "marker": {"color": INSERT_COLOR_HERE, "opacity": 1.0, "size": INSERT_SIZE_HERE},
        "mode": "markers",
        "name": "cog-projection",
        "type": "scatter3d",
        "x": [INSERT_COG_X_HERE],
        "y": [INSERT_COG_Y_HERE,
        "z": [0],
    }

3. HexapodPlotter could draw this point in the figure template

hexapod-robot-simulator/hexapod/plotter.py

Line 14 in 531fbb3

def _draw_hexapod(fig, hexapod):

Twisting about z axis does not account for all cases

If all feet are on the ground,
and only one of the legs (coxia) pivot, how should the hexapod react?

Add setting for inverse kinematics page

• Either show the detached hexapod or the default should be to prevent update to the figure

SHOW_DETACHED_HEXAPOD = False

Make text monospace

• Hexapod robot dimensions label
• Hexapod Robot dimensions input
• Kinematics control input

Should check linkage ground contact in reverse order

hexapod-robot-simulator/hexapod/linkage.py

Line 161 in f67434e

for point in self.all_points:

IE do this instead

        ground_contact = self.p3
        for point in reversed(self.all_points):
            if point.z < ground_contact.z:
                ground_contact = point

Remove redundant message in Page Inverse

We display the current state in the user interface even though the widgets are already displaying it. Is that really necessary?

Wrong behavior in kinematics

when all left tibia are set to 90,

the hexapod's legs are going in the ground

Raise an error instead of returning None for get_legs_on_ground()

See:

hexapod-robot-simulator/hexapod/ground_contact_solver.py

Line 21 in fd1be18

if trio is None:

Use docker

• See also https://docker-curriculum.com/

Change Naming conventions (suggestions)

For each page we have a sort of block like this

GRAPH_NAME = "graph-kinematics"
ID_MESSAGE_SECTION = "message-kinematics"
ID_PARAMETERS_SECTION = "parameters-kinematics"

sidebar = shared.make_standard_sidebar(
    ID_MESSAGE_SECTION, ID_PARAMETERS_SECTION, SECTION_POSE_CONTROL
)

layout = shared.make_standard_page_layout(GRAPH_NAME, sidebar)

outputs, inputs, states = shared.make_standard_page_inputs_outputs_states(
    GRAPH_NAME, ID_PARAMETERS_SECTION, ID_MESSAGE_SECTION
)

I'm not a fan of the variable names
maybe something like

graph_id
parameters_section_id
message_section_id

respectively is more meaningful and appropriate

Hexapod object doesn't check whether the angles are within range as set in `settings.py`

Should it? The IK solver checks it, and the widget slider constraints the angles as well.

Refactoring Suggestions

Replace:

hexapod-robot-simulator/index.py

Line 14 in 808534d

header = dcc.Markdown(

With:

div_header = html.Div(
    [
        html.A(html.H6("👾"), href=URL_REPO, target="_blank", style=icon_link_style),
        html.A(html.H6("☕"), href=URL_KOFI, target="_blank", style=icon_link_style),
        dcc.Link(html.H6("●"), href="/", style=icon_link_style),
        dcc.Link(html.H6("●"), href="/inverse-kinematics", style=icon_link_style),
        dcc.Link(html.H6("●"), href="/kinematics", style=icon_link_style),
    ],
    style={"display": "flex", "flex-direction": "row"}
)

So that the page does not not refresh

When the right middle coxia is twisted the whole hexapod twists

All other legs work fine.

Reimplement ik_solver (2.0) module

Reimplement inverse kinematics solver (hexapod.ik_solver2). The current implementation hexapod.ik_solver involves a bunch of tiny helper methods and one big god function that tries to do almost everything. I plan to redesign this by making a class that centers around this responsibility.

Recomputed Hexapod is sometimes not equal to Updated Hexapod. Why?

https://mithi.github.io/robotics-blog/blog/hexapod-simulator/3-prerelease-2/

Should determine how body twists around its z axis

How to determine how the hexagon body will twist around its z axis?

Ideas:

given pose before and pose after

determine which leg points are on the ground
on both before and after.

This points are the "pivot" points.

which means the shape of the polygon defined by these points
should be the same in the pose before and the pose after.

get any point in this set.

the angle between the vector A and B
where A is the vector from center of gravity to point in old pose
and B is the vector from center of gravity to point in new pose.

is the angle of the twist???

Modify to be more pythonic

• Remove type parameter for def make_translate_slider It is not used and it doesn't make any sense.
  

  hexapod-robot-simulator/widgets/ik_ui.py

  Line 34 in 5c1f8a1

  def make_translate_slider(name, slider_label, type="translate_slider"):

• Use None instead of {} as default parameter as per convention
  

  hexapod-robot-simulator/widgets/pose_control/kinematics_section_maker.py

  Line 28 in 5c1f8a1

  def make_section_pose_control(joint_inputs, add_joint_names=False, style_to_use={}):

  • dangerous-default-value (W0102) Dangerous default value %s as argument Used when a mutable value as list or dictionary is detected in a default value for an argument.
  • See also https://stackoverflow.com/questions/26320899/why-is-the-empty-dictionary-a-dangerous-default-value-in-python/26320917

• It seems like we don't actually need to store n_axis as an attribute
  

  hexapod-robot-simulator/hexapod/models.py

  Line 108 in 5c1f8a1

  "n_axis",

robot pose wrt to body not wrt to feet on ground

The body should be positions wrt to the feet
right now the feet is positioned wrt to the body

Add local coordinated wrt hexapod in plotter

So it's easier to see how the robot is tilted

Foot tips in contact with polygon disregards non-foot tip points

If the height of the foot tip is greater than the point of contact with the body,
use the point of contact with the body instead.

Legs can criss-cross each other

You shouldn't be able to do that,

Check adjacent legs if they're going to crash to each other.
Prevent this by just rotating at the best acceptable range (increment by 5 degrees maybe?)

Add automated integration, unit tests, code coverage

recompute_hexapod() assumes which legs are on the ground

# ❗❗IMPORTANT!This assumes leg with id 3 and id 4 are on the ground
# THIS IS NOT ALWAYS THE CASE.
# Should check which two legs are both on the ground before and after
# instead of using leg 3 and 4

hexapod-robot-simulator/hexapod/ik_solver/ik_solver.py

Line 156 in f6d9536

def recompute_hexapod(dimensions, ik_parameters, poses):

Wrong behavior when unstable pose is known

When Hexapod.ground_contact_solver.legs_ can't find a stable pose, Hexapod.models.VirtualHexapod will render hexapod with cog at Point(0, 0, 0)

Unexpected Behaviors to Address

Just add any screenshot of unexpected behavior as a comment

❗Algorithm for computing hexapod orientation does not account for all cases

❗❗❗

The old algorithm rests upon the assumption that it knows which point of the each leg is in contact with the ground. This assumption seems to be true for all possible cases for
leg-patterns page and inverse-kinematics page.

But this is not true for all possible angle combinations (18 angles) that can be defined in
the kinematics page.

This current algorithm will still be used for the leg-patterns page, and the inverse-kinematics page. A more general algorithm will be used for the kinematics page

The following algorithm can be used for the leg-patterns page and inverse-kinematics page.
(How to find the ground contact points, tilt, and height of the hexapod)

hexapod-robot-simulator/hexapod/ground_contact_solver.py

Line 1 in 45acb5a

"""

But this can't be used in general.
This is because how we determine the ground contact ie Linkage.compute_ground_contact() doesn't always yield the correct result.

hexapod-robot-simulator/hexapod/linkage.py

Line 162 in 45acb5a

def compute_ground_contact(self):

Here's the new algorithm that accounts for most cases

hexapod-robot-simulator/hexapod/ground_contact_solver/ground_contact_solver2.py

Line 52 in 531fbb3

def compute_orientation_properties(legs):

Check stability in ik_solver module

• Check pose stability. The inverse kinematics solver doesn't yet actually check if the center of gravity is inside its support polygon.

Hexapod does not remember most recent old pose

The way it works right now is,

for each update, a new hexapod is created from scratch (all angles = 0)
and then the hexapod poses is built from there on.

It would be better if we remember the old hexapod pose, especially for computing twists along the z axis.

Rename Point class to Vector

We are using the Point class for 3d Vectors as well. I think the Point name is loaded, Vector is a more generalized term for a set of three numbers

Some stable poses are being marked as unstable. Why?

Here are a few cases:

Add preliminary tests

• Page IK Random Pose
• Kinematics Random Pose
• Page Leg Pattern

Use quaternions instead of rotation matrices?

This implementation uses matrices, not quaternions. I'm aware that quaternions is far superior in every single way.

It might also be interesting to benchmark the performances of the two.

Good reference(s):

• https://github.com/petercorke/spatial-math

Refactor pages

We currently have three pages apart from the landing page

• The inverse kinematics page
• The kinematics page
• The leg patterns page

All of them have the following:

GRAPH_NAME = "graph-hexapod-patterns"
ID_MESSAGE_DISPLAY_SECTION = "display-message-patterns"
SECTION_MESSAGE_DISPLAY = html.Div(id=ID_MESSAGE_DISPLAY_SECTION)
ID_POSES_SECTION = "hexapod-poses-values-patterns"
SECTION_HIDDEN_JOINT_POSES = html.Div(id=ID_POSES_SECTION, style={"display": "none"})

SECTION_CONTROLS = [
    SECTION_DIMENSION_CONTROL,
    *insert_widget_section_here*,
    SECTION_MESSAGE_DISPLAY,
    SECTION_HIDDEN_BODY_DIMENSIONS,
    *insert_hidden_parameters_here*,
]

They also have something like this

OUTPUT_MESSAGE_DISPLAY = Output(ID_MESSAGE_DISPLAY_SECTION, "children")
INPUT_POSES_JSON = Input(*insert parameter section_id_here*, "children")
OUTPUTS = [Output(GRAPH_NAME, "figure"), OUTPUT_MESSAGE_DISPLAY]
INPUTS = [INPUT_DIMENSIONS_JSON, INPUT_POSES_JSON]
STATES = [State(GRAPH_NAME, "relayoutData"), State(GRAPH_NAME, "figure")]

We can refactor this into the shared module

Error Handling for IK Solver

Currently this is how we do it:

@app.callback(OUTPUTS, INPUTS, STATES)
def update_inverse_page(dimensions_json, ik_parameters_json, relayout_data, figure):
    if figure is None:
        return BASE_FIGURE, ""

    dimensions = helpers.load_dimensions(dimensions_json)
    hexapod = VirtualHexapod(dimensions)
    ik_parameters = json.loads(ik_parameters_json)
    hexapod, poses, alert = inverse_kinematics_update(hexapod, ik_parameters)

    if RECOMPUTE_HEXAPOD and poses:
        hexapod = recompute_hexapod(dimensions, ik_parameters, poses)

    BASE_PLOTTER.update(figure, hexapod)
    helpers.change_camera_view(figure, relayout_data)

    if poses:
        text = helpers.make_poses_message(poses)
    else:
        text = helpers.make_alert_message(alert)

    return figure, text

We can do something like this

@app.callback(OUTPUTS, INPUTS, STATES)
def update_inverse_page(dimensions_json, ik_parameters_json, relayout_data, figure):
    if figure is None:
        return BASE_FIGURE, ""

    ik_parameters = json.loads(ik_parameters_json)
    dimensions = helpers.load_dimensions(dimensions_json)
    hexapod = VirtualHexapod(dimensions)

    try:
        hexapod, poses = inverse_kinematics_update(hexapod, ik_parameters)
    except Exception as e:
        return figure, helpers.make_alert_message(e)

    if RECOMPUTE_HEXAPOD :
        hexapod = recompute_hexapod(dimensions, ik_parameters, poses)

    BASE_PLOTTER.update(figure, hexapod)
    helpers.change_camera_view(figure, relayout_data)
    return figure, helpers.make_poses_message(poses)

Make hexapod graph colors and sizes customizable

• floor color
• paper color
• body outline color
• body mesh color
• support polygon color
• cog color
• leg color
• legends paper color
• cog size
• head size
• joint sizes
• line sizes - hexapod polygon
• line sizes - hexapod legs

Add Inverse Kinematics page

Checklist of todos for features to implement in the IK solver

Notes:

• limit beta and gamma ranges
• Limit alpha to range between -90 to 90
• When all left side or right side is above ground, make this an impossible pose.
• Name the updated points of the updated hexapod their correct names, right now they're names is None

Wrong behavior in IK page

This is bug when RECOMPUTE_HEXAPOD = True in settings.py

The issue can be replicated by moving
percent.z slider or percent.y slider

Experiment with different user interfaces for pose control

Based on experience,
it is better if you can write the value you want directly
rather than finding where exactly in the slider is that value.

Add docstrings for public packages etc

Public Packages

hexapod/
widgets/
pages/
tests/

Some public methods

hexapod/ik_solver/ik_solver2.py
- init 

hexapod/linkage.py
- init
- str
- repr

hexapod/points.py
- init
- repr
- str
- eq

hexapod/models.py
- for VirtualHexapod
- for Hexagon

See also: https://www.python.org/dev/peps/pep-0257/

Fix README's Incorrect list-item indent and Misaligned table fence

See: Codacy report