### Docker Environment Setup Script

Source: https://context7.com/jac99/minkloc3d/llms.txt

Provides bash commands to build and run the Docker container for the project, ensuring a reproducible environment with necessary dependencies like PyTorch and MinkowskiEngine.

```bash
# Build and run the Docker container
cd docker
./build_and_run_docker.sh

# Dockerfile installs:
# - Python 3.8
# - PyTorch 1.9.1 with CUDA 10.2
# - MinkowskiEngine 0.5.4
# - pytorch_metric_learning >= 1.0
# - tensorboard, pandas, scikit-learn, tqdm
```

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

### Dockerfile for MinkLoc3D Environment

Source: https://context7.com/jac99/minkloc3d/llms.txt

An excerpt from the Dockerfile detailing the installation of essential packages including Python, PyTorch with CUDA support, and MinkowskiEngine, along with project requirements.

```dockerfile
# docker/Dockerfile excerpt
FROM nvidia/cuda:10.2-devel-ubuntu18.04

# Install MinkowskiEngine dependencies
RUN apt-get update && apt-get install -y \
    python3.8 python3-pip libopenblas-dev

# Install PyTorch and MinkowskiEngine
RUN pip3 install torch==1.9.1+cu102 -f https://download.pytorch.org/whl/torch_stable.html
RUN pip3 install -U MinkowskiEngine==0.5.4 --install-option="--blas=openblas"

# Install additional requirements
COPY requirements.txt .
RUN pip3 install -r requirements.txt
```

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

### Loss Functions for Metric Learning (PyTorch)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Explains the implementation of BatchHard triplet margin loss and contrastive loss with hard negative mining. It shows how to create these loss functions using `make_loss` from configuration or directly by instantiating the respective classes, and provides an example of their usage with embeddings.

```python
import torch
from models.loss import make_loss, BatchHardTripletLossWithMasks, BatchHardContrastiveLossWithMasks
from misc.utils import MinkLocParams

# Create loss function from configuration
params = MinkLocParams('config/config_baseline.txt', 'models/minkloc3d.txt')
loss_fn = make_loss(params)

# Or create directly with specific parameters
triplet_loss = BatchHardTripletLossWithMasks(
    margin=0.2,
    normalize_embeddings=False
)

contrastive_loss = BatchHardContrastiveLossWithMasks(
    pos_margin=0.2,
    neg_margin=0.65,
    normalize_embeddings=True
)

# Example usage with embeddings
batch_size = 16
embedding_dim = 256
embeddings = torch.randn(batch_size, embedding_dim)
```

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

### Pooling Layers

Source: https://context7.com/jac99/minkloc3d/llms.txt

Provides examples of using different global pooling layers: MAC, SPoC, and GeM for aggregating local features into a global descriptor.

```APIDOC
## Pooling Layers

### Description
Global pooling layers aggregate local features into a single global descriptor. Available options include MAC (max pooling), SPoC (average pooling), and GeM (generalized mean pooling).

### Available Pooling Layers
- **MAC**: Global max pooling.
- **SPoC**: Global average pooling.
- **GeM**: Generalized mean pooling with a learnable parameter `p`.

### Request Example
```python
import torch
import MinkowskiEngine as ME
from layers.pooling import MAC, SPoC, GeM

# Create sparse tensor input
coords = torch.tensor([[0, 0, 0, 0], [0, 1, 1, 1], [0, 2, 2, 2]], dtype=torch.int32)  # batch_idx, x, y, z
features = torch.randn(3, 256)  # 3 points, 256 features each
sparse_tensor = ME.SparseTensor(features=features, coordinates=coords)

# MAC: Maximum Activation of Convolutions (global max pooling)
mac_pool = MAC()
mac_output = mac_pool(sparse_tensor)
print(f"MAC output shape: {mac_output.shape}")

