Metadata-Version: 2.4
Name: torch-points3d-modern
Version: 2.0.0a3
Summary: Community-maintained modern fork of Torch Points3D
Author-email: Thomas Chaton <thomas.chaton.ai@gmail.com>, Nicolas Chaulet <nicolas.chaulet@gmail.com>
Maintainer: Alexandre77777 and Torch Points3D Modern contributors
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/Alexandre77777/torch-points3d-modern
Project-URL: Documentation, https://github.com/Alexandre77777/torch-points3d-modern/tree/main/docs
Project-URL: Issues, https://github.com/Alexandre77777/torch-points3d-modern/issues
Project-URL: Source, https://github.com/Alexandre77777/torch-points3d-modern
Project-URL: Upstream, https://github.com/torch-points3d/torch-points3d
Keywords: 3d,deep-learning,lidar,point-cloud,pytorch,segmentation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE.md
Requires-Dist: hydra-core<1.4,>=1.3.2
Requires-Dist: laspy<3,>=2.5
Requires-Dist: lazrs>=0.6
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: omegaconf<2.4,>=2.3
Requires-Dist: pandas>=2.0
Requires-Dist: plyfile>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: torch>=2.4
Requires-Dist: torch-geometric>=2.5
Requires-Dist: tqdm>=4.66
Requires-Dist: typing-extensions>=4.10
Provides-Extra: compression
Requires-Dist: lazrs>=0.6; extra == "compression"
Provides-Extra: training
Requires-Dist: pytorch-metric-learning>=2.5; extra == "training"
Requires-Dist: tensorboard>=2.16; extra == "training"
Requires-Dist: wandb>=0.17; extra == "training"
Provides-Extra: visualization
Requires-Dist: open3d>=0.18; extra == "visualization"
Requires-Dist: pyvista>=0.43; extra == "visualization"
Provides-Extra: acceleration
Requires-Dist: numba>=0.59; extra == "acceleration"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: lazrs>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: all
Requires-Dist: lazrs>=0.6; extra == "all"
Requires-Dist: numba>=0.59; extra == "all"
Requires-Dist: open3d>=0.18; extra == "all"
Requires-Dist: pyvista>=0.43; extra == "all"
Requires-Dist: pytorch-metric-learning>=2.5; extra == "all"
Requires-Dist: tensorboard>=2.16; extra == "all"
Requires-Dist: wandb>=0.17; extra == "all"
Dynamic: license-file

# Torch Points3D Modern

