Skip to main content

data_preparation_cfg

Module: GBC.utils.data_preparation.data_preparation_cfg

This module provides a comprehensive configuration system for data preparation workflows in the GBC framework. It offers pre-configured classes for common data processing tasks including AMASS dataset handling, robot kinematics setup, motion filtering, and action conversion pipelines.

📚 Dependencies​

This module requires the following Python packages:

  • torch - PyTorch framework for tensor operations
  • typing - Type annotations and hints
  • GBC.utils.base.configclass - Enhanced dataclass functionality
  • GBC.utils.base.assets - Path management and asset configuration

🏗️ Configuration Hierarchy​

The module follows a hierarchical configuration design where specialized configurations inherit from base configurations, allowing for easy customization and extension.

BaseCfg
├── AMASSDatasetCfg
│   ├── AMASSDatasetInterpolateCfg
│   │   └── AMASSActionConverterCfg
│   └── AMASSDatasetSingleFrameCfg
├── FilterCfg
├── RobotKinematicsCfg
├── BodyModelCfg
└── PoseRendererCfg

🔧 Base Configuration​

📋 BaseCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.BaseCfg

Definition:

@configclass
class BaseCfg:
    smplh_model_path: str
    dmpls_model_path: str  
    urdf_path: str
    device: str = "cuda"

🔧 Functionality: Foundation configuration class providing essential paths and device settings. All other configurations inherit from this base to ensure consistent access to core resources.

⚙️ Configuration Parameters:

  • smplh_model_path: Path to SMPL+H human body model
  • dmpls_model_path: Path to DMPL muscle dynamics model
  • urdf_path: Path to robot URDF description file
  • device: Computing device for tensor operations

💡 Usage: Automatically populated from DATA_PATHS configuration. Users should ensure proper asset paths are configured before using any derived configurations.

📊 Dataset Configuration​

🗂️ AMASSDatasetCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.AMASSDatasetCfg

Definition:

@configclass
class AMASSDatasetCfg(BaseCfg):
    root_dir: str
    num_betas: int = 16
    num_dmpls: int = 8
    load_hands: bool = False
    secondary_dir: Optional[str] = None

🔧 Functionality: Configuration for loading and processing AMASS motion capture datasets. Provides settings for body shape parameters, muscle dynamics, and optional hand motion data.

⚙️ Configuration Parameters:

  • root_dir: Root directory containing AMASS dataset files
  • num_betas: Number of body shape parameters (typically 16)
  • num_dmpls: Number of muscle dynamics parameters (typically 8)
  • load_hands: Whether to include hand motion data
  • secondary_dir: Optional secondary dataset directory

🔄 AMASSDatasetInterpolateCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.AMASSDatasetInterpolateCfg

Definition:

@configclass
class AMASSDatasetInterpolateCfg(AMASSDatasetCfg):
    interpolate_fps: int = 50
    seq_min_duration: Optional[int] = None
    specialize_dir: Optional[List[str]] = None

🔧 Functionality: Extended dataset configuration for temporal interpolation and sequence processing. Enables consistent frame rates and duration filtering for training data.

⚙️ Configuration Parameters:

  • interpolate_fps: Target frame rate for motion interpolation
  • seq_min_duration: Minimum sequence duration filter (frames)
  • specialize_dir: List of specialized dataset subdirectories

📸 AMASSDatasetSingleFrameCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.AMASSDatasetSingleFrameCfg

Definition:

@configclass
class AMASSDatasetSingleFrameCfg(AMASSDatasetCfg):
    transform: Optional[Callable] = None

🔧 Functionality: Configuration for single-frame pose processing from AMASS data. Useful for pose-based training tasks or static pose analysis.

⚙️ Configuration Parameters:

  • transform: Optional transformation function for pose preprocessing

🔧 Processing Configuration​

🌊 FilterCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.FilterCfg

Definition:

@configclass
class FilterCfg(BaseCfg):
    filter_cutoff: float = 5
    filter_sample_rate: float = 50
    filter_order: int = 2

🔧 Functionality: Signal filtering configuration for smoothing actions and velocities. Essential for removing noise from motion data and ensuring stable robot control.

⚙️ Configuration Parameters:

  • filter_cutoff: Low-pass filter cutoff frequency (Hz)
  • filter_sample_rate: Data sampling rate (Hz)
  • filter_order: Filter order for smoothness vs responsiveness trade-off

💡 Typical Values:

  • Cutoff: 3-10 Hz depending on motion type
  • Sample Rate: 30-60 Hz for robot control
  • Order: 2-4 for balance between smoothing and delay

🤖 RobotKinematicsCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.RobotKinematicsCfg

Definition:

@configclass
class RobotKinematicsCfg(BaseCfg):
    mapping_table: Dict[str, str]
    offset_map: Dict[str, torch.Tensor]

🔧 Functionality: Robot-specific kinematic configuration including joint mappings and position offsets. Critical for accurate motion transfer from human to robot.

⚙️ Configuration Parameters:

  • mapping_table: SMPL+H to robot joint name mapping
  • offset_map: Position offsets for improved joint alignment

⚠️ User Configuration Required:

  • Adapt mapping_table for your specific robot platform
  • Adjust offset_map based on robot geometry and fitting results
  • Ensure device placement for tensor operations

🚀 Pipeline Configuration​

🔄 AMASSActionConverterCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.AMASSActionConverterCfg

Definition:

@configclass
class AMASSActionConverterCfg(AMASSDatasetInterpolateCfg, RobotKinematicsCfg):
    pose_transformer_path: str
    batch_size: int = 512
    export_path: str
    filter: FilterCfg
    visualize: bool = True
    smpl_fits_dir: str

🔧 Functionality: Comprehensive configuration for converting AMASS motion data to robot actions. Combines dataset loading, kinematic mapping, filtering, and export functionality.

⚙️ Configuration Parameters:

  • pose_transformer_path: Path to trained pose transformation model
  • batch_size: Processing batch size for efficiency
  • export_path: Output directory for converted actions
  • filter: Embedded filter configuration
  • visualize: Enable visualization during processing
  • smpl_fits_dir: Directory containing SMPL+H fitting results

👤 BodyModelCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.BodyModelCfg

Definition:

@configclass
class BodyModelCfg(BaseCfg):
    # Inherits base model paths and device settings

🔧 Functionality: Specialized configuration for body model operations. Provides a dedicated configuration context for SMPL+H body model tasks.

🎨 PoseRendererCfg​

Module Name: GBC.utils.data_preparation.data_preparation_cfg.PoseRendererCfg

Definition:

@configclass
class PoseRendererCfg(RobotKinematicsCfg, BodyModelCfg, AMASSDatasetCfg):
    poseformer_model_path: str
    save_path: str
    max_single_batch: int = 512

🔧 Functionality: Multi-inheritance configuration for pose rendering and visualization tasks. Combines robot kinematics, body modeling, and dataset access.

⚙️ Configuration Parameters:

  • poseformer_model_path: Path to pose transformation model
  • save_path: Output directory for rendered results
  • max_single_batch: Maximum batch size for memory management

💡 Usage Examples​

🚀 Basic Dataset Processing​

from GBC.utils.data_preparation.data_preparation_cfg import AMASSDatasetCfg

# Configure for your dataset
dataset_cfg = AMASSDatasetCfg(
    root_dir="/path/to/your/amass/dataset",
    num_betas=16,
    num_dmpls=8,
    load_hands=False  # Set True if you need hand motions
)

🔄 Motion Filtering Setup​

from GBC.utils.data_preparation.data_preparation_cfg import FilterCfg

# Configure filtering for your robot's control frequency
filter_cfg = FilterCfg(
    filter_cutoff=5.0,      # Adjust based on motion type
    filter_sample_rate=50.0, # Match your control frequency
    filter_order=2          # Balance smoothing vs delay
)

