[REVIEW]: TriP: A Python package for the kinematic modeling of serial-parallel hybrid robots

[whedon]

Submitting author: @liquidcronos (Jan Baumgärtner)
Repository: https://github.com/TriPed-Robot/TriP
Branch with paper.md (empty if default branch): paper
Version: v1.0.3
Editor: @danielskatz
Reviewers: @SeungBack, @bmagyar
Archive: 10.5281/zenodo.6360087

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/03c967bcda198bac6af1ef6342507c3f"><img src="https://joss.theoj.org/papers/03c967bcda198bac6af1ef6342507c3f/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/03c967bcda198bac6af1ef6342507c3f/status.svg)](https://joss.theoj.org/papers/03c967bcda198bac6af1ef6342507c3f)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@SeungBack & @bmagyar, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @danielskatz know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @SeungBack

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@liquidcronos) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of Need' that clearly states what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @bmagyar

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@liquidcronos) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of Need' that clearly states what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @SeungBack, @bmagyar it looks like you're currently assigned to review this paper 🎉.

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.06 s (540.6 files/s, 69444.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          15            409            532           1146
XML                              1              0              2            792
reStructuredText                 4            219            174            305
Markdown                         5             43              0             98
YAML                             3             17             18             78
make                             1              4              6             10
SVG                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                            30            692            732           2430
-------------------------------------------------------------------------------


Statistical information for the repository '3c8e1b429fe35986dea22c43' was
gathered on 2021/12/01.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Jan Baumgärnter                 17           359            215            1.48
Jan Baumgärtner                102         17383           2868           52.37
Torben Miller                   80          2635          15208           46.14

Below are the number of rows from each author that have survived and are still
intact in the current revision:

Author                     Rows      Stability          Age       % in comments
Jan Baumgärnter            1791          498.9          2.1                7.09
Jan Baumgärtner             162            0.9          0.0               54.32
Torben Miller               134            5.1          6.3                7.46

[whedon]

PDF failed to compile for issue #3967 with the following error:

 Can't find any papers to compile :-(

[danielskatz]

@whedon generate pdf from branch paper

[whedon]

Attempting PDF compilation from custom branch paper. Reticulating splines etc...

[danielskatz]

@whedon check references from branch paper

[whedon]

Attempting to check references... from custom branch paper

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1016/j.mechatronics.2020.102367 is OK
- 10.1007/s12532-018-0139-4 is OK
- 10.1109/TMECH.2006.871087 is OK
- 10.1016/j.mechmachtheory.2008.03.002 is OK
- 10.1016/j.rcim.2012.09.016 is OK
- 10.1109/MRA.2011.2181749 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[danielskatz]

👋 @SeungBack and @bmagyar - Thanks for agreeing to review this submission.
This is the review thread for the paper. All of our communications will happen here from now on.

Both reviewers have checklists at the top of this thread with the JOSS requirements. As you go over the submission, please check any items that you feel have been satisfied. There are also links to the JOSS reviewer guidelines.

Please read the first couple of comments in this issue carefully, so that you can accept the invitation from JOSS and be able to check items, and so that you don't get overwhelmed with notifications from other activities in JOSS.

The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention openjournals/joss-reviews#3967 so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package.

We aim for reviews to be completed within about 2-4 weeks. Please let me know if either of you require some more time. We can also use Whedon (our bot) to set automatic reminders if you know you'll be away for a known period of time.

Please feel free to ping me (@danielskatz) if you have any questions/concerns.

[whedon]

👋 @bmagyar, please update us on how your review is going (this is an automated reminder).

[whedon]

👋 @SeungBack, please update us on how your review is going (this is an automated reminder).

[danielskatz]

HI @bmagyar and @SeungBack - I've been on vacation, and continue to be for another week, but also want to check on the status of this review. I'll check again on the 10th when I'm back at work.

[SeungBack]

I reviewed the paper and documentation, and here are the comments. I am reviewing the codes and will add detailed comments about the codes soon.

This paper introduces an easy-to-use Python package for computing the forward and inverse kinematics of robots. The author claims that previous libraries lack support for hybrid serial-parallel systems, and TirP can be used to model both parallel and serial mechanisms. Solving Inverse and forward kinematics is an essential component for robotics, and I think this library can be useful for those who want to easily model the kinematics of complex robots.

Major issues

• There are other libraries that support computing the F.K and I.K of robots, such as ikpy and Klampt, but the paper compares TriP with Openrave, MoveIt, and Matlab. It would be better to describe the strength of this library by comparing it to other libraries in terms of functionality and speed.
• For the easy modeling of chain models, support of URDF import/export and 2D/3D visualization is necessary. Is there a plan to support this? 

Minor issues

• I think the summary section does not summarize the paper, rather, it introduces the overall background.
• In the tutorial, some code references are broken and refer to the wrong lines of code
• Examples do not include the codes for importing packages. Please add this information (e.g. import trip_kinematics, from math import radians)
• Documentation includes only TriPed robots, and I think adding an example for popular serial mechanisms (e.g., Panda, UR5) would be helpful.
• The names of the pip package name (trip-kinematics) and paper title (TriP) do not match, and thus please consider adding an installation section on readthedocs.
• The colors of Figures 1 and 3 in the paper are confusing, and it would be better to use contrastive colors.
• typos in Figure 2. (e.g., ,,Spherical Joint", [,tz'])

[liquidcronos]

Hi @SeungBack Thanks for your valuable feedback!
I am not sure If I should immediately respond or wait for the second reviewer, So I hope that it is alright to address the Issues:

There are other libraries that support computing the F.K and I.K of robots, such as ikpy and Klampt, but the paper compares TriP with Openrave, MoveIt, and Matlab. It would be better to describe the strength of this library by comparing it to other libraries in terms of functionality and speed.

You are correct we do not mention other python kinematic libraries.
This was an oversight, ultimately the libraries you mentioned suffer from the same shortcomings as the other ones namely lacking support for serial mechanisms or hybrid serial parallel mechanisms.
I will add them shortly.

For the easy modeling of chain models, support of URDF import/export and 2D/3D visualization is necessary. Is there a plan to support this?

We completely agree that visualization is very important in practice.
For this reason we are working on adding visualizations for a future release of the library.

While URDF is a standard format for robot descriptions, it is unfortunately rather basic and lacks support for the hybrid mechanisms TriP aims to model.
Since it is still sufficient to describe the virtual open chain of a mechanism we are currently working on URDF support which we will hopefully finish next month.

I think the summary section does not summarize the paper, rather, it introduces the overall background.

You are right. To be honest I was a bit confused by the required content of this section since many other papers seem to include the background in order to describe the purpose of the software for a 'diverse, non-specialist audience'.
Would you rather I shorten the overview or write more about TriP itself?

In the tutorial, some code references are broken and refer to the wrong lines of code

Examples do not include the codes for importing packages. Please add this information (e.g. import trip_kinematics, from math import radians)

Thanks for letting me know, should be fixed now :)

Documentation includes only TriPed robots, and I think adding an example for popular serial mechanisms (e.g., Panda, UR5) would be helpful.

Ideally we want more examples of hybrid serial parallel robots to better showcase TriPs performance as you can see here.
Popular examples of such hybrid systems are the Kuka KR 40 PA or the fanuc-m410ic.
The main reason we have not included these systems so far is that we want to independently verify that we have correctly implemented the models.
Since we are the only library supporting hybrid mechanisms calculating reference values is very difficult.
For this reason we have currently included the excavator robots as toy examples while we slowly add more examples.
If you want we can prioritize the development of these robot models to get them out sooner.

The names of the pip package name (trip-kinematics) and paper title (TriP) do not match, and thus please consider adding an installation section on readthedocs.

Good point, we will add a getting started section including the installation instructions of the README.md.

The colors of Figures 1 and 3 in the paper are confusing, and it would be better to use contrastive colors.

Are you referring only to the two green colors, or the blue and green color as well?
I will try to change them to be more contrastive.

[danielskatz]

@liquidcronos - it's fine (and even good) for you to respond as issues come up - this will make it easier for the second reviewer. thanks!

[liquidcronos]

@SeungBack I have included IKPy and Klam't in my discussion.
Let me know if this is sufficient or if you want a more detailed comparison

[liquidcronos]

@whedon generate pdf from branch paper

[whedon]

Attempting PDF compilation from custom branch paper. Reticulating splines etc...

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[SeungBack]

Hi @liquidcronos,

I have checked the updated version of the manuscripts, and I am satisfied with the response and the revised manuscript. It is good to hear that TriP will be updated to support URDF and visualization. Here are the additional comments for your response:

1. Would you rather I shorten the overview or write more about TriP itself?

I recommend adding more about TriP itself (e.g., features, structures, and the strength of TriP).

2. Are you referring only to the two green colors, or the blue and green colors as well?

The colors of green and blue links are hard to distinguish for me. 

3. Examples do not include the codes for importing packages. Please add this information (e.g. import trip_kinematics, from math import radians)

Thanks for letting me know, should be fixed now :)

