From Panorama to Planetarium: Building PanoPose

Astronomical software can tell me precisely when the Moon rises.

Unfortunately, the Moon does not rise over a mathematical horizon from my observing site. It rises behind trees, roofs, hills, antennas, and whatever else happens to occupy that particular azimuth.

A planet may technically have risen while remaining invisible behind a ridge for another twenty minutes. A conjunction may happen low enough that one tree makes the difference between seeing it and missing it. A young crescent Moon may appear in a narrow gap in the landscape. An eclipse or planetary event close to sunrise or sunset may be theoretically visible but practically hidden.

For an observer, rise and set times are only theoretical until you know the shape of the real horizon.

That is the problem PanoPose is meant to solve.

PanoPose is a free and open-source Linux desktop application for taking a full-sphere 360° panorama of a real location, calibrating it against real altitude and azimuth coordinates, and turning it into something useful for astronomical planning — including a ready-to-install Stellarium landscape.

The basic idea is simple:

Take a picture of your horizon, teach the picture where it is looking, and let the planetarium use the real landscape.

Capturing the whole horizon used to be the hard part

Years ago, when I wanted a panorama of an observing site, I did it the traditional way.

Take a photograph.

Rotate the camera.

Take another.

Keep enough overlap.

Repeat until you have covered the full 360°.

If you also need a large vertical field of view, repeat the process at different elevations.

Then feed everything into Hugin or another panorama stitcher and hope that the seams, exposure differences, moving branches, clouds, and projection geometry all cooperate.

That still works, and for very high-resolution panoramas it may still be the right solution.

But consumer 360° cameras have changed the practical equation.

I now use an old Huawei CV60 connected to my phone and mounted on a monopod. The monopod is useful because a full-sphere camera sees almost everything, including whatever is holding it up, so minimizing the footprint makes the final image cleaner.

One shot gives me a 5376×2688 pixel, 2:1 equirectangular panorama covering the complete 360×180° sphere.

No stitching. No sequence of exposures. No carefully measured rotation.

You press the button and you have the panorama.

That makes capturing the site almost trivial.

There is still one problem.

The panorama does not know which way it is looking.

A photograph without coordinates

A 360° image can contain the entire landscape and still have no useful relationship with astronomical coordinates.

Which pixel is north?

Where exactly is the geometric horizon?

Is the camera perfectly level?

How much roll, pitch, or yaw is present?

If I see a tree in the panorama, what is its actual azimuth? If its canopy reaches a certain height in the image, what altitude does that correspond to?

That is where PanoPose begins.

Instead of editing the panorama as a flat rectangle, PanoPose places it on the inside of a sphere. You view the landscape from the same conceptual position from which it was photographed.

Over that sphere it can draw an Alt/Az coordinate grid, calculate the positions of astronomical objects for a chosen location and time, and let you rotate the panorama until the photograph agrees with the real sky.

The job is calibration rather than image editing.

First, let gravity tell you which way is up

The first step is getting the panorama level.

Buildings make this surprisingly easy.

Corners, columns, window frames, lamp posts, utility poles and similar structures provide vertical lines. Tilt the panorama until those features agree with the vertical grid lines in PanoPose.

If you are photographing somewhere completely natural and there are no trustworthy vertical features, you can create one.

Tie a cord to a tree, hang a rock from the end, and make sure the improvised plumb line appears somewhere in the 360° photograph.

Gravity has now drawn a vertical reference into your panorama.

It is crude surveying equipment, but physics does not care that the weight is a rock.

Once the panorama is level, one major uncertainty is gone.

Then let the Sun tell you which way you are looking

This is the part that makes the workflow much easier than I initially expected.

If the Sun appears in the photograph, PanoPose can calculate where the Sun actually was when the photograph was taken.

The application reads the timestamp and GPS coordinates from the image metadata when they are available. Location and time can also be entered manually.

Given those values, PanoPose calculates the Sun's expected Alt/Az position and displays a marker at that point in the spherical view.

Then the calibration procedure is essentially:

1. Switch to Align Target mode.
2. Find the photographed Sun.
3. Drag the panorama until the photographed Sun coincides with the calculated Sun marker.

