360-panorama-viewer — Claude Code skill: what it does, how to install
360-panorama-viewer builds a standalone HTML file with 360° panoramas rendered via Three.js. Useful for creating interactive VR galleries from local or generated equirectangular images.
MIT ★ 138 updated 2026-09-03
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a claude-codeWhat 360-panorama-viewer does
This skill generates a single .html document (usually 3–6 MB) that embeds Three.js along with all panorama textures encoded as base64 JPEG at quality 90. It runs offline without CDN links, providing mouse drag controls, scroll zoom, an auto-rotation switch, and a sidebar chip list to switch scenes.
The build relies on assets/viewer_template.html and scripts/build_viewer.py. It resizes inputs to 1774×887 (2:1 ratio) and performs a seam alignment via np.roll. By shifting the image horizontally to match edges with minimum difference, it prevents visible seams on the sphere without color blending artifacts.
Generating fresh scenes via the gateway needs Python with PIL, numpy, requests, and the AI_GATEWAY_API_KEY variable set. If you provide existing equirectangular images directly, external image generation is bypassed entirely.
What it helps with
- compile interactive 360° VR scenes into a standalone HTML file
- align equirectangular seam artifacts horizontally using
np.roll - switch between spherical environments using a thumbnail sidebar
- replace a single panorama inside an existing HTML bundle
Example prompts for the agent
- Build a 360 panorama HTML viewer from images in
tmp/ - Create an interactive VR scene gallery featuring three fantasy locations
- Swap out the underwater city scene in
outputs/360_viewer.htmlwith a new image
How to install 360-panorama-viewer
1Skills CLI (Vercel)
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a claude-code2Manually: put the files in place
~/.claude/skills/360-panorama-viewer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/360-panorama-viewer/
1Skills CLI (Vercel)
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a codex2Manually: put the files in place
.agents/skills/360-panorama-viewer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a cursor2Manually: put the files in place
.cursor/skills/360-panorama-viewer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install happycapy-ai/Happycapy-skills skills/360-panorama-viewer2Manually: put the files in place
.github/skills/360-panorama-viewer/SKILL.md1Skills CLI (Vercel)
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a gemini-cli2Platform CLI
gemini skills install https://github.com/happycapy-ai/Happycapy-skills --path skills/360-panorama-viewerManually: put the files in place
.devin/skills/360-panorama-viewer/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 360-panorama-viewer
How to install 360-panorama-viewer in Claude Code?
Run npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a claude-code in your terminal.
What does 360-panorama-viewer do?
It packages equirectangular panoramas into an offline Three.js HTML viewer with camera controls and a scene sidebar.
Does the skill require an API key?
The AI_GATEWAY_API_KEY is required only if you generate panoramas using AI models. Building from your own image files works without any API credentials.
Source text
SKILL.md · MIT
---
name: 360-panorama-viewer
description: >
Build a fully self-contained 360° equirectangular panorama viewer as a single HTML file.
The viewer uses Three.js to render immersive spherical panoramas with drag-to-look,
zoom, auto-rotate, and a scene-switcher sidebar. All panorama images are embedded as
base64 JPEG — no server needed. Use this skill whenever the user asks to create a 360
viewer, VR panorama app, immersive scene gallery, equirectangular image viewer, or
wants to combine multiple AI-generated panoramas into an interactive webpage.
Also trigger when the user says things like "make a 360 viewer", "VR world gallery",
"360度全景", "全景查看器", "make scenes I can look around in", etc.
---
# 360° Panorama Viewer Skill
This skill creates a polished, self-contained 360° panorama viewer HTML file.
## What it produces
A single `.html` file (~3–6 MB depending on scene count) that:
- Renders equirectangular panoramas as spherical 360° environments using Three.js
- Supports dragging to look around, scroll to zoom, auto-rotate toggle, fullscreen
- Shows a thumbnail sidebar to switch between multiple scenes
- Works offline — no CDN dependencies, all assets embedded
## Skill assets
| Asset | Purpose |
|---|---|
| `assets/viewer_template.html` | Complete viewer HTML with Three.js inlined; panorama data injected at build time |
| `scripts/build_viewer.py` | Loads images, applies seam fix, base64-encodes, injects into template |
---
## Workflow
### Step 1 — Gather scene specs from the user
Ask (or infer from context) for each scene:
- **Description** of what the panorama should show
- **Title** for the HUD (emoji + name, e.g. `🍄 Mario World`)
- **Thumbnail label** (≤12 chars shown on the sidebar chip)
Typical count: 3–6 scenes. You can also accept user-provided image files directly (skip generation).
### Step 2 — Generate panorama images
For **each scene**, generate a 360° equirectangular panorama image.
**Model choice:**
- **Preferred:** `google/gemini-3.1-flash-image-preview` via AI Gateway — reliable 2:1 output, no safety rejections for fictional themes
- **Alternative:** `gpt-image-2` via AI Gateway at size `1536x1024` — higher quality but may reject branded IP (Mario, Zelda, etc.)
**Generation code (Gemini route):**
```python
import os, requests, base64
from PIL import Image
import io
api_key = os.environ['AI_GATEWAY_API_KEY']
def generate_panorama(prompt: str, save_path: str):
payload = {
"model": "google/gemini-3.1-flash-image-preview",
"prompt": prompt,
"response_format": "b64_json",
"n": 1
}
resp = requests.post(
'https://ai-gateway.happycapy.ai/api/v1/images/generations',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json',
'Origin': 'https://trickle.so'
},
json=payload,
timeout=180
)
resp.raise_for_status()
img_bytes = base64.b64decode(resp.json()['data'][0]['b64_json'])
img = Image.open(io.BytesIO(img_bytes)).convert('RGB')
img.save(save_path)
return save_path
```
**Prompt formula for good equirectangular panoramas:**
```
360 degree equirectangular panorama of [SCENE DESCRIPTION].
[Key visual elements]. [Style description].
Wide seamless landscape, 2:1 aspect ratio,
left and right edges must tile perfectly for 360 VR viewing.
```
**Example prompts:**
- Mario: `360 degree equirectangular panorama of a colorful cartoon mushroom kingdom platformer world. Bright blue sky, rolling green hills, red mushroom houses, floating brick blocks, gold coins, stone castle. Vibrant cartoon illustration, 2:1 aspect ratio, seamless tiling.`
- Underwater city: `360 degree equirectangular panorama of a futuristic underwater city. Bioluminescent buildings, schools of fish, coral reefs, deep ocean light shafts. Cinematic, 2:1 aspect ratio, seamless tiling.`
Save each generated image to a temp path (e.g. `tmp/scene_N_raw.png`).
### Step 3 — Build the viewer
Run the build script, passing all scenes as a JSON array:
```bash
SKILL_DIR=/home/node/.claude/skills/360-panorama-viewer
python3 "$SKILL_DIR/scripts/build_viewer.py" \
--template "$SKILL_DIR/assets/viewer_template.html" \
--output "outputs/360_viewer.html" \
--scenes '[
{"title":"🍄 Mario World","thumb_label":"Mario","image_path":"tmp/mario.png","initial_lon":90},
{"title":"🐚 Underwater City","thumb_label":"Deep City","image_path":"tmp/underwater.png","initial_lon":0}
]'
```
The script will:
1. Resize each image to 1774×887 (standard 2:1)
2. Apply a **pure-roll seam fix** — finds the horizontal offset that minimises left/right edge difference, then `np.roll`s the image. No blending. This ensures the 360° seam is as clean as possible without distorting colors.
3. Base64-encode as JPEG quality 90
4. Inject into the template and write the output HTML
### Step 4 — Deliver
Output the file to `outputs/360_viewer.html` (or user-specified path) and attach it as a static HTML deliverable.
---
## Replacing a single scene in an existing viewer
If the user already has a viewer and wants to swap out one scene (e.g. regenerate Mario), do NOT rerun all scenes — just re-encode the new image and replace its `b64` field in the HTML:
```python
import re, base64, io, numpy as np
from PIL import Image
SKILL_DIR = '/home/node/.claude/skills/360-panorama-viewer'
# Load and fix the new image
img = Image.open('new_mario.png').convert('RGB')
img = img.resize((1774, 887), Image.LANCZOS)
arr = np.array(img)
# pure roll seam fix
f = arr.astype(np.float32)
h, w = arr.shape[:2]
best_roll, best_score = 0, float('inf')
for roll in range(w):
r = np.roll(f, roll, axis=1)
score = float(np.abs(r[:, :5] - r[:, w-5:]).mean())
if score < best_score:
best_score = score
best_roll = roll
fixed = np.roll(arr, best_roll, axis=1)
buf = io.BytesIO()
Image.fromarray(fixed).save(buf, format='JPEG', quality=90)
new_b64 = base64.b64encode(buf.getvalue()).decode('ascii')
# Replace in HTML by matching scene title
with open('outputs/360_viewer.html') as fh:
html = fh.read()
# Match the specific scene entry (adjust title keyword as needed)
pattern = r"(title:\s*'[^']*Mario[^']*',\s*initialLon:\s*[\d.]+,\s*b64:\s*')([^']+)(')"
html_new, n = re.subn(pattern, r'\g<1>' + new_b64 + r'\g<3>', html)
assert n == 1, f"Expected 1 replacement, got {n}"
with open('outputs/360_viewer.html', 'w') as fh:
fh.write(html_new)
print(f'Replaced Mario scene (roll={best_roll})')
```
---
## Seam fix — why pure roll, not blending
Equirectangular panoramas wrap horizontally: x=0 and x=w-1 represent the same physical meridian. AI-generated images rarely place the seam at a natural boundary (e.g. open sky), so the default seam is often visible.
**Pure roll**: shift the whole image left/right to find the position where the 5-pixel columns at both edges are most similar (lowest mean absolute difference). `np.roll()` is a circular shift — no pixels are added or removed, no colors are changed. This is lossless and never creates artifacts.
**Never use blending/color correction** at the seam: it creates a visible "smeared" band where pixel values are artificially averaged, which looks worse than the original seam.
---
## Viewer features reference
The template includes these controls, all functional out of the box:
- **Drag** — look around (mouse or touch)
- **Scroll / pinch** — zoom (FOV 30°–120°, default 75°)
- **Auto Rotate** button — gentle continuous pan
- **Reset** button — return to `initialLon` of current scene
- **Fullscreen** button
- **FOV slider** — right-side vertical range input
- **Thumbnail sidebar** — left-side scene switcher with active highlight
Scene `initialLon` is the starting horizontal angle (0–360). Use it to face an interesting part of the panorama on load (e.g. 90 = face right, 180 = face backwards).
---
## Tips for better panoramas
- Ask for **2:1 aspect ratio** explicitly in every prompt — this is the equirectangular standard
- Mention **"seamless tiling"** and **"left and right edges must connect"** in the prompt
- For fictional/branded themes (Mario, Zelda), describe the visual style without using trademarked names if GPT-Image-2 rejects them: "colorful cartoon platformer mushroom kingdom style" instead of "Mario"
- Gemini rarely rejects prompts and consistently produces good 2:1 panoramas — prefer it for speed
© happycapy-ai · MIT · happycapy-ai/Happycapy-skills