DOCSEARCHbyAlgolia
Submit Docs

DeepSDF

repository·main·Indexed 23 days ago

https://github.com/facebookresearch/deepsdf

An implementation of the CVPR '19 paper for learning continuous Signed Distance Functions (SDFs) for shape representation. The library provides tools for preprocessing mesh data, training models via specs.json configurations, visualizing training progress, and reconstructing and evaluating explicit meshes from trained models.

Tokens
970
Snippets
4
Records
8
Agent score
32%

What's inside DeepSDF

  1. Understand DeepSDF data and experiment layouts

    main

    DeepSDF relies on a specific directory structure for data and experiments to ensure scripts can pass information between stages.

    Data Layout

    Unified data sources are organized by dataset and class:

    <data_source_name>/
    .datasources.json
    SdfSamples/
        <dataset_name>/<class_name>/<instance_name>.npz
    SurfaceSamples/
        <dataset_name>/<class_name>/<instance_name>.ply

    datasources.json maps dataset names to their source paths.

    Experiment Layout

    Experiments collect all relevant outputs in a single directory:

    <experiment_name>/
    specs.json (Required to start)
    Logs.pth
    LatentCodes/<Epoch>.pth
    ModelParameters/<Epoch>.pth
    OptimizerParameters/<Epoch>.pth
    Reconstructions/<Epoch>/
        Codes/<MeshId>.pth
        Meshes/<MeshId>.pth
    Evaluations/
        Chamfer/<Epoch>.json
        EarthMoversDistance/<Epoch>.json

  2. Pre-process mesh data for training

    main

    Use preprocess_data.py to convert meshes into a unified data source. This script uses the compiled C++ binaries to generate SDF samples or surface samples.

    To generate SDF samples (required for training), run the script with your data directory, source path, dataset name, and a split file. Use the --skip flag to avoid re-processing existing data.

    python preprocess_data.py --data_dir data --source [...]/ShapeNetCore.v2/ --name ShapeNetV2 --split examples/splits/sv2_sofas_train.json --skip

  4. Reconstruct meshes from a trained model

    main
    To generate explicit mesh representations from the test set using a trained model, use reconstruct.py. By default, it uses the latest model parameters. You can specify a specific checkpoint using the --checkpoint flag followed by the epoch number.

  5. Train a DeepSDF model

    main

    Models are trained using train_deep_sdf.py. All training parameters (network architecture, data references, etc.) are defined in a specs.json file located within the experiment directory. This ensures reproducibility and avoids long command-line arguments.

    To continue training from a specific interrupted state, use the --continue flag with an epoch index. Note that ModelParameters, OptimizerParameters, and LatentCodes directories must all contain the corresponding checkpoint for this to work.

  6. Use headless rendering for preprocessing

    main

    The preprocessing script requires an OpenGL context. By default, Pangolin opens a window for each shape. If Pangolin was compiled with EGL support, you can enable headless mode to prevent windows from stealing focus by setting the PANGOLIN_WINDOW_URI environment variable.

    export PANGOLIN_WINDOW_URI=headless://

  7. Build the DeepSDF preprocessing binaries

    main

    The preprocess_data.py script requires C++ executables for surface sampling and SDF sampling. To build them, you must have the following dependencies installed:

    • CLI11
    • Pangolin
    • nanoflann
    • Eigen3

    Follow the standard CMake build procedure:

    mkdir build
cd build
cmake ..
make -j

  8. Evaluate reconstructions

    main

    Evaluation requires a two-step process:

    1. Pre-process test meshes: Run preprocess_data.py with the --surface flag to generate surface samples for the test set.
    2. Run evaluation: Use evaluate.py with the experiment directory, data directory, and the appropriate split file.

    Note: Due to the stochastic nature of reconstruction (gradient descent with random initialization), results may vary across runs. The reported metrics in the original paper were obtained by keeping the best of two reconstructions per shape.