Python 月相可视化系统：天文计算与 Web 界面实现

核心算法说明：

• lunar_cycle 设定为精确的朔望月天数。
• get_moon_phase() 利用模运算处理周期性，确保数值在 0-2 之间归一化。
• 使用 total_seconds() 保证时间差计算的浮点精度。

可视化渲染类

class WebMoonVisualizer:
    """Web 版月相可视化器"""
    def __init__(self):
        self.calculator = MoonPhaseCalculator()

    def draw_moon(self, ax, phase, size=1.0, position=(0, 0), is_mid_autumn=False):
        """绘制月亮形状"""
        x, y = position
        # 绘制月亮基础圆形
        circle = patches.Circle((x, y), size, facecolor='lightyellow', edgecolor='gold', linewidth=2)
        ax.add_patch(circle)
        
        # 根据月相绘制阴影部分
        if phase < 0.95:
            shadow_width = size * 2 * (1 - phase)
            if shadow_width > 0.1:
                shadow = patches.Ellipse((x + size * 0.1, y), shadow_width, size * 2, facecolor='darkgray', alpha=0.6)
                ax.add_patch(shadow)
        
        # 中秋节特效
        if is_mid_autumn:
            for i in range(4):
                halo = patches.Circle((x, y), size * (1.3 + i * 0.15), facecolor='orange', alpha=0.12 - i * 0.03, edgecolor='none')
                ax.add_patch(halo)
            
            # 添加星星装饰
            star_positions = [
                (x - size * 2.0, y + size * 1.0),
                (x + size * 2.0, y + size * 1.0),
                (x - size * 1.8, y - size * 1.3),
                (x + size * 1.8, y - size * 1.3),
            ]
            for sx, sy in star_positions:
                star = patches.RegularPolygon((sx, sy), 5, radius=size * 0.12, facecolor='gold', alpha=0.9)
                ax.add_patch(star)

    def get_phase_name(self, phase):
        """获取月相名称"""
        if phase < 0.1:
            return "新月"
        elif phase < 0.35:
            return "蛾眉月"
        elif phase < 0.65:
            return "上弦月"
        elif phase < 0.9:
            return "盈凸月"
        else:
            return "满月"

绘制要点：

• 使用 patches.Circle 构建基础形态。
• 阴影宽度公式 size * 2 * (1 - phase) 模拟光照遮挡效果。
• 中秋模式下增加多层光晕和五角星，提升节日氛围。

四种图表实现详解

时间轴图表 - 连续月相展示

此图表用于展示一段时间内的月相连续变化。关键在于调整 X 轴间距，避免月亮图标重叠。

def create_timeline_chart(self, center_date=None, days=30):
    """创建时间轴图表（修复重叠问题）"""
    if center_date is None:
        center_date = datetime(2025, 10, 6)
    start_date = center_date - timedelta(days=15)
    fig, ax = plt.subplots(figsize=(24, 12))
    
    for i in range(days):
        current_date = start_date + timedelta(days=i)
        phase = self.calculator.get_moon_phase(current_date)
        is_mid_autumn = self.calculator.is_mid_autumn_festival(current_date)
        
        x_pos = i * 3.5  # 增大间距避免重叠
        y_pos = 0
        self.draw_moon(ax, phase, size=1.0, position=(x_pos, y_pos), is_mid_autumn=is_mid_autumn)
        
        # 添加日期标签
        ax.text(x_pos, -3.0, current_date.strftime('%m-%d'), ha='center', va='top', fontsize=11, fontweight='bold')
        
        # 中秋节特殊标记
        if is_mid_autumn:
            ax.text(x_pos, 3.5, '2025 年中秋节', ha='center', va='bottom', fontsize=14, fontweight='bold', color='red')

实现关键：

• x_pos = i * 3.5 确保每个日期的月亮有足够空间。
• 画布尺寸设为 24x12，防止长序列被压缩。
• 中秋节位置用红色高亮文本标注。

月相曲线图 - 数学规律可视化

通过折线图展示月相值的正弦波趋势，适合分析周期性规律。

def create_phase_chart(self):
    """创建月相图表"""
    fig, ax = plt.subplots(figsize=(12, 8))
    ax.set_facecolor('#001133')
    today = datetime(2025, 10, 6)
    dates_range = [today + timedelta(days=i - 15) for i in range(31)]
    phase_values = [self.calculator.get_moon_phase(d) for d in dates_range]
    
    ax.plot(range(31), phase_values, 'gold', linewidth=4, marker='o', markersize=6, markerfacecolor='yellow', markeredgecolor='orange')
    ax.fill_between(range(31), phase_values, alpha=0.3, color='gold')
    
    # 重要标记线
    ax.axhline(y=1.0, color='red', linestyle='--', alpha=0.8, linewidth=2, label='Full Moon')
    ax.axhline(y=0.0, color='silver', linestyle='--', alpha=0.8, linewidth=2, label='New Moon')
    ax.axvline(x=15, color='lime', linestyle=':', alpha=0.8, linewidth=3, label='Mid-Autumn Festival')
    
    mid_autumn_phase = self.calculator.get_moon_phase(today)
    ax.plot(15, mid_autumn_phase, 'r*', markersize=15, label=f'Festival Phase({mid_autumn_phase:.2f})')

设计要点：

• 深蓝背景配合金色曲线，营造夜空视觉效果。
• fill_between 填充区域增强曲线的立体感。
• 水平/垂直参考线清晰标注了满月和节日节点。

当前月相图

单张特写图，突出当前时刻的月亮状态及详细信息。

