### Install OpenPoints from Source with CUDA

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/README.md

Instructions for cloning the OpenPoints repository, installing with optional dependencies, and building CUDA operators for enhanced performance.

```bash
git clone https://github.com/guochengqian/openpoints.git
cd openpoints

pip install -e .[data,viz,wandb]

# Build CUDA operators
cd cpp/pointnet2_batch && python setup.py install && cd ../..
cd cpp/pointops && python setup.py install && cd ../..
cd cpp/chamfer_dist && python setup.py install && cd ../..
cd cpp/emd && python setup.py install && cd ../..
```

--------------------------------

### Install OpenPoints from Source with CUDA Ops

Source: https://github.com/guochengqian/openpoints/blob/master/README.md

Install OpenPoints from source for full training/evaluation with CUDA operators. This requires cloning the repository and installing PyTorch first.

```bash
git clone --recursive https://github.com/guochengqian/openpoints.git
cd openpoints
pip install -e .[data,viz,wandb]
cd cpp/pointnet2_batch && python setup.py install && cd ../..
cd cpp/pointops && python setup.py install && cd ../..
cd cpp/chamfer_dist && python setup.py install && cd ../..
cd cpp/emd && python setup.py install && cd ../..
```

--------------------------------

### Example: Registering and Building a Model

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Demonstrates how to create a Registry, register a custom model class using the decorator, and then build an instance of that model from a configuration dictionary.

```python
from openpoints.utils import Registry

MODELS = Registry('models')

@MODELS.register_module()
class MyModel(torch.nn.Module):
    def __init__(self, in_channels, num_classes):
        ...

# Build from config
cfg = {'NAME': 'MyModel', 'in_channels': 3, 'num_classes': 40}
model = MODELS.build(cfg)
```

--------------------------------

### Distributed Data Sampler Setup

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/README.md

Shows how to set up a DistributedDataSampler for multi-GPU training with PyTorch, ensuring proper data distribution across processes.

```python
sampler = torch.utils.data.distributed.DistributedSampler(dataset)
loader = torch.utils.data.DataLoader(dataset, sampler=sampler)
```

--------------------------------

### Build Optimizer from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Demonstrates how to build an optimizer using the Optimizer Registry and a configuration dictionary. This example shows how to manually register PyTorch optimizers and then build one with specified learning rate and weight decay.

```python
from openpoints.optim import build_optimizer_from_cfg

# Manually register PyTorch optimizers
from openpoints.optim.optim_factory import OPTIM

# Build optimizer
cfg = {'NAME': 'AdamW', 'lr': 0.001, 'weight_decay': 0.02}
optimizer = build_optimizer_from_cfg(cfg, model)
```

--------------------------------

### Configuration-Driven Training Example

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/README.md

Illustrates a typical configuration structure for training pipelines using YAML or dictionary format, specifying model, optimizer, and scheduler parameters.

```yaml
model:
  NAME: PointNeXt
  depth: 18
  width: 32
optim:
  NAME: AdamW
  lr: 0.001
scheduler:
  sched: cosine
  epochs: 300
```

--------------------------------

### Poly1FocalLoss Usage Example

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/loss.md

Demonstrates how to instantiate and use the Poly1FocalLoss function with sample logits and labels. Ensure the 'openpoints' library is installed.

```python
from openpoints.loss import Poly1FocalLoss

loss_fn = Poly1FocalLoss(
    epsilon=1.0,
    alpha=0.25,
    gamma=2.0
)

logits = torch.randn(32, 40)
labels = torch.randint(0, 40, (32,))
loss = loss_fn(logits, labels)
```

--------------------------------

### Instantiate PolyLRScheduler

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/scheduler.md

Example of creating a PolyLRScheduler instance with custom parameters for optimizer, power, total epochs, minimum LR, and warmup.

```python
from openpoints.scheduler import PolyLRScheduler

scheduler = PolyLRScheduler(
    optimizer,
    power=2.0,
    t_initial=200,
    lr_min=1e-6,
    warmup_t=10
)
```

--------------------------------

### Example Usage of Model Outputs

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/types.md

Demonstrates how to use classification and segmentation logits with PyTorch loss functions.

```python
import torch

# Classification
logits_cls = torch.randn(32, 40)  # [B, num_classes]
loss_cls = torch.nn.functional.cross_entropy(logits_cls, targets)

# Segmentation
logits_seg = torch.randn(8, 50, 4096)  # [B, classes, points]
logits_seg = logits_seg.transpose(1, 2).reshape(-1, 50)  # Reshape for loss
loss_seg = torch.nn.functional.cross_entropy(logits_seg, targets_flat)
```

--------------------------------

### PointNet Model Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the PointNet model. Use 'use_bn' to control batch normalization.

```python
# PointNet Configuration
cfg_pointnet = {
    'NAME': 'PointNet',
    'in_channels': 3,
    'num_classes': 40,
    'use_bn': True
}
```

--------------------------------

### Install OpenPoints Package

Source: https://github.com/guochengqian/openpoints/blob/master/README.md

Install the OpenPoints Python package using pip. This installs the Python library and necessary files for datasets and configs.

```bash
pip install openpoints
```

--------------------------------

### SemanticKITTI Dataset Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the SemanticKITTI dataset, detailing common parameters and split-specific settings for training and validation.

