Skip to content

Overview

Benchmark point cloud datasets with disk caching and download helpers.

Modules:

  • concat –

    Concatenate several datasets into one flat index space for multi-dataset joint training.

  • dales –

    The DALES dataset.

  • kitti –

    KITTI 3D object detection dataset with calibration loading and coordinate-frame conversion helpers.

  • mix –

    Dataset wrapper that mixes each sample with a random partner via a pairwise transform.

  • modelnet –

    ModelNet10/40 shape classification datasets, including normal-resampled and HDF5 variants.

  • nuscenes –

    nuScenes 3D object detection datasets with sweep aggregation and annotation loading helpers.

  • parislille3d –

    The Paris-Lille-3D (NPM3D) dataset.

  • pointcloud –

    Base class for point cloud datasets cached on disk under a raw/ + processed/ layout.

  • repeat –

    Dataset wrapper that lengthens an epoch by repeating an underlying dataset.

  • s3dis –

    S3DIS indoor scene segmentation datasets with room loading, alignment, and tiling helpers.

  • scannet –

    The ScanNet dataset as described in the paper

  • scanobjectnn –

    ScanObjectNN real-world object classification dataset with its background and perturbation variants.

  • semantic3d –

    The Semantic3D dataset.

  • semantickitti –

    The SemanticKITTI dataset, as described in the paper

  • shapenetpart –

    ShapeNetPart object part segmentation dataset.

  • sunrgbd –

    The SUN RGB-D dataset for 3D object detection, as described in the paper

  • toronto3d –

    The Toronto-3D dataset.

  • utils –

    Download, archive extraction, and hash verification helpers for disk-cached datasets.

Classes:

  • ConcatDataset –

    Concatenates several datasets into one flat index space.

  • SingleDatasetBatchSampler –

    Yields batches whose global indices all come from one dataset of a ConcatDataset.

  • DALES –

    The DALES dataset.

  • KITTI –

    KITTI 3D object-detection dataset (LiDAR points + raw LiDAR-frame ground-truth boxes).

  • MixDataset –

    Draws a second random sample and applies a pairwise mix transform.

  • ModelNet10 –

    The ModelNet10 dataset as described in the paper

  • ModelNet40 –

    The ModelNet40 dataset as described in the paper

  • ModelNet40Hdf5 –

    The pre-sampled HDF5 version of ModelNet40 (modelnet40_ply_hdf5_2048), introduced with

  • ModelNetNormalResampled –

    The ModelNet shapes resampled to 10,000 surface points with normals, as described in the paper

  • NuScenes –

    nuScenes 3D object-detection dataset (LiDAR keyframes + LiDAR-frame ground-truth boxes).

  • NuScenesMini –

    nuScenes mini 3D object-detection dataset: every keyframe of the v1.0-mini release.

  • ParisLille3D –

    The Paris-Lille-3D 10-class benchmark.

  • PointCloudDataset –

    Base class for point-cloud datasets stored under a raw/ + processed/ disk layout.

  • RepeatDataset –

    Repeats a dataset k times so one epoch iterates it k times.

  • RepeatSampler –

    Draws every sample of a dataset its own number of times per epoch.

  • S3DIS –

    The Stanford 3D Indoor Spaces Dataset (S3DIS) dataset, as described in the original paper

  • S3DISHdf5 –

    Pre-processed HDF5 version of the S3DIS dataset used by multiple SOTA reference implementations.

  • ScanNet –

    The ScanNet dataset as described in the paper

  • ScanNet20 –

    ScanNet restricted to the standard 20-class semantic-segmentation benchmark.

  • ScanNet200 –

    ScanNet restricted to the 200-class benchmark, as described in the paper

  • ScanObjectNN –

    The ScanObjectNN dataset of 3D object point clouds, as described in the paper

  • Semantic3D –

    The Semantic3D dataset.

  • SemanticKITTI –

    The SemanticKITTI dataset, as described in the paper

  • ShapeNetPart –

    ShapeNetPart dataset packed into per-split .npy files.

  • SunRGBD –

    The SUN RGB-D dataset for 3D object detection, as described in the paper

  • Toronto3D –

    The Toronto-3D dataset.

ConcatDataset [source] ¶

ConcatDataset(datasets: Sequence[Dataset])

Bases: Dataset

Concatenates several datasets into one flat index space.

Each child dataset keeps its own transform, so datasets from different domains (e.g. ScanNet and S3DIS) train jointly while stamping their own condition key and mapping to their native label space. Pair it with SingleDatasetBatchSampler to keep every batch single-domain so per-dataset normalization statistics (BatchNorm, PDNorm) stay clean.

Parameters:

  • datasets (Sequence[Dataset]) –

    The datasets to concatenate, in order. The first is treated as the main dataset by SingleDatasetBatchSampler (its exhaustion ends the epoch).

Example 
from torch_pointcloud.datasets import ConcatDataset, S3DIS, ScanNet20

dataset = ConcatDataset([ScanNet20(root="data", split="train"), S3DIS(root="data", areas=["Area_1"])])
len(dataset)  # len(scannet) + len(s3dis)
dataset.sizes  # [len(scannet), len(s3dis)]

SingleDatasetBatchSampler [source] ¶

SingleDatasetBatchSampler(
    sizes: Sequence[int],
    ratios: Sequence[int],
    batch_size: int,
    shuffle: bool = True,
    drop_last: bool = True,
    generator: Optional[Generator] = None,
)

Bases: Sampler[List[int]]

Yields batches whose global indices all come from one dataset of a ConcatDataset.

Given the per-dataset sizes and one positive integer ratio per dataset, it partitions each dataset's indices into batches of batch_size and interleaves the datasets round-robin weighted by the ratios. Within a round the first dataset yields ratios[0] batches, the second ratios[1], and so on. The first (main) dataset drives the epoch length: when it is exhausted the epoch ends, while the other datasets restart (reshuffled) as needed. Because every yielded batch is drawn from a single dataset, per-batch normalization (BatchNorm, PDNorm) sees a single domain.

Parameters:

  • sizes (Sequence[int]) –

    Number of samples in each child dataset, in ConcatDataset order.

  • ratios (Sequence[int]) –

    One positive integer sampling weight per dataset, aligned with sizes.

  • batch_size (int) –

    Number of indices per batch.

  • shuffle (bool, default: True ) –

    Shuffle each dataset's indices, reshuffling on restart.

  • drop_last (bool, default: True ) –

    Drop each dataset's trailing partial batch.

  • generator (Optional[Generator], default: None ) –

    Optional torch.Generator for shuffling.

Shape

Each yielded value is a List[int] of length batch_size (or fewer for a trailing batch when drop_last is False).

Example 
import torch
from torch.utils.data import DataLoader, TensorDataset

from torch_pointcloud.datasets import ConcatDataset, SingleDatasetBatchSampler

dataset = ConcatDataset([TensorDataset(torch.zeros(16, 3)), TensorDataset(torch.zeros(8, 3))])
sampler = SingleDatasetBatchSampler(dataset.sizes, ratios=[2, 1], batch_size=4)
loader = DataLoader(dataset, batch_sampler=sampler)
len(loader)  # 6: two batches of the first dataset for one of the second, until the first is exhausted

DALES [source] ¶

DALES(
    root: PathLike,
    *,
    train: bool = True,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
)

Bases: PointCloudDataset

The DALES dataset.

Each sample is one 500 x 500 m tile, returned as a dictionary:

Key Shape Dtype Meaning
pos \((N, 3)\) float32 UTM zone 10N metres, minus the tile's minimum corner
return_number \((N, 1)\) int64 Return number, 1-based
number_of_returns \((N, 1)\) int64 Number of returns of the pulse
segment \((N,)\) int64 Raw class id, 0-8 (0 = unknown, ignored)
name str Tile file name without extension

Reading the LAS files needs the optional laspy package.

Parameters:

  • root (PathLike) –

    Dataset root. Tiles are read from <root>/DALES/raw/dales_las/<split>/<tile>.las, the layout of the dales_semantic_segmentation_las.tar.gz archive extracted under raw/.

  • train (bool, default: True ) –

    Whether to load the 29 training tiles (the default) or the 11 test tiles.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each loaded sample dict at __getitem__ time.

Note

The raw dataset must be requested from the authors (the download form linked from data_url; the data are released under CC BY 3.0 for non-commercial use) and extracted by hand. The expected layout is <root>/DALES/raw/dales_las/{train,test}/<tile>.las.

Example 
from torch_pointcloud.datasets import DALES

dataset = DALES(root="data", train=False)
sample = dataset[0]

Methods:

  • download –

    DALES must be requested from the authors and downloaded by hand.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • split (str) –

    Name of the split directory, "train" or "test".

  • split_dir (str) –

    Directory holding the .las tiles of the split.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

split property ¶

split: str

Name of the split directory, "train" or "test".

split_dir property ¶

split_dir: str

Directory holding the .las tiles of the split.

download [source] ¶

download(force: bool = False) -> None

DALES must be requested from the authors and downloaded by hand.

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises:

  • RuntimeError –

    Always; automatic download is not supported.

KITTI [source] ¶

