"""Small matplotlib replacement for the MATLAB arrow3 helper."""

from __future__ import annotations

from typing import Sequence

import numpy as np
from mpl_toolkits.mplot3d.axes3d import Axes3D


def arrow3(
    p0: Sequence[float],
    p1: Sequence[float],
    style: str = "3_v",
    scale: Sequence[float] | None = None,
    ax: Axes3D | None = None,
):
    del style  # retained for call compatibility
    if ax is None:
        import matplotlib.pyplot as plt

        ax = plt.gca()
    p0a = np.asarray(p0, dtype=float)
    p1a = np.asarray(p1, dtype=float)
    d = p1a - p0a
    arrow_scale = float(scale[0]) if scale else 1.0
    return ax.quiver(
        p0a[0],
        p0a[1],
        p0a[2],
        d[0],
        d[1],
        d[2],
        color="k",
        linewidth=1.5,
        arrow_length_ratio=0.12 * arrow_scale,
        normalize=False,
    )