# SPoC: Sum of Pooled Convolutions (global average pooling)
spoc_pool = SPoC()
spoc_output = spoc_pool(sparse_tensor)
print(f"SPoC output shape: {spoc_output.shape}")

# GeM: Generalized Mean Pooling (learnable parameter p)
gem_pool = GeM(p=3, eps=1e-6)
gem_output = gem_pool(sparse_tensor)
print(f"GeM output shape: {gem_output.shape}")
print(f"GeM learnable p: {gem_pool.p.item():.2f}")
```

### Response
#### Success Response (200)
- **output** (torch.Tensor) - The aggregated global descriptor. Shape is typically `[batch_size, num_features]`.

#### Response Example
```json
{
  "MAC output shape": "torch.Size([1, 256])",
  "SPoC output shape": "torch.Size([1, 256])",
  "GeM output shape": "torch.Size([1, 256])",
  "GeM learnable p": "3.00"
}
```
```

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

### Configuration Management with MinkLocParams (Python)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Shows how to use the MinkLocParams class to load and manage training and model configuration from text files. It covers accessing dataset paths, hyperparameters like batch size and learning rate, loss function settings, and model architecture parameters.

```python
from misc.utils import MinkLocParams, ModelParams

# Load full configuration
params = MinkLocParams(
    params_path='config/config_baseline.txt',
    model_params_path='models/minkloc3d.txt'
)

# Access training parameters
print(f"Batch size: {params.batch_size}")              # 16
print(f"Batch size limit: {params.batch_size_limit}")  # 256
print(f"Learning rate: {params.lr}")                   # 0.001
print(f"Epochs: {params.epochs}")                      # 40
print(f"Loss function: {params.loss}")                 # BatchHardTripletMarginLoss
print(f"Margin: {params.margin}")                      # 0.2
print(f"Dataset folder: {params.dataset_folder}")
print(f"Train file: {params.train_file}")              # training_queries_baseline.pickle

# Access model-specific parameters
model_params = params.model_params
print(f"Model: {model_params.model}")                  # MinkFPN_GeM
print(f"Quantization size: {model_params.mink_quantization_size}")  # 0.01
print(f"Feature size: {model_params.feature_size}")    # 256
print(f"Planes: {model_params.planes}")                # [32, 64, 64]
print(f"Layers: {model_params.layers}")                # [1, 1, 1]

# Print all parameters
params.print()
```

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

### INI Configuration File Format

Source: https://context7.com/jac99/minkloc3d/llms.txt

Demonstrates the INI file format used for project configuration, including sections for default parameters, training settings, and model architecture details.

```ini
# config/config_baseline.txt - Training configuration
[DEFAULT]
num_points = 4096
dataset_folder = /data/pointnetvlad/benchmark_datasets

[TRAIN]
num_workers = 4
batch_size = 16
batch_size_limit = 256
batch_expansion_rate = 1.4
batch_expansion_th = 0.7

lr = 1e-3
epochs = 40
scheduler_milestones = 30

aug_mode = 1
weight_decay = 1e-3

loss = BatchHardTripletMarginLoss
normalize_embeddings = False
margin = 0.2

train_file = training_queries_baseline.pickle
```

```ini
# models/minkloc3d.txt - Model configuration
[MODEL]
model = MinkFPN_GeM
mink_quantization_size = 0.01
planes = 32,64,64
layers = 1,1,1
num_top_down = 1
conv0_kernel_size = 5
feature_size = 256
```

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

### Train MinkLoc3D Models (Bash)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Scripts to train MinkLoc3D models using configuration files. Supports different datasets (Baseline, Refined) and includes options for debug mode and visualization. Requires navigating to the 'training' directory.

```bash
cd training
python train.py --config ../config/config_baseline.txt --model_config ../models/minkloc3d.txt
```

```bash
python train.py --config ../config/config_refined.txt --model_config ../models/minkloc3d.txt
```

```bash
python train.py --config ../config/config_baseline.txt --model_config ../models/minkloc3d.txt --debug
```

