monniert/unicorn

(ECCV 2022) Code for Share With Thy Neighbors: Single-View Reconstruction by Cross-Instance Consistency

UNICORN 🦄

Share With Thy Neighbors:
Single-View Reconstruction by Cross-Instance Consistency

Tom Monnier  Matthew Fisher  Alexei A. Efros  Mathieu Aubry

Official PyTorch implementation of Share With Thy Neighbors: Single-View Reconstruction by Cross-Instance Consistency (ECCV 2022). Check out our webpage for video results!

This repository contains:

• scripts to download and load both datasets and pretrained models
• demo to reconstruct cars from raw images (script or interactive notebook )
• configs to train the models from scratch
• evaluation pipelines to reproduce quantitative results
• guidelines to train a model on a new dataset

If you find this code useful, don't forget to star the repo ⭐ and cite the paper 👇

@inproceedings{monnier2022unicorn,
  title={{Share With Thy Neighbors: Single-View Reconstruction by Cross-Instance Consistency}},
  author={Monnier, Tom and Fisher, Matthew and Efros, Alexei A and Aubry, Mathieu},
  booktitle={{ECCV}},
  year={2022},
}

Major code updates 📋

• 08/22: pytorch 1.10 instead of 1.5, big models, kp_eval.py, eval with gradient-based ICP with aniso scale, pascal3D car chamfer eval
• 05/22: first code release

Installation 👷

1. Create conda environment 🔧

conda env create -f environment.yml
conda activate unicorn

Optional visualization 📉

Some monitoring routines are implemented, you can use them by specifying your visdom port in the config file. You will need to install visdom from source beforehand:

git clone https://github.com/facebookresearch/visdom
cd visdom && pip install -e .

2. Download datasets ⬇️

bash scripts/download_data.sh

This command will download one of the following datasets:

• ShapeNet NMR: paper / NMR paper / dataset (33Go, thanks to the DVR team for hosting the data)
• CUB-200-2011: paper / webpage / dataset (1Go)
• Pascal3D+ Cars: paper / webpage (with ftp download link, 7.5Go) / UCMR annotations (bbox + train/test split, thanks to the UCMR team for hosting them) / UNICORN annotations(3D shape ground-truth)
• CompCars: paper / webpage / dataset (12Go, thanks to the GIRAFFE team for hosting the data)
• LSUN: paper / webpage / horse dataset (69Go) / moto dataset (42Go)

3. Download pretrained models ⬇️

bash scripts/download_model.sh

We provide a small (200Mo) and a big (600Mo) version for each pretrained model (see training section for details). The command will download one of the following models:

• car trained on CompCars: car.pkl / car_big.pkl
• car_p3d trained on Pascal3D+: car_p3d.pkl / car_p3d_big.pkl
• bird trained on CUB: bird.pkl / bird_big.pkl
• moto trained on LSUN Motorbike: moto.pkl / moto_big.pkl
• horse trained on LSUN Horse: horse.pkl / horse_big.pkl
• sn_* trained on each ShapeNet category: airplane, bench, cabinet, car, chair, display, lamp, phone, rifle, sofa, speaker, table, vessel
• sn_big_* trained on each ShapeNet category: airplane, bench, cabinet, car, chair, display, lamp, phone, rifle, sofa, speaker, table, vessel

Important notes 📃

1. ❗These small models correspond to an old version of the code, with in particular less training iterations. We release them for retrocompatibility and completeness, retrain from scratch for a thorough comparison.
2. it may happen that gdown hangs, if so you can download them manually with the gdrive links and move them to the models folder.

How to use 🚀

1. Demo - 3D reconstruction of car images 🚘

You first need to download the car model (see above), then launch:

cuda=gpu_id model=car_big.pkl input=demo ./scripts/reconstruct.sh

where gpu_id is a target cuda device id, car_big.pkl corresponds to a pretrained model, demo is a folder containing the target images. Reconstruction results (.obj + gif) will be saved in a folder demo_rec.

We also provide an interactive demo to reconstruct cars from single images.

2. Train models from scratch 🏃

To launch a training from scratch, run:

cuda=gpu_id config=filename.yml tag=run_tag ./scripts/pipeline.sh

where gpu_id is a device id, filename.yml is a config in configs folder, run_tag is a tag for the experiment.

Results are saved at runs/${DATASET}/${DATE}_${run_tag} where DATASET is the dataset name specified in filename.yml and DATE is the current date in mmdd format.

