Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

RAPiD Examples

This directory contains comprehensive examples demonstrating how to use the RAPiD library for point cloud feature extraction. The examples are organized logically from basic usage to advanced applications.

⚠️ Important Notice

This project is NOT published to official package repositories (PyPI, conda-forge, etc.). Local source installation is the ONLY supported method.

❌ NOT Supported:

  • pip install rapid-seg
  • conda install rapid-seg
  • uv pip install rapid-seg
  • Any installation from official package managers

✅ Supported:

  • Local source installation with pip install -e .
  • Local source installation with uv pip install -e .

📁 Example Files

1. 01_getting_started.py - Getting Started Guide

Purpose: Complete introduction to fundamental RAPiD functionality Features:

  • Basic point cloud creation and processing
  • RAPiD feature extraction
  • Configuration management
  • Feature validation and statistics
  • Range-aware processing

Best for: Beginners, first-time users, understanding basic concepts

2. 02_advanced_features.py - Advanced Features

Purpose: Demonstration of advanced RAPiD capabilities Features:

  • Performance benchmarking
  • Multiple configuration testing
  • Range-aware RAPiD processing
  • Custom configuration creation
  • Batch processing
  • Memory usage analysis
  • Feature validation testing

Best for: Advanced users, performance optimization, production use

3. 03_c_rapid_semantic.py - Semantic-Aware RAPiD

Purpose: C-RAPiD (Intra-Class RAPiD) feature extraction Features:

  • Semantic class-aware feature extraction
  • Multi-class point cloud processing
  • Class-specific k-neighbor selection
  • Feature validation and statistics
  • Integration with RAPiDFeatures

Best for: Semantic segmentation, class-aware feature extraction, advanced users

4. 04_memory_optimization.py - Memory Optimization

Purpose: Memory monitoring and optimization strategies Features:

  • Memory usage tracking during computation
  • Memory profiling for different parameters
  • Memory requirement estimation
  • Optimization strategies (batch processing, adaptive k values)
  • Memory cleanup techniques

Best for: Production environments, memory-constrained systems, performance tuning

5. 05_performance_benchmarking.py - Performance Analysis

Purpose: Comprehensive performance benchmarking and optimization Features:

  • Performance testing across different configurations
  • Hardware utilization analysis
  • Scaling behavior with point cloud size
  • CPU vs GPU performance comparison
  • Optimization recommendations

Best for: Performance analysis, hardware selection, production deployment

6. 06_integration_examples.py - Integration Patterns

Purpose: Practical integration patterns and real-world applications Features:

  • Integration with popular 3D vision libraries
  • Pipeline integration examples
  • Data loading and preprocessing
  • Post-processing and analysis
  • Custom workflow examples
  • Error handling and validation

Best for: Production integration, custom workflows, real-world applications

🚀 Running Examples

Prerequisites

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone repository (REQUIRED - no pip install available)
git clone https://github.com/l1997i/rapid-seg.git
cd rapid-seg

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install RAPiD from source (ONLY method available)
uv pip install -e .

# Or install with development dependencies
uv pip install -e ".[dev]"

Basic Execution

# Run getting started example
python examples/01_getting_started.py

# Run advanced features example
python examples/02_advanced_features.py

# Run semantic RAPiD example
python examples/03_c_rapid_semantic.py

# Run memory optimization example
python examples/04_memory_optimization.py

# Run performance benchmarking
python examples/05_performance_benchmarking.py

# Run integration examples
python examples/06_integration_examples.py

With uv Environment

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Run examples
python examples/01_getting_started.py

📊 Expected Output

Getting Started Example

RAPiD Getting Started Guide
============================================================
==================================================
1. Basic RAPiD Usage Demonstration
==================================================
Creating synthetic point cloud data...
Point cloud created: 500 points
Coordinates shape: torch.Size([500, 3])
Reflectivity shape: torch.Size([500])

