| Name | garm JSON |
| Version |
0.3.3
JSON |
| download |
| home_page | |
| Summary | Library to generate 3D animation (glTF,USD) files from robot model in URDF |
| upload_time | 2023-10-04 13:48:21 |
| maintainer | |
| docs_url | None |
| author | Masanobu Koga |
| requires_python | >=3.8 |
| license | |
| keywords |
urdf
ros
robot
gltf
usd
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Garm (Generator of Animated Robot Model)
Garm is a library which transforms a robot model in [URDF][URDF],
which is the file format of robot in [ROS][ROS],
into various 3D file formats with animation.
# Features
- converting robot model in [URDF][URDF] to 3D file formats [glTF][glTF] and [USD][USD].
- generating 3D animation files of robot in [glTF][glTF] and [USD][USD] from robot model in [URDF][URDF].
- converting robot model in [URDF][URDF] to other robot model.
- generating a template of [garm file](#GarmFile) from robot model in [URDF][URDF].
# Installation
Garm can be installed from [PyPI][PyPI] using `pip`:
pip install garm
# Example Usage
## converting URDF to 3D files formats and vice versa.
### converting urdf to other formats
Here is an example on how to convert robot model in [URDF][URDF] to 3D file formats.
from garm import garm
garm.convert('robot.urdf', 'robot.glb')
garm.convert('robot.urdf', 'robot.gltf')
garm.convert('robot.urdf', 'robot.usdz')
garm.convert('robot.urdf', 'robot.usda')
### converting other formats to urdf.
Here is an example on how to convert 3D file formats to robot model in [URDF][URDF].
from garm import garm
garm.convert('robot.glb', 'robot.urdf')
garm.convert('robot.gltf', 'robot.urdf')
## generating 3D animation files of robot
Here is an example on how to generate 3D animation files of robot from robot model in [URDF][URDF].
We give a [garm file](#GarmFile) in [YAML][YAML] format, which is described below, as the third parameter to the function `convert`.
from garm import garm
garm.convert('robot.urdf', 'robot.glb', 'robot.garm')
garm.convert('robot.urdf', 'robot.gltf', 'robot.garm')
garm.convert('robot.urdf', 'robot.usdz', 'robot.garm')
garm.convert('robot.urdf', 'robot.usda', 'robot.garm')
## converting urdf to other robot model and vice versa.
Here is an example on how to convert robot model in [URDF][URDF] to other robot model.
from garm import garm
garm.convert('robot.urdf', 'robot.mk3d')
garm.convert('robot.urdf', 'robot.rdtf')
garm.convert('robot.urdf', 'robot.usdr')
### converting other robot model to urdf
Here is an example on how to convert other robot model to robot model in [URDF][URDF].
from garm import garm
garm.convert('robot.mk3d', 'robot.urdf')
garm.convert('robot.rdtf', 'robot.urdf')
garm.convert('robot.usdr', 'robot.urdf')
<a id="GarmFile"></a>
# Garm file
Garm file is written in [YAML][YAML] format.
## Parameter of garm file
| Name | Function | Possible values |
| ---------------- | ----------------- | ----------------------- |
| version | number of version | number |
| asset (optional) | asset | [*asset*](#asset) |
| sources | a set of source | [*source*](#source) |
| behaviors | a set of behavior | [*behavior*](#behavior) |
### Example
version: 0.3
asset:
...............
sources:
...............
behaviors:
...............
<a id="asset"></a>
## *asset*
### Parameter of *asset*
| Name | Function | Possible values |
| ----------- | ----------- | ---------------- |
| title | title | character string |
| copyright | copyright | character string |
| year | year | number |
| license | license | character string |
| generator | generator | character string |
| attribution | attribution | character string |
### Example of *asset*
asset:
title: "Single Pendulum"
copyright: "Copyright (C) 2023 MKLab.org (Koga Laboratory)"
year: 2023
license: "CC BY 4.0"
<a id="source"></a>
## *source*
### Parameter of *source*
| Name | Function | Possible values |
| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| name | name of source | character string started with a alphanumeric character |
| url | filename, url of data | filename or URL (*csv*, *txt*, *mat*) |
| numbers (optional) | column numbers of data to be loaded | a list of column number separated by `,` and surrounded by `[` and `]` |
| timeShift (optional) | shift the time so that the initial time is 0 if true | *true* or *false* |
| timeScale (optional) | scale of time (default value is 1) | real number |
### Example of *source*
sources:
- name: "s1"
url: "Simulation.mat"
- name: "s2"
url: "joint_states.csv"
numbers: "[1, 7, 8]"
timeShift: "true"
timeScale: "1.0E-9"
<a id="behavior"></a>
## *behavior*
### Parameter of *behavior*
| Name | Function | Possible values |
| ------- | ----------------- | ----------------------------------------- |
| name | name | character string started with a alphanumeric character |
| actions | a set of action | [*action*](#action) |
<a id="action"></a>
### Parameter of *action*
| Name | Function | Possible values |
| --------- | -------------------- | ------------------------------------------------------ |
| name | name | character string started with a alphanumeric character |
| timeRange | time range of action | startingTime and endingTime separated by `:` |
| time | time of action | [*source*](#source) variables or time variable `t` |
| motions | a set of motion | [*motion*](#motion) |
<a id="motion"></a>
### Parameter of *motion*
| Name | Function | Possible values |
| -------| ---------------------| --------------------------------- |
| target | joint to be moved | id (name) of joint in robot model |
| type | type of motion | *translation* or *rotation* |
| value | variation of joint | `"[dx, dy, dz]"` |
An element of *value* in [*motion*](#motion) is a mathematical expression with [*source*](#source) variables and time variable `t`, where `s(2)` means the second element of the source data with name of "s". The mathematical expression can include the operations, such as '+', '-', '*', and '/', and many fundamental function, such as 'sin', 'cos', and 'exp'.
### Example of *behavior*
behaviors:
- name: "simulation"
actions:
- name: action1
timeRange: 0:12
time: s1(1)
motions:
- target: pendulum
type: rotation
value: "[s1(3), 0, 0]"
- target: cart
type: translation
value: "[0, s1(2), 0]"
- name: "experiment"
actions:
- name: "action1"
time: "s2(1)"
motions:
- target: "base.joint"
type: "translation"
value: "[0, s2(2), 0]"
- target: "cart.joint"
type: "rotation"
value: "[s2(3), 0, 0]"
# Generating a template of garm file
It is tedious work to write a [garm file](#GarmFile) from scratch.
We can generate a template of garm file from robot model and
modify a part of the file to complete.
### generating a template of garm file from robot model.
Here is an example on how to generate a template of garm file from robot model.
from garm import garm
garm.convert('robot.urdf', 'robot_urdf.garm')
garm.convert('robot.mk3d', 'robot_mk3d.garm')
# Dependencies
Garm depends on the following Java libraries.
[GraalVM](https://www.graalvm.org/) was used to build shared libraries, which is called from python program, from Java libraries.
## [MK-LAB](https://www.mk.ces.kyutech.ac.jp/) libraries
- [jmatx](https://jmatx.mklab.org/index.html)
- [mikity3D](https://mikity3d.mk.ces.kyutech.ac.jp/)
- nfc
- [wheels](https://wheels.mklab.org/)
## Other libraries
- [jackson](https://github.com/FasterXML/jackson) (Apache License Version 2.0)
- [simple-xml](https://sourceforge.net/projects/simple/) (Apache License Version 2.0)
- [snakeyaml](https://github.com/snakeyaml/snakeyaml) (Apache License Version 2.0)
# License
Garm is licensed under [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
# Author
Garm was written by Masanobu Koga (<koga@ices.kyutech.ac.jp>) in 2022.
[glTF]:https://www.khronos.org/gltf/
[PyPI]:https://pypi.org/
[ROS]:https://wiki.ros.org/
[URDF]:http://wiki.ros.org/urdf
[USD]:https://openusd.org/release/index.html
[YAML]:https://yaml.org/
Raw data
{
"_id": null,
"home_page": "",
"name": "garm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "URDF,ROS,robot,glTF,USD",
"author": "Masanobu Koga",
"author_email": "Masanobu Koga <koga@ics.kyutech.ac.jp>",
"download_url": "https://files.pythonhosted.org/packages/b0/04/bd2fdec4f597e62c677515c0b67bc69e1561162eee855b48450acb89700b/garm-0.3.3.tar.gz",
"platform": null,
"description": "# Garm (Generator of Animated Robot Model)\r\n\r\nGarm is a library which transforms a robot model in [URDF][URDF],\r\nwhich is the file format of robot in [ROS][ROS], \r\ninto various 3D file formats with animation.\r\n\r\n# Features\r\n\r\n- converting robot model in [URDF][URDF] to 3D file formats [glTF][glTF] and [USD][USD].\r\n- generating 3D animation files of robot in [glTF][glTF] and [USD][USD] from robot model in [URDF][URDF].\r\n- converting robot model in [URDF][URDF] to other robot model.\r\n- generating a template of [garm file](#GarmFile) from robot model in [URDF][URDF].\r\n\r\n# Installation\r\n\r\nGarm can be installed from [PyPI][PyPI] using `pip`:\r\n\r\n pip install garm\r\n\r\n# Example Usage\r\n\r\n## converting URDF to 3D files formats and vice versa.\r\n\r\n### converting urdf to other formats\r\n\r\nHere is an example on how to convert robot model in [URDF][URDF] to 3D file formats.\r\n\r\n from garm import garm\r\n garm.convert('robot.urdf', 'robot.glb')\r\n garm.convert('robot.urdf', 'robot.gltf')\r\n garm.convert('robot.urdf', 'robot.usdz')\r\n garm.convert('robot.urdf', 'robot.usda')\r\n\r\n### converting other formats to urdf.\r\n\r\nHere is an example on how to convert 3D file formats to robot model in [URDF][URDF].\r\n\r\n from garm import garm\r\n garm.convert('robot.glb', 'robot.urdf')\r\n garm.convert('robot.gltf', 'robot.urdf')\r\n\r\n## generating 3D animation files of robot\r\n\r\nHere is an example on how to generate 3D animation files of robot from robot model in [URDF][URDF].\r\nWe give a [garm file](#GarmFile) in [YAML][YAML] format, which is described below, as the third parameter to the function `convert`.\r\n\r\n from garm import garm\r\n garm.convert('robot.urdf', 'robot.glb', 'robot.garm')\r\n garm.convert('robot.urdf', 'robot.gltf', 'robot.garm')\r\n garm.convert('robot.urdf', 'robot.usdz', 'robot.garm')\r\n garm.convert('robot.urdf', 'robot.usda', 'robot.garm')\r\n\r\n## converting urdf to other robot model and vice versa.\r\n\r\nHere is an example on how to convert robot model in [URDF][URDF] to other robot model.\r\n\r\n from garm import garm\r\n garm.convert('robot.urdf', 'robot.mk3d')\r\n garm.convert('robot.urdf', 'robot.rdtf')\r\n garm.convert('robot.urdf', 'robot.usdr')\r\n\r\n### converting other robot model to urdf\r\n\r\nHere is an example on how to convert other robot model to robot model in [URDF][URDF].\r\n\r\n from garm import garm\r\n garm.convert('robot.mk3d', 'robot.urdf')\r\n garm.convert('robot.rdtf', 'robot.urdf')\r\n garm.convert('robot.usdr', 'robot.urdf')\r\n\r\n<a id=\"GarmFile\"></a>\r\n# Garm file\r\n\r\nGarm file is written in [YAML][YAML] format.\r\n\r\n## Parameter of garm file\r\n\r\n| Name | Function | Possible values |\r\n| ---------------- | ----------------- | ----------------------- |\r\n| version | number of version | number |\r\n| asset (optional) | asset | [*asset*](#asset) |\r\n| sources | a set of source | [*source*](#source) |\r\n| behaviors | a set of behavior | [*behavior*](#behavior) |\r\n\r\n### Example\r\n\r\n version: 0.3\r\n asset:\r\n ...............\r\n sources:\r\n ...............\r\n behaviors:\r\n ...............\r\n\r\n<a id=\"asset\"></a>\r\n## *asset*\r\n\r\n### Parameter of *asset*\r\n\r\n| Name | Function | Possible values |\r\n| ----------- | ----------- | ---------------- |\r\n| title | title | character string |\r\n| copyright | copyright | character string |\r\n| year | year | number |\r\n| license | license | character string |\r\n| generator | generator | character string |\r\n| attribution | attribution | character string |\r\n\r\n### Example of *asset*\r\n\r\n asset:\r\n title: \"Single Pendulum\"\r\n copyright: \"Copyright (C) 2023 MKLab.org (Koga Laboratory)\"\r\n year: 2023\r\n license: \"CC BY 4.0\"\r\n\r\n<a id=\"source\"></a>\r\n## *source*\r\n\r\n### Parameter of *source*\r\n\r\n| Name | Function | Possible values |\r\n| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |\r\n| name | name of source | character string started with a alphanumeric character |\r\n| url | filename, url of data | filename or URL (*csv*, *txt*, *mat*) |\r\n| numbers (optional) | column numbers of data to be loaded | a list of column number separated by `,` and surrounded by `[` and `]` |\r\n| timeShift (optional) | shift the time so that the initial time is 0 if true | *true* or *false* |\r\n| timeScale (optional) | scale of time (default value is 1) | real number |\r\n\r\n### Example of *source*\r\n\r\n sources:\r\n - name: \"s1\"\r\n url: \"Simulation.mat\"\r\n - name: \"s2\"\r\n url: \"joint_states.csv\"\r\n numbers: \"[1, 7, 8]\"\r\n timeShift: \"true\"\r\n timeScale: \"1.0E-9\" \r\n\r\n<a id=\"behavior\"></a>\r\n## *behavior*\r\n\r\n### Parameter of *behavior*\r\n\r\n| Name | Function | Possible values |\r\n| ------- | ----------------- | ----------------------------------------- |\r\n| name | name | character string started with a alphanumeric character |\r\n| actions | a set of action | [*action*](#action) |\r\n\r\n<a id=\"action\"></a>\r\n### Parameter of *action*\r\n\r\n| Name | Function | Possible values |\r\n| --------- | -------------------- | ------------------------------------------------------ |\r\n| name | name | character string started with a alphanumeric character |\r\n| timeRange | time range of action | startingTime and endingTime separated by `:` |\r\n| time | time of action | [*source*](#source) variables or time variable `t` |\r\n| motions | a set of motion | [*motion*](#motion) |\r\n\r\n<a id=\"motion\"></a>\r\n### Parameter of *motion*\r\n\r\n| Name | Function | Possible values |\r\n| -------| ---------------------| --------------------------------- |\r\n| target | joint to be moved | id (name) of joint in robot model |\r\n| type | type of motion | *translation* or *rotation* |\r\n| value | variation of joint | `\"[dx, dy, dz]\"` |\r\n\r\nAn element of *value* in [*motion*](#motion) is a mathematical expression with [*source*](#source) variables and time variable `t`, where `s(2)` means the second element of the source data with name of \"s\". The mathematical expression can include the operations, such as '+', '-', '*', and '/', and many fundamental function, such as 'sin', 'cos', and 'exp'.\r\n\r\n### Example of *behavior*\r\n\r\n behaviors:\r\n - name: \"simulation\"\r\n actions:\r\n - name: action1\r\n timeRange: 0:12\r\n time: s1(1)\r\n motions:\r\n - target: pendulum\r\n type: rotation\r\n value: \"[s1(3), 0, 0]\"\r\n - target: cart\r\n type: translation\r\n value: \"[0, s1(2), 0]\"\r\n - name: \"experiment\"\r\n actions:\r\n - name: \"action1\"\r\n time: \"s2(1)\"\r\n motions:\r\n - target: \"base.joint\"\r\n type: \"translation\"\r\n value: \"[0, s2(2), 0]\"\r\n - target: \"cart.joint\"\r\n type: \"rotation\"\r\n value: \"[s2(3), 0, 0]\"\r\n\r\n# Generating a template of garm file\r\n\r\nIt is tedious work to write a [garm file](#GarmFile) from scratch.\r\nWe can generate a template of garm file from robot model and\r\nmodify a part of the file to complete.\r\n\r\n### generating a template of garm file from robot model.\r\n\r\nHere is an example on how to generate a template of garm file from robot model.\r\n\r\n from garm import garm\r\n garm.convert('robot.urdf', 'robot_urdf.garm')\r\n garm.convert('robot.mk3d', 'robot_mk3d.garm')\r\n\r\n# Dependencies\r\n\r\nGarm depends on the following Java libraries.\r\n[GraalVM](https://www.graalvm.org/) was used to build shared libraries, which is called from python program, from Java libraries.\r\n\r\n## [MK-LAB](https://www.mk.ces.kyutech.ac.jp/) libraries\r\n\r\n- [jmatx](https://jmatx.mklab.org/index.html)\r\n- [mikity3D](https://mikity3d.mk.ces.kyutech.ac.jp/)\r\n- nfc\r\n- [wheels](https://wheels.mklab.org/)\r\n\r\n## Other libraries\r\n\r\n- [jackson](https://github.com/FasterXML/jackson) (Apache License Version 2.0)\r\n- [simple-xml](https://sourceforge.net/projects/simple/) (Apache License Version 2.0)\r\n- [snakeyaml](https://github.com/snakeyaml/snakeyaml) (Apache License Version 2.0)\r\n\r\n# License\r\n\r\nGarm is licensed under [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\r\n\r\n# Author\r\n\r\nGarm was written by Masanobu Koga (<koga@ices.kyutech.ac.jp>) in 2022.\r\n\r\n[glTF]:https://www.khronos.org/gltf/\r\n[PyPI]:https://pypi.org/\r\n[ROS]:https://wiki.ros.org/ \r\n[URDF]:http://wiki.ros.org/urdf\r\n[USD]:https://openusd.org/release/index.html\r\n[YAML]:https://yaml.org/\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Library to generate 3D animation (glTF,USD) files from robot model in URDF",
"version": "0.3.3",
"project_urls": null,
"split_keywords": [
"urdf",
"ros",
"robot",
"gltf",
"usd"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3bd3ba949cc6491170246cc111aa0b203d2d802f68031b227b6e53f34128e39",
"md5": "5fb31219b9332700636488c11c15ad7b",
"sha256": "ff12c73be4b81bd87bb19e1aa8b392816746c09f34420c4ae7d022efe9d9a7f1"
},
"downloads": -1,
"filename": "garm-0.3.3-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "5fb31219b9332700636488c11c15ad7b",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 32948052,
"upload_time": "2023-10-04T13:47:12",
"upload_time_iso_8601": "2023-10-04T13:47:12.005553Z",
"url": "https://files.pythonhosted.org/packages/b3/bd/3ba949cc6491170246cc111aa0b203d2d802f68031b227b6e53f34128e39/garm-0.3.3-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b004bd2fdec4f597e62c677515c0b67bc69e1561162eee855b48450acb89700b",
"md5": "ceb76d5ea177a54a358c91fc24952f34",
"sha256": "d2cedd9a2540ecb20e1aef4b3515b7fd28365a2940ff9823de218cd82bf656d6"
},
"downloads": -1,
"filename": "garm-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "ceb76d5ea177a54a358c91fc24952f34",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32747011,
"upload_time": "2023-10-04T13:48:21",
"upload_time_iso_8601": "2023-10-04T13:48:21.868891Z",
"url": "https://files.pythonhosted.org/packages/b0/04/bd2fdec4f597e62c677515c0b67bc69e1561162eee855b48450acb89700b/garm-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-04 13:48:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "garm"
}
