PoinTr converts a point cloud into point proxies so a transformer can complete it, and its AdaPoinTr weights are still marked coming soon

A challenge win from 2021 promised code that never arrived

The news section runs newest first and the oldest entry is the interesting one. Dated 2021-10-07, it records that a solution built on this model won the championship on the MVP completion challenge at an ICCV workshop, and then adds six words: the code will come soon.

That was almost five years before the last push on 2026-06-24, and no directory in the tree corresponds to it. There is a paper related directory, a data directory, configuration directories, model code, extensions, tools, utilities, demo samples and two entry scripts, but nothing labelled for the challenge.

For a research repository this is a minor gap, since the workshop challenge code is a different artifact from the model itself. It matters in one specific case: if you are looking for the submission that won, it is not here, and the entries between that one and the present describe other work. The 2022 entry records an implementation of a different method, a snowflake network, and the 2023 entries record the adaptive denoising variant and a journal acceptance for it.

The AdaPoinTr table is fully populated under a coming soon heading

The pretrained model section is split in two. The first table is for the original model and gives five rows with full download links and a reported metric each. The second is introduced with a heading that says the adaptive variant is coming soon.

The second table is not empty. It has five rows, each with three download options and a metric, covering the two ShapeNet benchmarks, two projected ShapeNet variants and the PCN benchmark. The links are present, the numbers are present, and only the heading says otherwise.

That contradiction is easy to read past in the opposite direction too: someone assuming the adaptive weights are unavailable will not open the table, and someone assuming they are available will hit a download link whose contents the project has not vouched for. The reported values are also lower than the original model's across every row, which is consistent with the follow-on work being better rather than unfinished.

The distinction that matters for a reader is whether they are after the base model or the denoising variant. The base table is unambiguous. The adaptive one is not.

The PCN row still carries the number the 2021 fix replaced

Four of the base rows are labelled with benchmark names and one is not. ShapeNet-55 and ShapeNet-34 carry the completion distance for the harder benchmarks the authors introduced, the KITTI row carries a different metric entirely, and then there are two PCN rows: PCN and PCN_new.

The news section explains the split. An entry dated 2021-09-09 records a fix to a bug in the dataset file, and states that the performance of the model on the PCN benchmark changed from 8.38 to 7.26 as a result. Those two numbers are exactly the two values in the two PCN rows, with the original figure on the row named PCN and the corrected figure on the row named PCN_new.

So the table is not wrong, but it is a trap. Anyone reading the first PCN row as the headline result for that benchmark will quote a number the project has already superseded. The fix itself came from a pull request against a different repository, the one the data file was taken from, so the fix lives upstream and this repository inherited the corrected file.

Three compiled extensions, one of them installed the legacy way

Getting this to run means building three pieces that are not in the repository. The chamfer distance extension goes through a script at the root:

bash install.sh

The other two are installed straight from source URLs. PointNet++ comes from a pip specification pointing at a git repository and one of its subdirectories, and the GPU kNN operator comes as a pinned wheel file for a release numbered 0.2. Both are third-party, both are pinned by URL rather than by a version range, and neither will move on its own.

The fourth piece has its own troubleshooting path. A missing module error for the gridding extension is answered by changing into the extension directory and running the setup script's install command directly:

    1. cd into extensions/Module (eg extensions/gridding)
    2. run `python setup.py install`

That install command is the deprecated form. On a current setuptools it either refuses or warns, so anyone on a recent Python will meet that instruction and have to install the package the modern way instead. The requirements note the same constraint in prose, that a specific PyTorch version and compiler version are both needed for the extensions to build.

Two packages are pinned old, with a comment saying newer works

The requirements file is mostly unpinned. Argument parsing, a dictionary helper, an HDF5 reader, plotting, the array library, an OpenCV binding, YAML, SciPy, a progress bar, a transforms library and an einsum-style tensor helper all appear with no version at all.

Two entries are pinned, and both carry the same trailing comment. The 3D library is held at 0.9 and the vision library at 0.4.5, and each is followed by a note saying that on newer versions of Python, or in a conda or mamba environment, installing may throw an error, and that installing the latest release seems to work.

