彻底解析Supervisely Blob格式与数据集图像提取：从底层编码到工程实践
项目地址: https://gitcode.com/gh_mirrors/su/supervisely 痛点与解决方案概述
在计算机视觉（Computer Vision）项目开发中，标注数据的高效存储与精准提取是影响模型训练效率的关键瓶颈。传统图像标注格式（如COCO、Pascal VOC）普遍存在存储空间占用大、网络传输效率低、掩码（Mask）精度损失等问题。Supervisely平台提供的Blob格式通过ZLIB压缩与Base64编码结合的二进制存储方案，将标注数据体积减少60%-80%，同时保持像素级精度。本文将系统剖析Blob格式的底层实现原理，并通过完整工程案例演示如何从数据集高效提取与还原标注图像。
读完本文你将掌握：
- Blob格式的二进制编码规范与压缩原理
- Bitmap/AlphaMask几何对象的序列化与反序列化机制
- 数据集图像与标注的批量提取技术
- 标注数据可视化与质量校验方法
Blob格式技术原理
核心数据结构
Supervisely Blob格式的核心实现位于supervisely/geometry/bitmap.py，通过Bitmap类实现二进制掩码的高效处理。其数据流程包含三个关键步骤：掩码预处理→ZLIB压缩→Base64编码。
关键代码实现：
# Bitmap数据压缩核心实现
def data_2_base64(mask: np.ndarray) -> str:
img_pil = Image.fromarray(np.array(mask, dtype=np.uint8))
img_pil.putpalette([0, 0, 0, 255, 255, 255]) # 黑白调色板
bytes_io = io.BytesIO()
img_pil.save(bytes_io, format="PNG", transparency=0, optimize=0)
bytes_enc = bytes_io.getvalue()
return base64.b64encode(zlib.compress(bytes_enc)).decode("utf-8")
与传统格式对比
| 特性 | Blob格式 | COCO JSON | Pascal VOC XML |
|---|---|---|---|
| 存储效率 | 高（压缩比3-5倍） | 低（纯文本） | 极低（XML+图像文件） |
| 精度 | 像素级 | 多边形近似 | 多边形近似 |
| 读取速度 | 快（内存映射） | 慢（JSON解析） | 慢（XML解析） |
| 适用场景 | 大规模数据集传输与存储 | 学术研究与小数据集 | 传统计算机视觉任务 |
核心类与API解析
Bitmap类层次结构
关键方法解析
-
掩码裁剪优化
def _find_mask_tight_bbox(raw_mask: np.ndarray) -> Rectangle: rows = np.any(raw_mask, axis=1).tolist() cols = np.any(raw_mask, axis=0).tolist() top_margin = rows.index(True) bottom_margin = len(rows) - 1 - rows[::-1].index(True) left_margin = cols.index(True) right_margin = len(cols) - 1 - cols[::-1].index(True) return Rectangle(top=top_margin, left=left_margin, bottom=bottom_margin, right=right_margin)该方法通过寻找掩码矩阵中非零像素的最小边界，去除无效空白区域，平均减少30%-50%的存储体积。
-
双向格式转换
# Base64字符串解码为NumPy矩阵 @staticmethod def base64_2_data(s: str) -> np.ndarray: try: z = zlib.decompress(base64.b64decode(s)) except zlib.error: img = Image.open(io.BytesIO(base64.b64decode(s))) return np.any(np.array(img), axis=-1) n = np.frombuffer(z, np.uint8) imdecoded = cv2.imdecode(n, cv2.IMREAD_UNCHANGED) return imdecoded[:, :, 3].astype(bool) if imdecoded.shape[2] == 4 else imdecoded.astype(bool)
数据集图像提取工程实践
环境准备
# 克隆官方仓库
git clone https://gitcode.com/gh_mirrors/su/supervisely
cd supervisely
# 安装依赖
pip install -r docs/doc-requirements.txt
pip install -e .
核心提取流程
数据集图像提取通过supervisely/project/download.py中的download_fast方法实现，支持异步并发下载与缓存机制。关键参数说明：
| 参数名 | 类型 | 描述 |
|---|---|---|
api | Api | Supervisely API客户端实例 |
project_id | int | 项目ID |
dest_dir | str | 本地存储路径 |
download_blob_files | bool | 是否下载原始Blob文件 |
semaphore | Semaphore | 并发控制信号量 |
提取代码示例：
import supervisely as sly
from supervisely.io.fs import ensure_base_path
# 初始化API客户端
api = sly.Api.from_env()
# 项目配置
PROJECT_ID = 8888
DEST_DIR = "/data/supervisely_datasets/coco2017"
ensure_base_path(DEST_DIR)
# 异步下载（默认开启）
sly.download_fast(
api=api,
project_id=PROJECT_ID,
dest_dir=DEST_DIR,
download_blob_files=True, # 保留原始Blob文件
log_progress=True
)
标注数据还原与可视化
从Blob格式还原标注并可视化的完整流程：
import cv2
import numpy as np
from supervisely.geometry.bitmap import Bitmap
from supervisely.annotation.annotation import Annotation
from supervisely.project.project_meta import ProjectMeta
def visualize_annotation(image_path, ann_path, output_path):
# 读取图像
img = cv2.imread(image_path)
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
# 读取标注
meta = ProjectMeta.from_json(api.project.get_meta(PROJECT_ID))
ann_json = sly.json.load_json_file(ann_path)
ann = Annotation.from_json(ann_json, meta)
# 绘制所有掩码
for label in ann.labels:
if isinstance(label.geometry, Bitmap):
# Blob解码为掩码矩阵
mask = label.geometry.data
# 获取掩码在图像中的位置
origin = label.geometry.origin
# 生成随机颜色
color = np.random.randint(0, 255, 3).tolist()
# 绘制掩码
img[origin.row:origin.row+mask.shape[0],
origin.col:origin.col+mask.shape[1]][mask] = color
# 保存可视化结果
cv2.imwrite(output_path, cv2.cvtColor(img, cv2.COLOR_RGB2BGR))
# 批量处理示例
for dataset in sly.Project(DEST_DIR).datasets:
for item_name in dataset.get_items_names():
img_path, ann_path = dataset.get_item_paths(item_name)
visualize_annotation(img_path, ann_path, f"{DEST_DIR}/visualized/{item_name}")
性能优化与最佳实践
内存优化策略
-
分块处理大尺寸图像：对于4K以上分辨率图像，使用
supervisely.geometry.sliding_windows模块进行分块处理from supervisely.geometry.sliding_windows import SlidingWindow windows = SlidingWindow(img_size=(4096, 4096), window_size=(512, 512), step=(256, 256)) for window in windows: process_window(img[window.slice], ann.crop(window.rect)) -
缓存机制：利用
download_to_cache方法缓存已下载数据集，避免重复网络传输# 缓存数据集 downloaded, cached = sly.download_to_cache( api=api, project_id=PROJECT_ID, dataset_ids=[123, 456] # 指定数据集ID ) # 从缓存复制到工作目录 sly.copy_from_cache(PROJECT_ID, DEST_DIR, dataset_paths=cached)
常见问题解决方案
| 问题场景 | 解决方案 | 代码示例 |
|---|---|---|
| Blob解码失败 | 检查Base64字符串完整性，尝试跳过ZLIB解压 | try: z = zlib.decompress(...) except: Image.open(...) |
| 掩码与图像尺寸不匹配 | 使用resize方法标准化处理 | scaled_mask = bitmap.resize(in_size=(1024,1024), out_size=(512,512)) |
| 大规模数据集下载超时 | 启用断点续传与增量下载 | sly.download_fast(..., resume_download=True) |
总结与扩展应用
Supervisely Blob格式通过创新的二进制编码方案，有效解决了传统标注格式的存储与传输效率问题。其核心价值体现在：
- 工业级数据集管理：支持TB级标注数据的高效存储与分发
- 实时协作标注：压缩格式降低网络带宽需求，提升多人协作效率
- 边缘设备部署：小体积标注数据适合嵌入式设备离线推理
扩展应用方向：
- 结合
supervisely/aug模块实现基于Blob格式的实时数据增强 - 利用
supervisely/nn/inference构建Blob标注驱动的模型推理 pipeline - 通过
supervisely/export/pascal_voc.py实现Blob到其他格式的转换
通过本文阐述的技术原理与工程实践，开发者可构建高效、可靠的计算机视觉数据处理流水线，显著提升模型开发迭代效率。
附录：关键API速查表
| 类/方法 | 功能描述 | 所在文件 |
|---|---|---|
Bitmap.data_2_base64 | 掩码转Blob字符串 | supervisely/geometry/bitmap.py |
Bitmap.base64_2_data | Blob字符串转掩码 | supervisely/geometry/bitmap.py |
Annotation.from_json | JSON标注转Annotation对象 | supervisely/annotation/annotation.py |
download_fast | 数据集快速下载 | supervisely/project/download.py |
AlphaMask | 带透明度掩码处理 | supervisely/geometry/alpha_mask.py |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