🤖 Robot-Specific Configuration​

from GBC.utils.data_preparation.data_preparation_cfg import RobotKinematicsCfg
import torch

# Create robot-specific configuration
class MyRobotCfg(RobotKinematicsCfg):
    mapping_table = {
        'Pelvis': 'your_base_link',
        'L_Hip': 'your_left_hip_link',
        'R_Hip': 'your_right_hip_link',
        # Add your complete mapping
    }
    
    offset_map = {
        'your_end_effector_link': torch.tensor([0.1, 0.0, 0.0]),
        # Add offsets as needed
    }

robot_cfg = MyRobotCfg()

🚀 Complete Pipeline Configuration​

from GBC.utils.data_preparation.data_preparation_cfg import AMASSActionConverterCfg

# Configure complete action conversion pipeline
converter_cfg = AMASSActionConverterCfg(
    # Dataset settings
    root_dir="/path/to/amass/dataset",
    interpolate_fps=50,
    
    # Model paths
    pose_transformer_path="/path/to/pose/transformer.pt",
    smpl_fits_dir="/path/to/smplh/fits",
    
    # Output settings
    export_path="/path/to/converted/actions",
    batch_size=256,  # Adjust based on GPU memory
    visualize=True   # Enable for validation
)

⚙️ Configuration Guidelines​

🎯 Robot Adaptation Checklist​

  1. Joint Mapping: Update mapping_table for your robot's URDF structure
  2. Position Offsets: Configure offset_map based on SMPL+H fitting results
  3. Filter Parameters: Adjust cutoff frequency for your robot's dynamics
  4. Batch Sizes: Optimize based on available GPU memory
  5. File Paths: Ensure all model and data paths are correctly configured

📊 Performance Optimization​

Memory Management:

  • Reduce batch_size if encountering GPU memory issues
  • Adjust max_single_batch for rendering tasks
  • Consider load_hands=False if hand data is not needed

Processing Speed:

  • Increase batch_size for faster processing (if memory allows)
  • Use device="cuda" for GPU acceleration
  • Enable visualize=False for production runs

🔧 Customization Patterns​

Inheritance-Based Customization:

@configclass
class MyCustomCfg(AMASSActionConverterCfg):
    # Override specific parameters
    interpolate_fps: int = 60
    custom_parameter: str = "my_value"
    
    def __post_init__(self):
        super().__post_init__()
        # Add custom initialization logic

Composition-Based Configuration:

# Create specialized configurations
my_filter = FilterCfg(filter_cutoff=7.0)
my_robot = MyRobotCfg()

# Combine in pipeline configuration
pipeline_cfg = AMASSActionConverterCfg(
    filter=my_filter,
    # Inherit robot settings via multiple inheritance
)

🚨 Common Configuration Issues​

❌ Path Configuration Errors​

Issue: Incorrect model or dataset paths
Solution: Verify all paths exist and are accessible

❌ Device Mismatch​

Issue: Tensor device conflicts in offset_map
Solution: Ensure all tensors are moved to correct device in __post_init__

❌ Robot Mapping Errors​

Issue: Joint mapping doesn't match URDF structure
Solution: Verify mapping against actual robot joint names

❌ Memory Issues​

Issue: GPU out of memory during processing
Solution: Reduce batch sizes and enable memory-efficient options

🎯 Integration with GBC Workflows​

These configurations serve as the foundation for:

  1. Data Preprocessing: AMASS dataset loading and cleaning
  2. Motion Retargeting: Human-to-robot motion conversion
  3. Training Data Generation: Preparing datasets for policy learning
  4. Validation Pipelines: Visualizing and validating processed data
  5. Production Deployment: Consistent configuration across environments

The modular design allows teams to quickly adapt configurations for different robots, datasets, and processing requirements while maintaining compatibility with the broader GBC framework.