Output formats

cruiseplan.output package.

This package contains output generation modules for various formats:

  • csv_generator: Generates comprehensive CSV files with detailed cruise activity formatting

  • html_generator: Creates HTML reports with summary tables and activity listings

  • kml_generator: Produces Google Earth compatible KML files for geographic visualization

  • latex_generator: Generates LaTeX tables using Jinja2 templates for scientific proposals

  • map_generator: Creates interactive Leaflet maps from cruise track data

  • netcdf_generator: Produces CF-1.8 compliant NetCDF datasets for scientific data management

These modules handle the conversion of cruise planning data into various output formats suitable for different use cases, from interactive web maps to scientific data archives.

Note that the current set of outputs were each designed for a specific purpose.

cruiseplan.output.csv_generator module

CSV Schedule Generation System.

Generates comprehensive CSV files with detailed formatting for all cruise activities.

class cruiseplan.output.csv_generator.CSVGenerator[source]

Bases: object

Manages CSV generation for cruise schedules with comprehensive formatting.

__init__()[source]

Initialize the CSV generator.

generate_schedule_csv(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Generate CSV schedule output with comprehensive formatting.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output CSV file

Returns:

Path to generated CSV file

Return type:

Path

cruiseplan.output.csv_generator.generate_csv_schedule(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Main interface to generate CSV schedule from scheduler timeline.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output CSV file

Returns:

Path to generated CSV file

Return type:

Path

cruiseplan.output.html_generator module

HTML Schedule Generation System.

Generates comprehensive HTML reports with summary tables and detailed activity listings for cruise planning and execution. Provides human-readable visualizations of cruise schedules including statistics, timelines, and operational details.

Notes

The HTML generator creates self-contained HTML files with embedded CSS styling, requiring no external dependencies for viewing. Output includes summary statistics for different activity types (moorings, stations, surveys, areas) and detailed tables for each operation type.

class cruiseplan.output.html_generator.HTMLGenerator[source]

Bases: object

Manages HTML generation for cruise schedules with summary tables and detailed listings.

This class provides methods to generate comprehensive HTML reports from cruise schedule data, including summary statistics and detailed activity breakdowns.

__init__()[source]

Initialize the HTML generator.

generate_schedule_report(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Generate comprehensive HTML schedule report.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output HTML file

Returns:

Path to generated HTML file

Return type:

Path

cruiseplan.output.html_generator.generate_html_schedule(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Main interface to generate HTML schedule from scheduler timeline.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output HTML file

Returns:

Path to generated HTML file

Return type:

Path

cruiseplan.output.kml_generator module

KML Generation System for Cruise Planning.

Generates Google Earth compatible KML files from cruise configuration catalogs. Creates geospatial visualizations of all cruise entities (stations, moorings, transits, ports, areas) for geographic analysis and planning.

This module provides two generation modes: 1. Catalog-based: Generate KML from YAML configuration entities (recommended) 2. Timeline-based: Generate KML from scheduled timeline activities (legacy)

Notes

KML files can be opened directly in Google Earth or other GIS applications. Each entity type is styled differently for visual distinction. Point features include detailed metadata in popups. Catalog-based generation shows each location once regardless of visitation frequency.

class cruiseplan.output.kml_generator.KMLGenerator[source]

Bases: object

Manages KML generation for cruise schedules showing only scientific operations.

This class generates Google Earth compatible KML files containing geospatial representations of scientific cruise activities. Only scientific operations are included, with different styling for each operation type.

__init__()[source]

Initialize the KML generator.

generate_schedule_kml(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Generate KML schedule output with only scientific operations.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output KML file

Returns:

Path to generated KML file

Return type:

Path

cruiseplan.output.kml_generator.generate_kml_catalog(config: CruiseConfig, output_file: Path) → Path[source]

Generate KML file from YAML configuration catalog entities.

Creates a KML file containing all entities defined in the cruise configuration (stations, moorings, transits, ports, areas) without timeline duplication. Each location appears once regardless of how many times it’s visited.

Parameters:

  • config (CruiseConfig) – The cruise configuration object containing all catalog entities

  • output_file (Path) – Path to output KML file

Returns:

Path to generated KML file

Return type:

Path

cruiseplan.output.kml_generator.generate_kml_schedule(config: CruiseConfig, timeline: list[ActivityRecord], output_file: Path) → Path[source]

Main interface to generate KML schedule from scheduler timeline.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_file (Path) – Path to output KML file

Returns:

Path to generated KML file

Return type:

Path

cruiseplan.output.latex_generator module

LaTeX Table Generation System (Phase 3a).

Generates proposal-ready tables using Jinja2 templates for LaTeX documents. Creates paginated tables with proper LaTeX formatting for scientific proposals and reports. Supports multiple table types with automatic page breaks.

Notes

Uses Jinja2 templating with custom delimiters to avoid LaTeX syntax conflicts. Templates are stored in the templates/ subdirectory. Tables are automatically paginated to fit within LaTeX float environments.

class cruiseplan.output.latex_generator.LaTeXGenerator[source]

Bases: object

Manages the Jinja2 environment and template rendering for LaTeX outputs.

This class handles LaTeX table generation using Jinja2 templates with custom delimiters to avoid conflicts with LaTeX syntax. Supports automatic pagination of large tables.

MAX_ROWS_PER_PAGE

Maximum number of rows per page for LaTeX table float environment (45).

Type:

int

env

Jinja2 environment configured with LaTeX-safe delimiters.

Type:

jinja2.Environment

MAX_ROWS_PER_PAGE = 45
generate_stations_table(config: CruiseConfig, timeline: list[ActivityRecord]) → str[source]

Generates the Working Area, Stations and Profiles table from scheduler timeline.

generate_work_days_table(config: CruiseConfig, timeline: list[ActivityRecord]) → str[source]

Generates the Work Days at Sea table from scheduler timeline.

If multiple legs exist, generates separate tables per leg.

cruiseplan.output.latex_generator.generate_latex_tables(config: CruiseConfig, timeline: list[ActivityRecord], output_dir: Path, base_name: str = None) → list[Path][source]

Main interface to generate LaTeX tables for cruise proposal from scheduler timeline.

Parameters:

  • config (CruiseConfig) – The cruise configuration object

  • timeline (List[ActivityRecord]) – Timeline generated by the scheduler

  • output_dir (Path) – Directory to write output files

Return type:

List of generated .tex files

cruiseplan.output.map_generator module

Interactive Map Generation System.

Generates interactive Leaflet maps from cruise track data using Folium. Creates HTML files with embedded JavaScript for web-based geographic visualization of cruise operations and tracks.

Notes

Maps are centered on the first track’s average position. Multiple tracks are displayed with different colors. Requires internet connection for tile loading when viewing the generated HTML files.

cruiseplan.output.map_generator.calculate_optimal_figsize(display_bounds: tuple[float, float, float, float], base_width: float = 12.0, max_height: float = 10.0, min_height: float = 4.0) → tuple[float, float][source]

Calculate figure size that matches geographic aspect ratio.

This prevents aspect ratio conflicts between matplotlib’s figure and the geographic extent of the map.

Parameters:

  • display_bounds (tuple) – (min_lon, max_lon, min_lat, max_lat) in degrees

  • base_width (float, optional) – Preferred figure width in inches (default 12.0)

  • max_height (float, optional) – Maximum figure height in inches (default 10.0)

  • min_height (float, optional) – Minimum figure height in inches (default 4.0)

Returns:

(width, height) in inches optimized for geographic extent

Return type:

tuple

cruiseplan.output.map_generator.extract_areas_from_cruise(cruise) → list[dict[str, Any]][source]

Extract area features (survey areas, polygons) from cruise configuration.

Parameters:

cruise (Cruise) – Cruise object with config containing areas

Returns:

List of area dictionaries with keys: name, corners, entity_type, operation_type, action

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.extract_areas_from_timeline(timeline_data) → list[dict[str, Any]][source]

Extract area features from timeline data.

Parameters:

timeline_data (List[Dict]) – Timeline activity records

Returns:

List of area dictionaries with keys: name, corners, entity_type, operation_type, action

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.extract_lines_from_cruise(cruise) → list[dict[str, Any]][source]

Extract line features (scientific transits, cruise tracks) from cruise configuration.

Parameters:

cruise (Cruise) – Cruise object with config containing transits

Returns:

List of line dictionaries with keys: name, waypoints, entity_type, operation_type, action

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.extract_lines_from_timeline(timeline) → list[dict[str, Any]][source]

Extract line features (cruise tracks) from timeline activities by connecting sequential positions.

Parameters:

timeline (List[ActivityRecord]) – List of timeline activity records

Returns:

List of line dictionaries with waypoints showing cruise track progression

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.extract_map_data(data_source, source_type='cruise', include_ports=True)[source]

Extract all map features (points, lines, areas) from cruise config or timeline.

Parameters:

  • data_source (Cruise or list) – Either a Cruise object or timeline list

  • source_type (str, optional) – “cruise” for Cruise object, “timeline” for timeline list

  • include_ports (bool, optional) – Whether to include departure/arrival ports (default True)

Returns:

Dictionary with keys: points, lines, areas, title, bounds

Return type:

dict

cruiseplan.output.map_generator.extract_points_from_cruise(cruise, include_ports=True) → list[dict[str, Any]][source]

Extract point features (stations, moorings, optionally ports) from cruise configuration.

Parameters:

  • cruise (Cruise) – Cruise object with station registry and configuration

  • include_ports (bool, optional) – Whether to include departure/arrival ports (default True)

Returns:

List of point dictionaries with keys: name, lat, lon, entity_type, operation_type, action

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.extract_points_from_timeline(timeline) → list[dict[str, Any]][source]

Extract point features (stations, ports) from timeline activities.

Parameters:

timeline (List[ActivityRecord]) – List of timeline activity records

Returns:

List of point dictionaries with keys: name, lat, lon, entity_type, operation_type, action, depth

Return type:

List[Dict[str, Any]]

cruiseplan.output.map_generator.generate_folium_map(tracks: list[dict[str, Any]], output_file: str | Path = 'cruise_map.html') → Path | None[source]

Generates an interactive Leaflet map from merged cruise tracks.

Parameters:

  • tracks (list of dict) – List of track dictionaries with ‘latitude’, ‘longitude’, ‘label’, ‘dois’ keys. Each track contains coordinate lists and metadata.

  • output_file (str or Path, optional) – Path or string for the output HTML file. Default is “cruise_map.html”.

Returns:

The absolute path to the generated map file.

Return type:

Path

Notes

Map is centered on the average position of the first track. Tracks are displayed with different colors. Returns None if no valid tracks provided.

cruiseplan.output.map_generator.generate_map(data_source, source_type: str = 'cruise', output_file: str | Path = 'cruise_map.png', bathy_source: str = 'gebco2025', bathy_stride: int = 5, bathy_dir: str = 'data', show_plot: bool = False, figsize: tuple[float, float] = (10, 8.1), include_ports: bool = True) → Path | None[source]

Generate a static PNG map from either cruise config or timeline data.

This is a unified function that can handle both cruise configuration objects and timeline data from the scheduler.

Parameters:

  • data_source (Cruise or list) – Either a Cruise object or timeline data

  • source_type (str, optional) – “cruise” for Cruise object, “timeline” for timeline data (default: “cruise”)

  • output_file (str or Path, optional) – Path or string for the output PNG file. Default is “cruise_map.png”.

  • bathy_source (str, optional) – Bathymetry dataset to use (“etopo2022” or “gebco2025”). Default is “gebco2025”.

  • bathy_stride (int, optional) – Downsampling factor for bathymetry (higher = faster but less detailed). Default is 5.

  • show_plot (bool, optional) – Whether to display the plot inline (useful for notebooks). Default is False.

  • figsize (tuple of float, optional) – Figure size as (width, height) in inches. Default is (10, 8).

  • include_ports (bool, optional) – Whether to include departure/arrival ports in the map. Default is True.

Returns:

The absolute path to the generated PNG map file, or None if failed.

Return type:

Path or None

cruiseplan.output.map_generator.generate_map_from_timeline(timeline, output_file: str | Path = 'timeline_map.png', bathy_source: str = 'gebco2025', bathy_dir: str = 'data', bathy_stride: int = 5, figsize: tuple[float, float] = (10, 8), config=None) → Path | None[source]

Generate a static PNG map from timeline data showing scheduled sequence.

This function creates a map showing the actual scheduled sequence of operations with cruise tracks between stations.

Parameters:

  • timeline (list) – Timeline data from scheduler with activities and coordinates

  • output_file (str or Path, optional) – Path or string for the output PNG file. Default is “timeline_map.png”.

  • bathy_source (str, optional) – Bathymetry dataset to use (“etopo2022” or “gebco2025”). Default is “gebco2025”.

  • bathy_dir (str, optional) – Directory containing bathymetry data. Default is “data”.

  • bathy_stride (int, optional) – Downsampling factor for bathymetry (higher = faster but less detailed). Default is 5.

  • figsize (tuple of float, optional) – Figure size as (width, height) in inches. Default is (10, 8).

  • config (CruiseConfig, optional) – Cruise configuration object to extract port information

Returns:

The absolute path to the generated PNG map file, or None if failed.

Return type:

Path or None

cruiseplan.output.map_generator.generate_map_from_yaml(cruise, output_file: str | Path = 'cruise_map.png', bathy_source: str = 'gebco2025', bathy_stride: int = 5, bathy_dir: str = 'data', show_plot: bool = False, figsize: tuple[float, float] = (10, 8), include_ports: bool = True) → Path | None[source]

Generate a static PNG map directly from a Cruise configuration object.

This is a high-level function that combines the individual plotting functions.

Parameters:

  • cruise (Cruise) – Cruise object with station registry and configuration

  • output_file (str or Path, optional) – Path or string for the output PNG file. Default is “cruise_map.png”.

  • bathy_source (str, optional) – Bathymetry dataset to use (“etopo2022” or “gebco2025”). Default is “gebco2025”.

  • bathy_stride (int, optional) – Downsampling factor for bathymetry (higher = faster but less detailed). Default is 5.

  • show_plot (bool, optional) – Whether to display the plot inline (useful for notebooks). Default is False.

  • figsize (tuple of float, optional) – Figure size as (width, height) in inches. Default is (10, 8).

  • include_ports (bool, optional) – Whether to include departure/arrival ports in the map. Default is True.

Returns:

The absolute path to the generated PNG map file, or None if failed.

Return type:

Path or None

cruiseplan.output.map_generator.plot_bathymetry(ax, bathy_min_lon: float, bathy_max_lon: float, bathy_min_lat: float, bathy_max_lat: float, bathy_source: str = 'gebco2025', bathy_stride: int = 5, bathy_dir: str = 'data') → bool[source]

Plot bathymetry contours on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – The matplotlib axis to plot on

  • bathy_min_lon (float) – Longitude bounds for bathymetry data

  • bathy_max_lon (float) – Longitude bounds for bathymetry data

  • bathy_min_lat (float) – Latitude bounds for bathymetry data

  • bathy_max_lat (float) – Latitude bounds for bathymetry data

  • bathy_source (str, optional) – Bathymetry dataset to use (default “gebco2025”)

  • bathy_stride (int, optional) – Downsampling factor for bathymetry (default 5)

Returns:

True if bathymetry was successfully plotted, False otherwise

Return type:

bool

cruiseplan.output.map_generator.plot_cruise_elements(ax, map_data: dict[str, Any], display_bounds: tuple[float, float, float, float]) → None[source]

Plot stations, ports, transit lines, and areas on a matplotlib axis using structured map data.

Parameters:

  • ax (matplotlib.axes.Axes) – The matplotlib axis to plot on

  • map_data (Dict[str, Any]) – Structured map data with ‘points’, ‘lines’, ‘areas’, ‘title’, and ‘bounds’

  • display_bounds (tuple) – (min_lon, max_lon, min_lat, max_lat) for display area

cruiseplan.output.netcdf_generator module

NetCDF Output Generation System (Phase 3c).

Generates CF-1.8 compliant NetCDF datasets for scientific data management and analysis. Implements discrete sampling geometries as specified in netcdf_outputs.md.

class cruiseplan.output.netcdf_generator.NetCDFGenerator[source]

Bases: object

CF-1.8 compliant NetCDF generator using xarray.

Generates CF-1.8 compliant NetCDF files organized by operation geometry type. Implements discrete sampling geometries for scientific data management and analysis as specified in the netcdf_outputs.md specification.

cf_conventions

CF conventions version used for NetCDF files (“CF-1.8”).

Type:

str

derive_area_operations(schedule_file: Path, areas_file: Path, config: CruiseConfig) → None[source]

Derive area operations file from master schedule.nc.

Filters to include only area_operation categories.

derive_line_operations(schedule_file: Path, lines_file: Path, config: CruiseConfig) → None[source]

Derive line operations file from master schedule.nc.

Filters to include only line_operation categories.

derive_point_operations(schedule_file: Path, points_file: Path, config: CruiseConfig) → None[source]

Derive point operations file from master schedule.nc.

Filters to include only point_operation categories.

generate_all_netcdf_outputs(config: CruiseConfig, timeline: list[ActivityRecord], output_dir: Path) → list[Path][source]

Generate all NetCDF files according to netcdf_outputs.md specification.

Uses master file approach: generate schedule.nc as master, then derive specialized files for different operation types. Implements CF-1.8 compliant discrete sampling geometries.

Parameters:

  • config (CruiseConfig) – Cruise configuration object containing cruise metadata.

  • timeline (list of ActivityRecord) – Timeline of scheduled activities from the scheduler.

  • output_dir (Path) – Directory where NetCDF files will be written.

Returns:

List of paths to all generated NetCDF files.

Return type:

list of Path

generate_area_operations(config: CruiseConfig, output_path: Path) → None[source]

Generate area operations NetCDF (placeholder for future implementation).

FeatureType: trajectory (coverage patterns).

generate_line_operations(config: CruiseConfig, timeline: list[ActivityRecord], output_path: Path) → None[source]

Generate line operations NetCDF from scientific transits.

FeatureType: trajectory (start/end points defining survey lines).

generate_master_schedule(timeline: list[ActivityRecord], config: CruiseConfig, output_path: Path) → None[source]

Generate master schedule NetCDF from timeline with waterdepth included for all operations.

FeatureType: trajectory (ship’s continuous path) This is the master file containing all data that other files derive from.

generate_point_operations(config: CruiseConfig, timeline: list[dict[str, Any]], output_path: Path) → None[source]

Generate point operations NetCDF from stations and moorings.

FeatureType: point (CF discrete sampling geometry)

generate_ship_schedule(timeline: list[ActivityRecord], config: CruiseConfig, output_path: Path) → None[source]

Generate ship schedule NetCDF from timeline.

FeatureType: trajectory (ship’s continuous path).

cruiseplan.output.netcdf_generator.generate_netcdf_outputs(config: CruiseConfig, timeline: list[ActivityRecord], output_dir: Path) → list[Path][source]

Convenience function to generate all NetCDF outputs.

Args:

config: Cruise configuration timeline: Generated timeline from scheduler output_dir: Directory to write NetCDF files (defaults to tests_output/netcdf for tests)

Return type:

List of generated NetCDF file paths

cruiseplan.output.netcdf_metadata module

Centralized NetCDF metadata management for CF-1.8 compliant outputs.

This module provides standardized metadata definitions and factory functions for creating consistent NetCDF global attributes and variable attributes across all NetCDF output types. Eliminates duplication and ensures adherence to CF conventions.

cruiseplan.output.netcdf_metadata.create_coordinate_variables(times, lats, lons, depths=None, operation_depths=None) → dict[str, tuple[list[str], Any, dict[str, Any]]][source]

Create standardized coordinate variable definitions for xarray Dataset.

Parameters:

  • times (array_like) – Time values

  • lats (array_like) – Latitude values

  • lons (array_like) – Longitude values

  • depths (array_like, optional) – Water depth values (seafloor depth)

  • operation_depths (array_like, optional) – Operation depth values (target depth for operations)

Returns:

Dictionary of coordinate variable definitions for xarray.Dataset

Return type:

Dict[str, tuple]

cruiseplan.output.netcdf_metadata.create_global_attributes(feature_type: str, config: CruiseConfig, title_template: str, source: str = 'YAML configuration file') → dict[str, Any][source]

Create standardized global attributes for NetCDF files.

Parameters:

  • feature_type (str) – CF feature type (“point”, “trajectory”, “timeSeries”, etc.)

  • config (CruiseConfig) – Cruise configuration object containing metadata

  • title_template (str) – Template for the title (e.g., “Point Operations: {cruise_name}”)

  • source (str, optional) – Data source description

Returns:

Dictionary of global attributes following CF-1.8 conventions

Return type:

Dict[str, Any]

cruiseplan.output.netcdf_metadata.create_operation_variables(names, types, actions, durations, comments=None) → dict[str, tuple[list[str], Any, dict[str, Any]]][source]

Create standardized operation variable definitions for xarray Dataset.

Parameters:

  • names (array_like) – Station/operation names

  • types (array_like) – Operation types

  • actions (array_like) – Operation actions

  • durations (array_like) – Operation durations

  • comments (array_like, optional) – Operation comments

Returns:

Dictionary of operation variable definitions for xarray.Dataset

Return type:

Dict[str, tuple]

cruiseplan.output.netcdf_metadata.get_variable_attributes(variable_name: str) → dict[str, Any][source]

Get standardized attributes for a variable name.

Parameters:

variable_name (str) – Name of the variable to get attributes for

Returns:

Dictionary of variable attributes, empty dict if not found

Return type:

Dict[str, Any]