KITTI(
    root: PathLike,
    *,
    train: bool = True,
    split_file: Optional[PathLike] = None,
    fov: bool = True,
    return_calib: bool = False,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: PointCloudDataset

KITTI 3D object-detection dataset (LiDAR points + raw LiDAR-frame ground-truth boxes).

The raw object split is read from <root>/KITTI/raw/<split>/ and processed once into a per-frame .npy cache (<root>/KITTI/processed_fov/<split>/ when fov=True, else <root>/KITTI/processed/), so each __getitem__ is a flat array read. The whole split is processed; split_file only selects which cached frames to load. Frames are loaded lazily from the cache, so a full split does not need to fit in host memory.

KITTI requires manual download (a license must be accepted), so download=True raises with the download URL rather than fetching anything.

Parameters:

  • root (PathLike) –

    Dataset root; raw data is read from <root>/KITTI/raw/<split>/.

  • train (bool, default: True ) –

    If True, reads the training split directory, otherwise testing.

  • split_file (Optional[PathLike], default: None ) –

    Optional text file of frame ids (one per line) selecting which cached frames to load; defaults to every processed frame.

  • fov (bool, default: True ) –

    Restrict points to the front-camera field of view (requires image_2/). Baked into the cache.

  • return_calib (bool, default: False ) –

    Also emit the calib (the composed \((3, 4)\) LiDAR-to-image matrix \(P_2 [R_0 T_\text{velo}]\) with the perspective-divide row from \(R_0 T_\text{velo}\), the projected_ignore_mask contract) and image_shape (image (height, width)) keys, read lazily at access time from the raw calib/ txt and the image_2/ PNG header (both must be present in the raw split).

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each sample dict (e.g. RelabelBoxes + the model's transform).

  • download (bool, default: False ) –

    Unsupported; raises a RuntimeError pointing at the manual download page when set.

  • force_download (bool, default: False ) –

    Unsupported; raises like download.

  • force_process (bool, default: False ) –

    Reprocess the raw split even if a cache already exists.

  • show_progress (bool, default: True ) –

    Show a progress bar while processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for processing, or None for sequential processing.

Example

Assuming the raw split is extracted under data/KITTI/raw/training/:

from torch_pointcloud.datasets import KITTI

dataset = KITTI(root="data", train=True)
sample = dataset[0]
sample["pos"].shape  # (N, 3)
sample["box"].shape  # (K, 7)

Methods:

  • download –

    KITTI must be downloaded manually after accepting its license.

  • process –

    Convert every raw frame in the split into its .npy cache directory.

  • process_frame –

    Read one raw frame (optionally FOV-filtered) and write its .npy cache.

  • load –

    Enumerate the cached frames to load, honoring split_file when given.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory, suffixed _fov when the clouds are cropped to the camera view.

  • raw_split_dir (Path) –

    Path to the split's raw directory.

  • processed_split_dir (Path) –

    Path to the split's processed cache directory.

  • frame_ids (List[str]) –

    Frame ids of the loaded samples, in dataset order.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, suffixed _fov when the clouds are cropped to the camera view.

raw_split_dir property ¶

raw_split_dir: Path

Path to the split's raw directory.

processed_split_dir property ¶

processed_split_dir: Path

Path to the split's processed cache directory.

frame_ids property ¶

frame_ids: List[str]

Frame ids of the loaded samples, in dataset order.

download [source] ¶

download(force: bool = False) -> None

KITTI must be downloaded manually after accepting its license.

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises: RuntimeError: Always; automatic download is not supported.

process [source] ¶

process(
    force: bool = False,
    num_workers: Optional[int] = None,
    show_progress: bool = True,
) -> None

Convert every raw frame in the split into its .npy cache directory.

Parameters:

  • force (bool, default: False ) –

    Reprocess even if a cache already exists.

  • num_workers (Optional[int], default: None ) –

    Worker processes, or None for sequential processing.

  • show_progress (bool, default: True ) –

    Show a progress bar while processing.

process_frame [source] ¶

process_frame(frame: str) -> None

Read one raw frame (optionally FOV-filtered) and write its .npy cache.

Parameters:

  • frame (str) –

    Frame id, e.g. "000000".

load [source] ¶

load() -> None

Enumerate the cached frames to load, honoring split_file when given.

Raises a RuntimeError listing the missing frame ids when split_file references frames absent from the processed cache.

MixDataset [source] ¶

MixDataset(
    dataset: Dataset,
    mix: Callable[
        [Dict[str, Any], Dict[str, Any]], Dict[str, Any]
    ],
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    seed: Optional[int] = None,
)

Bases: Dataset, Randomizable

Draws a second random sample and applies a pairwise mix transform.

Each source sample is produced by the wrapped dataset (its own transform runs first), then a partner sample is drawn at a random index and merged via mix(data, other). Pairwise mixes such as Mix3D, LaserMix, and PolarMix fit this contract; the mix's own p decides how often the merge actually happens.

Parameters:

  • dataset (Dataset) –

    The wrapped dataset; its own transform runs per source sample before mixing.

  • mix (Callable[[Dict[str, Any], Dict[str, Any]], Dict[str, Any]]) –

    Pairwise transform called as mix(data, other).

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Optional per-sample transform applied after mixing.

  • seed (Optional[int], default: None ) –

    Seed for the partner index; None draws from the global generator (see Randomizable).

Methods:

  • set_random_state –

    Give the object its own random stream, or return it to the global generator.

set_random_state [source] ¶

set_random_state(
    seed: Optional[int] = None,
    state: Optional[Generator] = None,
) -> Self

Give the object its own random stream, or return it to the global generator.

Parameters:

  • seed (Optional[int], default: None ) –

    Seed of a new generator.

  • state (Optional[Generator], default: None ) –

    Generator to draw from, shared with the caller.

Returns:

  • Self –

    The object itself, for chaining.

Raises:

  • ValueError –

    If both seed and state are given.

ModelNet10 [source] ¶

ModelNet10(
    root: PathLike,
    *,
    train: bool = True,
    classes: Union[str, Sequence[str]] = "all",
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: _ModelNet

The ModelNet10 dataset as described in the paper 3D ShapeNets: A Deep Representation for Volumetric Shapes.

You can download the official dataset from the Princeton dedicated website.

The ModelNet10 dataset consists of 10 classes, containing 3,991 training and 908 test examples.

Parameters:

  • root (PathLike) –

    Root directory where the dataset should be stored.

  • train (bool, default: True ) –

    If True, loads the training set, otherwise the test set.

  • classes (Union[str, Sequence[str]], default: 'all' ) –

    The class names to include in the dataset. If "all", all classes are included.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    A function/transform that takes in a dictionary containing the data and returns a transformed version.

  • download (bool, default: False ) –

    If True, downloads the dataset from the internet and puts it in root.

  • force_download (bool, default: False ) –

    If True, forces to download the dataset from the internet, even if it is already downloaded.

  • force_process (bool, default: False ) –

    If True, forces to process the dataset, even if it is already processed.

  • show_progress (bool, default: True ) –

    If True, displays a progress bar of the download and processing.

  • num_workers (Optional[int], default: None ) –

    The number of workers to use for parallel processing.

Example 
from torch_pointcloud.datasets import ModelNet10

train_dataset = ModelNet10(root="data", train=True, download=True)
test_dataset = ModelNet10(root="data", train=False, download=True)

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

ModelNet40 [source] ¶

ModelNet40(
    root: PathLike,
    *,
    train: bool = True,
    classes: Union[str, Sequence[str]] = "all",
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: _ModelNet

The ModelNet40 dataset as described in the paper 3D ShapeNets: A Deep Representation for Volumetric Shapes.

You can download the official dataset from the Princeton dedicated website.

The ModelNet40 dataset consists of 40 classes, containing 9,843 training and 2,468 test examples.

Parameters:

  • root (PathLike) –

    Root directory where the dataset should be stored.

  • train (bool, default: True ) –

    If True, loads the training set, otherwise the test set.

  • classes (Union[str, Sequence[str]], default: 'all' ) –

    The class names to include in the dataset. If "all", all classes are included.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    A function/transform that takes in a dictionary containing the data and returns a transformed version.

  • download (bool, default: False ) –

    If True, downloads the dataset from the internet and puts it in root.

  • force_download (bool, default: False ) –

    If True, forces to download the dataset from the internet, even if it is already downloaded.

  • force_process (bool, default: False ) –

    If True, forces to process the dataset, even if it is already processed.

  • show_progress (bool, default: True ) –

    If True, displays a progress bar of the download and processing.

  • num_workers (Optional[int], default: None ) –

    The number of workers to use for parallel processing.

Example 
from torch_pointcloud.datasets import ModelNet40

train_dataset = ModelNet40(root="data", train=True, download=True)
test_dataset = ModelNet40(root="data", train=False, download=True)

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

ModelNet40Hdf5 [source] ¶

ModelNet40Hdf5(
    root: PathLike,
    *,
    train: bool = True,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
)

Bases: PointCloudDataset

The pre-sampled HDF5 version of ModelNet40 (modelnet40_ply_hdf5_2048), introduced with PointNet: Deep Learning on Point Sets for 3D Classification and Segmentation.

Each ModelNet40 mesh is sampled to 2,048 surface points with normals, normalized to the unit sphere, and the pre-shuffled clouds are sharded into HDF5 files listed by train_files.txt / test_files.txt (9,840 train and 2,468 test clouds). This is the standard evaluation input for point-based classification benchmarks (DGCNN, PointMLP, PointNeXt, ...), which take the first \(N\) points of each cloud rather than resampling.

Each sample is a dict with the following keys:

Key Shape Dtype Description
pos \((2048, 3)\) float32 Unit-sphere XYZ coordinates
normal \((2048, 3)\) float32 Surface normals
label scalar int64 Class index (40 classes)

The HDF5 shards are used directly (no separate processed cache): force_process is accepted for contract parity and is a no-op.

Parameters:

  • root (PathLike) –

    Root directory where the dataset should be stored.

  • train (bool, default: True ) –

    If True, loads the training set, otherwise the test set.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    A function/transform that takes in a dictionary containing the data and returns a transformed version.

  • download (bool, default: False ) –

    If True, downloads the dataset from the internet and puts it in root.

  • force_download (bool, default: False ) –

    If True, forces to download the dataset from the internet, even if it is already downloaded.

  • force_process (bool, default: False ) –

    Accepted for contract parity; the HDF5 shards are used directly, so this is a no-op.

  • show_progress (bool, default: True ) –

    If True, displays a progress bar of the download and loading.

Example 
from torch_pointcloud.datasets import ModelNet40Hdf5

train_dataset = ModelNet40Hdf5(root="data", train=True, download=True)
test_dataset = ModelNet40Hdf5(root="data", train=False, download=True)

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • split_file (str) –

    Path to the raw file list of the split.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

split_file property ¶

split_file: str

Path to the raw file list of the split.

ModelNetNormalResampled [source] ¶

ModelNetNormalResampled(
    root: PathLike,
    *,
    variant: Literal["10", "40"],
    train: bool = True,
    classes: Union[str, Sequence[str]] = "all",
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: PointCloudDataset

The ModelNet shapes resampled to 10,000 surface points with normals, as described in the paper PointNet++: Deep Hierarchical Feature Learning on Point Sets in a Metric Space.

Each shape from ModelNet10 / ModelNet40 (see ModelNet10 and ModelNet40 for the mesh datasets) is stored as a .txt file of 10,000 rows with six comma-separated columns: the \(xyz\) coordinates (normalized to the unit sphere) followed by the surface normal. This is the standard input for the point-based classification benchmarks (PointNet++, PointMLP, Point-MAE, ...), which typically sample the first \(1024\) points. The variant selects the 10-class or 40-class label set from the same resampled release.

Parameters:

  • root (PathLike) –

    Root directory where the dataset should be stored.

  • variant (Literal['10', '40']) –

    The label set to load, "10" (ModelNet10 classes) or "40" (ModelNet40 classes).

  • train (bool, default: True ) –

    If True, loads the training set, otherwise the test set.

  • classes (Union[str, Sequence[str]], default: 'all' ) –

    The class names to include in the dataset. If "all", all classes are included.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    A function/transform that takes in a dictionary containing the data and returns a transformed version.

  • download (bool, default: False ) –

    If True, downloads the dataset from the internet and puts it in root.

  • force_download (bool, default: False ) –

    If True, forces to download the dataset from the internet, even if it is already downloaded.

  • force_process (bool, default: False ) –

    If True, forces to process the dataset, even if it is already processed.

  • show_progress (bool, default: True ) –

    If True, displays a progress bar of the download and processing.

  • num_workers (Optional[int], default: None ) –

    The number of workers to use for parallel processing.

Shape
  • pos: \((10000, 3)\) unit-sphere coordinates.
  • normal: \((10000, 3)\) surface normals.
  • label: scalar class index.
Example 
from torch_pointcloud.datasets import ModelNetNormalResampled

train_dataset = ModelNetNormalResampled(root="data", variant="40", train=True, download=True)
test_dataset = ModelNetNormalResampled(root="data", variant="40", train=False, download=True)

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • original_classes (Tuple[str, ...]) –

    Class names of the variant, in the original release order.

  • class_to_idx (dict[str, int]) –

    Mapping from class name to label index.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

original_classes property ¶

original_classes: Tuple[str, ...]

Class names of the variant, in the original release order.

class_to_idx property ¶

class_to_idx: dict[str, int]

Mapping from class name to label index.

NuScenes [source] ¶

NuScenes(
    root: PathLike,
    *,
    split: Optional[NuScenesSplit] = "train",
    version: Optional[str] = None,
    max_sweeps: int = 10,
    classes: Sequence[str] = NUSCENES_DETECTION_CLASSES,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: PointCloudDataset

nuScenes 3D object-detection dataset (LiDAR keyframes + LiDAR-frame ground-truth boxes).

Reference: nuScenes: A multimodal dataset for autonomous driving.

Each LiDAR keyframe aggregates max_sweeps sweeps into the keyframe frame (ego-point removal + per-sweep ego/sensor transform, with a per-point time lag), and the global-frame annotations are converted to LiDAR 7-DoF boxes \((c_x, c_y, c_z, dx, dy, dz, \theta)\) mapped onto the official 10-class detection set (NUSCENES_DETECTION_CLASSES). split selects the keyframes through the official scene lists and resolves the metadata version it reads (train / val read v1.0-trainval, test reads v1.0-test, mini_train / mini_val read v1.0-mini); split=None takes every keyframe of an explicit version. The split is processed once into per-keyframe numpy files under <root>/NuScenes/processed/<version>_<split>_sweeps<max_sweeps>/, then loaded from there (the same raw -> processed -> load flow as S3DIS / ModelNet40).

Note

nuScenes cannot be downloaded automatically (it requires registration and accepting the dataset EULA). Download the metadata and every *_blobs.tgz archive of the version manually from https://www.nuscenes.org/nuscenes#download and extract them under <root>/NuScenes/raw/ so that raw/<version>/*.json, raw/samples/LIDAR_TOP/ and raw/sweeps/LIDAR_TOP/ exist; each blob archive holds a different set of scenes, so a split is complete only once all of them are extracted.

Tip

The processed cache is keyed by version, split and max_sweeps, so different sweep counts coexist. The cache also records the classes it was built with and refuses to load under a different class set; pass force_process=True to regenerate it.

Each sample is a dict:

Key Shape Dtype Description
pos \((N, 3)\) float32 LiDAR XYZ (sweeps aggregated into keyframe frame)
intensity \((N, 1)\) float32 LiDAR reflectance
timestamp \((N, 1)\) float32 Per-point time lag to the keyframe (seconds)
box \((K, 7)\) float32 GT boxes \((c_x, c_y, c_z, dx, dy, dz, \theta)\)
label \((K,)\) int64 Detection class index into classes
velocity \((K, 2)\) float32 Per-box LiDAR-frame BEV velocity \((v_x, v_y)\)
num_points \((K,)\) int64 Per-box LiDAR point count (num_lidar_pts)
attribute \((K,)\) int64 Index into NUSCENES_ATTRIBUTES (\(-1\) when unset)
token - str Source keyframe sample_token

Per-box velocities are the finite difference of the annotation translation across the prev / next annotations divided by their sample-timestamp delta, computed in the global frame, rotated into the keyframe LiDAR frame, and zero when neither neighbor exists. The test split ships no annotations, so its box tensors are empty.

Parameters:

  • root (PathLike) –

    Dataset root; raw data is read from <root>/NuScenes/raw/.

  • split (Optional[NuScenesSplit], default: 'train' ) –

    One of NUSCENES_SPLITS ("train", "val", "test", "mini_train", "mini_val"), or None for every keyframe of version.

  • version (Optional[str], default: None ) –

    Metadata version directory; resolved from split when omitted, required when split is None.

  • max_sweeps (int, default: 10 ) –

    Total LiDAR sweeps aggregated per keyframe (keyframe + prior sweeps).

  • classes (Sequence[str], default: NUSCENES_DETECTION_CLASSES ) –

    Foreground class names kept (order defines the label index).

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each sample dict (e.g. the model's registered transform).

  • download (bool, default: False ) –

    If True, call download (which raises, since nuScenes needs a manual download).

  • force_download (bool, default: False ) –

    Forwarded to download as force.

  • force_process (bool, default: False ) –

    If True, reprocess the raw data even if a processed cache exists.

  • show_progress (bool, default: True ) –

    If True, show a progress bar while processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for processing, or None for sequential processing.

Example

Assuming the raw v1.0-trainval release is extracted under data/NuScenes/raw/:

from torch_pointcloud.datasets import NuScenes

dataset = NuScenes(root="data", split="val", num_workers=8)
len(dataset)          # 6019
sample = dataset[0]
sample["pos"].shape   # torch.Size([N, 3])
sample["box"].shape   # torch.Size([K, 7])

Methods:

  • split_scenes –

    Scene names of split, or None when every scene of version belongs to it.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory, one per version, split and sweep count.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, one per version, split and sweep count.

split_scenes [source] ¶

split_scenes() -> Optional[FrozenSet[str]]

Scene names of split, or None when every scene of version belongs to it.

NuScenesMini [source] ¶

NuScenesMini(
    root: PathLike,
    *,
    version: str = "v1.0-mini",
    max_sweeps: int = 10,
    classes: Sequence[str] = NUSCENES_DETECTION_CLASSES,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: NuScenes

nuScenes mini 3D object-detection dataset: every keyframe of the v1.0-mini release.

A NuScenes preset for the ten-scene mini release (404 keyframes, no train / val split) that reads its own <root>/NuScenesMini/raw/ directory, so the mini download can live next to the full dataset. Samples and the processed cache follow NuScenes; the cache lives under <root>/NuScenesMini/processed/<version>_sweeps<max_sweeps>/.

Parameters:

  • root (PathLike) –

    Dataset root; raw data is read from <root>/NuScenesMini/raw/.

  • version (str, default: 'v1.0-mini' ) –

    Metadata version directory (the mini split is "v1.0-mini").

  • max_sweeps (int, default: 10 ) –

    Total LiDAR sweeps aggregated per keyframe (keyframe + prior sweeps).

  • classes (Sequence[str], default: NUSCENES_DETECTION_CLASSES ) –

    Foreground class names kept (order defines the label index).

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each sample dict (e.g. the model's registered transform).

  • download (bool, default: False ) –

    If True, call download (which raises, since nuScenes needs a manual download).

  • force_download (bool, default: False ) –

    Forwarded to download as force.

  • force_process (bool, default: False ) –

    If True, reprocess the raw data even if a processed cache exists.

  • show_progress (bool, default: True ) –

    If True, show a progress bar while processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for processing, or None for sequential processing.

Example

Assuming the raw mini split is extracted under data/NuScenesMini/raw/:

from torch_pointcloud.datasets import NuScenesMini

dataset = NuScenesMini(root="data")
sample = dataset[0]
sample["pos"].shape   # torch.Size([N, 3])
sample["box"].shape   # torch.Size([K, 7])

Methods:

  • split_scenes –

    Scene names of split, or None when every scene of version belongs to it.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory, one per version, split and sweep count.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, one per version, split and sweep count.

split_scenes [source] ¶

split_scenes() -> Optional[FrozenSet[str]]

Scene names of split, or None when every scene of version belongs to it.

ParisLille3D [source] ¶

ParisLille3D(
    root: PathLike,
    *,
    split: ParisLille3DSplit = "train",
    files: Optional[Sequence[str]] = None,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
)

Bases: PointCloudDataset

The Paris-Lille-3D 10-class benchmark.

Each sample is a single PLY scan, returned as a dictionary:

Key Shape Dtype Meaning
pos \((N, 3)\) float32 XYZ
intensity \((N, 1)\) uint8 LiDAR reflectance
segment \((N,)\) int64 Raw class id, 0-9 (0 = unclassified, ignored)
name str Source file name without extension

Parameters:

  • root (PathLike) –

    Dataset root. Files are read from <root>/ParisLille3D/raw/<file>.ply.

  • split (ParisLille3DSplit, default: 'train' ) –

    One of "train" (the default) / "val" / "trainval" / "all". The 10-class benchmark holds out Lille2.ply as the val split; the public test files (test_10_classes/) have no labels and are not loaded here.

  • files (Optional[Sequence[str]], default: None ) –

    Optional explicit list of file names. Overrides split.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each loaded sample dict at __getitem__ time.

Note

The raw dataset must be downloaded manually from npm3d.fr/paris-lille-3d. The expected layout is <root>/ParisLille3D/raw/<Lille1_1, Lille1_2, Lille2, Paris>.ply.

Methods:

  • download –

    Paris-Lille-3D must be downloaded manually (a license must be accepted).

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

download [source] ¶

download(force: bool = False) -> None

Paris-Lille-3D must be downloaded manually (a license must be accepted).

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises: RuntimeError: Always; automatic download is not supported.

PointCloudDataset [source] ¶

PointCloudDataset(root: PathLike)

Bases: Dataset

Base class for point-cloud datasets stored under a raw/ + processed/ disk layout.

Data for a concrete dataset lives under <root>/<name>/, with the original download in raw/ and the preprocessed cache in processed/. Subclasses implement __getitem__ / __len__ and return per-sample Dict[str, Tensor] objects keyed by DataKeys members; batching is left to the caller (see torch_pointcloud.utils.data.collate).

Note

Datasets that keep their samples in an in-memory cache return a shallow dict copy from __getitem__, so adding or replacing keys on a returned sample never mutates the cache. The tensor values still share storage with the cache: treat them as read-only and let transforms return new tensors instead of writing in place.

Parameters:

  • root (PathLike) –

    The root directory under which the dataset directory is created.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

RepeatDataset [source] ¶

RepeatDataset(dataset: Dataset, k: int)

Bases: Dataset

Repeats a dataset k times so one epoch iterates it k times.

Lengthens an epoch (and thus the number of optimizer steps per epoch) without otherwise changing training.

Parameters:

  • dataset (Dataset) –

    The dataset to repeat.

  • k (int) –

    Number of times the dataset is iterated per epoch.

RepeatSampler [source] ¶

RepeatSampler(
    counts: Sequence[int],
    shuffle: bool = True,
    generator: Optional[Generator] = None,
)

Bases: Sampler[int]

Draws every sample of a dataset its own number of times per epoch.

An epoch yields index \(i\) counts[i] times, shuffled unless shuffle is off, so unevenly sized samples can be visited in proportion to their size (large scenes more often than small ones).

Parameters:

  • counts (Sequence[int]) –

    Number of draws per epoch of every sample, one non-negative count per dataset index.

  • shuffle (bool, default: True ) –

    Shuffle the draws; False yields them grouped by sample, in index order.

  • generator (Optional[Generator], default: None ) –

    Random generator of the shuffle; None uses the global one.

Example 
>>> sampler = RepeatSampler([2, 0, 3, 1], shuffle=False)
>>> list(sampler)
[0, 0, 2, 2, 2, 3]
>>> len(sampler)
6

S3DIS [source] ¶

S3DIS(
    root: PathLike,
    *,
    areas: Union[
        ValueCollection[S3DISArea], Literal["all"]
    ] = "all",
    classes: Union[
        ValueCollection[S3DISClass], Literal["all"]
    ] = "all",
    aligned: bool = True,
    block_size: Optional[float] = None,
    block_stride: float = 1.0,
    num_nodes: Optional[int] = 4096,
    min_num_nodes: int = 100,
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
    accept_terms: bool = False,
)

Bases: PointCloudDataset

The Stanford 3D Indoor Spaces Dataset (S3DIS) dataset, as described in the original paper 3D Indoor Spaces Dataset: Collection, Annotations, and Methods.

You can download the raw dataset from https://cvg-data.inf.ethz.ch/s3dis/ official website. The dataset is released under a terms-of-use agreement (terms_url): accept it, then pass download=True, accept_terms=True (or answer the prompt download=True alone raises on the terminal), or place the archive under raw by hand.

The S3DIS dataset contains 6 diverse areas (one used for testing) covering a total of 6020 square meters. Each area contains multiple rooms (e.g. office, conference room, etc.), and each room contains multiple segment regions (e.g. wall, floor, ceiling, etc.) with instance-level annotations.

The dataset will be processed automatically and saved in the S3DIS/processed directory. Each room is stored as its own folder: <processed_dir>/<Area_i>/<room_name>/{coord,color,segment,instance}.npy. If the processed data already exists, it will be loaded from the S3DIS/processed directory and processing will be skipped.

Tip

If you change the preprocessing parameters, you can delete the processed data to reprocess the dataset or use the force_process argument to force the processing of the raw data.

Parameters:

  • root (PathLike) –

    The root directory of the dataset, where the raw and processed data will be stored.

  • areas (Union[ValueCollection[S3DISArea], Literal['all']], default: 'all' ) –

    The areas to load, either a list of area names or "all".

  • classes (Union[ValueCollection[S3DISClass], Literal['all']], default: 'all' ) –

    The classes to load, either a list of class names or "all".

  • aligned (bool, default: True ) –

    Whether to apply each room's global alignment rotation during processing. The raw Stanford3dDataset_v1.2_Aligned_Version download ships the same (non-aligned) coordinates as V1.2 plus per-room Area_{i}_alignmentAngle.txt files. When aligned=True (default) the rotation is applied so the stored coordinates are globally aligned. When False the original V1.2 coordinate frame is kept: this is required when benchmarking pretrained weights that were trained on non-aligned data (e.g. the DGCNN reference weights whose HDF5 blocks use non-aligned coordinates). Aligned and unaligned data are stored in separate processed directories so they can coexist.

  • block_size (Optional[float], default: None ) –

    If set, each room is split into ground-plane blocks of this size (meters) at load time. Changing this only affects loading, not on-disk processed data.

  • block_stride (float, default: 1.0 ) –

    Stride between blocks when block_size is set.

  • num_nodes (Optional[int], default: 4096 ) –

    Number of points kept per block when tiling, drawn at random (None keeps every point).

  • min_num_nodes (int, default: 100 ) –

    Skip blocks with fewer than this many points.

  • transform (Optional[Callable], default: None ) –

    A callable that transforms the data when retrieved from the dataset.

  • download (bool, default: False ) –

    Whether to download the raw data.

  • force_download (bool, default: False ) –

    Whether to force the download of the raw data.

  • force_process (bool, default: False ) –

    Whether to force the processing of the raw data.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Number of worker processes for parallel room processing. If None, rooms are processed sequentially.

  • accept_terms (bool, default: False ) –

    Confirm that you have accepted the S3DIS terms of use (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

Example

Assuming you have downloaded the raw dataset from https://cvg-data.inf.ethz.ch/s3dis/, and extracted it under data/S3DIS/raw, you can load the dataset as follows:

from torch_pointcloud.datasets import S3DIS

dataset = S3DIS(
    root="data",
    areas=["Area_1", "Area_2", "Area_3", "Area_4", "Area_6"],
)

To split rooms into 1m x 1m blocks (matching the DGCNN evaluation protocol):

from torch_pointcloud.datasets import S3DIS

dataset = S3DIS(
    root="data",
    areas=["Area_5"],
    block_size=1.0,
    block_stride=1.0,
    num_nodes=4096,
)

Methods:

  • is_area_processed –

    Check whether an area is fully packed in the processed cache.

  • process –

    Process the raw dataset for easier loading.

  • load –

    Load the processed dataset into memory.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory, suffixed _aligned when the rooms are axis-aligned.

  • class_to_idx (dict[str, int]) –

    Mapping from class name to label index.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, suffixed _aligned when the rooms are axis-aligned.

class_to_idx cached property ¶

class_to_idx: dict[str, int]

Mapping from class name to label index.

is_area_processed [source] ¶

is_area_processed(area: str) -> bool

Check whether an area is fully packed in the processed cache.

Parameters:

  • area (str) –

    Name of the area (e.g. Area_1).

Returns:

  • bool –

    True if every packed file of the area exists, False otherwise.

process [source] ¶

process(
    force: bool = False,
    num_workers: Optional[int] = None,
    show_progress: bool = True,
) -> None

Process the raw dataset for easier loading.

When aligned=True, applies the per-room alignment rotation so that the stored coordinates are in the globally-aligned frame (the s3disfull convention). When aligned=False, coordinates are kept in the raw scan frame.

load [source] ¶

load(
    block_size: Optional[float] = None,
    block_stride: float = 1.0,
    num_nodes: Optional[int] = 4096,
    min_num_nodes: int = 100,
    show_progress: bool = True,
) -> None

Load the processed dataset into memory. If the provided block_size is not None and greater than 0, the rooms will be split into fixed-size spatial blocks.

Parameters:

  • block_size (Optional[float], default: None ) –

    Side length of each square block in meters.

  • block_stride (float, default: 1.0 ) –

    Step size for the sliding window in meters. Must be \(\leq\) block_size.

  • num_nodes (Optional[int], default: 4096 ) –

    Fixed number of nodes per block. Nodes are randomly subsampled (or duplicated if the block has fewer nodes); None keeps every node.

  • min_num_nodes (int, default: 100 ) –

    Minimum number of raw nodes for a block to be kept.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during loading.

S3DISHdf5 [source] ¶

S3DISHdf5(
    root: PathLike,
    *,
    areas: Union[
        Sequence[S3DISArea], Literal["all"]
    ] = "all",
    classes: Union[
        ValueCollection[S3DISClass], Literal["all"]
    ] = "all",
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    accept_terms: bool = False,
)

Bases: PointCloudDataset

Pre-processed HDF5 version of the S3DIS dataset used by multiple SOTA reference implementations.

Unlike S3DIS, which loads from the raw annotated rooms, this class loads the pre-tiled 4096-point blocks distributed as HDF5 files. The blocks are already spatially tiled and fixed-size, so no additional tiling step is needed.

Each sample is a dict with the following keys:

Key Shape Dtype Description
pos \((4096, 3)\) float32 XYZ coordinates
color \((4096, 3)\) float32 RGB values
norm_pos \((4096, 3)\) float32 Room-normalized XYZ coordinates (range \([0,1]\))
segment \((4096,)\) int64 Per-point semantic label (13 classes)

Labels are emitted in S3DIS_CLASSES order (the archive itself stores them in S3DIS_HDF5_CLASSES order, which swaps table / chair and sofa / bookcase).

Important

This dataset is already processed and the HDF5 files are used directly. They are stored in the S3DIS/indoor3d_sem_seg_hdf5_data directory, meaning that they are co-located with the S3DIS dataset.

Parameters:

  • root (PathLike) –

    Root directory where S3DIS/indoor3d_sem_seg_hdf5_data/ is stored.

  • areas (Union[Sequence[S3DISArea], Literal['all']], default: 'all' ) –

    Areas to load, either a sequence of area names or "all".

  • classes (Union[ValueCollection[S3DISClass], Literal['all']], default: 'all' ) –

    Classes to load, either a sequence of class names or "all". When a subset is selected, labels are remapped to contiguous indices in the given order; unselected classes fall back to the new index of clutter when it is selected, else to the ignore index -1 (matching S3DIS).

  • transform (Optional[Callable], default: None ) –

    Optional callable applied to each sample dict at __getitem__ time.

  • download (bool, default: False ) –

    Whether to download the HDF5 archive if not already present.

  • force_download (bool, default: False ) –

    Whether to re-download even if the archive already exists.

  • force_process (bool, default: False ) –

    Whether to force re-processing (no-op for this variant since the HDF5 files are used directly).

  • show_progress (bool, default: True ) –

    Whether to show progress bars during download and loading.

  • accept_terms (bool, default: False ) –

    Confirm that you have accepted the S3DIS terms of use (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

Example

Assuming you have downloaded the HDF5 files from https://shapenet.cs.stanford.edu/media/, and extracted it under data/S3DIS/indoor3d_sem_seg_hdf5_data, you can load the dataset as follows:

from torch_pointcloud.datasets import S3DISHdf5

dataset = S3DISHdf5(root="data", areas=["Area_1"])
sample = dataset[0]
sample["pos"].shape   # torch.Size([4096, 3])
sample["segment"].shape  # torch.Size([4096])

Attributes:

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • name (str) –

    Name of the dataset directory (shared with S3DIS).

  • class_to_idx (dict[str, int]) –

    Mapping from class name to label index.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory, which aliases raw_dir since the HDF5 blocks are read as-is.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

name property ¶

name: str

Name of the dataset directory (shared with S3DIS).

class_to_idx cached property ¶

class_to_idx: dict[str, int]

Mapping from class name to label index.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, which aliases raw_dir since the HDF5 blocks are read as-is.

ScanNet [source] ¶

ScanNet(
    root: PathLike,
    *,
    version: Literal["v1", "v2"] = "v2",
    split: Literal["train", "test", "val"] = "train",
    label_name: str = "nyu40class",
    label_id: str = "nyu40id",
    use_axis_alignment: bool = True,
    return_superpoint: bool = False,
    block_size: Optional[float] = None,
    block_stride: float = 0.75,
    num_nodes: int = 8192,
    min_num_nodes: int = 100,
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
    accept_terms: bool = False,
)

Bases: PointCloudDataset

The ScanNet dataset as described in the paper ScanNet: Richly-annotated 3D Reconstructions of Indoor Scenes. This dataset contains 2.5M views in 1513 scans acquired in 707 distinct spaces. Each scan is annotated with 3D camera poses, meshes, object segmentation, and scene semantics for a total of 36,000 annotated object instance.

The dataset is available in two versions:

  • v1: The original dataset with 1,513 scans.
  • v2: Improved annotation coverage to ~90% (from 63% in v1), with 100 more scans for test.
Note

It is recommended to use the v2 version, as it contains more annotated object instance. The v1 version is kept for backward compatibility.

Note

By default, the labels are taken from the nyu40class column in the labels CSV file, and the nyu40id column is used to sort the labels. Note than the class_to_idx property returns a dictionary mapping the class name to the contiguous index, and indices may not correspond to the nyu40id values.

In most cases, the loaded labels are contiguous; see class_to_idx for the mapping from class name to index (indices may not match raw nyu40id values in the source files).

Parameters:

  • root (PathLike) –

    The root directory of the dataset.

  • version (Literal['v1', 'v2'], default: 'v2' ) –

    The version of the dataset to use.

  • split (Literal['train', 'test', 'val'], default: 'train' ) –

    The split to load, one of train, val, or test.

  • label_name (str, default: 'nyu40class' ) –

    The name of the label column in the labels CSV file.

  • label_id (str, default: 'nyu40id' ) –

    The name of the id column in the labels CSV file.

  • use_axis_alignment (bool, default: True ) –

    If True, apply ScanNet's axis-alignment transform to the mesh.

  • return_superpoint (bool, default: False ) –

    Also emit the per-point superpoint ids, read from the raw scans/<scene>/<scene>_vh_clean_2.0.010000.segs.json mesh segmentation (requires the raw scans).

  • block_size (Optional[float], default: None ) –

    If set, split each scene into ground-plane blocks of this size (meters) for training.

  • block_stride (float, default: 0.75 ) –

    Stride between adjacent blocks when block_size is set.

  • num_nodes (int, default: 8192 ) –

    Number of points sampled per block (when block_size is set) or per scene.

  • min_num_nodes (int, default: 100 ) –

    Skip blocks with fewer than this many points.

  • transform (Optional[Callable], default: None ) –

    A callable that transforms the data when retrieved from the dataset.

  • download (bool, default: False ) –

    Whether to download the raw data.

  • force_download (bool, default: False ) –

    Whether to force the download of the raw data.

  • force_process (bool, default: False ) –

    Whether to force the processing of the raw data.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for preprocessing, or None for sequential processing.

  • accept_terms (bool, default: False ) –

    Confirm that you have signed the ScanNet terms of use (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

Example

Assuming you have downloaded the raw dataset from https://kaldir.vc.in.tum.de/scannet/, and extracted it under data/ScanNet/raw, you can load the dataset as follows:

from torch_pointcloud.datasets import ScanNet

dataset = ScanNet(
    root="data",
    version="v2",
    split="train",
)

By default, the labels are taken from the nyu40class column in the labels CSV file, and the nyu40id column is used to map the labels to contiguous indices. You can change this by setting the label_name and label_id arguments.

For example, to use the raw_category column and the id column, you can do:

from torch_pointcloud.datasets import ScanNet

dataset = ScanNet(
    root="data",
    version="v2",
    split="train",
    label_name="raw_category",
    label_id="id",
)

Methods:

  • read_scene –

    Read one processed scene directory into a sample dict, relabeled if relabel is set.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • labels (DataFrame) –

    The raw label table, read from the version's combined labels TSV.

  • classes (List[str]) –

    Class names in label order.

  • class_to_idx (Dict[str, int]) –

    Mapping from class name to label index.

  • relabel (Optional[Relabel]) –

    Transform remapping the raw segment ids to the benchmark ids, or None when they are used as-is.

  • processed_dir (str) –

    Path to the processed cache directory, suffixed _noalign when axis alignment is off.

  • processed_files (List[Path]) –

    Sorted list of the split's processed scene directories.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

labels cached property ¶

labels: DataFrame

The raw label table, read from the version's combined labels TSV.

classes cached property ¶

classes: List[str]

Class names in label order.

class_to_idx cached property ¶

class_to_idx: Dict[str, int]

Mapping from class name to label index.

relabel cached property ¶

relabel: Optional[Relabel]

Transform remapping the raw segment ids to the benchmark ids, or None when they are used as-is.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, suffixed _noalign when axis alignment is off.

processed_files property ¶

processed_files: List[Path]

Sorted list of the split's processed scene directories.

read_scene [source] ¶

read_scene(path: Path) -> Dict[str, Any]

Read one processed scene directory into a sample dict, relabeled if relabel is set.

Parameters:

  • path (Path) –

    Processed scene directory holding pos.npy, color.npy, normal.npy and, when annotated, segment.npy / instance.npy.

Returns:

  • Dict[str, Any] –

    The scene as a DataKeys-keyed dict of tensors plus its DataKeys.SCENE id.

Example 
from torch_pointcloud.datasets import ScanNet20

dataset = ScanNet20(root="data", split="val")
scene = dataset.read_scene(dataset.processed_files[0])
scene["pos"].shape  # (N, 3)

ScanNet20 [source] ¶

ScanNet20(
    root: PathLike,
    *,
    version: Literal["v1", "v2"] = "v2",
    split: Literal["train", "test", "val"] = "train",
    use_axis_alignment: bool = True,
    return_superpoint: bool = False,
    block_size: Optional[float] = None,
    block_stride: float = 0.75,
    num_nodes: int = 8192,
    min_num_nodes: int = 100,
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
    accept_terms: bool = False,
)

Bases: ScanNet

ScanNet restricted to the standard 20-class semantic-segmentation benchmark.

A thin wrapper over ScanNet that fixes the label columns to nyu40class / nyu40id and exposes the official 20-class benchmark label set (wall, floor, cabinet, ..., otherfurniture) plus the <unk> ignore class at index \(0\). The relabel transform, applied while loading, maps the raw NYU40 segment ids onto these contiguous benchmark indices; points outside the 20 classes map to <unk>. The processed cache lives in processed_20/ so it never collides with the base ScanNet or ScanNet200 caches.

Parameters:

  • root (PathLike) –

    The root directory of the dataset.

  • version (Literal['v1', 'v2'], default: 'v2' ) –

    The version of the dataset to use.

  • split (Literal['train', 'test', 'val'], default: 'train' ) –

    The split to load, one of train, val, or test.

  • use_axis_alignment (bool, default: True ) –

    If True, apply ScanNet's axis-alignment transform to the mesh.

  • return_superpoint (bool, default: False ) –

    Also emit the per-point superpoint ids, read from the raw scans/<scene>/<scene>_vh_clean_2.0.010000.segs.json mesh segmentation (requires the raw scans).

  • block_size (Optional[float], default: None ) –

    If set, split each scene into ground-plane blocks of this size (meters) for training.

  • block_stride (float, default: 0.75 ) –

    Stride between adjacent blocks when block_size is set.

  • num_nodes (int, default: 8192 ) –

    Number of points sampled per block (when block_size is set) or per scene.

  • min_num_nodes (int, default: 100 ) –

    Skip blocks with fewer than this many points.

  • transform (Optional[Callable], default: None ) –

    A callable that transforms the data when retrieved from the dataset.

  • download (bool, default: False ) –

    Whether to download the raw data.

  • force_download (bool, default: False ) –

    Whether to force the download of the raw data.

  • force_process (bool, default: False ) –

    Whether to force the processing of the raw data.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for preprocessing, or None for sequential processing.

  • accept_terms (bool, default: False ) –

    Confirm that you have signed the ScanNet terms of use (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

Example

Assuming you have downloaded the raw dataset from https://kaldir.vc.in.tum.de/scannet/ and extracted it under data/ScanNet/raw, you can load the benchmark labels as follows:

from torch_pointcloud.datasets import ScanNet20

dataset = ScanNet20(root="data", split="val")
sample = dataset[0]
sample["segment"].unique()  # benchmark indices in [0, 20]

Methods:

  • read_scene –

    Read one processed scene directory into a sample dict, relabeled if relabel is set.

Attributes:

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • labels (DataFrame) –

    The raw label table, read from the version's combined labels TSV.

  • class_to_idx (Dict[str, int]) –

    Mapping from class name to label index.

  • processed_files (List[Path]) –

    Sorted list of the split's processed scene directories.

  • name (str) –

    Name of the dataset directory (shared with ScanNet).

  • processed_dir (str) –

    Path to the processed cache directory, suffixed _20 for the 20-class benchmark.

  • classes (List[str]) –

    Class names in label order.

  • relabel (Relabel) –

    Transform remapping the raw segment ids to the 20 benchmark ids.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

labels cached property ¶

labels: DataFrame

The raw label table, read from the version's combined labels TSV.

class_to_idx cached property ¶

class_to_idx: Dict[str, int]

Mapping from class name to label index.

processed_files property ¶

processed_files: List[Path]

Sorted list of the split's processed scene directories.

name property ¶

name: str

Name of the dataset directory (shared with ScanNet).

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, suffixed _20 for the 20-class benchmark.

classes cached property ¶

classes: List[str]

Class names in label order.

relabel cached property ¶

relabel: Relabel

Transform remapping the raw segment ids to the 20 benchmark ids.

read_scene [source] ¶

read_scene(path: Path) -> Dict[str, Any]

Read one processed scene directory into a sample dict, relabeled if relabel is set.

Parameters:

  • path (Path) –

    Processed scene directory holding pos.npy, color.npy, normal.npy and, when annotated, segment.npy / instance.npy.

Returns:

  • Dict[str, Any] –

    The scene as a DataKeys-keyed dict of tensors plus its DataKeys.SCENE id.

Example 
from torch_pointcloud.datasets import ScanNet20

dataset = ScanNet20(root="data", split="val")
scene = dataset.read_scene(dataset.processed_files[0])
scene["pos"].shape  # (N, 3)

ScanNet200 [source] ¶

ScanNet200(
    root: PathLike,
    *,
    version: Literal["v1", "v2"] = "v2",
    split: Literal["train", "test", "val"] = "train",
    use_axis_alignment: bool = True,
    return_superpoint: bool = False,
    block_size: Optional[float] = None,
    block_stride: float = 0.75,
    num_nodes: int = 8192,
    min_num_nodes: int = 100,
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
    accept_terms: bool = False,
)

Bases: ScanNet

ScanNet restricted to the 200-class benchmark, as described in the paper Language-Grounded Indoor 3D Semantic Segmentation in the Wild.

A thin wrapper over ScanNet that reads the fine-grained raw_category / id label columns and exposes the 200-class benchmark label set plus the <unk> ignore class at index \(0\). The relabel transform, applied while loading, maps the raw category ids onto contiguous benchmark indices; categories outside the 200 classes map to <unk>. The processed cache lives in processed_200/ so it never collides with the base ScanNet or ScanNet20 caches.

Parameters:

  • root (PathLike) –

    The root directory of the dataset.

  • version (Literal['v1', 'v2'], default: 'v2' ) –

    The version of the dataset to use.

  • split (Literal['train', 'test', 'val'], default: 'train' ) –

    The split to load, one of train, val, or test.

  • use_axis_alignment (bool, default: True ) –

    If True, apply ScanNet's axis-alignment transform to the mesh.

  • return_superpoint (bool, default: False ) –

    Also emit the per-point superpoint ids, read from the raw scans/<scene>/<scene>_vh_clean_2.0.010000.segs.json mesh segmentation (requires the raw scans).

  • block_size (Optional[float], default: None ) –

    If set, split each scene into ground-plane blocks of this size (meters) for training.

  • block_stride (float, default: 0.75 ) –

    Stride between adjacent blocks when block_size is set.

  • num_nodes (int, default: 8192 ) –

    Number of points sampled per block (when block_size is set) or per scene.

  • min_num_nodes (int, default: 100 ) –

    Skip blocks with fewer than this many points.

  • transform (Optional[Callable], default: None ) –

    A callable that transforms the data when retrieved from the dataset.

  • download (bool, default: False ) –

    Whether to download the raw data.

  • force_download (bool, default: False ) –

    Whether to force the download of the raw data.

  • force_process (bool, default: False ) –

    Whether to force the processing of the raw data.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for preprocessing, or None for sequential processing.

  • accept_terms (bool, default: False ) –

    Confirm that you have signed the ScanNet terms of use (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

Example

Assuming you have downloaded the raw dataset from https://kaldir.vc.in.tum.de/scannet/ and extracted it under data/ScanNet/raw, you can load the benchmark labels as follows:

from torch_pointcloud.datasets import ScanNet200

dataset = ScanNet200(root="data", split="val")
sample = dataset[0]
sample["segment"].unique()  # benchmark indices in [0, 200]

Methods:

  • read_scene –

    Read one processed scene directory into a sample dict, relabeled if relabel is set.

Attributes:

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • labels (DataFrame) –

    The raw label table, read from the version's combined labels TSV.

  • class_to_idx (Dict[str, int]) –

    Mapping from class name to label index.

  • processed_files (List[Path]) –

    Sorted list of the split's processed scene directories.

  • name (str) –

    Name of the dataset directory (shared with ScanNet).

  • processed_dir (str) –

    Path to the processed cache directory, suffixed _200 for the 200-class benchmark.

  • classes (List[str]) –

    Class names in label order.

  • relabel (Relabel) –

    Transform remapping the raw segment ids to the 200 benchmark ids.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

labels cached property ¶

labels: DataFrame

The raw label table, read from the version's combined labels TSV.

class_to_idx cached property ¶

class_to_idx: Dict[str, int]

Mapping from class name to label index.

processed_files property ¶

processed_files: List[Path]

Sorted list of the split's processed scene directories.

name property ¶

name: str

Name of the dataset directory (shared with ScanNet).

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, suffixed _200 for the 200-class benchmark.

classes cached property ¶

classes: List[str]

Class names in label order.

relabel cached property ¶

relabel: Relabel

Transform remapping the raw segment ids to the 200 benchmark ids.

read_scene [source] ¶

read_scene(path: Path) -> Dict[str, Any]

Read one processed scene directory into a sample dict, relabeled if relabel is set.

Parameters:

  • path (Path) –

    Processed scene directory holding pos.npy, color.npy, normal.npy and, when annotated, segment.npy / instance.npy.

Returns:

  • Dict[str, Any] –

    The scene as a DataKeys-keyed dict of tensors plus its DataKeys.SCENE id.

Example 
from torch_pointcloud.datasets import ScanNet20

dataset = ScanNet20(root="data", split="val")
scene = dataset.read_scene(dataset.processed_files[0])
scene["pos"].shape  # (N, 3)

ScanObjectNN [source] ¶

ScanObjectNN(
    root: PathLike,
    *,
    train: bool = True,
    partition: ScanObjectNNPartition = "main",
    background: bool = False,
    variant: Optional[ScanObjectNNVariant] = None,
    classes: Union[
        ScanObjectNNClasses,
        Sequence[ScanObjectNNClasses],
        Literal["all"],
    ] = "all",
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    accept_terms: bool = False,
)

Bases: PointCloudDataset

The ScanObjectNN dataset of 3D object point clouds, as described in the paper Revisiting Point Cloud Classification: A New Benchmark Dataset and Classification Model on Real-World Data by Mikaela Angelina Uy, Quang-Hieu Pham, Binh-Son Hua, Duc Thanh Nguyen, Sai-Kit Yeung (submitted on 2019).

The dataset is released under a terms-of-use agreement (terms_url): accept it, then pass download=True, accept_terms=True (or answer the prompt download=True alone raises on the terminal), or place the h5_files folder under raw by hand.

The registered checkpoints name the benchmark splits by tag (*.scanobjectnn-<tag>.*):

Tag Arguments
objbg background=True
objonly background=False
hardest background=True, variant="augmentedrot_scale75"

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • class_to_idx (Dict[str, int]) –

    Mapping from class name to label index.

  • raw_file (str) –

    Path to the raw HDF5 file of the split, partition and variant.

  • processed_file (str) –

    Path to the packed .npz cache mirroring raw_file.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

class_to_idx property ¶

class_to_idx: Dict[str, int]

Mapping from class name to label index.

raw_file property ¶

raw_file: str

Path to the raw HDF5 file of the split, partition and variant.

processed_file property ¶

processed_file: str

Path to the packed .npz cache mirroring raw_file.

Semantic3D [source] ¶

Semantic3D(
    root: PathLike,
    *,
    split: Semantic3DSplit = "train",
    scenes: Optional[Sequence[str]] = None,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    download: bool = False,
    force_download: bool = False,
    accept_terms: bool = False,
    show_progress: bool = True,
)

Bases: PointCloudDataset

The Semantic3D dataset.

Each sample is a single ASCII-text scene, returned as a dictionary:

Key Shape Dtype Meaning
pos \((N, 3)\) float32 XYZ
intensity \((N, 1)\) float32 LiDAR intensity
color \((N, 3)\) uint8 RGB (0-255)
segment \((N,)\) int64 Raw class id 0-8 (0 = unlabelled, ignored). Absent for held-out scenes.
name str Source scene name

Parameters:

  • root (PathLike) –

    Dataset root. Files are read from <root>/Semantic3D/raw/<scene>.txt.

  • split (Semantic3DSplit, default: 'train' ) –

    One of "train" / "test" / "all". Defaults to "train". "test" returns the four reduced-8 benchmark scenes (without labels).

  • scenes (Optional[Sequence[str]], default: None ) –

    Optional explicit list of scene names (without the .txt / .labels suffix). Overrides split.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each loaded sample dict at __getitem__ time.

  • download (bool, default: False ) –

    Whether to download the requested scenes when they are missing.

  • force_download (bool, default: False ) –

    Whether to download and extract them again even when present.

  • accept_terms (bool, default: False ) –

    Confirm that you have accepted the Semantic3D licence (terms_url). When left False, download asks for the confirmation on the terminal, once in every process that triggers the download.

  • show_progress (bool, default: True ) –

    Whether to show the download progress bars.

Note

The data come from the benchmark site, semantic3d.net (archived; the original links now ask for a login), which serves its scenes as 7z archives from an ETH mirror, https://share.phys.ethz.ch/~pf/semantic3d/data/ (data_url), under the CC BY-NC-SA 3.0 licence (terms_url). Accept it, then pass download=True, accept_terms=True (or answer the prompt; download=True alone asks on the terminal) to fetch the requested scenes and the labels of the training ones; reading the archives needs the optional py7zr package. Or place one <scene>.txt (and the matching <scene>.labels for training scenes) per scene under <root>/Semantic3D/raw/ by hand.

Warning

Loading is done with np.loadtxt, which reads the (often 100M+-row) ASCII files into RAM in a single shot. Each scene needs ~5 GB of RAM to parse; consider extracting only the scenes you need for evaluation.

Methods:

  • archive_url –

    URL of the 7z archive holding <scene>.txt on the benchmark's mirror.

  • download –

    Fetch the requested scenes, and the labels of the training ones, from the benchmark's mirror.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

archive_url classmethod [source] ¶

archive_url(scene: str) -> str

URL of the 7z archive holding <scene>.txt on the benchmark's mirror.

Parameters:

  • scene (str) –

    A training or reduced-8 test scene name.

Raises:

  • ValueError –

    If the scene is not one the mirror serves.

download [source] ¶

download(force: bool = False) -> None

Fetch the requested scenes, and the labels of the training ones, from the benchmark's mirror.

Every scene is a 7z archive holding its .txt, read with the optional py7zr package; the training labels come in one archive, of which only the requested scenes are extracted. Reduced-8 test scenes have no labels.

Parameters:

  • force (bool, default: False ) –

    Download and extract the scenes again even when their files are present.

Raises:

  • RuntimeError –

    If the licence is not accepted.

  • ImportError –

    If py7zr is not installed.

SemanticKITTI [source] ¶

SemanticKITTI(
    root: PathLike,
    *,
    split: SemanticKittiSplit = "train",
    sequences: Optional[
        ValueCollection[Union[SemanticKittiSequence, str]]
    ] = None,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
)

Bases: PointCloudDataset

The SemanticKITTI dataset, as described in the paper SemanticKITTI: A Dataset for Semantic Scene Understanding of LiDAR Sequences.

The dataset contains a sequence of LiDAR scans collected from a vehicle driving in several urban areas, with point-wise semantic and instance annotations. The 22 sequences are split into train (00-07, 09, 10), val (08), and test (11-21). Test labels are not publicly available; only the velodyne scans are released.

Note

The raw dataset must be downloaded manually from https://www.semantic-kitti.org/dataset.html (a license must be accepted). The expected layout under <root>/SemanticKITTI/raw is:

sequences/
    00/
        velodyne/{frame:06d}.bin
        labels/{frame:06d}.label
    01/
        ...

Each sample is returned as a dict with the following keys:

Key Shape Dtype Description
pos \((N, 3)\) float32 XYZ coordinates
intensity \((N, 1)\) float32 Reflected LiDAR intensity
segment \((N,)\) int64 Raw per-point semantic id (when available)
instance \((N,)\) int64 Per-point instance id (when available)
sequence - str Source sequence id (e.g. "00")
frame - str Source frame id (e.g. "000000")
Note

Scans are loaded from disk on demand (lazy loading), so the dataset can be used with very large splits without exhausting host memory. As a consequence, the dataset has no process step: it just enumerates .bin files at construction time. Augmentation, voxelization, feature normalization, and label remapping are intentionally left out so they can be composed with torch_pointcloud.transforms and shared across models.

Note

segment contains the raw SemanticKITTI label ids (see SEMANTIC_KITTI_LABEL_NAMES); no class merging or contiguous remapping is applied. Compose a downstream torch_pointcloud.transforms.Relabel to project them onto the (model-specific) class set you train against.

Parameters:

  • root (PathLike) –

    Root directory of the dataset. Raw data is expected under <root>/SemanticKITTI/raw/sequences/<seq>/....

  • split (SemanticKittiSplit, default: 'train' ) –

    One of "train", "val", "trainval", or "test". Selects the sequences used by the official benchmark. Ignored when sequences is set.

  • sequences (Optional[ValueCollection[Union[SemanticKittiSequence, str]]], default: None ) –

    Optional explicit list of sequences to use. Overrides split.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each sample dict at __getitem__ time. Used for augmentation, voxelization, label remapping, feature construction, etc.

Example

Assuming you have downloaded the raw dataset and extracted it under data/SemanticKITTI/raw/sequences/..., you can load the validation split:

from torch_pointcloud.datasets import SemanticKITTI

dataset = SemanticKITTI(root="data", split="val")
sample = dataset[0]
sample["pos"].shape         # torch.Size([N, 3])
sample["intensity"].shape   # torch.Size([N, 1])
sample["segment"].shape     # torch.Size([N]) - raw label ids in [0, 259]

To map raw labels onto the 19-class benchmark, compose a Relabel transform with SEMANTIC_KITTI_LEARNING_MAP, the official semantic-kitti-api learning map (bus and on-rails merge into other-vehicle, lane-marking into road). Checkpoints trained with another map register their own: randlanet.semantickitti.tsung-han-wu sends those three classes to the ignore index.

import torch_pointcloud.transforms as T
from torch_pointcloud.datasets import SemanticKITTI
from torch_pointcloud.datasets.semantickitti import SEMANTIC_KITTI_LEARNING_MAP

dataset = SemanticKITTI(
    root="data",
    split="val",
    transform=T.Relabel(keys="segment", labels=SEMANTIC_KITTI_LEARNING_MAP, default=255),
)

Methods:

  • download –

    SemanticKITTI must be downloaded manually (a license must be accepted).

  • load –

    Enumerate the velodyne scans for the configured sequences.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • sequences_dir (str) –

    Path to the raw sequences directory.

  • processed_dir (str) –

    Path to the processed cache directory, which aliases raw_dir since the scans are read as-is.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

sequences_dir property ¶

sequences_dir: str

Path to the raw sequences directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory, which aliases raw_dir since the scans are read as-is.

download [source] ¶

download(force: bool = False) -> None

SemanticKITTI must be downloaded manually (a license must be accepted).

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises: RuntimeError: Always; automatic download is not supported.

load [source] ¶

load() -> None

Enumerate the velodyne scans for the configured sequences.

This populates self.scans with (sequence, frame, bin_path, label_path) tuples, where label_path is None when no .label file is present (e.g. test split). Raises a RuntimeError listing the missing sequences when only part of the requested sequences has velodyne scans on disk.

ShapeNetPart [source] ¶

ShapeNetPart(
    root: PathLike,
    *,
    split: Literal["train", "val", "test"] = "train",
    categories: Optional[
        Union[List[ShapeNetCategory], ShapeNetCategory]
    ] = None,
    transform: Optional[TransformLike] = None,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: PointCloudDataset

ShapeNetPart dataset packed into per-split .npy files.

Each split is packed once into:

<processed_dir>/<split>/
    pos.npy           # float32, (total_points, 3)
    normal.npy        # float32, (total_points, 3)
    segment.npy       # int16,   (total_points,)
    offset.npy        # int64,   (n_samples + 1,)
    category.npy      # int16,   (n_samples,)

The packed files contain every category; categories filters the sample index at load time, so changing the subset is free.

Parameters:

  • root (PathLike) –

    Dataset root directory.

  • split (Literal['train', 'val', 'test'], default: 'train' ) –

    One of "train" (the default), "val", "test".

  • categories (Optional[Union[List[ShapeNetCategory], ShapeNetCategory]], default: None ) –

    Which categories to expose. Defaults to all 16.

  • transform (Optional[TransformLike], default: None ) –

    Callable applied to each sample in __getitem__.

  • force_process (bool, default: False ) –

    Re-pack raw data even if processed files exist.

  • show_progress (bool, default: True ) –

    Show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Parallelism for raw-file reading during processing.

Methods:

  • download –

    ShapeNetPart must be downloaded manually (registration is required).

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • category_to_id (Dict[str, int]) –

    Mapping from category name to its index among the exposed categories.

  • seg_to_id (Dict[int, int]) –

    Mapping from part label to its index among the exposed categories' parts.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

category_to_id property ¶

category_to_id: Dict[str, int]

Mapping from category name to its index among the exposed categories.

seg_to_id property ¶

seg_to_id: Dict[int, int]

Mapping from part label to its index among the exposed categories' parts.

download [source] ¶

download(force: bool = False) -> None

ShapeNetPart must be downloaded manually (registration is required).

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises: RuntimeError: Always; automatic download is not supported.

SunRGBD [source] ¶

SunRGBD(
    root: PathLike,
    *,
    train: bool = True,
    transform: Optional[Callable] = None,
    download: bool = False,
    force_download: bool = False,
    force_process: bool = False,
    show_progress: bool = True,
    num_workers: Optional[int] = None,
)

Bases: PointCloudDataset

The SUN RGB-D dataset for 3D object detection, as described in the paper SUN RGB-D: A RGB-D Scene Understanding Benchmark Suite.

SUN RGB-D provides 10335 RGB-D frames with amodal oriented 3D bounding boxes. This dataset reconstructs the upright point cloud from the raw depth frames following the votenet recipe ( facebookresearch/votenet) and exposes per-scene clouds with their ground-truth boxes over the 10 detection classes.

The dataset reads the depth and RGB frames directly from the 6.8 GB SUNRGBD.zip release and the metadata from SUNRGBDtoolbox.zip, without extracting either archive wholesale. Each scene is processed into a <processed_dir>/<split>/<sequence_id>/ directory holding one .npy per attribute; pos is stored as float16 and color as uint8 to keep the cache compact. Construction only enumerates the cached scene directories; each scene's arrays are read from disk on access. Cached boxes keep the on-disk \((K, 8)\) encoding (half extents, clockwise heading, trailing class column) and the per-box classes stay in class.npy; __getitem__ converts them to the emitted \((K, 7)\) box / \((K,)\) label format below, so existing caches stay valid.

Parameters:

  • root (PathLike) –

    Root directory where the dataset is stored or will be downloaded.

  • train (bool, default: True ) –

    If True, loads the train split; if False, loads the val split.

  • transform (Optional[Callable], default: None ) –

    A callable that transforms the data when retrieved from the dataset.

  • download (bool, default: False ) –

    Whether to download missing raw inputs if not present.

  • force_download (bool, default: False ) –

    Whether to force the download of the raw data.

  • force_process (bool, default: False ) –

    Whether to force the processing of the raw data.

  • show_progress (bool, default: True ) –

    Whether to show a progress bar during processing.

  • num_workers (Optional[int], default: None ) –

    Worker processes for preprocessing, or None for sequential processing.

Shape
  • pos: \((N, 3)\) point coordinates in the upright depth frame.
  • color: \((N, 3)\) RGB values in \([0, 255]\) (uint8).
  • box: \((K, 7)\) boxes as \([cx, cy, cz, dx, dy, dz, \text{heading}]\) with full extents and a counter-clockwise heading about \(+z\) from \(+x\).
  • label: \((K,)\) per-box class indices.
Example

Assuming you have downloaded SUNRGBD.zip and SUNRGBDtoolbox.zip under data/SunRGBD/raw, you can load the dataset as follows:

from torch_pointcloud.datasets import SunRGBD

dataset = SunRGBD(root="data", train=False)
sample = dataset[0]
sample["pos"].shape  # (N, 3)
sample["box"].shape  # (K, 7)

Methods:

  • read_split –

    Read the split's sequence ids from the toolbox archive.

  • read_meta –

    Read the per-scene metadata structs from the toolbox archive, keyed by sequence id.

  • process_scene –

    Unproject one scene and write its packed pos / color / box / class arrays.

  • read_scene_cloud –

    Unproject one scene's depth and RGB images into a colored point cloud.

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

  • release_zip_path (str) –

    Path to the raw SUNRGBD.zip release archive.

  • toolbox_zip_path (str) –

    Path to the raw SUNRGBDtoolbox.zip archive holding the splits and metadata.

  • class_to_idx (Dict[str, int]) –

    Mapping from class name to label index.

  • processed_files (List[Path]) –

    Sorted list of the split's processed scene directories.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

release_zip_path property ¶

release_zip_path: str

Path to the raw SUNRGBD.zip release archive.

toolbox_zip_path property ¶

toolbox_zip_path: str

Path to the raw SUNRGBDtoolbox.zip archive holding the splits and metadata.

class_to_idx cached property ¶

class_to_idx: Dict[str, int]

Mapping from class name to label index.

processed_files property ¶

processed_files: List[Path]

Sorted list of the split's processed scene directories.

read_split [source] ¶

read_split() -> List[str]

Read the split's sequence ids from the toolbox archive.

read_meta [source] ¶

read_meta() -> Dict[str, Any]

Read the per-scene metadata structs from the toolbox archive, keyed by sequence id.

process_scene [source] ¶

process_scene(args: Tuple[str, Any, str]) -> None

Unproject one scene and write its packed pos / color / box / class arrays.

Parameters:

  • args (Tuple[str, Any, str]) –

    The scene's sequence id, its metadata struct, and the split directory to write into.

read_scene_cloud [source] ¶

read_scene_cloud(entry: Any) -> Tuple[ndarray, ndarray]

Unproject one scene's depth and RGB images into a colored point cloud.

Parameters:

  • entry (Any) –

    The scene's metadata struct, holding the image paths, the intrinsics K and the upright rotation Rtilt.

Returns:

  • Tuple[ndarray, ndarray] –

    The upright points \((N, 3)\) and their RGB colors \((N, 3)\), with the zero-depth pixels dropped.

Toronto3D [source] ¶

Toronto3D(
    root: PathLike,
    *,
    split: Toronto3DSplit = "train",
    files: Optional[Sequence[str]] = None,
    utm_offset: Sequence[float] = TORONTO3D_UTM_OFFSET,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
)

Bases: PointCloudDataset

The Toronto-3D dataset.

Each sample is a single CloudCompare-exported PLY scan from the four-tile mobile LiDAR sweep, returned as a dictionary:

Key Shape Dtype Meaning
pos \((N, 3)\) float32 XYZ (UTM offset by utm_offset)
color \((N, 3)\) uint8 RGB (0-255)
intensity \((N, 1)\) float32 LiDAR intensity
gps_time \((N, 1)\) float32 GPS timestamp
segment \((N,)\) int64 Raw class id, 0-8 (0 = Unclassified, ignored)
name str Source file name without extension

Parameters:

  • root (PathLike) –

    Dataset root. Files are read from <root>/Toronto3D/raw/<file>.ply.

  • split (Toronto3DSplit, default: 'train' ) –

    One of "train" (the default) / "val" / "test" / "trainval" / "all". Test labels are publicly available so val and test are the same file (L002.ply).

  • files (Optional[Sequence[str]], default: None ) –

    Optional explicit list of file names. Overrides split.

  • utm_offset (Sequence[float], default: TORONTO3D_UTM_OFFSET ) –

    3-vector subtracted from raw UTM (x, y, z) to keep coordinates in a small numerical range. Defaults to TORONTO3D_UTM_OFFSET; pass (0, 0, 0) to keep raw UTM coordinates.

  • transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

    Callable applied to each loaded sample dict at __getitem__ time.

Note

The raw dataset must be downloaded manually from WeikaiTan/Toronto-3D (a license must be accepted). The expected layout is <root>/Toronto3D/raw/L00{1,2,3,4}.ply.

Methods:

  • download –

    Toronto-3D must be downloaded manually (a license must be accepted).

Attributes:

  • name (str) –

    Name of the dataset directory.

  • data_dir (str) –

    Path to the dataset directory <root>/<name>.

  • raw_dir (str) –

    Path to the raw download directory.

  • processed_dir (str) –

    Path to the processed cache directory.

name property ¶

name: str

Name of the dataset directory.

data_dir property ¶

data_dir: str

Path to the dataset directory <root>/<name>.

raw_dir property ¶

raw_dir: str

Path to the raw download directory.

processed_dir property ¶

processed_dir: str

Path to the processed cache directory.

download [source] ¶

download(force: bool = False) -> None

Toronto-3D must be downloaded manually (a license must be accepted).

Parameters:

  • force (bool, default: False ) –

    Unused; present to mirror the other datasets' download signature.

Raises: RuntimeError: Always; automatic download is not supported.