Consider using other sphere texturing technique to avoid strong distortion at poles

[andreasfranke1]

Describe what is missing or deficient and why it should be included or improved.

For instance, take a look at the northern pole of the moon:

This project uses another approach to avoid such problems.

If this is a simulation or planetarium "content" proposal, describe how the content should appear and how users should interact with it.

No response

If this is a "code" or "development platform" proposal, describe how developers will use the new system. Provide detailed API if possible.

No response

If applicable, provide implementation code, pseudo-code, mock-ups, diagrams, or orbital maths. Do you have any helpful tips or gotchas to watch out for?

No response

Which of the following describes your feature? (1) A feature or content improvement for our Planetarium. (2) An improvement for game/app developers that should be in our core repositories. (3) An improvement for game/app developers that should be an optional addon.

I can imagine that this should be enabled for all projects, so it should go into the core repository.

[charliewhitfield]

We're going to do something about this in v0.2. (That's in the works after near-future v0.1.2.)

Click for Claude's analysis...

The problem: three artifacts, not one

"Pinched poles" bundles three separate defects with different causes and different fixes. Keeping them apart is the whole game:

#	Artifact	Root cause	Where it lives
(1)	Sliver triangles fanning into the pole vertex (degrades normal-map shading)	UV-sphere topology — latitude rings shrink to radius 0	Mesh geometry
(2)	Texture convergence / radial starburst / smeared pole	The equirectangular projection itself — the entire top pixel row is the pole	Texture data
(3)	Blurry/aliased line at the pole and along the ±180° seam	Hardware mip/anisotropic selection breaking where UVs wrap or stretch extremely	Sampling

What the close-up shows

The south-pole starburst above is artifact (2), sharpened by (3). An equirectangular map represents the pole as its single top row of texels, stretched across the full image width. Mapping that row back onto the sphere wraps it around the pole, where the meridians converge — so each texture column becomes a radial spoke. The hard, high-contrast spokes (rather than a soft blur) are (3): the per-fragment texture footprint near the pole is extremely anisotropic, and the sampler isn't filtering along it. Artifact (1) is underneath this but isn't what you see.

Two consequences worth stating plainly:

• This is universal — every body textured from an equirect map shows it at both poles, exactly as you noted.
• Geometry and resolution can't fix it. A better mesh (cube-sphere, icosphere) or a denser sphere removes the sliver triangles (1), but the starburst (2) is a property of the equirect texture, not the mesh. The only way to remove it is to stop sampling the pole through an equirectangular parameterization — i.e. re-project the source, globally or just at the caps.

How Core renders spheroids today

Three properties of the current pipeline constrain every option:

• One shared mesh. Every body and shell uses a single Godot SphereMesh (128 × 64, from sphere_radial_segments/sphere_rings in core_settings.gd) built in _make_sphere_mesh() (resource_initializer.gd) and assigned in spheroid_model.gd. A geometry change is a one-function swap — but, per above, it doesn't touch the starburst.
• Shape is a per-instance scale; the mesh stays a unit sphere. Oblateness is Basis().scaled(Vector3(e_radius, polar_radius, e_radius)) in physical_body.gd — the mesh is never modified. Direction-based sampling stays correct under that scale (the model-space trick cloud_detail.gdshader already uses).
• The asset library is equirect-only, and that assumption is wired in. asset_preloader.gd warns on any map that isn't 2:1 equirectangular, and map_offset rotates that projection. Surfaces sample by UV — depixelation.gdshader (solid, bicubic) and cloud_detail.gdshader (clouds) — and some bodies still use a plain StandardMaterial3D.

What each class of fix does to this starburst

• Shader-only (analytic UV + textureGrad): fixes (3), so the hard spokes soften into a smooth radial smudge, and the ±180° seam goes away — but the smudge itself (2) remains. A real improvement on what's pictured, not a cure. Cheap, assets untouched.
• Stereographic polar caps: sample the cap region through an azimuthal projection that has no pole singularity, blended back into the equirect map over a high-latitude band. The starburst is replaced by clean, properly-oriented polar detail (the data is actually present in the equirect top rows — just catastrophically stretched — so re-projecting it locally recovers it). Keeps the equirect library for everything outside the caps. Targeted at exactly the visible defect.
• Cube-sphere + cubemap / octahedral / hcschuetz atlas: re-project the whole surface; (2) disappears globally. The thorough fix, and the expensive one.

