using RobotNet10.GlobalPathPlanner.Model;

namespace RobotNet10.GlobalPathPlanner;

/// <summary>
/// Interface for path planning algorithms that calculate optimal routes between nodes in a graph.
/// Supports various robot types (differential drive, forklift, omni-drive) with different planning strategies.
/// </summary>
public interface IPathPlanner
{
    /// <summary>
    /// Sets the graph data (nodes and edges) that will be used for path planning.
    /// This method must be called before any path planning operations.
    /// </summary>
    /// <param name="nodes">Array of nodes representing waypoints in the map.</param>
    /// <param name="edges">Array of edges representing connections between nodes.</param>
    void SetData(GlobalNode[] nodes, GlobalEdge[] edges);

    /// <summary>
    /// Configures the path planner with custom options such as distance limits, resolution, and timeout.
    /// This method is optional; if not called, default options will be used.
    /// </summary>
    /// <param name="options">Configuration options for the path planner.</param>
    void SetOptions(PathPlannerOptions options);

    /// <summary>
    /// Calculates a path from the specified starting coordinates to the goal node.
    /// Uses A* algorithm to find the optimal route through the graph.
    /// </summary>
    /// <param name="x">Starting X coordinate.</param>
    /// <param name="y">Starting Y coordinate.</param>
    /// <param name="theta">Starting orientation angle in degrees.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanning(double x, double y, double theta, Guid goalId, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path with a specified starting direction constraint.
    /// The planner will attempt to ensure the robot starts moving in the specified direction.
    /// </summary>
    /// <param name="x">Starting X coordinate.</param>
    /// <param name="y">Starting Y coordinate.</param>
    /// <param name="theta">Starting orientation angle in degrees.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="startDiretion">Desired starting direction (FORWARD, BACKWARD, or NONE to use default).</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithStartDirection(double x, double y, double theta, Guid goalId, Orientation startDiretion = Orientation.NONE, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path with a specified final direction constraint.
    /// The planner will attempt to ensure the robot arrives at the goal facing the specified direction.
    /// </summary>
    /// <param name="x">Starting X coordinate.</param>
    /// <param name="y">Starting Y coordinate.</param>
    /// <param name="theta">Starting orientation angle in degrees.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="goalDirection">Desired final direction at the goal (FORWARD, BACKWARD, or NONE to use default).</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithFinalDirection(double x, double y, double theta, Guid goalId, Orientation goalDirection = Orientation.NONE, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path with a specified final angle constraint.
    /// The planner will attempt to ensure the robot arrives at the goal with the specified orientation angle.
    /// </summary>
    /// <param name="x">Starting X coordinate.</param>
    /// <param name="y">Starting Y coordinate.</param>
    /// <param name="theta">Starting orientation angle in degrees.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="goalAngle">Desired final orientation angle in degrees at the goal.</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithAngle(double x, double y, double theta, Guid goalId, double goalAngle, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path from the specified starting node to the goal node.
    /// This overload uses node IDs instead of coordinates, which is more efficient when the robot is already at a known node.
    /// </summary>
    /// <param name="startNodeId">Unique identifier of the starting node.</param>
    /// <param name="theta">Current orientation angle in degrees at the start node.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the start or goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanning(Guid startNodeId, double theta, Guid goalId, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path from a starting node with a specified starting direction constraint.
    /// </summary>
    /// <param name="startNodeId">Unique identifier of the starting node.</param>
    /// <param name="theta">Current orientation angle in degrees at the start node.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="startDiretion">Desired starting direction (FORWARD, BACKWARD, or NONE to use default).</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the start or goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithStartDirection(Guid startNodeId, double theta, Guid goalId, Orientation startDiretion = Orientation.NONE, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path from a starting node with a specified final direction constraint.
    /// </summary>
    /// <param name="startNodeId">Unique identifier of the starting node.</param>
    /// <param name="theta">Current orientation angle in degrees at the start node.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="goalDirection">Desired final direction at the goal (FORWARD, BACKWARD, or NONE to use default).</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the start or goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithFinalDirection(Guid startNodeId, double theta, Guid goalId, Orientation goalDirection = Orientation.NONE, CancellationToken? cancellationToken = null);

    /// <summary>
    /// Calculates a path from a starting node with a specified final angle constraint.
    /// </summary>
    /// <param name="startNodeId">Unique identifier of the starting node.</param>
    /// <param name="theta">Current orientation angle in degrees at the start node.</param>
    /// <param name="goalId">Unique identifier of the goal node.</param>
    /// <param name="goalAngle">Desired final orientation angle in degrees at the goal.</param>
    /// <param name="cancellationToken">Optional cancellation token to cancel the operation.</param>
    /// <returns>A tuple containing the sequence of nodes and edges that form the path from start to goal.</returns>
    /// <exception cref="Exception">Thrown when the start or goal node does not exist or no path can be found.</exception>
    /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled.</exception>
    /// <exception cref="TimeoutException">Thrown when the operation times out.</exception>
    (GlobalNode[] Nodes, GlobalEdge[] Edges) PathPlanningWithAngle(Guid startNodeId, double theta, Guid goalId, double goalAngle, CancellationToken? cancellationToken = null);
}