assets

This module provides centralized configuration management for data paths and assets used throughout the GBC (Generalized Behavior Cloning) framework. It handles automatic path resolution, prefix management, and ensures consistent access to datasets, models, and generated results.

📚 Dependencies

This module requires the following Python packages:

• os (standard library)
• GBC.utils.base.config_class (for the @configclass decorator)

---

🌐 Module Constants

📍 PROJECT_ROOT_DIR

Definition:

PROJECT_ROOT_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..")

🔧 Functionality: Automatically determines the project root directory by navigating up three levels from the current file location. This provides a stable reference point for all relative paths within the GBC framework.

---

🏗️ Configuration Classes

📁 DataPathsCfg

Module Name: GBC.utils.base.assets.DataPathsCfg

Definition:

@configclass
class DataPathsCfg:
    # Configuration attributes for managing data paths

🔧 Functionality: Central configuration class for managing all data paths in the GBC framework. Provides automatic path resolution, prefix management, and organized access to datasets, models, and generated results.

---

📋 Configuration Attributes

🏠 Root and Base Paths

root_path

Type: str
Default: PROJECT_ROOT_DIR
Purpose: Base directory for all project-generated files and outputs

dataset_path

Type: str
Default: "/path/to/your/dataset" (User Configuration Required)
Purpose: Base directory containing all external datasets

⚠️ User Configuration Required: Users must configure this path to point to their local dataset directory containing URDF files, SMPL models, AMASS datasets, and other external data.

---

📦 Dataset Path Management

list_add_dataset_path

Type: list[str]
Default: ["urdf", "smplh_model", "dmpls_model", "amass_dataset", "extra_accad"]
Purpose: List of attribute names that should be prefixed with dataset_path

🔧 Functionality: Controls which path attributes are automatically prefixed with the dataset base path during initialization.

---

🤖 URDF and Robot Models

urdf_path

Type: str
Default: "robots/description/robot.urdf" (Example Path)
Purpose: Path to robot URDF description file

⚠️ User Configuration Required: Configure to point to your specific robot URDF file (e.g., Unitree H1, Go1, or custom robot descriptions).

---

👤 Human Body Models

smplh_model_path

Type: str
Default: "smplh/male/model.npz" (Example Path)
Purpose: Path to SMPL+H human body model files

dmpls_model_path

Type: str
Default: "dmpls/male/model.npz" (Example Path)
Purpose: Path to DMPL human body model files

⚠️ User Configuration Required: Download SMPL/SMPL+H/DMPL models from official sources and configure paths accordingly. Models are required for human motion processing and imitation learning.

---

💃 Motion Capture Datasets

amass_dataset_path

Type: str
Default: "AMASS_FULL/" (Example Path)
Purpose: Path to AMASS (Archive of Motion Capture as Surface Shapes) dataset

extra_accad_path

Type: str
Default: "amass_accad_data/" (Example Path)
Purpose: Path to additional ACCAD motion capture data

⚠️ User Configuration Required: Download AMASS and ACCAD datasets from CMU Graphics Lab and configure paths. These datasets contain human motion capture data essential for imitation learning tasks.

---

🔄 Generated Results Management

list_add_root_path

Type: list[str]
Default: ["smplh_fit_result", "pose_transformer", "converted_actions", "ref_data"]
Purpose: List of attribute names that should be prefixed with root_path

🔧 Functionality: Controls which path attributes are automatically prefixed with the project root path during initialization.

---

🎯 Model and Result Paths

smplh_fit_result_path

Type: str
Default: "fit_results/best_fit.pt" (Example Path)
Purpose: Path to fitted SMPL+H model parameters

pose_transformer_path

Type: str
Default: "models/pose_transformer.pt" (Example Path)
Purpose: Path to trained pose transformation model

converted_actions_path

Type: str
Default: "output/converted_actions" (Example Path)
Purpose: Directory containing processed action sequences

ref_data_path

Type: list[str]
Default: ["output/reference_data"] (Example Path)
Purpose: Paths to reference data for training and evaluation

💡 Note: These paths are automatically created relative to root_path and will be generated by the framework during training and data processing.

---

🔧 Core Methods

🚀 post_init

Definition:

def __post_init__(self) -> None

🔧 Functionality: Automatic path resolution method called after configuration initialization. Processes all attributes defined in list_add_* arrays and applies appropriate path prefixes.

📋 Process:

1. Iterates through all attributes starting with "list_add_"
2. Extracts the corresponding prefix attribute name
3. Applies the prefix to all listed path attributes
4. Handles both single paths and lists of paths
5. Respects absolute paths (leaves them unchanged)

💡 Example Workflow:

# Before __post_init__:
# urdf_path = "robots/robot.urdf"
# dataset_path = "/home/user/dataset"

# After __post_init__:
# urdf_path = "/home/user/dataset/robots/robot.urdf"

---

🔗 __add_prefix

Definition:

def __add_prefix(self, path: str, prefix: str) -> str

📥 Input:

• path (str): The path to process
• prefix (str): The prefix to add if path is relative

📤 Output:

• full_path (str): The processed path with prefix applied if needed

🔧 Functionality: Internal helper method that intelligently adds prefixes to paths. Absolute paths are left unchanged, while relative paths are joined with the specified prefix.

💡 Example Usage:

# Internal usage during __post_init__
result = self.__add_prefix("models/robot.urdf", "/home/user/dataset")
# Result: "/home/user/dataset/models/robot.urdf"

# Absolute paths remain unchanged
result = self.__add_prefix("/absolute/path/file.txt", "/prefix")
# Result: "/absolute/path/file.txt"

---

🌟 Global Configuration Instance

📍 DATA_PATHS

Definition:

DATA_PATHS = DataPathsCfg(
    dataset_path="/path/to/your/dataset",  # Configure for your system
    # Additional overrides as needed
)

🔧 Functionality: Global configuration instance providing centralized access to all data paths throughout the GBC framework. This instance is imported and used by other modules to ensure consistent path resolution.

⚠️ User Configuration Required: Modify the initialization parameters to match your local system setup:

DATA_PATHS = DataPathsCfg(
    dataset_path="/your/local/dataset/path",
    # Uncomment and configure additional paths as needed
    # extra_accad_path="/your/additional/data/path",
)

---

💡 Usage Examples

🚀 Basic Configuration

from GBC.utils.base.assets import DATA_PATHS

# Access configured paths
robot_urdf = DATA_PATHS.urdf_path
smpl_model = DATA_PATHS.smplh_model_path
output_dir = DATA_PATHS.converted_actions_path

🔧 Custom Configuration

from GBC.utils.base.assets import DataPathsCfg

# Create custom configuration
custom_config = DataPathsCfg(
    dataset_path="/custom/dataset/location",
    root_path="/custom/output/location"
)

# All paths are automatically resolved
print(custom_config.urdf_path)  # Prints full resolved path

📁 Path Verification

import os
from GBC.utils.base.assets import DATA_PATHS

# Verify critical paths exist
if not os.path.exists(DATA_PATHS.dataset_path):
    raise FileNotFoundError(f"Dataset path not found: {DATA_PATHS.dataset_path}")

if not os.path.exists(DATA_PATHS.urdf_path):
    raise FileNotFoundError(f"URDF file not found: {DATA_PATHS.urdf_path}")

---

⚙️ Configuration Guide

📋 Required Setup Steps

1. Dataset Directory Setup:

   mkdir -p /your/dataset/path
   cd /your/dataset/path

2. Download Required Models:

   • SMPL/SMPL+H models from SMPL website
   • AMASS dataset from AMASS website
   • Robot URDF files for your specific robot platform

3. Configure Paths:

   # In your local configuration
   DATA_PATHS = DataPathsCfg(
       dataset_path="/your/dataset/path",
       # Add other custom paths as needed
   )

4. Verify Configuration:

   from GBC.utils.base.assets import DATA_PATHS
   import os
   
   # Check all critical paths
   assert os.path.exists(DATA_PATHS.dataset_path)
   assert os.path.exists(DATA_PATHS.urdf_path)
   print("✅ All paths configured correctly!")

---

🔍 Best Practices

✅ Recommended Practices

• Use Absolute Paths: Configure dataset_path with absolute paths for system independence
• Environment Variables: Consider using environment variables for deployment flexibility
• Path Validation: Always verify critical paths exist before starting training
• Backup Configuration: Keep backup copies of working configurations
• Documentation: Document any custom path modifications for team collaboration

⚠️ Common Pitfalls

• Relative Path Issues: Ensure working directory consistency when using relative paths
• Permission Problems: Verify read/write permissions for output directories
• Missing Dependencies: Check that all required datasets and models are downloaded
• Path Separators: The module handles cross-platform path separators automatically

---

🚨 Troubleshooting

Common Issues and Solutions

Issue: FileNotFoundError when accessing model files Solution: Verify dataset_path is correctly configured and files are downloaded

Issue: Permission denied errors Solution: Ensure proper read/write permissions for configured directories

Issue: Paths not resolving correctly Solution: Check that __post_init__ is being called and prefix logic is working

Issue: Cross-platform path issues Solution: Use os.path.join() consistently (handled automatically by the module)