# FCGF: fully convolutional geometric features and the WarpConvNet switch

> FCGF is the PyTorch implementation of the ICCV 2019 work on computing 3D point cloud descriptors in one fully convolutional pass, and as of 2026-07-02 it runs on WarpConvNet instead of MinkowskiEngine. The repository ships training, benchmark and demo scripts with no packaged releases, so adoption means cloning and installing dependencies yourself.

**chrischoy/FCGF** — Fully Convolutional Geometric Features: Fast and accurate 3D features for registration and correspondence.

- Repository: https://github.com/chrischoy/FCGF
- Stars: 737 · Forks: 117
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/chrischoy-fcgf

## One pass over the scan instead of a descriptor per patch

Geometric feature extraction is the first step in registration, reconstruction and tracking, and the prior approach most of the README discusses is patch based. Prior methods either compute expensive low level geometric signatures as input or extract patch based features with a limited receptive field. The README explains the two problems with that: a small 3D patch or set of points mapped to a low dimensional space limits the receptive field and is computationally inefficient, because intermediate representations are computed separately even where the 3D regions overlap.

FCGF changes the shape of the computation. A 3D fully convolutional network computes features in a single pass over the whole scan, so the receptive field covers broad spatial context and the representation scales to large scenes. The features are 32 dimensions. The README also notes that restricting extraction to a subset of interest points lowers spatial resolution for the matching stage that follows, which can reduce registration accuracy.

The result the README reports is that the approach reaches what it calls state-of-the-art accuracy on the 3DMatch benchmark without requiring preprocessing, and is 600 times faster than the most accurate prior method. Those are the paper's numbers, from the ICCV 2019 work, not measurements repeated for this repository.

## Hardest-contrastive and hardest-triplet losses for dense feature sets

The training objective is where the fully convolutional setting breaks the usual recipe, and the README gives a concrete account of why. Standard metric learning assumes features are independent and identically distributed because a batch is built by random sampling. That assumption fails here, because adjacent features in a fully convolutional network are locally correlated, so hard negative mining keeps finding neighbours of the anchor, which are false negatives rather than true mismatches. The README notes that filtering these out is a necessary step, the same way the earlier Universal Correspondence Network used a distance threshold.

The scale difference matters as much. FCGF generates roughly 40k features for a pair of scans, growing with the batch size, while a minibatch in traditional metric learning holds around 1k features. Computing all pairwise distances inside a batch is therefore not feasible, which is why the authors propose the hardest-contrastive and hardest-triplet losses instead.

Both are described as simple variants that use the hardest negatives for features within a positive pair. The claimed practical advantage of the hardest-contrastive variant is memory behaviour: you do not need to keep the temporary variables used to find the hardest negatives, because the loss can be reconstructed from the hardest negative indices afterwards, so the intermediate results across the large feature set can be discarded once those indices are known.

## The 2026-07-02 change from MinkowskiEngine to WarpConvNet

The most recent entry in the project news is a backend change, and it is the one piece of current information a new user needs. As of 2026-07-02 FCGF runs on WarpConvNet instead of MinkowskiEngine. The maintained code path lives under the wcn directory and installs from a prebuilt wheel, so no compilation step is needed. The original MinkowskiEngine checkpoints still work, but they have to be converted once using wcn/convert_me_to_wcn.py.

That last sentence is the practical catch. Any checkpoint you trained earlier, or downloaded from someone else, needs a conversion pass before it can be used with the current code path. The README does not describe what the conversion script changes internally, so treat it as a one-time migration step and verify that your converted weights produce the same descriptors as before.

The repository structure reflects the split. Alongside wcn you still find model, lib, util, config, scripts, and the top level scripts train.py, benchmark.py, config.py and demo.py, which is the layout of a research code drop rather than an installed package.

## Installing the dependencies, since no install command is given

There is no pip install line and no setup file in the README, and the repository has no GitHub releases. The dependency list lives in requirements.txt, which is the starting point for setting up an environment:

```python
numpy
# pytorch  # for anaconda, please refer to pytorch.org for installation
scipy
matplotlib
open3d
# to visualize it, you need tensorflow, but it doesn't have to be in the same virual environment :)
tensorboardX
MinkowskiEngine
# Or follow the installation instruction on github.com/StanfordVL/MinkowskiEngine
future-fstrings
easydict
joblib
scikit-learn
huggingface_hub
```

Two details in that list are worth reading rather than skimming. PyTorch is commented out with a pointer to pytorch.org, which tells you the project expects you to install the framework that suits your environment first. And the MinkowskiEngine entry still points at the original installation instructions, which matters only if you keep the older code path; the WarpConvNet route described in the news section installs from a prebuilt wheel instead.

The tensorboardX and tensorflow comments show a pragmatic stance on visualization dependencies: they are optional and can live in a separate environment. The other entries, open3d, scipy, scikit-learn, easydict, joblib, huggingface_hub and future-fstrings, are the ordinary scientific Python stack, installed by whatever package manager your team already uses.

## Train, benchmark and demo live at the repository root

The root files tell you the intended workflow. train.py is the training entry point, benchmark.py the evaluation script, demo.py an interactive or scripted demonstration, and config.py plus a config directory hold the settings. A lib directory holds the training and loss logic, model the network definition, util the helpers, and scripts the shell level automation.

