README.md

---
tags:
- seismic
- first-break-picking
- segmentation
- pytorch
library_name: pytorch
---

# First-Break Picking Model Release

This directory is a compact release package for first-break-picking model
weights. It keeps only the best checkpoint and the exact training config for
each run.

## Current remote inventory

The remote repository was checked on 2026-08-17. It contains 150 runs and
302 files, including the two root files `README.md` and `.gitattributes`.
Each run contains exactly one `config.yaml` and one
`checkpoints/best.pt`. The current payload is approximately 36.1 GB.

| Directory | Meaning | Runs |
| --- | --- | ---: |
| `first_break_picking/` | Multi-dataset first-break-picking model runs | 21 |
| `first_break_picking_single_dataset_grouped/by_dataset/` | Grouped single-dataset first-break-picking model runs | 84 |
| `first_break_picking_plus/` | Plus multi-dataset runs | 9 |
| `first_break_picking_single_dataset_plus/by_dataset/` | Plus single-dataset runs | 36 |

The repository covers standard, DSU-Net, plus, HUNet, STUNet, and related
first-break-picking model configurations across the four SEG-Y datasets.

The release does not include intermediate `epoch_*.pt` checkpoints, logs,
metric CSV files, plots, visualizations, or inference SEG-Y files.

## Directory Layout

```text
first_break_picking_hf_release/
  README.md
  first_break_picking/
    first_break_pick_<model>_geomseg_seed<seed>/
      config.yaml
      checkpoints/
        best.pt
  first_break_picking_single_dataset_grouped/
    by_dataset/
      <dataset>/
        <model>/
          seed<seed>/
            config.yaml
            checkpoints/
              best.pt
  first_break_picking_plus/
    first_break_pick_<model>_geomseg_seed<seed>/
      config.yaml
      checkpoints/
        best.pt
  first_break_picking_single_dataset_plus/
    by_dataset/
      <dataset>/
        <model>/
          seed<seed>/
            config.yaml
            checkpoints/
              best.pt
```

The multi-dataset runs use:

```text
models: unet, res_unet, atten_unet, dncnn_seg, dsu_net
seeds: 42, 43, 44
```

The single-dataset runs use:

```text
datasets: brunswick_valid, dongbei, halfmile_valid, lalor_valid
models: unet, res_unet, atten_unet, dncnn_seg, dsu_net
seeds: 42, 43, 44
```

The repository also contains `hunet` and `stunet` experiments. The `plus`
directories are a separate release family for
UNet, ResUNet, and Attention UNet; `plus` is not a model name.

## Task Definition

The benchmark treats first-break picking as binary step-mask segmentation.

- Input: single-channel SEG-Y amplitude patches.
- Label: binary step mask, with 0 before the first break and 1 from the
  first-break sample onward.
- Prediction: single-channel logits with the same spatial shape as the mask.
- Pick extraction: the first time index where `sigmoid(logit) >= 0.5`.

## Dataset Configuration

All configs point to:

```text
data.root: /home/dataset-local/dataset/first_break_picking/segy_with_masks
data.data_dir: data
data.label_dir: label
```

The available SEG-Y input files are:

```text
Brunswick_valid.sgy
Dongbei.segy
Halfmile_valid.sgy
Lalor_valid.sgy
```

For multi-dataset runs, `data.files: null`, so all SEG-Y pairs under `data/`
are used. For single-dataset runs, `data.files` contains exactly one input
SEG-Y filename.

Common data parameters:

| Parameter | Value |
| --- | --- |
| `label_threshold` | `0.5` |
| `prediction_threshold` | `0.5` |
| `validate_labels` | `true` |
| `label_check_traces` | `2048` |
| `max_patches_per_split` | `null` |
| `split.train` | `0.8` |
| `split.val` | `0.1` |
| `split.test` | `0.1` |
| `split.shuffle_ffids` | `true` |

Gather segmentation parameters:

| Parameter | Value |
| --- | --- |
| `gather_segment.enabled` | `true` |
| `gather_segment.line_id_header` | `INLINE_3D` |
| `gather_segment.infer_line_from_geometry` | `true` |
| `gather_segment.distance_floor` | `1000.0` |
| `gather_segment.median_multiplier` | `5.0` |

Patch and loader parameters:

| Parameter | Multi-dataset | Single-dataset |
| --- | ---: | ---: |
| `patch.trace` | `128` | `128` |
| `patch.time` | `512` | `512` |
| `patch.trace_stride` | `64` | `64` |
| `patch.time_stride` | `256` | `256` |
| `loader.batch_size` | `64` | `64` |
| `loader.num_workers` | `4` | `1` |
| `loader.pin_memory` | `true` | `true` |

## Preprocessing