Torch Points3D Modern is a community-maintained modernization of
[Torch Points3D](https://github.com/torch-points3d/torch-points3d). It keeps
the original task structure and YAML model catalogue while targeting current
Python, PyTorch, CUDA, PyTorch Geometric, Hydra, and NumPy releases.

> **Status:** `2.0.0a3` is an alpha release. This project is an independent
> fork and is not an official release from the original Torch Points3D
> maintainers. Validate accuracy on your own datasets before production use.

The base installation runs on CPU and NVIDIA CUDA without compiling custom
point-cloud extensions. Compatible optional accelerators are detected at
runtime; portable PyTorch implementations remain available as a fallback.

## Supported environment

- Python 3.10–3.12
- PyTorch 2.4 or newer
- PyTorch Geometric 2.5 or newer
- CPU-only execution or NVIDIA CUDA
- Windows, Linux, and macOS where the required PyTorch packages are available

The package distribution is named `torch-points3d-modern`, while the Python
import remains compatible with upstream:

```python
import torch_points3d

print(torch_points3d.__version__)
```

## Model catalogue

All 90 executable configurations in the modern catalogue are covered by
deterministic synthetic forward, loss, and backward validation.

| Task | Configurations | Main families |
|---|---:|---|
| Semantic segmentation | 53 | PointNet, PointNet++, PointCNN, RandLA-Net, KPConv, RSConv, PPNet, PVCNN, SparseConv3D, Minkowski/Res16 U-Net, MS-SVConv |
| Point-cloud registration | 27 | PointNet++, MiniPointNet, KPConv, SparseConv3D, Minkowski/Res16 U-Net, MS-SVConv |
| 3D object detection | 8 | VoteNet with PointNet++, KPConv, RSConv, and sparse U-Net backbones |
| Panoptic segmentation | 2 | PointGroup and PointGroup-PAPER |

List the models installed in the current environment:

```bash
tp3d-models
tp3d-models --task segmentation
tp3d-models --json
```

## Install from GitHub

### 1. Clone the repository

These commands will work after this repository has been published at the URL
declared in `pyproject.toml`:

```bash
git clone https://github.com/Alexandre77777/torch-points3d-modern.git
cd torch-points3d-modern
```

### 2. Create and activate a virtual environment

Linux or macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

Windows PowerShell:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```

### 3. Install PyTorch

For NVIDIA GPU use, first install the PyTorch build recommended for your
driver and CUDA environment by the official
[PyTorch installation selector](https://pytorch.org/get-started/locally/).
CPU users can allow the next command to install the default compatible
PyTorch build.

### 4. Install Torch Points3D Modern

Editable installation for normal development and local use:

```bash
python -m pip install -e .
```

The default installation includes both uncompressed LAS and compressed LAZ
support through Laspy and lazrs.

Verify the installation and the selected CPU/CUDA backends:

```bash
tp3d-doctor
tp3d-models --task segmentation
```

`requirements.txt` is a small wrapper around the canonical `pyproject.toml`
dependencies, including LAS and LAZ support:

```bash
python -m pip install -r requirements.txt
```

## Install from PyPI

Install the current release from PyPI:

```bash
python -m venv .venv
source .venv/bin/activate              # Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install torch-points3d-modern
tp3d-doctor
```

For the tested NVIDIA CUDA 13.0 configuration, install the CUDA-enabled
PyTorch build first, then install Torch Points3D Modern:

```bash
python -m pip install "torch==2.13.0+cu130" --index-url https://download.pytorch.org/whl/cu130
python -m pip install torch-points3d-modern
```

For other drivers and CUDA versions, choose the compatible PyTorch command
from the official installation selector before installing this package.

## Run a model on CPU or CUDA

This complete example creates PointNet, automatically selects CUDA when it is
available, and performs inference on synthetic point features. `input_channels`
is the number of channels in `data.x`; XYZ coordinates are supplied separately
in `data.pos`.

```python
import torch
from torch_geometric.data import Data

from torch_points3d.zoo import create_model

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

model = create_model(
    task="segmentation",
    name="PointNet",
    family="pointnet",
    input_channels=4,
    num_classes=4,
).to(device).eval()

data = Data(
    pos=torch.randn(32, 3),
    x=torch.randn(32, 4),
    batch=torch.zeros(32, dtype=torch.long),
)
model.set_input(data, device)

with torch.inference_mode():
    logits = model()

print(f"device={logits.device}, shape={tuple(logits.shape)}")
```

Real datasets still require task-specific preprocessing. Dense networks expect
`pos[B, N, 3]` and `x[B, N, C]`; PyG networks use concatenated `pos[N, 3]`,
`x[N, C]`, and `batch[N]`; sparse models additionally use integer voxel
coordinates in `coords[N, 3]`.

## Optional dependencies

LAS and LAZ support is installed by default. The `compression` extra remains
accepted for compatibility with existing installation commands.

```bash
python -m pip install -e ".[training]"        # TensorBoard, W&B, metric learning
python -m pip install -e ".[visualization]"   # Open3D and PyVista
python -m pip install -e ".[acceleration]"    # Numba acceleration where supported
python -m pip install -e ".[dev]"             # tests, linting, and package builds
```

## Training and evaluation with Hydra

The original configuration-oriented workflow remains available:

```bash
tp3d-train \
  task=segmentation \
  models=segmentation/randlanet \
  model_name=Randlanet_Conv \
  data=segmentation/s3dis

tp3d-eval task=segmentation checkpoint_dir=/path/to/checkpoint
```

On Windows PowerShell, enter the command on one line or replace each Bash `\`
line continuation with PowerShell's backtick. The root `train.py` and `eval.py`
files remain compatibility wrappers.

## Point-operation backends

| Mode | Availability | Purpose |
|---|---|---|
| `portable` | Always installed | Pure PyTorch CPU/CUDA implementation without compilation |
| `pyg` | Compatible `pyg-lib` wheel | Accelerated k-NN, radius search, and farthest-point sampling |
| `auto` | Default | Uses available accelerated operations and otherwise falls back to `portable` |

Select the backend before importing models:

```bash
export TP3D_POINT_OPS_BACKEND=portable
```

Windows PowerShell:

```powershell
$env:TP3D_POINT_OPS_BACKEND = "portable"
```

Inspect or install an ABI-compatible optional accelerator:

```bash
tp3d-doctor --json
python scripts/install_pyg_acceleration.py --dry-run
python scripts/install_pyg_acceleration.py
```

`pyg-lib` is deliberately not a mandatory dependency because its wheel must
match the installed Python, PyTorch, and CUDA versions.

## Sparse-convolution backends

| Backend | Availability | Notes |
|---|---|---|
| `native` | Always installed | Portable active-voxel PyTorch reference backend for CPU/CUDA |
| `torchsparse` | Optional | Used when a compatible TorchSparse installation is present |
| `minkowski` | Optional | Used when a compatible MinkowskiEngine installation is present |
| `auto` | Recommended interface | Selects an available accelerator and can fall back to `native` |

```python
from torch_points3d.modules.SparseConv3d import nn as sparse_nn

print(sparse_nn.available_backends())
sparse_nn.set_backend("auto")
```

The native backend is the portability and correctness reference. Specialized
sparse engines may be faster on large scenes and should be benchmarked for the
target workload.

## Validation

Fast development checks:

```bash
python -m unittest discover -s test/modern -v
PYTHONPATH=test python -m unittest -v test.test_api test.test_model_checkpoint
python scripts/validate_model_catalogue.py --smoke
```

Windows PowerShell equivalent for the legacy tests:

```powershell
$env:PYTHONPATH = "test"
python -m unittest -v test.test_api test.test_model_checkpoint
```

Full catalogue validation on both execution paths:

```bash
python scripts/validate_model_catalogue.py --device cpu --output reports/catalogue-cpu.json
python scripts/validate_model_catalogue.py --device cuda --output reports/catalogue-cuda.json
```

Without `--device`, the validator selects CUDA when available and otherwise
uses CPU. The synthetic suite checks program and architecture contracts, but
it does not replace retraining and benchmark evaluation on real datasets.
Corrected bugs and different parallel-reduction orders mean that bitwise
identity with legacy extension kernels is not promised.

Build and inspect release artifacts:

```bash
python -m build
python -m twine check --strict dist/*
```

See [CHANGELOG.md](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/CHANGELOG.md),
[the migration guide](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/docs/MIGRATION.md),
and [the model validation matrix](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/docs/MODEL_MATRIX.md)
for detailed compatibility information.

## Upstream sources and model attribution

This repository is derived from
[torch-points3d/torch-points3d](https://github.com/torch-points3d/torch-points3d),
originally developed by Thomas Chaton, Nicolas Chaulet, and contributors. It
also contains adaptations based on the publications and implementations below:

- [PointNet](https://arxiv.org/abs/1612.00593)
- [PointNet++](https://arxiv.org/abs/1706.02413)
- [PointCNN](https://arxiv.org/abs/1801.07791)
- [RandLA-Net](https://arxiv.org/abs/1911.11236)
- [KPConv](https://arxiv.org/abs/1904.08889)
- [RS-CNN](https://arxiv.org/abs/1904.07601)
- [PPNet / PosPool](https://arxiv.org/abs/2007.01294)
- [PVCNN](https://arxiv.org/abs/1907.03739)
- [VoteNet](https://arxiv.org/abs/1904.09664)
- [PointGroup](https://arxiv.org/abs/2004.01658)
- [MinkowskiEngine](https://github.com/NVIDIA/MinkowskiEngine)

More specific source references are retained in model configuration files,
module docstrings, and the
[model validation matrix](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/docs/MODEL_MATRIX.md).
When
publishing research, cite the original Torch Points3D paper and the papers for
the models and datasets actually used.

```bibtex
@inproceedings{tp3d,
  title        = {Torch-Points3D: A Modular Multi-Task Framework for Reproducible Deep Learning on 3D Point Clouds},
  author       = {Chaton, Thomas and Chaulet, Nicolas and Horache, Sofiane and Landrieu, Loic},
  booktitle    = {2020 International Conference on 3D Vision (3DV)},
  year         = {2020},
  organization = {IEEE},
  url          = {https://github.com/torch-points3d/torch-points3d}
}
```

## License

Torch Points3D Modern is distributed under the
[BSD 3-Clause License](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/LICENSE.md)
inherited from the upstream project. The
original copyright notice, license conditions, and disclaimer are preserved.
See the
[attribution notice](https://github.com/Alexandre77777/torch-points3d-modern/blob/main/NOTICE.md)
for the independent-maintenance disclaimer.

Redistributions must retain the copyright notice, license conditions, and
disclaimer as required by BSD-3-Clause. The names of Principia Labs Ltd and
the upstream contributors may not be used to endorse this fork without prior
written permission.
