3D Projection

Turn flat astro images into stereo pairs, wiggle animations, red/cyan anaglyphs, interactive HTML 3D, pseudo-surface point clouds, and top-down galaxy views — all from a single sub.

1. The six output modes

Pick one from the top Output dropdown:

The three stereo modes (Parallel, Cross-eye, Wiggle) and the Anaglyph all share the same underlying stereo-pair generation — they just differ in how the pair is composited for display. Interactive 3D and Galaxy Polar View generate their outputs via different pipelines.

2. The four planet types

The planet type and the output mode combine freely: for example, "Saturn + Interactive 3D" gives you a Plotly sphere with real ring geometry you can orbit, while "Pseudo surface + Wiggle" gives you a swaying heightmap of your lunar close-up.

3. Common workflow

1. Open the dialog on an active image.
2. Pick Output and Planet type from the two top dropdowns.
3. Set Strength (°) — the stereo parallax angle. 6° is the sweet spot for most planets; 2-3° for subtle depth, 10-15° for exaggerated. Only matters for the stereo and anaglyph modes.
4. Review the detected disk if the "Review / adjust detected disk" checkbox is ticked (default). The disk-adjust dialog opens with an automatic estimate — nudge or redraw as needed.
5. Click Generate. The preview window opens with your result.
6. From the preview: Save Still, Save Wiggle (if wiggle mode is active), or Push to New Document to drop the result into a SASpro doc for further processing.

4. The disk-adjust dialog

When "Review / adjust detected disk" is enabled, Generate pauses to let you confirm the disk location. The dialog shows the image with a green circle (and, for Saturn / galaxy / planet types, an ellipse overlay with PA and tilt handles).

5. Backgrounds and parallax

The background behind the planet can be configured three ways:

• Starfield (checkbox) — a synthetic random starfield, with density and seed controls. Default on. The starfield is screen-locked (no parallax) by default, which looks right for most planetary stereo.
• Background image (checkbox + Choose… button) — load any image (nebula field, your Milky Way shot, a star cluster). It's resized to fit the ROI and composited behind the planet.
• Both — background image + starfield painted on top.

The Background depth slider controls how much the background participates in the stereo parallax, as a percentage of the planet's parallax:

• 0% — screen-locked, no parallax. Stars appear to float at the screen plane.
• 25% (default for most workflows) — background sits visually behind the planet. Recommended for a clean depth cue without forcing the eye to fuse the stars themselves.
• 100% — background at the same depth as the planet (unnatural for astro-stereo, since stars are much farther than planets).
• Negative values — background in front of the planet. Mostly for creative/weird effects.

6. Workflow recipes

7. Interactive 3D exports — details

The HTML export has three distinct forms depending on planet type:

• Sphere (Normal, Saturn) — a Plotly Mesh3d sphere with the equirectangular texture derived from your disk. 480 × 960 latitude/longitude resolution by default. The visible-hemisphere pixels are mapped to the near side; the back hemisphere is painted black (since you only have one view of the planet). Camera starts at (0, 0, 2.2) looking at origin.
• Saturn rings (if enabled) — a second Mesh3d built as a polar grid (180 radial × 720 angular by default), textured from the ROI by sampling along the ellipse at each (radius, angle) point. The rings are 3D-tilted around the X axis by inclination = arccos(tilt), rotated around Z by the PA. Ring pixels behind the sphere are painted black so the planet correctly occludes them.
• Pseudo-surface point cloud (Pseudo surface) — a Plotly Scatter3d with up to 900000 points (default 250000), each positioned at (x, y, z=height) where height is derived from luminance or saturation (or both in Dual mode). The point color follows the "3D Color Mode" setting: Brightness (actual pixel RGB), Depth (colormap by height), or Dual (overlaid). Downsampling honors a target vertex count so the file stays browser-friendly.

8. Technical details

The projection math, the ring geometry, the pseudo-surface heightmap, the galaxy deprojection, and the anaglyph composition.

8.1 Sphere reprojection (the core of planet stereo)

The planet in your image is a 2D disk — the orthographic shadow of a sphere. To make stereo, we first unproject each disk pixel back onto the sphere, then rotate the sphere by ±θ around the vertical axis, then project back to pixels for the left and right views.

Setup: center coordinates at the disk center, scale so x and y lie in [-1, 1] at the limb (so r = 1 is the disk radius). The front-hemisphere height is:

Rotate the sphere around the vertical (Y) axis by angle θ (positive for left eye, negative for right):

Project back to pixel coordinates:

where (c_x, c_y) is the disk center in the image and r is the disk radius in pixels. The result is implemented as cv2.remap with Lanczos4 interpolation; pixels outside the disk get borderValue=0. This correctly curves the sphere so that limb features move more than central features — the natural stereo effect of looking at a 3D ball from two angles.

8.2 Ring geometry (Saturn)

Rings are modeled as a tilted elliptical annulus in the image plane. For a position (x, y) relative to the disk center, rotate into the ring's own frame by -PA to get (x_r, y_r). The outer ellipse condition is:

with a_o = (outer factor) · r and b_o = a_o · tilt. The inner ellipse is the same with a_i, b_i. The ring annulus is:

The tilt parameter (b/a) encodes the viewing inclination of the ring plane:

so tilt = 1 is face-on (circle) and tilt → 0 is edge-on. For true 3D geometry in the Interactive HTML export, this is inverted:

to recover the actual ring-plane inclination from the apparent axis ratio in your image.

8.3 Ring front/back split and occlusion

The ring plane crosses the planet body: part of the ring sits in front of the body (closer to you), part sits behind. To composite them correctly, we split the ring annulus into two halves using the signed distance along the minor-axis normal:

where (n_x, n_y) = (cos(PA + 90°), sin(PA + 90°)) is the unit vector along the ring plane's minor axis in the image. During compositing, back-half ring pixels are drawn first (so the planet body overpaints them), then the planet body is drawn, then front-half ring pixels (so they sit on top of the body). This creates the familiar "ring passing in front of Saturn" visual effect.

8.4 Ring stereo via yaw warp

Rings are flat 2D structures — the sphere-reprojection math from §8.1 doesn't apply. Instead, we use a simpler yaw warp for stereo disparity on the ring pixels:

which horizontally foreshortens the ring positions around the rotation center. This produces parallax that scales with distance from the center (so ring tips move more than ring bases), matching how a rotating ring plane would appear to shift between two eye positions.

8.5 Pseudo-surface heightmap and disparity warp

For the Pseudo surface planet type, image brightness is treated as 3D height. The pipeline, in order:

1. Compute luminance as the Rec.709 weighted sum: Y = 0.299·R + 0.587·G + 0.114·B.

2. Center around the median so background is near zero height:

3. Apply gamma shaping (preserving sign) to control contrast:

Default γ = 1.15 emphasizes bright peaks slightly; γ < 1 broadens depth; γ > 1 sharpens it.

4. Normalize by MAD (Median Absolute Deviation) so bright stars don't dominate:

The gain divisor 6 gives a visually comfortable amplitude without stars exploding into huge disparity spikes. The result is clipped to [-1, 1].

5. Compute per-pixel disparity from the stereo strength θ:

and clamp Δ_max to at most 0.35 · min(H, W) so disparity never gets absurd on large frames.

6. Warp each pixel horizontally by ±½Δ for the left/right views:

Bilinear remap (INTER_LINEAR, deliberately not Lanczos) because Lanczos ringing on sharp stars would produce visible halos in the output.

8.6 Anaglyph composition

The red/cyan anaglyph composite uses luminance from each eye to drive one color channel:

Luminance (rather than per-color-channel copying) is used because it's more robust across different source color balances — a stereo pair derived from a monochrome luminance capture produces the same anaglyph as one from a well-balanced RGB. The red lens of the glasses blocks the cyan (G+B) channels, delivering only the left-eye luminance to the left eye; the cyan lens blocks red, delivering only the right-eye luminance to the right eye. Your visual system fuses the two monochrome views into depth.

8.7 Galaxy top-down deprojection

The Galaxy Polar View reverses the perspective-and-tilt projection that turned the real face-on galactic disk into the elliptical patch you see in your image. Given an output grid (u, v) ∈ [-1, 1] in the deprojected disk plane:

1. Apply the inclination foreshortening (y compressed by the tilt factor):

2. Rotate by the galaxy's position angle α (negative, to undo the on-sky rotation):

3. Scale by the galaxy's apparent radius r in pixels and translate back to image coordinates:

where X and Y are the rotated-and-tilted plane coordinates. The output image is sampled by cv2.remap at these back-projected coordinates. Pixels where (u, v) falls outside the galaxy's apparent ellipse remain black.

The result: a galaxy that looked like a thin needle (edge-on) can be shown as a face-on disk, revealing spiral structure that was foreshortened out of visibility in the original frame. This is purely a geometric reprojection — it doesn't invent any new information, so features that were hidden behind the disk from your line of sight stay hidden. But features that were just squashed by projection recover their original on-disk shape.

8.8 Equirectangular texture for Interactive 3D sphere

For the Plotly sphere export, the planet disk is first converted to an equirectangular (latitude/longitude) texture that can be mapped onto a sphere mesh. For each (lat φ, lon λ) in the texture:

Orthographically project onto the disk:

and sample the disk pixel at (u, v). Points on the back hemisphere (Z < 0) stay black because you have no information about what's behind. The resulting equirectangular image is then wrapped onto a Plotly Mesh3d sphere, giving you a rotatable 3D planet where the near-side pixels are your real data and the far side is dark.

8.9 Automatic disk detection (WinJUPOS-style)

The disk-detection pipeline (used both for automatic ROI centering and in the Auto-detect button of the adjust dialog):

1. Percentile stretch the green channel to uint8 (1st-99.5th percentile).
2. Gaussian blur with σ=1.2 to reduce noise.
3. Otsu's method to find the optimal threshold between background and planet.
4. Morphological open+close with a 7×7 ellipse kernel to clean the mask.
5. Connected-components; pick the largest component with area ≥ 200 pixels.
6. Centroid gives (c_x, c_y). Equivalent radius from area:
   r = \sqrt{\frac{A_{\mathrm{disk}}}{\pi}}
7. For ellipse modes (Saturn, Galaxy, Planet-axis): extract the component's contour and fit an ellipse with cv2.fitEllipse, recovering the major/minor axes, orientation angle, and refined center all in one step. The ellipse PA and the b/a tilt both come out of this fit directly.

This matches the WinJUPOS approach of fitting a limb ellipse rather than assuming a perfect circle — valuable for Jupiter and Saturn, which are visibly oblate, and essential for galaxies, which are inclined.

8.10 Background parallax math

The background depth setting determines how much the background participates in stereo:

where p_depth is the depth percentage from the slider (0 to 1 for 0% to 100%). The background is then shifted by ±½Δ_bg for the left/right views. At p_depth = 0 the shift is zero and both views see the same background — the stars appear "screen locked". At p_depth = 1 the background shifts the same as the planet — stars appear "at planet depth". The 25% default puts stars visually further than the planet, which is the natural astronomical ordering.