Pointgroup:ConfigParameters

weight

None

Path to the model weights loaded at the start of training. Used by the CheckpointLoader hook

Set when fine-tuning from a pretrained backbone (e.g. Sonata, PTv3). If key names differ, map them with CheckpointLoader's keywords/replacement

resume

False

Resumes interrupted training. Restores the optimizer/scheduler state as well

True when continuing from model_last.pth in the same save_path. False if you switched to a new dataset

evaluate

True

Runs val set evaluation at every eval interval

If evaluation takes long, set False and evaluate later with test_only. However, the best checkpoint is not saved

test_only

False

Runs test only, without training

Set automatically by tools/test.sh. No need to touch it

seed

None

Random seed. If None, one is generated randomly and logged

Fix it for reproducible experiments. Ablation comparisons must use the same seed

save_path

"exp/default"

Path where logs, checkpoints, and config backups are saved

A different path per experiment. Set automatically by tools/train.sh -n

num_worker

12

Total number of DataLoader workers across all GPUs

No more than the number of CPU cores. Reduce if RAM runs out (OOM kill). 4–8 per GPU recommended

batch_size

12

Total batch size across all GPUs. Per GPU = batch_size / number of GPUs

<span style="color:orange;font-weight:bold">Caution Fit it to GPU memory. If you reduce it, reducing lr proportionally is the safe choice. Must be divisible by the number of GPUs

gradient_accumulation_steps

1

Accumulates gradients this many times, then updates once. Effective batch = batch_size × steps

Use when there is not enough memory to increase batch_size. BN statistics are not accumulated, so it is not a complete substitute

batch_size_val

None

Val batch. If None, 1 per GPU

Instance seg evaluates per scene, so keeping 1 is recommended

batch_size_test

None

Test batch. If None, 1 per GPU

Keep 1

epoch

800

Total training epochs

<span style="color:orange;font-weight:bold">Caution If the data grows from 100 to 700 samples, the same epoch count means 7x the iterations. Reset it based on total iterations. Decide by looking at the convergence curve

eval_epoch

100

Used to compute the evaluation/checkpoint interval. Number of data loops = epoch // eval_epoch

Adjust together when you change epoch. Lower the value to evaluate more often

clip_grad

None

Gradient norm clipping value. Disabled if None

Set 1.0–10.0 if the loss becomes NaN or diverges

sync_bn

False

Synchronizes BatchNorm statistics across multiple GPUs

True recommended if the per-GPU batch is small (2 or less). Slightly slower

enable_amp

True

Uses automatic mixed precision (AMP)

Large memory/speed gains. If NaN occurs, check with False

amp_dtype

"float16"

AMP data type

On Ampere or newer GPUs, "bfloat16" is numerically more stable

empty_cache

False

Empties the CUDA cache every iteration

Very slow. True only when OOM is intermittent

empty_cache_per_epoch

False

Empties the CUDA cache every epoch

Same as above; a less costly alternative

find_unused_parameters

False

Allows unused parameters in DDP

True if you get an error after freezing part of the model

enable_wandb

True

Weights & Biases logging

False in offline environments

wandb_project

"pointcept"

wandb project name

Free to change

wandb_key

None

wandb API token. If None, the terminal login is used

Free to change

mix_prob

0

Probability of CutMix-style augmentation that mixes two scenes in a batch

<span style="color:red;font-weight:bold">Danger Must be 0 for instance seg. Mixing causes instance id collisions

param_dicts

None

Learning rate multiplier per keyword. E.g. [dict(keyword="backbone", lr_scale=0.1)]

Used to lower the backbone lr when fine-tuning a pretrained backbone

class_names

20 ScanNet classes

List of class names. The order corresponds to the integer labels

<span style="color:red;font-weight:bold">Danger Must exactly match the label indices of your dataset. Changing the order scrambles the evaluation results

num_classes

20

Number of semantic classes

Must equal len(class_names)

segment_ignore_index

(-1, 0, 1)

Semantic labels excluded from instances. -1 is unlabeled, 0/1 are ScanNet's wall/floor

<span style="color:red;font-weight:bold">Danger Passed identically to four places: the model's clustering, InstanceParser, the evaluator, and the tester. Redefine it with the "background" class indices of your data. Classes included here are never detected as instances

