Upload from Ropedia Academy

README.md

@@ -4,19 +4,25 @@ library_name: pytorch
 tags:
 - ropedia-academy
 - educational
+- embodied-ai
+- from-scratch
+- reproducible
 - implicit-neural-representation
 ---
 
 # Neural SDF (DeepSDF-style)
 
-An MLP signed-distance field with an eikonal regularizer; the surface is its zero level set (marching cubes).
+> An MLP signed-distance field with an eikonal regularizer; the surface is its zero level set (marching cubes).
 
-Trained from scratch in **[Ropedia Academy](https://chaoyue0307.github.io/ropedia-academy/)** — an interactive, bilingual course on embodied & spatial AI. **Educational model:** small and quick to train; the value is the *method* and a reproducible pipeline, not a leaderboard score.
+Trained from scratch in **[Ropedia Academy](https://chaoyue0307.github.io/ropedia-academy/)** — an interactive, bilingual course on embodied & spatial AI. **Educational model:** small and quick to train; the value is the *method* and a reproducible pipeline, not a leaderboard score. Try it live in the **[Ropedia demos Space](https://huggingface.co/spaces/cy0307/ropedia-demos)**.
+
+## At a glance
 
 | | |
 |---|---|
+| **Base model** | Trained **from scratch** (random initialization) — no pretrained base model. |
 | **Task** | implicit 3D shape |
-| **Data** | analytic torus samples |
+| **Training objective** | Regress a **signed distance field** (clamped L1) with an **eikonal** gradient regularizer; surface = zero level set. |
 | **Track** | B · 3D & rendering |
 | **Notebook** | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ChaoYue0307/ropedia-academy/blob/main/notebooks/training/B_deepsdf_shape.ipynb) |
 
@@ -28,22 +34,48 @@ Trained from scratch in **[Ropedia Academy](https://chaoyue0307.github.io/ropedi
 - **Split:** generative (infinite)
 - **Source:** procedural (analytic torus)
 
-## Results
+## Training config
 
-| metric | value |
-|---|---|
-| l1 (final) | 0.016 |
+Adam (lr 1e-3), 2000 steps; SD targets clamped to ±0.1 + eikonal regularizer; near-surface sampling.
+
+## Evaluation results
+
+| metric | value | meaning |
+|---|---|---|
+| `l1 (final)` | 0.016 |  |
 
 
 ![figure](figure.png)
 
-## How to use
+## Inference example
 
 ```python
 import torch
-state = torch.load("model.pt", map_location="cpu")   # some labs save pose.pt / gaussians.pt / transform.pt
-# Rebuild the model class from the Ropedia Academy notebook (linked above), then:
-# model.load_state_dict(state)
+state = torch.load("sdf.pt", map_location="cpu")   # this repo's checkpoint
+# Rebuild the exact module from the lab notebook (see "Reproduce"), then:
+# model.load_state_dict(state); model.eval()
+```
+
+## Limitations
+
+**Educational scale.** Trained quickly on CPU on small or synthetic data, so absolute numbers are not competitive with production systems — the value is the *method* and a reproducible pipeline. No large-scale data, no hyperparameter sweep, and no multi-seed variance is reported. **Not for production use.**
+
+## Failure cases
+
+Clamping the *prediction* (not just the target) zeroes gradients (saturation); a too-high-frequency encoding overfits noise.
+
+## Reproduce / train your own
+
+**One click:** open the notebook in Colab → **Runtime → GPU → Run all**, then run its *Publish to the Hugging Face Hub* cell.
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ChaoYue0307/ropedia-academy/blob/main/notebooks/training/B_deepsdf_shape.ipynb)
+
+**From a shell:**
+```bash
+git clone https://github.com/ChaoYue0307/ropedia-academy.git && cd ropedia-academy
+pip install torch numpy matplotlib scikit-learn scikit-image gymnasium
+jupyter nbconvert --to notebook --execute notebooks/training/B_deepsdf_shape.ipynb --output run.ipynb
+# optional: override training length, e.g.  STEPS=2000  (or EPISODES=600)  before running
 ```
 
 ## Files
@@ -53,10 +85,34 @@ state = torch.load("model.pt", map_location="cpu")   # some labs save pose.pt /
 - `sdf.pt`
 
 
-## Reproduce / train your own
+## License
+
+Code & weights: **MIT** (this repository) — educational use encouraged.  
+Data: generated procedurally in the notebook — no external dataset.
+
+## Citation
+
+If you use this model or the course materials, please cite:
+
+```bibtex
+@misc{ropedia_academy,
+  title  = {Ropedia Academy: an interactive course on embodied & spatial AI},
+  author = {Ropedia Academy},
+  year   = {2026},
+  howpublished = {\url{https://chaoyue0307.github.io/ropedia-academy/}}
+}
+```
+
+
+**Method / original work:** Park et al., *DeepSDF*, CVPR 2019; Gropp et al., *Implicit Geometric Regularization (eikonal)*, ICML 2020.
+
+## Related assets
 
-Open the [lab notebook in Colab](https://colab.research.google.com/github/ChaoYue0307/ropedia-academy/blob/main/notebooks/training/B_deepsdf_shape.ipynb) → **Runtime → GPU → Run all**, then its *Publish to the Hugging Face Hub* cell. Browse every lab in the [Ropedia Academy Labs tab](https://chaoyue0307.github.io/ropedia-academy/labs).
+- 🚀 **Live demos:** [https://huggingface.co/spaces/cy0307/ropedia-demos](https://huggingface.co/spaces/cy0307/ropedia-demos)
+- 🤗 **All trained models + collection:** [https://huggingface.co/cy0307](https://huggingface.co/cy0307)
+- 📚 **Course & all labs:** [https://chaoyue0307.github.io/ropedia-academy/](https://chaoyue0307.github.io/ropedia-academy/) · [Labs tab](https://chaoyue0307.github.io/ropedia-academy/labs)
+- 💻 **Source / notebooks:** [github.com/ChaoYue0307/ropedia-academy](https://github.com/ChaoYue0307/ropedia-academy)
 
 
 ---
-*Part of the [Ropedia Academy](https://chaoyue0307.github.io/ropedia-academy/) trained-model collection.*
+*Part of the [Ropedia Academy](https://chaoyue0307.github.io/ropedia-academy/) trained-model collection. Contributions & issues welcome on [GitHub](https://github.com/ChaoYue0307/ropedia-academy).*