Metadata-Version: 2.4
Name: cruiseplan
Version: 0.2.0
Summary: Oceanographic Research Cruise Planning System
Maintainer-email: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Eleanor Frajka-Williams
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: documentation, https://github.com/ocean-uhh/cruiseplan
Project-URL: homepage, https://github.com/ocean-uhh/cruiseplan
Project-URL: repository, https://github.com/ocean-uhh/cruiseplan
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3.0
Requires-Dist: xarray>=2023.12.0
Requires-Dist: netCDF4>=1.5.8
Requires-Dist: scipy>=1.7.0
Requires-Dist: requests>=2.25.0
Requires-Dist: pangaeapy>=1.0.7
Requires-Dist: pydantic>=2.0.0
Requires-Dist: ruamel.yaml>=0.18.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: folium
Requires-Dist: branca
Requires-Dist: tqdm>=4.65
Requires-Dist: jinja2
Provides-Extra: dev
Requires-Dist: jupyterlab>=4.0; extra == "dev"
Requires-Dist: nbconvert>=7.8; extra == "dev"
Requires-Dist: myst-nb>=1.0; extra == "dev"
Requires-Dist: nbsphinx>=0.9; extra == "dev"
Requires-Dist: sphinx>=7.2; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "dev"
Requires-Dist: pypandoc>=1.11; extra == "dev"
Requires-Dist: myst-parser>=2.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: mock; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: license-file

# CruisePlan

> 🌊 **Comprehensive Oceanographic Research Cruise Planning System** — Streamlining the complex process of designing, optimizing, and planning oceanographic research expeditions.

