g3ms-pcp 0.1.0__tar.gz

g3ms_pcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

g3ms_pcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10.12

g3ms_pcp-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: g3ms-pcp
+Version: 0.1.0
+Summary: Small point-cloud utilities built with PyTorch
+Project-URL: Homepage, https://github.com/G3MS-Lab/pcp
+Project-URL: Repository, https://github.com/G3MS-Lab/pcp
+Project-URL: Issues, https://github.com/G3MS-Lab/pcp/issues
+Author-email: Kittipong Tapyou <kittipong.tpy@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: nbformat>=5.11.1; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pcp
+
+Small point-cloud utilities built with PyTorch.
+
+The package currently includes:
+
+- a `PointCloud` tensor wrapper
+- CSV loading
+- farthest-point and random sampling
+- k-nearest-neighbor search
+- Chamfer distance
+- inverse-distance weighted interpolation
+- PointNet classification and segmentation models
+
+## Installation
+
+Install the project in editable mode:
+
+```bash
+pip install -e .
+```
+
+Using `uv`:
+
+```bash
+uv pip install -e .
+```
+
+Python 3.10 or newer is required.
+
+## Basic usage
+
+```python
+import torch
+
+from pcp import PointCloud
+from pcp.distance import chamfer
+from pcp.grouping import knn
+from pcp.sampling import fps, random
+
+cloud = PointCloud(torch.rand(1024, 3))  # (N, C)
+
+sampled = fps(cloud, k=256)
+random_sampled = random(cloud, k=256)
+
+center = torch.tensor([0.5, 0.5, 0.5])
+neighbors = knn(cloud, center, k=16)
+
+distance = chamfer(sampled, random_sampled)
+```
+
+Interpolate scalar or vector values at new coordinates with IDW:
+
+```python
+from pcp.interpolation import IDW
+
+known_points = torch.tensor([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]])
+known_values = torch.tensor([10.0, 20.0, 30.0])
+query_points = torch.tensor([[0.25, 0.25]])
+
+interpolated = IDW(
+    known_points,
+    known_values,
+    query_points,
+    alpha=2.0,
+    n_neighbors=3,
+)
+```
+
+Set `n_neighbors=None` to use every known point. IDW also supports batched
+coordinates `(B, N, C)` and vector values `(B, N, F)`.
+
+Load a point cloud from CSV:
+
+```python
+from pcp.io import read_csv
+
+cloud = read_csv("points.csv")
+```
+
+## PointNet
+
+PointNet models accept batched tensors in `(B, N, C)` format:
+
+- `B`: batch size
+- `N`: number of points
+- `C`: number of input channels
+
+```python
+import torch
+
+from pcp.nn.PointNet import PointNetCls, PointNetSeg
+
+points = torch.randn(4, 1024, 3)  # (B, N, C)
+
+classifier = PointNetCls(
+    in_channels=3,
+    num_classes=10,
+    use_tnet=True,
+)
+class_logits = classifier(points)  # (4, 10)
+
+segmenter = PointNetSeg(
+    in_channels=3,
+    num_classes=4,
+    use_tnet=True,
+)
+point_logits = segmenter(points)  # (4, 4, 1024)
+```
+
+An unbatched `PointCloud` with shape `(N, C)` can be prepared for PointNet with:
+
+```python
+batched_points = cloud.points.unsqueeze(0)  # (1, N, C)
+```
+
+Segmentation logits use `(B, num_classes, N)`, which can be passed directly to PyTorch's `CrossEntropyLoss` with targets shaped `(B, N)`.
+
+## Source layout
+
+```text
+src/pcp/
+├── core/       # PointCloud
+├── distance/   # Chamfer distance
+├── grouping/   # k-nearest neighbors
+├── interpolation/ # inverse-distance weighting
+├── io/         # CSV loading
+├── nn/         # PointNet models
+└── sampling/   # FPS and random sampling
+```
+
+## RepKPU point-cloud upsampling
+
+`RepKPU` follows the official architecture: a three-stage PointTransformer
+encoder, deformable RepKPoints Extraction Modules (REM), a KP-Queries
+Generation Module (KGM), and cross-attention that turns queries into
+displacements. The full decoder uses three REM blocks; `simple=True` uses one
+REM block and the simple attention/skip path. The forward result is a tuple
+`(upsampled_points, regularization_loss)`.
+
+This library implementation uses tiled PyTorch neighborhood lookup rather
+than the reference repository's compiled `pointops` CUDA kernels. Its distance
+work remains quadratic in point count, though temporary distance memory is
+bounded by `B * chunk_size * N`; the portable path is intended for patch-sized
+inputs. The encoder and decoder reuse `pcp.grouping.knn` and
+`pcp.grouping.ball_query`; both utilities retain their original return values
+and add optional neighbor-index/validity-mask returns. It does not require
+`pointops`, `einops`, or compiled Chamfer3D.
+
+Inputs are batched coordinates with shape `(B, N, 3)`. The model returns
+coordinates of shape `(B, N * up_rate, 3)`, with each input point followed by
+its generated points. For example:
+
+```python
+import torch
+
+from pcp.nn.RepKPU import RepKPU, RepKPUConfig
+
+config = RepKPUConfig(
+    up_rate=4,
+    encoder_dim=32,
+    out_dim=64,
+    k=16,
+    in_dim=64,
+    kp_dim=64,
+    num_kernel_points=15,
+    trans_dim=128,
+    head_num=4,
+    trans_num=3,
+    simple=False,
+)
+model = RepKPU(config)
+points = torch.rand(2, 256, 3)
+upsampled, reg_loss = model(points)  # (2, 1024, 3), scalar loss
+```
+
+Configuration fields mirror the official PU1K options: encoder width and
+neighbor count, kernel radii and limits, KP dimensions, upsampling rate,
+attention width/depth, and the simple/full decoder switch. The scalar loss is
+the sum of the official deformable-kernel fitting and repulsion terms; include
+it with the task loss during training. Input and output coordinates are
+`(B, N, 3)` and `(B, N * up_rate, 3)`.
+
+The module structure and forward mechanisms follow the official source, but
+this is not a bit-for-bit port: neighborhood search is tiled PyTorch instead
+of `pointops`, and the fixed kernel layouts use a deterministic centered
+Fibonacci sphere instead of `kernel_utils.load_kernels`. Consequently model
+weights and reported results are not checkpoint-compatible with official
+RepKPU. The reference training/evaluation scripts also require their datasets
+and custom Chamfer3D extension. The official code is MIT licensed; its notice
+is included with the RepKPU package code.

