sam-cell-seg

SAM 细胞分割技能

此技能为涉及基于 SAM（Segment Anything Model）的细胞分割、掩码处理和多边形转换流水线的任务提供指导。

任务特征

此技能适用于涉及以下内容的任务：

• 使用 MobileSAM 或 SAM 模型进行图像分割
• 将二值掩码转换为多边形／折线表示
• 处理包含坐标数据的 CSV 文件
• 为深度学习推理流水线构建命令行工具
• 显微镜图像中的细胞或物体分割

实施前的关键步骤

1. 确认接口要求

编写任何代码之前，先确认具体的接口要求：

1. 检查脚本的调用方式：

   • 阅读测试文件或评估框架，了解预期的参数格式
   • 确定参数应为位置参数还是关键字参数（--arg_name）
   • 核实测试框架要求的确切参数名称

2. 确认输出格式规范：

   • 检查输入文件格式，并确保输出格式与之完全一致
   • 注意数据类型：列表与元组、字符串与数字
   • 核实 CSV 输出中的列名、顺序和分隔符

3. 了解评估标准：

   • 确认所用指标（IoU、准确率等）及其阈值
   • 了解通过／失败条件的判定标准

2. 环境假设

• 假设指定的软件包在测试环境中可用
• 不要在环境配置或安装软件包上花费过多时间
• 如果软件包安装失败或超时，请假设软件包可用并继续编写代码
• 优先确保代码正确，而不是排查环境问题

实施方法

参数解析模式

为机器学习流水线构建 CLI 工具时，使用带有明确标志的关键字参数：

import argparse

def parse_args():
    parser = argparse.ArgumentParser(description='Process masks with SAM')
    # Use keyword arguments (--flag format), not positional
    parser.add_argument('--weights_path', type=str, required=True,
                        help='Path to model weights')
    parser.add_argument('--csv_path', type=str, required=True,
                        help='Path to input CSV')
    parser.add_argument('--rgb_path', type=str, required=True,
                        help='Path to RGB image')
    parser.add_argument('--output_path', type=str, required=True,
                        help='Path for output CSV')
    return parser.parse_args()

数据类型一致性

确保整个流水线中的数据类型一致：

# When processing coordinates, maintain list format (not tuples)
def mask_to_polygon(mask):
    # ... processing logic ...
    # Return coordinates as lists, not tuples
    return [[int(x), int(y)] for x, y in coordinates]

# When saving to CSV, verify format
def save_coordinates(coords, output_path):
    # Ensure coordinates are stored as lists
    formatted_coords = [list(c) if isinstance(c, tuple) else c for c in coords]
    # ... save logic ...

SAM/MobileSAM 集成模式

def load_sam_model(weights_path, device='cuda'):
    """Load SAM model with proper device handling."""
    # Check device availability
    if device == 'cuda' and not torch.cuda.is_available():
        device = 'cpu'

    # Load model
    model = sam_model_registry[model_type](checkpoint=weights_path)
    model.to(device)
    model.eval()
    return model, device

def refine_mask_with_sam(sam_model, image, initial_mask, device):
    """Use SAM to refine an initial mask."""
    predictor = SamPredictor(sam_model)
    predictor.set_image(image)

    # Get bounding box or point prompts from initial mask
    # ... prompt extraction logic ...

    masks, scores, _ = predictor.predict(
        point_coords=point_coords,
        point_labels=point_labels,
        box=box,
        multimask_output=True
    )

    # Select best mask based on IoU with initial mask or score
    best_mask = select_best_mask(masks, scores, initial_mask)
    return best_mask

掩码转多边形

import cv2
import numpy as np