type

"PG-v1m1"

Model registry name

To use a PTv3 backbone, see the "PG-v1m2" + PT-v3m1 backbone combination (configs/scannetpp/insseg-pointgroup-v1m2-0-ptv3-base.py)

backbone_out_channels

96

Backbone output feature dimension. Input to seg_head and bias_head

Must match the last value of the backbone channels

semantic_num_classes

num_classes

Number of semantic head outputs

Same as num_classes

semantic_ignore_index

-1

Label ignored by the CE loss

Match the unlabeled value of your data

segment_ignore_index

(-1, 0, 1)

At inference, points predicted as these semantic classes are excluded from clustering

See section 2

instance_ignore_index

-1

Instance label excluded from the offset loss

Must equal the value in InstanceParser

cluster_thresh

1.5

Ball query radius. In voxel units (3cm if grid_size is 0.02). Points whose predicted centers are within this distance are candidates for the same cluster

<span style="color:orange;font-weight:bold">Caution Lower it (1.0–1.2) if small objects merge with their neighbors; raise it (2.0) if one object splits into several pieces. Changing grid_size changes the physical distance, so readjust it

cluster_closed_points

300

Maximum number of neighbors per point in the ball query

Raise it if point density is very high. Affects speed/memory

cluster_min_points

50

In BFS clustering, clusters with fewer points than this are not created

<span style="color:orange;font-weight:bold">Caution A direct cause of missed small objects. Experiment by lowering it to 10–20. Lowering it too far increases noisy proposals

cluster_propose_points

100

Generated proposals with this many points or fewer are discarded

<span style="color:orange;font-weight:bold">Caution A direct cause of missed small objects. Lower it together with cluster_min_points. It must match the evaluator's min_region_sizes to be reflected in evaluation

voxel_size

0.02

Divisor that converts predicted center coordinates to voxel units at inference

<span style="color:red;font-weight:bold">Danger Must equal GridSample grid_size. Otherwise the meaning of cluster_thresh breaks

type

"SpUNet-v1m1"

spconv-based sparse 3D UNet

Keep as is

in_channels

6

Input feature dimension. Sum of Collect feat_keys (color 3 + normal 3)

<span style="color:red;font-weight:bold">Danger Must be changed together whenever feat_keys changes. 3 for color only, 9 if coordinates are included

num_classes

0

Number of outputs of the backbone's own classification head. If 0, outputs features only, without a head

Keep 0 for PointGroup (the head is on the PG side)

channels

(32, 64, 128, 256, 256, 128, 96, 96)

Channels for 4 encoder stages + 4 decoder stages. First half encoder, second half decoder

Last value = backbone_out_channels. For small objects, enlarging the channels of the shallow stages (32, 64) is more effective than the deep stages. Increases memory

layers

(2, 3, 4, 6, 2, 2, 2, 2)

Number of residual blocks in each stage

Must have the same length as channels and an even length. Increasing it adds capacity and lowers speed

optimizer.type

"SGD"

Optimization algorithm

SGD is standard for SpUNet. AdamW (lr 0.002–0.006) for a PTv3 backbone

optimizer.lr

0.1

Initial learning rate

<span style="color:orange;font-weight:bold">Caution Based on batch_size 12. Halving the batch gives 0.05. If training diverges, keep halving it

optimizer.momentum

0.9

SGD momentum

Keep as is

optimizer.weight_decay

0.0001

L2 regularization

Up to 0.0005 if overfitting. Generally raised the less data you have

optimizer.nesterov

True

Nesterov momentum

Keep as is

scheduler.type

"PolyLR" || lr = lr₀ × (1 − step/total)^0.9. Decays to 0 over the total steps

Changing epoch changes total_steps automatically. Consider "OneCycleLR" if you need warmup

dataset_type

"ScanNetDataset"

Dataset class

For your own data, add a class in pointcept/datasets/ or use "DefaultDataset"

data_root

"data/scannet"

Root of the preprocessed data. Contains train/val directories

Path to the preprocessing output

data.num_classes

num_classes

Dataset metadata

Same as section 2

data.ignore_index

-1

