如何在 Excel 中使用 GroupDocs.Watermark Java 搜索图像

在 Excel 工作簿中搜索特定图像可能非常繁琐，尤其是在处理大型文件或大量嵌入式图形时。How to search images 很快就成为任何自动化文档工作流的人所面临的关键问题。在本指南中，我们将准确展示如何使用 GroupDocs.Watermark Java 在 Excel 电子表格中搜索图像，同时还涵盖高效 load Excel file java 项目的关键步骤。

快速答案

  • 定位嵌入图像的最快方法是什么？ Use ImageDctHashSearchCriteria with SpreadsheetSearchableObjects.AttachedImages.
  • 我需要特殊许可证吗？ A temporary or trial license unlocks full search capabilities.
  • 需要哪个 Maven 依赖？ Add com.groupdocs:groupdocs-watermark to your pom.xml.
  • 我可以将搜索限制在单个工作表吗？ Yes, configure SpreadsheetLoadOptions with the sheet name.
  • API 是否线程安全？ All public methods are safe for concurrent use after proper initialization.

ImageDctHashSearchCriteria 定义用于图像比较的 DCT 哈希。SpreadsheetSearchableObjects.AttachedImages 将搜索限制为嵌入的图片。

在 GroupDocs.Watermark 上下文中，“how to search images” 是什么？

“How to search images” 指的是使用 Watermarker API 以编程方式定位文档内部的嵌入图片对象。库会扫描每个工作表，提取图片对象，计算它们的离散余弦变换（DCT）哈希，并将其与目标图像的哈希进行比较，返回任何匹配项作为可进一步处理的 watermark 对象。

为什么在 Excel 图像搜索中使用 GroupDocs.Watermark？

GroupDocs.Watermark 支持 50+ 输入和输出格式——包括 XLSX、XLS、CSV 和 ODS——在处理多百页工作簿时无需将整个文件加载到内存中。其 DCT‑hash 算法能够以 > 95% 的准确率识别视觉相似的图像，大幅降低误报。此外，库提供流式访问，允许您处理大于可用 RAM 的文件，并内置对受密码保护的工作簿的支持，使其适用于企业级自动化流水线。

前提条件

在开始之前，请确保您拥有：

  • Java Development Kit (JDK) 8+ 已安装并在您的 PATH 中配置。
  • Maven 用于依赖管理（或您可以手动下载 JAR）。
  • 一个 GroupDocs.Watermark license（试用、临时或永久）以解锁搜索 API。
  • 对 Java 集合和异常处理有基本了解。

必需的库和依赖项

要使用 GroupDocs.Watermark Java，请使用 Maven 设置环境或下载必要的库。确保您拥有：

  • Maven Configuration: 将 GroupDocs 仓库和依赖项添加到您的 pom.xml。
  • Java Development Kit (JDK): 需要 8 版或更高版本。

环境设置要求

确保 Java 已在系统上正确安装，并在选择此安装方式时配备 Maven 用于依赖管理。

知识前提

对 Java 编程的基本理解以及熟悉以编程方式处理 Excel 文件将大有裨益。如果您对这些概念不熟悉，建议先查阅入门资源。

如何为 Java 设置 GroupDocs.Watermark？

加载您的 Maven 项目，添加依赖项，并使用适当的设置初始化 Watermarker。此两步过程让您准备好开始搜索。首先，将 Maven 仓库和依赖项添加到您的 pom.xml，然后通过传入 Excel 文件路径和一个指定所需工作表和搜索设置的 WatermarkLoadOptions 对象来创建 Watermarker 实例。SpreadsheetLoadOptions 允许您指定加载哪些工作表并配置搜索选项，如大小写敏感性。Watermarker 是加载文档并执行搜索或水印操作的主要入口。

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/watermark/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-watermark</artifactId>
      <version>24.11</version>
   </dependency>
</dependencies>

如何使用特定搜索设置加载 Excel 文件 java？

在加载工作簿时指示库仅查看附加图像。这种聚焦方法可将典型电子表格的处理时间缩短最多 30 %。

import com.groupdocs.watermark.Watermarker;
// Basic initialization code here...

如何配置搜索以仅针对附加图像？

SpreadsheetSearchableObjects 枚举允许您精确指定要扫描的内容。将其设置为 AttachedImages 会将引擎限制为图片对象，忽略文本、公式或图表。

import com.groupdocs.watermark.WatermarkerSettings;
import com.groupdocs.watermark.options.SpreadsheetLoadOptions;