```bash
python train.py --config ../config/config_baseline.txt --model_config ../models/minkloc3d.txt --visualize
```

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

### Forward Pass with Sparse Tensor Input (PyTorch)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Demonstrates how to prepare a sparse tensor batch and perform a forward pass through a PyTorch model. It includes preparing coordinates, quantizing them, creating batched coordinates, and generating features. The output is an embedding tensor.

```python
device = 'cuda' if torch.cuda.is_available() else 'cpu'
model.to(device)
model.eval()

# Prepare sparse tensor batch
coords = torch.rand(4096, 3)  # Point cloud with 4096 points
quantized_coords = ME.utils.sparse_quantize(coordinates=coords, quantization_size=0.01)
batched_coords = ME.utils.batched_coordinates([quantized_coords])
features = torch.ones((batched_coords.shape[0], 1), dtype=torch.float32)

batch = {'coords': batched_coords.to(device), 'features': features.to(device)}
with torch.no_grad():
    embedding = model(batch)  # Output: (batch_size, output_dim) tensor
    print(f"Descriptor shape: {embedding.shape}")  # torch.Size([1, 256])
```

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

### Generate Training and Evaluation Data (Bash)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Scripts to generate pickle files containing positive/negative point cloud pairs required for training and evaluation. These scripts process raw datasets and create query dictionaries. Requires navigating to the 'generating_queries' directory.

```bash
cd generating_queries
python generate_training_tuples_baseline.py --dataset_root /data/pointnetvlad/benchmark_datasets/
```

```bash
python generate_training_tuples_refine.py --dataset_root /data/pointnetvlad/benchmark_datasets/
```

```bash
python generate_test_sets.py --dataset_root /data/pointnetvlad/benchmark_datasets/
```

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

### Dataset and DataLoader Creation (PyTorch)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Details the creation of PyTorch DataLoaders for training with metric learning, including custom batch samplers and collate functions. It shows how to use `make_dataloaders` with `MinkLocParams` and how to directly instantiate `OxfordDataset` for custom use cases.

```python
import torch
from torch.utils.data import DataLoader
from datasets.dataset_utils import make_dataloaders, make_datasets, make_collate_fn
from datasets.oxford import OxfordDataset, TrainTransform, TrainSetTransform
from datasets.samplers import BatchSampler
from misc.utils import MinkLocParams

# Create dataloaders from configuration
params = MinkLocParams('config/config_baseline.txt', 'models/minkloc3d.txt')
dataloaders = make_dataloaders(params)

# Access train and validation dataloaders
train_loader = dataloaders['train']
if 'val' in dataloaders:
    val_loader = dataloaders['val']

# Iterate through batches
for batch, positives_mask, negatives_mask in train_loader:
    # batch['coords']: batched sparse coordinates
    # batch['features']: point features (ones)
    # positives_mask: (batch_size, batch_size) boolean tensor
    # negatives_mask: (batch_size, batch_size) boolean tensor
    print(f"Batch coords shape: {batch['coords'].shape}")
    print(f"Positives in batch: {torch.sum(positives_mask).item()}")
    print(f"Negatives in batch: {torch.sum(negatives_mask).item()}")
    break

# Create dataset directly for custom use
dataset = OxfordDataset(
    dataset_path='/data/pointnetvlad/benchmark_datasets/',
    query_filename='training_queries_baseline.pickle',
    transform=TrainTransform(aug_mode=1),
    set_transform=TrainSetTransform(aug_mode=1)
)

# Access individual samples
point_cloud, idx = dataset[0]
positives = dataset.get_positives(idx)
non_negatives = dataset.get_non_negatives(idx)
print(f"Point cloud shape: {point_cloud.shape}")  # torch.Size([4096, 3])
print(f"Number of positives: {len(positives)}")
```

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

### Generate Training and Evaluation Tuples (Python)

Source: https://github.com/jac99/minkloc3d/blob/master/README.md

