Enhance model card with sample usage, library name, and citation (#2)

- Enhance model card with sample usage, library name, and citation (4ac8dbb5454740d1dcd8e90e8d0a7c7d56dc1955)


Co-authored-by: Niels Rogge <[email protected]>

README.md

@@ -1,10 +1,11 @@
 ---
 license: mit
+pipeline_tag: other
 tags:
 - 3D point clouds
 - reconstruction
 - ply
-pipeline_tag: other
+library_name: MinkowskiEngine
 ---
 
 # **ScoreLiDAR: Distilling Diffusion Models to Efficient 3D LiDAR Scene Completion**
@@ -15,4 +16,53 @@ pipeline_tag: other
 Diffusion models have been applied to 3D LiDAR scene completion due to their strong training stability and high completion quality. However, the slow sampling speed limits the practical application of diffusion-based scene completion models since autonomous vehicles require an efficient perception of surrounding environments. This paper proposes a novel distillation method tailored for 3D Li- DAR scene completion models, dubbed ScoreLiDAR, which achieves efficient yet high-quality scene completion. Score- LiDAR enables the distilled model to sample in significantly fewer steps after distillation. To improve completion quality, we also introduce a novel Structural Loss, which encourages the distilled model to capture the geometric structure of the 3D LiDAR scene. The loss contains a scene-wise term constraining the holistic structure and a point-wise term constraining the key landmark points and their relative configuration. Extensive experiments demonstrate that ScoreLiDAR significantly accelerates the completion time from 30.55 to 5.37 seconds per frame (>5x) on SemanticKITTI and achieves superior performance compared to state-of-the-art 3D LiDAR scene completion models. Our model and code are publicly available on https: //github.com/happyw1nd/ScoreLiDAR.
 
 ## Repo Info
-This repository stores checkpoints for the ScoreLiDAR paper. For more information and detailed usage of the models, please refer to the [official GitHub repository](https://github.com/happyw1nd/ScoreLiDAR).
+This repository stores checkpoints for the ScoreLiDAR paper. For more information and detailed usage of the models, please refer to the [official GitHub repository](https://github.com/happyw1nd/ScoreLiDAR).
+
+## Sample Usage
+
+To get started with ScoreLiDAR, follow these steps to set up the environment, download the necessary weights, and run an inference example.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/happyw1nd/ScoreLiDAR
+    cd ScoreLiDAR
+    ```
+
+2.  **Install the environment:**
+    ```bash
+    sudo apt install build-essential python3-dev libopenblas-dev
+    pip3 install -r requirements.txt
+    pip3 install -U MinkowskiEngine==0.5.4 --install-option="--blas=openblas" -v --no-deps
+    pip3 install -U -e .
+    ```
+
+3.  **Download model checkpoints:**
+    Download the required checkpoint files from this Hugging Face repository and place them in the `checkpoints/` directory within your cloned `ScoreLiDAR` repository.
+    ```bash
+    huggingface-cli download happywind/ScoreLiDAR ScoreLiDAR_diff_net.ckpt --local-dir checkpoints
+    huggingface-cli download happywind/ScoreLiDAR refine_net.ckpt --local-dir checkpoints
+    ```
+
+4.  **Run inference:**
+    The inference script will read `.ply` files from the `scorelidar/Datasets/test/` directory. A sample `.ply` file is typically included in the repository for testing. Results will be saved under `scorelidar/results/`.
+    ```bash
+    python3 tools/diff_completion_pipeline.py --denoising_steps 8 --cond_weight 3.5
+    ```
+
+5.  **Visualize results (optional):**
+    You can visualize the generated point cloud files using the provided script:
+    ```bash
+    python3 vis_pcd.py -p <path_to_.ply_file>
+    ```
+
+## Citation
+If you find our paper useful or relevant to your research, please kindly cite our papers:
+
+```bibtex
+@article{zhang2024distillingdiffusionmodels,
+    title={Distilling Diffusion Models to Efficient 3D LiDAR Scene Completion}, 
+    author={Shengyuan Zhang and An Zhao and Ling Yang and Zejian Li and Chenye Meng and Haoran Xu and Tianrun Chen and AnYang Wei and Perry Pengyun GU and Lingyun Sun,
+    journal={arXiv:2412.03515},
+    year={2024}
+}
+```