That establishes the panorama's absolute orientation.

In practice, I have found that this two-stage procedure gets remarkably close:

Gravity gives you vertical.
The Sun gives you orientation.

For most purposes, that may already be all you need.

At night, the stars become precision instruments

If you want to refine the calibration further, the night sky provides an almost ridiculous number of free reference points.

Given an observer's geographical location and the time, the expected Alt/Az coordinates of stars can be calculated very accurately.

That means the stars are effectively lots of little precision Alt/Az gauges scattered across the sky.

PanoPose includes a Planetarium mode using a bundled catalog of bright stars. Set the correct location and time and the expected star field appears above the horizon.

You can then take a nighttime photograph — even an ordinary phone photograph if the phone is sensitive enough — that includes both stars and recognizable horizon features.

Perhaps a star appears just above a roof corner.

Perhaps another sits beside a particular branch.

Perhaps one is visible through a notch in a tree canopy.

If PanoPose predicts that star in exactly the same place relative to the landscape, the calibration agrees. If not, the remaining discrepancy tells you that there is still a small orientation error.

I found that leveling against vertical structures and aligning against the Sun was already extremely good. Stars are where you go when you want to chase the remaining tiny fraction of a degree.

So the full calibration hierarchy becomes:

Gravity gives you vertical.
The Sun gives you orientation.
The stars give you precision.

The geometric horizon is not your horizon

Once a panorama is calibrated, it stops being merely a picture of the site.

It becomes a directional model of the local horizon.

Suppose Stellarium tells you that an object rises at 05:42.

That means it crosses altitude 0° at 05:42.

But perhaps there is a ridge at altitude 6° in that direction.

Or a large tree.

Or two trees with a useful gap between them.

The question you normally care about is not:

When does the object geometrically rise?

It is:

When will I actually be able to see it from here?

A calibrated panorama lets the real landscape answer that question.

This is especially useful for phenomena that happen close to the horizon: conjunctions, young or old crescent Moons, Mercury and Venus, objects in twilight, eclipses near sunrise or sunset, and photographic compositions involving celestial objects and landscape features.

Sometimes the difference between seeing an event and missing it really is one particular tree.

Comparing one horizon with another

PanoPose can also load reference panoramas.

This is useful if you already have a calibrated panorama and later photograph the same location again.

Vegetation grows. Trees lose branches. Trees fall. New trees appear in gaps that used to be open. Buildings and other structures change too.

PanoPose can place the new panorama, called the target, over an older reference panorama and compare them directly.

You can blend the two images or adjust their opacity manually, but one of the most revealing comparison modes is Blink.

In Blink mode, PanoPose automatically alternates between the target panorama and the reference panorama.

The effect is simple but surprisingly effective.

A tree that has grown several degrees higher seems to jump between the two states. A missing branch becomes immediately obvious. A tree that has fallen simply disappears and reappears as the images alternate. Small changes that are difficult to notice while looking at two static images become conspicuous when the whole horizon flips back and forth.

That makes an older calibrated panorama more than an archive. It becomes a measuring reference for the new one.

Saving the calibration with the photograph

Once a panorama has been aligned, it would be annoying if the calibration existed only inside the current PanoPose session.

PanoPose can optionally save a copy of the loaded image containing the calibration metadata.

That includes the three pose angles together with time and location information. PanoPose uses GPano metadata where appropriate and also stores its own calibration information in XMP metadata.

Open that image again later and the application can recover the pose.

In other words, you only have to teach the panorama where it is looking once.

PanoPose can also import time and GPS information from another ordinary photograph without loading that photograph as the panorama itself. That can be useful when another camera or phone has the metadata you want to use for the calibration. It also makes it easy to show the star positions at the precise time you took that night-time reference photo.

Removing the sky sounded easier than it was

For a Stellarium landscape, it is necessary to make the real photographic sky transparent so that Stellarium can draw its own sky behind the landscape.

At first this looked like a problem that ought to have a pleasantly simple solution.

Start at the top of the image.

Identify sky-like colors.

Follow connected regions.

Perhaps look at brightness or gradients.

Remove everything that looks like sky.

That works wonderfully until it doesn't.

