feat: Complete simulator-agnostic TSR library overhaul with template generators #12
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ild system This commit represents a complete refactoring of the TSR library to: 1. Remove OpenRAVE dependencies from the core library 2. Modernize the build system from ROS/catkin to uv/pyproject.toml 3. Add comprehensive test coverage for all functionality Key Changes: BUILD SYSTEM MODERNIZATION: - Replace setup.py (ROS/catkin) with pyproject.toml (modern Python) - Remove package.xml and CMakeLists.txt (ROS-specific) - Add uv.lock for dependency management - Update .gitignore for modern Python development - Update README.md with installation and usage instructions CORE LIBRARY REFACTORING: - Create src/tsr/core/ with robot-agnostic TSR implementation - Implement TSR and TSRChain classes with all legacy functionality - Add utility functions (wrap_to_interval, geodesic_error, geodesic_distance) - Maintain backward compatibility through src/tsr/__init__.py - Fix bugs in legacy code (util.py GeodesicError function) WRAPPER ARCHITECTURE: - Create src/tsr/wrappers/ for simulator-specific code - Implement abstract base classes for robot/object/environment adapters - Add OpenRAVE wrapper implementation - Prepare structure for future MuJoCo wrapper COMPREHENSIVE TESTING: - Add 54 comprehensive tests covering all functionality - Equivalence tests ensuring new implementation matches legacy behavior - Serialization tests for dict/JSON/YAML conversions - Utility function tests for mathematical operations - TSRChain method tests for all public methods - Edge case and error handling tests TEST COVERAGE: - Equivalence tests (7): Legacy vs new implementation comparison - Serialization tests (20): Dict/JSON/YAML roundtrip testing - Utility tests (15): Mathematical function validation - TSRChain tests (12): All public method testing - All tests passing (54/54) The refactored library maintains complete feature parity with the original while being robot-agnostic and ready for multiple simulator integrations.
…base Major changes: - Remove legacy tsr.py, kin.py, rodrigues.py, util.py files - Update core implementation to match legacy behavior exactly - Remove equivalence tests (no longer needed) - Update all imports to use core implementation - Modernize TSR library structure Core improvements: - Core TSR and TSRChain now handle multi-arm scenarios properly - Lenient bounds checking during optimization prevents failures - Improved error handling for empty chains and edge cases - Backward compatibility for tsr parameter in TSRChain - Enhanced contains() method with individual TSR checking Test updates: - All tests updated to use core implementation - Performance tests simplified to test only core implementation - Wrapper tests updated for compatibility - Comprehensive test coverage maintained MuJoCo wrapper foundation: - Add MuJoCo robot adapter with multi-arm support - Add MuJoCo-specific TSR functions - Add comprehensive tests for MuJoCo wrapper - Prepare for future MuJoCo integration This commit establishes a clean, modern, robot-agnostic TSR library with proper multi-arm support and prepares for MuJoCo integration.
This commit represents a complete refactoring of the TSR library to be simulator-agnostic and provide a rich interface for representing, storing, and creating TSRs. Major Changes: - Remove all simulator-specific wrappers (OpenRAVE, MuJoCo) - Remove old TSR library and generic functions - Add new architecture components: * TSRTemplate: Scene-agnostic TSR definitions * TSRLibraryRelational: Task-based TSR generation * Schema system: Controlled vocabulary for tasks/entities * Advanced sampling utilities - Comprehensive documentation updates - Modular example structure with 6 focused examples - Complete test suite with 103 passing tests New Features: - TSR templates for reusable, scene-agnostic definitions - Relational library for task-based TSR generation - Schema system with TaskCategory, TaskType, EntityClass - Advanced sampling with weighted selection - Full serialization support (dict, JSON, YAML) - Comprehensive API documentation - Modular examples with learning path Documentation: - Updated README with new architecture overview - Comprehensive API documentation in docs/API.md - Modular examples with clear learning path - Enhanced docstrings throughout codebase Testing: - 103 comprehensive tests covering all components - Performance benchmarks - Edge case testing - All tests passing Examples: - 01_basic_tsr.py: Core TSR operations - 02_tsr_chains.py: Complex constraints - 03_tsr_templates.py: Reusable definitions - 04_relational_library.py: Task-based generation - 05_sampling.py: Advanced sampling - 06_serialization.py: Data persistence The library is now fully simulator-agnostic and provides a rich, well-documented interface for TSR manipulation.
Add a clear explanation of how the relational library treats TSRs as spatial relationships between subject and reference entities. This clarifies the manipulator-agnostic and reusable nature of the relational approach.
Remove .travis.yml file which was using an outdated, complex build system specific to Personal Robotics Lab infrastructure. The configuration was: - Using Ubuntu 14.04 (trusty) which is very outdated - Relying on custom pr-cleanroom scripts - Not appropriate for our modern, simulator-agnostic Python package - Using uv for dependency management This will be replaced with modern GitHub Actions CI in a future update.
This commit adds comprehensive YAML serialization support and semantic context to TSR templates, making them much more powerful and user-friendly. Major Features Added: - TSRTemplate with semantic context (subject_entity, reference_entity, task_category, variant) - Optional metadata (name, description) for better documentation - Complete serialization support (to_dict, from_dict, to_yaml, from_yaml) - Enhanced TSRLibraryRelational with template-based registration and description support - Comprehensive test coverage for all new functionality TSRTemplate Enhancements: - Added semantic fields: subject_entity, reference_entity, task_category, variant - Added metadata fields: name, description (optional) - Full serialization support following the same pattern as TSR/TSRChain - YAML format is human-readable and includes semantic context - Template instantiation works seamlessly with semantic context TSRLibraryRelational Enhancements: - register_template(): Register individual templates with descriptions - query_templates(): Query templates with optional description inclusion - list_available_templates(): Browse available templates with filtering - get_template_info(): Get template names and descriptions - Backward compatibility with existing generator-based approach Serialization Features: - YAML format includes semantic context and metadata - Cross-format roundtrip support (dict ↔ YAML) - Template library serialization for collections - Human-readable YAML structure with clear semantic meaning Testing: - 14 new TSRTemplate tests covering creation, instantiation, and serialization - 12 new TSRLibraryRelational tests covering template-based functionality - Updated existing tests to work with new semantic context - All 111 tests passing Examples: - Updated all examples to use new semantic context - Enhanced serialization example with template library demonstration - All 6 examples working and demonstrating new features Benefits: - Human-readable YAML templates with clear semantic meaning - Self-documenting template libraries - Easy template sharing and version control - Rich semantic context for better integration - Backward compatibility maintained
…ures This commit updates the README to showcase the new YAML serialization and semantic context features that were added to TSR templates. Key Updates: - Enhanced Features section highlighting semantic context and YAML serialization - Updated TSR Template examples with semantic fields (subject_entity, reference_entity, etc.) - Added Enhanced Template-Based Library section showing new registration methods - Expanded Serialization section with YAML template examples - Added Examples section with comprehensive example descriptions - Added Key Benefits section highlighting the advantages of new features - Updated all code examples to use semantic context - Added YAML output examples showing human-readable template format The README now provides a complete guide to the enhanced TSR library capabilities, making it easy for users to understand and adopt the new semantic context and YAML serialization features.
This commit adds a complete template file management system for TSR templates: New Features: - TemplateIO class with comprehensive file management utilities - save_template() and load_template() for individual template files - save_template_collection() and load_template_collection() for bulk operations - load_templates_from_directory() for loading all templates from a directory - load_templates_by_category() for organized category-based loading - save_templates_by_category() for organized category-based saving - validate_template_file() for file validation - get_template_info() for metadata extraction without full loading - Convenience functions for common operations New Example: - examples/07_template_file_management.py demonstrates the recommended multiple files approach (one file per template) with organized directory structure, individual loading, bulk loading, and template usage Package Updates: - Updated src/tsr/__init__.py to expose all new template I/O utilities - Updated examples/run_all_examples.py to include the new example The system supports both individual template files and collections, but recommends the multiple files approach for better version control and collaborative development.
This commit updates the project configuration for the major refactor: - Update version from 0.0.1 to 1.0.0 to reflect the major refactor - Change author and maintainer to Siddhartha Srinivasa - Trim pyproject.toml to essential configuration only - Remove verbose tool configurations (black, isort, mypy, pylint) - Keep core project metadata, dependencies, and basic pytest setup The version bump to 1.0.0 reflects the breaking changes and new architecture introduced in this refactor.
This commit fixes the 'Variable not allowed in type expression' errors by implementing proper forward references: - Add from __future__ import annotations for deferred evaluation - Add TYPE_CHECKING conditional imports for type hints - Add type: ignore[name-defined] comments for Pylance compatibility - Remove string literal forward references in favor of proper annotations The changes ensure type safety while maintaining runtime compatibility and resolving Pylance warnings.
This commit adds a templates/ directory to store TSR template YAML files: ## New Structure - templates/README.md - Documentation for template organization - templates/grasps/mug_side_grasp.yaml - Example mug side grasp template - templates/places/mug_on_table.yaml - Example mug placement template ## Template Features - Semantic context (subject, reference, task category, variant) - Geometric parameters (T_ref_tsr, Tw_e, Bw matrices) - Human-readable YAML format with comments - Organized by task category (grasps, places, tools) ## Usage Templates can be loaded using the TemplateIO utilities: This establishes the foundation for a comprehensive template library that ships with the TSR package.
- Add src/tsr/generators.py with simulator-agnostic template generation - Support cylinder grasps (side, top, bottom) with configurable parameters - Support box grasps (side_x, side_y, top, bottom) with configurable parameters - Support placement templates (on, in, against) with surface constraints - Support transport templates (upright, horizontal, custom) for trajectory constraints - Add convenience functions for common objects (mug, box) - All generators return TSRTemplate objects with semantic context - Integrate with relational library and YAML serialization - Add comprehensive example (examples/08_template_generators.py) - Update README.md with generators documentation - All tests passing (111/111) This adapts the old generic.py functionality to our new architecture while maintaining geometric logic and adding rich semantic context.
- Add comprehensive CI pipeline with matrix testing - Test on multiple platforms (Linux, macOS, Windows) - Test on multiple Python versions (3.8-3.12) - Use uv for dependency management with caching - Include separate pip compatibility test - Add package build and installation test - Exclude some platform/Python combinations to reduce CI time - Test core package imports and functionality - Verify examples directory structure This replaces the old Travis CI configuration with a modern, comprehensive CI pipeline that ensures code quality across all supported platforms and Python versions.
- Add build>=1.0.0 to test dependencies (required by CI) - Add pytest configuration with strict markers and verbose output - Add coverage configuration for better test reporting - Configure test markers for slow and integration tests - Set up coverage exclusions for better reporting accuracy These changes support the GitHub Actions CI workflow and improve the development experience with better test configuration.
- Add uv venv creation before pip install - Add pytest version check to ensure it's available - Fix virtual environment setup for all platforms
- Fix Python 3.8 type annotation compatibility (use Tuple/Dict instead of tuple/dict) - Remove Unicode emojis from CI output to fix Windows encoding issues - Ensure all platforms can run tests successfully
- Add optional preshape field to TSRTemplate for gripper configuration - Preshape stores DOF values (e.g., aperture for parallel jaw, joint angles for multi-finger hands) - Update all generator functions to support preshape parameter - Add comprehensive example demonstrating preshape functionality - Update serialization methods to handle preshape field - All tests passing and backward compatible - Preshape is None by default for templates that don't need gripper configuration
- Add preshape feature to main README features list - Add dedicated 'Gripper Preshape Configuration' section with examples - Update template generators section with preshape examples - Add preshape documentation to templates README - Update section numbering and examples list - Include preshape in YAML template format examples
atharva620
requested changes
Aug 15, 2025
| # Clone and install the package | ||
| git clone https://github.com/personalrobotics/tsr.git | ||
| cd tsr | ||
| uv sync |
There was a problem hiding this comment.
Assuming the user is developing in a virtual environment, this should be modified to uv sync --active to avoid the following warning which hinders installation:
warning: `VIRTUAL_ENV=/home/atharva620/temp` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead
| "pytest>=6.0.0", | ||
| "pytest-cov>=2.10.0", | ||
| "build>=1.0.0", | ||
| ] |
There was a problem hiding this comment.
Add lark as an optional dependency. Necessary for running tests.
| self._reg: Dict[RelKey, Generator] = {} | ||
| self._templates: Dict[RelKey, List[TemplateEntry]] = {} | ||
|
|
||
| def register( |
There was a problem hiding this comment.
A better name for this function could be register_generator because it avoids ambiguity and remains consistent with its own description as well as its sister function i.e. register_template
There was a problem hiding this comment.
The templates/ folder exists both at the repo root and under src/tsr/. Please remove the top-level copy and keep src/tsr/templates/ to avoid code duplication.
| templates/ | ||
| ├── grasps/ # Grasping templates | ||
| ├── places/ # Placement templates | ||
| ├── tools/ # Tool manipulation templates |
There was a problem hiding this comment.
tools/ directory is not present. Please update the README accordingly.
| - `mug_on_table.yaml` - Place mug on flat surface | ||
| - `bottle_in_shelf.yaml` - Place bottle in shelf compartment | ||
|
|
||
| ### Tools (`tools/`) |
There was a problem hiding this comment.
tools/ directory is not present. Please update the README accordingly.
There was a problem hiding this comment.
Applicable to the whole file: Is it intentional to include the "bottom" grasp variant here even when the object is resting on a surface (where a +z approach is blocked)? Or is the intent to also support suspended/edge cases with underside clearance? If the latter, should we explicitly document it?
| @@ -0,0 +1,116 @@ | |||
| #!/usr/bin/env python | |||
There was a problem hiding this comment.
TSRLibraryRelational.register accepts either a generator or a concrete template keyed by (subject, reference, task). As shown here, do we actually want to support direct instantiation of TSRTemplate outside the relational library? If the recommended usage is solely via TSRLibraryRelational, this example that instantiates a template without going through the TSRLibraryRelational.register route is confusing. Should we remove this example? (since Example 04 already demonstrates template instantiation). Right now it feels redundant/inconsistent if we want to discourage by-passing the relational layer.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🚀 Complete Simulator-Agnostic TSR Library Overhaul
This PR represents a major refactor and feature expansion of the TSR library, transforming it from a simulator-specific implementation to a rich, simulator-agnostic interface for representing, storing, and creating Task Space Regions (TSRs).
📊 Overview
🏗️ Major Architectural Changes
1. Simulator-Agnostic Design
2. Modern Python Packaging
setup.py,package.xml,CMakeLists.txt,.travis.ymlpyproject.toml,uv.lock, GitHub Actions ready3. Enhanced Core Architecture
src/tsr/core/: Reorganized core TSR functionalityTSRTemplate: Scene-agnostic TSR definitions with semantic contextTSRLibraryRelational: Task-based TSR generation and querying🆕 New Features
1. Template Generators 🔧
Supported Generators:
2. YAML Serialization 📄
Features:
3. Enhanced Relational Library 📚
4. Advanced Sampling 🎲
📁 File Structure Changes
Added Files:
src/tsr/generators.py- Template generators for primitive objectssrc/tsr/schema.py- Controlled vocabulary systemsrc/tsr/sampling.py- Advanced sampling utilitiessrc/tsr/template_io.py- YAML serialization utilitiessrc/tsr/core/tsr_template.py- TSR template implementationsrc/tsr/core/tsr_chain.py- TSR chain compositionsrc/tsr/tsr_library_rel.py- Relational TSR libraryexamples/- 8 comprehensive example filestemplates/- Example YAML template filestests/- Comprehensive test suite (111 tests)Removed Files:
src/tsr/generic.py- Replaced bygenerators.pysrc/tsr/kin.py- Simulator-specific kinematicssrc/tsr/rodrigues.py- Simulator-specific utilitiessrc/tsr/tsrlibrary.py- Replaced bytsr_library_rel.pysrc/tsr/util.py- Replaced bycore/utils.py.travis.yml- Replaced by GitHub Actions (future)setup.py- Replaced bypyproject.toml🧪 Testing & Quality
Test Coverage:
Quality Metrics:
🎯 Key Benefits
1. Simulator Independence
2. Rich Semantic Context
3. Flexible Template System
4. Modern Development Experience
📋 Migration Guide
For Existing Users:
For New Users:
📝 Commit History
✅ Ready for Review
This PR is ready for review and merge. All tests pass, documentation is comprehensive, and the implementation follows modern Python best practices.
Reviewers should focus on:
This represents a major milestone in the TSR library's evolution, transforming it from a simulator-specific tool into a rich, flexible interface for TSR representation and manipulation.