Scripts to generate training and evaluation data tuples from a dataset root. Requires read/write access to the dataset path for saving generated pickles.

```python
python generate_training_tuples_refine.py --dataset_root <dataset_root_path>
python generate_test_sets.py --dataset_root <dataset_root_path>
```

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

### Train MinkLoc3D Models (Python)

Source: https://github.com/jac99/minkloc3d/blob/master/README.md

Commands to train the MinkLoc3D network. Users need to configure dataset paths and batch size limits in configuration files. Training is performed within the 'training' directory.

```python
cd training
python train.py --config ../config/config_baseline.txt --model_config ../models/minkloc3d.txt
python train.py --config ../config/config_refined.txt --model_config ../models/minkloc3d.txt
```

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

### Evaluate Pretrained MinkLoc3D Models (Bash)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Scripts to evaluate trained MinkLoc3D models on various test datasets. Computes recall metrics by loading point clouds, extracting embeddings, and performing nearest neighbor search. Requires navigating to the 'eval' directory.

```bash
cd eval
python evaluate.py \
    --config ../config/config_baseline.txt \
    --model_config ../models/minkloc3d.txt \
    --weights ../weights/minkloc3d_baseline.pth
```

```bash
python evaluate.py \
    --config ../config/config_refined.txt \
    --model_config ../models/minkloc3d.txt \
    --weights ../weights/minkloc3d_refined.pth
```

```bash
python evaluate.py \
    --config ../config/config_baseline.txt \
    --model_config ../models/minkloc3d.txt
```

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

### Generate Training Tuples for Baseline Dataset

Source: https://github.com/jac99/minkloc3d/blob/master/README.md

Executes the script to generate training tuples (positive and negative point clouds) required for training the MinkLoc3D model on the Baseline Dataset. This step must be performed before training or evaluation.

```bash
cd generating_queries/
python generate_training_tuples_baseline.py --dataset_root <dataset_root_path>
```

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

### Create Masks with PyTorch

Source: https://context7.com/jac99/minkloc3d/llms.txt

Demonstrates how to create and manipulate boolean masks using PyTorch tensors. These masks are used to identify positive and negative pairs for loss computation in embedding-based models.

```python
positives_mask = torch.zeros(batch_size, batch_size, dtype=torch.bool)
negatives_mask = torch.ones(batch_size, batch_size, dtype=torch.bool)

# Mark some positive pairs
positives_mask[0, 1:4] = True
positives_mask[1, [0, 2, 3]] = True
negatives_mask[0, 0:5] = False  # Non-negatives include positives
negatives_mask[1, 0:5] = False

# Compute loss
loss, stats, hard_triplets = triplet_loss(embeddings, positives_mask, negatives_mask)

print(f"Loss: {stats['loss']:.4f}")
print(f"Num triplets: {stats['num_triplets']}")
print(f"Non-zero triplets: {stats['num_non_zero_triplets']}")
print(f"Mean positive distance: {stats['mean_pos_pair_dist']:.4f}")
print(f"Mean negative distance: {stats['mean_neg_pair_dist']:.4f}")
```

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

### MinkLoc Model Architecture Definition (Python)

Source: https://context7.com/jac99/minkloc3d/llms.txt

Python code demonstrating how to define and instantiate the MinkLoc model architecture. It shows creation using configuration files or direct parameter specification, utilizing MinkowskiEngine and custom model components.

```python
import torch
import MinkowskiEngine as ME
from models.minkloc import MinkLoc
from models.model_factory import model_factory
from misc.utils import MinkLocParams

# Create model from configuration files
params = MinkLocParams('config/config_baseline.txt', 'models/minkloc3d.txt')
model = model_factory(params)

# Or create model directly with custom parameters
model = MinkLoc(
    model='MinkFPN_GeM',           # Architecture: MinkFPN_GeM, MinkFPN_Max, MinkFPN_NetVlad
    in_channels=1,                  # Input feature channels (1 for point presence)
    feature_size=256,               # Local feature dimensionality
    output_dim=256,                 # Global descriptor dimensionality
    planes=[32, 64, 64],            # Channel dimensions for each layer
    layers=[1, 1, 1],               # Number of residual blocks per layer
    num_top_down=1,                 # Number of top-down FPN connections
    conv0_kernel_size=5             # Initial convolution kernel size
)

# Print model information
model.print_info()
```

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

