# Core Computation

The core computation module contains the fundamental components for RAPiD feature extraction.

## RAPiDCalculator

The main class for computing RAPiD features from point cloud data.

### Methods

#### `compute_rapid_features(coordinates, reflectivity, k)`

Computes standard RAPiD features for a given point cloud.

**Parameters:**
- `coordinates`: Point cloud coordinates (N, 3)
- `reflectivity`: Reflectivity values (N,)
- `k`: Number of nearest neighbors

**Returns:**
- RAPiD features tensor (N, feature_dim)

#### `compute_range_aware_rapid(coordinates, reflectivity, k_close, k_mid, k_far)`

Computes range-aware RAPiD features with different k values for different ranges.

**Parameters:**
- `coordinates`: Point cloud coordinates (N, 3)
- `reflectivity`: Reflectivity values (N,)
- `k_close`: Neighbors for close range points
- `k_mid`: Neighbors for mid range points
- `k_far`: Neighbors for far range points

### Example

```python
from rapid_seg.core import RAPiDCalculator
import torch

# Initialize calculator
calculator = RAPiDCalculator(device="cuda")

# Sample data
coordinates = torch.randn(1000, 3)
reflectivity = torch.rand(1000)

# Standard RAPiD
features = calculator.compute_rapid_features(coordinates, reflectivity, k=8)

# Range-aware RAPiD
range_features = calculator.compute_range_aware_rapid(
    coordinates, reflectivity, k_close=3, k_mid=8, k_far=2
)
```

## DistanceCalculator

Handles 4D distance computation combining geometric and reflectivity components.

### Methods

#### `compute_4d_distances(coordinates, reflectivity, k)`

Computes 4D distances between points including geometric and reflectivity components.

**Parameters:**
- `coordinates`: Point coordinates (N, 3)
- `reflectivity`: Reflectivity values (N,)
- `k`: Number of nearest neighbors

**Returns:**
- Distance matrix (N, k)
- Neighbor indices (N, k)

### Example

```python
from rapid_seg.core import DistanceCalculator

calculator = DistanceCalculator(device="cuda")
distances, indices = calculator.compute_4d_distances(coordinates, reflectivity, k=8)
```

## ReflectivityMapper

Maps reflectivity values to appropriate feature representations.

### Methods

#### `map_reflectivity(reflectivity, mapping_type="linear")`

Maps raw reflectivity values using different strategies.

**Parameters:**
- `reflectivity`: Raw reflectivity values
- `mapping_type`: Mapping strategy ("linear", "log", "normalized")

**Returns:**
- Mapped reflectivity features

### Example

```python
from rapid_seg.core import ReflectivityMapper

mapper = ReflectivityMapper()
mapped_reflectivity = mapper.map_reflectivity(reflectivity, "log")
```

## SortingModule

Provides lexicographic sorting utilities for point cloud processing.

### Methods

#### `sort_points_lexicographically(coordinates)`

Sorts points using lexicographic ordering for consistent processing.

**Parameters:**
- `coordinates`: Point coordinates (N, 3)

**Returns:**
- Sorted coordinates
- Sorting indices

### Example

```python
from rapid_seg.core import SortingModule

sorter = SortingModule()
sorted_coords, indices = sorter.sort_points_lexicographically(coordinates)
```

## Performance Optimization

The core modules are optimized for high-performance processing:

- **Batch Processing**: Efficient handling of large point clouds
- **Memory Management**: Optimized memory usage with configurable batch sizes
- **GPU Acceleration**: Full CUDA support for all computations
- **Parallel Processing**: Multi-threaded CPU operations when GPU is unavailable