That comment is effectively an instruction to ignore the pin. The pin and the comment disagree, and the comment is the one that reflects the current state of the ecosystem. Anyone who installs the file as written gets 2019 and 2020 era builds, which is likely to fight with a current PyTorch regardless of what the note says.

The prose requirements list above the file is looser still, giving minimum versions for PyTorch, Python, the CUDA toolkit and the compiler, then naming the vision library and the 3D library with no versions at all. The two lists also disagree about which constraints are real.

Evaluation takes a GPU list and a difficulty mode

The evaluation entry point is a shell script rather than a Python module, and it takes a GPU identifier as its first positional argument. The rest are flags for the checkpoint, the config, an experiment name, and an optional difficulty mode with three values, easy, median and hard.

bash ./scripts/test.sh <GPU_IDS>  \
    --ckpts <path> \
    --config <config> \
    --exp_name <name> \
    [--mode <easy/median/hard>]

The difficulty mode belongs to the projected benchmarks, where incomplete shapes are graded at three levels of how much of the object survives. It is optional, so a run against a benchmark without that notion simply omits it.

The example runs point at a checkpoint under a pretrained directory and a config under the configuration directory. Neither exists in the tree, which means the checkpoints from the download tables have to be placed by hand at the paths the commands assume. The example that follows uses two different models on two different benchmarks, the base model on PCN and the adaptive model on a projected ShapeNet config, so the two families of configuration directories are named separately.

Inference takes a config and a checkpoint as bare arguments

The inference tool is a Python script whose first two arguments are positional and unlabelled, a config file and a checkpoint file, followed by flags describing where the input lives and where the output should go. The input is either a root directory or a single file, so the same script covers a folder of samples and one object.

python tools/inference.py \
${POINTR_CONFIG_FILE} ${POINTR_CHECKPOINT_FILE} \
[--pc_root <path> or --pc <file>] \
[--save_vis_img] \
[--out_pc_root <dir>] \

The worked example uses an adaptive config and an adaptive checkpoint, with a directory of demo samples as input, a visualisation flag, and an output directory. The demo directory in the tree holds two point cloud files and one polygon file, so a smoke test needs no dataset download at all.

The variable placeholders in the usage block are shell variables, which means the intended usage is to export the config and checkpoint paths once and invoke the tool repeatedly, rather than to paste paths each time. Nothing in the two arguments is validated as a pair, so a config for one model with a checkpoint from another will run and produce output that reflects the mismatch.

The harder benchmarks exist because the originals were too easy

The stated contribution is not only the architecture. Two benchmarks are proposed alongside it, referred to by the number of input views, and they exist because the standard completion datasets use incomplete point clouds that are less diverse than real captures. A separate data document describes them and the other datasets in use, and a second pair of projected variants appears in the adaptive model table.

The metrics differ by benchmark, which is worth knowing before comparing numbers across rows. The ShapeNet rows and the PCN rows report a completion distance in scientific notation, while the KITTI row reports a different measure, and there is a metric script at the repository root that sits outside the main package, which is how that one gets computed.

The method itself is compact enough to state in a sentence. A point cloud is represented as a set of unordered groups of points carrying position embeddings, which turns it into a sequence of point proxies, and a transformer encoder-decoder generates the completion from that sequence. Everything else in the tree, the extensions, the metrics script and the configuration directories, exists to support that one transformation.

Editorial conclusion

PoinTr is worth using if you are reproducing point cloud completion results on the PCN or ShapeNet benchmarks, or if you want a readable reference for the point proxy formulation, since the code is short and the method is one paper rather than a framework. Three things to check first. Building it needs three compiled extensions, two of which come from outside the repository by direct URL, and one of them is installed through a legacy setup command. The AdaPoinTr weights are the better model and are described as coming soon, so do not plan around them. And the PCN number in the pretrained table is the pre-fix figure, with the corrected value living on a separate row, so quote the row you actually loaded.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. yuxumin/PoinTr on GitHub