### Data Augmentation Transforms

Source: https://context7.com/jac99/minkloc3d/llms.txt

Illustrates various data augmentation techniques for point clouds, including jittering, point removal, rotation, flipping, translation, scaling, and shearing, to improve training robustness.

```APIDOC
## Data Augmentation Transforms

### Description
Point cloud augmentation transforms for training robustness. Includes jittering, random point removal, random block removal, rotation, flipping, translation, scaling, and shearing.

### Available Transforms
- **JitterPoints**: Adds random noise to point coordinates.
- **RemoveRandomPoints**: Randomly removes a percentage of points.
- **RemoveRandomBlock**: Randomly removes a block of points.
- **RandomRotation**: Rotates the point cloud around a specified axis.
- **RandomFlip**: Flips the point cloud along specified axes.
- **RandomTranslation**: Translates the point cloud.
- **RandomScale**: Scales the point cloud.
- **RandomShear**: Applies shear transformation to the point cloud.

### Request Example
```python
import torch
import numpy as np
from datasets.oxford import (
    TrainTransform, TrainSetTransform,
    JitterPoints, RemoveRandomPoints, RemoveRandomBlock,
    RandomRotation, RandomFlip, RandomTranslation, RandomScale, RandomShear
)

# Create a sample point cloud (4096 points)
point_cloud = torch.randn(4096, 3)

# Default training transform (applied per-element)
train_transform = TrainTransform(aug_mode=1)
augmented_pc = train_transform(point_cloud.clone())

# Default set transform (applied to entire batch)
set_transform = TrainSetTransform(aug_mode=1)
batch = torch.stack([point_cloud, point_cloud.clone()])  # (2, 4096, 3)
augmented_batch = set_transform(batch)

# Individual transforms for custom pipelines
jitter = JitterPoints(sigma=0.001, clip=0.002, p=1.0)
remove_points = RemoveRandomPoints(r=(0.0, 0.1))  # Remove 0-10% of points
remove_block = RemoveRandomBlock(p=0.4, scale=(0.02, 0.33))

rotation = RandomRotation(
    axis=np.array([0, 0, 1]),  # Rotation around Z-axis
    max_theta=5,               # Max rotation in degrees
    max_theta2=0               # Additional random rotation
)
flip = RandomFlip(p=[0.25, 0.25, 0.0])  # Probability for each axis
translation = RandomTranslation(max_delta=0.01)
scale = RandomScale(min=0.95, max=1.05)
shear = RandomShear(delta=0.1)

# Apply transforms sequentially
pc = point_cloud.clone()
pc = jitter(pc)
pc = remove_points(pc)
pc = remove_block(pc)
pc = rotation(pc)
pc = flip(pc)
pc = translation(pc)
print(f"Augmented point cloud shape: {pc.shape}")
```

### Response
#### Success Response (200)
- **augmented_point_cloud** (torch.Tensor) - The transformed point cloud with shape `[num_points, 3]`.

#### Response Example
```json
{
  "Augmented point cloud shape": "torch.Size([4096, 3])"
}
```
```

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

### Evaluate MinkLoc3D Models (Python)

Source: https://github.com/jac99/minkloc3d/blob/master/README.md

Scripts to evaluate the performance of trained MinkLoc3D models using specified configuration and weight files. Evaluation is performed within the 'eval' directory.

