LineamentLearning

Deep Learning for Lineament Detection in Geoscience Data

Minerals exploration is becoming more difficult, particularly because most mineral deposits at the surface of the earth have been found. While there may be a lot of sensing data, there is a shortage of expertise to interpret that data. This thesis aims to bring some of the recent advances in AI to the interpretation of sensing data. Our AI model learns one-dimensional features (lineaments) from two-dimensional data (in particular, magnetics surveys, maps of gravity and digital elevation maps), which surprisingly has not had a great deal of attention (whereas getting two-dimensional or zero-dimensional features is very common). We define a convolutional neural network to predict the probability that a lineament passes through each location on the map. Then, using these probabilities, cluster analysis, and regression models, we develop a post-processing method to predict lineaments. We train and evaluate our model on large real-world datasets in BC and Australia.

🎯 Version 2.0 - What's New

This modernized version includes significant improvements:

• Modern TensorFlow 2.x/Keras: Updated from legacy Keras to TensorFlow 2.x
• Multiple Architectures: Support for RotateNet, U-Net, and ResNet architectures
• CLI Interface: User-friendly command-line tools for training and inference
• Configuration System: JSON-based configuration management
• Advanced Training: Mixed precision, early stopping, TensorBoard integration
• Better Documentation: Comprehensive guides and examples
• Type Hints: Full type annotations for better code quality
• Modular Design: Clean separation of concerns and reusable components

📋 Table of Contents

• Features
• Installation
• Quick Start
• Architecture
• Usage
• Configuration
• Examples
• Contributing
• Citation
• License

✨ Features

Core Capabilities

• Multiple Model Architectures: RotateNet (original), U-Net, ResNet
• Advanced Training: Batch normalization, dropout, early stopping
• Data Augmentation: Rotation, flipping, and more
• Mixed Precision Training: Faster training on modern GPUs
• TensorBoard Integration: Real-time training visualization
• Flexible Configuration: JSON/YAML configuration files
• CLI Tools: Easy command-line interface for all operations

Input Data Support

• Magnetic surveys
• Gravity maps
• Digital elevation models (DEM)
• Multiple geophysical layers (up to 8 layers)

Post-Processing

• DBSCAN clustering
• Line/curve fitting (linear, polynomial)
• Probability map generation
• Visualization tools
• Comprehensive statistics

See POSTPROCESSING_GUIDE.md for detailed documentation.

🚀 Installation

Prerequisites

• Python 3.8 or higher
• CUDA 11.2+ (optional, for GPU support)
• 8GB+ RAM recommended

Option 1: Install from Source (Recommended)

# Clone the repository
git clone https://github.com/RichardScottOZ/LineamentLearning.git
cd LineamentLearning

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Or install with all features
pip install -e ".[full,modern-ui,dev]"

Option 2: Install from PyPI (Coming Soon)

pip install lineament-learning

Verify Installation

python -c "import tensorflow as tf; print('TensorFlow version:', tf.__version__)"
lineament-train --help

🎮 Quick Start

Training a Model

# Train with default RotateNet architecture
lineament-train \
    --data ./Dataset/Australia/Rotations/Australia_strip.mat \
    --output ./models/my_model \
    --epochs 50 \
    --tensorboard

# Train with U-Net architecture
lineament-train \
    --data ./Dataset/Australia/Rotations/Australia_strip.mat \
    --output ./models/unet_model \
    --architecture UNet \
    --window-size 64 \
    --epochs 100

Running Inference

# Run prediction
lineament-predict \
    --model ./models/my_model/best_model.h5 \
    --data ./Dataset/test_data.mat \
    --output ./results \
    --visualize \
    --threshold 0.5

Using Python API

from config import Config
from model_modern import build_model, ModelTrainer

# Create configuration
config = Config()
config.model.architecture = 'UNet'
config.model.window_size = 64
config.model.epochs = 100

# Build and train model
model = build_model(config)
trainer = ModelTrainer(config, output_dir='./models')

# Model summary
model.summary()

🏗️ Architecture

Input Layers

We use 8 aerial/geophysical images to train this model:

Supported Model Architectures

1. RotateNet (Original)

The original architecture from the thesis with modern improvements:

• Convolutional layer (3×3 kernel, 8 filters)
• Max pooling (6×6)
• Two dense layers (300 units each)
• Sigmoid output for binary classification

2. U-Net

U-Net architecture adapted for lineament detection:

• Encoder-decoder structure with skip connections
• Better spatial context preservation
• Excellent for segmentation tasks

3. ResNet

ResNet-inspired architecture:

• Skip connections for deeper networks
• Batch normalization
• Residual blocks for better gradient flow

Training Pipeline

Input Data → Preprocessing → Data Augmentation → Model Training → 
→ Validation → Checkpoint Saving → Probability Maps → 
→ Post-processing (Clustering + Line Fitting) → Final Lineaments

📖 Usage

Configuration File

Create a config.json file:

{
    "model": {
        "architecture": "UNet",
        "window_size": 64,
        "batch_size": 32,
        "epochs": 100,
        "learning_rate": 0.001,
        "use_batch_normalization": true,
        "use_dropout": true,
        "dropout_rate": 0.3
    },
    "data": {
        "mask_threshold": 0.9,
        "train_ratio": 0.7,
        "val_ratio": 0.15,
        "test_ratio": 0.15
    },
    "inference": {
        "threshold": 0.5,
        "clustering_method": "DBSCAN",
        "line_fitting_method": "BestCurve"
    }
}

