nepher 0.1.0__py3-none-any.whl

nepher/cli/commands/view.py

@@ -0,0 +1,310 @@
+"""View environment command (Isaac Sim integration)."""
+
+import argparse
+import os
+import sys
+from typing import Optional
+import click
+from nepher.loader.registry import load_env, load_scene
+from nepher.cli.utils import print_error, print_info, print_success
+
+original_argv = None
+
+
+def _check_isaaclab_installed():
+    """Check if isaaclab is installed and raise error if not."""
+    try:
+        import isaaclab  # noqa: F401
+    except ImportError:
+        try:
+            import isaacsim  # noqa: F401
+            raise ImportError(
+                "Isaac Lab is not installed. The 'view' command requires Isaac Lab to be installed.\n"
+                "Please install Isaac Lab to use this command. See: https://isaac-sim.github.io/IsaacLab/"
+            )
+        except ImportError:
+            from pathlib import Path
+            script_paths = [
+                Path(__file__).parent.parent.parent / "scripts" / "nepher_view.py",
+                Path("envhub/scripts/nepher_view.py"),
+                Path("scripts/nepher_view.py"),
+            ]
+            script_found = next((p for p in script_paths if p.exists()), None)
+            if script_found:
+                try:
+                    script_found = str(script_found.relative_to(Path.cwd()))
+                except ValueError:
+                    script_found = str(script_found)
+                help_msg = (
+                    "Isaac Lab is not available in the current environment.\n\n"
+                    "The 'view' command must be run through Isaac Lab's Python environment.\n"
+                    f"Please use the script instead:\n\n"
+                    f"  isaaclab.bat -p {script_found} <env_id> --category <category> [--scene <scene>]\n\n"
+                    "Or on Linux/Mac:\n"
+                    f"  ./isaaclab.sh -p {script_found} <env_id> --category <category> [--scene <scene>]\n\n"
+                    "Example:\n"
+                    f"  isaaclab.bat -p {script_found} digital-twin-warehouse-v1 --category navigation --scene small_warehouse"
+                )
+            else:
+                help_msg = (
+                    "Isaac Lab is not available in the current environment.\n\n"
+                    "The 'view' command must be run through Isaac Lab's Python environment.\n"
+                    "Please use the script 'scripts/nepher_view.py' with isaaclab.bat or isaaclab.sh.\n\n"
+                    "Example:\n"
+                    "  isaaclab.bat -p scripts/nepher_view.py <env_id> --category <category> [--scene <scene>]"
+                )
+            raise ImportError(help_msg)
+
+
+def _spawn_usd_scene(scene_cfg, env_cache_path=None):
+    """Spawn a USD scene in Isaac Sim."""
+    import omni.usd
+    from pxr import Gf, UsdGeom
+    from pathlib import Path
+    import isaaclab.sim as sim_utils
+    
+    if not scene_cfg.usd_path:
+        raise ValueError("USD scene config missing usd_path")
+    
+    usd_path = Path(scene_cfg.usd_path)
+    if not usd_path.is_absolute():
+        usd_path = (env_cache_path / usd_path) if env_cache_path else usd_path.resolve()
+    usd_path_str = str(usd_path.resolve())
+    
+    print_info(f"Loading USD scene: {usd_path_str}")
+    stage = omni.usd.get_context().get_stage()
+    
+    if not stage.GetPrimAtPath("/World"):
+        UsdGeom.Xform.Define(stage, "/World")
+    
+    scene_prim_path = "/World/Scene"
+    scene_prim = stage.DefinePrim(scene_prim_path, "Xform")
+    scene_prim.GetReferences().AddReference(usd_path_str)
+    
+    try:
+        children = scene_prim.GetChildren()
+        if children:
+            print_info(f"USD scene reference loaded with {len(children)} top-level prims")
+        elif scene_prim.IsValid():
+            from pxr import Usd
+            for child in Usd.PrimRange(scene_prim):
+                if child != scene_prim:
+                    print_info(f"Found prim in scene: {child.GetPath()}")
+                    break
+    except Exception as e:
+        print_error(f"Warning: Could not verify USD scene loading: {e}")
+    
+    xform = UsdGeom.Xformable(scene_prim)
+    
+    def _apply_xform_op(attr_name, default_value, op_type):
+        """Apply transform op if value differs from default."""
+        value = getattr(scene_cfg, attr_name, None)
+        if not value or value == default_value:
+            return
+        existing_ops = xform.GetOrderedXformOps()
+        op = next((o for o in existing_ops if o.GetOpType() == op_type), None)
+        if op is None:
+            op = xform.AddTranslateOp() if op_type == UsdGeom.XformOp.TypeTranslate else xform.AddScaleOp()
+        op.Set(Gf.Vec3d(*value))
+    
+    _apply_xform_op('usd_position', (0.0, 0.0, 0.0), UsdGeom.XformOp.TypeTranslate)
+    _apply_xform_op('usd_scale', (1.0, 1.0, 1.0), UsdGeom.XformOp.TypeScale)
+    
+    print_success(f"USD scene loaded at {scene_prim_path}")
+    
+    sky_light_path = "/World/SkyLight"
+    if not stage.GetPrimAtPath(sky_light_path):
+        light_cfg = sim_utils.DomeLightCfg(intensity=1000.0, color=(1.0, 1.0, 1.0))
+        light_cfg.func(sky_light_path, light_cfg)
+        print_success("Added sky light")
+
+
+def _spawn_preset_scene(scene_cfg):
+    """Spawn a preset scene in Isaac Sim."""
+    import isaaclab.sim as sim_utils
+    import omni.usd
+    from pxr import Gf, UsdGeom
+    from isaaclab.terrains import TerrainImporter
+    
+    print_info("Spawning preset scene...")
+    
+    stage = omni.usd.get_context().get_stage()
+    if not stage.GetPrimAtPath("/World"):
+        UsdGeom.Xform.Define(stage, "/World")
+    
+    terrain_cfg = scene_cfg.get_terrain_cfg()
+    if terrain_cfg:
+        if not getattr(terrain_cfg, 'prim_path', None):
+            terrain_cfg.prim_path = "/World/Terrain"
+        TerrainImporter(terrain_cfg)
+        print_success(f"Terrain spawned (type: {terrain_cfg.terrain_type})")
+    
+    if hasattr(scene_cfg, 'get_light_cfgs'):
+        for name, light_cfg in (scene_cfg.get_light_cfgs() or {}).items():
+            prim_path = getattr(light_cfg, 'prim_path', f"/World/Lights/{name}")
+            if getattr(light_cfg, 'spawn', None) is not None:
+                light_cfg.spawn.func(prim_path, light_cfg.spawn)
+                print_success(f"Light '{name}' spawned at {prim_path}")
+    
+    if hasattr(scene_cfg, 'get_obstacle_cfgs'):
+        obstacle_cfgs = scene_cfg.get_obstacle_cfgs()
+        if obstacle_cfgs:
+            env_prim_path = "/World/envs/env_0"
+            for path in ["/World/envs", env_prim_path]:
+                if not stage.GetPrimAtPath(path):
+                    UsdGeom.Xform.Define(stage, path)
+            
+            for name, obs_cfg in obstacle_cfgs.items():
+                prim_path = getattr(obs_cfg, 'prim_path', f"{env_prim_path}/{name}").replace(
+                    "{ENV_REGEX_NS}", env_prim_path
+                )
+                if getattr(obs_cfg, 'spawn', None) is not None:
+                    obs_cfg.spawn.func(prim_path, obs_cfg.spawn)
+                    init_state = getattr(obs_cfg, 'init_state', None)
+                    if init_state is not None:
+                        prim = stage.GetPrimAtPath(prim_path)
+                        if prim.IsValid():
+                            xformable = UsdGeom.Xformable(prim)
+                            xformable.ClearXformOpOrder()
+                            
+                            if getattr(init_state, 'pos', None) is not None:
+                                pos = init_state.pos
+                                xformable.AddTranslateOp().Set(Gf.Vec3d(pos[0], pos[1], pos[2]))
+                            
+                            rot = getattr(init_state, 'rot', None)
+                            if rot is not None:
+                                import math
+                                if len(rot) == 4:
+                                    xformable.AddOrientOp(UsdGeom.XformOp.PrecisionDouble).Set(
+                                        Gf.Quatd(rot[0], rot[1], rot[2], rot[3])
+                                    )
+                                elif len(rot) == 3:
+                                    xformable.AddRotateXYZOp(UsdGeom.XformOp.PrecisionDouble).Set(
+                                        Gf.Vec3d(math.radians(rot[0]), math.radians(rot[1]), math.radians(rot[2]))
+                                    )
+            print_success(f"Spawned {len(obstacle_cfgs)} obstacles")
+    
+    sky_light_path = "/World/SkyLight"
+    if not stage.GetPrimAtPath(sky_light_path):
+        light_cfg = sim_utils.DomeLightCfg(intensity=1000.0, color=(1.0, 1.0, 1.0))
+        light_cfg.func(sky_light_path, light_cfg)
+        print_success("Added default sky light")
+
+
+def _setup_app_launcher():
+    """Set up AppLauncher and return the simulation app.
+    
+    This function extracts AppLauncher arguments from the original sys.argv
+    and creates the AppLauncher instance. It should be called before importing
+    any Isaac Lab modules that require the app to be running.
+    
+    Returns:
+        The SimulationApp instance from the AppLauncher.
+    """
+    _check_isaaclab_installed()
+    
+    from isaaclab.app import AppLauncher
+    
+    argv_to_parse = original_argv if original_argv is not None else sys.argv
+    
+    app_launcher_args = []
+    i = 1  # Skip script name
+    while i < len(argv_to_parse):
+        arg = argv_to_parse[i]
+        if arg in ("--category", "--scene"):
+            i += 2 if i + 1 < len(argv_to_parse) else 1
+            continue
+        if not arg.startswith("--") and i == 1:
+            i += 1
+            continue
+        app_launcher_args.append(arg)
+        i += 1
+    
+    parser = argparse.ArgumentParser()
+    AppLauncher.add_app_launcher_args(parser)
+    args_cli = parser.parse_args(app_launcher_args)
+    
+    app_launcher = AppLauncher(args_cli)
+    return app_launcher.app
+
+
+@click.command()
+@click.argument("env_id")
+@click.option("--category", required=True, help="Environment category")
+@click.option("--scene", help="Scene name or index")
+def view(env_id: str, category: str, scene: Optional[str]):
+    """View environment in Isaac Sim (requires isaaclab)."""
+    simulation_app = None
+    try:
+        simulation_app = _setup_app_launcher()
+        
+        import isaaclab.sim as sim_utils
+        from isaaclab.sim import SimulationContext
+        import omni.usd
+        
+        env = load_env(env_id, category)
+
+        if scene:
+            scene_cfg = load_scene(env, scene, category)
+            print_info(f"Loaded scene: {scene}")
+            
+            usd_path = getattr(scene_cfg, 'usd_path', None)
+            
+            sim_cfg = sim_utils.SimulationCfg(dt=0.01)
+            if usd_path:
+                _spawn_usd_scene(scene_cfg, env_cache_path=env.cache_path)
+                sim = SimulationContext(sim_cfg)
+                sim.set_camera_view(eye=[30.0, 30.0, 20.0], target=[0.0, 0.0, 0.0])
+            else:
+                sim = SimulationContext(sim_cfg)
+                _spawn_preset_scene(scene_cfg)
+                sim.set_camera_view(eye=[15.0, 15.0, 12.0], target=[0.0, 0.0, 0.0])
+            
+            sim.reset()
+            
+            print_success("Scene loaded successfully!")
+            click.echo("\n" + "=" * 60)
+            click.echo("Camera Controls:")
+            click.echo("   • Left-click + drag: Rotate view")
+            click.echo("   • Right-click + drag: Pan view")
+            click.echo("   • Scroll: Zoom in/out")
+            click.echo("   • F: Focus on selection")
+            click.echo("\nPress Ctrl+C in terminal to exit")
+            click.echo("=" * 60)
+            
+            try:
+                simulation_app = sim.app
+                click.echo("\nRunning simulation...\n   (Press Ctrl+C to exit)")
+                if simulation_app and hasattr(simulation_app, 'is_running'):
+                    while simulation_app.is_running():
+                        sim.step()
+                else:
+                    while not sim.is_stopped():
+                        sim.step()
+            except KeyboardInterrupt:
+                click.echo("\n\nExiting...")
+            except Exception as e:
+                if os.getenv("NEPHER_DEBUG"):
+                    import traceback
+                    traceback.print_exc()
+                click.echo(f"\nWarning: Could not start simulation loop: {e}")
+                click.echo("   Scene is loaded. You can interact with it in the Isaac Sim viewport.")
+        else:
+            print_info(f"Environment: {env.name}")
+            click.echo(f"  Scenes: {len(env.get_all_scenes())}")
+            click.echo("\nAvailable scenes:")
+            for i, scene_obj in enumerate(env.get_all_scenes()):
+                click.echo(f"  [{i}] {scene_obj.name}")
+
+    except KeyboardInterrupt:
+        click.echo("\n\nExiting...")
+    except Exception as e:
+        import traceback
+        print_error(f"Failed to view environment: {str(e)}")
+        if __debug__ or os.getenv("NEPHER_DEBUG"):
+            click.echo(f"Exception type: {type(e).__name__}")
+            traceback.print_exc()
+    finally:
+        if simulation_app is not None:
+            simulation_app.close()
+