```python
cd eval
python evaluate.py --config ../config/config_baseline.txt --model_config ../models/minkloc3d.txt --weights ../weights/minkloc3d_baseline.pth
python evaluate.py --config ../config/config_refined.txt --model_config ../models/minkloc3d.txt --weights ../weights/minkloc3d_refined.pth
```

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

### MinkFPN Backbone Implementation

Source: https://context7.com/jac99/minkloc3d/llms.txt

Implements a Feature Pyramid Network backbone using MinkowskiEngine for sparse 3D convolutions. It processes sparse input tensors and outputs feature maps suitable for place recognition tasks.

```python
import torch
import MinkowskiEngine as ME
from models.minkfpn import MinkFPN
from MinkowskiEngine.modules.resnet_block import BasicBlock

# Create FPN backbone
backbone = MinkFPN(
    in_channels=1,
    out_channels=256,
    num_top_down=1,
    conv0_kernel_size=5,
    block=BasicBlock,
    layers=(1, 1, 1),
    planes=(32, 64, 64)
)

# Forward pass with sparse tensor
coords = torch.randint(0, 100, (1000, 3))
batched_coords = ME.utils.batched_coordinates([coords])
features = torch.ones((batched_coords.shape[0], 1), dtype=torch.float32)

sparse_input = ME.SparseTensor(features=features, coordinates=batched_coords)
sparse_output = backbone(sparse_input)

print(f"Input points: {sparse_input.shape[0]}")
print(f"Output points: {sparse_output.shape[0]}")
print(f"Output features: {sparse_output.shape[1]}")
```

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

### Evaluation Metrics and Functions

Source: https://context7.com/jac99/minkloc3d/llms.txt

Details on functions for computing place recognition metrics like Recall@N and Average Recall@1%, utilizing KDTree for efficient nearest neighbor search.

```APIDOC
## Evaluation Metrics and Functions

### Description
Functions for computing place recognition metrics including Recall@N and Average Recall@1%. Uses KDTree for efficient nearest neighbor search in the embedding space.

### Core Functions
- **evaluate**: Runs the full evaluation pipeline on specified datasets.
- **evaluate_dataset**: Evaluates the model on a single dataset.
- **get_latent_vectors**: Extracts latent vectors (embeddings) from the model.
- **get_recall**: Computes recall metrics.
- **print_eval_stats**: Formats and prints evaluation statistics.

### Request Example
```python
import torch
import numpy as np
from eval.evaluate import evaluate, evaluate_dataset, get_latent_vectors, get_recall, print_eval_stats
from models.model_factory import model_factory
from misc.utils import MinkLocParams

# Load model and configuration
params = MinkLocParams('config/config_baseline.txt', 'models/minkloc3d.txt')
device = 'cuda' if torch.cuda.is_available() else 'cpu'

model = model_factory(params)
model.load_state_dict(torch.load('weights/minkloc3d_baseline.pth', map_location=device))
model.to(device)
model.eval()

# Run full evaluation on all datasets
stats = evaluate(model, device, params, silent=False)

# Print formatted results
print_eval_stats(stats)
```

### Response
#### Success Response (200)
- **stats** (dict) - A dictionary containing evaluation statistics for each dataset, including average recall, similarity, and Recall@N values.

#### Response Example
```json
{
  "Dataset: oxford": {
    "Avg. top 1% recall": 97.90,
    "Avg. similarity": 0.8234,
    "Avg. recall @N": [93.2, 95.1, 96.0, ...]
  }
}
```
```

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

### Accessing Dataset Metrics

Source: https://context7.com/jac99/minkloc3d/llms.txt

Iterates through dataset statistics to print key performance metrics like average recall and similarity. This is useful for evaluating model performance on different datasets.

```python
for dataset_name, dataset_stats in stats.items():
    print(f"\n{dataset_name}:")
    print(f"  Average Recall@1%: {dataset_stats['ave_one_percent_recall']:.2f}%")
    print(f"  Recall@1: {dataset_stats['ave_recall'][0]:.2f}%")
    print(f"  Recall@5: {dataset_stats['ave_recall'][4]:.2f}%")
    print(f"  Average similarity: {dataset_stats['average_similarity']:.4f}")
```

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