| Parameter | Value |
| --- | --- |
| `normalize_mode` | `max_abs` |
| `normalize_scope` | `gather` |
| `clip_percentile` | `99.5` |
| `normalize_eps` | `1.0e-6` |

Only input amplitudes are normalized. Labels remain binary segmentation
targets; invalid or padded areas are ignored by the loss and metrics in the
training code.

## Models

| Model | Parameters |
| --- | --- |
| `unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `res_unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `atten_unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `dncnn_seg` | `in_channels=1`, `out_channels=1`, `depth=17`, `base_channels=64`, `kernel_size=3` |

## Training Parameters

| Parameter | Value |
| --- | --- |
| `train.epochs` | `20` |
| `train.grad_clip` | `1.0` |
| `train.log_interval` | `20` |
| `train.eval_interval` | `1` |
| `train.ckpt_interval` | `1` |
| `train.vis_interval` | `1` |
| `train.resume` | `null` |
| `optimizer` | `adamw` |
| `optimizer.lr` | `1.0e-4` |
| `optimizer.weight_decay` | `1.0e-5` |
| `scheduler` | `cosine` |
| `scheduler.min_lr` | `1.0e-6` |

Loss:

```text
type: bce_dice
bce_weight: 0.5
dice_weight: 0.5
smooth: 1.0
pos_weight: null
```

Metrics:

```text
dice
iou
f1
HitRate1px
HitRate3px
HitRate5px
HitRate7px
HitRate9px
MeanAbsoluteError
RootMeanSquaredError
MeanBiasError
GatherCoverage
```

All metric thresholds are `0.5`.

## Loading A Checkpoint

Use the matching `config.yaml` next to each `best.pt` to reconstruct the model
and preprocessing settings.

```python
import torch

checkpoint_path = "first_break_picking/first_break_pick_unet_geomseg_seed42/checkpoints/best.pt"
checkpoint = torch.load(checkpoint_path, map_location="cpu")
print(checkpoint.keys())
```

The `experiment.output_dir` values inside `config.yaml` are the original
training output paths. They are preserved for reproducibility and do not need
to match this release directory.

## Release and upload notes

The model repository publishes only `config.yaml` and `checkpoints/best.pt`
for each run. The raw SEG-Y dataset should be uploaded separately because it
is much larger and has a different structure:

```text
segy_with_masks/
  data/
  label/
```

The local training result directories contain epoch checkpoints, logs, plots,
metrics, and inference files. Those files are intentionally excluded from
this compact model release. The exact preprocessing and training settings are
preserved in each run config.yaml.

---

# 初至拾取 Hugging Face 发布包

该目录是初至拾取模型权重的精简发布包。每一次实验只保留最优模型
checkpoint 和对应的完整训练配置。

## 当前远端内容

截至 2026-08-17，远端共有 150 组实验、302 个文件，发布包大小约
36.1 GB。每组实验严格只包含一个 `config.yaml` 和一个
`checkpoints/best.pt`。

| 目录 | 含义 | 运行数量 |
| --- | --- | ---: |
| `first_break_picking/` | 多数据联合训练模型结果 | 21 |
| `first_break_picking_single_dataset_grouped/by_dataset/` | 按数据集分组的单数据集模型结果 | 84 |
| `first_break_picking_plus/` | plus 多数据联合训练结果 | 9 |
| `first_break_picking_single_dataset_plus/by_dataset/` | plus 单数据集结果 | 36 |

仓库覆盖标准模型、DSU-Net、plus、HUNet、STUNet 等初至拾取模型配置，
并包含四个 SEG-Y 数据集上的联合训练和单数据集训练结果。

## 目录结构

```text
first_break_picking_hf_release/
  README.md
  first_break_picking/
    first_break_pick_<model>_geomseg_seed<seed>/
      config.yaml
      checkpoints/
        best.pt
  first_break_picking_single_dataset_grouped/
    by_dataset/
      <dataset>/
        <model>/
          seed<seed>/
            config.yaml
            checkpoints/
              best.pt
  first_break_picking_plus/
    first_break_pick_<model>_geomseg_seed<seed>/
      config.yaml
      checkpoints/
        best.pt
  first_break_picking_single_dataset_plus/
    by_dataset/
      <dataset>/
        <model>/
          seed<seed>/
            config.yaml
            checkpoints/
              best.pt
