QuPath OpenSlide 扩展：本地库来源、依赖版本清单与打包实现解析-平芜编程栈

计算机视觉
图像处理
桌面应用
机器学习
医疗健康

【免费下载链接】qupath

QuPath - Open-source bioimage analysis for research

项目地址：https://gitcode.com/gh_mirrors/qu/qupath

本文基于 QuPath 仓库中 OpenSlide 扩展的许可证来源说明文档，系统梳理 QuPath 所捆绑的 OpenSlide 原生库来自哪里、由哪些组件构成、各平台版本有何差异，并结合qupath-extension-openslide模块的源码，深入解析 QuPath 实际加载与调用 OpenSlide 的方式（JNA 加载、金字塔读取、ICC 配置与裁剪选项）。读完本文，你将清楚理解 QuPath 中 OpenSlide 支持能力的底层依赖构成，以及如何核对、配置和排查 OpenSlide 相关的运行行为。

文档定位：一份第三方组件的“来源与版本”归属清单

在qupath-extension-openslide模块中，QuPath 不仅随扩展分发 OpenSlide 的原生库，还必须在src/main/resources/licenses/OpenSlide/目录下保留完整的第三方来源声明与许可文本。README.md 正是这份归属清单的核心：它回答了三个关键问题——

原生库从哪来：OpenSlide 本体、Java 绑定、Windows 预编译二进制各自的官方出处；
用的哪个版本：Windows 与 Mac 两套分发各自的 OpenSlide 版本及全部依赖版本；
依赖了哪些组件：从 zlib、libpng 到 cairo、SQLite 的完整列表。

这份清单不是泛泛的版权模板，而是与扩展的实际打包方式一一对应的技术记录，例如“预编译二进制被加入 Jar 以便从本地 Maven 仓库导入”这一句，直接对应了当前 build.gradle.kts 中通过 Maven 坐标引入 OpenSlide 构件（artifact）的做法。

OpenSlide 在 QuPath 中的角色

OpenSlide 是一个用于读取全玻片图像（whole slide image）的 C 库，支持 SVS、NDPI、MRXS、BIF 等多种格式。QuPath 通过独立的扩展模块qupath-extension-openslide接入它：

模块在 build.gradle.kts 中声明description = "QuPath extension to support image reading using OpenSlide."，模块名（JPMS）为qupath.extension.openslide；
扩展通过META-INF/services机制被 QuPath 自动发现：qupath.lib.gui.extensions.QuPathExtension 注册了界面扩展 OpenSlideExtension，qupath.lib.images.servers.ImageServerBuilder 注册了图像服务构建器 OpenslideServerBuilder；
调用方式是JNA 直连原生库：qupath.lib.images.servers.openslide.jna包下的 OpenSlideJNA 是 JNA 接口，逐一映射openslide_*C 函数。

因此，README 中记录的“OpenSlide 3.4.1”“OpenSlide Java 0.12.x”正是 QuPath 早期随扩展分发的原生层版本；当前仓库则以 Gradle 依赖形式管理更新的版本（见下文“版本演进”小节）。

源码与二进制来源

README 明确记录了四类来源：

内容	来源说明
OpenSlide 本体	使用3.4.1版本，源码取自其官方 GitHub 发布页`v3.4.1`标签
OpenSlide Java 绑定	使用0.12.2版本（Mac 分发）的 Java 绑定源码，取自 openslide-java 发布页`v0.12.2`
Windows 预编译二进制	取自 OpenSlide 官网下载页（openslide.org/download）的预编译构建，随后加入 Jar 文件，以便从本地 Maven 仓库导入
Windows 构建源码	取自 openslide-winbuild 的`v20150527`发布（包含全部依赖的构建工程）

从当前仓库代码可以印证“打包进 Jar + 本地 Maven”这条路径：

build.gradle.kts 声明依赖implementation("io.github.qupath:openslide:${libs.versions.openslide.get()}:${platform.classifier}")，即按当前平台（Windows/Mac/Linux）的分类器（classifier）拉取对应原生库构件；
版本号在 gradle/libs.versions.toml 中统一定义为openslide = "4.0.1.2"；
运行时若未配置用户自定义路径，OpenSlideLoader 会调用Native.extractFromResourcePath("openslide")从 Jar 中把原生库抽取到临时文件再加载——这正是 README 所说“加入 Jar 便于导入”的落地实现。

Windows 分发的依赖版本清单

README 对 Windows 分发列出了 OpenSlide 及其全部依赖的精确版本（共 16 项），这是 OpenSlide 3.4.1 时代官方 Windows 构建的依赖快照：

组件	版本
zlib	1.2.8
libpng	1.6.17
libjpeg-turbo	1.4.0
libtiff	4.0.4beta
OpenJPEG	2.1.0
win-iconv	0.0.6
gettext	0.19.4
libffi	3.2.1
glib	2.44.1
gdk-pixbuf	2.31.1
pixman	0.32.6
cairo	1.14.2
libxml2	2.9.2
SQLite	3.8.10.1
OpenSlide	3.4.1
OpenSlide Java	0.12.1