### Minkowski Engine Global Pooling Layers

Source: https://context7.com/jac99/minkloc3d/llms.txt

Implements and demonstrates the usage of global pooling layers (MAC, SPoC, GeM) from Minkowski Engine for aggregating local features in sparse tensors into a single global descriptor.

```python
import torch
import MinkowskiEngine as ME
from layers.pooling import MAC, SPoC, GeM

# Create sparse tensor input
coords = torch.tensor([[0, 0, 0, 0], [0, 1, 1, 1], [0, 2, 2, 2]], dtype=torch.int32)  # batch_idx, x, y, z
features = torch.randn(3, 256)  # 3 points, 256 features each
sparse_tensor = ME.SparseTensor(features=features, coordinates=coords)

# MAC: Maximum Activation of Convolutions (global max pooling)
mac_pool = MAC()
mac_output = mac_pool(sparse_tensor)
print(f"MAC output shape: {mac_output.shape}")  # torch.Size([1, 256])

# SPoC: Sum of Pooled Convolutions (global average pooling)
spoc_pool = SPoC()
spoc_output = spoc_pool(sparse_tensor)
print(f"SPoC output shape: {spoc_output.shape}")  # torch.Size([1, 256])

# GeM: Generalized Mean Pooling (learnable parameter p)
gem_pool = GeM(p=3, eps=1e-6)
gem_output = gem_pool(sparse_tensor)
print(f"GeM output shape: {gem_output.shape}")  # torch.Size([1, 256])
print(f"GeM learnable p: {gem_pool.p.item():.2f}")  # Initial value: 3.0
```

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

### Minkloc3d Evaluation Metrics and Functions

Source: https://context7.com/jac99/minkloc3d/llms.txt

Implements and utilizes functions for evaluating place recognition performance, including Recall@N and Average Recall@1%, using KDTree for efficient nearest neighbor search in embedding spaces.

```python
import torch
import numpy as np
from eval.evaluate import evaluate, evaluate_dataset, get_latent_vectors, get_recall, print_eval_stats
from models.model_factory import model_factory
from misc.utils import MinkLocParams

# Load model and configuration
params = MinkLocParams('config/config_baseline.txt', 'models/minkloc3d.txt')
device = 'cuda' if torch.cuda.is_available() else 'cpu'

model = model_factory(params)
model.load_state_dict(torch.load('weights/minkloc3d_baseline.pth', map_location=device))
model.to(device)
model.eval()

# Run full evaluation on all datasets
stats = evaluate(model, device, params, silent=False)

# Print formatted results
print_eval_stats(stats)
# Output format:
# Dataset: oxford
# Avg. top 1% recall: 97.90   Avg. similarity: 0.8234   Avg. recall @N:
# [93.2, 95.1, 96.0, ...]  # Recall@1 through Recall@25
```

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

### Triplet Loss Computation

Source: https://context7.com/jac99/minkloc3d/llms.txt

Demonstrates how to compute the triplet loss using positive and negative masks for embeddings. It also shows how to print statistics related to the loss.

```APIDOC
## Triplet Loss Computation

### Description
This section shows how to compute the triplet loss using pre-defined positive and negative masks. It includes creating the masks, computing the loss, and printing associated statistics.

### Method
`triplet_loss(embeddings, positives_mask, negatives_mask)`

### Parameters
- **embeddings** (torch.Tensor) - The input embeddings.
- **positives_mask** (torch.Tensor) - A boolean mask indicating positive pairs.
- **negatives_mask** (torch.Tensor) - A boolean mask indicating negative pairs.

### Request Example
```python
import torch

batch_size = 4
embeddings = torch.randn(batch_size, 128) # Example embeddings

positives_mask = torch.zeros(batch_size, batch_size, dtype=torch.bool)
negatives_mask = torch.ones(batch_size, batch_size, dtype=torch.bool)