```

联合训练实验包含：

```text
模型: unet, res_unet, atten_unet, dncnn_seg, dsu_net
随机种子: 42, 43, 44
```

单数据集训练实验包含：

```text
数据集: brunswick_valid, dongbei, halfmile_valid, lalor_valid
模型: unet, res_unet, atten_unet, dncnn_seg, dsu_net
随机种子: 42, 43, 44
```

## 任务定义

该 benchmark 将初至拾取建模为二值 step-mask 分割任务。

- 输入：单通道 SEG-Y 振幅 patch。
- 标签：二值 step mask，初至之前为 0，从初至采样点开始为 1。
- 预测：与标签空间尺寸相同的单通道 logits。
- 拾取点提取：取 `sigmoid(logit) >= 0.5` 的第一个时间采样点作为初至位置。

## 数据配置

所有配置文件都指向：

```text
data.root: /home/dataset-local/dataset/first_break_picking/segy_with_masks
data.data_dir: data
data.label_dir: label
```

可用的 SEG-Y 输入文件为：

```text
Brunswick_valid.sgy
Dongbei.segy
Halfmile_valid.sgy
Lalor_valid.sgy
```

联合训练实验中，`data.files: null`，表示使用 `data/` 下所有 SEG-Y
数据对。单数据集实验中，`data.files` 只包含一个输入 SEG-Y 文件名。

通用数据参数：

| 参数 | 取值 |
| --- | --- |
| `label_threshold` | `0.5` |
| `prediction_threshold` | `0.5` |
| `validate_labels` | `true` |
| `label_check_traces` | `2048` |
| `max_patches_per_split` | `null` |
| `split.train` | `0.8` |
| `split.val` | `0.1` |
| `split.test` | `0.1` |
| `split.shuffle_ffids` | `true` |

炮集与接收线切分参数：

| 参数 | 取值 |
| --- | --- |
| `gather_segment.enabled` | `true` |
| `gather_segment.line_id_header` | `INLINE_3D` |
| `gather_segment.infer_line_from_geometry` | `true` |
| `gather_segment.distance_floor` | `1000.0` |
| `gather_segment.median_multiplier` | `5.0` |

patch 与 DataLoader 参数：

| 参数 | 联合训练 | 单数据集训练 |
| --- | ---: | ---: |
| `patch.trace` | `128` | `128` |
| `patch.time` | `512` | `512` |
| `patch.trace_stride` | `64` | `64` |
| `patch.time_stride` | `256` | `256` |
| `loader.batch_size` | `64` | `64` |
| `loader.num_workers` | `4` | `1` |
| `loader.pin_memory` | `true` | `true` |

## 预处理

| 参数 | 取值 |
| --- | --- |
| `normalize_mode` | `max_abs` |
| `normalize_scope` | `gather` |
| `clip_percentile` | `99.5` |
| `normalize_eps` | `1.0e-6` |

只对输入振幅做归一化。标签保持二值分割目标；无效区域或 padding 区域在训练代码中会被 loss 和 metrics 忽略。

## 模型

| 模型 | 参数 |
| --- | --- |
| `unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `res_unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `atten_unet` | `in_channels=1`, `out_channels=1`, `base_channels=32`, `depth=4` |
| `dncnn_seg` | `in_channels=1`, `out_channels=1`, `depth=17`, `base_channels=64`, `kernel_size=3` |

## 训练参数

| 参数 | 取值 |
| --- | --- |
| `train.epochs` | `20` |
| `train.grad_clip` | `1.0` |
| `train.log_interval` | `20` |
| `train.eval_interval` | `1` |
| `train.ckpt_interval` | `1` |
| `train.vis_interval` | `1` |
| `train.resume` | `null` |
| `optimizer` | `adamw` |
| `optimizer.lr` | `1.0e-4` |
| `optimizer.weight_decay` | `1.0e-5` |
| `scheduler` | `cosine` |
| `scheduler.min_lr` | `1.0e-6` |

损失函数：

```text
type: bce_dice
bce_weight: 0.5
dice_weight: 0.5
smooth: 1.0
pos_weight: null
```

评价指标：

```text
dice
iou
f1
HitRate1px
HitRate3px
HitRate5px
HitRate7px
HitRate9px
MeanAbsoluteError
RootMeanSquaredError
MeanBiasError
GatherCoverage
```

所有指标阈值均为 `0.5`。

## 加载 Checkpoint

使用每个 `best.pt` 旁边对应的 `config.yaml` 来重建模型和预处理设置。

```python
import torch

checkpoint_path = "first_break_picking/first_break_pick_unet_geomseg_seed42/checkpoints/best.pt"
checkpoint = torch.load(checkpoint_path, map_location="cpu")
print(checkpoint.keys())
```

`config.yaml` 中的 `experiment.output_dir` 是原始训练时的输出路径。这里保留这些路径是为了可复现性，不要求它们与当前发布目录一致。

## Hugging Face 上传说明

该目录适合作为模型权重发布包上传。原始 SEG-Y 数据集体积更大，结构也不同，建议单独上传：

```text
segy_with_masks/
  data/
  label/
```

当前远端已经完成上传。每组只发布 `config.yaml` 和
`checkpoints/best.pt`；本地训练目录中的 epoch checkpoint、日志、指标、
可视化和推理 SEG-Y 均不属于模型发布包。