Clouds are not blue. Sunset skies are not blue. Haze reduces boundaries. Tree branches produce thousands of tiny edges. Bright gaps appear between leaves. Buildings have reflections. Thin objects cross the sky. A heuristic that works perfectly on one panorama can remove part of a tree on the next.

After trying simpler approaches, I eventually stopped trying to turn the problem into something simpler than it really is.

PanoPose uses the open-source skyseg-ncnn program for optional sky segmentation. It runs a small trained model specifically intended to distinguish sky from non-sky regions.

PanoPose deliberately treats this as an external optional tool rather than bundling it.

At startup, the application checks whether the skyseg-ncnn executable exists in the user's PATH.

If it does, the Remove Sky option becomes available.

If it does not, nothing else changes. PanoPose works normally without sky removal.

The resulting mask is converted into transparency, including partially transparent edges around trees and other fine structures.

For a Stellarium landscape, the result is much cleaner than simply placing the original photographed sky over the simulated one.

From panorama to planetarium

Once the panorama is calibrated, PanoPose can export it as a corrected full-sphere PNG.

The orientation is baked into the pixels while preserving the original equirectangular format and dimensions.

More importantly for astronomy users, PanoPose can export a Stellarium spherical landscape ZIP.

You provide a name, author and description, and PanoPose generates both the posed panorama texture and the landscape.ini file that Stellarium expects.

The current site latitude, longitude and elevation are included automatically.

If sky removal is enabled, the exported landscape can contain transparency so Stellarium's own sky appears above the photographed horizon.

The result can then be installed in Stellarium like any other custom landscape.

That closes the loop:

Real location → 360° photograph → calibrated Alt/Az panorama → Stellarium landscape.

It is not a panorama stitcher

PanoPose is deliberately narrow in scope.

It does not convert ordinary photographs into a spherical panorama.

It does not replace Hugin.

It does not attempt automatic computer-vision registration.

It is not a complete planetarium.

And its Planetarium mode is not intended to compete with Stellarium.

Its job is the missing step between those tools:

Take an existing 2:1 spherical panorama and establish precisely how that panorama corresponds to the real world.

Once that relationship exists, the image becomes much more useful.

A note about how it was built

PanoPose was developed entirely by OpenAI Codex from my requirements, testing, and iteration, and went from concept to v1.0 in about 48 hours on my $20/mo ChatGPT Plus plan. That is not really the point of the project, but it is worth stating for completeness. This is 2026; I wanted the tool, so I had the machine write it. Developers should probably get comfortable with the tools of the present before somebody starts calling them the tools of the past.

More interesting than who typed the code is whether the resulting software solves the problem.

For me, it does.

Getting PanoPose

PanoPose is free, open source, and currently a Linux application.

The project supports Linux packaging as .deb, .rpm, and AppImage builds.

Project repository:
https://github.com/arturormk/panopose-rust

The repository also contains a guided build/install script for people who prefer to build from source.

Two external programs are relevant:

• ExifTool is used when writing calibration and metadata back into image files.
• skyseg-ncnn is optional and is needed only for automatic sky removal.

The application itself remains usable without skyseg-ncnn.

The repository contains a script that will clone the ncnn and skyseg-ncnn repositories, patch the latter to work around a version mismatch, build the tool, and install it in your system.

The short version

If you want to try PanoPose with your own observing site, the workflow is roughly:

1. Capture or stitch a full-sphere 2:1 equirectangular panorama.
2. Open it in PanoPose.
3. Let PanoPose read the image's location and timestamp, or enter them manually.
4. Level the panorama using trustworthy vertical features — or an improvised plumb line.
5. Switch to Align Target.
6. Drag the photographed Sun onto PanoPose's calculated Sun marker.
7. Optionally use stars and Planetarium mode to refine the alignment.
8. Save the calibrated metadata if you want to preserve the pose in the image.
9. Optionally remove the sky.
10. Export the result as a corrected PNG or a Stellarium landscape ZIP.

A modern 360° camera makes the first step almost trivial.

The Sun and stars provide the calibration references for free.

PanoPose handles the bit in between.

If your astronomical horizon contains more than an infinite flat ocean, that bit may be useful.