Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add happycapy-ai/Happycapy-skills --skill 360-panorama-viewer -a claude-code
Open on GitHub

What 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.html with 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-code

2Manually: put the files in place

~/.claude/skills/360-panorama-viewer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/360-panorama-viewer/

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

Similar skills

All skills for Frontend and UI →

From the same set41

The whole set →
agent-9-status-monitor agent-9-status-monitor — a Claude subagent that polls your open pull requests, catches merges, closures, new reviews and CI failures, then updates the contribution history and alerts the other agents in the swarm. CX Codex ★ 138repo stars generate-image generate-image generates images from text prompts and edits existing pictures via the AI Gateway API. Connects Claude Code to Gemini, Byteplus Seedream, and GPT-Image models. CX Codex +1 ★ 138repo stars agent-0-strategic-planner The agent-0-strategic-planner subagent ranks GitHub issues by user impact and feasibility. Use it to find meaningful contribution opportunities instead of spending effort on cosmetic fixes. CX Codex ★ 138repo stars claude-code-templates Installs and drives the claude-code-templates CLI: a catalog of agents, slash commands, MCP servers, hooks and project templates for Claude, plus session monitoring. CX Codex +1 ★ 138repo stars agent-8-review-responder The agent-8-review-responder subagent tracks PR reviews and CI checks, handles simple feedback, and replies to reviewers. It escalates security concerns and changes that need human judgment. CX Codex ★ 138repo stars capy-video-gen-skill capy-video-gen-skill — a Claude Code skill that transforms scripts and ideas into full-length videos where character faces remain consistent throughout. Use it when you need to create multi-shot video from text, a story, or a brief concept. CX Codex +1 ★ 138repo stars reddit-post-writer reddit-post-writer drafts authentic Reddit posts via phased emotional state simulation and checks against AI writing habits. CX Codex +1 ★ 138repo stars film-creator film-creator turns a text idea or image into a short film by writing a screenplay, planning scenes, and generating video. Use it to shape a concept into a cinematic story. CX Codex +1 ★ 138repo stars

Project sponsors

Companies that keep this analytics open