g3ms_pcp-0.1.0/README.md

@@ -0,0 +1,191 @@
+# pcp
+
+Small point-cloud utilities built with PyTorch.
+
+The package currently includes:
+
+- a `PointCloud` tensor wrapper
+- CSV loading
+- farthest-point and random sampling
+- k-nearest-neighbor search
+- Chamfer distance
+- inverse-distance weighted interpolation
+- PointNet classification and segmentation models
+
+## Installation
+
+Install the project in editable mode:
+
+```bash
+pip install -e .
+```
+
+Using `uv`:
+
+```bash
+uv pip install -e .
+```
+
+Python 3.10 or newer is required.
+
+## Basic usage
+
+```python
+import torch
+
+from pcp import PointCloud
+from pcp.distance import chamfer
+from pcp.grouping import knn
+from pcp.sampling import fps, random
+
+cloud = PointCloud(torch.rand(1024, 3))  # (N, C)
+
+sampled = fps(cloud, k=256)
+random_sampled = random(cloud, k=256)
+
+center = torch.tensor([0.5, 0.5, 0.5])
+neighbors = knn(cloud, center, k=16)
+
+distance = chamfer(sampled, random_sampled)
+```
+
+Interpolate scalar or vector values at new coordinates with IDW:
+
+```python
+from pcp.interpolation import IDW
+
+known_points = torch.tensor([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]])
+known_values = torch.tensor([10.0, 20.0, 30.0])
+query_points = torch.tensor([[0.25, 0.25]])
+
+interpolated = IDW(
+    known_points,
+    known_values,
+    query_points,
+    alpha=2.0,
+    n_neighbors=3,
+)
+```
+
+Set `n_neighbors=None` to use every known point. IDW also supports batched
+coordinates `(B, N, C)` and vector values `(B, N, F)`.
+
+Load a point cloud from CSV:
+
+```python
+from pcp.io import read_csv
+
+cloud = read_csv("points.csv")
+```
+
+## PointNet
+
+PointNet models accept batched tensors in `(B, N, C)` format:
+
+- `B`: batch size
+- `N`: number of points
+- `C`: number of input channels
+
+```python
+import torch
+
+from pcp.nn.PointNet import PointNetCls, PointNetSeg
+
+points = torch.randn(4, 1024, 3)  # (B, N, C)
+
+classifier = PointNetCls(
+    in_channels=3,
+    num_classes=10,
+    use_tnet=True,
+)
+class_logits = classifier(points)  # (4, 10)
+
+segmenter = PointNetSeg(
+    in_channels=3,
+    num_classes=4,
+    use_tnet=True,
+)
+point_logits = segmenter(points)  # (4, 4, 1024)
+```
+
+An unbatched `PointCloud` with shape `(N, C)` can be prepared for PointNet with:
+
+```python
+batched_points = cloud.points.unsqueeze(0)  # (1, N, C)
+```
+
+Segmentation logits use `(B, num_classes, N)`, which can be passed directly to PyTorch's `CrossEntropyLoss` with targets shaped `(B, N)`.
+
+## Source layout
+
+```text
+src/pcp/
+├── core/       # PointCloud
+├── distance/   # Chamfer distance
+├── grouping/   # k-nearest neighbors
+├── interpolation/ # inverse-distance weighting
+├── io/         # CSV loading
+├── nn/         # PointNet models
+└── sampling/   # FPS and random sampling
+```
+
+## RepKPU point-cloud upsampling
+
+`RepKPU` follows the official architecture: a three-stage PointTransformer
+encoder, deformable RepKPoints Extraction Modules (REM), a KP-Queries
+Generation Module (KGM), and cross-attention that turns queries into
+displacements. The full decoder uses three REM blocks; `simple=True` uses one
+REM block and the simple attention/skip path. The forward result is a tuple
+`(upsampled_points, regularization_loss)`.
+
+This library implementation uses tiled PyTorch neighborhood lookup rather
+than the reference repository's compiled `pointops` CUDA kernels. Its distance
+work remains quadratic in point count, though temporary distance memory is
+bounded by `B * chunk_size * N`; the portable path is intended for patch-sized
+inputs. The encoder and decoder reuse `pcp.grouping.knn` and
+`pcp.grouping.ball_query`; both utilities retain their original return values
+and add optional neighbor-index/validity-mask returns. It does not require
+`pointops`, `einops`, or compiled Chamfer3D.
+
+Inputs are batched coordinates with shape `(B, N, 3)`. The model returns
+coordinates of shape `(B, N * up_rate, 3)`, with each input point followed by
+its generated points. For example:
+
+```python
+import torch
+
+from pcp.nn.RepKPU import RepKPU, RepKPUConfig
+
+config = RepKPUConfig(
+    up_rate=4,
+    encoder_dim=32,
+    out_dim=64,
+    k=16,
+    in_dim=64,
+    kp_dim=64,
+    num_kernel_points=15,
+    trans_dim=128,
+    head_num=4,
+    trans_num=3,
+    simple=False,
+)
+model = RepKPU(config)
+points = torch.rand(2, 256, 3)
+upsampled, reg_loss = model(points)  # (2, 1024, 3), scalar loss
+```
+
+Configuration fields mirror the official PU1K options: encoder width and
+neighbor count, kernel radii and limits, KP dimensions, upsampling rate,
+attention width/depth, and the simple/full decoder switch. The scalar loss is
+the sum of the official deformable-kernel fitting and repulsion terms; include
+it with the task loss during training. Input and output coordinates are
+`(B, N, 3)` and `(B, N * up_rate, 3)`.
+
+The module structure and forward mechanisms follow the official source, but
+this is not a bit-for-bit port: neighborhood search is tiled PyTorch instead
+of `pointops`, and the fixed kernel layouts use a deterministic centered
+Fibonacci sphere instead of `kernel_utils.load_kernels`. Consequently model
+weights and reported results are not checkpoint-compatible with official
+RepKPU. The reference training/evaluation scripts also require their datasets
+and custom Chamfer3D extension. The official code is MIT licensed; its notice
+is included with the RepKPU package code.