Creating RAPiD configuration...
Configuration: RAPiDConfig(...)

Initializing RAPiD calculator...
Using device: cuda

Computing RAPiD features...
Using k=8 neighbors
RAPiD features computed successfully!
Features shape: torch.Size([500, 8])
Features dtype: torch.float32
Features device: cuda:0

Feature statistics:
Min value: -0.1234
Max value: 0.5678
Mean value: 0.2345
Std value: 0.3456

Validating features...
Features are valid: True

[... more output ...]

Performance Benchmarking Example

RAPiD Performance Benchmarking and Optimization
======================================================================
System Information
========================================
CPU: 8 cores
CPU Frequency: 2400.0 MHz
RAM: 16.0 GB
GPU: 1 device(s) available
  GPU 0: NVIDIA GeForce RTX 3080 (10.0 GB)

Configuration Performance Comparison
==================================================
  Testing fast configuration...
    k=6, Time: 0.0219s ± 0.0009s
    Memory: 45.23 MB
  Testing balanced configuration...
    k=8, Time: 0.0345s ± 0.0012s
    Memory: 67.89 MB
  Testing accurate configuration...
    k=12, Time: 0.0567s ± 0.0018s
    Memory: 89.45 MB

[... more output ...]

🔧 Customization

Modifying Examples

You can easily modify these examples to:

  • Use your own point cloud data
  • Test different parameters
  • Benchmark on your hardware
  • Integrate with your pipeline

Example: Custom Point Cloud

# Load your own data
from rapid_seg import RAPiDCalculator
import numpy as np

# Your point cloud data
coordinates = np.load("my_coordinates.npy")
reflectivity = np.load("my_reflectivity.npy")

# Convert to torch tensors
coordinates = torch.from_numpy(coordinates).float()
reflectivity = torch.from_numpy(reflectivity).float()

# Process with RAPiD
calculator = RAPiDCalculator(device="cuda")
features = calculator.compute_rapid_features(coordinates, reflectivity, k=10)

📈 Performance Tips

For Large Point Clouds

  • Use GPU acceleration when available
  • Adjust batch sizes based on memory
  • Consider using range-aware processing for sparse clouds
  • Monitor memory usage during processing

For Real-time Applications

  • Use "fast" configuration for speed
  • Reduce k parameter for faster computation
  • Consider preprocessing to reduce point count
  • Use batch processing for multiple clouds

For Production Use

  • Monitor memory usage and implement optimization strategies
  • Use performance benchmarking to select optimal configurations
  • Implement proper error handling and validation
  • Consider semantic-aware processing for better feature quality

🐛 Troubleshooting

Common Issues

  1. CUDA out of memory: Reduce batch size or point count, use memory optimization strategies
  2. Slow performance: Check if GPU is being used, adjust k parameter, run performance benchmarking
  3. Import errors: Ensure RAPiD is properly installed from source with uv
  4. Memory issues: Use memory optimization examples and batch processing

Installation Issues

Remember: This project can ONLY be installed from source, not from pip/conda!

# ❌ This will NOT work:
pip install rapid-seg

# ✅ This IS the correct way:
git clone https://github.com/l1997i/rapid-seg.git
cd rapid-seg
uv pip install -e .

Getting Help

📚 Learning Path

Recommended Order

  1. Start with 01_getting_started.py to understand basic concepts
  2. Progress to 02_advanced_features.py for advanced capabilities
  3. Explore 03_c_rapid_semantic.py for semantic-aware processing
  4. Optimize with 04_memory_optimization.py for production use
  5. Benchmark with 05_performance_benchmarking.py for performance analysis
  6. Integrate with 06_integration_examples.py for real-world applications

Next Steps

After running these examples:

  1. Try with your own point cloud data
  2. Experiment with different configurations
  3. Integrate RAPiD into your 3D vision pipeline
  4. Contribute improvements or new examples

Happy coding with RAPiD! 🚀