Because the losses are the unusual part of this work, expect to spend your reading time in lib rather than in model. The hardest-contrastive variant needs the hardest negative indices for each positive feature, and the README notes that roughly 40k features were used to mine the hardest negative while destroying all intermediate variables once the indices were found. Reproducing that behaviour means matching the sampling and mining strategy rather than only the network architecture.

The repository also ships a style config, .style.yapf, and a .gitignore, and an assets directory holding the comparison tables and figures used in the README. The formatting config is a small sign of the code's provenance: this is a research repository that was kept tidy enough for others to build on, not a maintained package with a public API contract.

## Speed claims that were measured years ago on specific hardware

Every performance figure in the README is tied to dated hardware and dated software, and an adopter should read them that way. The news entries record that MinkowskiEngine v0.5 improved FCGF inference speed by a factor of 2.8, taking the feed forward time for ResUNetBN2C on the 3DMatch kitchen point cloud ID-20 from 37ms with ME v0.4.3 down to 13.2ms with ME v0.5.0, measured on a TitanXP with a Ryzen 3700X. A later entry reports the inference time dropping further to 11.8ms, and the v0.5 speedup ranging from 2.7x to 7.7x depending on batch size, as measured on the MinkowskiEngineBenchmark repository.

The headline claim of being 600 times faster than the most accurate prior method comes from the ICCV 2019 paper rather than from a current run, and it compares against the slower accurate method of that era rather than against current sparse convolution libraries.

None of these numbers were re-measured after the switch to WarpConvNet in July 2026, and the repository publishes no releases to attach them to. The maintenance picture is therefore mixed: the last push was on 2026-07-02, so the code is current, while the performance evidence is not. Benchmark your own data before you rely on any of it. The licence is MIT, which places no obligation on commercial use and only requires the notice to be retained.

## How FCGF differs from the point cloud descriptors it replaces

The README positions FCGF against several prior feature approaches, and the comparison is mostly about what gets thrown away. 3DMatch by Zeng and colleagues uses a Siamese convolutional network to learn 3D patch descriptors. CGF by Khoury and colleagues maps 3D oriented histograms into a low dimensional feature space using multi layer perceptrons. PPFNet and PPF-FoldNet by Deng and colleagues adapt the PointNet architecture for geometric feature description, and 3DFeat by Yew and Lee uses a PointNet to extract features in outdoor scenes.

FCGF's argument is that all of those extract a small patch or set of points and map it to a low dimensional space, which caps the receptive field and computes overlapping regions repeatedly. Using expensive low level geometric signatures as input also slows feature computation down.

So the choice is architectural rather than incremental. If your pipeline is already built around patch descriptors and a matching stage tuned for them, FCGF changes the interface as well as the numbers, because it hands you a dense per-point feature grid instead of a list of isolated descriptors, and the loss function has to change with it. A registration approach that expects FCGF features specifically, such as the Deep Global Registration code released separately and referenced in the README, is the natural place to start if you want a working pairing.

## Conclusion

Adopt FCGF when you need dense per-point descriptors for 3D registration and want one fully convolutional pass over a scan rather than patch-based descriptors, and when you can commit to the WarpConvNet code path introduced on 2026-07-02. Do not adopt it as a pip package, because the repository publishes no GitHub releases and gives no installation command, so the dependency stack is yours to assemble. Verify first that your checkpoints load, since the original MinkowskiEngine checkpoints require a one-time conversion with wcn/convert_me_to_wcn.py, and reproduce the speed figures yourself on your own hardware, because every timing quoted in the README was measured years ago on a TitanXP with a Ryzen 3700X.

## FAQ

### What is FCGF used for?

FCGF computes geometric features for 3D scans and point clouds, which is the first step in registration, reconstruction and tracking. The features are 32 dimensions and are computed in a single pass by a 3D fully convolutional network rather than per patch.

### What backend does FCGF use now?

Since 2026-07-02 FCGF runs on WarpConvNet instead of MinkowskiEngine, with the maintained code path under the wcn directory installing from a prebuilt wheel with no compilation. Original MinkowskiEngine checkpoints still work after a one-time conversion with wcn/convert_me_to_wcn.py.

### How do I install FCGF and its dependencies?

The repository gives no install command and publishes no GitHub releases. The dependency list is in requirements.txt, which includes numpy, scipy, matplotlib, open3d, tensorboardX, MinkowskiEngine, future-fstrings, easydict, joblib, scikit-learn and huggingface_hub, with PyTorch commented out and referred to pytorch.org.

### What training losses does FCGF use?

The README describes hardest-contrastive and hardest-triplet losses, variants that use the hardest negatives for features within a positive pair. They exist because fully convolutional training yields roughly 40k features per scan pair, making full pairwise distances infeasible and making adjacent features false negatives for hard negative mining.

## Sources

- [chrischoy/FCGF on GitHub](https://github.com/chrischoy/FCGF)
- [Issues](https://github.com/chrischoy/FCGF/issues)
- [License: MIT](https://github.com/chrischoy/FCGF/blob/master/LICENSE)
- [README](https://github.com/chrischoy/FCGF/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chrischoy-fcgf