ODSAS++ - Open Digital Shoreline Analysis System

Overview

ODSAS++ is a high-performance C++ implementation of the Open Digital Shoreline Analysis System (ODSAS), designed for comprehensive coastal change analysis and shoreline evolution studies. This advanced geospatial tool provides researchers and coastal engineers with robust capabilities for analyzing historical shoreline positions and quantifying coastal change rates.

Built upon the foundation of the original ODSAS methodology, ODSAS++ offers enhanced performance, cross-platform compatibility, and extended analytical capabilities for processing large-scale coastal datasets.

Features

📊 Comprehensive Shoreline Analysis: Calculate multiple shoreline change statistics (NSM, EPR, LRR, etc.)
🚀 High Performance: Optimized C++ implementation for large datasets
🌐 Cross-Platform: Compatible with Windows and Linux/Unix systems
📁 Multiple Data Formats: Support for GPKG vector files and CSV data
🔧 Flexible Configuration: Customizable processing parameters via INI files
📈 Statistical Analysis: Advanced coastal change rate calculations with uncertainty quantification
🗺️ Geospatial Integration: Built on GDAL/OGR for robust spatial data handling

Requirements

System Requirements

Operating System: Windows 10+ or Linux (Ubuntu 18.04+, CentOS 7+)
Memory: Minimum 4GB RAM (8GB+ recommended for large datasets)
Storage: 1GB free disk space

Software Dependencies

CMake: Version 3.12 or higher
C++ Compiler: GCC 7+ or MSVC 2019+
GDAL/OGR: Version 3.0 or higher

Installation

Using CMake (Recommended)

Clone or download the ODSAS++ source code
Navigate to the project directory

Configure the build environment:

cmake -S src -B build -DCMAKE_BUILD_TYPE=Release

Compile the application:
```
cmake --build build --config Release
```

Platform-Specific Notes

Windows

Ensure GDAL is installed and properly configured in your system PATH
Use Visual Studio 2019 or later for optimal compatibility

Linux

Install GDAL development packages:

sudo apt-get install libgdal-dev gdal-bin  # Ubuntu/Debian
sudo yum install gdal-devel                # CentOS/RHEL

Quick Start

Prepare your data:
- Baseline vector file (GPKG format)
- Historical shoreline positions (GPKG format)
- Shoreline timestamps and uncertainty data (CSV format)
Configure the analysis:
- Create or modify the initialization file (.ini)
- Set up the run data file (.dat)
Run the analysis:
```
./odsas config/your_config.ini
```

Configuration

Input Files

ODSAS++ requires three primary input files:

1. Initialization File (`.ini`)

Contains general configuration parameters for the analysis session.

2. Run Data File (`.dat`)

Specifies run-specific parameters and input file paths.

3. Data Files

Baselines: Vector GPKG file containing points along the baseline where transects will be generated
Historical Shoreline Positions: Vector GPKG file with historical shoreline geometries
Historical Shoreline Metadata: CSV file with columns:
- ID: Shoreline identifier
- Day: Date in YYYY-MM-DD format
- Hour: Time in HH:MM:SS format
- Uncertainty: Root Mean Square uncertainty in meters

Configuration Parameters

Key Settings

Profile Spacing: Distance between shore-normal profile lines
Profile Length: Seaward and landward extent of analysis profiles
Smoothing Method: Coastline smoothing algorithm options:
- Running mean
- Savitzky-Golay filter

Output Products

Vector Outputs

Shore-Normal Transects (.gpkg): Transect lines with calculated change metrics
Intersection Points (.gpkg): Point geometries with detailed crossing analysis results

Statistical Outputs