Dataset metadata

Same as section 2

data.names

class_names

Used by the evaluator to print per-class AP

Same as section 2

train/val/test.split

"train" / "val" / "val"

Split directory to use

Use "test" for test if a separate split exists. The current tester does not support unlabeled test data

test_mode

False

If True, enables GridSample test mode (iterating over all voxels) and TTA

Instance seg does not support test_mode yet. Keep False

CenterShift

apply_z

True

Moves the midpoint of the point cloud's xy (and z) min/max to the origin

Keep as is. Required as the first step

RandomDropout

dropout_ratio

0.2

Randomly removes 20% of the points

<span style="color:orange;font-weight:bold">Caution Small objects have few points and are vulnerable to dropout. Experiment with lowering it to 0.1 or removing it

dropout_application_ratio

0.5

Applies dropout with this probability

Adjust together with the above

RandomRotate (z)

angle

[-1, 1]

In units of π. Random z-axis rotation in the range [-π, π]

Keep as is for indoor scenes. Narrow the range for data with a fixed orientation (e.g. always facing front)

axis

"z"

Rotation axis

Keep as is

center

[0, 0, 0]

Rotation center

The origin, since this runs after CenterShift

p

0.5

Application probability

Keep as is

RandomRotate (x, y)

angle

[-1/64, 1/64]

±2.8° tilt. Simulates sensor tilt

Can be removed if the ground is always level

RandomScale

scale

[0.9, 1.1]

Isotropic random scaling

<span style="color:orange;font-weight:bold">Caution Widening it to [0.8, 1.2] may help strengthen small object detection. However, cluster_thresh is in voxel units, so scale changes blur the sense of physical size

anisotropic

False

Different scale per axis

Usually False

RandomFlip

p

0.5

Flips along the x or y axis

Keep as is unless left-right asymmetry is meaningful in your data

RandomJitter

sigma

0.005

Standard deviation of per-point Gaussian noise (m)

Match it to the sensor noise level. 5mm is for RGB-D

clip

0.02

Maximum absolute noise value (m)

Keep as is

ElasticDistortion

distortion_params

[[0.2, 0.4], [0.8, 1.6]]

Pairs of [grid size (m), distortion magnitude]. Nonlinear distortion on 20cm/80cm grids

<span style="color:orange;font-weight:bold">Caution Can destroy the shape of small objects. Remove it and compare when investigating missed detections

ChromaticAutoContrast

p

0.2

Probability of automatic color contrast adjustment

Keep as is

blend_factor

None

Blend ratio with the original. Random if None

Keep as is

ChromaticTranslation

p

0.95

Probability of adding a constant offset to all colors

Keep as is

ratio

0.1

Offset range (±10% of 255)

Keep it if lighting varies a lot; lower it if color matters for your classes

ChromaticJitter

p

0.95

Probability of per-point color noise

Keep as is

std

0.05

Noise standard deviation (relative to 255)

Keep as is

GridSample

grid_size

0.02

Voxel size (m). Points in the same voxel are merged into one

<span style="color:red;font-weight:bold">Danger The most influential value. Reducing it to 0.01 for small objects gives 2–8x the points and a matching increase in memory. Must equal the model's voxel_size and the val/test grid_size. The cluster_* values need readjusting

hash_type

"fnv"

Voxel hash function

Keep as is

mode

"train"

Picks one random point per voxel

Always "train" for train

return_grid_coord

True

Returns integer voxel coordinates. Required for spconv input

Always True

SphereCrop

sample_rate

0.8

Keeps only the 80% of points closest to a random center

<span style="color:orange;font-weight:bold">Caution 20% is cut off, so small objects can disappear entirely. Experiment with 1.0 or removing it. If memory allows, switch to the point_max method

mode

"random"

How the center is chosen

random for train

NormalizeColor

(none)

Normalizes color from [0,255] → [-1,1]

Remove if colors are already normalized. If there is no color, fill it with 0

InstanceParser

segment_ignore_index

(-1, 0, 1)

Sets the instances of these semantic classes to -1 and computes each instance's centroid and bbox

Same value as section 2

instance_ignore_index

-1

Ignored instance value

Same as the model value

ToTensor

(none)

