Skip to content

CLAUDE.md

Latest commit

 

History

History
89 lines (68 loc) · 5.28 KB

CLAUDE.md

File metadata and controls

89 lines (68 loc) · 5.28 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an Isaac Sim drone simulation project using NVIDIA Omniverse and Cesium for geospatial positioning. The project demonstrates drone control and movement in a realistic 3D environment with real-world coordinates.

Key Components

  • demo1.py: Main drone controller script that handles a Crazyflie drone (/World/cf2x) with kinematic movement using Cesium Globe Anchor API. Includes automatic cleanup of physics components and position reset functionality.
  • demo2.py: Comprehensive Isaac Sim Replicator learning module for Synthetic Data Generation (SDG). Implements senior-level patterns for environment setup, object creation, domain randomization, and data collection using omni.replicator.core API.
  • USD files: Various Universal Scene Description files containing 3D scenes and assets, including campus and NYC scenes.

Architecture and Development Patterns

Drone Control System (demo1.py)

  • Uses Omniverse Kit APIs (omni.kit.commands, omni.usd, omni.timeline) for scene manipulation
  • Integrates Cesium USD Schemas for real-world geospatial positioning
  • Implements frame-by-frame update system using subscription pattern
  • Global state management through g_simulation_state dictionary
  • Automatic cleanup of stale physics components (UsdPhysics.RigidBodyAPI) on each run

Replicator Synthetic Data Generation System (demo2.py)

  • Uses omni.replicator.core API for production-scale synthetic dataset generation
  • Implements modular architecture with separate phases: environment setup, object creation, camera management, randomization, and data collection
  • Critical Pattern: SimulationApp must be initialized BEFORE importing any other omni modules
  • Supports multiple annotators: RGB, semantic segmentation, 2D/3D bounding boxes
  • Domain randomization for object poses, materials, and lighting conditions
  • Multi-camera render products for diverse viewpoints

Key Design Patterns

  • Subscription-based updates: Uses app_update.create_subscription_to_pop() for real-time movement
  • State management: Global dictionary pattern for simulation state persistence
  • Error handling: Comprehensive logging and validation of USD prims and APIs
  • Reset functionality: Explicit position reset to initial coordinates on each script execution
  • Resource management: Proper cleanup of USD stage and orchestrator resources
  • Factory patterns: Configurable object and camera creation with validation

Development Environment

This project appears to run within NVIDIA Isaac Sim/Omniverse environment. No traditional build/test/lint commands are present as this is a simulation script project rather than a packaged application.

Running the Project

Drone Simulation (demo1.py):

  • Execute scripts directly within Isaac Sim environment
  • Main entry point: setup_and_move_drone() in demo1.py
  • Stop movement: stop_movement() function
  • Press PLAY in Isaac Sim timeline to see drone movement

Replicator Learning Module (demo2.py):

  • Execute within Isaac Sim Python environment: ./python.sh demo2.py
  • Main entry point: ReplicatorLearningEnvironment() class
  • Generates synthetic data to _out_replicator_learning/ directory
  • Advanced example: create_advanced_scene_example() for warehouse scenarios
  • Configuration via CONFIG dictionary for frames, resolution, output directory

Critical Implementation Notes

Drone Simulation (demo1.py):

  • Physics Component Cleanup: Always remove stale UsdPhysics.RigidBodyAPI before applying new transformations
  • Coordinate System: Uses latitude/longitude/height for positioning (Virginia Tech campus area: ~37.22N, -80.41W)
  • Movement Pattern: Sinusoidal movement along longitude axis with configurable speed and distance
  • Scale Handling: Drone uses 100x scale factor for visibility

Replicator Learning (demo2.py):

  • Initialization Order: SimulationApp MUST be created before importing omni modules
  • Resource Management: Always call cleanup() and simulation_app.close() in finally blocks
  • Physics Timesteps: 240Hz physics (1/240s), 60Hz rendering (1/60s) for optimal performance
  • Render Products: Each camera creates independent render products for data collection
  • Randomization Patterns: Use rep.new_layer() context for registering randomizers
  • Output Management: Configure output directories and ensure proper annotator attachment

File Structure Context

  • demo1.py: Production drone simulation with Cesium integration (533 lines)
  • demo2.py: Comprehensive Replicator learning module (537 lines)
  • REPLICATOR_LEARNING_GUIDE.md: Comprehensive documentation for synthetic data generation
  • USD files: 3D scene data and should be handled as binary assets
  • Python scripts: Primary development focus with Isaac Sim integration
  • No package management files: Direct Isaac Sim environment integration

Learning Resources

  • REPLICATOR_LEARNING_GUIDE.md: Comprehensive guide for mastering Isaac Sim Replicator
  • demo2.py: Progressive learning implementation with production patterns
  • Official documentation: Isaac Sim 4.5.0+ Replicator tutorials
  • Key concepts: Domain randomization, annotators, writers, orchestration patterns