Transect Statistics (transects_stats_##.txt): Comprehensive change statistics including:
- ID_Profile: Profile identifier
- NSM: Net Shoreline Movement
- EPR: End Point Rate
- EPRunc: End Point Rate uncertainty
- SCE: Shoreline Change Envelope
- LRR: Linear Regression Rate
- LR2: Linear Regression R-squared
- WLR: Weighted Linear Regression Rate
- WR2: Weighted Linear Regression R-squared

Configuration Summary

ODSAS Input Summary (.dat): ASCII file containing complete analysis configuration details

Visualization

QGIS Integration

ODSAS++ includes professional visualization capabilities for QGIS with automated styling of coastal change results.

Automated Symbology Script

The included qgis_style_normals.py script provides:

🎨 Dynamic Color Coding: Red (erosion) → White (stable) → Green (accretion)
📏 Length Scaling: Line lengths proportional to change magnitude ⭐ NEW!
📊 Smart Classification: Statistically-driven breakpoints for meaningful visualization
🗺️ Publication Ready: Professional cartographic styling suitable for reports and papers
💾 Memory Layer Creation: Preserves original data while displaying scaled visualization

Supported Metrics

NSM: Net Shoreline Movement (total change in meters)
EPR: End Point Rate (linear change rate in m/year)
LRR: Linear Regression Rate (trend-based rate in m/year)
EPRunc: Uncertainty quantification visualization
SCE: Shoreline Change Envelope analysis

Quick Start Visualization

# In QGIS Python Console
exec(open('qgis_style_normals.py').read())
quick_style_epr()  # Instant styling with End Point Rate and length scaling

Benefits

Immediate Insights: Line length instantly shows change magnitude
Spatial Patterns: Reveal trends not obvious in tabular data
Quality Assurance: Visual validation of analysis results
Magnitude Comparison: Longer lines = larger changes, shorter lines = smaller changes
Communication: Professional figures for stakeholders and publications

For detailed instructions, see QGIS_VISUALIZATION.md.

Architecture

Program Flow

The application implements a structured analytical pipeline:

graph TD
    A[main()] --> B[CDelineation::nDoDelineation()]
    B --> C[Configuration Loading]
    C --> D[Data Input Processing]
    D --> E[Transect Generation]
    E --> F[Intersection Analysis]
    F --> G[Statistical Calculations]
    G --> H[Results Output]

Error Handling

ODSAS++ implements a comprehensive error management system:

RTN_OK: Successful operation completion
RTN_ERR_*: Specific error codes for:
- File I/O operations
- Data processing errors
- Memory allocation failures
- Geospatial data validation issues

Cross-Platform Compatibility

The system handles platform-specific requirements through:

Dynamic file path separator detection
Platform-optimized API calls
Compiler-specific optimizations
Thread-safe function implementations

Dependencies

Required Libraries

GDAL/OGR: Geospatial data abstraction library for vector and raster processing
Standard C++ Libraries: STL containers, file I/O streams, mathematical functions

Optional Libraries

Platform-specific libraries for enhanced functionality and performance optimization

Usage Examples

Moray Coastal Analysis Example

This repository includes a complete worked example analyzing the Moray Firth coastline in Scotland. The example demonstrates all key ODSAS++ capabilities using real coastal data.

Example Dataset

Location: Moray Firth, Scotland
Data: Historical shoreline positions with uncertainty quantification
Format: GeoPackage (GPKG) vector files and CSV metadata
Analysis: 378 shore-normal profiles, 21,377+ intersection measurements

Quick Start with Example Data

Navigate to project directory:
```
cd ODSAS
```
Configure input data (already provided in in/):
- Moray_HighWater_15mPoint.gpkg - Baseline shoreline points
- Moray_Processed_Output.gpkg - Historical coastline positions
- Moray_Processed_Output.csv - Temporal metadata and uncertainties
- Moray_ODSAS_InputFile.dat - Analysis configuration
Run the analysis:
```
./odsas
```
Check results in out/ directory:
- normals_Moray_Log.gpkg - Shore-normal profiles with change statistics
- point_Mcoast_Moray_Log.gpkg - Intersection points with distances
- transects_stats_Moray_Log.txt - Statistical summary
- coast_Moray_Log.gpkg - Processed coastline features

Expected Output

The analysis will generate:

378 profiles delineated from baseline to sea and land
6,784+ unique measurement points after quality control
Multiple change metrics: Net Shoreline Movement (NSM), End Point Rate (EPR), Linear Regression Rate (LRR)
Uncertainty quantification for all measurements
GPKG format outputs for seamless GIS integration

Basic Analysis

# Run analysis with default configuration
./odsas config/default.ini

Advanced Configuration

# Run with custom parameters
./odsas config/high_resolution_analysis.ini

Batch Processing

# Process multiple datasets
for config in config/*.ini; do
    ./odsas "$config"
done

Important Notes for WSL Users

If editing configuration files in Windows and running in WSL, convert line endings:

# Convert Windows line endings to Unix format
wsl -e sed -i 's/\r$//' ODSAS.ini
wsl -e sed -i 's/\r$//' in/Moray_ODSAS_InputFile.dat

Contributing

We welcome contributions to ODSAS++! Please consider:

Issues: Report bugs or request features via the issue tracker
Pull Requests: Submit improvements following our coding standards
Documentation: Help improve user guides and technical documentation

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for complete terms and conditions.

Authors

Andrés Payo - Project Lead & Principal Developer
Cristina Torrecillas Lozano - Core Developer

References

[1] Gómez-Pazo, A., et al. "ODSAS: Open Digital Shoreline Analysis System." Journal of Marine Science and Engineering 2022, 10(1), 26. https://doi.org/10.3390/jmse10010026

Name		Name	Last commit message	Last commit date
in		in
src		src
.gitignore		.gitignore
MyODSASINIfileGB.ini		MyODSASINIfileGB.ini
MyODSASInputFileTemplateGB.dat		MyODSASInputFileTemplateGB.dat
ODSAS.ini		ODSAS.ini
ODSAS_QGIS_view.png		ODSAS_QGIS_view.png
ODSAS_SBATCH.sh		ODSAS_SBATCH.sh
ODSAS_WSL_Launcher_GB.sh		ODSAS_WSL_Launcher_GB.sh
QGIS_VISUALIZATION.md		QGIS_VISUALIZATION.md
README.md		README.md
qgis_simple_style.py		qgis_simple_style.py

Latest commit

History

Folders and files

Repository files navigation