The option set

Option	(1)	(2)	(3)	Keeps equirect assets?	Effort	Godot-native
Shader-only: analytic UV + textureGrad	✅	◻️ (softens only)	✅	Yes	Low–Med	shader edit
Stereographic polar caps (shader blend + small pole textures)	n/a	✅ (at poles)	✅	Yes + small per-pole textures	Med	shader + offline cap bake
Octasphere / icosphere geometry	✅	◻️	◻️	Yes	Low–Med	ArrayMesh gen
Cube-sphere + cubemap textures	✅	✅	✅	No — re-project to 6 faces	High	⭐ native Cubemap/samplerCube + built-in panorama→cubemap
hcschuetz octa/ico atlas	✅	✅	✅	No — re-project to triangle atlas	High	none (all custom)
Octahedral / equal-area cube map	✅	✅	~	No — re-project	High	partial
HEALPix	◻️	✅	◻️	No	Very High	❌ not a GPU texture format

✅ fixes · ~ partial/relocated · ◻️ doesn't fix. Note the top and third rows leave (2) empty — they make the geometry honest and tame the seam, but the starburst in the screenshot is (2), so on its own neither is the fix. HEALPix is out for body surfaces (astronomy data format, no hardware mip/aniso; even WorldWide Telescope chose octahedral TOAST over it) — relevant only if Core ever grows an all-sky background.

A sketch of the polar-cap blend (schematic, Godot spatial shader):

vec3 n = normalize(model_position);                 // object space (varying)
float lat = asin(clamp(n.y, -1.0, 1.0));
vec2 cap = n.xz / (1.0 + abs(n.y));                 // azimuthal: each pole -> origin, no singularity
vec4 equirect = texture_bicubic(albedo, UV);        // existing path, away from the poles
vec4 polar    = texture(pole_cap, cap * 0.5 + 0.5); // small per-pole, per-body texture
float t = smoothstep(LAT_BLEND_LO, LAT_BLEND_HI, abs(lat));
ALBEDO = mix(equirect, polar, t).rgb;

Difficulty, mapped to Core's architecture

Shader-only softening (assets untouched). Add object-space VERTEX as a varying to the surface shaders, compute analytic UV, sample with textureGrad. Frictions: our samplers go through a custom texture_bicubic, so the manual-gradient variant is fiddly; the seam fix must use explicit gradients (the cheap fwidth-select is unreliable on Vulkan/GL/Web — Ben Golus — so test the PWA export specifically); and Earth + the ICE types still use StandardMaterial3D, so they'd need conversion to ShaderMaterial to benefit. Low–Medium, and only softens the pictured defect.

Stereographic polar caps (the targeted fix). A surface-shader change plus a small offline tool that re-projects each source map's polar bands into two azimuthal cap textures per body. The mesh and the bulk equirect pipeline are untouched; asset_preloader gains a cap-texture channel; the StandardMaterial3D bodies still need converting to a shader. The normal map needs a cap too — and re-projecting a tangent-space normal map means recomputing the tangent frame in the cap, the same gotcha as full re-projection but over a tiny region. Minor blend-band seam at the cap boundary (negligible if both samples derive from the same source). Medium, and it directly kills what's in the screenshot while keeping the equirect library.

Full re-projection (cube-sphere / atlas). The mesh swap is an afternoon. The cost is the asset pipeline, identical in scope whichever layout we target:

1. Re-project every channel of every body (albedo, normal, roughness, emission, clouds) offline — cube-sphere wins here, since Godot ships a panorama→cubemap converter and the atlas route is fully custom.
2. Rework asset_preloader ingestion — it discovers 2:1 maps and binds them to UV; it would instead load Cubemaps sampled by direction, which also forces the StandardMaterial3D bodies to ShaderMaterial.
3. The tangent-space normal re-bake (per face/triangle), across the whole library.
4. Update the Python build tools and bake map_offset into the projection step.

