---
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]`.