LibCspCore 1.3.1

LibCspCore — CSP 数字病理图像读取库

高性能读取 CSP（Chinese Society of Pathology）数字病理图像格式，遵循《CSP 数字病理图像数据存储格式规范》。专为数字病理切片（Whole Slide Image）场景设计，适用于病理诊断、远程病理、AI 分析等领域。

🔥 核心特性

• ‌Data Entry 树解析‌：支持递归解析 SEQUENCE 嵌套结构，完整提取金字塔层、瓦片索引、附加图像等元数据
• ‌金字塔式瓦片索引‌：支持多分辨率层快速定位与 JPEG 瓦片读取，优化阅片体验
• ‌瓦片零转码‌：CSP 瓦片本身即 JPEG，ReadTileImg 直接返回原始字节
• ‌私有信息嵌入文件‌：解析 CspWritePrivateInfo 写入的打包嵌入文件（Config.cfg、SlideInfo.json、AI 图块等），按名读取原始字节
• ‌文件句柄池技术‌：支持高并发场景下的文件句柄复用与元数据缓存
• ‌统一接口设计‌：与 LibTiffCore（SVS/BigTIFF）共享 IWSIInfo/IWSILayerInfo/IWSIReaderProxy 接口，方便多格式集成调用
• ‌跨平台支持‌：基于 .NET Standard 2.0，兼容 .NET Framework 4.6.1+ / .NET Core 3.1+ / .NET 5+；跨平台能力随依赖的 LibTiffCore 一致（Windows/Linux/macOS）
• ‌小端二进制解析‌：支持 16/32/64 位三种寻址方式，覆盖全部 CSP 文件规格

📦 安装

dotnet add package LibCspCore --version 1.3.0

🚀 快速开始

using LibCspCore;
using LibTiffCore;

// 使用连接池（推荐）
using var pool = new CspReaderPool(
    fileHandleTimeout: TimeSpan.FromMinutes(5),
    cleanupInterval: TimeSpan.FromMinutes(1),
    metadataCacheExpiration: TimeSpan.FromHours(1),
    maxHandles: 10);

// 通过统一接口读取
IWSIReaderProxy reader = await pool.GetReaderAsync(@"path\to\slide.csp");
IWSIInfo info = reader.Info;

Console.WriteLine($"尺寸: {info.Width} x {info.Height}");
Console.WriteLine($"层数: {info.Layers.Count}");

// 读取指定层的瓦片（JPEG 原始字节，可直接保存或解码显示）
for (short level = 0; level < info.Layers.Count; level++)
{
    var layer = info.Layers[level];
    for (int row = 0; row < layer.Rows; row++)
        for (int col = 0; col < layer.Cols; col++)
        {
            byte[] tileData = reader.ReadTileImg(level, row, col);
        }
}

// 读取附加图像（标签图/预览图/缩略图）
foreach (var kvp in info.AssociatedImages)
{
    byte[] imageBytes = reader.GetAssociatedImageJpegBytes(kvp.Key);
}

私有信息打包嵌入文件（1.3.0+）

扫描端通过 CspWritePrivateInfo（UID 0xFF000001）批量嵌入文件时，库会自动解析打包块， 嵌入文件集合在 CspInfo.PrivateFiles 中（同时并入 AssociatedImages）：

using var pool = new CspReaderPool();
using var reader = pool.GetReader(@"path\to\slide.csp");
var info = reader.CspImg;

// 遍历嵌入文件（名称 + 大小 + 文件内偏移）
foreach (var kvp in info.PrivateFiles)
    Console.WriteLine($"{kvp.Key}  {kvp.Value.Length} 字节");

// 按名称读取原始字节（配置文件/AI 图块等）
byte[] config = reader.GetPrivateFileBytes("Config.cfg");
byte[] slideInfo = reader.GetPrivateFileBytes("SlideInfo.json");
byte[] aiTile = reader.GetPrivateFileBytes("AI/Cluster/OTHERS/0.000_1.000_0_014_012_967_713_512_512.jpg");

// 不存在的文件返回 null

🏗️ 项目架构

┌─────────────────────────────────────┐
│         你的应用程序                  │
├─────────────────────────────────────┤
│  IWSIInfo / IWSILayerInfo / ...     │  ← 统一接口
├──────────────────┬──────────────────┤
│   LibTiffCore     │   LibCspCore    │
│  (SVS/BigTIFF)   │   (CSP格式)     │
└──────────────────┴──────────────────┘

📖 CSP 格式简介

CSP（Chinese Society of Pathology）是中华医学会病理学分会制定的数字病理图像统一格式标准，后缀为 .csp。主要特点：

• 128 字节定长文件头：魔数 "MEDIC"，支持 16/32/64 位寻址
• Data Entry 结构：[2B MID][2B EID][2B DT] + [VN][VL] + [Value]，SEQUENCE 类型支持递归嵌套
• 金字塔多分辨率：从底层（最高分辨率）到顶层（最低分辨率），每层分割为固定尺寸的 JPEG 瓦片
• 附加图像：支持标签图（Label）、预览图（Preview）、缩略图（Thumbnail）
• 私有信息：厂商扩展区（MDID=0xFF00），支持嵌入任意二进制私有数据与批量打包文件
• 丰富元数据：扫描仪信息、扫描配置（倍率/MPP/压缩算法）、切片信息、患者信息、标注信息

🔗 相关项目

• LibTiffCore — SVS/BigTIFF 格式读取库，与本库共享统一接口

📧 联系方式

如有问题，请发邮件至：kkkwp@foxmail.com

⚠️ 许可证

请勿用于商业用途，仅供学习交流使用。详见 LICENSE。

📜 更新日志

1.3.0（2026-09-29）

• 新增：私有信息打包嵌入文件读取（CspWritePrivateInfo 写入的 UID 0xFF000001 打包块， 格式：[4B 文件总数] + 循环[4B 名长 + 文件名 + 4B 数据长 + 数据]，与 SVS 侧嵌入文件格式一致）
• 新增：CspInfo.PrivateFiles 嵌入文件集合，并同步并入 AssociatedImages
• 新增：CspReaderProxy.GetPrivateFileBytes(fileName) 按文件名读取嵌入文件原始字节
• 性能：打开文件时不再将 PIXEL_DATA 值域（可达数百 MB）整块载入内存

1.2.1

修复资源释放方法。

1.2.0

层序重排（ReorganizeCspLayers），layer 0 = 最小缩略层，与 LibTiffCore 约定一致。