g3ms_pcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "g3ms-pcp"
+version = "0.1.0"
+description = "Small point-cloud utilities built with PyTorch"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Kittipong Tapyou", email = "kittipong.tpy@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.0.0",
+    "polars>=1.0.0",
+    "torch>=2.0.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/G3MS-Lab/pcp"
+Repository = "https://github.com/G3MS-Lab/pcp"
+Issues = "https://github.com/G3MS-Lab/pcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "nbformat>=5.11.1",
+    "pytest>=8.0.0",
+    "ruff>=0.5.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pcp"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.venv",
+    "/data",
+    "/notebooks",
+]

g3ms_pcp-0.1.0/src/pcp/__init__.py

@@ -0,0 +1,13 @@
+from pcp import core, distance, grouping, interpolation, io, sampling, nn
+from pcp.core.PointCloud import PointCloud
+
+__all__ = [
+    "core",
+    "distance",
+    "grouping",
+    "interpolation",
+    "io",
+    "sampling",
+    "nn",
+    "PointCloud",
+]

g3ms_pcp-0.1.0/src/pcp/core/PointCloud.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+from typing import Any
+import torch
+
+@dataclass
+class PointCloud:
+    points: torch.Tensor
+    
+    def __init__(self, points: torch.Tensor):
+        self.points = points
+        
+    def __getitem__(self, index: Any):
+        if isinstance(index, tuple):
+            return self.points[index]
+        
+        new_pos = self.points[index]
+        if new_pos.ndim == 2:
+            new_pos = new_pos.unsqueeze(0)
+        
+        return new_pos
+
+    @property
+    def shape(self):
+        return self.points.shape
+
+    def to_numpy(self):
+        return self.points.numpy()
+    