WatermarkerSettings settings = new WatermarkerSettings();
settings.getSearchableObjects().setSpreadsheetSearchableObjects(SpreadsheetSearchableObjects.AttachedImages);

如何使用 DCT 哈希标准执行图像搜索？

DCT‑hash 方法为参考图像创建紧凑的指纹，并将其与每个嵌入的图片进行比较，返回具有高度视觉相似性的匹配项。

import com.groupdocs.watermark.Watermarker;

String filePath = "YOUR_DOCUMENT_DIRECTORY/spreadsheet.xlsx";
SpreadsheetLoadOptions loadOptions = new SpreadsheetLoadOptions();
Watermarker watermarker = new Watermarker(filePath, loadOptions, settings);

如何定义 DCT 哈希搜索标准？

ImageDctHashSearchCriteria 封装了参考图像和可选的相似度阈值。您可以调整阈值（0‑100）以收紧或放宽匹配。

// Reuse the previous configuration from the 'Load Spreadsheet' section.

如何运行搜索并处理结果？

调用 watermarker.search(criteria) 将返回 Watermark 对象的集合。遍历该集合以获取页码、单元格地址，或替换图像。

import com.groupdocs.watermark.search.ImageDctHashSearchCriteria;

String imagePath = "YOUR_DOCUMENT_DIRECTORY/sample_image.png";
ImageDctHashSearchCriteria criteria = new ImageDctHashSearchCriteria(imagePath);

实际应用

以下是这些功能发挥作用的一些真实场景：

  1. Document Management Systems: 自动根据嵌入的徽标或产品照片对电子表格进行索引和标记。
  2. Data Auditing: 通过比较不同版本的 DCT 哈希，验证视觉数据（图表、截图）未被篡改。
  3. Content Verification: 确保财务报告或营销演示文稿中仅出现授权的品牌资产。

性能考虑因素

为了保持应用程序的响应速度：

  • Scope the search 仅限 AttachedImages；这平均可将 CPU 使用率降低约 30 %。
  • Process large files 通过分块加载单个工作表而不是整个工作簿来处理大文件。
  • Reuse WatermarkerSettings 在多个搜索之间复用，以避免重复创建对象。
  • Monitor memory 使用 Java 性能分析工具进行监控；库会流式处理数据，但非常大的图像仍可能影响堆内存使用。

常见问题及解决方案

症状可能原因解决办法
未返回结果可搜索对象设置为 None设置 SpreadsheetSearchableObjects.AttachedImages。
OutOfMemoryError 在 500 页文件上整个工作簿加载到内存中使用 SpreadsheetLoadOptions 并调用 setLoadAllSheets(false)，然后逐个加载工作表。
哈希比较中的误报阈值过低（例如 30）将相似度阈值提高到 80‑90，以实现更严格的匹配。

常见问题

Q: GroupDocs.Watermark 能读取哪些 Excel 文件格式？
A: 它支持 XLSX、XLS、CSV 和 ODS，能够处理传统和现代的工作簿结构。

Q: 我可以搜索未附加的图像（例如漂浮形状）吗？
A: 可以，通过将 SpreadsheetSearchableObjects.All 设置为包含漂浮图片、图表和其他绘图对象。

Q: DCT 哈希匹配的准确度如何？
A: 该算法在对尺寸调整或轻微重新着色的图像进行相似度检测时可达 > 95 % 的准确率，适用于品牌检查。

Q: 能否自动替换找到的图像？
A: 完全可以。在定位到 Watermark 后，调用 watermarker.replace(watermark, newImagePath) 以交换图形。

Q: 该库能在 Linux 容器上运行吗？
A: 可以，GroupDocs.Watermark 纯 Java，实现可在任何兼容 JRE 的平台上运行，包括基于 Docker 的 Linux 容器。

结论

在本教程中，我们通过使用 GroupDocs.Watermark Java 在 Excel 工作簿中 how to search images，从环境设置到执行基于 DCT‑hash 的搜索，进行了完整演示。通过将扫描限制为附加图像并利用强大的哈希比较，您可以显著加快图像验证工作流，同时保持高准确性。接下来，探索库的水印添加功能或将搜索逻辑集成到更大的文档处理流水线中。

最后更新： 2026-06-01
测试环境： GroupDocs.Watermark 23.12 for Java
作者： GroupDocs

资源

import com.groupdocs.watermark.PossibleWatermarkCollection;

PossibleWatermarkCollection possibleWatermarks = watermarker.search(criteria);

资源

相关教程