# Mark some positive pairs
positives_mask[0, 1:4] = True
positives_mask[1, [0, 2, 3]] = True
negatives_mask[0, 0:5] = False
negatives_mask[1, 0:5] = False

# Compute loss (assuming triplet_loss function is defined elsewhere)
# loss, stats, hard_triplets = triplet_loss(embeddings, positives_mask, negatives_mask)

# print(f"Loss: {stats['loss']:.4f}")
# print(f"Num triplets: {stats['num_triplets']}")
# print(f"Non-zero triplets: {stats['num_non_zero_triplets']}")
# print(f"Mean positive distance: {stats['mean_pos_pair_dist']:.4f}")
# print(f"Mean negative distance: {stats['mean_neg_pair_dist']:.4f}")
```

### Response
#### Success Response (200)
- **loss** (float) - The computed triplet loss.
- **stats** (dict) - Dictionary containing statistics like loss, number of triplets, mean positive/negative distances.
- **hard_triplets** (torch.Tensor) - Tensor containing the hard triplets.

#### Response Example
```json
{
  "loss": 0.5678,
  "stats": {
    "loss": 0.5678,
    "num_triplets": 100,
    "num_non_zero_triplets": 50,
    "mean_pos_pair_dist": 0.2345,
    "mean_neg_pair_dist": 0.8765
  },
  "hard_triplets": "[tensor data]"
}
```
```

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

### Point Cloud Data Augmentation Transforms

Source: https://context7.com/jac99/minkloc3d/llms.txt

Provides a suite of data augmentation transforms for point clouds, including jittering, point removal, rotation, flipping, translation, scaling, and shearing, to enhance training robustness.

```python
import torch
import numpy as np
from datasets.oxford import (
    TrainTransform, TrainSetTransform,
    JitterPoints, RemoveRandomPoints, RemoveRandomBlock,
    RandomRotation, RandomFlip, RandomTranslation, RandomScale, RandomShear
)

# Create a sample point cloud (4096 points)
point_cloud = torch.randn(4096, 3)

# Default training transform (applied per-element)
train_transform = TrainTransform(aug_mode=1)
augmented_pc = train_transform(point_cloud.clone())

# Default set transform (applied to entire batch)
set_transform = TrainSetTransform(aug_mode=1)
batch = torch.stack([point_cloud, point_cloud.clone()])  # (2, 4096, 3)
augmented_batch = set_transform(batch)

# Individual transforms for custom pipelines
jitter = JitterPoints(sigma=0.001, clip=0.002, p=1.0)
remove_points = RemoveRandomPoints(r=(0.0, 0.1))  # Remove 0-10% of points
remove_block = RemoveRandomBlock(p=0.4, scale=(0.02, 0.33))

rotation = RandomRotation(
    axis=np.array([0, 0, 1]),  # Rotation around Z-axis
    max_theta=5,               # Max rotation in degrees
    max_theta2=0               # Additional random rotation
)
flip = RandomFlip(p=[0.25, 0.25, 0.0])  # Probability for each axis
translation = RandomTranslation(max_delta=0.01)
scale = RandomScale(min=0.95, max=1.05)
shear = RandomShear(delta=0.1)

# Apply transforms sequentially
pc = point_cloud.clone()
pc = jitter(pc)
pc = remove_points(pc)
pc = remove_block(pc)
pc = rotation(pc)
pc = flip(pc)
pc = translation(pc)
print(f"Augmented point cloud shape: {pc.shape}")  # torch.Size([4096, 3])
```

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

### Configure PYTHONPATH Environment Variable

Source: https://github.com/jac99/minkloc3d/blob/master/README.md

Sets the PYTHONPATH environment variable to include the project root directory, ensuring that internal modules are correctly importable by Python scripts.

```bash
export PYTHONPATH=$PYTHONPATH:/home/.../MinkLoc3D
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.