K-Scale's library for programmatically interacting with OnShape
Project description
K-Scale OnShape Library
This library is what we use at K-Scale for interacting with OnShape. It is a wrapper around the OnShape API that allows us to easily import parts from OnShape into our projects.
Getting Started
Install the library using pip:
pip install kscale-onshape-library
pip install 'kscale-onshape-library @ git+https://github.com/kscalelabs/onshape.git@master' # Install from Github
pip install 'kscale-onshape-library[all]' # Install all dependencies
In order to access the OnShape API, you need to define ONSHAPE_ACCESS_KEY
and ONSHAPE_SECRET_KEY
using a key generated here.
Usage
To download and postprocess an assembly, run:
kol run https://cad.onshape.com/documents/DDDDDDDD/w/WWWWWWWW/e/EEEEEEEE
An example run with a config file to download Stompy Mini:
kol run https://cad.onshape.com/documents/50fe60f593f5c98e8f52552c/w/23cfc61ce40dd25ad76f414c/e/9c37b547deaa42ff258901fe -c config_example.json
By default, this will automatically generate both a URDF and MJCF file.
You can visualize the resulting artifacts using MuJoCo Viewer:
python -m mujoco.viewer
For URDF files it's sometimes necessary to first drag the file into the meshes folder before viewing it.
You can also visualize the resulting URDF using PyBullet:
pip install pybullet
kol pybullet robot/<urdf-name>.urdf
Simulation
The output of the onshape library is simply a robot floating in space. Luckily, most simulators which support URDFs are able to define an environment within code. More changes are needed to make MJCF files simulation ready. We have support for adapting MJCF files to isaac sim here: https://github.com/kscalelabs/sim/blob/master/sim/scripts/create_mjcf.py.
It will be useful to create more automatic scripts for adapting raw URDF and MJCF to various simulators. Feel free to contribute! Support for other file formats like USD files for IsaacLab will be helpful as well.
Tips and Suggestions
- To avoid mishaps from occuring due to cached files, if making big changes in a single export, or if the robot has undergone major changes since the last export, it's good to start fresh with a new
/robot/
folder. - There's no guarantee that the robot's starting pose (when all joint positions are set to 0) will be good, or even matching what you see on onshape. It's reccomended to use MuJoCo Viewer to find a good starting position for each joint.
- Robots function much better in simulation when they have less parts. It's very good to make sure that link names are descriptive in onshape so small parts can be better removed using
--skip-small-parts
. This will also make export faster. - When using functions that can be destructive like
simplify-meshes
,merge-joints
, and especiallycleanup-mesh-dir
, it's good to make copies of the STL files elsewhere first.
Development
Since this is a library, it's necessary to upversion after big changes. You can do this by changing the version number in kol/__init__.py
, then running the Github Action to publish a new version.
Please keep this repo well linted! Specifically, it is quite easy to run into errors with mypy since many of the functions and variables have ambiguous types. To check which files have issues locally, run mypy kol
and make static-checks
. Many mypy issues can be alleviated with one of the following:
- Ensure that type annotations properly include
None
when necessary. This is especially important for functions. - Make good use of classes to ensure everything is well typed. See
kol/onshape/schema/assembly.py
. - When using functions such as
dict.find
, use aNone
check to guarantee that variable accesses are safe - Make sure docstrings are descriptive and that there's one for every function, even if it seems trivial. This makes mouseovers and references to those functions much easier elsewhere.
- Save often to make sure that black and ruff don't get confused.
If creating new features, new files that get created that are large/have too many of them should be added to the .gitignore
.
Notes
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for kscale_onshape_library-0.0.31.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f878b1f6579537d9d54e2c3c672d0822a731b8176bb5239a10747c994e29a23d |
|
MD5 | 09b372d0efb189ec0d4df0335a5d7443 |
|
BLAKE2b-256 | 5fe728c63b33c0d160f73f16021acd46c69e71bb95c30079d6a4f7bd130d1014 |
Hashes for kscale_onshape_library-0.0.31-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89aa55394913f3dbcb96c2eb0d1200c0d1f090a00a9ee8c88517847141ddd68d |
|
MD5 | 460a9024ddb1a22975acd538ca482b04 |
|
BLAKE2b-256 | 07686caba8acf3d7be2e2ac7c879ec0fb949b02bcf7242ba5c44451b108baa2a |