nepher/cli/main.py

@@ -0,0 +1,30 @@
+"""
+Main CLI entry point.
+"""
+
+import click
+from nepher.cli.commands import auth, list_cmd, download, upload, cache, view, config
+
+
+@click.group()
+@click.version_option()
+def main():
+    """Nepher: Universal Isaac Lab Environments Platform."""
+    pass
+
+
+# Register commands
+main.add_command(auth.login)
+main.add_command(auth.logout)
+main.add_command(auth.whoami)
+main.add_command(list_cmd.list_cmd)
+main.add_command(download.download)
+main.add_command(upload.upload)
+main.add_command(cache.cache)
+main.add_command(view.view)
+main.add_command(config.config)
+
+
+if __name__ == "__main__":
+    main()
+

nepher/cli/utils.py

@@ -0,0 +1,28 @@
+"""CLI utility functions."""
+
+import click
+from rich.console import Console
+from rich import print as rprint
+
+console = Console()
+
+
+def print_success(message: str):
+    """Print success message."""
+    rprint(f"[green]✓[/green] {message}")
+
+
+def print_error(message: str):
+    """Print error message."""
+    rprint(f"[red]✗[/red] {message}")
+
+
+def print_info(message: str):
+    """Print info message."""
+    rprint(f"[blue]ℹ[/blue] {message}")
+
+
+def print_warning(message: str):
+    """Print warning message."""
+    rprint(f"[yellow]⚠[/yellow] {message}")
+

