torch_pointcloud

PyTorch library for 3D point cloud deep learning: models, datasets, transforms, and pretrained weights.

Modules:

config –

Environment-variable configuration of cache, model, and data directories and randomness defaults.
datasets –

Benchmark point cloud datasets with disk caching and download helpers.
inferers –

Inference strategies for scenes larger than one forward pass: tiling, windows, and refinement.
layers –

Reusable neural network blocks shared across the model architectures.
lightning –

Optional PyTorch Lightning integration: modules, datamodule, callbacks, and metrics.
losses –

Training criteria for detection, segmentation, and generative models.
models –

Model architectures, the create_model factory, and the pretrained weight registry.
transforms –

Dict-based transforms and their tensor-level functional equivalents.
utils –

Tensor utilities: clustering, voxelization, geometry, serialization, metrics, and I/O.

Functions:

create_model –

Build a registered model, optionally loading pretrained or local checkpoint weights.
list_models –

List registered model names, sorted alphabetically.
register_model –

Register a model entry point under name for task.

create_model ¶

create_model(
    name: str,
    task: Literal["base"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> tuple[Module, Dict[str, Any]]

create_model(
    name: str,
    task: Literal["base"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[False] = False,
    **kwargs: Any,
) -> Module

create_model(
    name: str,
    task: Literal["classification"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> tuple[ClassificationModel, Dict[str, Any]]

create_model(
    name: str,
    task: Literal["classification"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[False] = False,
    **kwargs: Any,
) -> ClassificationModel

create_model(
    name: str,
    task: Literal["segmentation"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> tuple[SegmentationModel, Dict[str, Any]]

create_model(
    name: str,
    task: Literal["segmentation"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[False] = False,
    **kwargs: Any,
) -> SegmentationModel

create_model(
    name: str,
    task: Literal["detection"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> tuple[DetectionModel, Dict[str, Any]]

create_model(
    name: str,
    task: Literal["detection"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[False] = False,
    **kwargs: Any,
) -> DetectionModel

create_model(
    name: str,
    task: Task,
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: bool = False,
    **kwargs: Any,
) -> Any

create_model(
    name: str,
    task: Task,
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: bool = False,
    **kwargs: Any,
) -> Any

Build a registered model, optionally loading pretrained or local checkpoint weights.

Weights load through a head-adapting policy: overriding num_classes (or in_channels) keeps the matching backbone weights and leaves the rebuilt head at its fresh initialization with a warning, while an untouched configuration loads completely. Model keys missing from the checkpoint raise.

Parameters:

name (str) –

Registered model name (see list_models).
task (Task) –

Registry the model belongs to (base, classification, segmentation, or detection).
pretrained (bool, default: False ) –

Load the registered pretrained weights. Mutually exclusive with checkpoint_path.
checkpoint_path (Optional[PathLike], default: None ) –

Local checkpoint to load instead of the registered weights. Supports torch.save files, .safetensors, and Lightning checkpoints (the wrapped network is extracted).
return_info (bool, default: False ) –

Also return the registry entry, with hparams reflecting the effective values.
**kwargs (Any, default: {} ) –

Overrides merged into the registered hparams and passed to the model constructor.

Returns:

Any –

The model, or a (model, info) tuple when return_info is true.

Raises:

ValueError –

If task or name is unknown, or both pretrained and checkpoint_path are passed.
TypeError –

If the entry registers architecture hparams only and the data-dependent arguments (typically in_channels and num_classes) are not passed.
FileNotFoundError –

If the checkpoint file does not exist, or if the registered weights are absent from the models cache and cannot be downloaded.

Building a registered model, overriding its registered hparams, and inspecting its registry entry:

import torch_pointcloud as tp

model = tp.create_model("pointnet.modelnet40", task="classification")
model = tp.create_model("pointnet.modelnet40", task="classification", num_classes=10)
model, info = tp.create_model("pointnet.modelnet40", task="classification", return_info=True)

list_models ¶

list_models(
    name: str = "*",
    *,
    task: Optional[Task] = None,
    pretrained: bool = False,
) -> List[str]

List registered model names, sorted alphabetically.

Parameters:

name (str, default: '*' ) –

Wildcard filter on the registered name (fnmatch syntax, e.g. "pointnext*").
task (Optional[Task], default: None ) –

Restrict the listing to one registry; None lists across all tasks (duplicates removed).
pretrained (bool, default: False ) –

Only list models that ship pretrained weights.

Returns:

List[str] –

The matching model names.

Filtering by name pattern, task, and weight availability:

import torch_pointcloud as tp

classifiers = tp.list_models("pointnext*", task="classification")
with_weights = tp.list_models(task="segmentation", pretrained=True)
everything = tp.list_models()

register_model ¶

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Callable] = None,
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["base"],
) -> Callable[
    [Callable[..., Module]], Callable[..., Module]
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Callable] = None,
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["classification"],
) -> Callable[
    [Callable[..., ClassificationModel]],
    Callable[..., ClassificationModel],
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Callable] = None,
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["segmentation"],
) -> Callable[
    [Callable[..., SegmentationModel]],
    Callable[..., SegmentationModel],
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Callable] = None,
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["detection"],
) -> Callable[
    [Callable[..., DetectionModel]],
    Callable[..., DetectionModel],
]

register_model(
    name: str,
    *,
    task: Task,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Callable] = None,
    weights: Union[str, WeightsDict, None] = None,
) -> Callable

Register a model entry point under name for task.

The decorated callable becomes reachable through create_model. A bare weights URL string is normalized to a WeightsDict, so registry consumers always see the structured form.

Parameters:

name (str) –

Registry name, <architecture>[.<dataset tag>] (e.g. pointnext-sm.scanobjectnn.openpoints).
task (Task) –

Registry the model belongs to (base, classification, segmentation, or detection).
hparams (Optional[Dict[str, Any]], default: None ) –

Default keyword arguments the entry point is called with; create_model kwargs override them.
transform (Optional[Callable], default: None ) –

Evaluation transform reproducing the preprocessing the weights were trained with.
weights (Union[str, WeightsDict, None], default: None ) –

Pretrained checkpoint, either a URL string or a WeightsDict with metadata.

Returns:

Callable –

The decorator registering its target callable.

Registering a classification entry point with weight metadata:

from torch_pointcloud.models import PointNetClassification, WeightsDict, register_model


@register_model(
    "pointnet-demo.scanobjectnn",
    task="classification",
    hparams=dict(in_channels=0, num_classes=15),
    weights=WeightsDict(
        url="hf://my-org/pointnet-demo.scanobjectnn/resolve/main/model.safetensors",
        dataset="scanobjectnn",
        metrics={"OA": 88.20},
    ),
)
def pointnet_demo(**hparams):
    return PointNetClassification(**hparams)