faultSeg

Files (1)

• SKILL.md

SKILL.md (first lines)

# FaultSeg3D Repository Analysis

## Purpose

**FaultSeg3D** is a Keras/TensorFlow implementation of a 3D convolutional neural network for **automatic fault segmentation in 3D seismic volumes**. Given a 3D seismic amplitude cube, the model outputs a corresponding fault-probability volume in which high values indicate likely fault surfaces.

The key innovation is that the CNN is trained entirely on **synthetic** seismic/fault pairs (200 pairs), yet generalises well to real field datasets (Netherlands F3, Clyde, Costa Rica, Campos, Kerry-3D, Opunake-3D). This eliminates the need for hand-labelled field data.

Published as:
> Wu et al. (2019). *FaultSeg3D: using synthetic datasets to train an end-to-end convolutional neural network for 3D seismic fault segmentation*. **GEOPHYSICS**, 84(3), IM35–IM45.

---


## Boglodite MCP execution

For routine F3 prediction, prefer the project MCP tool `run_faultseg(slice_type, coordinate)` rather than rebuilding the repository command sequence. The MCP tool delegates to the validated Boglodite adapter in `sandbox/FaultSeg/predict_only_fault.py`, which preserves the axis ordering, normalization, padding, trained model, and output conventions described in this skill. Use direct repository execution for training, research inspection, or unsupported custom workflows.

## Verified Repository Summary

| Item | Detail |
|---|---|
| Language | Python 3 |
| Framework | Keras (TensorFlow 1.x backend) |
| Input format | Raw binary `.dat` files, `float32`, C order |
| Training volume size | 128 × 128 × 128 voxels |
| Network | Simplified 3D U-Net (4 levels, 16–128 filters) |
| Loss | `binary_crossentropy` (Adam, lr=1e-4) |
| Training epochs | 100 |
| Training samples | 200 synthetic pairs |
| Validation samples | 20 synthetic pairs |
| License | CC BY-NC 4.0 (non-commercial research only) |

---

## Repository Walkthrough

### Top-level structure

```
faultSeg/
├── train.py          # Training entrypoint
├── apply.py          # Inference/evaluation script
├── unet3.py          # 3D U-Net model definition + custom loss
├── utils.py          # Keras DataGenerator for .dat files
├── predNew.ipynb     # Newer interactive prediction notebook
├── prediction.ipynb  # Original prediction notebook
├── cpurun            # Shell wrapper: forces CPU (CUDA_VISIBLE_DEVICES='')
├── model/
│   └── model3.json   # Exported JSON of a trained model architecture
├── data/
│   ├── train/        # (downloaded separately) seis/ fault/
│   ├── validation/   # (downloaded separately) seis/ fault/
│   └── prediction/   # Field data for inference
├── log/              # TensorBoard log directory
└── results/          # Result images for the README
```

---

### `unet3.py` — 3D U-Net model

**Role:** Defines the CNN architecture and the optional balanced cross-entropy loss.

#### `unet(pretrained_weights=None, input_size=(None, None, None, 1))`

Builds and returns a simplified 3D U-Net Keras model. The architecture:

**Encoder (contracting path):**
| Block | Layers | Output filters |
|---|---|---|
| Block 1 | Conv3D(16) × 2, ReLU, same padding | 16 |
| Pool 1 | MaxPooling3D(2,2,2) | — |
| Block 2 | Conv3D(32) × 2, ReLU, same padding | 32 |
| Pool 2 | MaxPooling3D(2,2,2) | — |
| Block 3 | Conv3D(64) × 2, ReLU, same padding | 64 |
| Pool 3 | MaxPooling3D(2,2,2) | — |

**Bottleneck:**
| Block 4 | Conv3D(128) × 2, ReLU | 128 |

**Decoder (expanding path) — skip connections via concatenate:**
| Block 5 | UpSampling3D(2) + skip(conv3) → Conv3D(64) × 2 | 64 |
| Block 6 | UpSampling3D(2) + skip(conv2) → Conv3D(32) × 2 | 32 |
| Block 7 | UpSampling3D(2) + skip(conv1) → Conv3D(16) × 2 | 16 |

**Output:**
| Block 8 | Conv3D(1, kernel=1×1×1, sigmoid) | 1 (fault probability) |

Accepts volumes of arbitrary spatial size (all-`None` input shape), enabling inference on field datasets larger than 128³. Returns a `keras.Model`.

#### `cross_entropy_balanced(y_true, y_pred)`

A class-balanced binary cross-entropy loss that dynamically weights positive (fault) and negative (non-fault) voxels inversely proportional to their counts:

```
beta    = count_neg / (count_neg + count_pos)
weight  = beta / (1 - beta)   # up-weights scarce fault voxels
cost    = weighted_cross_entropy(logits, targets, pos_weight=weight) * (1 - beta)
```

Returns 0 if no fault voxels are present (avoids division-by-zero). This loss is defined here but **not used in `train.py`** (which uses plain `'binary_crossentropy'`). It is required when loading checkpoints saved with this custom loss.

#### `_to_tensor(x, dtype)`

Utility: converts a numpy array or Python scalar to a TensorFlow tensor of the specified dtype.

---

### `utils.py` — DataGenerator

**Role:** A `keras.utils.Sequence` subclass that streams training/validation batches from `.dat` files on disk. Supports shuffling and on-the-fly data augmentation.

#### `DataGenerator.__init__(dpath, fpath, data_IDs, batch_size, dim, n_channels, shuffle)`

Stores paths, IDs, and hyper-parameters, then calls `on_epoch_end()` to initialise the index array.

#### `DataGenerator.__len__()`

From yohanesnuwara/boglodite, MIT.

More from yohanesnuwara/boglodite