numpy → torch conversion

Keep as is

Collect

keys

coord, grid_coord, segment, instance, instance_centroid, bbox

List of keys passed to the model

Keys required by the model's forward. Keep as is

feat_keys

("color", "normal")

Concatenates these keys to create feat

<span style="color:red;font-weight:bold">Danger If you change it, change the backbone in_channels at the same time. For data without normals, ("color",) + in_channels=3

Copy

keys_dict

coord→origin_coord, segment→origin_segment, instance→origin_instance

Preserves the original points before voxelization. The evaluator computes AP at the original resolution

Keep as is. Evaluation is impossible without it

GridSample

grid_size

0.02

Must be the same as train

<span style="color:red;font-weight:bold">Danger Always the same as train

SphereCrop (commented out)

point_max

1000000

Enable when memory runs out

Uncomment if very large scenes cause OOM

CenterShift

apply_z

False

Re-centers xy only, after GridSample

Keep as is

Collect

keys

train keys + origin_*, name

Passes the original coordinates/labels and the scene name

Keep as is

offset_keys_dict

offset→coord, origin_offset→origin_coord

Generates the in-batch scene boundary offsets at both resolutions

Keep as is

CheckpointLoader

keywords / replacement

"module." / "module."

Substitutes state_dict keys when loading weight

Prefix mapping when using weights from another framework

IterationTimer

warmup_iter

2

Excludes the first N iterations from timing

Keep as is

InformationWriter

(none)

Logs loss and lr to the log/tensorboard/wandb

Keep as is

InsSegEvaluator

segment_ignore_index

(-1, 0, 1)

Classes excluded from evaluation

Same as section 2

instance_ignore_index

-1

Same

(in code) min_region_sizes

100

Predictions with fewer than 100 points are excluded from evaluation

<span style="color:orange;font-weight:bold">Caution Not exposed in the config. Modify evaluator.py:339 directly. Match it with cluster_propose_points

(in code) overlaps

0.5~0.95 + 0.25

IoU thresholds for AP calculation. Produces mAP, AP50, AP25

Keep as is

CheckpointSaver

save_freq

None

If None, saves only model_last + model_best. If an integer, also saves every N epochs

If there is enough disk space, set it to e.g. 100 so you can recover midway

PreciseEvaluator

test_last

False

Runs precise evaluation with the tester after training ends. False uses the best checkpoint, True the last

Keep as is

test.type

"InsSegTester"

Tester dedicated to instance seg

Keep as is

segment_ignore_index

(-1, 0, 1)

Same as section 2

Same

instance_ignore_index

-1

Same

verbose

False

Prints detailed per-scene results

True when analyzing failure types

Voxel size

train.GridSample.grid_size = val.GridSample.grid_size = test.GridSample.grid_size = model.voxel_size. If changed, also readjust cluster_thresh, cluster_min_points, cluster_propose_points, and the evaluator's min_region_sizes

Ignored classes

The single segment_ignore_index variable is passed to the model, InstanceParser (train/val/test), InsSegEvaluator, and InsSegTester. Changing the variable is enough

Input features

Collect.feat_keys ↔ backbone.in_channels

Backbone output

backbone.channels[-1] ↔ backbone_out_channels

Number of classes

Length of class_names = num_classes = semantic_num_classes = data.num_classes

Batch and lr

When changing batch_size, scale optimizer.lr proportionally

epoch

When changing epoch, adjust eval_epoch. PolyLR total_steps is automatic

Small object filters

cluster_min_points ≤ cluster_propose_points ≈ evaluator min_region_sizes

type

"PG-v1m1"

"PG-v1m2"

v1m2 takes the loss from the config and supports backbone freezing

backbone_out_channels

96

64

Must match PTv3 dec_channels[0]

criteria

(none, CE fixed)

CrossEntropyLoss + LovaszLoss

<span style="color:orange;font-weight:bold">Caution Available only in v1m2. Lovasz optimizes IoU directly, which favors small classes. To add class weights, add weight= to CrossEntropyLoss. Adjust the ratio with loss_weight

freeze_backbone

(none)

False

If True, freezes the backbone and trains only the head. For linear evaluation of a pretrained backbone

in_channels