可以看到，OpenSlide 的图像解码链路高度依赖一组经典开源组件：zlib/libpng/libjpeg-turbo/libtiff/OpenJPEG 负责各厂商格式的解码，cairo/pixman 负责金字塔与区域渲染，glib/gdk-pixbuf 提供基础数据结构与像素缓冲，libxml2 用于解析 XML 元数据，SQLite 则服务于部分格式的元数据存储。这些依赖的许可证文本都被收纳在扩展的 licenses 目录中（见下文）。

Mac 分发的差异：Homebrew 构建版本表

与 Windows 不同，Mac 分发通过Homebrew编译原生库，因此依赖版本存在系统性差异。README 给出的完整清单如下：

组件	版本
cairo	1.14.6_1
libffi	3.0.13
fontconfig	2.12.1_2
freetype	2.7
gdk-pixbuf	2.36.0_2
gettext	0.19.8.1
glib	2.50.2
libjpeg	8d
OpenJPEG	2.1.2
pcre	8.39
pixman	0.34.0
libpng	1.6.26
libtiff	4.0.7
libxml2	2.9.4
OpenSlide	3.4.1_2
OpenSlide Java	0.12.2

与 Windows 列表对照，差异点集中在：Mac 额外引入fontconfig与freetype（字体渲染，Windows 构建通过 win-iconv/gettext 组合处理字符集）；libjpeg 使用 8d 而 Windows 使用 libjpeg-turbo 1.4.0；pcre 8.39 是 Windows 列表中没有的独立项；OpenSlide 本体为 Homebrew 修订版3.4.1_2，Java 绑定升级为0.12.2。

README 同时说明：Mac 分发的其他相关许可证收录在'Mac'目录。对应到仓库实际路径为 qupath-extension-openslide/src/main/resources/licenses/OpenSlide/mac/（当前包含 glib 的 COPYING 文本）。

仓库实现纵深：QuPath 如何加载和调用 OpenSlide

原生库加载的两种策略

OpenSlideLoader 是管理原生库生命周期的静态工具类，其加载策略与 README 描述的“Jar 打包”路线完全一致：

无用户路径（默认）：通过Native.extractFromResourcePath("openslide")从随扩展分发的 Jar 中抽取原生库到临时文件，再Native.load加载（L70-L80）；
有用户路径：将用户指定的目录拼入jna.library.path系统属性，然后Native.load("openslide", ...)按常规搜索路径加载（L82-L99）。

此外它还提供getLibraryVersion()（调用openslide_get_version）、detectVendor(path)（调用openslide_detect_vendor，用于 OpenslideServerBuilder 判断文件是否可被 OpenSlide 识别）、openImage(path)等入口。

JNA 接口映射

OpenSlideJNA 将 C API 映射为 Java 接口，覆盖：版本查询、厂商检测、打开/关闭图像、金字塔层数与各层尺寸、降采样倍数、属性名/属性值、关联图像（缩略图、标签图等）读写、区域像素读取（openslide_read_region）、错误获取（openslide_get_error）。值得注意的是，接口中还包含两个标注“New in OpenSlide 4.0.0”的方法openslide_get_icc_profile_size与openslide_read_icc_profile——它们是 QuPath 的 ICC 配置支持的原生基础。

像素读取与金字塔元数据

OpenSlide 类封装了一个已打开的 OpenSlide 句柄：

构造时读取金字塔层级数、各层宽高、全部属性键值对（openslide.comment、openslide.vendor、openslide.mpp-x/y、openslide.objective-power、openslide.bounds-*等）以及关联图像名称（L95-L146）；
paintRegionARGB调用openslide_read_region将指定层级、指定区域的像素写入 ARGB 整数数组，并通过ReentrantReadWriteLock保证并发读安全；
dispose()/close()调用openslide_close释放原生资源。

OpenslideImageServer 则在 QuPath 图像服务层消费这些能力：将 OpenSlide 报告的各层尺寸换算为ImageResolutionLevel（并自行计算 downsampling 而非直接采用 OpenSlide 的浮点近似值，L205-L218），默认以UINT8RGB 三通道构建元数据，并优先读取openslide.level[0].tile-width/tile-height作为分块尺寸（默认 256）。该服务还通过java.lang.ref.Cleaner确保 OpenSlide 原生句柄在服务被回收时自动关闭（L73-L93）。

配置与行为选项：裁剪、ICC 与背景色

README 虽未展开扩展参数，但仓库源码给出了完整的可配置行为，它们与 OpenSlide 属性直接相关。

扩展偏好（Preferences）

OpenSlideExtension 注册了三个持久化偏好（L53-L63），界面文案见 strings.properties：

