visual_analysis_tool.h

Go to the documentation of this file.

 
#ifndef YAZE_SRC_CLI_SERVICE_AGENT_TOOLS_VISUAL_ANALYSIS_TOOL_H_
#define YAZE_SRC_CLI_SERVICE_AGENT_TOOLS_VISUAL_ANALYSIS_TOOL_H_
 
#include <cstdint>
#include <map>
#include <string>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "cli/service/resources/command_handler.h"
 
namespace yaze {
namespace cli {
namespace agent {
namespace tools {
 
struct TileSimilarityMatch {
  int tile_id;
  double similarity_score;  // 0.0 - 100.0
  int sheet_index;
  int x_position;  // X position in sheet (pixels)
  int y_position;  // Y position in sheet (pixels)
};
 
struct UnusedRegion {
  int sheet_index;
  int x;
  int y;
  int width;
  int height;
  int tile_count;  // Number of 8x8 tiles in region
};
 
struct PaletteUsageStats {
  int palette_index;
  int usage_count;
  double usage_percentage;
  std::vector<int> used_by_maps;  // Map IDs using this palette
};
 
struct TileUsageEntry {
  int tile_id;
  int usage_count;
  double usage_percentage;
  std::vector<int> locations;  // Map/room IDs where used
};
 
class VisualAnalysisBase : public resources::CommandHandler {
 public:
  // Constants for SNES graphics (public for testing)
  static constexpr int kTileWidth = 8;
  static constexpr int kTileHeight = 8;
  static constexpr int kTilePixels = kTileWidth * kTileHeight;  // 64
  static constexpr int kSheetWidth = 128;   // pixels
  static constexpr int kSheetHeight = 32;   // pixels per sheet row
  static constexpr int kTilesPerRow = kSheetWidth / kTileWidth;  // 16
  static constexpr int kMaxSheets = 223;
 
 protected:
  double ComputePixelDifference(const std::vector<uint8_t>& tile_a,
                                const std::vector<uint8_t>& tile_b) const;
 
  double ComputeStructuralSimilarity(const std::vector<uint8_t>& tile_a,
                                     const std::vector<uint8_t>& tile_b) const;
 
  absl::StatusOr<std::vector<uint8_t>> ExtractTile(Rom* rom, int sheet_index,
                                                   int tile_index) const;
 
  absl::StatusOr<std::vector<uint8_t>> ExtractTileAtPosition(Rom* rom,
                                                              int sheet_index,
                                                              int x,
                                                              int y) const;
 
  bool IsRegionEmpty(const std::vector<uint8_t>& data) const;
 
  int GetTileCountForSheet(int sheet_index) const;
 
  std::string FormatMatchesAsJson(
      const std::vector<TileSimilarityMatch>& matches) const;
 
  std::string FormatRegionsAsJson(
      const std::vector<UnusedRegion>& regions) const;
 
  std::string FormatPaletteUsageAsJson(
      const std::vector<PaletteUsageStats>& stats) const;
 
  std::string FormatHistogramAsJson(
      const std::vector<TileUsageEntry>& entries) const;
};
 
class TileSimilarityTool : public VisualAnalysisBase {
 public:
  std::string GetName() const override { return "visual-find-similar-tiles"; }
 
  std::string GetDescription() const {
    return "Find tiles with similar patterns to a reference tile";
  }
 
  std::string GetUsage() const override {
    return "visual-find-similar-tiles --tile_id <id> [--sheet <index>] "
           "[--threshold <0-100>] [--method <pixel|structural>]";
  }
 
 protected:
  absl::Status ValidateArgs(const resources::ArgumentParser& parser) override;
 
  absl::Status Execute(Rom* rom, const resources::ArgumentParser& parser,
                       resources::OutputFormatter& formatter) override;
 
  bool RequiresLabels() const override { return false; }
};
 
class SpritesheetAnalysisTool : public VisualAnalysisBase {
 public:
  std::string GetName() const override { return "visual-analyze-spritesheet"; }
 
  std::string GetDescription() const {
    return "Identify unused regions in graphics sheets for ROM hacking";
  }
 
  std::string GetUsage() const override {
    return "visual-analyze-spritesheet [--sheet <index>] [--tile_size <8|16>] "
           "[--format <json|text>]";
  }
 
 protected:
  absl::Status ValidateArgs(const resources::ArgumentParser& parser) override;
 
  absl::Status Execute(Rom* rom, const resources::ArgumentParser& parser,
                       resources::OutputFormatter& formatter) override;
 
  bool RequiresLabels() const override { return false; }
 
 private:
  std::vector<UnusedRegion> FindUnusedRegions(Rom* rom, int sheet_index,
                                               int tile_size) const;
 
  std::vector<UnusedRegion> MergeAdjacentRegions(
      const std::vector<UnusedRegion>& regions) const;
};
 
class PaletteUsageTool : public VisualAnalysisBase {
 public:
  std::string GetName() const override { return "visual-palette-usage"; }
 
  std::string GetDescription() const {
    return "Analyze palette usage statistics across maps";
  }
 
  std::string GetUsage() const override {
    return "visual-palette-usage [--type <overworld|dungeon|all>] "
           "[--format <json|text>]";
  }
 
 protected:
  absl::Status ValidateArgs(const resources::ArgumentParser& parser) override;
 
  absl::Status Execute(Rom* rom, const resources::ArgumentParser& parser,
                       resources::OutputFormatter& formatter) override;
 
  bool RequiresLabels() const override { return false; }
 
 private:
  std::vector<PaletteUsageStats> AnalyzeOverworldPalettes(Rom* rom) const;
 
  std::vector<PaletteUsageStats> AnalyzeDungeonPalettes(Rom* rom) const;
};
 
class TileHistogramTool : public VisualAnalysisBase {
 public:
  std::string GetName() const override { return "visual-tile-histogram"; }
 
  std::string GetDescription() const {
    return "Generate frequency histogram of tile usage across maps";
  }
 
  std::string GetUsage() const override {
    return "visual-tile-histogram [--type <overworld|dungeon>] [--top <n>] "
           "[--format <json|text>]";
  }
 
 protected:
  absl::Status ValidateArgs(const resources::ArgumentParser& parser) override;
 
  absl::Status Execute(Rom* rom, const resources::ArgumentParser& parser,
                       resources::OutputFormatter& formatter) override;
 
  bool RequiresLabels() const override { return false; }
 
 private:
  std::map<int, TileUsageEntry> CountOverworldTiles(Rom* rom) const;
 
  std::map<int, TileUsageEntry> CountDungeonTiles(Rom* rom) const;
};
 
#ifdef YAZE_WITH_OPENCV
namespace opencv {
 
std::pair<std::pair<int, int>, double> TemplateMatch(
    const std::vector<uint8_t>& reference,
    const std::vector<uint8_t>& search_region, int width, int height,
    int method);
 
double FeatureMatch(const std::vector<uint8_t>& tile_a,
                    const std::vector<uint8_t>& tile_b);
 
double ComputeSSIM(const std::vector<uint8_t>& tile_a,
                   const std::vector<uint8_t>& tile_b);
 
}  // namespace opencv
#endif  // YAZE_WITH_OPENCV
 
}  // namespace tools
}  // namespace agent
}  // namespace cli
}  // namespace yaze
 
#endif  // YAZE_SRC_CLI_SERVICE_AGENT_TOOLS_VISUAL_ANALYSIS_TOOL_H_