```python
# SemanticKITTI Segmentation
cfg_semantic_kitti = {
    'common': {
        'NAME': 'SemanticKITTI',
        'data_root': '/path/to/semantic_kitti',
        'num_points': 4096,
        'num_classes': 19
    },
    'train': {'split': 'train'},
    'val': {'split': 'val'}
}
```

--------------------------------

### Point Cloud Data Usage Examples

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/types.md

Illustrates how to construct the data dictionary for different tasks like classification, segmentation, and handling variable-length batches with offsets. Imports torch.

```python
import torch

# Classification task: one label per point cloud
data_classification = {
    'pos': torch.randn(32, 1024, 3),    # 32 clouds, 1024 points each
    'x': torch.randn(32, 1024, 3),      # RGB features
    'y': torch.randint(0, 40, (32,))    # 1 label per cloud
}
```

```python
# Segmentation task: one label per point
data_segmentation = {
    'pos': torch.randn(8, 4096, 3),     # 8 point clouds
    'x': torch.randn(8, 4096, 64),      # 64-dimensional features
    'y': torch.randint(0, 50, (8, 4096))  # Label per point
}
```

```python
# Variable-length batch with offsets
data_variable = {
    'pos': torch.randn(8192, 3),        # Concatenated points from all scenes
    'x': torch.randn(8192, 128),
    'y': torch.randint(0, 13, (8192,)),
    'batch': torch.tensor([0]*2048 + [1]*2048 + [2]*2048 + [3]*2048),
    'o': torch.tensor([0, 2048, 4096, 6144, 8192])  # Cumulative offsets
}
```

--------------------------------

### Example Usage of RandomScale

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/transforms.md

Demonstrates how to instantiate and use the RandomScale transform for uniform scaling with Y-axis mirroring.

```python
from openpoints.transforms import RandomScale

# Uniform scaling with potential Y-axis mirroring
transform = RandomScale(
    scale=[0.9, 1.1],
    scale_anisotropic=False,
    mirror=[-1, 0.5, -1]  # 50% chance to mirror Y
)

data = {'pos': points}
scaled = transform(data)
```

--------------------------------

### Example Usage of ConfusionMatrix

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Demonstrates how to initialize ConfusionMatrix, update it with model predictions and ground truth labels from a dataloader, and compute mean IoU and mean accuracy.

```python
from openpoints.utils import ConfusionMatrix

conf_mat = ConfusionMatrix(num_classes=13)

for batch in dataloader:
    preds = model(batch).argmax(dim=1)
    conf_mat.update(preds, batch['label'])

iou = conf_mat.compute_iou()
acc = conf_mat.compute_acc()
miou = iou.mean()
macc = acc.mean()

print(f'mIoU: {miou:.4f}, mAcc: {macc:.4f}')
```

--------------------------------

### PointNeXt Model Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the PointNeXt model. Specify model depth and block type for customization.

```python
# PointNeXt Configuration
cfg_pointnext = {
    'NAME': 'PointNeXt',
    'in_channels': 3,
    'num_classes': 40,
    'depth': 18,              # {12, 18, 34}
    'width': 32,              # Feature dimension
    'drop_path_rate': 0.2,
    'block_type': 'invresfeedforward'
}
```

--------------------------------

### Example Usage of TransformerEncoder

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/layers.md

Demonstrates how to instantiate and use the TransformerEncoder layer with sample input data. Ensure torch and TransformerEncoder are imported.

```python
import torch
from openpoints.models.layers import TransformerEncoder

encoder = TransformerEncoder(dim=256, num_heads=8, mlp_ratio=4.0)

x = torch.randn(2, 1024, 256)  # batch, points, dim
out = encoder(x)
# out shape: [2, 1024, 256]
```

--------------------------------

### Example Usage of AverageMeter

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Demonstrates how to use AverageMeter to track loss and accuracy during a training loop. Ensure dataloader, model, criterion, and batch_size are defined.

```python
from openpoints.utils import AverageMeter

loss_meter = AverageMeter('Loss')
acc_meter = AverageMeter('Accuracy')

for batch in dataloader:
    output = model(batch)
    loss = criterion(output, batch['label'])
    
    loss_meter.update(loss.item(), batch_size)
    acc_meter.update(acc, batch_size)

print(f'Avg Loss: {loss_meter.get_avg():.4f}')
print(f'Avg Acc: {acc_meter.get_avg():.4f}')
```

--------------------------------

### ModelNet40 Dataset Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the ModelNet40 dataset, specifying common parameters and split-specific settings for training, validation, and testing.

```python
# ModelNet40 Classification
cfg_modelnet = {
    'common': {
        'NAME': 'ModelNet40',
        'data_root': '/path/to/modelnet40',
        'num_points': 1024,
        'num_classes': 40
    },
    'train': {'split': 'train'},
    'val': {'split': 'test'},
    'test': {'split': 'test'}
}
```

--------------------------------

### DGCNN Model Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the DGCNN model. Set 'k' for the number of neighbors and 'dynamic_graph' for graph construction.

```python
# DGCNN Configuration
cfg_dgcnn = {
    'NAME': 'DGCNN',
    'in_channels': 3,
    'num_classes': 40,
    'k': 20,                  # Number of neighbors
    'dynamic_graph': True
}
```

--------------------------------