def create_current_moon(self):
    """创建当前月相图"""
    fig, ax = plt.subplots(figsize=(8, 8))
    ax.set_facecolor('#001133')
    today = datetime(2025, 10, 6)
    phase_today = self.calculator.get_moon_phase(today)
    is_today_mid_autumn = self.calculator.is_mid_autumn_festival(today)
    
    self.draw_moon(ax, phase_today, size=3.0, position=(0, 0), is_mid_autumn=is_today_mid_autumn)
    ax.set_xlim(-6, 6)
    ax.set_ylim(-6, 6)
    ax.set_aspect('equal')
    ax.axis('off')
    
    phase_name = self.get_phase_name(phase_today)
    title = f'2025 Mid-Autumn Festival Moon Phase - {phase_name}\n{today.strftime("%Y-%m-%d")}\nPhase Value: {phase_today:.3f}'
    if is_today_mid_autumn:
        title += '\nHappy Mid-Autumn Festival!'
    
    ax.text(0, -5, title, ha='center', va='top', fontsize=14, color='white', fontweight='bold', bbox=dict(boxstyle="round,pad=0.8", facecolor="darkblue", alpha=0.8))

技术特点：

• 正方形画布保证月亮比例不失真。
• size=3.0 放大主体，便于观察细节。
• 圆角文本框承载元数据，信息层级分明。

图像 Base64 编码

为了将图表嵌入 HTML，需要将 Matplotlib 对象转换为 Base64 字符串。

def fig_to_base64(self, fig):
    """将 matplotlib 图形转换为 base64 字符串"""
    buffer = io.BytesIO()
    fig.savefig(buffer, format='png', facecolor=fig.get_facecolor(), bbox_inches='tight', dpi=150)
    buffer.seek(0)
    image_png = buffer.getvalue()
    buffer.close()
    plt.close(fig)  # 释放内存防止泄漏
    graphic = base64.b64encode(image_png)
    return graphic.decode('utf-8')

要点：

• 使用内存缓冲区 (BytesIO) 避免生成临时文件。
• dpi=150 平衡图片质量与传输大小。
• plt.close(fig) 至关重要，防止长时间运行导致内存溢出。

HTML 界面生成

generate_html.py - 界面组装器

主脚本负责调用上述模块，生成最终的静态页面。

from moon_calculator import WebMoonVisualizer
from datetime import datetime

def generate_html():
    visualizer = WebMoonVisualizer()
    # 生成图表
    mid_autumn_date = datetime(2025, 10, 6)
    timeline_fig = visualizer.create_timeline_chart(mid_autumn_date, days=30)
    timeline_img = visualizer.fig_to_base64(timeline_fig)
    
    phase_fig = visualizer.create_phase_chart()
    phase_img = visualizer.fig_to_base64(phase_fig)
    
    current_fig = visualizer.create_current_moon()
    current_img = visualizer.fig_to_base64(current_fig)
    
    # 获取月相信息
    moon_info = visualizer.get_moon_info()
    # 注意：create_annual_overview 需自行补充实现逻辑
    # annual_fig = visualizer.create_annual_overview()
    # annual_img = visualizer.fig_to_base64(annual_fig)
    
    # 此处省略 HTML 模板拼接代码，实际项目中可结合 Jinja2 或字符串格式化
    with open('moon_phase_report.html', 'w', encoding='utf-8') as f:
        f.write(f'<html><body>...{timeline_img}...</body></html>')

CSS3 特效设计

前端样式决定了页面的观感，利用动画增加交互性。

/* 星空背景动画 */
@keyframes twinkle {
    0%, 100% { opacity: 0.3; }
    50% { opacity: 1; }
}

/* 流星效果 */
@keyframes shooting {
    0% { transform: rotate(-45deg) translateX(0) translateY(0); opacity: 1; }
    100% { transform: rotate(-45deg) translateX(-800px) translateY(800px); opacity: 0; }
}

/* 月亮背景浮动 */
@keyframes float {
    0%, 100% { transform: translateY(0px); }
    50% { transform: translateY(-15px); }
}

/* 渐变文字效果 */
.highlight {
    background: linear-gradient(45deg, #ff6b35, #f7931e, #ffd700);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    animation: gradient-shift 3s ease infinite;
}

JavaScript 交互特效

动态生成 DOM 元素，实现随机星星和流星效果。

// 创建 120 颗星星
function createStars() {
    const starsContainer = document.getElementById('stars');
    const numberOfStars = 120;
    for (let i = 0; i < numberOfStars; i++) {
        const star = document.createElement('div');
        star.className = 'star';
        star.style.left = Math.random() * 100 + '%';
        star.style.top = Math.random() * 100 + '%';
        const size = Math.random() * 3 + 1;
        star.style.width = size + 'px';
        star.style.height = size + 'px';
        star.style.animationDelay = Math.random() * 3 + 's';
        starsContainer.appendChild(star);
    }
}

// 流星效果
function createShootingStar() {
    const shootingStar = document.createElement('div');
    shootingStar.className = 'shooting-star';
    const startX = Math.random() * window.innerWidth;
    const startY = Math.random() * (window.innerHeight * 0.5);
    shootingStar.style.left = startX + 'px';
    shootingStar.style.top = startY + 'px';
    shootingStar.style.animation = 'shooting 1.5s linear forwards';
    document.body.appendChild(shootingStar);
    setTimeout(() => {
        shootingStar.remove();
    }, 1500);
}

特效实现：

• 随机分布的闪烁星星增加背景层次感。
• 流星从屏幕边缘斜向划过，自动清理 DOM 节点防止内存堆积。
• 动画延迟随机化，避免视觉单调。

结语

本项目展示了如何利用 Python 进行科学计算与 Web 可视化的结合。通过模块化设计，核心算法与前端展示解耦，既保证了数据的准确性，又提供了良好的用户体验。在实际应用中，可根据需求扩展更多天文参数或接入实时 API。