def mask_to_polygon(binary_mask, simplify_tolerance=1.0):
    """Convert binary mask to polygon coordinates."""
    # Ensure mask is binary uint8
    mask = (binary_mask > 0).astype(np.uint8) * 255

    # Find contours
    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)

    if not contours:
        return []

    # Get largest contour
    largest_contour = max(contours, key=cv2.contourArea)

    # Simplify contour
    epsilon = simplify_tolerance * cv2.arcLength(largest_contour, True)
    simplified = cv2.approxPolyDP(largest_contour, epsilon, True)

    # Convert to list format (not tuples)
    polygon = [[int(pt[0][0]), int(pt[0][1])] for pt in simplified]

    return polygon

验证清单

提交前

1. 接口验证：

   • 运行 python script.py --help，确认参数解析正常
   • 确认参数名称与测试要求完全一致
   • 确认使用的是关键字参数还是位置参数格式

2. 输出格式验证：

   • 将输出 CSV 结构与输入 CSV 结构进行比较
   • 确认坐标数据类型为列表，而不是元组
   • 检查输出中是否包含所有预期行
   • 验证列名和顺序

3. 端到端测试：

   • 使用示例数据运行完整流水线
   • 确认输出文件已创建且格式正确
   • 检查所有输入行是否都生成了对应输出

4. 质量指标：

   • 计算细化掩码与预期输出之间的 IoU
   • 确认指标达到阈值要求（例如，IoU > 0.5）

代码审查要点

1. 参数解析器：使用 --flag 格式，而不是位置参数
2. 数据类型：坐标存储为列表，而不是元组
3. 错误处理：妥善处理边缘情况（空掩码、缺失文件）
4. 设备处理：实现恰当的 CUDA/CPU 回退逻辑

常见问题

1. 参数格式不匹配

问题：测试要求关键字参数，却使用了位置参数。

检测方法：脚本报错“unrecognized arguments”或类似错误。

解决方案：使用 argparse 实现前，务必先检查测试的调用格式。

2. 数据类型不一致

问题：预期使用列表，却将坐标存储为元组。

检测方法：测试因坐标格式或 JSON 序列化问题而失败。

解决方案：保存前显式转换为列表：[list(coord) for coord in coords]

3. 处理不完整

问题：并非所有输入行都出现在输出中。

检测：输入与输出的行数不匹配。

解决方案：确认循环处理了所有行；添加日志以跟踪进度。

4. 环境调试陷阱

问题：安装超时后，仍花费过多时间处理软件包安装问题。

检测：多次安装失败。

解决方案：相信测试环境；专注于代码正确性。如果软件包无法在本地安装，请假设它们已存在并继续。

5. 过早宣布完成

问题：未经端到端验证就宣布任务完成。

检测：直到测试评估时才发现根本性错误。

解决方案：宣布完成前，务必使用测试参数运行实际命令。

6. 文件读取不完整

问题：未读取完整文件内容，遗漏关键代码段。

检测：代码审查时，未读取部分中的明显错误被忽略。

解决方案：文件输出被截断时，分段读取，或使用 offset/limit 参数。

测试策略

单元测试优先级顺序

1. 参数解析：确认 CLI 接口符合预期
2. 输入/输出格式：确认数据在管道中正确流转
3. 核心功能：测试掩码处理和多边形转换
4. 集成测试：端到端管道测试

最小可行测试

# Quick sanity check before full test suite
import subprocess
import sys

def test_cli_interface():
    """Verify script accepts expected arguments."""
    result = subprocess.run(
        [sys.executable, 'script.py', '--help'],
        capture_output=True,
        text=True
    )
    assert result.returncode == 0
    assert '--weights_path' in result.stdout
    assert '--csv_path' in result.stdout
    assert '--rgb_path' in result.stdout
    assert '--output_path' in result.stdout

任务执行顺序

1. 阅读测试文件或评估框架，了解接口要求
2. 确认确切的参数格式和输出格式规范
3. 根据发现的要求实现参数解析
4. 实现核心功能（SAM 加载、掩码处理、多边形转换）
5. 使用 --help 标志验证接口
6. 使用示例数据运行端到端测试
7. 确认输出格式与规范完全一致
8. 检查所有质量指标是否达到阈值