### Setup Distributed Logger

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Sets up a logger for distributed training that logs from rank 0 to avoid duplicate messages. Logs are saved to a file and printed to the console. Specify the save directory, process rank, and an optional filename.

```python
from openpoints.utils import setup_logger_dist
import os

rank = int(os.environ.get('RANK', 0))
logger = setup_logger_dist('outputs/exp1', rank)

logger.info('Starting training...')
```

--------------------------------

### S3DIS Dataset Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Example configuration for the S3DIS dataset, including common parameters and split-specific settings for training and validation. Note the 'test_area' parameter.

```python
# S3DIS Segmentation
cfg_s3dis = {
    'common': {
        'NAME': 'S3DIS',
        'data_root': '/path/to/s3dis',
        'num_points': 4096,
        'num_classes': 13,
        'test_area': 5
    },
    'train': {'split': 'train'},
    'val': {'split': 'val', 'test_area': 5}
}
```

--------------------------------

### Train a Model with OpenPoints

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/00_START_HERE.md

Example of training a model using OpenPoints. Requires a configuration file (config.yaml) and PyTorch. Ensure all necessary components are built from configuration and data is moved to CUDA.

```python
from openpoints.utils import EasyConfig, set_random_seed
from openpoints.models import build_model_from_cfg
from openpoints.loss import build_criterion_from_cfg
from openpoints.optim import build_optimizer_from_cfg
from openpoints.scheduler import build_scheduler_from_cfg
from openpoints.dataset import build_dataloader_from_cfg

# Reproducibility
set_random_seed(42)

# Load configuration (see configuration.md for all options)
cfg = EasyConfig.from_file('config.yaml')

# Build components
model = build_model_from_cfg(cfg.model).cuda()
criterion = build_criterion_from_cfg(cfg.criterion_args)
optimizer = build_optimizer_from_cfg(cfg.optim, model)
scheduler = build_scheduler_from_cfg(cfg.scheduler, optimizer)

# Build data
train_loader = build_dataloader_from_cfg(
    batch_size=cfg.batch_size,
    dataset_cfg=cfg.dataset,
    dataloader_cfg=cfg.dataloader,
    datatransforms_cfg=cfg.datatransforms,
    split='train'
)

# Train
for epoch in range(cfg.num_epochs):
    for batch in train_loader:
        data = {k: v.cuda() for k, v in batch.items() if isinstance(v, torch.Tensor)}
        logits = model(data)
        loss = criterion(logits, data['y'])
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
    scheduler.step(epoch)

```

--------------------------------

### DataLoader Configuration Example

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Configure parameters for the DataLoader, such as the number of workers, collate function, and memory pinning. Adjust 'num_workers' based on your system's capabilities.

```python
cfg_dataloader = {
    'num_workers': 8,         # Number of data loading workers
    'collate_fn': 'default_collate_fn',  # Collate function
    'pin_memory': True
}
```

--------------------------------

### Build Dataset from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Shows how to instantiate a dataset using the Dataset Registry and a configuration dictionary. This includes specifying the dataset name, data root, and other relevant parameters.

```python
from openpoints.dataset import DATASETS, build_dataset_from_cfg

# Build dataset
cfg = {'NAME': 'ModelNet40', 'data_root': '/path/to/data', 'num_points': 1024}
dataset = build_dataset_from_cfg(cfg)
```

--------------------------------

### Install CUDA Operators for Pointnet2

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/errors.md

ImportError for 'openpoints.cpp.pointnet2_batch' indicates CUDA-compiled modules are not installed. Build and install them from source.

```bash
cd openpoints/cpp/pointnet2_batch
python setup.py install

cd ../pointops
python setup.py install

cd ../chamfer_dist
python setup.py install

cd ../emd
python setup.py install
```

--------------------------------

### Create and Register a Class with Registry

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Demonstrates how to create a new registry, register a class using a decorator, and then build an instance from a configuration dictionary.

```python
from openpoints.utils import Registry

# Create a registry
MODELS = Registry('models')

# Register a class
@MODELS.register_module()
class PointNet(torch.nn.Module):
    pass

# Build from config
cfg = {'NAME': 'PointNet', 'in_channels': 3, 'num_classes': 40}
model = MODELS.build(cfg)
```

--------------------------------

### Install Optional Graph Dependencies

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/errors.md

ModuleNotFoundError for 'torch_geometric' suggests optional graph dataset dependencies are missing. Install them using pip.

```bash
pip install torch-geometric torch-sparse torch-scatter
```

--------------------------------

### LayerDecayValueAssigner

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/optimizers.md

Assigns per-layer learning rate scaling for vision transformers. It provides methods to get the learning rate scale for a specific layer and to get the layer ID for a named parameter.

```APIDOC
## LayerDecayValueAssigner

### Description
Assigns per-layer learning rate scaling for vision transformers.

### Constructor
```python
def __init__(self, values: list)
```

### Parameters
#### Parameters
- **values** (list[float]) - Required - LR scaling per layer; values[0] for embedding, values[-1] for head

### Methods
#### get_scale

##### Description
Get the learning rate scale for a layer.

##### Method Signature
```python
def get_scale(self, layer_id: int) -> float
```

##### Parameters
- **layer_id** (int) - Required - Layer ID (0 = embedding, higher = deeper layers)

##### Return Type
`float` — LR scaling factor for this layer.

#### get_layer_id

##### Description
Get the layer ID for a named parameter.

##### Method Signature
```python
def get_layer_id(self, var_name: str) -> int
```

##### Parameters
- **var_name** (str) - Required - Parameter name from model.named_parameters()

##### Return Type
`int` — Layer ID for this parameter.

### Description
Utility for layer-wise learning rate schedules in vision transformers. Maps parameter names to layer IDs and provides per-layer scaling factors. Handles 'blocks.N', 'cls_token', 'pos_embed', 'patch_embed' naming conventions.

### Example
```python
from openpoints.optim import LayerDecayValueAssigner

