"""
Station plan API for generating cruise activity lists and forecasts.
This module provides the main API functions for reading cruise schedules
and generating station plan outputs for real-time cruise operations.
"""
import dataclasses
import logging
from dataclasses import dataclass
from datetime import timedelta
from pathlib import Path
import numpy as np
import xarray as xr
from cruiseplan.forecast.formatter import format_letsgo_output
from cruiseplan.forecast.generator import (
anchor_rule,
format_activities_table,
generate_forecast,
list_activities,
parse_start_time,
ship_time_offset,
time_zone_label,
)
from cruiseplan.forecast.reader import read_schedule
from cruiseplan.output.kml_generator import KMLGenerator
from cruiseplan.timeline.record import KIND_OPERATION_CLASS, ActivityRecord, kind_of
logger = logging.getLogger(__name__)
[docs]
@dataclass
class StationplanResult:
"""
Result object for stationplan operations.
Attributes
----------
success : bool
Whether the operation completed successfully
message : str
Status message or error description
output : str, optional
Generated output text (for list mode)
"""
success: bool
message: str
output: str = ""
[docs]
def stationplan_list(schedule_file: str | Path) -> StationplanResult:
"""
List all activities in a cruise schedule with indices.
This function reads a NetCDF schedule file and returns a formatted table
of all activities with their indices, time offsets, categories, durations,
and names. This is used for the --list mode of the stationplan command.
Parameters
----------
schedule_file : str or Path
Path to NetCDF schedule file (e.g., 'MSM142_leg_2_schedule.nc')
Returns
-------
StationplanResult
Result object containing:
- success: True if successful, False if error
- message: Status message
- output: Formatted activities table (if successful)
Examples
--------
>>> result = stationplan_list("data/cruise_schedule.nc")
>>> if result.success:
... print(result.output)
... else:
... print(f"Error: {result.message}")
"""
try:
logger.info(f"Loading schedule for activity listing: {schedule_file}")
# Read the schedule file
schedule = read_schedule(schedule_file)
# Get activity list
activities = list_activities(schedule)
if not activities:
return StationplanResult(
success=False, message="No activities found in schedule file", output=""
)
# Format as table
output_table = format_activities_table(activities)
logger.info(f"Successfully listed {len(activities)} activities")
return StationplanResult(
success=True,
message=f"Listed {len(activities)} activities from {schedule_file}",
output=output_table,
)
except FileNotFoundError as e:
error_msg = f"Schedule file not found: {e}"
logger.error(error_msg)
return StationplanResult(success=False, message=error_msg, output="")
except ValueError as e:
error_msg = f"Invalid schedule file: {e}"
logger.error(error_msg)
return StationplanResult(success=False, message=error_msg, output="")
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Unexpected error processing schedule: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
[docs]
def stationplan_forecast(
schedule_file: str | Path,
start_index: int,
start_time: str,
duration_hours: float = 24.0,
transit_speed: float = 10.0,
current_position: tuple[float, float] | None = None,
) -> StationplanResult:
"""
Generate station plan forecast starting from specified activity.
This function reads a NetCDF schedule file, generates a time-shifted forecast
starting from the specified activity index with a new start time, and formats
the output as letsgo.m compatible text.
Parameters
----------
schedule_file : str or Path
Path to NetCDF schedule file (e.g., 'MSM142_leg_2_schedule.nc')
start_index : int
Row index (0-based, as in ``cruiseplan list``); an operation row
starts at ``start_time``, a transit row starts at ``start_time`` from
where it begins (with ``current_position``, the operation it leads to
is used)
start_time : str
Start time of the anchored operation, or of the ship at
``current_position`` (ISO format). A time without a zone is UTC; with
the ship's zone (``"2026-08-30T14:00+03:00"``) it is ship time
duration_hours : float, optional
Forecast duration in hours (default: 24.0)
transit_speed : float, optional
Ship transit speed in knots for header metadata (default: 10.0)
current_position : tuple of float, optional
Ship position (lat, lon) in decimal degrees at ``start_time``. A
transit from it to the anchored operation is inserted at the leg's
speed, and the operation starts when it ends.
Returns
-------
StationplanResult
Result object containing:
- success: True if successful, False if error
- message: Status message
- output: Formatted letsgo.m forecast text (if successful)
Examples
--------
>>> result = stationplan_forecast("data/cruise_schedule.nc", 18, "2026-08-30T14:00:00", 36.0)
>>> if result.success:
... print(result.output)
... else:
... print(f"Error: {result.message}")
"""
try:
logger.info(
f"Generating forecast from {schedule_file} starting at index {start_index}"
)
# Read the schedule file
schedule = read_schedule(schedule_file)
# Generate forecast
forecast_activities = generate_forecast(
schedule, start_index, start_time, duration_hours, current_position
)
if not forecast_activities:
return StationplanResult(
success=False,
message=f"No activities found in forecast window ({duration_hours}h from {start_time})",
output="",
)
# Format as letsgo.m output
output_text = format_letsgo_output(
forecast_activities,
start_time,
transit_speed,
anchor_note=anchor_rule(
schedule, start_index, start_time, current_position
),
)
logger.info(
f"Successfully generated forecast with {len(forecast_activities)} activities"
)
return StationplanResult(
success=True,
message=f"Generated {duration_hours}h forecast with {len(forecast_activities)} activities",
output=output_text,
)
except FileNotFoundError as e:
error_msg = f"Schedule file not found: {e}"
logger.error(error_msg)
return StationplanResult(success=False, message=error_msg, output="")
except ValueError as e:
error_msg = f"Invalid forecast parameters: {e}"
logger.error(error_msg)
return StationplanResult(success=False, message=error_msg, output="")
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Unexpected error generating forecast: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
[docs]
def stationplan_tex(
schedule_file: str | Path,
output_path: str | Path | None = None,
logo_path: str | Path | None = None,
workplan_number: str | None = None,
cruise_title: str | None = None,
) -> StationplanResult:
"""
Generate TeX station table in letsgo.m format from NetCDF schedule file.
This function reads a NetCDF schedule file and generates a TeX table
in the letsgo.m format using rich NetCDF data with proper coordinates,
depths, and distance calculations.
Parameters
----------
schedule_file : str or Path
Path to NetCDF schedule file (e.g., 'MSM142_leg_2_schedule.nc')
output_path : str or Path, optional
Output path for .tex file. If None, uses schedule_file name with .tex extension
logo_path : str or Path, optional
Path to a logo image (PNG, JPG or PDF). If None, ``config/images/`` is
searched for a default logo.
workplan_number : str, optional
Workplan number printed in the TeX header (e.g. ``"28"``).
cruise_title : str, optional
Cruise title printed in the TeX header (e.g. ``"MSM142"``).
Returns
-------
StationplanResult
Result object containing:
- success: True if successful, False if error
- message: Status message
- output: Path to generated .tex file (if successful)
Examples
--------
>>> result = stationplan_tex("data/cruise_schedule.nc", "station_plan.tex")
>>> if result.success:
... print(f"TeX table generated: {result.output}")
... else:
... print(f"Error: {result.message}")
"""
try:
from cruiseplan.output.latex_generator import generate_letsgo_table_from_netcdf
schedule_path = Path(schedule_file)
logger.info(f"Generating TeX table from schedule: {schedule_path}")
# Determine output path
if output_path is None:
output_file = schedule_path.with_suffix(".tex")
else:
output_file = Path(output_path)
# Generate TeX table using our letsgo-style generator
generated_file = generate_letsgo_table_from_netcdf(
schedule_path, output_file, logo_path, workplan_number, cruise_title
)
logger.info(f"Successfully generated TeX table: {generated_file}")
return StationplanResult(
success=True,
message=f"Generated TeX station table: {generated_file}",
output=str(generated_file),
)
except FileNotFoundError as e:
error_msg = f"Schedule file not found: {e}"
logger.error(error_msg)
return StationplanResult(success=False, message=error_msg, output="")
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Error generating TeX table: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
def _lookup_schedule_depth_data(
schedule: xr.Dataset, index: int
) -> tuple[float | None, float | None, str]:
"""Look up water_depth, operation_depth, and comment from a NetCDF schedule.
Returns (water_depth, operation_depth, comment) with None/empty defaults.
"""
water_depth = None
operation_depth = None
comment = ""
if "water_depth" in schedule.variables:
try:
depth_val = schedule.water_depth[index].values
if depth_val is not None and not np.isnan(float(depth_val)):
water_depth = float(depth_val)
except (TypeError, ValueError):
pass
if "operation_depth" in schedule.variables:
try:
op_depth_val = schedule.operation_depth[index].values
if op_depth_val is not None and not np.isnan(float(op_depth_val)):
operation_depth = float(op_depth_val)
except (TypeError, ValueError):
pass
if "comment" in schedule.variables:
comment_val = str(schedule.comment[index].values)
if comment_val and comment_val not in {"nan", "_"}:
comment = comment_val
return water_depth, operation_depth, comment
def _lookup_tex_exit_coords(
schedule: xr.Dataset, index: int, latitude: float, longitude: float
) -> tuple[float, float]:
"""Return exit (lat, lon) from schedule variables, falling back to entry coords."""
try:
if (
"exit_latitude" in schedule.variables
and "exit_longitude" in schedule.variables
):
exit_lat_val = float(schedule.exit_latitude[index].values)
exit_lon_val = float(schedule.exit_longitude[index].values)
if not (np.isnan(exit_lat_val) or np.isnan(exit_lon_val)):
return exit_lat_val, exit_lon_val
except (AttributeError, TypeError, ValueError, IndexError):
pass
return latitude, longitude
def _build_tex_forecast_record(
schedule: xr.Dataset, index: int, activity_tuple: tuple
) -> "ActivityRecord | None":
"""Convert one forecast row to a record for TeX output; None for transits."""
(
_idx,
time,
category,
activity_type,
action,
duration,
latitude,
longitude,
name,
) = activity_tuple
if category == "transit":
return None
water_depth, operation_depth, comment = _lookup_schedule_depth_data(schedule, index)
exit_lat, exit_lon = _lookup_tex_exit_coords(schedule, index, latitude, longitude)
end_time = time + timedelta(hours=duration)
operation_distance = (
float(schedule.distance[index].values)
if "distance" in schedule.variables
else 0.0
)
next_transit_distance = (
float(schedule.distance_to_next[index].values)
if "distance_to_next" in schedule.variables
else 0.0
)
from cruiseplan.forecast.reader import _float, _text, stored_kind
kind = "transit" if index < 0 else stored_kind(schedule, index)
return ActivityRecord(
kind=kind,
activity=_text(schedule, "activity", index, category),
label=name,
entry_lat=float(latitude),
entry_lon=float(longitude),
exit_lat=float(exit_lat),
exit_lon=float(exit_lon),
start_time=time,
end_time=end_time,
duration_minutes=float(duration) * 60.0,
planned_duration_minutes=float(duration) * 60.0,
water_depth_m=water_depth,
operation_depth_m=operation_depth,
dist_nm=operation_distance,
transit_dist_nm=next_transit_distance,
vessel_speed_kt=_float(schedule, "vessel_speed", index, np.nan),
leg_name="forecast",
op_type=activity_type,
operation_class=KIND_OPERATION_CLASS[kind],
action=action if action else None,
comment=comment,
)
[docs]
def stationplan_forecast_tex(
schedule_file: str | Path,
start_index: int,
start_time: str,
duration_hours: float = 24.0,
output_path: str | Path | None = None,
logo_path: str | Path | None = None,
workplan_number: str | None = None,
cruise_title: str | None = None,
current_position: tuple[float, float] | None = None,
) -> StationplanResult:
"""
Generate TeX station forecast starting from specified activity.
Combines forecast generation with TeX formatting - generates a time-shifted
forecast and outputs it as a complete LaTeX document. When ``start_time``
carries the ship's zone, the table is printed in that ship time and the
time column is labelled with it; otherwise it is in UTC.
Parameters
----------
schedule_file : str or Path
Path to NetCDF schedule file
start_index : int
Row index (0-based, as in ``cruiseplan list``); an operation row
starts at ``start_time``, a transit row starts at ``start_time`` from
where it begins (with ``current_position``, the operation it leads to
is used)
start_time : str
Start time of the anchored operation, or of the ship at
``current_position`` (ISO format). A time without a zone is UTC; with
the ship's zone (``"2026-08-30T14:00+03:00"``) it is ship time
duration_hours : float
Forecast duration in hours (default: 24.0)
output_path : str or Path, optional
Output path for .tex file
logo_path : str or Path, optional
Path to logo image file (PNG, JPG, or PDF). If None, checks for default logos in config/images/ folder
workplan_number : str, optional
Workplan number printed in the TeX header (e.g. ``"28"``).
cruise_title : str, optional
Cruise title printed in the TeX header (e.g. ``"MSM142"``).
current_position : tuple of float, optional
Ship position (lat, lon) in decimal degrees at ``start_time``. A
transit from it to the anchored operation is inserted at the leg's
speed, and the operation starts when it ends.
Returns
-------
StationplanResult
Result object with success status and generated file path
"""
try:
from cruiseplan.output.latex_generator import LaTeXGenerator
schedule_path = Path(schedule_file)
logger.info(
f"Generating TeX forecast from {schedule_path} starting at index {start_index}"
)
# Read schedule and generate forecast with time shifting
schedule = read_schedule(schedule_path)
forecast_activities = generate_forecast(
schedule, start_index, start_time, duration_hours, current_position
)
if not forecast_activities:
return StationplanResult(
success=False,
message=f"No activities found in forecast window ({duration_hours}h from {start_time})",
output="",
)
if "vessel_speed" not in schedule.variables:
logger.warning(
f"{schedule_path}: no vessel_speed variable; record speeds are NaN"
)
activity_records = [
record
for activity_tuple in forecast_activities
if (
record := _build_tex_forecast_record(
schedule, activity_tuple[0], activity_tuple
)
)
is not None
]
# Ship time: the table is printed in the clock of --start-time
offset = ship_time_offset(start_time)
if offset is not None:
activity_records = [
dataclasses.replace(
r, start_time=r.start_time + offset, end_time=r.end_time + offset
)
for r in activity_records
]
# Determine output path
if output_path is None:
output_file = schedule_path.with_name(f"{schedule_path.stem}_forecast.tex")
else:
output_file = Path(output_path)
# Generate TeX using our LaTeX generator
generator = LaTeXGenerator()
cruise_name = f"{schedule_path.stem} forecast"
tex_content = generator.generate_letsgo_table(
activity_records,
cruise_name,
logo_path=logo_path,
workplan_number=workplan_number,
cruise_title=cruise_title,
anchor_note=anchor_rule(
schedule, start_index, start_time, current_position
),
time_label=time_zone_label(offset),
)
# Write to file
output_file.parent.mkdir(exist_ok=True, parents=True)
output_file.write_text(tex_content, encoding="utf-8")
logger.info(f"Successfully generated TeX forecast: {output_file}")
return StationplanResult(
success=True,
message=f"Generated TeX forecast with {len(activity_records)} activities: {output_file}",
output=str(output_file),
)
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Error generating TeX forecast: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
def _activity_to_waypoint_lines(
activity: tuple,
schedule: object,
use_decimal_degrees: bool,
) -> list[str]:
"""Convert one forecast activity tuple to 1-2 bridge waypoint lines.
Returns an empty list for transit activities or malformed tuples.
"""
if len(activity) < 9:
return []
(
index,
_time,
category,
activity_type,
_action,
_duration,
latitude,
longitude,
name,
) = activity
# Waypoints are where work is done: no transits, waits or contingency
if category == "transit" or activity_type in {"wait", "buffer"}:
return []
work_code = _map_activity_to_work_code(category, activity_type, name)
exit_lat, exit_lon = _resolve_exit_coordinates(
schedule, index, latitude, longitude, name, activity_type
)
fmt = _format_decimal_degrees if use_decimal_degrees else _format_ddm_coordinate
entry_lat = fmt(latitude, "lat")
entry_lon = fmt(longitude, "lon")
exit_lat_s = fmt(exit_lat, "lat")
exit_lon_s = fmt(exit_lon, "lon")
if abs(latitude - exit_lat) > 0.001 or abs(longitude - exit_lon) > 0.001:
return [
f"{work_code}\t{entry_lat}\t{entry_lon}\t{name} Start",
f"{work_code}\t{exit_lat_s}\t{exit_lon_s}\t{name} End",
]
return [f"{work_code}\t{entry_lat}\t{entry_lon}\t{name}"]
def _resolve_exit_coordinates(
schedule: object,
index: int,
latitude: float,
longitude: float,
name: str,
activity_type: str,
) -> tuple[float, float]:
"""Return (exit_lat, exit_lon) for an activity, falling back to entry coords.
Checks explicit exit_latitude/exit_longitude variables first, then falls
back to the next waypoint for survey/transit line operations.
"""
if index >= len(schedule.latitude) - 1:
return latitude, longitude
try:
if (
"exit_latitude" in schedule.variables
and "exit_longitude" in schedule.variables
):
exit_lat_val = float(schedule.exit_latitude[index].values)
exit_lon_val = float(schedule.exit_longitude[index].values)
if not (np.isnan(exit_lat_val) or np.isnan(exit_lon_val)):
return exit_lat_val, exit_lon_val
if (
"Transit_" in name
or "Bathy_" in name
or activity_type in ["survey", "unknown", "underway"]
):
next_lat = float(schedule.latitude[index + 1].values)
next_lon = float(schedule.longitude[index + 1].values)
if not (np.isnan(next_lat) or np.isnan(next_lon)):
return next_lat, next_lon
except (AttributeError, TypeError, ValueError, IndexError):
pass
return latitude, longitude
[docs]
def stationplan_waypoints(
schedule_file: str | Path,
start_index: int | None,
start_time: str | None = None,
duration_hours: float | None = 48.0,
current_position: tuple[float, float] | None = None,
output_path: str | Path | None = None,
) -> StationplanResult:
"""
Generate bridge waypoints file in Stationsplan.txt format.
Creates a simple waypoint list suitable for bridge navigation systems
with DDM coordinate format and work type codes.
Parameters
----------
schedule_file : str or Path
Path to NetCDF schedule file
start_index : int, optional
Row index (0-based, as in ``cruiseplan list``); an operation row
starts at ``start_time``, a transit row starts at ``start_time`` from
where it begins. If None, the full schedule from row 0.
start_time : str, optional
Start time of the anchored operation, or of the ship at
``current_position`` (ISO format, UTC; a time without a zone is taken
as UTC). If None, now (UTC) rounded to 10 minutes.
duration_hours : float, optional
Forecast duration in hours (if None, uses remaining schedule)
current_position : tuple of float, optional
Ship position (lat, lon) in decimal degrees at ``start_time``. A
transit from it to the anchored operation is inserted at the leg's
speed, and the operation starts when it ends.
output_path : str or Path, optional
Output file path. If None, returns content as string
Returns
-------
StationplanResult
Result object containing success status and waypoint content
"""
try:
from cruiseplan.forecast.generator import generate_forecast
from cruiseplan.forecast.reader import read_schedule
logger.info(f"Generating bridge waypoints from {schedule_file}")
# Read the schedule file
schedule = read_schedule(schedule_file)
# Default start_index to 0 if not provided (full cruise from beginning)
if start_index is None:
start_index = 0
# Default start_time to now, rounded to 10 minutes (like letsgo.m)
if start_time is None:
from datetime import UTC, datetime
from cruiseplan.utils.units import round_to_minutes
now = datetime.now(UTC).replace(tzinfo=None)
start_time = round_to_minutes(now, 10).isoformat()
# Always use forecast mode for waypoints (from start_index forward)
activities = generate_forecast(
schedule,
start_index,
start_time,
duration_hours or 1000,
current_position,
)
if not activities:
return StationplanResult(
success=False, message="No activities found in schedule", output=""
)
# Generate waypoint content in both coordinate formats
def generate_waypoint_content(use_decimal_degrees: bool = False) -> str:
waypoint_lines = []
# Add header with proper spacing
waypoint_lines.append("%")
# Add start date if available (at top)
if start_time:
start_utc = parse_start_time(start_time).strftime(
"%Y-%m-%dT%H:%M:%S UTC"
)
waypoint_lines.append(f"% start_date = {start_utc}")
waypoint_lines.append("%")
# Add coordinate format indicator
format_type = (
"Decimal Degrees"
if use_decimal_degrees
else "Degrees Decimal Minutes (DDM)"
)
waypoint_lines.append(f"% Coordinate format: {format_type}")
# Add legend header
waypoint_lines.append(
"% (1: Transit, 2: CTD, 3: Mooring, 4: PIES, 5: Float/Drifter, 6: Survey)"
)
waypoint_lines.append("%")
# Add current position if provided
if current_position:
lat, lon = current_position
if use_decimal_degrees:
lat_formatted = _format_decimal_degrees(lat, "lat")
lon_formatted = _format_decimal_degrees(lon, "lon")
else:
lat_formatted = _format_ddm_coordinate(lat, "lat")
lon_formatted = _format_ddm_coordinate(lon, "lon")
waypoint_lines.append(f"1\t{lat_formatted}\t{lon_formatted}\tMerian")
# Process activities and convert to waypoints
for activity in activities:
waypoint_lines.extend(
_activity_to_waypoint_lines(activity, schedule, use_decimal_degrees)
)
# Join all lines
return "\n".join(waypoint_lines) + "\n"
# Generate content for both formats
waypoint_content_ddm = generate_waypoint_content(use_decimal_degrees=False)
waypoint_content_decdeg = generate_waypoint_content(use_decimal_degrees=True)
# Write to file(s) if path provided
if output_path:
output_file = Path(output_path)
output_file.parent.mkdir(exist_ok=True, parents=True)
# Generate both filenames based on the provided path
# If output_path is "route/Stationsplan28.txt", generate:
# - route/Stationsplan28_ddm.txt (degrees decimal minutes)
# - route/Stationsplan28_decdeg.txt (decimal degrees)
base_path = output_file.with_suffix("") # Remove .txt extension
ddm_file = Path(str(base_path) + "_ddm.txt")
decdeg_file = Path(str(base_path) + "_decdeg.txt")
# Write both files
ddm_file.write_text(waypoint_content_ddm, encoding="utf-8")
decdeg_file.write_text(waypoint_content_decdeg, encoding="utf-8")
logger.info(f"Generated bridge waypoints: {ddm_file} and {decdeg_file}")
# Count waypoints (exclude comment lines)
waypoint_count = len(
[
line
for line in waypoint_content_ddm.split("\n")
if line and not line.startswith("%")
]
)
return StationplanResult(
success=True,
message=f"Generated {waypoint_count} waypoints in both coordinate formats",
output=f"{ddm_file} and {decdeg_file}",
)
# Return DDM content directly (default format)
waypoint_count = len(
[
line
for line in waypoint_content_ddm.split("\n")
if line and not line.startswith("%")
]
)
return StationplanResult(
success=True,
message=f"Generated {waypoint_count} waypoints (DDM format)",
output=waypoint_content_ddm,
)
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Error generating bridge waypoints: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
def _format_ddm_coordinate(decimal_degrees: float, coord_type: str) -> str:
"""Format a coordinate in degrees decimal minutes for bridge waypoints."""
from cruiseplan.utils.coordinates import ddm_parts
degrees, minutes = ddm_parts(decimal_degrees, 2)
if coord_type == "lat":
# Latitude: 2 digits for degrees, N/S direction with space
direction = "N" if decimal_degrees >= 0 else "S"
return f"{degrees:02d} {minutes:05.2f} {direction}"
# longitude
# Longitude: 3 digits for degrees, E/W direction with space
direction = "E" if decimal_degrees >= 0 else "W"
return f"{degrees:03d} {minutes:05.2f} {direction}"
def _format_decimal_degrees(decimal_degrees: float, coord_type: str) -> str:
"""Format a coordinate in decimal degrees for bridge waypoints."""
if coord_type == "lat":
# Latitude: format with 6 decimal places, signed (negative for South)
return f"{decimal_degrees:8.5f}"
# longitude
# Longitude: format with 6 decimal places, signed (negative for West)
return f"{decimal_degrees:9.5f}"
def _log_failure(message: str, error: Exception) -> None:
"""Log a failed forecast: a bad input without a traceback, anything else with one."""
if isinstance(error, ValueError):
logger.error(message)
else:
logger.exception(message)
_WORK_CODE_BY_TYPE: dict[str, int] = {
"ctd": 2,
"station": 2,
"mooring": 3,
"pies": 4,
"float": 5,
"drifter": 5,
"survey": 6,
"navigation": 1,
"transit": 1,
}
def _map_activity_to_work_code(
_category: str, activity_type: str, name: str = ""
) -> int:
"""
Map activity category/type to letsgo.m work code.
Work codes: 1=Transit, 2=CTD, 3=Mooring, 4=PIES, 5=Float/Drifter, 6=Survey
"""
activity_type_lower = activity_type.lower()
name_lower = name.lower()
code = _WORK_CODE_BY_TYPE.get(activity_type_lower)
if code is not None:
return code
if activity_type_lower == "unknown" and "transit_" in name_lower:
return 6
if activity_type_lower == "underway" or "bathy_" in name_lower:
return 6
return 2
def _convert_raw_activity_to_kml_record(
activity: tuple, schedule: xr.Dataset | None = None
) -> "ActivityRecord | None":
"""Convert a forecast row to a KML record; None for transits or invalid positions."""
import pandas as pd
if len(activity) < 9:
return None
(
index,
time,
category,
activity_type,
action,
duration,
latitude,
longitude,
name,
) = activity
if np.isnan(latitude) or np.isnan(longitude):
return None
if category == "transit":
return None
def stored(var: str, default: str) -> str:
if schedule is not None and var in schedule.variables and index >= 0:
return str(schedule[var][index].values).strip()
return default
from cruiseplan.forecast.reader import stored_kind
operation_class = stored("operation_class", "PointOperation")
if operation_class not in {"PointOperation", "LineOperation", "AreaOperation"}:
return None # only scientific operations and ports are shown
if schedule is not None and index >= 0:
kind = stored_kind(schedule, index)
else:
kind = kind_of(operation_class, activity_type)
start = pd.to_datetime(time).to_pydatetime()
minutes = float(duration) * 60.0
return ActivityRecord(
kind=kind,
activity=stored("activity", "Station"),
label=name,
entry_lat=float(latitude),
entry_lon=float(longitude),
exit_lat=float(latitude),
exit_lon=float(longitude),
start_time=start,
end_time=start + timedelta(minutes=minutes),
duration_minutes=minutes,
planned_duration_minutes=minutes,
dist_nm=0.0,
vessel_speed_kt=0.0,
leg_name=stored("leg_assignment", "forecast"),
op_type=activity_type,
operation_class=operation_class,
action=action or None,
)
[docs]
def stationplan_forecast_kml(
schedule_file: str | Path,
start_index: int,
start_time: str,
duration_hours: float,
output_path: str | Path | None = None,
current_position: tuple[float, float] | None = None,
) -> StationplanResult:
"""
Generate KML forecast from a cruise schedule for a specific time window.
Creates a Google Earth compatible KML file showing scientific operations
within the specified forecast period.
Parameters
----------
schedule_file : Union[str, Path]
Path to the NetCDF schedule file
start_index : int
Row index (0-based, as in ``cruiseplan list``); an operation row
starts at ``start_time``, a transit row starts at ``start_time`` from
where it begins (with ``current_position``, the operation it leads to
is used)
start_time : str
Start time of the anchored operation, or of the ship at
``current_position`` (ISO format, UTC, e.g. '2026-05-05 08:00')
duration_hours : float
Forecast duration in hours
output_path : Union[str, Path, None], optional
Path to output KML file, by default None
current_position : tuple of float, optional
Ship position (lat, lon) in decimal degrees at ``start_time``. A
transit from it to the anchored operation is inserted at the leg's
speed, and the operation starts when it ends.
Returns
-------
StationplanResult
Result object with success status, message, and output path
"""
try:
schedule_path = Path(schedule_file)
if not schedule_path.exists():
return StationplanResult(
success=False, message=f"Schedule file not found: {schedule_path}"
)
from cruiseplan.forecast.generator import generate_forecast
from cruiseplan.forecast.reader import read_schedule
# Read schedule and generate forecast with proper time shifting
schedule = read_schedule(schedule_file)
forecast_activities_raw = generate_forecast(
schedule, start_index, start_time, duration_hours, current_position
)
# Convert forecast activities to the format expected by KML generation
forecast_activities = [
record
for activity in forecast_activities_raw
if (record := _convert_raw_activity_to_kml_record(activity, schedule))
is not None
]
if not forecast_activities:
return StationplanResult(
success=False,
message=f"No scientific activities found in forecast window starting from index {start_index} for {duration_hours} hours",
)
# Create a minimal cruise config for KML generation
class MockCruiseConfig:
def __init__(self) -> None:
self.cruise_name = schedule_path.stem
self.description = (
f"Forecast starting from {start_time} for {duration_hours}h"
)
mock_config = MockCruiseConfig()
activity_records = forecast_activities
# Determine output path
if output_path is None:
output_file = schedule_path.with_name(f"{schedule_path.stem}_forecast.kml")
else:
output_file = Path(output_path)
# Generate KML
generator = KMLGenerator()
output_file = generator.generate_schedule_kml(
mock_config, activity_records, output_file
)
logger.info(f"Successfully generated KML forecast: {output_file}")
# Count activities
activity_count = len(forecast_activities)
return StationplanResult(
success=True,
message=f"Generated {activity_count} activities in KML format",
output=str(output_file),
)
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Error generating KML forecast: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")
[docs]
def stationplan_forecast_png(
schedule_file: str | Path,
start_index: int,
start_time: str,
duration_hours: float,
output_path: str | Path | None = None,
bathy_source: str = "gebco2025",
bathy_dir: str = "data/bathymetry",
bathy_stride: int = 10,
figsize: tuple[float, float] = (10.0, 8.1),
lat_bounds: list[float] | None = None,
lon_bounds: list[float] | None = None,
max_depth: int | None = None,
bathy_contours: list[float] | None = None,
no_title: bool = False,
no_labels: bool = False,
no_legend: bool = False,
current_position: tuple[float, float] | None = None,
) -> StationplanResult:
"""
Generate PNG map forecast from a cruise schedule for a specific time window.
Creates a static PNG map showing scientific operations within the specified
forecast period, using the same map generation system as 'cruiseplan schedule --format png'
but filtered to show only work from the start-index for the specified duration.
Parameters
----------
schedule_file : Union[str, Path]
Path to the NetCDF schedule file
start_index : int
Row index (0-based, as in ``cruiseplan list``); an operation row
starts at ``start_time``, a transit row starts at ``start_time`` from
where it begins (with ``current_position``, the operation it leads to
is used)
start_time : str
Start time of the anchored operation, or of the ship at
``current_position`` (ISO format, UTC, e.g. '2026-05-05 08:00')
duration_hours : float
Forecast duration in hours
output_path : Union[str, Path, None], optional
Path to output PNG file, by default None
bathy_source : str, optional
Bathymetry dataset to use, by default "gebco2025"
bathy_dir : str, optional
Directory containing bathymetry data, by default "data/bathymetry"
bathy_stride : int, optional
Bathymetry grid downsampling factor, by default 10
figsize : tuple[float, float], optional
Figure size in inches, by default (10.0, 8.1)
lat_bounds : list[float], optional
Latitude bounds [min, max], by default None
lon_bounds : list[float], optional
Longitude bounds [min, max], by default None
max_depth : int, optional
Maximum water depth (m) for the bathymetry colour scale, by default None
bathy_contours : list[float], optional
Explicit contour depths in metres, by default None
no_title : bool, optional
Suppress the map title, by default False
no_labels : bool, optional
Suppress station name labels, by default False
no_legend : bool, optional
Suppress the map legend, by default False
current_position : tuple of float, optional
Ship position (lat, lon) in decimal degrees at ``start_time``. A
transit from it to the anchored operation is inserted at the leg's
speed, and the operation starts when it ends.
Returns
-------
StationplanResult
Result object with success status, message, and output path
"""
try:
from cruiseplan.forecast.generator import generate_forecast
from cruiseplan.forecast.reader import read_schedule
from cruiseplan.output.map_generator import generate_map_from_timeline
schedule_path = Path(schedule_file)
if not schedule_path.exists():
return StationplanResult(
success=False, message=f"Schedule file not found: {schedule_path}"
)
logger.info(
f"Generating PNG forecast from {schedule_path} starting at index {start_index}"
)
# Read schedule and generate forecast with time shifting
schedule = read_schedule(schedule_path)
forecast_activities = generate_forecast(
schedule, start_index, start_time, duration_hours, current_position
)
if not forecast_activities:
return StationplanResult(
success=False,
message=f"No activities found in forecast window ({duration_hours}h from {start_time})",
output="",
)
# Convert forecast activities to timeline format compatible with map generator
# The map generator expects timeline data similar to what comes from the scheduler
timeline_for_map = []
for activity_tuple in forecast_activities:
(
index,
time,
category,
activity_type,
_action,
duration,
latitude,
longitude,
name,
) = activity_tuple
# Operations only: no transits, waits or contingency on the map
if category == "transit" or activity_type in {"wait", "buffer"}:
continue
water_depth, operation_depth, _ = _lookup_schedule_depth_data(
schedule, index
)
minutes = float(duration) * 60.0
timeline_record = ActivityRecord(
kind="station",
activity=category,
label=name,
entry_lat=float(latitude),
entry_lon=float(longitude),
exit_lat=float(latitude),
exit_lon=float(longitude),
start_time=time,
end_time=time + timedelta(minutes=minutes),
duration_minutes=minutes,
planned_duration_minutes=minutes,
dist_nm=0.0,
vessel_speed_kt=0.0,
operation_class="PointOperation",
leg_name="forecast",
op_type=activity_type,
water_depth_m=water_depth,
operation_depth_m=operation_depth,
)
timeline_for_map.append(timeline_record)
# Determine output path
if output_path is None:
output_file = schedule_path.with_name(f"{schedule_path.stem}_forecast.png")
else:
output_file = Path(output_path)
if output_file.suffix.lower() in [".txt", ".tex", ".kml"]:
output_file = output_file.with_suffix(".png")
# Generate PNG map using the same function as cruiseplan schedule
map_file = generate_map_from_timeline(
timeline=timeline_for_map,
output_file=output_file,
bathy_source=bathy_source,
bathy_dir=bathy_dir,
bathy_stride=bathy_stride,
lat_bounds=lat_bounds,
lon_bounds=lon_bounds,
figsize=figsize,
no_ports=True, # Focus on operations, not ports for forecast
config=None, # No cruise config needed for forecast
max_depth=max_depth,
bathy_contours=bathy_contours,
no_title=no_title,
no_labels=no_labels,
no_legend=no_legend,
)
if map_file:
logger.info(f"Successfully generated PNG forecast map: {map_file}")
activity_count = len(timeline_for_map)
return StationplanResult(
success=True,
message=f"Generated PNG forecast map with {activity_count} activities",
output=str(map_file),
)
return StationplanResult(
success=False,
message="PNG map generation failed",
output="",
)
except Exception as e: # noqa: BLE001 - reported in the result; logged with a traceback
error_msg = f"Error generating PNG forecast: {e}"
_log_failure(error_msg, e)
return StationplanResult(success=False, message=error_msg, output="")