garm 0.3.3

Library to generate 3D animation (glTF,USD) files from robot model in URDF

Garm (Generator of Animated Robot Model)

Garm is a library which transforms a robot model in URDF, which is the file format of robot in ROS, into various 3D file formats with animation.

Features

• converting robot model in URDF to 3D file formats glTF and USD.
• generating 3D animation files of robot in glTF and USD from robot model in URDF.
• converting robot model in URDF to other robot model.
• generating a template of garm file from robot model in URDF.

Installation

Garm can be installed from 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 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.

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. We give a garm file in 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 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.

from garm import garm
garm.convert('robot.mk3d', 'robot.urdf')
garm.convert('robot.rdtf', 'robot.urdf')
garm.convert('robot.usdr', 'robot.urdf')

Garm file

Garm file is written in YAML format.

Parameter of garm file

Name	Function	Possible values
version	number of version	number
asset (optional)	asset	asset
sources	a set of source	source
behaviors	a set of behavior	behavior

Example

version: 0.3
asset:
    ...............
sources:
    ...............
behaviors:
    ...............

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"

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"       

behavior

Parameter of behavior

Name	Function	Possible values
name	name	character string started with a alphanumeric character
actions	a set of action	action

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 variables or time variable t
motions	a set of motion	motion

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 is a mathematical expression with 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 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 was used to build shared libraries, which is called from python program, from Java libraries.

MK-LAB libraries

• jmatx
• mikity3D
• nfc
• wheels

Other libraries

• jackson (Apache License Version 2.0)
• simple-xml (Apache License Version 2.0)
• snakeyaml (Apache License Version 2.0)

License

Garm is licensed under Apache License Version 2.0.

Author

Garm was written by Masanobu Koga ([e-mail]) in 2022.