# Decay schedule: 0.65^(num_layers - layer_id)
num_layers = 12
decay = 0.65
values = [decay ** (num_layers - i) for i in range(num_layers + 1)]

assigner = LayerDecayValueAssigner(values)

# Deeper layers (higher IDs) get smaller LR scaling
scale_embed = assigner.get_scale(0)  # 0.65^12 (smallest)
scale_final = assigner.get_scale(num_layers)  # 1.0 (largest)
```
```

--------------------------------

### Build Method

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Instantiates an object from a configuration dictionary, passing additional keyword arguments.

```python
def build(self, cfg: dict, **kwargs) -> object
```

--------------------------------

### AverageMeter Get Average Method

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Retrieves the current running average of the metric.

```python
def get_avg(self) -> float:
```

--------------------------------

### Build Loss Function from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Demonstrates how to build a loss function using the global Loss Registry and a configuration dictionary. This allows for flexible selection of different loss implementations.

```python
from openpoints.loss import LOSS, build_criterion_from_cfg

# Build loss functions
cfg = {'NAME': 'SmoothCrossEntropy', 'label_smoothing': 0.1}
loss_fn = build_criterion_from_cfg(cfg)
```

--------------------------------

### Build Model from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Shows how to use the global Model Registry to build a model instance from a configuration dictionary. This is the standard way to instantiate models in OpenPoints.

```python
from openpoints.models import MODELS, build_model_from_cfg

# All registered model names
MODELS.module_dict.keys()
# Includes: PointNet, PointNetPlus, DGCNN, PointNeXt, PointMLP, etc.

# Build from config
cfg = {'NAME': 'PointNeXt', 'in_channels': 3, 'num_classes': 40}
model = build_model_from_cfg(cfg)
```

--------------------------------

### Basic Model Training with OpenPoints

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/README.md

Demonstrates the fundamental workflow for training a model using OpenPoints. Ensure you have a 'config.yaml' file and necessary components are built from configuration.

```python
import torch
from openpoints.models import build_model_from_cfg
from openpoints.loss import build_criterion_from_cfg
from openpoints.optim import build_optimizer_from_cfg
from openpoints.scheduler import build_scheduler_from_cfg
from openpoints.dataset import build_dataloader_from_cfg
from openpoints.transforms import build_transforms_from_cfg
from openpoints.utils import EasyConfig, set_random_seed
from easydict import EasyDict as edict

# Set seed for reproducibility
set_random_seed(42)

# Load configuration
cfg = EasyConfig.from_file('config.yaml')

# Build components
model = build_model_from_cfg(cfg.model).cuda()
criterion = build_criterion_from_cfg(cfg.criterion_args)
optimizer = build_optimizer_from_cfg(cfg.optim, model)
scheduler = build_scheduler_from_cfg(cfg.scheduler, optimizer)

# Build dataloader
train_loader = build_dataloader_from_cfg(
    batch_size=cfg.batch_size,
    dataset_cfg=cfg.dataset,
    dataloader_cfg=cfg.dataloader,
    datatransforms_cfg=cfg.datatransforms,
    split='train'
)

# Training loop
for epoch in range(cfg.num_epochs):
    for batch in train_loader:
        data = {k: v.cuda() if isinstance(v, torch.Tensor) else v 
                for k, v in batch.items()}
        
        logits = model(data)
        loss = criterion(logits, data['y'])
        
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
    
    scheduler.step(epoch)
```

--------------------------------

### OpenPoints Library Structure

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/00_START_HERE.md

Illustrates the directory structure and the factory functions used to build components from configuration.

```text
openpoints/
├── models/         → build_model_from_cfg()
├── loss/           → build_criterion_from_cfg()
├── optim/          → build_optimizer_from_cfg()
├── scheduler/      → build_scheduler_from_cfg()
├── transforms/     → build_transforms_from_cfg()
├── dataset/        → build_dataset_from_cfg(), build_dataloader_from_cfg()
├── utils/          → Registry, config, logging, metrics
└── cpp/            → CUDA operators

```

--------------------------------

### Initialize LARS Optimizer

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/optimizers.md

Instantiate the LARS optimizer with model parameters and custom learning rate and momentum.

```python
from openpoints.optim import Lars

optimizer = Lars(model.parameters(), lr=1.0, momentum=0.9, weight_decay=0.0)
```

--------------------------------

### EasyDict Configuration Object

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/types.md

Demonstrates how to define and access configuration parameters using EasyDict. This allows for flexible and intuitive management of model, optimizer, and scheduler settings through dot or dictionary notation.