g3ms_pcp-0.1.0/src/pcp/core/__init__.py

@@ -0,0 +1,3 @@
+from pcp.core.PointCloud import PointCloud
+
+__all__ = ["PointCloud"]

g3ms_pcp-0.1.0/src/pcp/distance/__init__.py

@@ -0,0 +1,3 @@
+from pcp.distance.chamfer import chamfer
+
+__all__ = ["chamfer"]

g3ms_pcp-0.1.0/src/pcp/distance/chamfer.py

@@ -0,0 +1,14 @@
+import torch
+
+from pcp.core.PointCloud import PointCloud
+
+
+def chamfer(
+    points_a: PointCloud | torch.Tensor,
+    points_b: PointCloud | torch.Tensor,
+) -> torch.Tensor:
+    a = points_a.points if isinstance(points_a, PointCloud) else points_a
+    b = points_b.points if isinstance(points_b, PointCloud) else points_b
+
+    distances = torch.cdist(a, b)
+    return distances.min(dim=-1).values.mean() + distances.min(dim=-2).values.mean()

g3ms_pcp-0.1.0/src/pcp/grouping/__init__.py

@@ -0,0 +1,5 @@
+from pcp.grouping.ball_query import ball_query
+from pcp.grouping.knn import knn
+from pcp.grouping._query import index_features, index_points
+
+__all__ = ["ball_query", "index_features", "index_points", "knn"]

g3ms_pcp-0.1.0/src/pcp/grouping/_query.py

