@reftrixmcp/mcp-server 0.1.7

package/src/services/motion/analyzers/frame-diff.analyzer.ts

@@ -0,0 +1,372 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * FrameDiffAnalyzer
+ *
+ * Pixelmatchを使用したフレーム差分検出モジュール
+ *
+ * 機能:
+ * - 2つのフレーム間のピクセル差分検出
+ * - 変化率 (changeRatio) の計算 (0-1)
+ * - 差分領域 (BoundingBox) の抽出
+ * - 差分画像の生成
+ *
+ * 仕様: docs/specs/frame-image-analysis-spec.md
+ *
+ * @module services/motion/analyzers/frame-diff.analyzer
+ */
+
+import * as fs from "node:fs";
+import pixelmatch from "pixelmatch";
+import sharp from "sharp";
+import { logger, isDevelopment } from "../../../utils/logger";
+
+// =====================================================
+// 型定義
+// =====================================================
+
+/**
+ * バウンディングボックス
+ */
+export interface BoundingBox {
+  /** 左上X座標 */
+  x: number;
+  /** 左上Y座標 */
+  y: number;
+  /** 幅 */
+  width: number;
+  /** 高さ */
+  height: number;
+}
+
+/**
+ * フレーム差分検出オプション
+ */
+export interface FrameDiffOptions {
+  /** ピクセル差分閾値 (0-1) デフォルト: 0.1 */
+  threshold?: number;
+  /** 差分画像を含めるか デフォルト: false */
+  includeDiffImage?: boolean;
+  /** アンチエイリアシングを考慮するか デフォルト: true */
+  includeAA?: boolean;
+}
+
+/**
+ * フレーム差分検出結果
+ */
+export interface FrameDiffResult {
+  /** 変化率 (0-1) */
+  changeRatio: number;
+  /** 差分ピクセル数 */
+  diffPixelCount: number;
+  /** 総ピクセル数 */
+  totalPixelCount: number;
+  /** 差分領域のバウンディングボックス配列 */
+  diffRegions: BoundingBox[];
+  /** 差分画像バッファ (オプション) */
+  diffImageBuffer?: Buffer;
+}
+
+/**
+ * デフォルトオプション
+ */
+const DEFAULT_OPTIONS: Required<FrameDiffOptions> = {
+  threshold: 0.1,
+  includeDiffImage: false,
+  includeAA: true,
+};
+
+// =====================================================
+// エラークラス
+// =====================================================
+
+/**
+ * フレーム差分解析エラー
+ */
+export class FrameDiffError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FrameDiffError";
+  }
+}
+
+// =====================================================
+// FrameDiffAnalyzer クラス
+// =====================================================
+
+/**
+ * Pixelmatchを使用したフレーム差分検出クラス
+ */
+export class FrameDiffAnalyzer {
+  private readonly options: Required<FrameDiffOptions>;
+
+  /**
+   * コンストラクタ
+   * @param options - 差分検出オプション
+   */
+  constructor(options: FrameDiffOptions = {}) {
+    this.options = {
+      threshold: options.threshold ?? DEFAULT_OPTIONS.threshold,
+      includeDiffImage: options.includeDiffImage ?? DEFAULT_OPTIONS.includeDiffImage,
+      includeAA: options.includeAA ?? DEFAULT_OPTIONS.includeAA,
+    };
+
+    if (isDevelopment()) {
+      logger.debug("[FrameDiffAnalyzer] Initialized", {
+        threshold: this.options.threshold,
+        includeDiffImage: this.options.includeDiffImage,
+      });
+    }
+  }
+
+  /**
+   * 2つのフレーム間の差分を解析
+   *
+   * @param frame1 - 比較元フレーム (Buffer または ファイルパス)
+   * @param frame2 - 比較先フレーム (Buffer または ファイルパス)
+   * @param options - 解析オプション (コンストラクタオプションを上書き)
+   * @returns フレーム差分結果
+   * @throws FrameDiffError
+   */
+  async analyze(
+    frame1: Buffer | string,
+    frame2: Buffer | string,
+    options?: FrameDiffOptions
+  ): Promise<FrameDiffResult> {
+    const opts = {
+      threshold: options?.threshold ?? this.options.threshold,
+      includeDiffImage: options?.includeDiffImage ?? this.options.includeDiffImage,
+      includeAA: options?.includeAA ?? this.options.includeAA,
+    };
+
+    if (isDevelopment()) {
+      logger.debug("[FrameDiffAnalyzer] analyze called", { threshold: opts.threshold });
+    }
+
+    // 入力をBufferに変換
+    const buffer1 = await this.toBuffer(frame1);
+    const buffer2 = await this.toBuffer(frame2);
+
+    // 画像データを取得（RGBA形式に統一）
+    const [img1Data, img2Data] = await Promise.all([
+      this.getImageData(buffer1),
+      this.getImageData(buffer2),
+    ]);
+
+    // サイズチェック
+    if (img1Data.width !== img2Data.width || img1Data.height !== img2Data.height) {
+      throw new FrameDiffError(
+        `Image dimensions do not match: ${img1Data.width}x${img1Data.height} vs ${img2Data.width}x${img2Data.height}`
+      );
+    }
+
+    const { width, height } = img1Data;
+    const totalPixelCount = width * height;
+
+    // 差分画像バッファを準備
+    const diffBuffer = Buffer.alloc(width * height * 4);
+
+    // Pixelmatchで差分検出
+    const diffPixelCount = pixelmatch(img1Data.data, img2Data.data, diffBuffer, width, height, {
+      threshold: opts.threshold,
+      includeAA: opts.includeAA,
+    });
+
+    // 変化率を計算
+    const changeRatio = this.calculateChangeRatio(diffPixelCount, totalPixelCount);
+
+    // 差分領域を抽出（差分がない場合は空配列）
+    const diffRegions =
+      diffPixelCount === 0
+        ? []
+        : this.extractDiffRegionsFromBuffer(diffBuffer, width, height, diffPixelCount);
+
+    // 結果を構築
+    const result: FrameDiffResult = {
+      changeRatio,
+      diffPixelCount,
+      totalPixelCount,
+      diffRegions,
+    };
+
+    // 差分画像を含める場合
+    if (opts.includeDiffImage) {
+      result.diffImageBuffer = await this.bufferToPng(diffBuffer, width, height);
+    }
+
+    if (isDevelopment()) {
+      logger.debug("[FrameDiffAnalyzer] analyze completed", {
+        changeRatio,
+        diffPixelCount,
+        totalPixelCount,
+        regionsCount: diffRegions.length,
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * 変化率を計算
+   *
+   * @param diffPixels - 差分ピクセル数
+   * @param totalPixels - 総ピクセル数
+   * @returns 変化率 (0-1)
+   */
+  calculateChangeRatio(diffPixels: number, totalPixels: number): number {
+    if (totalPixels === 0) {
+      return 0;
+    }
+    return diffPixels / totalPixels;
+  }
+
+  /**
+   * 差分画像を生成
+   *
+   * @param frame1 - 比較元フレーム
+   * @param frame2 - 比較先フレーム
+   * @param outputPath - 出力ファイルパス (オプション)
+   * @returns 差分画像バッファ
+   */
+  async createDiffImage(
+    frame1: Buffer | string,
+    frame2: Buffer | string,
+    outputPath?: string
+  ): Promise<Buffer> {
+    const result = await this.analyze(frame1, frame2, { includeDiffImage: true });
+
+    if (!result.diffImageBuffer) {
+      throw new FrameDiffError("Failed to generate diff image");
+    }
+
+    if (outputPath) {
+      fs.writeFileSync(outputPath, result.diffImageBuffer);
+      if (isDevelopment()) {
+        logger.debug("[FrameDiffAnalyzer] Diff image saved", { outputPath });
+      }
+    }
+
+    return result.diffImageBuffer;
+  }
+
+  // =====================================================
+  // プライベートメソッド
+  // =====================================================
+
+  /**
+   * 入力をBufferに変換
+   */
+  private async toBuffer(input: Buffer | string): Promise<Buffer> {
+    if (Buffer.isBuffer(input)) {
+      if (input.length === 0) {
+        throw new FrameDiffError("Empty buffer provided");
+      }
+      return input;
+    }
+
+    // ファイルパスの場合
+    if (!fs.existsSync(input)) {
+      throw new FrameDiffError(`File not found: ${input}`);
+    }
+
+    return fs.promises.readFile(input);
+  }
+
+  /**
+   * 画像データをRGBA形式で取得
+   */
+  private async getImageData(
+    buffer: Buffer
+  ): Promise<{ data: Buffer; width: number; height: number }> {
+    try {
+      const result = await sharp(buffer)
+        .ensureAlpha() // アルファチャンネルを確保
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+
+      return {
+        data: result.data,
+        width: result.info.width,
+        height: result.info.height,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new FrameDiffError(`Failed to process image: ${message}`);
+    }
+  }
+
+  /**
+   * 差分バッファから領域を抽出
+   *
+   * Pixelmatchの差分バッファからバウンディングボックスを計算
+   * - 差分ピクセルは赤色(255, 0, 0, 255)で描画される
+   * - アルファが0でないピクセルを差分として検出
+   *
+   * @param diffBuffer - Pixelmatchが生成した差分バッファ
+   * @param width - 画像幅
+   * @param height - 画像高さ
+   * @param expectedDiffCount - Pixelmatchが報告した差分ピクセル数
+   */
+  private extractDiffRegionsFromBuffer(
+    diffBuffer: Buffer,
+    width: number,
+    height: number,
+    expectedDiffCount: number
+  ): BoundingBox[] {
+    if (expectedDiffCount === 0) {
+      return [];
+    }
+
+    // 差分があるピクセルの座標からバウンディングボックスを計算
+    // Pixelmatchは差分ピクセルをdiffColor（デフォルト: 赤#FF0000）で描画
+    // アルファが255のピクセルを差分として検出
+    let minX = width;
+    let minY = height;
+    let maxX = -1;
+    let maxY = -1;
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const offset = (y * width + x) * 4;
+        // アルファチャンネルで差分を検出（Pixelmatchはa=255で差分を描画）
+        const alpha = diffBuffer[offset + 3];
+        if (alpha !== undefined && alpha > 0) {
+          if (x < minX) minX = x;
+          if (y < minY) minY = y;
+          if (x > maxX) maxX = x;
+          if (y > maxY) maxY = y;
+        }
+      }
+    }
+
+    // 差分が見つからなかった場合
+    if (maxX < 0 || maxY < 0) {
+      return [];
+    }
+
+    return [
+      {
+        x: minX,
+        y: minY,
+        width: maxX - minX + 1,
+        height: maxY - minY + 1,
+      },
+    ];
+  }
+
+  /**
+   * RGBAバッファをPNG画像に変換
+   */
+  private async bufferToPng(buffer: Buffer, width: number, height: number): Promise<Buffer> {
+    return sharp(buffer, {
+      raw: {
+        width,
+        height,
+        channels: 4,
+      },
+    })
+      .png()
+      .toBuffer();
+  }
+}

package/src/services/motion/analyzers/layout-shift.detector.ts

@@ -0,0 +1,296 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Layout Shift Detector
+ *
+ * フレーム差分からレイアウトシフトを検出し、CLS (Cumulative Layout Shift) スコアを計算する
+ *
+ * CLS計算仕様:
+ * - impact_fraction: ビューポートに対する変化領域の割合
+ * - distance_fraction: ビューポートの最大次元に対する移動距離の割合
+ * - layout_shift_score = impact_fraction * distance_fraction
+ *
+ * 分類閾値:
+ * - good: < 0.1
+ * - needs-improvement: >= 0.1 && < 0.25
+ * - poor: >= 0.25
+ *
+ * @module @reftrixmcp/mcp-server/services/motion/analyzers/layout-shift.detector
+ */
+
+// =============================================================================
+// 型定義
+// =============================================================================
+
+/**
+ * バウンディングボックス
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * ビューポート情報
+ */
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+/**
+ * 差分領域情報
+ * フレーム差分検出から得られる変化領域
+ */
+export interface DiffRegion {
+  /** 左上X座標 */
+  x: number;
+  /** 左上Y座標 */
+  y: number;
+  /** 幅 */
+  width: number;
+  /** 高さ */
+  height: number;
+  /** 変化強度 (0-1) */
+  changeIntensity: number;
+  /** 変化ピクセル数 */
+  pixelCount: number;
+  /** 前フレームでの位置（移動情報がある場合） */
+  previousPosition?: { x: number; y: number };
+}
+
+/**
+ * 個別のレイアウトシフト情報
+ */
+export interface LayoutShift {
+  /** シフト領域 */
+  region: BoundingBox;
+  /** 影響割合 (0-1) - ビューポートに対する変化領域の割合 */
+  impactFraction: number;
+  /** 移動距離割合 (0-1) - ビューポート最大次元に対する移動距離の割合 */
+  distanceFraction: number;
+  /** シフトスコア (impactFraction * distanceFraction) */
+  score: number;
+}
+
+/**
+ * レイアウトシフト分析結果
+ */
+export interface LayoutShiftResult {
+  /** 累積レイアウトシフトスコア (0-1+) */
+  cls: number;
+  /** 分類 */
+  classification: "good" | "needs-improvement" | "poor";
+  /** 検出されたシフト一覧 */
+  shifts: LayoutShift[];
+  /** 全体の影響割合 */
+  impactFraction: number;
+  /** 全体の移動距離割合 */
+  distanceFraction: number;
+}
+
+// =============================================================================
+// 定数
+// =============================================================================
+
+/**
+ * CLS分類閾値
+ */
+const CLS_THRESHOLDS = {
+  GOOD: 0.1,
+  NEEDS_IMPROVEMENT: 0.25,
+} as const;
+
+/**
+ * 移動距離推定係数（previousPositionがない場合）
+ */
+const DISTANCE_ESTIMATION_FACTOR = 0.1;
+
+// =============================================================================
+// LayoutShiftDetector クラス
+// =============================================================================
+
+/**
+ * レイアウトシフト検出器
+ *
+ * フレーム差分からレイアウトシフトを検出し、CLSスコアを計算する
+ */
+export class LayoutShiftDetector {
+  /**
+   * 差分領域からレイアウトシフトを検出
+   *
+   * @param diffRegions - 差分領域の配列
+   * @param viewport - ビューポート情報
+   * @returns 検出されたレイアウトシフトの配列
+   * @throws Error - ビューポートが無効な場合
+   */
+  detectShifts(diffRegions: DiffRegion[], viewport: Viewport): LayoutShift[] {
+    // ビューポートのバリデーション
+    this.validateViewport(viewport);
+
+    // 空の配列の場合は空を返す
+    if (diffRegions.length === 0) {
+      return [];
+    }
+
+    const viewportArea = viewport.width * viewport.height;
+    const maxViewportDimension = Math.max(viewport.width, viewport.height);
+
+    return diffRegions.map((region) => {
+      // 領域のバウンディングボックス
+      const boundingBox: BoundingBox = {
+        x: region.x,
+        y: region.y,
+        width: region.width,
+        height: region.height,
+      };
+
+      // ビューポート内の有効領域を計算
+      const visibleArea = this.calculateVisibleArea(region, viewport);
+
+      // impactFraction: ビューポートに対する変化領域の割合
+      const impactFraction = viewportArea > 0 ? visibleArea / viewportArea : 0;
+
+      // distanceFraction: 移動距離のビューポート最大次元に対する割合
+      let distanceFraction: number;
+      if (region.previousPosition) {
+        // 移動距離を計算
+        const dx = region.x - region.previousPosition.x;
+        const dy = region.y - region.previousPosition.y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        distanceFraction = maxViewportDimension > 0 ? distance / maxViewportDimension : 0;
+      } else {
+        // previousPositionがない場合は changeIntensity に基づいて推定
+        distanceFraction = region.changeIntensity * DISTANCE_ESTIMATION_FACTOR;
+      }
+
+      // 0-1の範囲にクランプ
+      const clampedImpactFraction = Math.max(0, Math.min(1, impactFraction));
+      const clampedDistanceFraction = Math.max(0, Math.min(1, distanceFraction));
+
+      // スコア計算
+      const score = clampedImpactFraction * clampedDistanceFraction;
+
+      return {
+        region: boundingBox,
+        impactFraction: clampedImpactFraction,
+        distanceFraction: clampedDistanceFraction,
+        score,
+      };
+    });
+  }
+
+  /**
+   * シフト配列からCLSを計算
+   *
+   * @param shifts - レイアウトシフトの配列
+   * @returns 累積レイアウトシフトスコア
+   */
+  calculateCLS(shifts: LayoutShift[]): number {
+    if (shifts.length === 0) {
+      return 0;
+    }
+
+    // 各シフトのスコアを累積
+    return shifts.reduce((total, shift) => total + shift.score, 0);
+  }
+
+  /**
+   * CLSスコアを分類
+   *
+   * @param cls - CLSスコア
+   * @returns 分類結果 ('good' | 'needs-improvement' | 'poor')
+   */
+  classifyShift(cls: number): "good" | "needs-improvement" | "poor" {
+    // 負の値は 'good' として扱う
+    if (cls < CLS_THRESHOLDS.GOOD) {
+      return "good";
+    }
+    if (cls < CLS_THRESHOLDS.NEEDS_IMPROVEMENT) {
+      return "needs-improvement";
+    }
+    return "poor";
+  }
+
+  /**
+   * フレームペアを解析してレイアウトシフト結果を返す
+   *
+   * @param diffRegions - 差分領域の配列
+   * @param viewport - ビューポート情報
+   * @returns レイアウトシフト分析結果
+   */
+  analyzeFramePair(diffRegions: DiffRegion[], viewport: Viewport): LayoutShiftResult {
+    // シフトを検出
+    const shifts = this.detectShifts(diffRegions, viewport);
+
+    // CLSを計算
+    const cls = this.calculateCLS(shifts);
+
+    // 分類
+    const classification = this.classifyShift(cls);
+
+    // 全体のimpactFractionとdistanceFractionを計算
+    let totalImpactFraction = 0;
+    let totalDistanceFraction = 0;
+
+    if (shifts.length > 0) {
+      totalImpactFraction = shifts.reduce((sum, s) => sum + s.impactFraction, 0);
+      totalDistanceFraction = shifts.reduce((sum, s) => sum + s.distanceFraction, 0);
+
+      // 平均化
+      totalImpactFraction /= shifts.length;
+      totalDistanceFraction /= shifts.length;
+    }
+
+    // 0-1の範囲にクランプ
+    totalImpactFraction = Math.max(0, Math.min(1, totalImpactFraction));
+    totalDistanceFraction = Math.max(0, Math.min(1, totalDistanceFraction));
+
+    return {
+      cls,
+      classification,
+      shifts,
+      impactFraction: totalImpactFraction,
+      distanceFraction: totalDistanceFraction,
+    };
+  }
+
+  // ===========================================================================
+  // プライベートメソッド
+  // ===========================================================================
+
+  /**
+   * ビューポートのバリデーション
+   */
+  private validateViewport(viewport: Viewport): void {
+    if (viewport.width <= 0 || viewport.height <= 0) {
+      throw new Error("Invalid viewport: width and height must be positive");
+    }
+  }
+
+  /**
+   * ビューポート内の有効領域面積を計算
+   */
+  private calculateVisibleArea(region: DiffRegion, viewport: Viewport): number {
+    // 領域の右端と下端
+    const regionRight = region.x + region.width;
+    const regionBottom = region.y + region.height;
+
+    // ビューポート内の有効範囲を計算
+    const visibleLeft = Math.max(0, region.x);
+    const visibleTop = Math.max(0, region.y);
+    const visibleRight = Math.min(viewport.width, regionRight);
+    const visibleBottom = Math.min(viewport.height, regionBottom);
+
+    // 有効幅と高さ（負の場合は0）
+    const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+    const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+
+    return visibleWidth * visibleHeight;
+  }
+}
+
+export default LayoutShiftDetector;