urdfeus 1.2.2__tar.gz → 1.2.4__tar.gz

{urdfeus-1.2.2/urdfeus.egg-info → urdfeus-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urdfeus
-Version: 1.2.2
+Version: 1.2.4
 Summary: URDF converter for Euslisp
 Author-email: Iori Yanokura <yanokura@jsk.imi.i.u-tokyo.ac.jp>
 License: Copyright (c) 2023 Iori Yanokura.
@@ -59,15 +59,33 @@ URDF ⇄ EusLisp を相互変換するPythonライブラリ
 
 ## ブラウザで変換する（インストール不要）
 
-手元のURDFをその場でEusLispに変換できます → **<https://iory.github.io/urdfeus/convert/>**
+手元のモデルをその場で相互変換できます → **<https://iory.github.io/urdfeus/convert/>**
 
-`urdf2eus`がWebAssembly（Pyodide）として動くため、Pythonの環境構築が要りません。変換はすべてブラウザ内で完結するので、**ファイルはどこにもアップロードされません**。
+`urdfeus`がWebAssembly（Pyodide）として動くため、Pythonの環境構築が要りません。変換はすべてブラウザ内で完結するので、**ファイルはどこにもアップロードされません**。
+
+### URDF → EusLisp
 
 URDFをドラッグ&ドロップすると必要なメッシュが一覧表示されるので、「Select files」か「Select directory」でメッシュを渡してください。ファイル名を手がかりに`package://`のパスへ自動で突き合わせるので、メッシュの入ったフォルダごと指定して構いません。URDFとメッシュが同じフォルダにあるなら、フォルダごとドロップするだけで済みます。
 
+### EusLisp → URDF
+
+`.l`をドロップすると、その場でURDFパッケージに変換し**3Dで表示**します。関節はスライダで動かせ、`package.xml` + `urdf/` + `meshes/`一式をzipでダウンロードできます。生成モデル（`euscollada`/`urdfeus`のロボット、jskeusの物体モデル）は幾何情報をファイル内に持っているので、メッシュを別途渡す必要はありません。
+
+**GitHubのURLを貼るだけでも変換できます。** ファイルページのURL（`https://github.com/<owner>/<repo>/blob/<ref>/<path>.l`）を貼ると`raw.githubusercontent.com`に読み替えて取得します。リンクをドロップしても同じです。
+
+`?url=`を付ければ、開いた時点で取得と変換まで走ります（URLはパーセントエンコードしてください）。モデルをそのまま共有できます：
+
+```
+https://iory.github.io/urdfeus/convert/?url=https%3A%2F%2Fgithub.com%2Fowner%2Frepo%2Fblob%2Fmain%2Frobot.l
+```
+
+取得はブラウザからの直接アクセスなので、CORSを許可しているホストに限られます（GitHubのrawは許可しています）。それ以外のURLは失敗するので、ファイルを落としてドロップしてください。
+
+`irteusgl`はネイティブプログラムなのでブラウザでは動きません。代わりに`.l`を直接読む[静的パーサ](#eus2urdfのバックエンド)を使います。コードでリンクを組み立てるモデルや、他ファイルを`load`するシーンはこの経路では読めないので、[インストール](#インストール)した`eus2urdf`（irteusgl経由）を使ってください。
+
 初回のみPython実行環境（約33MB）を取得するため数秒かかります。2回目以降はブラウザのキャッシュが効きます。
 
-ブラウザ版で使えない機能が2つあります。`eus2urdf`（EusLisp → URDF）はEusLisp処理系（`irteusgl`）の起動が必要なため動きません。`--voxel-size`によるメッシュ簡素化もopen3dに依存するため使えません。どちらも[インストール](#インストール)した`urdfeus`を使ってください。
+`--voxel-size`によるメッシュ簡素化はopen3dに依存するため、ブラウザでは使えません。
 
 ## 概要
 
@@ -207,7 +225,7 @@ with open('robot.l', 'w') as f:
 
 ### 前提
 
-- `irteusgl`（jskeus）がインストールされていること
+- `irteusgl`（jskeus）がインストールされていること（無い場合は後述の静的パーサが使われます）
 - メッシュ書き出しに`trimesh` / `pycollada`（依存に含まれます）
 
 ### コマンドライン
@@ -250,12 +268,66 @@ urdf_path = eus2urdf('robot.l', 'output_package_dir',
 - `--mesh-format`: `trimesh.export`が扱う拡張子（既定`glb`）。`glb`/`ply`/`obj`は面ごとの色を保持。`dae`はtrimeshのColladaエクスポータが色をtextureに潰すため**多色メッシュがグレーになる**（単色メッシュは保持）。`stl`は色なし
 - `--draco`: glbメッシュをDraco圧縮（`KHR_draco_mesh_compression`）。頂点色を保ったまま密なメッシュを概ね1桁小さくする。`glb`固定で`DracoPy`が必要（`pip install urdfeus[draco]`）。読み込み側のglTFローダにはDracoデコーダが要る
 - `--irteusgl`: 使用する`irteusgl`実行ファイル
+- `--backend`: モデルの読み方（後述）
+
+#### 慣性テンソルの扱い
+
+EusLispの`:weight`と`:inertia-tensor`はそのままURDFの`<mass>`と`<inertia>`にします（`g`→`kg`、`g*mm^2`→`kg*m^2`）。ただしjskeusのモデルには、質量を持ちながら慣性テンソルが剛体として成立していないものがあります。
+
+- h3 / h3s / h4 / h6 / h7 / igoid2 / igoid3 / saizo: `:inertia-tensor`がゼロ行列
+- macra: 1e-40 相当の placeholder（数値誤差で固有値が負になるものもある）
+- human: 長軸まわりだけ`1.0`（他の2軸は`2.07e8`、単位は`g*mm^2`）
+
+質量があって慣性が無い剛体は存在しないので、こういうリンクを渡されたインポータは、そのボディを拒否するか、質量から作った既定テンソルを黙って代入します。後者はロボットと何の関係もない値です。そこでurdfeusは、テンソルが正定値でない、主慣性モーメントが三角不等式を満たさない、メッシュの大きさと質量に対して小さすぎる、のいずれかなら、**そのリンクのメッシュから一様密度で慣性を計算し直します**。質量と重心は宣言された値のままです。
+
+書き換えたリンクは変換時に一覧で警告し、URDFにも理由をコメントで残します。
+
+```xml
+<link name="root">
+  <!-- inertia recomputed by urdfeus: all-zero inertia tensor -->
+  <inertial>
+```
+
+メッシュが無くて計算もできないリンクは、成立しないテンソルを書く代わりに`<inertial>`自体を出力しません（これも警告します）。
+
+#### eus2urdfのバックエンド
+
+モデルを読む経路は2つあります。
+
+| `--backend` | 読み方 | 対応範囲 |
+| --- | --- | --- |
+| `irteusgl` | `irteusgl`でモデルを実体化してダンプ | どんなモデルでも読める。EusLispのインストールが必要 |
+| `static` | `.l`ファイルを直接パースする（`urdfeus.eus_parse`） | 生成モデル限定。EusLispは不要 |
+| `auto`（既定） | `irteusgl`がPATHにあればそちら、無ければ`static` | |
+
+`static`が読めるのは**生成された**モデルです。`euscollada`/`urdfeus`がURDF・colladaから吐いたロボット（`gl::glvertices`で幾何を持つもの）と、jskeusの物体モデル（`faceset`で幾何を持つもの）が該当します。手書きでリンクを計算するモデルや、他ファイルを`load`するシーン（`*-scene.l`）は読めず、その旨のエラーになります（黙って一部だけ変換することはありません）。
+
+`static`は`:assoc`や`:newcoords`といったEusLispの座標系の意味論を再現しており、jskeusの全モデル651個で`irteusgl`のダンプと突き合わせて検証しています（641個が完全一致、2個は下限が正のジョイントに関する差でURDFとしては等価、8個はシーンで対象外）。
+
+```bash
+# EusLispが入っていない環境でも変換できる
+eus2urdf robot.l out --backend static
+```
+
+```python
+from urdfeus.eus_parse import parse_eus_model
+
+data = parse_eus_model('robot.l')   # irteusgl不要。dumpと同じ辞書が返る
+```
 
 #### ジオメトリの扱い
 
 - colladaボディは`glvertices`から、`make-cube`等で生成されたプレーンなbody（例：`:init`で追加される可視化用の脚キューブや吸盤）は各faceを三角形分割してメッシュ化します。いずれもメッシュとして書き出されます。
 - プレーンbodyのface三角形分割は凸面を仮定します（プリミティブ形状では成立）。
 
+#### 往復（eus -> URDF -> eus）の検証
+
+`tests/urdfeus_tests/test_roundtrip.py`が、モデルをEusLispからURDFへ、URDFからEusLispへ戻し、両端の`irteusgl`ダンプを突き合わせます。単位や規約のずれは片道だけ見ると妥当に見えてしまうので、戻してから比べます（`g*mm^2`と`kg*m^2`の1e9、度とラジアン、mmとm、軸の符号）。
+
+`dump-robot`は全関節をゼロにしてからダンプするため、比較対象はゼロ姿勢での運動学パラメータ一式（リンク姿勢・関節軸・種類・可動範囲）です。これが一致すれば他の姿勢の順運動学も一致するので、関節角をランダムに振るテストは置いていません。
+
+往復で変わることを許しているのは2点だけです。名前は`:torso-waist-y`が`torso_waist_y`にサニタイズされるので、`eus2urdf`と同じ対応表で突き合わせます。そして剛体として成立しない慣性テンソルを持つリンクは、計算し直されたテンソルで戻ってきます（URDF内のコメントが付いているリンクを慣性の比較から外しています）。
+
 ### 生成されたEusLispファイルの使用
 
 ```lisp

{urdfeus-1.2.2 → urdfeus-1.2.4}/README.md

@@ -12,15 +12,33 @@ URDF ⇄ EusLisp を相互変換するPythonライブラリ
 
 ## ブラウザで変換する（インストール不要）
 
-手元のURDFをその場でEusLispに変換できます → **<https://iory.github.io/urdfeus/convert/>**
+手元のモデルをその場で相互変換できます → **<https://iory.github.io/urdfeus/convert/>**
 
-`urdf2eus`がWebAssembly（Pyodide）として動くため、Pythonの環境構築が要りません。変換はすべてブラウザ内で完結するので、**ファイルはどこにもアップロードされません**。
+`urdfeus`がWebAssembly（Pyodide）として動くため、Pythonの環境構築が要りません。変換はすべてブラウザ内で完結するので、**ファイルはどこにもアップロードされません**。
+
+### URDF → EusLisp
 
 URDFをドラッグ&ドロップすると必要なメッシュが一覧表示されるので、「Select files」か「Select directory」でメッシュを渡してください。ファイル名を手がかりに`package://`のパスへ自動で突き合わせるので、メッシュの入ったフォルダごと指定して構いません。URDFとメッシュが同じフォルダにあるなら、フォルダごとドロップするだけで済みます。
 
+### EusLisp → URDF
+
+`.l`をドロップすると、その場でURDFパッケージに変換し**3Dで表示**します。関節はスライダで動かせ、`package.xml` + `urdf/` + `meshes/`一式をzipでダウンロードできます。生成モデル（`euscollada`/`urdfeus`のロボット、jskeusの物体モデル）は幾何情報をファイル内に持っているので、メッシュを別途渡す必要はありません。
+
+**GitHubのURLを貼るだけでも変換できます。** ファイルページのURL（`https://github.com/<owner>/<repo>/blob/<ref>/<path>.l`）を貼ると`raw.githubusercontent.com`に読み替えて取得します。リンクをドロップしても同じです。
+
+`?url=`を付ければ、開いた時点で取得と変換まで走ります（URLはパーセントエンコードしてください）。モデルをそのまま共有できます：
+
+```
+https://iory.github.io/urdfeus/convert/?url=https%3A%2F%2Fgithub.com%2Fowner%2Frepo%2Fblob%2Fmain%2Frobot.l
+```
+
+取得はブラウザからの直接アクセスなので、CORSを許可しているホストに限られます（GitHubのrawは許可しています）。それ以外のURLは失敗するので、ファイルを落としてドロップしてください。
+
+`irteusgl`はネイティブプログラムなのでブラウザでは動きません。代わりに`.l`を直接読む[静的パーサ](#eus2urdfのバックエンド)を使います。コードでリンクを組み立てるモデルや、他ファイルを`load`するシーンはこの経路では読めないので、[インストール](#インストール)した`eus2urdf`（irteusgl経由）を使ってください。
+
 初回のみPython実行環境（約33MB）を取得するため数秒かかります。2回目以降はブラウザのキャッシュが効きます。
 
-ブラウザ版で使えない機能が2つあります。`eus2urdf`（EusLisp → URDF）はEusLisp処理系（`irteusgl`）の起動が必要なため動きません。`--voxel-size`によるメッシュ簡素化もopen3dに依存するため使えません。どちらも[インストール](#インストール)した`urdfeus`を使ってください。
+`--voxel-size`によるメッシュ簡素化はopen3dに依存するため、ブラウザでは使えません。
 
 ## 概要
 
@@ -160,7 +178,7 @@ with open('robot.l', 'w') as f:
 
 ### 前提
 
-- `irteusgl`（jskeus）がインストールされていること
+- `irteusgl`（jskeus）がインストールされていること（無い場合は後述の静的パーサが使われます）
 - メッシュ書き出しに`trimesh` / `pycollada`（依存に含まれます）
 
 ### コマンドライン
@@ -203,12 +221,66 @@ urdf_path = eus2urdf('robot.l', 'output_package_dir',
 - `--mesh-format`: `trimesh.export`が扱う拡張子（既定`glb`）。`glb`/`ply`/`obj`は面ごとの色を保持。`dae`はtrimeshのColladaエクスポータが色をtextureに潰すため**多色メッシュがグレーになる**（単色メッシュは保持）。`stl`は色なし
 - `--draco`: glbメッシュをDraco圧縮（`KHR_draco_mesh_compression`）。頂点色を保ったまま密なメッシュを概ね1桁小さくする。`glb`固定で`DracoPy`が必要（`pip install urdfeus[draco]`）。読み込み側のglTFローダにはDracoデコーダが要る
 - `--irteusgl`: 使用する`irteusgl`実行ファイル
+- `--backend`: モデルの読み方（後述）
+
+#### 慣性テンソルの扱い
+
+EusLispの`:weight`と`:inertia-tensor`はそのままURDFの`<mass>`と`<inertia>`にします（`g`→`kg`、`g*mm^2`→`kg*m^2`）。ただしjskeusのモデルには、質量を持ちながら慣性テンソルが剛体として成立していないものがあります。
+
+- h3 / h3s / h4 / h6 / h7 / igoid2 / igoid3 / saizo: `:inertia-tensor`がゼロ行列
+- macra: 1e-40 相当の placeholder（数値誤差で固有値が負になるものもある）
+- human: 長軸まわりだけ`1.0`（他の2軸は`2.07e8`、単位は`g*mm^2`）
+
+質量があって慣性が無い剛体は存在しないので、こういうリンクを渡されたインポータは、そのボディを拒否するか、質量から作った既定テンソルを黙って代入します。後者はロボットと何の関係もない値です。そこでurdfeusは、テンソルが正定値でない、主慣性モーメントが三角不等式を満たさない、メッシュの大きさと質量に対して小さすぎる、のいずれかなら、**そのリンクのメッシュから一様密度で慣性を計算し直します**。質量と重心は宣言された値のままです。
+
+書き換えたリンクは変換時に一覧で警告し、URDFにも理由をコメントで残します。
+
+```xml
+<link name="root">
+  <!-- inertia recomputed by urdfeus: all-zero inertia tensor -->
+  <inertial>
+```
+
+メッシュが無くて計算もできないリンクは、成立しないテンソルを書く代わりに`<inertial>`自体を出力しません（これも警告します）。
+
+#### eus2urdfのバックエンド
+
+モデルを読む経路は2つあります。
+
+| `--backend` | 読み方 | 対応範囲 |
+| --- | --- | --- |
+| `irteusgl` | `irteusgl`でモデルを実体化してダンプ | どんなモデルでも読める。EusLispのインストールが必要 |
+| `static` | `.l`ファイルを直接パースする（`urdfeus.eus_parse`） | 生成モデル限定。EusLispは不要 |
+| `auto`（既定） | `irteusgl`がPATHにあればそちら、無ければ`static` | |
+
+`static`が読めるのは**生成された**モデルです。`euscollada`/`urdfeus`がURDF・colladaから吐いたロボット（`gl::glvertices`で幾何を持つもの）と、jskeusの物体モデル（`faceset`で幾何を持つもの）が該当します。手書きでリンクを計算するモデルや、他ファイルを`load`するシーン（`*-scene.l`）は読めず、その旨のエラーになります（黙って一部だけ変換することはありません）。
+
+`static`は`:assoc`や`:newcoords`といったEusLispの座標系の意味論を再現しており、jskeusの全モデル651個で`irteusgl`のダンプと突き合わせて検証しています（641個が完全一致、2個は下限が正のジョイントに関する差でURDFとしては等価、8個はシーンで対象外）。
+
+```bash
+# EusLispが入っていない環境でも変換できる
+eus2urdf robot.l out --backend static
+```
+
+```python
+from urdfeus.eus_parse import parse_eus_model
+
+data = parse_eus_model('robot.l')   # irteusgl不要。dumpと同じ辞書が返る
+```
 
 #### ジオメトリの扱い
 
 - colladaボディは`glvertices`から、`make-cube`等で生成されたプレーンなbody（例：`:init`で追加される可視化用の脚キューブや吸盤）は各faceを三角形分割してメッシュ化します。いずれもメッシュとして書き出されます。
 - プレーンbodyのface三角形分割は凸面を仮定します（プリミティブ形状では成立）。
 
+#### 往復（eus -> URDF -> eus）の検証
+
+`tests/urdfeus_tests/test_roundtrip.py`が、モデルをEusLispからURDFへ、URDFからEusLispへ戻し、両端の`irteusgl`ダンプを突き合わせます。単位や規約のずれは片道だけ見ると妥当に見えてしまうので、戻してから比べます（`g*mm^2`と`kg*m^2`の1e9、度とラジアン、mmとm、軸の符号）。
+
+`dump-robot`は全関節をゼロにしてからダンプするため、比較対象はゼロ姿勢での運動学パラメータ一式（リンク姿勢・関節軸・種類・可動範囲）です。これが一致すれば他の姿勢の順運動学も一致するので、関節角をランダムに振るテストは置いていません。
+
+往復で変わることを許しているのは2点だけです。名前は`:torso-waist-y`が`torso_waist_y`にサニタイズされるので、`eus2urdf`と同じ対応表で突き合わせます。そして剛体として成立しない慣性テンソルを持つリンクは、計算し直されたテンソルで戻ってきます（URDF内のコメントが付いているリンクを慣性の比較から外しています）。
+
 ### 生成されたEusLispファイルの使用
 
 ```lisp

{urdfeus-1.2.2 → urdfeus-1.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "urdfeus"
-version = "1.2.2"
+version = "1.2.4"
 description = "URDF converter for Euslisp"
 requires-python = ">=3.10"
 dependencies = [

{urdfeus-1.2.2 → urdfeus-1.2.4}/urdfeus/apps/eus2urdf.py

@@ -42,6 +42,14 @@ def main():
     parser.add_argument(
         "--irteusgl", type=str, default="irteusgl",
         help="irteusgl executable to use.")
+    parser.add_argument(
+        "--backend", choices=("auto", "static", "irteusgl"), default="auto",
+        help="How to read the model. 'irteusgl' instantiates it in EusLisp, "
+        + "which handles any model but needs EusLisp installed. 'static' "
+        + "parses the .l file directly, which needs no EusLisp but only "
+        + "understands generated models (euscollada/urdfeus robots and "
+        + "jskeus objects; not scenes). 'auto' (default) uses irteusgl when "
+        + "it is on PATH and parses the file otherwise.")
     add_diagnostic_arguments(parser)
     args = parser.parse_args()
     if handle_doctor(args, parser, ['input_euslisp_path', 'output_dir']):
@@ -56,6 +64,7 @@ def main():
         mesh_format=args.mesh_format,
         draco=args.draco,
         irteusgl=args.irteusgl,
+        backend=args.backend,
     )
     print(f"Wrote URDF: {urdf_path}")
 

{urdfeus-1.2.2 → urdfeus-1.2.4}/urdfeus/eus2urdf.py

@@ -19,6 +19,7 @@ import json
 import os
 import os.path as osp
 import re
+import shutil
 import subprocess
 import tempfile
 import xml.etree.ElementTree as ET
@@ -142,6 +143,53 @@ def dump_eus_model(eus_path, constructor=None, irteusgl="irteusgl", timeout=600)
     return data
 
 
+def load_eus_model(eus_path, constructor=None, irteusgl="irteusgl",
+                   backend="auto", timeout=600):
+    """Return the dump of an EusLisp model, via irteusgl or by parsing it.
+
+    Parameters
+    ----------
+    eus_path : str
+        Path to the ``.l`` model file.
+    constructor : str or None
+        Constructor function (or class) name. Defaults to the file stem.
+    irteusgl : str
+        irteusgl executable, used by the ``irteusgl`` and ``auto`` backends.
+    backend : str
+        ``irteusgl`` instantiates the model in EusLisp, which handles any
+        model but needs EusLisp installed. ``static`` reads the file with
+        :func:`urdfeus.eus_parse.parse_eus_model`, which needs nothing but
+        only understands generated models. ``auto`` (the default) uses
+        irteusgl when it is on PATH and falls back to the static parser.
+    timeout : float
+        irteusgl subprocess timeout in seconds.
+
+    Returns
+    -------
+    dict
+        The dump described by ``euslisp/eus2urdf-dump.l``.
+    """
+    if backend not in ("auto", "static", "irteusgl"):
+        raise ValueError(
+            "backend must be 'auto', 'static' or 'irteusgl', not "
+            + repr(backend))
+    if backend == "static" or (
+            backend == "auto" and shutil.which(irteusgl) is None):
+        from urdfeus.eus_parse import EusParseError
+        from urdfeus.eus_parse import parse_eus_model
+        try:
+            return parse_eus_model(eus_path, constructor=constructor)
+        except EusParseError as e:
+            if backend == "static":
+                raise
+            raise RuntimeError(
+                f"'{irteusgl}' is not on PATH and {eus_path} cannot be read "
+                + "without it: " + str(e)
+                + "\nInstall EusLisp (jskeus) to convert this model.")
+    return dump_eus_model(eus_path, constructor=constructor,
+                          irteusgl=irteusgl, timeout=timeout)
+
+
 def _mat3(rows):
     return np.array(rows, dtype=np.float64).reshape(3, 3)
 
@@ -348,6 +396,17 @@ def _classify_joint(joint, is_follower):
     linear = "linear" in jtype
     is_master = bool(joint["mimic"])
     min_v, max_v = joint["min"], joint["max"]
+
+    # A multi-DOF joint (6dof, sphere) keeps its limits as float-vectors, which
+    # the dump writes as null because they are not numbers. There is no 1-DOF
+    # URDF joint to map such a joint onto: a free one is URDF's "floating", and
+    # anything else -- including the immovable 6dof joint urdf2eus leaves at a
+    # model's root -- is honestly just a fixed connection.
+    if min_v is None or max_v is None:
+        if joint["movable"] and "6dof" in jtype:
+            return "floating"
+        return "fixed"
+
     inf = abs(min_v) >= _INF_LIMIT or abs(max_v) >= _INF_LIMIT
 
     # Fixed joints are emitted by urdf2eus as rotational-joints with 0/0
@@ -363,28 +422,169 @@ def _classify_joint(joint, is_follower):
     return "revolute"
 
 
-def _add_inertial(link_el, link):
+#: Each principal moment is compared against ``mass * radius ** 2`` of the
+#: link's own mesh, and anything below this fraction of that is a placeholder
+#: rather than a mass distribution. A rod a thousand times longer than it is
+#: thick, slender past anything a robot link is, still keeps its smallest
+#: moment an order of magnitude above this; macra-robot declares ~1e-40 and
+#: human-robot a single 1.0 g*mm^2 next to two moments of 2.07e8 g*mm^2, both
+#: of which are several orders below it.
+_INERTIA_FLOOR_FRACTION = 1e-7
+
+
+def _inertia_defect(inertia, mass, mesh):
+    """Return why ``inertia`` cannot be a rigid body's tensor, else None.
+
+    A usable tensor is positive definite and its principal moments obey the
+    triangle inequality. Several EusLisp models declare ``:inertia-tensor`` as
+    a zero matrix (h3/h3s/h4/h6/h7, igoid2/igoid3, saizo) or placeholders
+    (macra) while still declaring a non-zero ``:weight``. Mass without inertia
+    is not a rigid body, so an importer handed it either refuses the body or
+    silently substitutes a preset tensor that has nothing to do with the
+    robot - both of which are worse than saying so here.
+
+    Parameters
+    ----------
+    inertia : numpy.ndarray or None
+        Candidate tensor in kg*m^2, or None when the link carries no
+        ``:inertia-tensor`` at all.
+    mass : float
+        Link mass in kg.
+    mesh : trimesh.Trimesh or None
+        The link's mesh in link-local metres. Used only for a length scale, so
+        the magnitude check is skipped when the link has no mesh.
+
+    Returns
+    -------
+    str or None
+        A one-line reason, or None when the tensor is usable as it stands.
+    """
+    if inertia is None:
+        return "no :inertia-tensor in the EusLisp model"
+    if not np.all(np.isfinite(inertia)):
+        return "inertia tensor holds a non-finite component"
+    if not np.any(inertia):
+        return "all-zero inertia tensor"
+    # Symmetric by construction (EusLisp stores the full 3x3), so the cheaper
+    # symmetric eigensolver is the right one and returns ascending moments.
+    moments = np.linalg.eigvalsh(0.5 * (inertia + inertia.T))
+    if moments[0] <= 0.0:
+        return ("inertia tensor is not positive definite (smallest principal"
+                + f" moment {moments[0]:.3g})")
+    small, mid, large = moments
+    if small + mid < large * (1.0 - 1e-9):
+        return ("principal moments violate the triangle inequality"
+                + f" ({small:.3g} + {mid:.3g} < {large:.3g})")
+    if mesh is not None:
+        radius = 0.5 * float(np.linalg.norm(mesh.bounding_box.extents))
+        floor = _INERTIA_FLOOR_FRACTION * mass * radius ** 2
+        if small < floor:
+            return (f"smallest principal moment {small:.3g} kg*m^2 is too"
+                    + f" small for {mass:.3g} kg spread over"
+                    + f" {2 * radius:.3g} m")
+    return None
+
+
+def _inertia_from_mesh(mesh, mass):
+    """Inertia tensor of ``mesh`` at the uniform density that gives ``mass``.
+
+    The tensor is taken about the mesh's own centre of mass and in link-local
+    axes, which is the frame URDF's ``<inertia>`` is read in. Uniform density
+    is a guess, but it is a guess derived from the link's actual shape, unlike
+    the mass-scaled presets importers substitute when inertia is missing.
+
+    Parameters
+    ----------
+    mesh : trimesh.Trimesh
+        The link's mesh in link-local metres.
+    mass : float
+        Link mass in kg, taken from the EusLisp ``:weight``.
+
+    Returns
+    -------
+    tuple of (numpy.ndarray, str) or None
+        The 3x3 tensor in kg*m^2 and the geometry it came from, or None when
+        the mesh encloses no usable volume.
+
+    Notes
+    -----
+    glvertices meshes are rarely watertight (they are render geometry, often
+    open shells), and the divergence-theorem volume integral trimesh uses is
+    only defined on a closed surface. So the raw mesh is used when it is
+    watertight and its convex hull, which is closed by construction, when it
+    is not.
+    """
+    if mesh.is_watertight and mesh.volume > 0.0:
+        body, source = mesh.copy(), "mesh"
+    else:
+        body, source = mesh.convex_hull.copy(), "convex hull of the mesh"
+    if not body.is_watertight or body.volume <= 0.0:
+        return None
+    # density, not mass, is what trimesh scales the integral by; mass/volume
+    # makes the resulting tensor match the declared mass exactly.
+    body.density = mass / body.volume
+    inertia = np.asarray(body.moment_inertia, dtype=np.float64)
+    inertia = 0.5 * (inertia + inertia.T)
+    if not np.all(np.isfinite(inertia)) or np.linalg.eigvalsh(inertia)[0] <= 0:
+        return None
+    return inertia, source
+
+
+def _add_inertial(link_el, link, mesh=None):
+    """Write ``<inertial>`` for one link, repairing an unusable tensor.
+
+    Parameters
+    ----------
+    link_el : xml.etree.ElementTree.Element
+        The ``<link>`` element to append to.
+    link : dict
+        One entry of the dump's ``links``, in EusLisp units (g, mm, g*mm^2).
+    mesh : trimesh.Trimesh or None
+        The link's mesh in link-local metres, used to recompute the tensor
+        when the declared one cannot be used.
+
+    Returns
+    -------
+    str or None
+        A note naming the link and what was wrong, for the caller to report,
+        or None when the declared inertia was written unchanged.
+    """
     weight = link["weight"]
     if weight is None or weight <= 0.0:
-        return
+        return None
+    mass = weight / 1000.0  # g -> kg
+    it = link["inertia"]
+    inertia = (_mat3(it) / 1e9) if it is not None else None  # g*mm^2 -> kg*m^2
+
+    note = None
+    defect = _inertia_defect(inertia, mass, mesh)
+    if defect is not None:
+        computed = _inertia_from_mesh(mesh, mass) if mesh is not None else None
+        if computed is None:
+            # Writing mass with no usable inertia is what breaks importers, and
+            # there is nothing here to compute one from, so the link is left
+            # without <inertial> rather than with an impossible one.
+            return (f"{link['name']}: {defect}, and no mesh to compute one"
+                    + " from, so no <inertial> was written")
+        inertia, source = computed
+        note = (f"{link['name']}: {defect}; recomputed from the {source}"
+                + " at uniform density")
+        link_el.append(ET.Comment(
+            f" inertia recomputed by urdfeus: {defect} "))
+
     inertial = ET.SubElement(link_el, "inertial")
     centroid = link["centroid"]
     xyz = (np.array(centroid) / meter2millimeter) if centroid is not None \
         else np.zeros(3)
     ET.SubElement(inertial, "origin", xyz=_fmt_vec(xyz), rpy="0 0 0")
-    ET.SubElement(inertial, "mass", value=f"{weight / 1000.0:.8g}")  # g -> kg
-    it = link["inertia"]
-    if it is not None:
-        # g*mm^2 -> kg*m^2
-        i = _mat3(it) / 1e9
-        ET.SubElement(
-            inertial, "inertia",
-            ixx=f"{i[0, 0]:.8g}", ixy=f"{i[0, 1]:.8g}", ixz=f"{i[0, 2]:.8g}",
-            iyy=f"{i[1, 1]:.8g}", iyz=f"{i[1, 2]:.8g}", izz=f"{i[2, 2]:.8g}",
-        )
-    else:
-        ET.SubElement(inertial, "inertia",
-                      ixx="0", ixy="0", ixz="0", iyy="0", iyz="0", izz="0")
+    ET.SubElement(inertial, "mass", value=f"{mass:.8g}")
+    i = inertia
+    ET.SubElement(
+        inertial, "inertia",
+        ixx=f"{i[0, 0]:.8g}", ixy=f"{i[0, 1]:.8g}", ixz=f"{i[0, 2]:.8g}",
+        iyy=f"{i[1, 1]:.8g}", iyz=f"{i[1, 2]:.8g}", izz=f"{i[2, 2]:.8g}",
+    )
+    return note
 
 
 def _package_xml(package_name):
@@ -433,6 +633,7 @@ def eus2urdf(
     mesh_format="glb",
     draco=False,
     irteusgl="irteusgl",
+    backend="auto",
 ):
     """Convert an EusLisp model to a URDF ROS package.
 
@@ -463,13 +664,17 @@ def eus2urdf(
         to read the result.
     irteusgl : str
         irteusgl executable.
+    backend : str
+        How to read the model: ``irteusgl``, ``static`` (parse the file, no
+        EusLisp needed) or ``auto``. See :func:`load_eus_model`.
 
     Returns
     -------
     str
         Path to the written ``.urdf`` file.
     """
-    data = dump_eus_model(eus_path, constructor=constructor, irteusgl=irteusgl)
+    data = load_eus_model(eus_path, constructor=constructor,
+                          irteusgl=irteusgl, backend=backend)
     return eus2urdf_from_data(
         data,
         output_dir,
@@ -567,13 +772,18 @@ def eus2urdf_from_data(
 
     # Links (+ meshes).
     used_fnames = set()
+    inertia_notes = []
     for link in data["links"]:
         name = link["name"]
         link_el = ET.SubElement(robot_el, "link", name=link_names[name])
-        _add_inertial(link_el, link)
 
+        # The mesh is built before <inertial> because it is what an unusable
+        # declared inertia tensor is recomputed from.
         pos, rot = link_pose[name]
         mesh = _build_link_mesh(link, pos, rot)
+        note = _add_inertial(link_el, link, mesh)
+        if note is not None:
+            inertia_notes.append(note)
         if mesh is not None:
             # _safe_name can collapse distinct link names to the same stem;
             # disambiguate so meshes never overwrite each other.
@@ -595,6 +805,12 @@ def eus2urdf_from_data(
                 geom = ET.SubElement(el, "geometry")
                 ET.SubElement(geom, "mesh", filename=uri)
 
+    if inertia_notes:
+        print(f"Warning: {len(inertia_notes)} link(s) declare a mass the"
+              + " EusLisp inertia tensor cannot go with:")
+        for note in inertia_notes:
+            print(f"  {note}")
+
     # Joints. ``joint_unames`` already gives each joint a unique sanitized name
     # (handling both invalid characters and models that reuse a name across
     # parts, e.g. a hand reusing :j10/:j11 on every finger).
@@ -679,6 +895,12 @@ def movable_joint_spec(data):
         if not joint["movable"]:
             continue
         jtype = _classify_joint(joint, joint["name"] in follower)
+        if jtype not in ("revolute", "continuous", "prismatic"):
+            # A multi-DOF joint carries a vector, which no single scale factor
+            # describes and no URDF joint here can be driven by. EusLisp's
+            # eus2urdf-movable-joints leaves the same ones out, which is what
+            # keeps the two lists index-aligned.
+            continue
         scale = (1.0 / meter2millimeter) if jtype == "prismatic" \
             else float(np.pi / 180.0)
         spec.append((joint_unames[i], scale))