```python
from easydict import EasyDict as edict

cfg = edict({
    'model': {
        'NAME': 'PointNeXt',
        'in_channels': 3,
        'num_classes': 40,
        'depth': 18,
        'width': 32
    },
    'optim': {
        'NAME': 'AdamW',
        'lr': 0.001,
        'weight_decay': 0.02
    },
    'scheduler': {
        'sched': 'cosine',
        'epochs': 300,
        'warmup_epochs': 20
    }
})

# Access via dot notation
model_name = cfg.model.NAME
learning_rate = cfg.optim.lr

# Access via dict notation
num_classes = cfg['model']['num_classes']
```

--------------------------------

### PlateauLRScheduler Usage Example

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/scheduler.md

Demonstrates how to instantiate and use the PlateauLRScheduler within a training loop. The scheduler is updated with the validation accuracy after each epoch.

```python
from openpoints.scheduler import PlateauLRScheduler

scheduler = PlateauLRScheduler(
 optimizer,
 decay_rate=0.1,
 patience_t=10,
 mode='max'  # for accuracy
)

for epoch in range(epochs):
 train(...)
 val_acc = validate(...)
 scheduler.step(val_acc)
```

--------------------------------

### Build Transform Pipeline from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Illustrates how to construct a data transformation pipeline using the Transform Registry and a configuration dictionary. The configuration specifies different pipelines for training and validation.

```python
from openpoints.transforms import DataTransforms, build_transforms_from_cfg

# All registered transform names
DataTransforms.module_dict.keys()

# Build transform pipeline
cfg = {
    'train': ['RandomRotate', 'RandomScale', 'PointsToTensor'],
    'val': ['PointsToTensor'],
    'kwargs': {'angle': [0, 0, 1]}
}
transform = build_transforms_from_cfg('train', cfg)
```

--------------------------------

### Initialize RAdam Optimizer

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/optimizers.md

Instantiate the RAdam optimizer with model parameters, learning rate, and weight decay.

```python
from openpoints.optim import RAdam

optimizer = RAdam(model.parameters(), lr=0.001, weight_decay=0.01)
```

--------------------------------

### Complete Training Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

This snippet shows a comprehensive configuration for training a point cloud model. It uses EasyDict to structure parameters for the model, loss, optimizer, scheduler, dataset, dataloader, and data transformations.

```python
from easydict import EasyDict as edict

cfg = edict({
    # Model
    'model': {
        'NAME': 'PointNeXt',
        'in_channels': 3,
        'num_classes': 40,
        'depth': 18,
        'width': 32,
        'drop_path_rate': 0.2
    },
    
    # Loss
    'criterion_args': {
        'NAME': 'SmoothCrossEntropy',
        'label_smoothing': 0.1,
        'num_classes': 40
    },
    
    # Optimizer
    'optim': {
        'NAME': 'AdamW',
        'lr': 0.001,
        'weight_decay': 0.02,
        'betas': (0.9, 0.999)
    },
    
    # Learning Rate Scheduler
    'scheduler': {
        'sched': 'cosine',
        'epochs': 300,
        'lr': 0.001,
        'min_lr': 1e-6,
        'warmup_epochs': 20,
        'warmup_lr': 1e-6
    },
    
    # Data
    'dataset': {
        'common': {
            'NAME': 'ModelNet40',
            'data_root': '/path/to/modelnet40',
            'num_points': 1024,
            'num_classes': 40
        },
        'train': {'split': 'train'},
        'val': {'split': 'test'}
    },
    
    'dataloader': {
        'num_workers': 8,
        'collate_fn': 'default_collate_fn'
    },
    
    # Transforms
    'datatransforms': {
        'train': ['RandomRotate', 'RandomScale', 'PointsToTensor'],
        'val': ['PointsToTensor'],
        'kwargs': {
            'angle': [0, 0, 1],
            'scale': [0.8, 1.2]
        },
        'compose_fn': 'Compose'
    },
    
    # Training
    'batch_size': 32,
    'num_epochs': 300,
    'seed': 42,
    'distributed': False
})
```

--------------------------------

### setup_logger_dist

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Sets up distributed logging for multi-GPU training, ensuring logs are saved to a file and printed to the console, with output only from rank 0.

```APIDOC
## setup_logger_dist

### Description
Sets up distributed logging for multi-GPU training.

### Parameters
#### Path Parameters
- **save_dir** (str) - Required - Directory to save log files
- **rank** (int) - Required - Process rank in distributed training
- **filename** (str) - Optional - Log filename (default: 'log.txt')

### Return Type
`logging.Logger` - Configured logger instance.

### Example
```python
from openpoints.utils import setup_logger_dist
import os

rank = int(os.environ.get('RANK', 0))
logger = setup_logger_dist('outputs/exp1', rank)

logger.info('Starting training...')
```
```

--------------------------------

### Install and Use EMD CUDA

Source: https://github.com/guochengqian/openpoints/blob/master/cpp/emd/README.md

Compile the EMD CUDA extension and import the earth_mover_distance function for use in PyTorch. Ensure the compiled library is in the main directory.

```bash
python setup.py install
```

```bash
cp build/lib.linux-x86_64-3.6/emd_cuda.cpython-36m-x86_64-linux-gnu.so .
```

```python
from emd import earth_mover_distance
d = earth_mover_distance(p1, p2, transpose=False)  # p1: B x N1 x 3, p2: B x N2 x 3
```

--------------------------------