nepher/config.py

@@ -0,0 +1,202 @@
+"""
+Configuration management for Nepher.
+
+Supports multiple configuration sources with priority:
+1. CLI arguments
+2. Environment variables
+3. Config file
+4. Category-specific overrides
+5. Default values
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+from functools import lru_cache
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    import tomli as tomllib  # Fallback for Python < 3.11
+
+
+class Config:
+    """Centralized configuration manager."""
+
+    def __init__(self):
+        self._config: Dict[str, Any] = {}
+        self._config_file: Optional[Path] = None
+        self._load_config()
+
+    def _load_config(self):
+        """Load configuration from all sources."""
+        self._config = {
+            "api_url": "https://envhub.nepher.ai",
+            "api_key": None,
+            "cache_dir": "~/.nepher/cache",
+            "default_category": None,
+            "categories": {},
+        }
+
+        config_file = self._find_config_file()
+        if config_file and config_file.exists():
+            self._config_file = config_file
+            try:
+                if config_file.suffix == ".toml":
+                    with open(config_file, "rb") as f:
+                        file_config = tomllib.load(f)
+                        self._config.update(file_config)
+                elif config_file.suffix == ".json":
+                    import json
+
+                    with open(config_file, "r") as f:
+                        file_config = json.load(f)
+                        self._config.update(file_config)
+            except Exception:
+                pass
+
+        if os.getenv("NEPHER_API_URL"):
+            self._config["api_url"] = os.getenv("NEPHER_API_URL")
+        if os.getenv("NEPHER_API_KEY"):
+            self._config["api_key"] = os.getenv("NEPHER_API_KEY")
+        if os.getenv("NEPHER_CACHE_DIR"):
+            self._config["cache_dir"] = os.getenv("NEPHER_CACHE_DIR")
+
+    def _find_config_file(self) -> Optional[Path]:
+        """Find config file in standard locations."""
+        cwd_config = Path.cwd() / ".nepherrc"
+        if cwd_config.exists():
+            return cwd_config
+
+        home_config = Path.home() / ".nepher" / "config.toml"
+        if home_config.exists():
+            return home_config
+
+        return None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value.
+
+        Supports dot notation for nested keys (e.g., 'categories.navigation.cache_dir').
+        """
+        keys = key.split(".")
+        value = self._config
+
+        for k in keys:
+            if isinstance(value, dict) and k in value:
+                value = value[k]
+            else:
+                return default
+
+        return value
+
+    def set(self, key: str, value: Any, save: bool = True):
+        """
+        Set configuration value.
+
+        Supports dot notation for nested keys.
+        Creates config file if it doesn't exist.
+        """
+        keys = key.split(".")
+        config = self._config
+
+        for k in keys[:-1]:
+            if k not in config or not isinstance(config[k], dict):
+                config[k] = {}
+            config = config[k]
+
+        config[keys[-1]] = value
+
+        if save:
+            self._save_config()
+
+    def get_cache_dir(self, category: Optional[str] = None, override: Optional[str] = None) -> Path:
+        """
+        Get cache directory path.
+
+        Priority:
+        1. override (CLI argument)
+        2. Category-specific cache_dir
+        3. Global cache_dir
+        4. Default
+
+        Args:
+            category: Optional category name for category-specific cache
+            override: Optional override path (from CLI flag)
+
+        Returns:
+            Resolved Path object
+        """
+        if override:
+            path_str = override
+        elif category:
+            cat_config = self.get(f"categories.{category}", {})
+            path_str = cat_config.get("cache_dir") or self.get("cache_dir")
+        else:
+            path_str = self.get("cache_dir")
+
+        path = Path(path_str).expanduser().resolve()
+        path.mkdir(parents=True, exist_ok=True)
+
+        return path
+
+    def get_api_url(self) -> str:
+        """Get API URL."""
+        return self.get("api_url")
+
+    def get_api_key(self) -> Optional[str]:
+        """Get API key (may be None if not set)."""
+        return self.get("api_key")
+
+    def _remove_none_values(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Recursively remove None values from dictionary for TOML serialization."""
+        result = {}
+        for key, value in data.items():
+            if value is None:
+                continue  # Skip None values
+            elif isinstance(value, dict):
+                cleaned = self._remove_none_values(value)
+                if cleaned:  # Only include non-empty dicts
+                    result[key] = cleaned
+            else:
+                result[key] = value
+        return result
+
+    def _save_config(self):
+        """Save configuration to file."""
+        if not self._config_file:
+            config_dir = Path.home() / ".nepher"
+            config_dir.mkdir(parents=True, exist_ok=True)
+            self._config_file = config_dir / "config.toml"
+
+        try:
+            import tomli_w
+
+            config_to_save = self._remove_none_values(self._config)
+
+            with open(self._config_file, "wb") as f:
+                tomli_w.dump(config_to_save, f)
+        except ImportError:
+            import json
+
+            with open(self._config_file.with_suffix(".json"), "w") as f:
+                json.dump(self._config, f, indent=2)
+
+
+_config_instance: Optional[Config] = None
+
+
+@lru_cache(maxsize=1)
+def get_config() -> Config:
+    """Get global configuration instance."""
+    global _config_instance
+    if _config_instance is None:
+        _config_instance = Config()
+    return _config_instance
+
+
+def set_config(key: str, value: Any, save: bool = True):
+    """Set configuration value."""
+    get_config().set(key, value, save=save)
+

nepher/core.py

@@ -0,0 +1,67 @@
+"""
+Core data structures for Nepher.
+
+Defines Environment, Scene, and related types.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Dict, Any, Union
+
+
+@dataclass
+class Scene:
+    """Represents a single scene within an environment."""
+
+    name: str
+    description: Optional[str] = None
+    usd: Optional[Path] = None
+    preset: Optional[str] = None
+    scene: Optional[str] = None  # Python scene file path (for USD scenes with custom config)
+    omap_meta: Optional[Path] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Environment:
+    """Represents an environment bundle."""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    category: str = "navigation"
+    type: str = "usd"  # "usd" or "preset"
+    version: Optional[str] = None
+    author: Optional[str] = None
+    scenes: List[Scene] = field(default_factory=list)
+    preset_scenes: List[Scene] = field(default_factory=list)
+    benchmark: bool = False
+    metadata: Optional[Dict[str, Any]] = None
+    cache_path: Optional[Path] = None
+
+    def get_scene(self, scene: Union[str, int]) -> Optional[Scene]:
+        """
+        Get a scene by name or index.
+
+        Args:
+            scene: Scene name (str) or index (int)
+
+        Returns:
+            Scene object or None if not found
+        """
+        all_scenes = self.scenes + self.preset_scenes
+
+        if isinstance(scene, int):
+            if 0 <= scene < len(all_scenes):
+                return all_scenes[scene]
+        else:
+            for s in all_scenes:
+                if s.name == scene:
+                    return s
+
+        return None
+
+    def get_all_scenes(self) -> List[Scene]:
+        """Get all scenes (USD and preset combined)."""
+        return self.scenes + self.preset_scenes
+

nepher/env_cfgs/__init__.py

@@ -0,0 +1,7 @@
+"""Environment configuration system."""
+
+from nepher.env_cfgs.base import BaseEnvCfg
+from nepher.env_cfgs.registry import get_config_class, register_config_class
+
+__all__ = ["BaseEnvCfg", "get_config_class", "register_config_class"]
+

nepher/env_cfgs/base.py

@@ -0,0 +1,32 @@
+"""
+Base environment configuration interface.
+"""
+
+from typing import Any
+
+
+class BaseEnvCfg:
+    """Base interface for all environment configs (category-agnostic).
+    
+    Note: Not using ABC to avoid pickling issues with @configclass decorator.
+    Subclasses should override methods and raise NotImplementedError if not implemented.
+    """
+
+    name: str = ""
+    description: str = ""
+    category: str = ""
+
+    def get_terrain_cfg(self) -> Any:
+        """Return terrain configuration.
+        
+        Subclasses must override this method.
+        """
+        raise NotImplementedError("Subclass must implement get_terrain_cfg()")
+
+    def get_scene_cfg(self) -> Any:
+        """Return scene configuration.
+        
+        Subclasses must override this method.
+        """
+        raise NotImplementedError("Subclass must implement get_scene_cfg()")
+

nepher/env_cfgs/manipulation/__init__.py

@@ -0,0 +1,4 @@
+"""Manipulation-specific environment configs."""
+
+# Placeholder for manipulation configs
+