| --- |
| title: Spherical Parameterization |
| emoji: 🌐 |
| colorFrom: blue |
| colorTo: green |
| sdk: gradio |
| sdk_version: 6.26.0 |
| app_file: app.py |
| suggested_hardware: zero-a10g |
| pinned: false |
| license: mit |
| --- |
| |
| # Spherical Parameterization Mini-Repo |
|
|
| Focused wrapper around Hoppe/Praun `SphereParam` for closed triangular genus-0 |
| meshes. The native code is the classic spherical parameterization path; no |
| curvature weighting or registration experiments are included. |
|
|
| ## 1. Create One Conda Environment |
|
|
| ```bash |
| conda env create -f environment.yml |
| conda activate sphereparam |
| ``` |
|
|
| It must contain Python, NumPy, Trimesh, Polyscope, and a recent conda clang. |
|
|
| ## 2. Compile Native Tools |
|
|
| ```bash |
| ./compile.sh |
| ``` |
|
|
| The script uses clang from the active conda environment and disables optional |
| image libraries, so no JPEG/PNG development packages are needed. |
|
|
| Expected executables: |
|
|
| ```text |
| bin/unix/MeshSimplify |
| bin/unix/Filterprog |
| bin/unix/reverselines |
| bin/unix/SphereParam |
| ``` |
|
|
| ## 3. Parameterize One Mesh |
|
|
| ```bash |
| python param_mesh.py demos/data/bunny.orig.m --effort 2 -o outputs/bunny_sphereparam.npz |
| ``` |
|
|
| The `.npz` contains: |
|
|
| ```text |
| vertices |
| faces |
| sphere_vertices |
| uv |
| source_mesh |
| effort |
| base_faces |
| ``` |
|
|
| ## 4. Interactive Demo Over One Mesh |
|
|
| This computes the parameterization and opens Polyscope with a slider from mesh |
| to sphere: |
|
|
| ```bash |
| python demo_single_mesh.py demos/data/bunny.orig.m --effort 2 |
| ``` |
|
|
| ## 5. Parameterize A Full Folder |
|
|
| ```bash |
| python param_folder.py /path/to/meshes -o outputs/my_folder --effort 2 --recursive --skip-existing |
| ``` |
|
|
| Supported extensions: |
|
|
| ```text |
| .m .ply .obj .off .stl .glb .gltf |
| ``` |
|
|
| ## 6. Parameterize A Registered Folder With One Template |
|
|
| For registered datasets where every mesh has the same vertex order as a common |
| `template.ply`, compute the spherical parameterization once on the template and |
| reuse it for every registered mesh: |
|
|
| ```bash |
| python param_registered_folder.py /path/to/registered_meshes \ |
| --template /path/to/template.ply \ |
| -o outputs/registered_to_template \ |
| --effort 2 \ |
| --recursive \ |
| --skip-existing |
| ``` |
|
|
| This writes one `.npz` per mesh with: |
|
|
| ```text |
| vertices # per-shape geometry |
| faces # template faces |
| sphere_vertices # template spherical parameterization |
| uv # template UV coordinates |
| registered_to_template |
| template_mesh |
| ``` |
|
|
| Use `--require-same-faces` if the registered meshes should have exactly the same |
| triangles as the template and you want the script to fail otherwise. |
|
|
| If the template was already parameterized: |
|
|
| ```bash |
| python param_registered_folder.py /path/to/registered_meshes \ |
| --template /path/to/template.ply \ |
| --template-npz outputs/template_sphereparam.npz \ |
| -o outputs/registered_to_template |
| ``` |
|
|
| ## 7. View A Saved `.npz` |
|
|
| ```bash |
| python view_npz_uv.py outputs/bunny_sphereparam.npz |
| ``` |
|
|
| The viewer shows: |
|
|
| - an interactive mesh-to-sphere slider |
| - mesh reference |
| - sphere reference |
| - UV/XY color transfer on both mesh and sphere |
|
|
| The color is derived from the spherical parameterization UV coordinates: |
|
|
| ```text |
| u = atan2(y, x) |
| v = acos(z) |
| ``` |
|
|
| normalized to `[0, 1]`. |
|
|