High, and identical whether the target is a cubemap or the hcschuetz triangle atlas — which is why, if we go global, cube-sphere + cubemap beats the atlas: native Godot types, built-in conversion, a proven path (Sebastian Lague), no bespoke sampler to maintain. The hcschuetz icosahedral atlas only wins if we can obtain source data natively in that layout (removing its lossy re-bake).

Net

The screenshot is artifact (2), so the cheap shader path is demoted to a cosmetic softener — worth doing for the seam and the hard spokes, but it won't remove the pinch. The two real candidates are:

• Stereographic polar caps — Medium effort, keeps the entire equirect asset library, fixes the defect exactly where it appears. Best cost/benefit if we want the starburst gone without re-tooling the whole pipeline.
• Cube-sphere + cubemap — High effort, re-projects the library, fixes (1)/(2)/(3) globally and permanently. The right answer if we'd rather solve it once at the root than carry a cap special-case.

References

• Ben Golus, Distinctive Derivative Differences — atan2 seam + textureGrad, and the Vulkan/GL/Metal caveat
• hcschuetz/sphere-texturing and the companion octasphere
• Catlike Coding, Cube Sphere; Zucker & Higashi, Cube-to-sphere Projections, JCGT 2018
• Philip Rideout, Octasphere — octaspheres keep lat-long UVs; switch to the octahedral map only when poles undersample
• Sebastian Lague, Procedural Planets — cube-sphere reference
• Octahedron-based Projections (TOAST), ApJS 2019; Red Blob Games, Sphere HEALPix — why HEALPix is awkward for real-time surfaces

[charliewhitfield]

After some experimentation, I can say that there are two compounding problems:

1. Some NASA equirectangular source images have serious polar artifacts. [Edited: I initially thought most based on the first couple I looked at. But it's really only "some".]
2. Godot's equirectangular wrap onto a sphere also causes a polar artifact.

Number 1 is actually the worse problem. To prove this, I reprojected a new Moon rectangular map by code so that the Moon is sideways: poles at equator, and equator at the poles.

Here is the NASA image pole reprojected at equator (problem 1). This is pure source-image defect:

Here is the NASA image equator reprojected at the pole (problem 2). The blurry center and radial streaks from center are the Godot equirectangular wrap artifact (not to be confused with similar looking impact effects elsewhere):

Problem 1 can only be cured by repairing each image individually using separate polar images where available. I'm solving problem 2 using Godot's built-in Cubemap.

I'll probably proceed with the Cubemap implementation for several reasons:

• We need it to cure problem 2.
• Some kind of reprojection is needed anyway to repair the source image polar defects. Cubemaps put the poles dead-center in faces 3 and 4 of 6, so easy to see and repair.
• It's already built as a prototype. (That's how I discovered problem 1.)

The cubemap import will be a parallel system, so that a project's assets can have either or both cubemaps and equirectangular maps. Either is detected by the same file prefix used currently. The dynamic file reader detects which kind of resource is present at load, so you don't have to change any code or table values.

Other than the source pole defects, the new cubemap system is working perfectly on a prototype Cubemap Moon. There are no image, normal, or shadow artifacts at the seams that I can detect.

[charliewhitfield]

Polar artifact is now fixed in the new v0.2 release, which uses Godot's built-in Cubemap instead of equirectangular wrapping.

Note: There are cases like the Moon where poles are in deep shadow so no shadow-free images exists. I corrected these to some extent, but they're not perfect. You can see poles easily in the cubemaps: just look at faces 3 and 4 (upper-right and lower left) of the 3x2 PNG.

[andreasfranke1]

But still very cool, thanks!!

[charliewhitfield]

Closing this as done now.

The only thing to revisit at some point in the future is a better patch job of some polar regions in the images themselves (using cubemaps which place them in the center of a square), particularly the Moon. It can't be done by merging real images since these regions are in deep shadow. But it might be doable with real relief maps and some mildly fictional albedo.

[andreasfranke1]

Thank you!