Add hybrid alpha blending

app.py

@@ -167,13 +167,42 @@ def refine_foreground(image, mask, r=90, device='cuda'):
     return estimated_foreground
 
 
-def get_rankseg_mask(pred: torch.Tensor, metric: str) -> Image.Image:
+def get_rankseg_pred(pred: torch.Tensor, metric: str) -> torch.Tensor:
     # BiRefNet produces a single foreground probability map, so RankSEG should
     # return a binary mask for that one channel instead of a multiclass map.
     rankseg = RankSEG(metric=metric, output_mode='multilabel', solver='RMA')
-    probs = pred.unsqueeze(0).unsqueeze(0)
-    rankseg_pred = rankseg.predict(probs).squeeze(0).squeeze(0).to(torch.float32)
-    return transforms.ToPILImage()(rankseg_pred)
+    probs = pred.unsqueeze(0).unsqueeze(0).to(torch.float32)
+    return rankseg.predict(probs).squeeze(0).squeeze(0).to(torch.float32)
+
+
+def get_soft_gate(rankseg_mask: torch.Tensor, dilate_kernel: int = 9, blur_kernel: int = 15) -> torch.Tensor:
+    support = rankseg_mask.unsqueeze(0).unsqueeze(0).to(torch.float32)
+    dilated = torch.nn.functional.max_pool2d(
+        support,
+        kernel_size=dilate_kernel,
+        stride=1,
+        padding=dilate_kernel // 2,
+    )
+    soft_gate = torch.nn.functional.avg_pool2d(
+        dilated,
+        kernel_size=blur_kernel,
+        stride=1,
+        padding=blur_kernel // 2,
+    )
+    return soft_gate.squeeze(0).squeeze(0).clamp(0, 1)
+
+
+def build_hybrid_alpha(pred: torch.Tensor, rankseg_mask: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+    soft_gate = get_soft_gate(rankseg_mask)
+    hard_alpha = (pred * rankseg_mask.to(torch.float32)).clamp(0, 1)
+    soft_alpha = torch.where(rankseg_mask > 0, pred, pred * soft_gate).clamp(0, 1)
+    return hard_alpha, soft_alpha
+
+
+def build_alpha_cutout(image: Image.Image, mask: Image.Image) -> Image.Image:
+    output = image.copy()
+    output.putalpha(mask.resize(image.size))
+    return output
 
 
 def build_masked_image(image: Image.Image, mask: Image.Image) -> Image.Image:
@@ -269,7 +298,8 @@ def predict(images, resolution, weights_file, enable_rankseg, rankseg_metric):
 
     if isinstance(images, list):
         raw_save_paths = []
-        rankseg_save_paths = []
+        rankseg_hard_save_paths = []
+        rankseg_soft_save_paths = []
         save_dir = 'preds-BiRefNet'
         if not os.path.exists(save_dir):
             os.makedirs(save_dir)
@@ -295,37 +325,44 @@ def predict(images, resolution, weights_file, enable_rankseg, rankseg_metric):
 
         # Prediction
         with torch.no_grad():
-            preds = birefnet(image_proc.to(device).half())[-1].sigmoid().cpu()
+            preds = birefnet(image_proc.to(device).half())[-1].sigmoid().float().cpu()
         pred = preds[0].squeeze()
 
         pred_pil = transforms.ToPILImage()(pred)
-        raw_image_masked = build_masked_image(image, pred_pil)
-        rankseg_image_masked = None
+        raw_image_masked = build_alpha_cutout(image, pred_pil)
+        rankseg_hard_image_masked = None
+        rankseg_soft_image_masked = None
         if enable_rankseg:
-            rankseg_mask = get_rankseg_mask(pred, rankseg_metric)
-            rankseg_image_masked = build_masked_image(image, rankseg_mask)
+            rankseg_pred = get_rankseg_pred(pred, rankseg_metric)
+            hard_alpha, soft_alpha = build_hybrid_alpha(pred, rankseg_pred)
+            rankseg_hard_image_masked = build_alpha_cutout(image, transforms.ToPILImage()(hard_alpha))
+            rankseg_soft_image_masked = build_alpha_cutout(image, transforms.ToPILImage()(soft_alpha))
 
         if device == 'cuda':
             torch.cuda.empty_cache()
 
         if tab_is_batch:
             image_name = os.path.splitext(os.path.basename(image_src))[0]
-            raw_save_file_path = os.path.join(save_dir, f"{image_name}_raw.png")
+            raw_save_file_path = os.path.join(save_dir, f"{image_name}_pred.png")
             raw_image_masked.save(raw_save_file_path)
             raw_save_paths.append(raw_save_file_path)
-            if enable_rankseg and rankseg_image_masked is not None:
-                rankseg_save_file_path = os.path.join(save_dir, f"{image_name}_rankseg.png")
-                rankseg_image_masked.save(rankseg_save_file_path)
-                rankseg_save_paths.append(rankseg_save_file_path)
+            if enable_rankseg and rankseg_hard_image_masked is not None:
+                rankseg_hard_save_file_path = os.path.join(save_dir, f"{image_name}_pred_rankseg.png")
+                rankseg_hard_image_masked.save(rankseg_hard_save_file_path)
+                rankseg_hard_save_paths.append(rankseg_hard_save_file_path)
+            if enable_rankseg and rankseg_soft_image_masked is not None:
+                rankseg_soft_save_file_path = os.path.join(save_dir, f"{image_name}_pred_softgate.png")
+                rankseg_soft_image_masked.save(rankseg_soft_save_file_path)
+                rankseg_soft_save_paths.append(rankseg_soft_save_file_path)
 
     if tab_is_batch:
         zip_file_path = os.path.join(save_dir, "{}.zip".format(save_dir))
         with zipfile.ZipFile(zip_file_path, 'w') as zipf:
-            for file in raw_save_paths + rankseg_save_paths:
+            for file in raw_save_paths + rankseg_hard_save_paths + rankseg_soft_save_paths:
                 zipf.write(file, os.path.basename(file))
-        return raw_save_paths, rankseg_save_paths, zip_file_path
+        return raw_save_paths, rankseg_hard_save_paths, rankseg_soft_save_paths, zip_file_path
     else:
-        return image, raw_image_masked, rankseg_image_masked
+        return image, raw_image_masked, rankseg_hard_image_masked, rankseg_soft_image_masked
 
 
 examples = [[_] for _ in glob('examples/*')][:]
@@ -361,8 +398,9 @@ tab_image = gr.Interface(
     ],
     outputs=[
         gr.Image(label="Original image", type="pil", format='png'),
-        gr.Image(label="BiRefNet result", type="pil", format='png'),
-        gr.Image(label="BiRefNet + RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred alpha", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred x RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet soft-gated hybrid", type="pil", format='png'),
     ],
     examples=examples,
     api_name="image",
@@ -380,8 +418,9 @@ tab_text = gr.Interface(
     ],
     outputs=[
         gr.Image(label="Original image", type="pil", format='png'),
-        gr.Image(label="BiRefNet result", type="pil", format='png'),
-        gr.Image(label="BiRefNet + RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred alpha", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred x RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet soft-gated hybrid", type="pil", format='png'),
     ],
     examples=examples_url,
     api_name="URL",
@@ -398,8 +437,9 @@ tab_batch = gr.Interface(
         gr.Radio(RANKSEG_METRICS, value='dice', label="RankSEG metric", info="Choose the target metric for RankSEG post-processing.")
     ],
     outputs=[
-        gr.Gallery(label="BiRefNet results"),
-        gr.Gallery(label="BiRefNet + RankSEG results"),
+        gr.Gallery(label="BiRefNet pred alpha results"),
+        gr.Gallery(label="BiRefNet pred x RankSEG results"),
+        gr.Gallery(label="BiRefNet soft-gated hybrid results"),
         gr.File(label="Download masked images."),
     ],
     api_name="batch",

app_local.py

@@ -164,13 +164,42 @@ def refine_foreground(image, mask, r=90, device='cuda'):
     return estimated_foreground
 
 
-def get_rankseg_mask(pred: torch.Tensor, metric: str) -> Image.Image:
+def get_rankseg_pred(pred: torch.Tensor, metric: str) -> torch.Tensor:
     # BiRefNet produces a single foreground probability map, so RankSEG should
     # return a binary mask for that one channel instead of a multiclass map.
     rankseg = RankSEG(metric=metric, output_mode='multilabel', solver='RMA')
-    probs = pred.unsqueeze(0).unsqueeze(0)
-    rankseg_pred = rankseg.predict(probs).squeeze(0).squeeze(0).to(torch.float32)
-    return transforms.ToPILImage()(rankseg_pred)
+    probs = pred.unsqueeze(0).unsqueeze(0).to(torch.float32)
+    return rankseg.predict(probs).squeeze(0).squeeze(0).to(torch.float32)
+
+
+def get_soft_gate(rankseg_mask: torch.Tensor, dilate_kernel: int = 9, blur_kernel: int = 15) -> torch.Tensor:
+    support = rankseg_mask.unsqueeze(0).unsqueeze(0).to(torch.float32)
+    dilated = torch.nn.functional.max_pool2d(
+        support,
+        kernel_size=dilate_kernel,
+        stride=1,
+        padding=dilate_kernel // 2,
+    )
+    soft_gate = torch.nn.functional.avg_pool2d(
+        dilated,
+        kernel_size=blur_kernel,
+        stride=1,
+        padding=blur_kernel // 2,
+    )
+    return soft_gate.squeeze(0).squeeze(0).clamp(0, 1)
+
+
+def build_hybrid_alpha(pred: torch.Tensor, rankseg_mask: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+    soft_gate = get_soft_gate(rankseg_mask)
+    hard_alpha = (pred * rankseg_mask.to(torch.float32)).clamp(0, 1)
+    soft_alpha = torch.where(rankseg_mask > 0, pred, pred * soft_gate).clamp(0, 1)
+    return hard_alpha, soft_alpha
+
+
+def build_alpha_cutout(image: Image.Image, mask: Image.Image) -> Image.Image:
+    output = image.copy()
+    output.putalpha(mask.resize(image.size))
+    return output
 
 
 def build_masked_image(image: Image.Image, mask: Image.Image) -> Image.Image:
@@ -265,7 +294,8 @@ def predict(images, resolution, weights_file, enable_rankseg, rankseg_metric):
 
     if isinstance(images, list):
         raw_save_paths = []
-        rankseg_save_paths = []
+        rankseg_hard_save_paths = []
+        rankseg_soft_save_paths = []
         save_dir = 'preds-BiRefNet'
         if not os.path.exists(save_dir):
             os.makedirs(save_dir)
@@ -291,37 +321,44 @@ def predict(images, resolution, weights_file, enable_rankseg, rankseg_metric):
 
         # Prediction
         with torch.no_grad():
-            preds = birefnet(image_proc.to(device).half())[-1].sigmoid().cpu()
+            preds = birefnet(image_proc.to(device).half())[-1].sigmoid().float().cpu()
         pred = preds[0].squeeze()
 
         pred_pil = transforms.ToPILImage()(pred)
-        raw_image_masked = build_masked_image(image, pred_pil)
-        rankseg_image_masked = None
+        raw_image_masked = build_alpha_cutout(image, pred_pil)
+        rankseg_hard_image_masked = None
+        rankseg_soft_image_masked = None
         if enable_rankseg:
-            rankseg_mask = get_rankseg_mask(pred, rankseg_metric)
-            rankseg_image_masked = build_masked_image(image, rankseg_mask)
+            rankseg_pred = get_rankseg_pred(pred, rankseg_metric)
+            hard_alpha, soft_alpha = build_hybrid_alpha(pred, rankseg_pred)
+            rankseg_hard_image_masked = build_alpha_cutout(image, transforms.ToPILImage()(hard_alpha))
+            rankseg_soft_image_masked = build_alpha_cutout(image, transforms.ToPILImage()(soft_alpha))
 
         if device == 'cuda':
             torch.cuda.empty_cache()
 
         if tab_is_batch:
             image_name = os.path.splitext(os.path.basename(image_src))[0]
-            raw_save_file_path = os.path.join(save_dir, f"{image_name}_raw.png")
+            raw_save_file_path = os.path.join(save_dir, f"{image_name}_pred.png")
             raw_image_masked.save(raw_save_file_path)
             raw_save_paths.append(raw_save_file_path)
-            if enable_rankseg and rankseg_image_masked is not None:
-                rankseg_save_file_path = os.path.join(save_dir, f"{image_name}_rankseg.png")
-                rankseg_image_masked.save(rankseg_save_file_path)
-                rankseg_save_paths.append(rankseg_save_file_path)
+            if enable_rankseg and rankseg_hard_image_masked is not None:
+                rankseg_hard_save_file_path = os.path.join(save_dir, f"{image_name}_pred_rankseg.png")
+                rankseg_hard_image_masked.save(rankseg_hard_save_file_path)
+                rankseg_hard_save_paths.append(rankseg_hard_save_file_path)
+            if enable_rankseg and rankseg_soft_image_masked is not None:
+                rankseg_soft_save_file_path = os.path.join(save_dir, f"{image_name}_pred_softgate.png")
+                rankseg_soft_image_masked.save(rankseg_soft_save_file_path)
+                rankseg_soft_save_paths.append(rankseg_soft_save_file_path)
 
     if tab_is_batch:
         zip_file_path = os.path.join(save_dir, "{}.zip".format(save_dir))
         with zipfile.ZipFile(zip_file_path, 'w') as zipf:
-            for file in raw_save_paths + rankseg_save_paths:
+            for file in raw_save_paths + rankseg_hard_save_paths + rankseg_soft_save_paths:
                 zipf.write(file, os.path.basename(file))
-        return raw_save_paths, rankseg_save_paths, zip_file_path
+        return raw_save_paths, rankseg_hard_save_paths, rankseg_soft_save_paths, zip_file_path
     else:
-        return image, raw_image_masked, rankseg_image_masked
+        return image, raw_image_masked, rankseg_hard_image_masked, rankseg_soft_image_masked
 
 
 examples = [[_] for _ in glob('examples/*')][:]
@@ -357,8 +394,9 @@ tab_image = gr.Interface(
     ],
     outputs=[
         gr.Image(label="Original image", type="pil", format='png'),
-        gr.Image(label="BiRefNet result", type="pil", format='png'),
-        gr.Image(label="BiRefNet + RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred alpha", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred x RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet soft-gated hybrid", type="pil", format='png'),
     ],
     examples=examples,
     api_name="image",
@@ -376,8 +414,9 @@ tab_text = gr.Interface(
     ],
     outputs=[
         gr.Image(label="Original image", type="pil", format='png'),
-        gr.Image(label="BiRefNet result", type="pil", format='png'),
-        gr.Image(label="BiRefNet + RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred alpha", type="pil", format='png'),
+        gr.Image(label="BiRefNet pred x RankSEG", type="pil", format='png'),
+        gr.Image(label="BiRefNet soft-gated hybrid", type="pil", format='png'),
     ],
     examples=examples_url,
     api_name="URL",
@@ -394,8 +433,9 @@ tab_batch = gr.Interface(
         gr.Radio(RANKSEG_METRICS, value='dice', label="RankSEG metric", info="Choose the target metric for RankSEG post-processing.")
     ],
     outputs=[
-        gr.Gallery(label="BiRefNet results"),
-        gr.Gallery(label="BiRefNet + RankSEG results"),
+        gr.Gallery(label="BiRefNet pred alpha results"),
+        gr.Gallery(label="BiRefNet pred x RankSEG results"),
+        gr.Gallery(label="BiRefNet soft-gated hybrid results"),
         gr.File(label="Download masked images."),
     ],
     api_name="batch",

docs/rankseg_refine_foreground_analysis.md

@@ -0,0 +1,455 @@
+# RankSEG 与 `refine_foreground` 管线分析报告
+
+## 1. 结论摘要
+
+1. `refine_foreground` 支持 soft mask，也支持 binary mask。它在实现上把 `mask` 当作 `alpha` 使用，要求数值范围在 `[0, 1]`；binary mask 只是 soft mask 的特例。
+2. 当前 `rankseg` 版本的 `RankSEG.predict()` 不输出 soft mask。官方文档和本地源码都表明，它返回的是离散预测，值为 `0/1` 或布尔值，而不是新的概率图。
+3. 对二分类单通道场景，RankSEG 不是简单地把固定阈值 `0.5` 换成另一个全局阈值 `tau`。更准确地说，它会基于整张图的概率排序，求一个当前图像、当前类别对应的最优 `top-k` 截断位置 `opt_tau`，再把前 `k` 个像素设为前景。
+4. 因此，`refine_foreground(rankseg_mask)` 在代码上是成立的，但它用到的是 hard alpha。这样更利于区域判定干净，不一定更利于发丝、半透明边缘等 soft alpha 细节。
+5. 如果目标是“让 RankSEG 的区域选择能力也帮助最终抠图质量”，更合理的方案通常不是要求 RankSEG 直接输出 soft mask，而是让 RankSEG 作为区域约束，原始 `pred` 继续提供 soft alpha。
+
+## 2. 问题与回答
+
+### Q1. `refine_foreground` 支持 soft mask 吗？
+
+支持。
+
+本地实现里，`refine_foreground` 明确写着：
+
+- `image` 和 `mask` 都应在 `[0, 1]` 范围内
+- `mask` 会被转成 `float32`
+- 后续计算里 `mask` 以 `alpha` 形式参与模糊、混合和前景估计
+
+这说明它期望的是连续 alpha，而不是仅限于 0/1 标签。
+
+### Q2. `refine_foreground` 能接受 binary mask 吗？
+
+能。
+
+binary mask 的取值是 `{0, 1}`，本身就是 `[0, 1]` 的子集，因此在数学上和实现上都合法。只是 binary mask 不携带边界过渡信息，所以对前景颜色估计来说通常不如 soft mask 丰富。
+
+### Q3. RankSEG 能输出 soft mask 吗？
+
+就当前项目安装的 `rankseg==0.0.4` 而言，不能。
+
+`RankSEG.predict()` 的官方文档和本地源码都写明它返回的是 binary segmentation predictions。`output_mode='multilabel'` 的含义是“每个类返回一张二值 mask”，不是“输出 soft mask”。
+
+### Q4. RankSEG 是否等价于“找一个更好的全局阈值 `tau`”？
+
+不完全是。
+
+对你现在的单图、单类、binary segmentation 使用场景，可以把它近似理解成“找到一个比 0.5 更合适的自适应截断位置”。但从源码看，它优化的是排序后的 `top-k` 选择，不是直接在原概率空间里学习一个固定全局阈值。
+
+更精确地说：
+
+- `0.5 threshold` 是固定规则
+- RankSEG 是对当前图像的所有像素概率排序
+- 然后根据目标指标估计最佳 `opt_tau`
+- 最终保留前 `opt_tau` 个像素为前景
+
+在单通道情况下，这个过程可以等价成一个“当前图像专属”的隐式阈值切点，但不是数据集级别的全局常数阈值。
+
+## 3. `refine_foreground` 的来源、术语与技术脉络
+
+### 3.1 `FB` 是什么意思？
+
+这里的 `F` 和 `B` 是 matting / compositing 领域里的经典记号：
+
+- `F` = Foreground，前景颜色
+- `B` = Background，背景颜色
+- `alpha` = 透明度或前景占比
+
+经典合成公式可以写成：
+
+```text
+I = alpha * F + (1 - alpha) * B
+```
+
+其中：
+
+- `I` 是观测到的输入图像
+- `F` 是希望恢复的真实前景颜色
+- `B` 是背景颜色
+- `alpha` 控制前景和背景的混合比例
+
+所以这份代码里的 `FB_blur_fusion_foreground_estimator_*`，名字可以直接读成：
+
+```text
+一种基于模糊融合（blur fusion）的 F/B 前景估计器
+```
+
+它的目标不是再次估计分割类别，而是在已知 `image` 和 `alpha(mask)` 后，估计更干净的 `F`。
+
+### 3.2 当前实现最直接的代码来源
+
+从项目代码注释看，当前 `refine_foreground` 链路最直接依赖了两个来源：
+
+1. Photoroom 的 `fast-foreground-estimation`
+2. BiRefNet 社区里的 GPU 改写版本
+
+项目本地注释已经写明：
+
+- CPU 版本参考了 Photoroom 仓库
+- GPU 双阶段版本参考了 BiRefNet issue comment
+
+对应代码见 [app.py](/Users/lev1s/Documents/BiRefNet_demo/app.py#L137)。
+
+BiRefNet 官方仓库后续也明确写到，`refine_foreground` 的提速来自 “the GPU implementation of fast-fg-est”。这说明当前仓库里的 `refine_foreground`，本质上不是 BiRefNet 原论文提出的新理论模块，而是把现有 foreground estimation 方法接到了推理后处理中。
+
+### 3.3 直接可追溯的论文来源
+
+当前这条实现链最清楚的论文来源分两层：
+
+#### 第一层：近似实现
+
+Photoroom 的开源仓库 `fast-foreground-estimation` 明确写着，它是论文 “Approximate Fast Foreground Colour Estimation” 的官方仓库，作者是 Marco Forte，发表于 ICIP 2021。
+
+这个仓库 README 又明确说明：
+
+- 该方法是一个很快的 foreground estimation technique
+- 它“yields comparable results to the full approach [1], while also being faster”
+- 其中 `[1]` 指向的就是 `Fast Multi-Level Foreground Estimation`
+
+也就是说，当前代码中这种非常短小、基于 blur fusion 的实现，最直接对应的是：
+
+```text
+Marco Forte, "Approximate Fast Foreground Colour Estimation", ICIP 2021
+```
+
+#### 第二层：更早的完整方法
+
+Photoroom 官方材料和 PyMatting 文档都把上面的近似法指向了更早的完整方法：
+
+```text
+Thomas Germer, Tobias Uelwer, Stefan Conrad, Stefan Harmeling,
+"Fast Multi-Level Foreground Estimation", ICPR 2020
+```
+
+这篇工作讨论的是：
+
+- 已知 alpha matte
+- 如何估计 foreground colours
+- 以避免直接抠图后出现边缘 bleed-through
+
+所以从“研究脉络”上讲：
+
+```text
+当前 refine_foreground
+    <- 工程上更接近 Photoroom 的 Approximate Fast Foreground Colour Estimation
+    <- 理论上又是对 Germer 等人 Fast Multi-Level Foreground Estimation 的近似实现
+```
+
+### 3.4 它和传统 matting 文献的关系
+
+这条线属于 image matting / foreground estimation，而不是纯 segmentation。
+
+更具体地说，它属于：
+
+- 已知 alpha 或已有 mask
+- 进一步恢复前景颜色 `F`
+- 让最终合成结果更自然
+
+这和只输出一个二值 mask 的分割工作不同，也和只估计 alpha matte 的方法不同。它解决的是：
+
+```text
+“mask 有了之后，怎么恢复更干净的前景颜色”。
+```
+
+所以它在定位上更接近：
+
+- foreground colour estimation
+- alpha matting 的后处理
+- compositing quality enhancement
+
+而不是：
+
+- segmentation mask optimization
+
+### 3.5 对当前项目的准确表述
+
+如果在报告或提交说明里需要一句准确表述，我建议写成：
+
+```text
+本项目中的 refine_foreground 并非 BiRefNet 原始分割网络的一部分，
+而是一个用于前景颜色估计的后处理模块。
+其当前实现最直接来源于 Photoroom 开源的
+"Approximate Fast Foreground Colour Estimation"（Marco Forte, ICIP 2021），
+该方法又是对 Germer 等人
+"Fast Multi-Level Foreground Estimation"（ICPR 2020）
+的快速近似。
+```
+
+## 4. 源码证据
+
+### 4.1 `refine_foreground` 如何使用 mask
+
+项目里的实现见 [app.py](/Users/lev1s/Documents/BiRefNet_demo/app.py#L143)。
+
+关键信息：
+
+```python
+def refine_foreground(image, mask, r=90, device='cuda'):
+    """both image and mask are in range of [0, 1]"""
+```
+
+以及：
+
+```python
+mask = transforms.functional.to_tensor(mask).float().cuda()
+```
+
+和：
+
+```python
+blurred_alpha = mean_blur(alpha, kernel_size=r)
+blurred_FGA = mean_blur(FG * alpha, kernel_size=r)
+blurred_B1A = mean_blur(B * (1 - alpha), kernel_size=r)
+```
+
+这些实现说明：
+
+1. `mask` 被当成连续 `alpha`
+2. 算法内部直接使用 `alpha` 和 `1 - alpha`
+3. soft alpha 会影响模糊融合结果
+4. binary alpha 也可运行，但只是一种退化情况
+
+### 4.2 当前项目中 RankSEG 的接法
+
+见 [app.py](/Users/lev1s/Documents/BiRefNet_demo/app.py#L170)：
+
+```python
+def get_rankseg_mask(pred: torch.Tensor, metric: str) -> Image.Image:
+    rankseg = RankSEG(metric=metric, output_mode='multilabel', solver='RMA')
+    probs = pred.unsqueeze(0).unsqueeze(0).to(torch.float32)
+    rankseg_pred = rankseg.predict(probs).squeeze(0).squeeze(0).to(torch.float32)
+    return transforms.ToPILImage()(rankseg_pred)
+```
+
+这里输入 `probs` 是 `(1, 1, H, W)` 的 soft probability map，但 `rankseg_pred` 是离散预测后再转回 `float32` 以便转图像，不代表它重新变成了 soft mask。
+
+### 4.3 RankSEG 官方语义
+
+本地安装包源码见 [rankseg/_rankseg.py](/Users/lev1s/Documents/BiRefNet_demo/.venv/lib/python3.12/site-packages/rankseg/_rankseg.py#L94)：
+
+```python
+def predict(self, probs):
+    """Convert probability maps to binary segmentation predictions.
+```
+
+返回说明见同文件 [rankseg/_rankseg.py](/Users/lev1s/Documents/BiRefNet_demo/.venv/lib/python3.12/site-packages/rankseg/_rankseg.py#L105)：
+
+```python
+preds : torch.Tensor
+    Binary segmentation predictions ...
+    Values are 0 or 1 (or boolean True/False depending on solver).
+```
+
+这已经直接排除了“当前 `predict()` 输出 soft mask”的解释。
+
+### 4.4 RankSEG 的 `tau` 到底是什么
+
+实现见 [rankseg/_rankseg_algo.py](/Users/lev1s/Documents/BiRefNet_demo/.venv/lib/python3.12/site-packages/rankseg/_rankseg_algo.py#L250)。
+
+关键逻辑：
+
+```python
+opt_tau = torch.argmax(metric_values, dim=-1) + 1
+```
+
+以及：
+
+```python
+overlap_preds[b, c, top_index[b, c, :opt_tau[b, c]]] = True
+```
+
+这说明：
+
+1. 先对概率从大到小排序
+2. 估计不同 `tau` 下的指标值
+3. 选择最优 `opt_tau`
+4. 将前 `opt_tau` 个像素直接置为前景
+
+因此 `tau` 是“保留多少个最高概率像素”的截断位置，本质上是 `top-k` 选择，不是简单地把所有像素与某个固定常数阈值比较。
+
+## 5. 解释：为什么 `refine_foreground` 更偏爱 soft mask
+
+`refine_foreground` 做的不是再次分割，而是前景颜色估计。它本质上在解下面这类问题：
+
+```text
+image ~= foreground * alpha + background * (1 - alpha)
+```
+
+这里的 `alpha` 越连续，算法越能利用边缘过渡信息去恢复更自然的前景颜色。
+
+所以：
+
+- soft mask 更利于柔边、发丝、半透明边缘
+- binary mask 更利于轮廓果断、区域清晰
+
+两者优化目标不同：
+
+- RankSEG 更偏向 mask 指标优化，如 Dice / IoU
+- `refine_foreground` 更偏向最终抠图观感优化
+
+## 6. 回答你的核心判断
+
+### 5.1 “如果 RankSEG 输出 soft mask，就能更好接上 `refine_foreground` 吗？”
+
+原则上是的。
+
+如果 RankSEG 能输出经过其全局优化后的 soft alpha，那它会比 hard mask 更适合 `refine_foreground`。但当前版本并没有这样的 API。
+
+### 5.2 “既然 RankSEG 不能输出 soft mask，那当前 `refine_foreground(rankseg_mask)` 是否没有意义？”
+
+不是没有意义，而是意义不同。
+
+当前做法的价值是：
+
+- 利用 RankSEG 提升区域级的前景/背景判定
+- 再利用 `refine_foreground` 改善前景颜色和合成效果
+
+但它的限制也很明确：
+
+- `refine_foreground` 用到的是 hard alpha
+- 边缘渐变信息已经丢失
+- 所以它无法完全发挥 soft alpha matting 的优势
+
+## 7. 最合理的工程建议
+
+### 方案 A. 保持现状
+
+管线：
+
+```text
+pred (soft prob) -> RankSEG -> binary mask -> refine_foreground
+```
+
+优点：
+
+- 实现简单
+- 区域判定更干净
+
+缺点：
+
+- 边缘容易变硬
+- 发丝、半透明细节可能不如原始 soft mask
+
+适合：
+
+- 更重视区域分割是否准确
+- 更像“分割后抠图”
+
+### 方案 B. 原始 soft mask 直接抠图
+
+管线：
+
+```text
+pred (soft prob) -> refine_foreground
+```
+
+优点：
+
+- 边缘更自然
+- 更像 matting
+
+缺点：
+
+- 区域级误检会直接进入最终结果
+
+适合：
+
+- 更重视最终视觉观感
+
+### 方案 C. 推荐的混合方案
+
+管线：
+
+```text
+pred (soft prob) -> RankSEG(binary support)
+                 -> hybrid_alpha = pred * rankseg_mask
+                 -> refine_foreground(hybrid_alpha)
+```
+
+或更保守地：
+
+```python
+hybrid_alpha = torch.where(rankseg_mask > 0, pred, torch.zeros_like(pred))
+```
+
+这个思路的含义是：
+
+- RankSEG 负责“哪些区域允许成为前景”
+- 原始 `pred` 负责“这些前景区域内部的透明度变化”
+
+优点：
+
+- 同时利用 RankSEG 的区域约束能力
+- 保留原始 soft mask 的边缘渐变
+
+这是当前代码架构下最有希望同时兼顾 Dice/IoU 与视觉质量的方案。
+
+## 8. 评估建议
+
+如果你的目标是论文式或工程式对比，建议把评估拆成两组，不要混为一谈。
+
+### 8.1 分割质量评估
+
+比较对象：
+
+- 原始 `pred` 阈值化后的 mask
+- RankSEG 输出 mask
+- 混合方案的最终 alpha 再阈值化的 mask
+
+指标：
+
+- IoU
+- Dice
+- Pixel Accuracy
+
+注意：
+
+- `refine_foreground` 不应作为 IoU/Dice 的评估对象
+- 因为它输出的是前景图像，不是 mask 优化本身
+
+### 8.2 抠图观感评估
+
+比较对象：
+
+- raw soft mask + refine
+- rankseg binary mask + refine
+- hybrid alpha + refine
+
+关注点：
+
+- 发丝
+- 透明边缘
+- 白边/黑边
+- 前景颜色污染
+
+如果有 matting 数据，可以进一步评估 alpha 或前景误差；如果没有，至少做稳定的可视化对比。
+
+## 9. 最终结论
+
+1. `refine_foreground` 同时支持 soft mask 与 binary mask，但从算法性质上更适合 soft alpha。
+2. 当前 RankSEG 版本不输出 soft mask，只输出离散预测。
+3. RankSEG 不应被简单理解成“把 0.5 换成一个更好的固定阈值”；它更接近于基于概率排序和目标指标的自适应 `top-k` 截断。
+4. 因此，“让 `refine_foreground` 也增强 RankSEG 的效果”这件事，不应期待 RankSEG 直接给 soft mask，而应考虑让 RankSEG 提供区域约束、让原始 `pred` 提供 soft alpha。
+5. 在当前工程里，最值得实验的下一步是混合方案，而不是继续追问 RankSEG 是否已有 soft output API。
+
+## 10. 参考来源
+
+### 本地代码
+
+- [app.py](/Users/lev1s/Documents/BiRefNet_demo/app.py)
+- [rankseg/_rankseg.py](/Users/lev1s/Documents/BiRefNet_demo/.venv/lib/python3.12/site-packages/rankseg/_rankseg.py)
+- [rankseg/_rankseg_algo.py](/Users/lev1s/Documents/BiRefNet_demo/.venv/lib/python3.12/site-packages/rankseg/_rankseg_algo.py)
+
+### 外部资料
+
+- RankSEG getting started: [GitHub](https://github.com/rankseg/rankseg/blob/main/doc/source/getting_started.md)
+- RankSEG auto API: [GitHub](https://github.com/rankseg/rankseg/blob/main/doc/source/autoapi/rankseg/rankseg/index.md)
+- BiRefNet repository: [GitHub](https://github.com/ZhengPeng7/BiRefNet)
+- Approximate Fast Foreground Colour Estimation repository: [GitHub](https://github.com/Photoroom/fast-foreground-estimation)
+- Approximate Fast Foreground Colour Estimation talk page: [IEEE SPS Resource Center](https://resourcecenter.ieee.org/conferences/icip-2021/spsicip21vid215)
+- Fast Multi-Level Foreground Estimation reference entry: [DBLP](https://dblp.org/rec/conf/icpr/GermerU0H20)
+- PyMatting foreground estimation docs: [PyMatting](https://pymatting.github.io/)