facies_net

Files (1)

• SKILL.md

SKILL.md (first lines)

# facies_net Repository Analysis

## Purpose

`facies_net` is a Python library and runnable script for **seismic facies classification** using deep 3D convolutional neural networks (CNNs). It is a direct evolution of the MalenoV project by the same author (Charles Rutherford Ildstad, ConocoPhillips / University of Trondheim, 2017).

Given one or more 3D SEGY seismic cubes and either a set of annotated training-point `.pts` files (one per class) or a labelled SEGY facies cube, facies_net:

1. Reads the SEGY volumes into memory as normalised numpy arrays.
2. Generates 3D mini-cubes ("voxelets") on-the-fly using a Keras `Sequence` generator.
3. Trains a 4-layer 3D CNN (Keras/TensorFlow) to distinguish the provided facies classes.
4. Logs training to TensorBoard.
5. Classifies a user-defined sub-section of the seismic cube voxel-by-voxel.
6. Writes the resulting facies prediction back out as a SEGY, `.npy`, and `.ixz` (CSV) file.

Compared to MalenoV, key improvements include:
- **Modular, multi-file architecture** instead of a single script.
- **Keras `Sequence` generator** (proper generator-based training instead of batch loops).
- **True data augmentation** (Mirror1/2/3, Transpose, and combinations) that is wired and functional.
- **Dual training input modes**: `.pts` annotation files OR a labelled SEGY facies cube.
- **TensorBoard integration** for training monitoring.
- **Multiple pre-trained models** included in the `F3/` folder for the Dutch F3 dataset.
- **Attribution analysis** (Integrated Gradients) and **feature visualisation** scripts for model interpretability.

---

## Verified Repository Summary

| Item | Detail |
|---|---|
| Language | Python 3 |
| Entry point | `facies_net.py` |
| Module folder | `facies_net_func/` (9 Python modules) |
| Pre-trained models | `F3/` (21 × `.h5` files for Dutch F3 dataset) |
| Training annotation formats | `.pts` text files (inline, xline, time) OR labelled SEGY cube |
| License | GNU LGPL v3.0 |
| Key dependencies | `segyio`, `keras`, `tensorflow`, `numpy`, `matplotlib`, `scipy` |
| CNN architecture | 4 × `Conv3D` → `Dense(10)` → `Dense(num_classes)` → softmax |
| Default voxelet size | 61 × 61 × 61 (controlled by `cube_incr=30`) |
| Optimised for | TensorFlow 1.5.0 |

---

## Repository Walkthrough

### Top-level structure

```
facies_net.py               ← Main entry point (run this)
facies_net_func/            ← All supporting modules
    masterf.py              ← Top-level orchestrator (master function)
    segy_files.py           ← SEGY I/O (segy_reader, segy_decomp, segy_adder)
    training.py             ← Model training (train_model, adaptive_lr)
    data_cond.py            ← Data conditioning (convert, convert_segy, ex_create generator)
    modelling.py            ← CNN architecture (make_model, SpatialDropout3D)
    prediction.py           ← Batch prediction (cube_parse, predicting, makeIntermediate)
    visualize.py            ← Plotting and prediction orchestration (visualization, show_details)
    attribution.py          ← Integrated Gradients (integrated_gradients class)
    feature_vis.py          ← Feature maximisation visualisation (features, save_image)
F3/                         ← Pre-trained Keras .h5 models for Dutch F3 dataset (21 variants)
class_addresses/            ← Pre-annotated .pts files for Dutch F3 multi-facies classification
    multi_*.pts             ← 9 facies class address files
    address_maker.py        ← Utility to generate address lists from a SEGY
    pixels_to_points.py     ← Convert pixel coordinates to seismic points
    points_to_pixels.py     ← Convert seismic points to pixel coordinates
attribution_analysis.py     ← Standalone script: run Integrated Gradients on a trained model
feature_analysis.py         ← Standalone script: visualise CNN filter responses
size_check.py               ← Utility: print layer input/output shapes for a trained model
logs/                       ← TensorBoard log output directory
predictions/                ← Output directory for saved prediction files
images/                     ← Output directory for attribution/feature visualisation images
```

---

### `facies_net.py` — Main entry point

**Role:** Configure and launch training runs. Not a library — it is a run script.

The script sets up `filenames`, `cube_incr`, `train_dict`, and `pred_dict`, then calls `master()` once per augmentation variant. The default run trains on `F3_entire.segy` using `F3_facies.segy` as the labelled training cube, iterating through all 15 data augmentation combinations (baseline + 7 single + 6 double + 1 triple + 1 full).

Key configuration:
- `cube_incr = 30` → voxelet size 61×61×61
- `num_train_ex = 80000` per epoch
- `epochs = 10`, `batch_size = 32`, `val_split = 0.3`
- `data_augmentation`: list of strings from `['Mirror1', 'Mirror2', 'Mirror3', 'Transpose']`
- Training input: `'files': ['F3_facies.segy']` (single SEGY label cube mode)

---

### `facies_net_func/masterf.py` — `master()`

**Role:** Top-level orchestrator. Single public function.

```python
def master(segy_filename, cube_incr, train_dict={}, pred_dict={}, mode='full')
```

| `mode` | Action |
|---|---|
| `'train'` | Calls `segy_reader` → `train_model`, times and prints duration |
| `'predict'` | Loads pre-trained model from `pred_dict['keras_model']`, calls `visualization` |
| `'full'` | Trains then immediately predicts |

**Returns:** `{'model': trained_model, 'pred': prediction_array}`

Notable: if `'keras_model'` is present in `pred_dict`, training will **continue from that model** rather than building a new one (fine-tuning).

---

### `facies_net_func/segy_files.py` — SEGY I/O

#### `segy_reader(segy_filenames)`

**Role:** Entry point for SEGY loading. Accepts a single filename string or a list of filenames.

- Single filename: calls `segy_decomp`, adds a channel dimension → shape `(xlines, inlines, samples, 1)`.
- List of filenames: stacks multiple SEGY cubes as channels → shape `(xlines, inlines, samples, N)`.

From yohanesnuwara/boglodite, MIT.

More from yohanesnuwara/boglodite