cruiseplan 0.1.0

Oceanographic Research Cruise Planning System

CruisePlan

🌊 Oceanographic Research Cruise Planning System — a software package for planning oceanographic research cruises.

CruisePlan assists oceanographers in designing optimal station layouts, calculating precise operational timings, and generating professional proposal outputs adhering to scientific standards like CF conventions.

📘 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, HTML 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

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

---

🔧 Quickstart

Install CruisePlan in development mode:

git clone https://github.com/ocean-uhh/cruiseplan.git
cd cruiseplan

# Option A: Using conda/mamba (recommended)
conda env create -f environment.yml
conda activate cruiseplan
pip install -e .

# Option B: Using pip
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -e .

To run tests:

pytest

To build the documentation locally:

cd docs
make html

---

📚 Learn More

• Installation Guide
• Usage Guide
• API Reference
• Development Roadmap
• Contributing Guidelines

---

🤝 Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on how to get started.

For information about planned improvements and the development roadmap, see PROJECT_SPECS.md.

---

📣 Citation

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