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.