6

Input feature dimension

Same rule as SpUNet. Linked to feat_keys

order

("z", "z-trans", "hilbert", "hilbert-trans")

Types of space-filling curves used for point serialization

Keep as is. Fewer curves means faster, with slightly lower accuracy

stride

(2, 2, 2, 2)

Downsampling factor of each encoder stage

Keep as is

enc_depths

(2, 2, 2, 6, 2)

Number of blocks in the 5 encoder stages

Model capacity. Increasing it raises memory/time

enc_channels

(32, 64, 128, 256, 512)

Encoder channels

For small objects, enlarging the shallow-stage (32, 64) channels is effective

enc_num_head

(2, 4, 8, 16, 32)

Number of encoder attention heads

Keep channels / head = 16

enc_patch_size

1024 × 5

Patch (window) size of serialized attention

Can be reduced to 512 for small scenes. Directly affects memory

dec_depths

(2, 2, 2, 2)

Number of blocks in the 4 decoder stages

Keep as is

dec_channels

(64, 64, 128, 256)

Decoder channels. [0] is the final output

<span style="color:red;font-weight:bold">Danger dec_channels[0] = backbone_out_channels

dec_num_head

(4, 4, 8, 16)

Number of decoder heads

Keep channels / head = 16

dec_patch_size

1024 × 4

Decoder patch size

Same as enc

mlp_ratio

4

FFN expansion ratio

Keep as is

qkv_bias

True

QKV projection bias

Keep as is

qk_scale

None

attention scale. 1/√d if None

Keep as is

attn_drop / proj_drop

0.0

attention / projection dropout

0.1 if overfitting

drop_path

0.3

Stochastic depth rate

<span style="color:orange;font-weight:bold">Caution Keep 0.3 with little data, 0.1–0.2 with a lot. Lower it if underfitting

shuffle_orders

True

Shuffles the serialization order on every forward (augmentation effect)

Keep as is

pre_norm

True

Pre-LayerNorm structure

Keep as is

enable_rpe

False

Relative positional encoding

Slightly higher accuracy, lower speed. Cannot be used together with flash attention

enable_flash

True

Uses FlashAttention

<span style="color:orange;font-weight:bold">Caution False on GPUs without flash-attn installed. When False, upcast_* takes effect

upcast_attention / upcast_softmax

False

Computes attention in fp32

True if NaN appears with flash disabled + AMP

enc_mode

False

If True, encoder only (for classification)

False for segmentation

pdnorm_*

bn/ln False, decouple True, adaptive False, affine True

Multi-dataset conditional normalization (PPT) settings

Keep all defaults for a single dataset. pdnorm_conditions is ignored

optimizer

SGD, lr 0.1, wd 1e-4

AdamW, lr 0.006, wd 0.05

<span style="color:red;font-weight:bold">Danger Transformers do not converge well with SGD. PTv3 must use AdamW

scheduler

PolyLR

OneCycleLR

Cosine decay after warmup (pct_start 5%). max_lr is a list per param group

scheduler.max_lr

-

[0.006, 0.0006]

[default group, block group]. Matches the order of param_dicts

scheduler.pct_start

-

0.05

Warmup fraction of the total steps

scheduler.anneal_strategy

-

"cos"

Decay curve after warmup

scheduler.div_factor

-

10.0

Starting lr = max_lr / 10

scheduler.final_div_factor

-

1000.0

Final lr = starting lr / 1000

param_dicts

None

[dict(keyword="block", lr=0.0006)]

<span style="color:orange;font-weight:bold">Caution Attention blocks get 1/10 of the lr. The standard setting when fine-tuning a pretrained backbone

RandomDropout.dropout_application_ratio

0.5

0.2

PTv3 applies dropout less often. The PTv3 value is better for small objects

ChromaticTranslation.ratio

0.1

0.05

Half the color offset

SphereCrop

| point_max=204800

<span style="color:orange;font-weight:bold">Caution A cap on the point count, not a ratio crop. If a scene has 204800 points or fewer, no crop happens at all, so small objects are not cut off

CenterShift(apply_z=False) after GridSample

No

Yes

PTv3 uses coordinates for positional encoding, so it needs re-centering after voxelization