Update to 0.1.0a1 for release (#48)

Since its a non-compiled project, we don't need a matrix of builds. So we now
- Build on Ubuntu
- Test on Ubuntu (x64 & arm) and Windows
- Deploy to PyPi for tags only

Also updated to usd-exchange 2.2.0

Fixes #41

Author: andrewkaufman

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ permissions:
   pull-requests: write  # Required to comment on PRs
 
 jobs:
-  check-code-format:
+  lint:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -29,15 +29,7 @@ jobs:
         run: uv run --group dev poe lint
 
   build:
-    strategy:
-      matrix:
-        os:
-          [
-            ubuntu-latest,
-            ubuntu-24.04-arm,
-            windows-latest,
-          ]
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -57,7 +49,7 @@ jobs:
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: urdf-usd-converter-dist-${{ matrix.os }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
+          name: urdf-usd-converter-dist-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
           path: dist/
 
   test:
@@ -81,7 +73,7 @@ jobs:
       - name: Download artifacts
         uses: actions/download-artifact@v4
         with:
-          name: urdf-usd-converter-dist-${{ matrix.os }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
+          name: urdf-usd-converter-dist-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
           path: dist/
 
       - name: Run tests
@@ -133,7 +125,7 @@ jobs:
       - name: Download artifacts
         uses: actions/download-artifact@v4
         with:
-          name: urdf-usd-converter-dist-${{ matrix.os }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
+          name: urdf-usd-converter-dist-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || format('{0}', github.ref_name) }}
           path: dist/
 
       - name: Test wheel installation (Linux)
@@ -165,3 +157,24 @@ jobs:
           # Test conversion
           New-Item -ItemType Directory -Force -Path test_outputs
           urdf_usd_converter -h
+
+  deploy:
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+      - test
+      - test-package
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/urdf-usd-converter
+    permissions:
+      id-token: write
+    steps:
+      - name: Download wheel and source tarball
+        uses: actions/download-artifact@v4
+        with:
+          name: urdf-usd-converter-dist-${{ github.ref_name }}
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc

.gitlab/.gitlab-ci.yml

@@ -1 +1,85 @@
-# 0.1.0dev0
+# 0.1.0a1
+
+## Features
+
+- **USD Asset Structure**
+  - Output Assets are completely standalone with no dependencies on the source URDF, OBJ, DAE, or STL files
+  - Atomic Component structure with Asset Interface layer and payloaded contents
+  - Separate geometry, material, and physics content layers for easy asset-reuse across domains
+  - Library-based asset references for meshes and materials to avoid heavy data duplication
+  - Explicit USD stage metadata with units (meters, kilograms) and up-axis (Z)
+- **Link Conversion**
+  - URDF links are converted as `UsdGeom.Xform` prims with `UsdPhysics.RigidBodyAPI` applied
+  - The root link has `UsdPhysics.ArticulationRootAPI` applied to indicate the root of the kinematic tree
+  - Links are nested in USD, reflecting the kinematic hierarchy of the source URDF rather than the XML file structure
+  - Complete mass properties including explicit inertia & center of mass via `UsdPhysics.MassAPI`
+- **Joint Conversion**
+  - Revolute joints as `UsdPhysics.RevoluteJoint` with angular limits
+  - Continuous joints as `UsdPhysics.RevoluteJoint` without limits
+  - Prismatic joints as `UsdPhysics.PrismaticJoint` with linear limits
+  - Fixed joints as `UsdPhysics.FixedJoint`
+  - Planar joints as `UsdPhysics.Joint` with the appropriate `UsdPhysics.LimitAPI` applied to constrain the locked DOFs
+  - Floating joints (bodies are free by default in USD)
+  - All joints have automatic joint frame alignment between Body0 and Body1, accounting for URDF joint axis, position, and orientation.
+  - Joint limits for velocity & effort have no equivalent in `UsdPhysics`, but are authored as custom attributes `urdf:limit:velocity` and `urdf:limit:effort` respectively.
+- **Geometry Conversion**
+  - All visual and collision geometry is converted to USD
+    - Visuals are set with `default` UsdPurpose and colliders with `guide` UsdPurpose
+  - `UsdPhysics.CollisionAPI` is applied to colliders
+  - Meshes as `UsdGeom.Mesh`
+    - Automatic mesh library generation with reference-based asset structure, to avoid duplicate topology
+    - STL files converted to USD using `numpy-stl` and `usd-exchange` with normal processing
+    - OBJ files converted using `tinyobjloader` and `usd-exchange` with UV coordinates and normal mapping
+    - DAE files converted using `pycollada` and `usd-exchange` with UV coordinates, normal mapping, and `UsdGeom.Subset` support
+    - OBJ and DAE files specifying multiple meshes convert as a list of meshes under a common parent prim
+    - `UsdPhysics.MeshCollisionAPI` is applied to mesh colliders with convex hull specified as the approximation preference
+  - Spheres as `UsdGeom.Sphere`
+  - Boxes as `UsdGeom.Cube` with scale transforms
+  - Cylinders as `UsdGeom.Cylinder`
+- **Visual Material and Texture Conversion**
+  - All materials are converted to `UsdShade.Material` graphs using `UsdPreviewSurface` shaders, and encapsulated as instanceable material interfaces
+  - PNG texture support with automatic texture copying and path resolution
+  - URDF materials convert rgba as diffuse color and opacity, with support for diffuse textures
+  - OBJ embedded materials (MTL files) convert diffuse color, specular color, dissolve (opacity), roughness (not shininess), metallic, and ior
+    - diffuse, specular, normal/bump, roughness, metallic, and opacity textures are all supported
+- **Prim Naming**
+  - If URDF/DAE/OBJ names are not valid USD specifiers they are automatically transcoded & made unique & valid
+  - Display name metadata preserves the original source names on the USD Prims
+- **Command Line Interface**
+  - Input is an URDF file and default output is a USD Layer as a structured Atomic Component with an Asset Interface USDA layer
+    - All heavy data is compressed binary data (via USDC layers) while lightweight data is plain text for legibility
+  - Optional comment string embedded into all authored USD Layers
+  - Optional Stage flattening for single-file output
+  - Optionally skip the `UsdPhysics.Scene` (this may be desirable for multi-asset setups)
+  - Error handling with graceful failures
+  - Enable verbose output for debugging (exposes any traceback info)
+- **Python API**
+  - Full programmatic access via `urdf_usd_converter.Converter` class with configurable parameters for all CLI flags
+  - Enables interactive editing of the USD Layers after conversion
+
+# Known Limitations
+
+## USD Data Conversion
+
+- **Joint Conversion**
+  - Calibration has no equivalent in `UsdPhysics` and is omitted
+  - Dynamics has no equivalent in `UsdPhysics` and is omitted
+  - Safety Controller has no equivalent in `UsdPhysics` and is omitted
+  - Mimic has no equivalent in `UsdPhysics` and is omitted
+- **Geometry Conversion**
+  - No other file formats beyond OBJ/DAE/STL are supported
+  - For DAE files, only "TriangleSet", "Triangles", "Polylist", and "Polygons" are supported
+  - For OBJ files, only objects with faces are supported (i.e. no points, lines, or free-form curves/surfaces)
+- **Visual Material and Texture Conversion**
+  - DAE embedded materials are not implemented
+  - Projection shaders for basic geometry primitives (box, cylinder, sphere) are not implemented
+  - More accurate PBR materials (e.g. OpenPBR via UsdMtlx) are not implemented
+- **Other Elements**
+  - Transmission conversion is not implemented
+  - Gazebo conversion is not implemented
+  - Conversion of other out-of-spec URDF extensions are not implemented
+
+## Using the USD Asset in other USD Ecosystem applications
+
+- The USD Asset contains nested rigid bodies within articulations.
+  - Support for nested bodies in UsdPhysics is fairly new (as of USD 25.11), and some existing applications may not support this style of nesting.

.gitlab/CODEOWNERS

@@ -10,7 +10,7 @@ Key Features:
 - Converts an input URDF file into an OpenUSD Layer
 - Supports data conversion of visual geometry & materials, as well as the links, collision geometry, and joints necessary for kinematic simulation.
 - Available as a python module or command line interface (CLI).
-- Creates a standalone, self-contained artifact with no connection to the source URDF, OBJ, or STL data.
+- Creates a standalone, self-contained artifact with no connection to the source URDF, OBJ, DAE, or STL data.
   - Structured as an [Atomic Component](https://docs.omniverse.nvidia.com/usd/latest/learn-openusd/independent/asset-structure-principles.html#atomic-model-structure-flowerpot)
   - Suitable for visualization & rendering in any OpenUSD Ecosystem application.
   - Suitable for import & simulation in [Newton](https://github.com/newton-physics/newton).
@@ -26,6 +26,7 @@ The output asset structure is based on NVIDIA's [Principles of Scalable Asset St
 The implementation also leverages the following dependencies:
 - NVIDIA's [OpenUSD Exchange SDK](https://docs.omniverse.nvidia.com/usd/code-docs/usd-exchange-sdk/latest/index.html) to author consistent & correct USD data.
 - Pixar's OpenUSD python modules & native libraries (vendored via the `usd-exchange` wheel).
+- [tinyobjloader](https://github.com/tinyobjloader/tinyobjloader), [pycollada](https://github.com/pycollada/pycollada), and [numpy-stl](https://numpy-stl.readthedocs.io) for parsing any mesh data referenced by the input URDF datasets.
 
 # Get Started
 
@@ -64,7 +65,9 @@ We recommend starting with [usdview](https://docs.omniverse.nvidia.com/usd/lates
 
 However, you cannot start simulating in usdview, as there is no native simulation engine in this application.
 
-To simulate this asset directly, the best application is ...
+To simulate this asset in Newton, call [newton.ModelBuilder.add_usd()](https://newton-physics.github.io/newton/api/_generated/newton.ModelBuilder.html#newton.ModelBuilder.add_usd) to parse the asset and add it to your Newton model.
+
+Simulating in other UsdPhysics enabled products (e.g. NVIDIA Omniverse, Unreal Engine, etc) may provided mixed results. The rigid bodies are structured hierarchically, which maximal coordinate solvers often do not support. In order to see faithful simulation in these applications, the USD asset will need to be modified to suit the expectations of each target runtime.
 
 # Contribution Guidelines
 

.gitlab/templates.yml

@@ -2,12 +2,12 @@
 name = "urdf-usd-converter"
 dynamic = ["version"]
 description = "A URDF to OpenUSD Data Converter"
-authors = [{name = "NVIDIA"}]
+authors = [{ name = "Newton Developers" }]
 license = {text = "Apache-2.0"}
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
 dependencies = [
-    "usd-exchange>=2.2.0rc2", # locked to USD 25.05
+    "usd-exchange>=2.2.0",
     "numpy-stl>=3.2",
     "tinyobjloader>=2.0.0rc13",
     "pycollada>=0.9.2",

CHANGELOG.md

@@ -1,3 +1,3 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 The Newton Developers
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "0.1.0dev0"
+__version__ = "0.1.0a1"