Pyglet调用GluProject()返回重复坐标致天体标签错位求解

开发类Stellarium行星追踪器时出现的行星标签在坐标对侧重影、位置错位问题，可通过以下方案修复。

问题根因 #

• 调用gluProject做3D转2D坐标时未做可见性判断：相机背后的天体同样会被投影到屏幕平面的对侧位置，直接绘制就会出现标签跑到反方向的问题
• 矩阵栈操作逻辑错误：在单个天体绘制流程中反复切换2D/3D投影矩阵，切回3D时未恢复完整的相机旋转变换，导致矩阵状态被污染，投影坐标计算不准
• 坐标计算存在硬编码误差：球坐标转笛卡尔坐标时未将角度值转为弧度，标签y轴偏移量绑定窗口宽度写死，缩放、调整窗口大小时标签会出现漂移

基于gluProject方案的修复步骤 #

1. 修正基础坐标转换逻辑 #

首先修正球坐标转笛卡尔坐标的公式，补充角度转弧度的计算，修正天文坐标转换的映射关系：

def sphere2cart(r, ra_deg, dec_deg):
    ra = math.radians(ra_deg)
    dec = math.radians(dec_deg)
    x = r * math.cos(dec) * math.cos(ra)
    y = r * math.cos(dec) * math.sin(ra)
    z = r * math.sin(dec)
    return x, y, z

2. 分离3D天体绘制和2D标签绘制流程 #

不要在绘制单个天体时反复切换投影矩阵，改为先完成所有3D天体绘制，同步收集可见天体的屏幕坐标，最后统一切换到2D模式批量绘制标签，避免矩阵栈污染。

3. 增加可见性判断过滤无效标签 #

gluProject返回的第三个值是点的裁剪空间深度，取值范围在0~1之间时才代表点在当前视锥范围内，超出范围直接跳过标签绘制，彻底过滤相机背后的天体投影。

修复后的核心实现代码 #

修改planetary_locations.py中的PlanetLocator类：

class PlanetLocator:
    def __init__(self, logger, window):
        self.logger = logger
        self.window = window

        self.ts = load.timescale()
        self.t = self.ts.now()
        self.planets = load('de421.bsp')

        self.sun = self.planets['sun']
        self.earth = self.planets['earth']
        self.moon = self.planets['moon']

        self.mercury = self.planets['mercury']
        self.venus = self.planets['venus']
        self.mars = self.planets['mars']
        self.jupiter = self.planets['Jupiter barycenter']
        self.saturn = self.planets['saturn barycenter']
        self.uranus = self.planets['uranus barycenter']
        self.neptune = self.planets['neptune barycenter']
        
        self.zoom = 1
        self.camrot = [0, 0]
        self.labels = {}
        self.visible_labels = [] # 存储当前帧需要渲染的标签及坐标

    def _draw_planet(self, planet, name, color, size):
        self.t = self.ts.now()
        observation = self.earth.at(self.t).observe(planet).apparent().radec()
        x, y, z = sphere2cart(400, observation[0]._degrees, observation[1]._degrees)
        
        glPushMatrix()
        glTranslatef(x, y, z)
        glColor3f(*color)
        gluSphere(gluNewQuadric(), size/10, 10, 10)
        
        # 计算屏幕投影坐标
        win_x, win_y, win_z = gluProject(0, 0, 0)
        # 仅保留视锥范围内、视口内的天体标签
        if 0 <= win_z <= 1 and 0 <= win_x <= self.window.width and 0 <= win_y <= self.window.height:
            # 固定20像素偏移，不绑定窗口尺寸
            self.visible_labels.append( (name, win_x, win_y + 20) )
        glPopMatrix()
        
    def draw(self):
        self.visible_labels.clear()
        # 第一步：绘制所有3D天体，收集标签坐标
        self._draw_planet(self.sun, 'Sun', (1, 1, 0), 80)
        self._draw_planet(self.moon, 'Moon', (1, 1, 1), 80)
        self._draw_planet(self.mercury, 'Mercury', (1, 0, 0), 30)
        self._draw_planet(self.venus, 'Venus', (1, 0, 0), 40)
        self._draw_planet(self.mars, 'Mars', (1, 0, 0), 35)
        self._draw_planet(self.jupiter, 'Jupiter', (1, 0, 0), 40)
        self._draw_planet(self.saturn, 'Saturn', (1, 0, 0), 38)
        self._draw_planet(self.uranus, 'Uranus', (0, 0, 1), 36)
        self._draw_planet(self.neptune, 'Neptune', (0, 0, 1), 36)

        # 第二步：统一切换2D模式绘制标签
        glMatrixMode(GL_PROJECTION)
        glPushMatrix()
        glLoadIdentity()
        gluOrtho2D(0, self.window.width, 0, self.window.height)
        glMatrixMode(GL_MODELVIEW)
        glPushMatrix()
        glLoadIdentity()

        for name, x, y in self.visible_labels:
            if name not in self.labels:
                self.labels[name] = pyglet.text.Label(
                    text=name, 
                    anchor_x='center', 
                    anchor_y='center', 
                    font_size=max(10, 20 - self.zoom/10), 
                    color=(255, 255, 255, 255)
                )
            self.labels[name].x = x
            self.labels[name].y = y
            self.labels[name].draw()

        # 恢复3D矩阵状态
        glMatrixMode(GL_MODELVIEW)
        glPopMatrix()
        glMatrixMode(GL_PROJECTION)
        glPopMatrix()
        glMatrixMode(GL_MODELVIEW)

    def set_zoom(self, zoom):
        self.zoom = zoom

其他替代实现方案 #

如果不想依赖OpenGL投影计算，也可以采用纯天文坐标映射的方案：

• 直接通过Skyfield拿到天体相对于观测点的高度角、方位角，和当前相机的朝向角度做差，直接将角度差映射为屏幕2D坐标，完全绕开3D投影计算，逻辑更可控
• 引入标签碰撞检测：按天体视星等排序，亮天体标签优先渲染，和已渲染标签重叠的暗天体标签自动隐藏，和Stellarium的标签渲染逻辑一致
• 用Pyglet的Batch批量管理标签渲染，减少逐标签draw call，提升大分辨率下的渲染帧率

内容的提问来源于stack exchange，提问作者user15922830