### Build Scheduler from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Illustrates how to build a learning rate scheduler from configuration. Unlike other components, schedulers are built directly without a global registry, using a configuration object that defines scheduler type and parameters.

```python
from openpoints.scheduler import build_scheduler_from_cfg

# Build scheduler
cfg = type('cfg', (), {
    'sched': 'cosine',
    'epochs': 300,
    'lr': 0.001,
    'min_lr': 1e-6,
    'warmup_epochs': 20
})()

scheduler = build_scheduler_from_cfg(cfg, optimizer)
```

--------------------------------

### Initialize AdaBelief Optimizer

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/optimizers.md

Instantiate the AdaBelief optimizer with model parameters and learning rate. Decouple weight decay is enabled by default.

```python
from openpoints.optim import AdaBelief

optimizer = AdaBelief(model.parameters(), lr=0.001, decouple=True)
```

--------------------------------

### Conservative Augmentation Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

An example configuration for conservative data augmentation. It uses a narrower scale range and omits more aggressive transforms like rotation and jitter.

```python
# Conservative augmentation
cfg_conservative = {
    'train': ['RandomScale', 'PointsToTensor'],
    'val': ['PointsToTensor'],
    'kwargs': {
        'scale': [0.9, 1.1]
    }
}
```

--------------------------------

### Register and Build Models

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/README.md

Demonstrates how to register custom models using the MODELS.register_module() decorator and then build them from a configuration dictionary.

```python
# Models are registered
@MODELS.register_module()
class MyModel(nn.Module):
    pass

# Then built from config
model = build_model_from_cfg({'NAME': 'MyModel', ...})
```

--------------------------------

### Aggressive Augmentation Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

An example configuration for aggressive data augmentation. It uses a wider range of scales, enables anisotropic scaling, and includes mirroring probabilities.

```python
# Aggressive augmentation
cfg_aggressive = {
    'train': ['RandomRotate', 'RandomScaleAndJitter', 'PointsToTensor'],
    'val': ['PointsToTensor'],
    'kwargs': {
        'angle': [0, 0, 1],
        'scale': [0.5, 1.5],
        'scale_anisotropic': True,
        'jitter_sigma': 0.02,
        'jitter_clip': 0.1,
        'mirror': [0.5, 0.5, -1]
    }
}
```

--------------------------------

### Initialize Distributed Training

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/errors.md

Shows the correct way to initialize distributed training using torch.distributed.init_process_group before using distributed utilities.

```python
import torch.distributed as dist

# In your main script
if __name__ == '__main__':
    torch.cuda.set_device(args.local_rank)
    dist.init_process_group(backend='nccl')
    
    # Now safe to use distributed utilities
    from openpoints.utils import reduce_tensor
    loss_reduced = reduce_tensor(loss)
```

--------------------------------

### Example Usage of DilatedKNN

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/layers.md

Demonstrates how to use the DilatedKNN layer to reduce the number of neighbors from a full k-NN list. Ensure knn_point is available and query is defined.

```python
import torch
from openpoints.models.layers import DilatedKNN

# Get initial neighbors
_, full_indices = knn_point(k=32, query=query)

dilated = DilatedKNN(k=16, dilation=2)
sparse_indices = dilated(full_indices)
# Reduces from 32 to 16 neighbors
```

--------------------------------

### Listing and Checking Registered Components

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

You can retrieve a list of all registered component names, check if a specific component is registered, or get the total number of registered components in a registry.

```python
from openpoints.models import MODELS

# Get all registered model names
all_models = list(MODELS.module_dict.keys())
print(all_models)
# ['PointNet', 'PointNet++', 'DGCNN', ...]

# Check if component is registered
is_registered = 'MyModel' in MODELS
print(is_registered)  # True/False

# Get registry length
num_models = len(MODELS)
print(num_models)  # 25
```

--------------------------------

### Build Model and Criterion from Config

Source: https://github.com/guochengqian/openpoints/blob/master/README.md

Easily build model and criterion components from configuration files. This is useful for setting up training pipelines.

```python
model = build_model_from_cfg(cfg.model)
criterion = build_criterion_from_cfg(cfg.criterion_args)
```

--------------------------------

### Build Dataset from Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/dataset.md

Use this function to create a dataset instance from a configuration dictionary. Ensure the 'NAME' field in the config specifies the dataset type.

```python
from openpoints.dataset import build_dataset_from_cfg
from easydict import EasyDict

cfg = EasyDict({
    'NAME': 'ModelNet40',
    'data_root': '/path/to/modelnet40',
    'num_points': 1024,
    'split': 'train'
})

dataset = build_dataset_from_cfg(cfg)
```

--------------------------------

### Handling Data Type Mismatches in Transforms (Numpy)

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/errors.md

Demonstrates a scenario where a transform expects a tensor but receives a numpy array, causing a TypeError. This example works with CPU transforms.

```python
import numpy as np
from openpoints.transforms import RandomRotate

data = {'pos': np.random.randn(1024, 3)}  # numpy array
transform = RandomRotate()
result = transform(data)
# Works for CPU transforms
```

--------------------------------

### Instantiate and Use MaskedCrossEntropy Loss

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/loss.md

Example of how to instantiate the MaskedCrossEntropy loss function with label smoothing and compute the loss using sample logits, targets, and a mask. The mask determines which elements contribute to the loss.

