Setup Converter API and CLI (#22)

ft-lab · web-flow · commit 90ac9a280dc0 · 2025-10-17T10:29:22.000-07:00
diff --git a/tests/data/simple_box.urdf b/tests/data/simple_box.urdf
@@ -0,0 +1,15 @@
+<?xml verison="1.0"?>
+<robot name="simple_box">
+  <material name="blue">
+    <color rgba="0.0 0.0 1.0 1.0"/>
+  </material>
+
+  <link name="link1">
+    <visual>
+      <geometry>
+        <box size="2.0 2.0 2.0"/>
+      </geometry>
+      <material name="blue"/>
+    </visual>
+  </link>
+</robot> 
diff --git a/tests/testCli.py b/tests/testCli.py
@@ -1,10 +1,116 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
+import pathlib
+import shutil
+from unittest.mock import patch
+
+import usdex.test
+from pxr import Tf
 
 from tests.util.ConverterTestCase import ConverterTestCase
+from urdf_usd_converter._impl.cli import run
 
 
 class TestCli(ConverterTestCase):
 
     def test_run(self):
-        pass  # dummy test for now
+        for robot in pathlib.Path("tests/data").glob("*.urdf"):
+            robot_name = robot.stem
+            with patch("sys.argv", ["urdf_usd_converter", str(robot), self.tmpDir()]):
+                self.assertEqual(run(), 0, f"Failed to convert {robot}")
+            self.assertTrue((pathlib.Path(self.tmpDir()) / f"{robot_name}.usda").exists())
+
+    # TODO: test_no_layer_structure, test_no_physics_scene, test_comment
+
+    def test_invalid_input(self):
+        with (
+            patch("sys.argv", ["urdf_usd_converter", "tests/data/invalid.xml", self.tmpDir()]),
+            usdex.test.ScopedDiagnosticChecker(self, [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Input file does not exist.*")]),
+        ):
+            self.assertEqual(run(), 1, "Expected non-zero exit code for invalid input")
+
+    def test_invalid_output(self):
+        # create a file that is not a directory
+        pathlib.Path("tests/output").mkdir(parents=True, exist_ok=True)
+        pathlib.Path("tests/output/invalid").touch()
+        with (
+            patch("sys.argv", ["urdf_usd_converter", "tests/data/simple_box.urdf", "tests/output/invalid"]),
+            usdex.test.ScopedDiagnosticChecker(self, [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Output path exists but is not a directory.*")]),
+        ):
+            self.assertEqual(run(), 1, "Expected non-zero exit code for invalid output")
+
+    def test_input_path_is_directory(self):
+        # Create a directory as input_file (should fail)
+        input_dir = pathlib.Path("tests/data/input_dir")
+        input_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            with (
+                patch("sys.argv", ["urdf_usd_converter", str(input_dir), self.tmpDir()]),
+                usdex.test.ScopedDiagnosticChecker(self, [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Input path is not a file.*")]),
+            ):
+                self.assertEqual(run(), 1, "Expected non-zero exit code for input path as directory")
+        finally:
+            shutil.rmtree(input_dir)
+
+    def test_input_file_not_xml(self):
+        # Create a non-xml file as input_file (should fail)
+        not_xml = pathlib.Path("tests/data/not_xml.txt")
+        not_xml.write_text("dummy content")
+        try:
+            with (
+                patch("sys.argv", ["urdf_usd_converter", str(not_xml), self.tmpDir()]),
+                usdex.test.ScopedDiagnosticChecker(self, [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Only URDF.*are supported as input.*")]),
+            ):
+                self.assertEqual(run(), 1, "Expected non-zero exit code for non-xml input file")
+        finally:
+            not_xml.unlink()
+
+    def test_output_dir_cannot_create(self):
+        # Simulate output_dir.mkdir raising an exception (should fail)
+        robot = "tests/data/simple_box.urdf"
+        output_dir = pathlib.Path("tests/output/cannot_create")
+        with (
+            patch("pathlib.Path.mkdir", side_effect=OSError("Permission denied")),
+            patch("sys.argv", ["urdf_usd_converter", robot, str(output_dir)]),
+            usdex.test.ScopedDiagnosticChecker(self, [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Failed to create output directory.*")]),
+        ):
+            self.assertEqual(run(), 1, "Expected non-zero exit code when output dir cannot be created")
+
+    def test_conversion_returns_none(self):
+        # Test the case where converter.convert() returns None/false value
+        robot = "tests/data/simple_box.urdf"
+        with (
+            patch("urdf_usd_converter.Converter.convert", return_value=None),
+            patch("sys.argv", ["urdf_usd_converter", robot, self.tmpDir()]),
+            usdex.test.ScopedDiagnosticChecker(
+                self,
+                [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Conversion failed for unknown reason.*")],
+                level=usdex.core.DiagnosticsLevel.eWarning,
+            ),
+        ):
+            self.assertEqual(run(), 1, "Expected non-zero exit code when conversion returns None")
+
+    def test_conversion_exception_non_verbose(self):
+        # Test exception handling when verbose=False (should not re-raise)
+        robot = "tests/data/simple_box.urdf"
+        with (
+            patch("urdf_usd_converter.Converter.convert", side_effect=RuntimeError("Test conversion error")),
+            patch("sys.argv", ["urdf_usd_converter", robot, self.tmpDir()]),
+            usdex.test.ScopedDiagnosticChecker(
+                self,
+                [(Tf.TF_DIAGNOSTIC_WARNING_TYPE, "Conversion failed: Test conversion error.*")],
+                level=usdex.core.DiagnosticsLevel.eWarning,
+            ),
+        ):
+            self.assertEqual(run(), 1, "Expected non-zero exit code when conversion raises exception")
+
+    def test_conversion_exception_verbose(self):
+        # Test exception handling when verbose=True (should re-raise)
+        robot = "tests/data/simple_box.urdf"
+        with (
+            patch("urdf_usd_converter.Converter.convert", side_effect=RuntimeError("Test conversion error")),
+            patch("sys.argv", ["urdf_usd_converter", robot, self.tmpDir(), "--verbose"]),
+            self.assertRaises(RuntimeError),
+            usdex.test.ScopedDiagnosticChecker(self, [], level=usdex.core.DiagnosticsLevel.eWarning),
+        ):
+            run()
diff --git a/tests/testConverter.py b/tests/testConverter.py
@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+import pathlib
+
+from tests.util.ConverterTestCase import ConverterTestCase
+from urdf_usd_converter._impl.convert import Converter
+
+
+class TestConverter(ConverterTestCase):
+    def test_invalid_input(self):
+        # input_path is a path that does not exist (should fail).
+        input_path = "tests/data/non_existent.urdf"
+        output_dir = self.tmpDir()
+
+        converter = Converter()
+        with self.assertRaisesRegex(ValueError, r".*Input file tests/data/non_existent.urdf is not a readable file.*"):
+            converter.convert(input_path, output_dir)
+
+    def test_output_path_is_file(self):
+        # Specify a file instead of a directory (should fail).
+        input_path = "tests/data/simple_box.urdf"
+        output_dir = "tests/data/simple_box.urdf"
+
+        converter = Converter()
+        with self.assertRaisesRegex(ValueError, r".*Output directory tests/data/simple_box.urdf is not a directory.*"):
+            converter.convert(input_path, output_dir)
+
+    def test_output_directory_does_not_exist(self):
+        # If the output directory does not exist.
+        input_path = "tests/data/simple_box.urdf"
+        output_dir = str(pathlib.Path(self.tmpDir()) / "non_existent_directory")
+
+        converter = Converter()
+        asset_path = converter.convert(input_path, output_dir)
+        self.assertIsNotNone(asset_path)
+        self.assertTrue(pathlib.Path(asset_path.path).exists())
diff --git a/urdf_usd_converter/__init__.py b/urdf_usd_converter/__init__.py
@@ -1,5 +1,6 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
+from ._impl.convert import Converter
 from ._version import __version__
 
-__all__ = ["__version__"]
+__all__ = ["Converter", "__version__"]
diff --git a/urdf_usd_converter/__main__.py b/urdf_usd_converter/__main__.py
@@ -2,10 +2,6 @@
 # SPDX-License-Identifier: Apache-2.0
 import sys
 
-
-def run() -> int:
-    print("Not implemented yet")
-    return 0
-
+from ._impl.cli import run
 
 sys.exit(run())
diff --git a/urdf_usd_converter/_impl/cli.py b/urdf_usd_converter/_impl/cli.py
@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+import argparse
+from pathlib import Path
+
+import usdex.core
+from pxr import Tf, Usd
+
+from .._version import __version__
+from .convert import Converter
+
+
+def run() -> int:
+    """
+    Main method in the command line interface.
+    """
+    parser = __create_parser()
+    args = parser.parse_args()
+
+    # Argument validation
+    # Check input_file
+    if not args.input_file.exists():
+        Tf.Warn(f"Input file does not exist: {args.input_file}")
+        return 1
+    if not args.input_file.is_file():
+        Tf.Warn(f"Input path is not a file: {args.input_file}")
+        return 1
+    if args.input_file.suffix.lower() != ".urdf":
+        Tf.Warn(f"Only URDF (.urdf) files are supported as input, got: {args.input_file.suffix}")
+        return 1
+    # Check output_dir
+    if args.output_dir.exists() and not args.output_dir.is_dir():
+        Tf.Warn(f"Output path exists but is not a directory: {args.output_dir}")
+        return 1
+    if not args.output_dir.exists():
+        try:
+            args.output_dir.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            Tf.Warn(f"Failed to create output directory: {args.output_dir}, error: {e}")
+            return 1
+
+    usdex.core.activateDiagnosticsDelegate()
+    usdex.core.setDiagnosticsLevel(usdex.core.DiagnosticsLevel.eStatus if args.verbose else usdex.core.DiagnosticsLevel.eWarning)
+    Tf.Status("Running urdf_usd_converter")
+    Tf.Status(f"Version: {__version__}")
+    Tf.Status(f"USD Version: {Usd.GetVersion()}")
+    Tf.Status(f"USDEX Version: {usdex.core.version()}")
+
+    try:
+        converter = Converter(layer_structure=not args.no_layer_structure, scene=not args.no_physics_scene, comment=args.comment)
+        if result := converter.convert(args.input_file, args.output_dir):
+            Tf.Status(f"Created USD Asset: {result.path}")
+            return 0
+        else:
+            Tf.Warn("Conversion failed for unknown reason. Try running with --verbose for more information.")
+            return 1
+    except Exception as e:
+        if args.verbose:
+            raise e
+        else:
+            Tf.Warn(f"Conversion failed: {e}")
+            return 1
+
+
+def __create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Convert URDF files to USD format",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    # Required arguments
+    parser.add_argument(
+        "input_file",
+        type=Path,
+        help="Path to the input URDF file",
+    )
+    parser.add_argument(
+        "output_dir",
+        type=Path,
+        help="""
+        Path to the output USD directory. The primary USD file will be <output_dir>/<robotname>.usda
+        and it will be an Atomic Component with Asset Interface layer and payloaded contents
+        (unless --no-layer-structure is used)
+        """,
+    )
+
+    # Optional arguments
+    # FUTURE: add arg to flatten hierarchy
+    parser.add_argument(
+        "--no-layer-structure",
+        action="store_true",
+        default=False,
+        help="Create a single USDC layer rather than an Atomic Component structure with Asset Interface layer and payloaded contents",
+    )
+    parser.add_argument(
+        "--no-physics-scene",
+        action="store_true",
+        default=False,
+        help="Disable authoring a `UsdPhysics.Scene` prim",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        default=False,
+        help="Enable verbose output",
+    )
+    parser.add_argument(
+        "--comment",
+        "-c",
+        default="",
+        help="Comment to add to the USD file",
+    )
+
+    return parser
diff --git a/urdf_usd_converter/_impl/convert.py b/urdf_usd_converter/_impl/convert.py
@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+import pathlib
+from dataclasses import dataclass
+
+import usdex.core
+from pxr import Sdf, Tf, UsdGeom
+
+from .utils import get_authoring_metadata
+
+__all__ = ["Converter"]
+
+
+class Converter:
+    @dataclass
+    class Params:
+        layer_structure: bool = True
+        scene: bool = True
+        comment: str = ""
+
+    def __init__(self, layer_structure: bool = True, scene: bool = True, comment: str = ""):
+        self.params = self.Params(layer_structure=layer_structure, scene=scene, comment=comment)
+
+    def convert(self, input_file: str, output_dir: str) -> Sdf.AssetPath:
+        """
+        Convert a URDF to a USD stage.
+
+        Args:
+            input_file: Path to the input URDF file.
+            output_dir: Path to the output USD directory.
+
+        Returns:
+            The path to the created USD asset.
+
+        Raises:
+            ValueError: If input_file does not exist or is not a readable file.
+            ValueError: If input_file cannot be parsed as a valid URDF.
+            ValueError: If output_dir exists but is not a directory.
+        """
+        input_path = pathlib.Path(input_file)
+        if not input_path.exists() or not input_path.is_file():
+            raise ValueError(f"Input file {input_file} is not a readable file")
+
+        output_path = pathlib.Path(output_dir)
+        if output_path.exists() and not output_path.is_dir():
+            raise ValueError(f"Output directory {output_dir} is not a directory")
+
+        if not output_path.exists():
+            output_path.mkdir(parents=True)
+
+        file_name = f"{input_path.stem}.usda"
+        asset_identifier = str(output_path / file_name)
+        Tf.Status(f"Converting {input_path} into {output_path}")
+        asset_stage = usdex.core.createStage(
+            asset_identifier,
+            defaultPrimName="Robot",  # TODO: use parsed name
+            upAxis=UsdGeom.Tokens.z,
+            linearUnits=UsdGeom.LinearUnits.meters,
+            authoringMetadata=get_authoring_metadata(),
+        )
+        # TODO: implement core logic
+        usdex.core.saveStage(asset_stage, comment=self.params.comment)
+        return Sdf.AssetPath(asset_identifier)
diff --git a/urdf_usd_converter/_impl/utils.py b/urdf_usd_converter/_impl/utils.py
@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+from .._version import __version__
+
+__all__ = ["get_authoring_metadata"]
+
+
+def get_authoring_metadata() -> str:
+    return f"URDF USD Converter v{__version__}"
