README.md

metadata

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

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

./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:

bin/unix/MeshSimplify
bin/unix/Filterprog
bin/unix/reverselines
bin/unix/SphereParam

3. Parameterize One Mesh

python param_mesh.py demos/data/bunny.orig.m --effort 2 -o outputs/bunny_sphereparam.npz

The .npz contains:

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:

python demo_single_mesh.py demos/data/bunny.orig.m --effort 2

5. Parameterize A Full Folder

python param_folder.py /path/to/meshes -o outputs/my_folder --effort 2 --recursive --skip-existing

Supported extensions:

.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:

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:

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:

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

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:

u = atan2(y, x)
v = acos(z)

normalized to [0, 1].