Please let me know after updating the codes so that I can run and review them.

[liquidcronos]

Hey @SeungBack
I have amended the paper with more references to TriPs features.
As promised I have also added a getting started section that explains how the library is installed.
The code examples should now also be self-contained and include all necessary imports.

Are there any other changes you would like to see apart from the figure colors (which I should be able to change until Friday)?

[liquidcronos]

@whedon generate pdf from branch paper

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1016/j.mechatronics.2020.102367 is OK
- 10.1007/s12532-018-0139-4 is OK
- 10.1109/TMECH.2006.871087 is OK
- 10.1016/j.mechmachtheory.2008.03.002 is OK
- 10.1016/j.rcim.2012.09.016 is OK
- 10.1109/MRA.2011.2181749 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[danielskatz]

@editorialbot generate pdf

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[danielskatz]

👋 @liquidcronos - I've suggested a bunch of changes in TriPed-Robot/trip_kinematics#75 If these are ok, please merge them. If not, we can discuss. Then we can move to final acceptance and publication.

[liquidcronos]

Hey @danielskatz the changes are all fine, i have thus accepted the pull request

[danielskatz]

At this point could you:

• Make a tagged release of your software, and list the version tag of the archived version here.
• Archive the reviewed software in Zenodo or a similar service (e.g., figshare, an institutional repository)
• Check the archival deposit (e.g., in Zenodo) has the correct metadata. This includes the title (should match the paper title) and author list (make sure the list is correct and people who only made a small fix are not on it). You may also add the authors' ORCID.
• Please list the DOI of the archived version here.