[![Tests](https://github.com/ocean-uhh/cruiseplan/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/cruiseplan/actions/workflows/tests.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-sphinx-blue)](https://ocean-uhh.github.io/cruiseplan/)

## Statement of Need

**The Challenge:** Oceanographic cruise planning involves precise timing and geographic calculations which may need frequent updating. Researchers currently face:

- **Fragmented Tools**: Scattered spreadsheets, manual calculations, and discipline-specific software
- **Time-Intensive Processes**: Semi-manual station planning, timing calculations, and proposal formatting  
- **Error-Prone Workflows**: Manual depth lookups, coordinate formatting, and schedule validation
- **Limited Historical Context**: Difficulty incorporating past cruise data and lessons learned

**The Solution:** CruisePlan provides an integrated, semi-automated, flexible solution that transforms drafting of cruise plans into an efficient workflow.

## Target Audience

**Primary Users:**
- **🔬 Oceanographic Researchers**: Principal investigators designing research expeditions
- **📊 Students**: Graduate students learning cruise planning methodology
- **📋 Proposal Writers**: Scientists preparing funding proposals with detailed cruise plans

**Research Domains:**
The primary development of CruisePlan is for physical oceanographers, with CTD stations, mooring deployments and glider operations as default.  However, it is possible to incorporate any type of point, line or area operation of a ship with a specified manual duration based on your own experience.

CruisePlan transforms complex cruise planning from a weeks-long manual process into a structured, validated workflow that produces proposal-ready documentation with some checks on operational feasibility.

**Important - Version 0.2.0 Release:** This release includes breaking changes to depth field semantics. See our [Development Roadmap](https://ocean-uhh.github.io/cruiseplan/roadmap.html) for migration guidance.

**Disclaimer:** This software is provided "as is" without warranty of any kind. Users are responsible for validating all calculations, timing estimates, and operational feasibility for their specific cruise requirements. Always consult with marine operations staff and verify all outputs before finalizing cruise plans.

📘 Full documentation available at:  
👉 https://ocean-uhh.github.io/cruiseplan/

---

## 🚀 What's Included

- ✅ **Interactive station planning**: Click-to-place stations on bathymetric maps with real-time depth feedback
- 📓 **PANGAEA integration**: Browse and incorporate past cruise data for context
- 📄 **Multi-format outputs**: Generate NetCDF, LaTeX reports, PNG maps, KML files, and CSV data
- 🔍 **Cruise validation**: Automated checking of cruise configurations and operational feasibility
- 🎨 **Documentation**: Sphinx-based docs with API references and usage guides
- 📦 **Modern Python packaging**: Complete with testing, linting, and CI/CD workflows
- 🧾 **Scientific citation support**: CITATION.cff for academic attribution

---

## Project structure

For a detailed breakdown of the package architecture and module descriptions, see the [Project Structure Documentation](https://ocean-uhh.github.io/cruiseplan/project_structure.html).

```text
cruiseplan/
├── .github/
│   └── workflows/              # GitHub Actions for tests, docs, PyPI
├── docs/                       # Sphinx-based documentation
│   ├── source/                 # reStructuredText + MyST Markdown + _static
│   └── Makefile                # for building HTML docs
├── notebooks/                  # Example notebooks and demos
├── cruiseplan/                 # Main Python package
│   ├── cli/                    # Command-line interface modules
│   ├── core/                   # Core cruise planning logic
│   ├── calculators/            # Distance, duration, routing calculators
│   ├── data/                   # Bathymetry and PANGAEA data handling
│   ├── interactive/            # Interactive station picking tools
│   ├── output/                 # Multi-format output generators
│   └── utils/                  # Utilities and coordinate handling
├── tests/                      # Comprehensive pytest test suite
├── data/                       # Bathymetry datasets
├── .gitignore
├── .pre-commit-config.yaml
├── CITATION.cff                # Citation file for academic use
├── CONTRIBUTING.md             # Contribution guidelines
├── LICENSE                     # MIT license
├── README.md
├── pyproject.toml              # Modern packaging config
├── requirements.txt            # Core package dependencies
├── requirements-dev.txt        # Development and testing tools
├── environment.yml             # Conda environment specification
└── PROJECT_SPECS.md            # Development roadmap and specifications
```

---

## 🔧 Installation

### Option 1: Install from PyPI (Most Users)

For general use, install the latest stable release from PyPI. **Note**: CruisePlan is in active development (0.x versions) with occasional breaking changes.

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install CruisePlan
pip install cruiseplan
```

### Option 2: Install Latest from GitHub

For the latest features and bug fixes:

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install directly from GitHub
pip install git+https://github.com/ocean-uhh/cruiseplan.git
```

### Option 3: Development Installation

For development or contributing to CruisePlan:

```bash
# Clone the repository
git clone https://github.com/ocean-uhh/cruiseplan.git
cd cruiseplan

# Option A: Using conda/mamba
conda env create -f environment.yml
conda activate cruiseplan
pip install -e ".[dev]"

# Option B: Using pip with virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

**Dependencies**: Core packages are listed in `requirements.txt`, development tools in `requirements-dev.txt`. The conda `environment.yml` loads from these files automatically.

To run tests:

```bash
pytest tests/
```

To build the documentation locally:

```bash
cd docs
make html
```

---

## 📚 Learn More

- [Installation Guide](https://ocean-uhh.github.io/cruiseplan/installation.html)
- [Usage Guide](https://ocean-uhh.github.io/cruiseplan/usage.html)
- [API Reference](https://ocean-uhh.github.io/cruiseplan/api/modules.html)
- [Development Roadmap](https://ocean-uhh.github.io/cruiseplan/roadmap.html)
- [Contributing Guidelines](https://github.com/ocean-uhh/cruiseplan/blob/main/CONTRIBUTING.md)

---

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guidelines](https://github.com/ocean-uhh/cruiseplan/blob/main/CONTRIBUTING.md) for details on how to get started.

For information about planned improvements and development priorities, see our [Development Roadmap](https://ocean-uhh.github.io/cruiseplan/roadmap.html).

---

## 🙏 Acknowledgments & Citation

The original timing algorithms were developed by [Yves Sorge](https://orcid.org/0009-0007-0043-9207) and [Sunke Trace-Kleeberg](https://orcid.org/0000-0002-5980-2492).  CruisePlan software development and maintenance by [Yves Sorge](https://orcid.org/0009-0007-0043-9207) and [Eleanor Frajka-Williams](https://orcid.org/0000-0001-8773-7838).

If you use CruisePlan in your research, please cite it using the information in [CITATION.cff](CITATION.cff).

