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 operationstyping
- Type annotations and hintsGBC.utils.base.configclass
- Enhanced dataclass functionalityGBC.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
- Joint Mapping: Update
mapping_table
for your robot's URDF structure - Position Offsets: Configure
offset_map
based on SMPL+H fitting results - Filter Parameters: Adjust cutoff frequency for your robot's dynamics
- Batch Sizes: Optimize based on available GPU memory
- 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:
- Data Preprocessing: AMASS dataset loading and cleaning
- Motion Retargeting: Human-to-robot motion conversion
- Training Data Generation: Preparing datasets for policy learning
- Validation Pipelines: Visualizing and validating processed data
- 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.