Use with CLI:

lineament-train --config config.json --data ./data/train.mat --output ./models

Python API Examples

Training with Custom Configuration

from config import Config
from model_modern import ModelTrainer

# Load or create config
config = Config.from_file('config.json')

# Initialize trainer
trainer = ModelTrainer(config, output_dir='./models')

# Train model
trainer.train(
    data_path='./data/train.mat',
    use_tensorboard=True
)

Custom Model Architecture

from tensorflow import keras
from config import Config

def create_custom_model(config):
    inputs = keras.layers.Input(
        shape=(config.model.window_size, config.model.window_size, 8)
    )
    
    # Your custom architecture here
    x = keras.layers.Conv2D(32, 3, activation='relu')(inputs)
    # ... more layers ...
    
    outputs = keras.layers.Dense(1, activation='sigmoid')(x)
    model = keras.Model(inputs, outputs)
    return model

⚙️ Configuration

Model Configuration Options

Parameter	Type	Default	Description
architecture	str	"RotateNet"	Model architecture (RotateNet, UNet, ResNet)
window_size	int	45	Input patch size
batch_size	int	32	Training batch size
epochs	int	150	Number of training epochs
learning_rate	float	0.001	Initial learning rate
use_batch_normalization	bool	true	Enable batch normalization
use_dropout	bool	true	Enable dropout regularization
dropout_rate	float	0.3	Dropout rate (0-1)
use_mixed_precision	bool	false	Enable mixed precision training
use_early_stopping	bool	true	Enable early stopping

Data Configuration Options

Parameter	Type	Default	Description
train_ratio	float	0.7	Training data ratio
val_ratio	float	0.15	Validation data ratio
test_ratio	float	0.15	Test data ratio
normalize_inputs	bool	true	Normalize input data

📊 Examples

Example Notebooks

Check the examples/ directory for Jupyter notebooks:

• 01_data_exploration.ipynb - Explore and visualize data
• 02_model_training.ipynb - Train models step-by-step
• 03_inference_visualization.ipynb - Run inference and visualize results
• 04_custom_architecture.ipynb - Create custom architectures

Legacy GUI Applet

The original TKinter-based GUI is still available:

from Demo import *
# Runs the legacy applet

🔗 Integration with Original Pipeline

The modernization maintains 100% backward compatibility while providing integration bridges.

Original Components Still Work

All original files are preserved and functional:

• MODEL.py: Original RotateNet architecture
• DATASET.py: Data loading from .mat files
• FILTER.py: Rotation filters
• Prob2Line.py: Original clustering & line fitting
• PmapViewer.py: GUI applet
• RotateLearning.py: Original training workflows
• Utility.py: Helper functions

Integration Bridge

The bridge.py module connects original and modern components:

from bridge import DatasetAdapter, LegacyTrainer
from config import Config

# Use original data loading with modern models
config = Config()
config.model.architecture = 'UNet'  # Modern architecture!

trainer = LegacyTrainer(config, 'path/to/data.mat')
history = trainer.train_simple(ratio=0.1, epochs=10)

Pipeline Coverage

• ✅ Model architectures: Enhanced (3 architectures vs 1)
• ✅ Post-processing: Enhanced (BestCurve + visualization)
• ✅ Configuration: Modernized (JSON vs global vars)
• ✅ CLI: Enhanced (5 commands vs basic argparse)
• ⚠️ Data loading: Available but needs integration for modern training
• ⚠️ Rotation filters: Available but not integrated with modern pipeline

See PIPELINE_COVERAGE.md for detailed comparison and bridge.py for integration examples.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

# Type checking
mypy .

📚 Citation

If you use this code in your research, please cite the original thesis:

@mastersthesis{aghaee2018lineament,
  title={Deep Learning for Lineament Detection in Geoscience Data},
  author={Aghaee, Amin},
  year={2018},
  school={University of British Columbia},
  url={http://hdl.handle.net/2429/68438}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors & Acknowledgments

Original Author

• Amin Aghaee - Original research and implementation

Modernization Contributors

• Version 2.0 modernization and improvements

References

• Original thesis: Deep Learning for Lineament Detection

🔮 Future Work & Roadmap

Planned Improvements

• Advanced Architectures: Attention mechanisms, Transformers
• Multi-scale Processing: Pyramid networks for multi-resolution analysis
• 3D Support: Extension to 3D geophysical data
• Active Learning: Interactive labeling and model improvement
• Cloud Deployment: Docker, Kubernetes, cloud platforms
• Mobile Deployment: TensorFlow Lite for mobile devices
• Explainability: GradCAM, attention visualization
• Ensemble Methods: Model ensembling for better predictions
• Real-time Processing: Streaming data support
• Web Dashboard: Modern React/Vue.js dashboard
• API Server: RESTful API for model serving
• Automated Hyperparameter Tuning: Optuna/Ray Tune integration

Technology Considerations (2026)

• Vision Transformers (ViT): For better long-range dependencies
• Diffusion Models: For data augmentation and generation
• Foundation Models: Leveraging pre-trained geoscience models
• Federated Learning: Privacy-preserving distributed training
• Neural Architecture Search: Automated architecture optimization
• Quantum ML: Exploring quantum computing for geoscience

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Create an issue for direct support

🔗 Related Resources

• Original Thesis
• TensorFlow Documentation
• Keras Documentation
• Deep Learning for Geoscience

---

Note: This is version 2.0 with significant modernization. For the original legacy version, see the legacy branch.