The problem

You want to know what your observing site can actually see: which part of the sky the trees hide, how low you can follow a planet before it drops behind the roof next door. Stellarium can show your own horizon instead of a generic one, if you give it a panorama of the site. So you take one with a 360° camera, or stitch one from several photos.

Then the hard part starts. For the landscape to be useful, North in the picture has to be true North, and the horizon has to sit where the real horizon is. A camera on a tripod is never perfectly level, and a compass reading is only approximate. A few degrees off, and the planner tells you a star clears the trees when it doesn’t.

Guessing the orientation

Rotate the panorama by eye using a compass bearing, and hope the camera was level. Errors of a few degrees go unnoticed.

Aligning with PanoPose

Drag the Sun, or a bright star or planet, in your picture onto the marker computed for your site and time. The sky itself fixes the orientation.

PanoPose reads the capture time and GPS position from the image’s metadata, works out where the Sun, Moon, planets and bright stars were at that moment, and draws them over the panorama with an Alt/Az grid. You turn and tilt the panorama until the real objects sit on their markers. Nothing is guessed automatically: you make the match, and you can see exactly how good it is.

How it works

1. LoadOpen a 2:1 equirectangular panorama. Time and site come from its EXIF/XMP metadata, or you type them in.
2. AlignDrag a visible object onto its marker, then pin it and roll around it to match a second one.
3. ExportSave the pose in the image's metadata, or export a calibrated PNG or a Stellarium landscape ZIP.

The orientation is a true spherical rotation, so PanoPose won’t let you do something physically impossible. You can’t lift the whole horizon uniformly: tilting it raises one side and lowers the opposite side by the same amount, which is exactly what a camera that wasn’t level does.

Made for careful alignment

Two stars, no drift

In Roll Target mode, the first click pins the sky direction under the pointer. Roll around it to bring a second star, planet or landmark into place without losing the first.

The image stays under your hand

Align Target drags along the sphere, so the point you grab stays under the cursor in every direction, including diagonals.

A sky to match against

Planetarium mode toggles the 1500 brightest catalogue stars above your horizon with one button, so you can blink between the picture and the computed sky.

Compare with a reference

Load an already calibrated panorama from the same spot as a reference layer, then fade or blink between the two to line up the shared landscape.

Your originals stay untouched

Save As only writes metadata, and exports are new files. The source pixels are never remapped or re-encoded.

Ready for Stellarium

Exports a landscape ZIP with landscape.ini, your site's coordinates and the oriented panorama, with optional transparent sky and a cap to hide the tripod.

One technique the README describes in detail: a GoPro MAX can take several night shots in quick succession, which you can stack to bring out faint stars. Calibrate that night panorama against the stars, then use it as the reference for a daytime panorama taken from the same camera position.

What it supports today

PanoPose is at version 1.4, with release packages (.deb, .rpm and .AppImage) built for amd64 Linux. It works with:

• Full-sphere 2:1 equirectangular panoramas in JPG, PNG or TIFF
• Capture time, timezone, GPS position and pose from EXIF/XMP metadata
• Upright, sideways and upside-down captures
• Sun, Moon, planet and bright-star markers; the star catalogue is bundled, so no network is needed

Two features rely on external programs you install separately. Save As writes metadata with ExifTool, and the optional Remove Sky uses skyseg-ncnn to make the sky transparent. Without them, everything else, including PNG and Stellarium export, still works.

Alignment is manual by design. PanoPose doesn’t detect stars or estimate the orientation for you, and it doesn’t project ordinary phone photos onto the sphere: from those it only imports the time and site.

Get started

1. Install

On amd64 Debian or Ubuntu, download the .deb from the latest release (an .rpm and an .AppImage are there too) and install it:

sudo apt install ./PanoPose_*_amd64.deb

To write orientation back into your images with Save As, also install ExifTool:

sudo apt install libimage-exiftool-perl

2. Or build it from source

You need Rust, Node.js and npm. The quickstart script builds the release app and offers to install the package it produces:

git clone https://github.com/arturormk/panopose-rust.git
cd panopose-rust
./quickstart-panopose.sh

For the optional sky removal, ./quickstart-skyseg-ncnn.sh builds and installs skyseg-ncnn under ~/.local, asking before it starts.

3. Align your first panorama

Start panopose and open your panorama. Then:

1. Check the latitude, longitude and capture time. If the fields are blank, the image has no location metadata: type them in.
2. Switch to Align Target (key A) and drag the Sun, or a bright planet or star, onto its marker.
3. If it still doesn’t fit, switch to Roll Target (key R), click the matched object and drag sideways until a second object meets its marker.
4. Use Export Stellarium ZIP, fill in the landscape name, and install the ZIP using Stellarium’s landscape instructions.

Learn more

• README: every feature, the full alignment workflow, the GoPro MAX night-to-day technique and exactly what each export produces.
• Design blueprint: the product direction, coordinate conventions and orientation model.
• Building skyseg-ncnn: manual build notes for the optional sky removal.
• Changelog, releases and issues: what changed, packages to download, and bug reports.

PanoPose is dual-licensed under MIT or Apache-2.0, at your option. Its bright-star data is derived from the Yale Bright Star Catalog, and ExifTool and skyseg-ncnn are separate programs under their own licences.