OWI-metadatabase SDK

Core SDK for OWI-Lab metadatabase geometry and location workflows, with optional extras for soil, results, and SHM.

A modern Python namespace package providing tools for working with offshore wind turbine geometry and location data from the OWI-metadatabase. The core package stays focused on shared APIs and data access, while optional extras install the soil, results, and structural health monitoring extensions into the same owi.metadatabase namespace.

📚 Read the Documentation

Features

• Geometry Module: Process offshore wind turbine geometries, components, and structures
• Locations Module: Handle geographic location and site data
• API Integration: Seamless connection to OWI-metadatabase API
• Extensible: Namespace package architecture supports deployed domain extensions
  • owi-metadatabase-soil
  • owi-metadatabase-results
  • owi-metadatabase-shm
  • owi-metadatabase-ext-sdk-tpl for scaffolding new extensions
  • owi-metadatabase-fatigue (planned)

Installation

Quick Install

Using pip:

pip install owi-metadatabase

Using uv (recommended for development):

uv pip install owi-metadatabase

Install optional extras

Using pip:

pip install "owi-metadatabase[soil]"
pip install "owi-metadatabase[results]"
pip install "owi-metadatabase[shm]"

Using uv:

uv pip install "owi-metadatabase[soil]"
uv pip install "owi-metadatabase[results]"
uv pip install "owi-metadatabase[shm]"

Install multiple extras together when you need more than one extension:

pip install "owi-metadatabase[soil,results,shm]"

In zsh, keep extras in quotes because [ and ] are treated as glob characters.

Development Installation

For contributing to the package:

# Clone the repository
git clone https://github.com/OWI-Lab/owi-metadatabase-sdk.git
cd owi-metadatabase-sdk

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Quick Start

from owi.metadatabase.geometry.io import GeometryAPI
from owi.metadatabase.locations.io import LocationsAPI

# Initialize API clients
geometry_api = GeometryAPI(API_key='your-api-key')
locations_api = LocationsAPI(API_key='your-api-key')

# Fetch turbine geometry
turbine = geometry_api.get_geometry_turbine(turbine_id=123)

# Get location data
location = locations_api.get_location(location_id=456)

See the How To Guide for more examples.

🔄 Migration from v0.10.x

If you're migrating from pwimetadatabase-preprocessor v0.10.x, see our Migration Guide.

Key Changes:

• Package name: owi-metadatabase-sdk → owi-metadatabase
• Import path: owimetadatabase_preprocessor.* → owi.metadatabase.*
• Removed modules: fatigue, soil, and results (available as package extensions)
• Extension extras now available from the core package: soil, results, and shm

Development

This project uses modern Python tooling:

• uv: Fast Python package manager
• invoke: Task automation
• ruff: Linting and formatting
• pytest: Testing with extensive doctest coverage
• Zensical: Documentation

Common Tasks

# Run tests and serve coverage report
uv run inv test

# Build documentation
uv run inv docs.build

# Serve documentation locally
uv run inv docs.serve

# Run code quality checks
uv run inv quality

Project Structure

src/owi/metadatabase/
├── __init__.py          # Main package entry point
├── geometry/            # Geometry data processing
│   ├── io.py           # GeometryAPI
│   ├── processing.py   # OWT, OWTs classes
│   └── structures.py   # Data structures
├── locations/           # Location data handling
│   └── io.py           # LocationsAPI
└── _utils/             # Internal utilities
    ├── exceptions.py   # Custom exceptions
    └── utils.py        # Helper functions

Extensibility

This package uses PEP 420 namespace packages, allowing modular extensions. Installed packages can extend the owi.metadatabase namespace side by side:

• owi-metadatabase-soil: Soil data processing
• owi-metadatabase-results: Results querying, typed models, and plotting helpers
• owi-metadatabase-shm: Structural health monitoring queries, typed records, and upload workflows
• owi-metadatabase-fatigue (planned): Fatigue analysis tools
• Your extension: Create custom extensions using the namespace

All extensions work seamlessly together:

from owi.metadatabase.geometry.io import GeometryAPI
from owi.metadatabase.results import ResultsAPI
from owi.metadatabase.shm import ShmAPI
from owi.metadatabase.soil import SoilAPI

Documentation

• Core SDK docs: Geometry, locations, and shared architecture
• How-to guides: Installation, authentication, and query recipes
• Results extension docs: Results APIs, models, services, and notebooks
• SHM extension docs: Sensor and signal retrieval, typed services, and upload workflows
• Soil extension docs: Soil APIs, processing, and visualization

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests and documentation
4. Run quality checks: uv run invoke quality.all
5. Run tests: uv run invoke test.all
6. Commit your changes: git commit -m 'feat: add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

License

This package is licensed under the GNU General Public License v3.0.

👥 Authors

owi-metadatabase is developed and maintained by the team at OWI-Lab.

Core Contributors:

• Pietro D'Antuono (@pietrodantuono)
• Arsen Melnikov (@arsmlnkv)

Acknowledgements

This package was developed as part of:

• ETF Smartlife (FOD165) project
• WILLOW (EUAR157) project

Project Status

Aspect	Status
Version
Python
Tests
Coverage
Documentation
License

Related Projects

• OWI-Lab Website: Research lab website
• OWI-metadatabase: Online database

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: pietro.dantuono@vub.be

Built with ❤️ and 🧠 by OWI-Lab