Configs and guidelines 🔆

Available configs are:

• sn/*.yml, sn_big/*.yml for each ShapeNet category
• car.yml, car_big.yml for CompCars dataset
• cub.yml, cub_big.yml for CUB-200 dataset
• horse.yml, horse_big.yml for LSUN Horse dataset
• moto.yml, horse_big.yml for LSUN Motorbike dataset
• p3d_car.yml, p3d_car_big.yml for Pascal3D+ Car dataset

❗NB: we advocate to always check the results after the first stage. In particular for cases like birds or horses, learning can fall into bad minima with bad prototypical shapes. If so, relaunch with a different seed.

Small vs big model 💪

We provide two configs to train a small and a big version of the model. Both versions give great results, the main benefit of the bigger model is slightly more detailed textures. The architecture differences are:

• a shared backbone vs separate backbones
• 32/128/128 vs 64/512/256 code sizes for shape/texture/background
• 16 vs 64 minimal number of channels in the generators

For faster experiments and prototyping, we advocate the training of the small version.

Computational cost 💰

On a single GPU, the approximate training times are:

• roughly 3 days for ShapeNet on a V100
• roughly 10 days for real-image datasets on a 2080Ti

3. Reproduce our quantitative results 📊

A model is evaluated at the end of training. To evaluate a pretrained model (e.g. sn_big_airplane.pkl):

1. move the model to a fake folder and rename it model.pkl (e.g. in runs/shapenet_nmr/airplane_big)
2. point to the fake tag to resume from in the config (e.g. resume: airplane_big in airplane.yml)
3. launch the training (and thus evaluation) with:

cuda=gpu_id config=sn_big/airplane.yml tag=airplane_big_eval ./scripts/pipeline.sh

Chamfer-L1 scores on ShapeNet 📐

airplane	bench	cabinet	car	chair	display	lamp	phone	rifle	sofa	speaker	table	vessel	mean
0.110	0.159	0.137	0.168	0.253	0.220	0.523	0.127	0.097	0.192	0.224	0.243	0.155	0.201

For CUB, the built-in evaluation included in the training pipeline is Mask-IoU. To evaluate PCK, run:

cuda=gpu_id tag=run_tag ./scripts/kp_eval.sh

4. Train on a custom dataset 🔮

If you want to learn a model for a custom object category, here are the key things you need to do:

1. put your images in a custom_name folder inside the datasets folder
2. edit the config file custom.yml (or custom_big.yml) in the configs folder: this includes changing the dataset name to custom_name and setting all training milestones
3. launch training with:

cuda=gpu_id config=custom.yml tag=custom_run_tag ./scripts/pipeline.sh

Further information 📚

If you like this project, check out related works from our group:

• Loiseau et al. - Representing Shape Collections with Alignment-Aware Linear Models (3DV 2021)
• Monnier et al. - Unsupervised Layered Image Decomposition into Object Prototypes (ICCV 2021)
• Monnier et al. - Deep Transformation Invariant Clustering (NeurIPS 2020)
• Deprelle et al. - Learning elementary structures for 3D shape generation and matching (NeurIPS 2019)
• Groueix et al. - AtlasNet: A Papier-Mache Approach to Learning 3D Surface Generation (CVPR 2018)

unicorn's Issues

The most impressive all-in-one 3D reconstruction and generation, with a single-image input (till 2023-10-10), but ...

2023-10-10:

1. dataset is too small ... (objvarse/3d, imagenet-l/2d, ...)
2. the shape generation network is not deep enough, it is diffucult to generate better shape from src_mesh. such as deeper iteration in alphafold, we can image that the shaping is a dynamic processing, step by step.
3. we need better priori stroage, not parameters in functional netowrk, but priori memory network(!), even vecter-db(?), ... such as MPCN.
4. the pose network is too simple, more fowerful network such as robustlock.
5. ......
   Anyway, the is the best design on this 3d recon/gen task, so far.

2023-10-12:
after try, modify, try, modify, try, modify, ...
I think:
if we want to fit a better mesh, these aspects in model we need to optimize from random initialized:
<notice: SINGLE image in, only, here>
a1. input-image: segmentation/mask(SAM) or not #segment background in model or not
a2. input-priori: where? what? #network-parameter, special memeory-priori-netowrk
a*. ......
b1. mesh - morphism #IMPORTANT ball/ring/...; pick up object template; even smplx for human #open/unbound/...
b2. mesh - scale, center, ...
b3. mesh - pose, #IMPORT if we can not predict pose correctly, can not fit a better mesh. (use pose-network? direct fit? or pose related loss)
b*. ......
c1. render-image: background vs foreground/object
c2. render-image: silhouette / shape
c3. render-image: texture
c4. render-light: no light modeling in this paper.
c*. ......

for these fiting aspects, there are different priority to optimzed, there are different composions to optimized.

in this paper, I found that, the pose prediction is not very accurate， so, the final mesh is not good enough.
i think how to do pose prediciton even representation(important, especial for single image in, what is the front-side/start-point of azimuth and eleation), is still an open problem.

Training Reproducibility

I am currently analyzing the training process of your model.
I recognized that results are only partially reproducible as there seems to be some randomness in the training.

Do you know which parts of the code are influencing the reproducibility? Could it be Pytorch3D, also related to this issue facebookresearch/pytorch3d#659?
It would be great if you could tell me more about it, the tests you might have run, and whether you plan to work on this.

Datasets URL error

CUB and LSUN dataset URL are broken. Help!

The result of your model you provided is a little wrong with the images download from the website

I am very appreciated with your work.
I download the images from the website.I found the car, bird, and horse model can not work well with the images.I can get the shape and the texture in the result, but the texture, even the colour is wrong.
And the motobike model works well.

.yml file to train from scratch

Hi, your work is impressive and much appreciated.

I'm trying to train a model from scratch but, even though in the README appears a tutorial to do so, i think there are no examples of .yml files in which training from scratch is specified so i'm a bit lost. What do i have to include in the .yml to train from scratch?

3D-IoU Metric

Dear Authors,

Could you please share how you evaluate the 3D-IoU metric? Thanks...

How to apply muti-gpu?

Hi, I try to retrain the code on muti-gpu by changing the cuda setting. But it still runs on a single gpu, can you help me with this? Thanks

FileNotFoundError: [Errno 2] No such file or directory:

hi , I'm new in AI
I'm training the model from scratch i download the dataset and the package

I run in google colab:
!cuda=GPU-f491dbb6-2dc7-a094-5417-a57de28df194 config=p3d_car.yml tag=run_tag /content/unicorn-main\scripts\pipeline.sh

this appears to me:

Traceback (most recent call last):
File "/usr/local/lib/python3.7/dist-packages/scipy/io/matlab/mio.py", line 39, in _open_file
return open(file_like, mode), True
FileNotFoundError: [Errno 2] No such file or directory: '/content/unicorn-main/datasets/pascal_3d/ucmr_anno/data/car_train.mat'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/content/unicorn-main/src/trainer.py", line 292, in
trainer = Trainer(cfg, run_dir, seed=seed)
File "/content/unicorn-main/src/utils/init.py", line 104, in wrapper
return f(*args, **kw)
File "/content/unicorn-main/src/trainer.py", line 41, in init
self.train_loader, self.val_loader, self.test_loader = create_train_val_test_loader(cfg, rank, world_size)
File "/content/unicorn-main/src/dataset/init.py", line 16, in create_train_val_test_loader
train = get_dataset(name)(split="train", **kwargs)
File "/content/unicorn-main/src/dataset/p3d_car.py", line 38, in init
self.data = scio.loadmat(str(path), struct_as_record=False, squeeze_me=True)['images']
File "/usr/local/lib/python3.7/dist-packages/scipy/io/matlab/mio.py", line 224, in loadmat
with _open_file_context(file_name, appendmat) as f:
File "/usr/lib/python3.7/contextlib.py", line 112, in enter
return next(self.gen)
File "/usr/local/lib/python3.7/dist-packages/scipy/io/matlab/mio.py", line 17, in _open_file_context
f, opened = _open_file(file_like, appendmat, mode)
File "/usr/local/lib/python3.7/dist-packages/scipy/io/matlab/mio.py", line 45, in _open_file
return open(file_like, mode), True
FileNotFoundError: [Errno 2] No such file or directory: '/content/unicorn-main/datasets/pascal_3d/ucmr_anno/data/car_train.mat'

i just want to know where the location of ucmr_anno file install so i can fix it and know the path

i spend so much time searching ucmr_anno file in colab files

help me please and thank for the work