Overview

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

Modules:

config –

Cache and data directories of the package.
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.
metrics –

Evaluation metrics for classification, segmentation, detection and instance segmentation.
models –

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

Tensor operations on packed point clouds: neighbor search, voxelization, geometry, boxes, and serialization.
optim –

Optimization helpers that torch.optim does not ship.
transforms –

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

Data keys and collation, conversions, the Hub token, optional imports, I/O, random state, checkpoints, and types.

Functions:

create_model –

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

Keep a renamed model reachable under its former name, placed above its register_model decorator.
list_models –

List registered model names, sorted alphabetically.
register_model –

Register a model entry point under name for task.

create_model [source] ¶

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

create_model(
    name: str,
    task: Literal["pretraining"],
    *,
    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, ModelInfoDict]

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["semantic-segmentation"],
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> Tuple[SemanticSegmentationModel, ModelInfoDict]

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

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

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

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

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: None = None,
    *,
    pretrained: bool = False,
    checkpoint_path: Optional[PathLike] = None,
    return_info: Literal[True],
    **kwargs: Any,
) -> Tuple[Module, ModelInfoDict]

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

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

create_model(
    name: str,
    task: Optional[Task] = None,
    *,
    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.

Registered weights load into the registered configuration, then an overridden num_classes rebuilds the head at its fresh initialization (0 drops it). Other overrides (e.g. in_channels) keep the matching weights, and the keys whose shape changed keep their initialization. Model keys missing from the checkpoint raise.

Parameters:

name (str) –

Registered model name (see list_models).
task (Optional[Task], default: None ) –

Registry the model belongs to (pretraining, classification, semantic-segmentation, part-segmentation or detection). Optional when name is registered under a single task.
pretrained (bool, default: False ) –

Load the registered pretrained weights, warning when their license is non-commercial. 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 (ModelInfoDict), with the resolved task and the effective hparams.
**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, if task is omitted for a name registered under several tasks, if both pretrained and checkpoint_path are passed, or if pretrained is requested for an entry that registers no weights.
TypeError –

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

If the model needs an optional dependency that is not installed or does not meet its version requirement; the original error is chained.
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")
model = tp.create_model("pointnet.modelnet40", num_classes=10)
model, info = tp.create_model("pointnet.modelnet40", return_info=True)

deprecated_model [source] ¶

deprecated_model(
    name: str,
    *,
    deprecated_in: str,
    removed_in: Optional[str] = None,
    message: Optional[str] = None,
) -> Callable[[F], F]

Keep a renamed model reachable under its former name, placed above its register_model decorator.

create_model and model_info resolve name to the registered name under its task with a FutureWarning that names both releases. list_models never lists former names, and a model of the same name registered under another task is not affected. Stack one decorator per former name, and delete it in the removed_in release.

Parameters:

name (str) –

Former registry name of the entry, under the task it is registered for.
deprecated_in (str) –

Release that renamed the model (e.g. 0.0.17).
removed_in (Optional[str], default: None ) –

Release that drops the former name, named in the warning; None leaves it unscheduled.
message (Optional[str], default: None ) –

Sentence appended to the warning, e.g. what else changed with the rename.

Returns:

Callable[[F], F] –

The decorator adding the former name to the registry entry of its target callable.

Raises:

ValueError –

If deprecated_in or removed_in is not a version string, if removed_in is not a later release than deprecated_in, if the decorated callable is not registered under exactly one name (the decorator belongs above register_model), or if name is the registered name itself, a registered model of its task or already a former name under its task.

Renaming a registered model while keeping its former name loadable for one release:

from torch_pointcloud.models import PointNetClassification, deprecated_model, register_model


@deprecated_model("pointnet.scanobjectnn", deprecated_in="0.0.17", removed_in="0.0.18")
@register_model("pointnet-base.scanobjectnn", task="classification", hparams=dict(in_channels=0, num_classes=15))
def pointnet_base(**hparams):
    return PointNetClassification(**hparams)

list_models [source] ¶

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="semantic-segmentation", pretrained=True)
everything = tp.list_models()

register_model [source] ¶

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["pretraining"],
) -> Callable[
    [Callable[..., Module]], Callable[..., Module]
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    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[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["semantic-segmentation"],
) -> Callable[
    [Callable[..., SemanticSegmentationModel]],
    Callable[..., SemanticSegmentationModel],
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    weights: Union[str, WeightsDict, None] = None,
    task: Literal["part-segmentation"],
) -> Callable[
    [Callable[..., PartSegmentationModel]],
    Callable[..., PartSegmentationModel],
]

register_model(
    name: str,
    *,
    hparams: Optional[Dict[str, Any]] = None,
    transform: Optional[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    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[Transform] = None,
    input_keys: Sequence[str] = ("x", "pos", "batch"),
    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. A deprecated_model decorator placed above adds the former names of the entry.

Parameters:

name (str) –

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

Registry the model belongs to (pretraining, classification, semantic-segmentation, part-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[Transform], default: None ) –

Evaluation transform reproducing the preprocessing the weights were trained with.
input_keys (Sequence[str], default: ('x', 'pos', 'batch') ) –

Batch keys forward takes positionally, in order; a dotted key reads an attribute (e.g. octree.depth). utils.data.select_inputs gathers them from a collated batch.
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.

Raises:

ValueError –

If task is unknown, or if name is the former name of another model of task.

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)