Python 月相可视化项目实战：从计算到 Web 渲染

算法逻辑上，我们主要关注 lunar_cycle 的精确天数设定，以及 get_moon_phase() 通过时间差和模运算计算月相值的过程。使用 total_seconds() 确保了计算的精度。

可视化渲染类

在绘制时，我们用 patches.Circle 绘制月亮基础形状，椭圆阴影模拟月相变化。中秋特效则通过多层光晕加五角星装饰来实现。

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 "满月"

四种图表实现详解

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

这里的关键点在于间距设置避免重叠，以及大画布确保显示完整。中秋节用红色高亮加边框装饰。

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

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

视觉设计上，深蓝背景加金色曲线营造夜空效果。fill_between 创建填充区域增强视觉效果，水平垂直参考线标注关键点。

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

当前月相图

在技术实现上，8x8 正方形画布保证月亮圆形显示，大尺寸突出视觉效果，圆角文本框显示详细信息。

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

图像 Base64 编码

要点在于内存缓冲区避免临时文件，dpi 平衡质量与大小，并释放内存防止泄漏。

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

HTML 界面生成

generate_html.py - 界面组装器

接下来我们来处理界面组装。这里实例化可视化器，生成各个图表并转换为 Base64 嵌入 HTML。

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)
    # 注意：create_annual_overview 需自行补充定义
    # annual_fig = visualizer.create_annual_overview()
    # annual_img = visualizer.fig_to_base64(annual_fig)

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

结语

代码如明月，永远照亮前行的路。希望这个项目能为你提供一个将天文计算与 Web 可视化结合的参考方案。