```python
from openpoints.loss import MaskedCrossEntropy

loss_fn = MaskedCrossEntropy(label_smoothing=0.1)
logits = torch.randn(8, 40, 2048)  # batch, classes, points
targets = torch.randint(0, 40, (8, 2048))
mask = torch.randint(0, 2, (8, 2048))  # 1 where labeled

loss = loss_fn(logits, targets, mask)
```

--------------------------------

### Print Configuration Arguments

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Pretty-prints configuration arguments in a tabular format. Useful for logging and visibility during training. Requires EasyConfig or a dictionary for arguments.

```python
from openpoints.utils import EasyConfig, print_args

cfg = EasyConfig.from_file('config.yaml')
print_args(cfg)
```

--------------------------------

### Initialize TanhLRScheduler

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/scheduler.md

Instantiate the TanhLRScheduler with an optimizer, total training steps/epochs, minimum learning rate, and warmup duration. Ensure the optimizer is already defined.

```python
from openpoints.scheduler import TanhLRScheduler

scheduler = TanhLRScheduler(
    optimizer,
    t_initial=200,
    lr_min=1e-6,
    warmup_t=10
)
```

--------------------------------

### FocalLoss Forward Method

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/loss.md

Computes the focal loss given logits and target labels. The loss is calculated as -α*(1-p_t)^γ*log(p_t), where p_t is the model's confidence in the correct class. This method is suitable for scenarios requiring focus on hard-to-classify examples.

```python
def forward(self, logit: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
    # Implementation details for forward pass would be here
    pass
```

--------------------------------

### resume_exp_directory

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Finds and validates an existing experiment directory for resuming training. Useful for checkpointing and recovery.

```APIDOC
## resume_exp_directory

### Description
Resumes an existing experiment directory for continued training.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **exp_dir** (str) - Required - Base experiment directory
- **resume_id** (str) - Required - Experiment ID or timestamp

### Return Type
`str` — Path to existing experiment directory.

### Example
```python
from openpoints.utils import resume_exp_directory

exp_path = resume_exp_directory('outputs', resume_id='PointNeXt/ModelNet40/2024-01-15_10-30-45')

print(exp_path)
```
```

--------------------------------

### Building Components with Registry.build()

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

The build() method instantiates objects from registered components using a configuration dictionary. It supports standard usage, providing default arguments, and passing extra keyword arguments to the constructor.

```python
from openpoints.utils import Registry

MODELS = Registry('models')

# Standard usage
cfg = {'NAME': 'MyModel', 'in_channels': 3, 'num_classes': 40}
model = MODELS.build(cfg)
```

```python
# With default args
default_args = {'device': 'cuda'}
model = MODELS.build(cfg, default_args=default_args)
```

```python
# Extra kwargs passed to constructor
model = MODELS.build(cfg, extra_param=value)
```

--------------------------------

### print_args

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Prints configuration arguments in a formatted table for better visibility during training and logging.

```APIDOC
## print_args

### Description
Prints configuration arguments in formatted table.

### Parameters
#### Path Parameters
- **args** (dict or EasyConfig) - Required - Configuration to print
- **logger** (Logger) - Optional - Logger object; prints to stdout if None

### Return Type
`None`

### Example
```python
from openpoints.utils import EasyConfig, print_args

cfg = EasyConfig.from_file('config.yaml')
print_args(cfg)
```
```

--------------------------------

### Instantiate and Use FocalLoss

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/loss.md

Demonstrates how to instantiate the FocalLoss with specific gamma and alpha values and then use it to compute loss between generated logits and targets. Ensure that the input tensors match the expected dimensions for logits and targets.

```python
from openpoints.loss import FocalLoss

loss_fn = FocalLoss(gamma=2.0, alpha=0.25)
logits = torch.randn(32, 40)
targets = torch.randint(0, 40, (32,))

loss = loss_fn(logits, targets)
```

--------------------------------

### CosineLRScheduler Initialization

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/scheduler.md

Initializes a CosineLRScheduler with optional linear warmup and restart cycles. Configure parameters like total steps, minimum LR, and warmup settings. The learning rate follows a cosine annealing formula.

```python
from openpoints.scheduler import CosineLRScheduler
import torch

optimizer = torch.optim.AdamW(model.parameters(), lr=0.001)
scheduler = CosineLRScheduler(
    optimizer,
    t_initial=300,
    lr_min=1e-6,
    warmup_t=20,
    warmup_lr_init=1e-6
)

for epoch in range(300):
    train(...)
    scheduler.step(epoch)
```

--------------------------------

### Provide Sensible Defaults

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Include default values for parameters in constructors to allow for easier instantiation and reduce the need for explicit configuration.

```python
# Good: Defaults provided
def __init__(self, in_channels=3, num_classes=40, depth=18, **kwargs):
    pass

# Avoid: Required parameters
def __init__(self, in_channels, num_classes, depth):
    pass
```

--------------------------------

### Initialize ConfusionMatrix

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Initialize ConfusionMatrix with the total number of classes. This is required before updating the matrix with predictions.

```python
class ConfusionMatrix(object)
```

```python
def __init__(self, num_classes: int)
```

--------------------------------

### Use **kwargs for Extensibility

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/registry-guide.md

Utilize `**kwargs` in constructors to gracefully handle and ignore unknown parameters, promoting extensibility without breaking existing code.