偏好	存储键	默认值	说明
指向 OpenSlide 安装目录的路径	`openslide.path`	空字符串	用于指定自定义 OpenSlide 安装位置；设为空则重置为默认（Jar 内抽取）
是否应用 OpenSlide ICC 配置	`openslide.use-icc`	`false`	应用后会改变像素值并影响分析，属实验特性
是否裁剪到 OpenSlide 边界	`openslide.crop`	`true`	关闭后部分图像（如 mrxs、svs）可能带有大量空白填充，且尺寸与 Bio-Formats 等其它库不一致

安装扩展时，如果无法从 Jar 加载 OpenSlide，会提示用户“在偏好设置中指定包含 OpenSlide 库的目录”（L80-L84）。偏好变更后若目录需要重载，界面会提示重启 QuPath。这些偏好最终写入 OpenSlideOptions 单例（applyIccProfiles默认false、cropBoundingBox默认true），并影响新创建图像服务的参数。

构建器参数

OpenslideServerBuilder 支持三类字符串参数（L60-L73）：

--no-crop：禁用边界裁剪（等价于将 crop 偏好置为 false；QuPath ≤ v0.1.2 曾以此为默认行为）；
--icc-profile：请求应用 ICC 配置，触发 OpenslideIccImageServer 的创建；
--background-color：指定背景色（支持white、black、red、green、blue或#RRGGBB十六进制），优先于图像内嵌的openslide.background-color属性，最终默认白色。

checkImageSupport阶段的updateArgs会依据用户偏好自动追加参数，并且只有“用户要求 + 图像确实内嵌可读 ICC 配置”时才添加--icc-profile（L122-L139）。

ICC 颜色转换

OpenslideIccImageServer 继承自 OpenslideImageServer，在每个 tile 读取后用ColorConvertOp做颜色空间转换：

源配置：默认读取图像内嵌 ICC 配置（openslide_get_icc_profile_size/openslide_read_icc_profile，需 OpenSlide ≥ 4.0.0），也可用--icc-profile-source指定外部配置文件；
目标配置：默认 sRGB（ICC_ColorSpace.CS_sRGB），可用--icc-profile-dest指定；
服务类型标识为OpenSlide (ICC profile)，其createID在父类基础上追加(ICC profile)后缀以区分缓存键。

许可证目录结构：随扩展分发的第三方许可

README 所属的 licenses/OpenSlide/ 目录为每一家上游组件保留了许可文本，与上文两张版本表一一对应：

组件	仓库内许可文件
OpenSlide	OpenSlide/COPYING.LESSER（LGPL）
OpenJPEG	OpenJPEG/LICENSE
PCRE2	PCRE2/LICENCE
SQLite	SQLite/PUBLIC-DOMAIN.txt（公有领域）
cairo	cairo/COPYING（LGPL-2.1 / MPL-1.1 双许可）
gdk-pixbuf	gdk-pixbuf/COPYING
libdicom	libdicom/LICENSE
libffi	libffi/LICENSE
libjpeg-turbo	libjpeg-turbo/LICENSE.md
libpng	libpng/LICENSE
libtiff	libtiff/LICENSE.md
libxml2	libxml2/Copyright
pixman	pixman/COPYING
proxy-libintl	proxy-libintl/COPYING
uthash	uthash/LICENSE
zlib	zlib/README
Mac 附加许可	mac/glib/COPYING

这一布局保证了随扩展二进制分发的每一份原生代码都有对应的许可声明，是 LGPL 等许可协议对再分发（redistribution）义务的具体落实。

版本演进提示：README 与当前构建的关系

需要区分两个时间层级的版本信息：

README 记录的版本：OpenSlide 3.4.1 + OpenSlide Java 0.12.x，对应早期基于 openslide-winbuild（v20150527，2015 年）与 Homebrew 的打包时代；
当前仓库使用的版本：由 gradle/libs.versions.toml 统一管理为openslide = "4.0.1.2"，以带平台分类器的io.github.qupath:openslide构件引入。

两者共同说明 QuPath 在 OpenSlide 支持上的做法始终如一——把上游原生库及其全部依赖作为一个整体随扩展分发，并同时保留源码出处与许可声明。对读者而言：

若需核对运行时实际加载的 OpenSlide 版本，可在 QuPath 日志中查看OpenSlide loaded successfully: <version>（由OpenSlideLoader.getLibraryVersion()输出）；
若遇到 ICC 配置不可用的情况，需确认所加载的 OpenSlide 原生库 ≥ 4.0.0（ICC 相关 JNA 接口在 4.0.0 才引入）；
若需要更换自定义 OpenSlide 安装，可在扩展偏好中设置openslide.path指向包含libopenslide的目录，加载器会优先通过jna.library.path搜索该目录。

以上内容均可在qupath-extension-openslide模块的源码与资源目录中直接验证，licenses/OpenSlide/README.md 则是对这套原生依赖体系的“来源 + 版本”权威记录。