Metadata-Version: 2.4
Name: pano-cli
Version: 0.3.5
Summary: Local DJI photo sphere stitcher
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=11.3
Requires-Dist: opencv-python-headless>=4.10
Requires-Dist: scipy>=1.13

# Pano Studio

Fast, native-resolution DJI 360° panorama stitcher and full-screen WebGL sphere viewer.

## Quick Start

Open the full-screen map from the project folder:

```bash
uv run pano-studio
```

Open the local URL printed in the terminal. Add `--browser` to open it automatically.

The Places map uses bundled [Natural Earth 1:50m country boundaries](https://github.com/nvkelso/natural-earth-vector/blob/v5.1.2/geojson/ne_50m_admin_0_countries.geojson) and [state and province boundaries](https://github.com/nvkelso/natural-earth-vector/blob/v5.1.2/geojson/ne_10m_admin_1_states_provinces_lines.geojson). It works offline. Select a thumbnail
to open the viewer, or select a photo stack to browse the captures at that
location in Grid. Select a place heading in Grid to show that group on the map.
Use **Grid** or **All photos** to browse the full library, including photos
without GPS, or use **B&W** for a grayscale map.
A capture with a single frame opens as a flat photo.

Captures with a matching DNG for every source frame have a yellow thumbnail
outline in Places and a **DNG** button in the viewer. It develops the RAW frames with
Apple Core Image on Metal at full resolution. Use **JPEG** to switch back.
Press **Esc** to return to the map at the previous center and zoom in the current tab.

The map reads one `PANORAMA/<year>/metadata.json` per year, with capture
dates, median GPS locations, and per-frame EXIF and DJI metadata grouped by
capture folder name. Set an optional `place_name` on a capture to label its
location. The example regions have built-in labels, and other unnamed locations
show coordinates. Use `--library PATH` for a different
library and restart the server after adding captures. The viewer stitches
from the original JPEGs on demand and caches the most recently stitched
panorama in memory. Each capture folder holds only the original JPEGs and DNGs.

Stitch a DJI panorama folder and open it full screen:

```bash
uv run pano-studio --folder PANORAMA/2022/100_0727
```

Use `--folder` for source photos on the same computer. Pano Studio reads them
directly from disk and reuses the last stitch on browser reload while the server
is running and the folder is unchanged.

Stitching requires Apple Metal and a macOS session with GPU access.

Use **Open studio** on the map to open or drop a DJI photo folder or an existing
panorama.

View an existing equirectangular JPEG directly:

```bash
uv run pano-studio --view 100_0727-panorama-360.jpg
```

## Debug a stitch

Press **D** or select **Borders** in the viewer to toggle the projected edges
of the original source images and see their filenames. The outlines stay thin
as you zoom.

Generate a local report from the original JPEGs, including the frame ownership
map, an adjustable overlay for any two projected frames, and feature-match
errors before and after alignment.

```bash
uv run pano-studio --folder PANORAMA/2022/100_0589 --debug-stitch ./stitch-debug --browser
```

The command prints the path to the report and exits. Each run writes to a new
subfolder. The report compares seam candidates at the resolution used for seam
finding and shows the selected composite before Metal blending and sky fill.
JPEG diagnostics can run without a GPU. Open the capture normally to render the
full-resolution panorama.

## Pipeline Highlights

- **Propeller & body mask detection**: Automatically masks upper-border propeller shadows on upward-tilted DJI frames before feature matching and projection.
- **Fast sparse bundle adjustment**: Parallel SIFT + RANSAC homography matching with a DJI telemetry check on matches, joint pose and lens refinement, and a pose-only fallback for unstable lens fits.
- **Consistent color & exposure**: Global log-tone and white-balance alignment, wrap-seamless low-frequency residual leveling, seam selection by comparing dynamic programming and graph cut, and tiled Metal multi-band blending at native resolution with upper-sky completion and GPano XMP metadata.

The Python code lives in `pano_studio/stitch/` (pipeline and image processing),
`pano_studio/server/` (CLI, HTTP routes, and library discovery), and
`pano_studio/metal/` (native GPU code). Browser assets are grouped by screen in
`pano_studio/web/places/` and `pano_studio/web/viewer/`.

Within `pano_studio/stitch/`, `pipeline.py` coordinates alignment, blending,
and export. `propeller.py` owns cut detection, scaling, and source-frame
cleanup. `sky.py` estimates the sky color and feather weights, and `clouds.py`
continues cloud bands when both sides of the zenith gap support a match.
`gaps.py` repairs general interior holes, `sky_borders.py` builds the viewer
overlays, and `output.py` encodes the GPano JPEG.

## Viewer Interaction

- **Drag / Arrow keys**: Look around
- **Scroll / Pinch / `+` `-`**: Zoom
- **Double-click / `R` / `Home`**: Reset view
- **Projection buttons / `1`–`4`**: Open 360° (default), Sphere (ground-centered), Inverse Sphere (sky-centered), or Flat directly
- **`A` / Space**: Toggle auto-rotate in the 360° projections
- **`C`**: Show or hide the compass
- **`N`**: Show the compass and turn to north, or to the panorama’s zero heading when capture orientation is unavailable
- **`F`**: Toggle browser fullscreen
- **`H`**: Hide or restore the controls. Tap the photo to bring them back.
- **`D`**: Toggle source image borders
- **`S`**: Download the original panorama, including GPano metadata on stitched JPEGs
- **Camera button**: Save the current view as a PNG
- **Motion button**: Look around by moving your phone on supported devices
- **Drop a folder or image**: Stitch DJI source frames or open an equirectangular panorama

## WebXR

Open a panorama and tap the goggles icon at the right end of the bottom toolbar. It opens the head-tracked 360° view on compatible headsets. Use the headset's exit control to return to the regular viewer.

For a headset on another device, bind the server to the computer's LAN address and use HTTPS with a certificate the headset trusts. Use a certificate that matches the address or hostname you open on the headset.

```bash
uv run pano-studio --view panorama.jpg --host YOUR_LAN_IP --port 8443 \
  --certfile certificate.pem --keyfile private-key.pem
```