@@ -0,0 +1,58 @@
+"""Shared tiled nearest-neighbor primitives for point grouping utilities."""
+
+import torch
+
+
+def nearest_indices(
+    points: torch.Tensor,
+    centroids: torch.Tensor,
+    k: int,
+    chunk_size: int = 128,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Return k nearest source indices and distances for batched coordinates."""
+    k = min(k, points.shape[1])
+    index_parts = []
+    distance_parts = []
+    for start in range(0, centroids.shape[1], chunk_size):
+        query = centroids[:, start : start + chunk_size]
+        distances = torch.cdist(query, points)
+        distances, indices = distances.topk(k, dim=-1, largest=False)
+        index_parts.append(indices)
+        distance_parts.append(distances)
+    return torch.cat(index_parts, dim=1), torch.cat(distance_parts, dim=1)
+
+
+def index_points(
+    points: torch.Tensor,
+    indices: torch.Tensor,
+    fill: float = 0.0,
+) -> torch.Tensor:
+    """Gather ``(B,N,C)`` points by ``(B,S[,K])`` indices; ``N`` means padding."""
+    batch, count, channels = points.shape
+    valid = indices < count
+    safe = indices.clamp(max=count - 1)
+    gathered = points.gather(
+        1,
+        safe.reshape(batch, -1).unsqueeze(-1).expand(-1, -1, channels),
+    ).reshape(*indices.shape, channels)
+    return gathered.masked_fill(~valid.unsqueeze(-1), fill)
+
+
+def index_features(
+    features: torch.Tensor,
+    indices: torch.Tensor,
+    fill: float = 0.0,
+) -> torch.Tensor:
+    """Gather ``(B,C,N)`` features into ``(B,C,S,K)`` with sentinel padding."""
+    batch, channels, count = features.shape
+    valid = indices < count
+    safe = indices.clamp(max=count - 1)
+    gathered = (
+        features.transpose(1, 2)
+        .gather(
+            1,
+            safe.reshape(batch, -1).unsqueeze(-1).expand(-1, -1, channels),
+        )
+        .reshape(*indices.shape, channels)
+    )
+    return gathered.permute(0, 3, 1, 2).masked_fill(~valid.unsqueeze(1), fill)

g3ms_pcp-0.1.0/src/pcp/grouping/ball_query.py

@@ -0,0 +1,44 @@
+import torch
+
+from pcp.core.PointCloud import PointCloud
+from pcp.grouping._query import index_points, nearest_indices
+
+
+def ball_query(
+    radius: float,
+    n_samples: int,
+    points: PointCloud | torch.Tensor,
+    centroids: PointCloud | torch.Tensor,
+    return_mask: bool = False,
+):
+    points = points.points if isinstance(points, PointCloud) else points
+    centroids = centroids.points if isinstance(centroids, PointCloud) else centroids
+
+    unbatched = points.ndim == 2 and centroids.ndim == 2
+    if points.ndim == 2:
+        points = points.unsqueeze(0)
+    if centroids.ndim == 2:
+        centroids = centroids.unsqueeze(0)
+
+    _, num_points, _ = points.shape
+    k = min(n_samples, num_points)
+    group_idx, distances = nearest_indices(points, centroids, k)
+    valid = distances <= radius
+
+    first_idx = group_idx[:, :, :1]
+    first_idx = first_idx.repeat(1, 1, k)
+    group_idx = torch.where(valid, group_idx, first_idx)
+
+    if k < n_samples:
+        padding = group_idx[:, :, :1].repeat(1, 1, n_samples - k)
+        group_idx = torch.cat([group_idx, padding], dim=-1)
+        valid = torch.cat([valid, torch.zeros_like(padding, dtype=torch.bool)], dim=-1)
+
+    group_points = index_points(points, group_idx)
+
+    if unbatched:
+        group_idx = group_idx.squeeze(0)
+        group_points = group_points.squeeze(0)
+        valid = valid.squeeze(0)
+    result = (group_idx, group_points)
+    return (*result, valid) if return_mask else result

g3ms_pcp-0.1.0/src/pcp/grouping/knn.py

@@ -0,0 +1,32 @@
+import torch
+
+from pcp.core.PointCloud import PointCloud
+from pcp.grouping._query import index_points, nearest_indices
+
+
+def knn(
+    points: PointCloud | torch.Tensor,
+    centroids: PointCloud | torch.Tensor,
+    k: int,
+    return_indices: bool = False,
+):
+    points = points.points if isinstance(points, PointCloud) else points
+    centroids = centroids.points if isinstance(centroids, PointCloud) else centroids
+
+    unbatched = points.ndim == 2 and centroids.ndim <= 2
+    if centroids.ndim == 1:
+        centroids = centroids.unsqueeze(0)
+
+    if points.ndim == 2:
+        points = points.unsqueeze(0)
+    if centroids.ndim == 2:
+        centroids = centroids.unsqueeze(0)
+    indices, _ = nearest_indices(points, centroids, k)
+    result = index_points(points, indices)
+
+    if unbatched:
+        result = result.squeeze(0)
+        indices = indices.squeeze(0)
+
+    result = PointCloud(result)
+    return (result, indices) if return_indices else result