I can then move forward with accepting the submission.

[liquidcronos]

• I have created a release with the tag v1.0.3 for the Journal Submission.
• I have archived it on Zenode
• I have checked the Metadata.
• The resulting DOI is: 10.5281/zenodo.6360087

[danielskatz]

@liquidcronos - can you please change the metadata of the zenodo archive to have "TriP: A Python package for the kinematic modeling of serial-parallel hybrid robots" as the title? (See "How can I edit the metadata of a published record?" on https://help.zenodo.org)

[danielskatz]

@editorialbot set v1.0.3 as version

[danielskatz]

@editorialbot set 10.5281/zenodo.6360087 as archive

[editorialbot]

Done! version is now v1.0.3

[editorialbot]

Done! Archive is now 10.5281/zenodo.6360087

[liquidcronos]

@danielskatz Should be updated know!
By the way thanks for making me aware of the edit button, Up until know I was changing the .zenodo.json file by hand and drafting a new release each time...

[danielskatz]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1016/j.mechatronics.2020.102367 is OK
- 10.1007/s12532-018-0139-4 is OK
- 10.1109/TMECH.2006.871087 is OK
- 10.1016/j.mechmachtheory.2008.03.002 is OK
- 10.1016/j.rcim.2012.09.016 is OK
- 10.1109/MRA.2011.2181749 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#3064

If the paper PDF and the deposit XML files look good in openjournals/joss-papers#3064, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[danielskatz]

@editorialbot accept

[danielskatz]

Sorry @liquidcronos - GitHub actions, which is how @editorialbot runs, are currently degraded, so this acceptance may take a while. Once this runs, I will verify the published PDF and DOI, then send a message closing this submission.

[editorialbot]

Doing it live! Attempting automated processing of paper acceptance...

[editorialbot]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[editorialbot]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.03967 joss-papers#3065
1. Wait a couple of minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.03967
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[danielskatz]

Congratulations to @liquidcronos (Jan Baumgärtner) and co-author!!

And thanks to @SeungBack and @bmagyar for reviewing!
We couldn't do this without you!

[editorialbot]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.03967/status.svg)](https://doi.org/10.21105/joss.03967)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.03967">
  <img src="https://joss.theoj.org/papers/10.21105/joss.03967/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.03967/status.svg
   :target: https://doi.org/10.21105/joss.03967

This is how it will look in your documentation:

We need your help!

The Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[liquidcronos]

Hey Guys, sorry for the late response, I was on vacation.
I just wanted to quickly thank everyone involved with this paper, although the process took longer than expected I really enjoyed how open and transparent this process was.
Special thanks also to you @danielskatz for being the editor even though you are normally not an editor in the robotics domain.