Python 月相可视化系统：从天文计算到 Web 界面生成

核心算法说明：

• lunar_cycle 设定为精确的朔望月天数，保证长期计算的准确性。
• get_moon_phase() 利用模运算处理周期性，确保相位值始终在合理范围内。
• 使用 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) 能够直观反映光照比例。
• 中秋模式下增加多层光晕和五角星，提升节日氛围。

四种图表实现详解

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

为了清晰展示一段时间内的月相变化，我们需要避免图形重叠。

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))

技术特点：

• 8x8 正方形画布保证月亮显示为正圆，不会变形。
• size=3.0 放大尺寸突出视觉效果。
• 圆角文本框包裹详细信息，布局整洁。

图像 Base64 编码

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

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')

要点：

• 使用内存缓冲区避免生成临时文件，提高效率。
• 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)
    
    annual_fig = visualizer.create_annual_overview()
    annual_img = visualizer.fig_to_base64(annual_fig)
    
    moon_info = visualizer.get_moon_info()
    # ... 后续 HTML 模板拼接逻辑 ...

CSS3 特效设计

静态图表之外，CSS 动画能显著提升交互体验。

/* 星空背景动画 */
@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 交互特效

前端脚本负责动态生成背景和流星效果。

// 创建 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);
}

特效实现：

• 随机分布 120 颗星星，每颗闪烁节奏不同，避免单调。
• 流星从屏幕右侧斜向划过，结束后自动移除 DOM 元素，防止内存泄漏。
• 整体交互流畅，无需刷新页面即可体验动态效果。