```python
# Good: Ignores unknown keys
def __init__(self, in_channels=3, **kwargs):
    self.in_channels = in_channels
    # Other keys in **kwargs are ignored

# Less ideal: Breaks with unknown keys
def __init__(self, in_channels=3):
    self.in_channels = in_channels
```

--------------------------------

### Resume Checkpoint

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Resumes training from a checkpoint by restoring model weights, optimizer state, and learning rate schedule. Returns checkpoint information.

```python
from openpoints.utils import resume_checkpoint

info = resume_checkpoint(
    'outputs/exp1/ckpt_latest.pth',
    model, optimizer, scheduler
)

start_epoch = info['epoch'] + 1
for epoch in range(start_epoch, num_epochs):
    train(...)
```

--------------------------------

### Cosine Annealing Scheduler Configuration

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Configuration for cosine annealing scheduler. Requires total epochs, base learning rate, and optionally warmup parameters.

```python
cfg_cosine = {
    'sched': 'cosine',
    'epochs': 300,
    'lr': 0.001,
    'min_lr': 1e-6,
    'warmup_epochs': 20,
    'warmup_lr': 1e-6
}
```

--------------------------------

### Build Optimizer from Config

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/configuration.md

Use this function to build a PyTorch optimizer from a configuration dictionary. The 'NAME' key must correspond to a registered optimizer.

```python
def build_optimizer_from_cfg(cfg, model, **kwargs) -> torch.optim.Optimizer
```

--------------------------------

### build_dataset_from_cfg

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/dataset.md

Constructs a dataset instance from a configuration dictionary. It supports multiple point cloud datasets like ModelNet, ShapeNet, and more, by identifying the dataset type via the 'NAME' field in the config.

```APIDOC
## build_dataset_from_cfg

### Description
Constructs a dataset instance from configuration.

### Parameters
#### Path Parameters
- None
#### Query Parameters
- None
#### Request Body
- **cfg** (eDICT) - Required - Config dict with 'NAME' field identifying dataset type
- **default_args** (dict) - Optional - Default arguments merged into config

### Request Example
```python
from openpoints.dataset import build_dataset_from_cfg
from easydict import EasyDict

cfg = EasyDict({
    'NAME': 'ModelNet40',
    'data_root': '/path/to/modelnet40',
    'num_points': 1024,
    'split': 'train'
})

dataset = build_dataset_from_cfg(cfg)
```

### Response
#### Success Response (200)
- **torch.utils.data.Dataset** - Dataset instance for point cloud data.

#### Response Example
```json
{
  "example": "dataset_instance"
}
```
```

--------------------------------

### Load Checkpoint

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Loads model weights and optionally optimizer/scheduler states from a checkpoint file. Handles missing keys gracefully.

```python
from openpoints.utils import load_checkpoint

checkpoint = load_checkpoint(
    'outputs/exp1/ckpt_best.pth',
    model=model,
    optimizer=optimizer,
    scheduler=scheduler
)

print(f'Resuming from epoch {checkpoint["epoch"]}')
```

--------------------------------

### build_model_from_cfg

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/models.md

Constructs a model instance from a configuration dictionary. It uses a global registry to find and instantiate the specified model type, passing any additional keyword arguments to the model's constructor.

```APIDOC
## build_model_from_cfg

### Description
Constructs a model instance from a configuration dictionary. It uses a global registry to find and instantiate the specified model type, passing any additional keyword arguments to the model's constructor.

### Parameters
#### Path Parameters
None
#### Query Parameters
None
#### Request Body
- **cfg** (eDICT) - Required - Configuration dictionary with a `NAME` key specifying the model type
- **kwargs** (dict) - Optional - Additional keyword arguments passed to the model constructor

### Request Example
```python
from openpoints.models import build_model_from_cfg
from easydict import EasyDict

# Configuration dictionary
cfg = EasyDict({
    'NAME': 'PointNeXt',
    'in_channels': 3,
    'num_classes': 40,
    'depth': 18,
    'width': 32,
})

# Build the model
model = build_model_from_cfg(cfg)
```

### Response
#### Success Response (200)
- **torch.nn.Module** - The constructed model instance, typically a PyTorch neural network module.

#### Response Example
None provided in source.

### Throws
- **KeyError**: Configuration missing 'NAME' field or NAME not registered
- **TypeError**: cfg is not a dictionary
- **Exception**: Model initialization fails (various — see model class documentation)
```

--------------------------------

### AdamW Optimizer Initialization

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/optimizers.md

Initialize the AdamW optimizer with model parameters, learning rate, and weight decay. Ensure model parameters and a criterion are defined before use.

```python
from openpoints.optim import AdamW
import torch

optimizer = AdamW(model.parameters(), lr=0.001, weight_decay=0.02)

loss = criterion(logits, targets)
loss.backward()
optimizer.step()
optimizer.zero_grad()
```

--------------------------------

### Resume Experiment Directory

Source: https://github.com/guochengqian/openpoints/blob/master/_autodocs/api-reference/utils.md

Finds and validates an existing experiment directory for resuming training. Useful for checkpointing and recovery.

```python
from openpoints.utils import resume_exp_directory

exp_path = resume_exp_directory('outputs', resume_id='PointNeXt/ModelNet40/2024-01-15_10-30-45')

print(exp_path)
```