TrajectoryData

@staticmethod
def name(value: int | TrajFlag) -> str:
    """Get the human-readable name for a trajectory flag value.

    Converts a numeric flag value to its corresponding string name for
    display, logging, or debugging purposes. Supports both individual
    flags and combined flag values with intelligent formatting.

    Args:
        value: The TrajFlag enum value or integer flag to convert.

    Returns:
        String name of the flag. For combined flags, returns names joined with "|".
            For unknown flags, returns "UNKNOWN". Special handling for ZERO flag combinations.

    Examples:
        ```python
        # Individual flag names
        print(TrajFlag.name(TrajFlag.ZERO))      # "ZERO"
        print(TrajFlag.name(TrajFlag.APEX))      # "APEX"

        # Combined flags
        combined = TrajFlag.ZERO | TrajFlag.APEX
        print(TrajFlag.name(combined))           # "ZERO|APEX"

        # Unknown flags
        print(TrajFlag.name(999))                # "UNKNOWN"
        ```
    """
    v = int(value)
    mapping = TrajFlag._value_to_name()
    if v in mapping:
        return mapping[v]
    parts = [mapping[bit] for bit in sorted(mapping) if bit and (v & bit) == bit]
    if "ZERO_UP" in parts and "ZERO_DOWN" in parts:
        parts.remove("ZERO_UP")
        parts.remove("ZERO_DOWN")
    return "|".join(parts) if parts else "UNKNOWN"

@staticmethod
def interpolate(
    key_attribute: BaseTrajDataAttribute,
    key_value: float,
    p0: BaseTrajData,
    p1: BaseTrajData,
    p2: BaseTrajData,
    method: InterpolationMethod = "pchip",
) -> BaseTrajData:
    """
    Interpolate a BaseTrajData point using monotone PCHIP (default) or linear.

    Args:
        key_attribute: Can be 'time', 'mach', or a vector component like 'position.x' or 'velocity.z'.
        key_value: The value to interpolate for.
        p0: First bracketing point.
        p1: Second (middle) bracketing point.
        p2: Third bracketing point.
        method: 'pchip' (default, monotone cubic Hermite) or 'linear'.

    Returns:
        The interpolated data point.

    Raises:
        AttributeError: If the key_attribute is not a member of BaseTrajData.
        ZeroDivisionError: If the interpolation fails due to zero division.
                           (This will result if two of the points are identical).
        ValueError: If method is not one of 'pchip' or 'linear'.
    """

    def get_key_val(td: BaseTrajData, path: str) -> float:
        """Helper to get the key value from a BaseTrajData point."""
        if "." in path:
            top, component = path.split(".", 1)
            obj = getattr(td, top)
            return getattr(obj, component)
        return getattr(td, path)

    # independent variable values
    x0 = get_key_val(p0, key_attribute)
    x1 = get_key_val(p1, key_attribute)
    x2 = get_key_val(p2, key_attribute)

    def _interp_scalar(y0, y1, y2):
        if method == "pchip":
            return interpolate_3_pt(key_value, x0, y0, x1, y1, x2, y2)
        elif method == "linear":
            pts = sorted(((x0, y0), (x1, y1), (x2, y2)), key=lambda p: p[0])
            (sx0, sy0), (sx1, sy1), (sx2, sy2) = pts
            if key_value <= sx1:
                return interpolate_2_pt(key_value, sx0, sy0, sx1, sy1)
            else:
                return interpolate_2_pt(key_value, sx1, sy1, sx2, sy2)
        else:
            raise ValueError("method must be 'pchip' or 'linear'")

    vp0 = p0.position
    vp1 = p1.position
    vp2 = p2.position
    vv0 = p0.velocity
    vv1 = p1.velocity
    vv2 = p2.velocity

    time = _interp_scalar(p0.time, p1.time, p2.time) if key_attribute != "time" else key_value
    position = Vector(
        _interp_scalar(vp0.x, vp1.x, vp2.x),
        _interp_scalar(vp0.y, vp1.y, vp2.y),
        _interp_scalar(vp0.z, vp1.z, vp2.z),
    )
    velocity = Vector(
        _interp_scalar(vv0.x, vv1.x, vv2.x),
        _interp_scalar(vv0.y, vv1.y, vv2.y),
        _interp_scalar(vv0.z, vv1.z, vv2.z),
    )
    mach = _interp_scalar(p0.mach, p1.mach, p2.mach) if key_attribute != "mach" else key_value

    return BaseTrajData(time=time, position=position, velocity=velocity, mach=mach)

@deprecated(reason="Use .slant_distance instead of .look_distance", version="2.2.0")
def look_distance(self) -> Distance:
    """Synonym for slant_distance."""
    return self.slant_distance

def formatted(self) -> tuple[str, ...]:
    """Return attributes as tuple of strings, formatted per PreferredUnits.

    Returns:
        Tuple of formatted strings for this point, in PreferredUnits.
    """

    def _fmt(v: GenericDimension, u: Unit) -> str:
        """Format Dimension as a string."""
        return f"{v >> u:.{u.accuracy}f} {u.symbol}"

    return (
        f"{self.time:.3f} s",
        _fmt(self.distance, PreferredUnits.distance),
        _fmt(self.velocity, PreferredUnits.velocity),
        f"{self.mach:.2f} mach",
        _fmt(self.height, PreferredUnits.drop),
        _fmt(self.slant_height, PreferredUnits.drop),
        _fmt(self.drop_angle, PreferredUnits.adjustment),
        _fmt(self.windage, PreferredUnits.drop),
        _fmt(self.windage_angle, PreferredUnits.adjustment),
        _fmt(self.slant_distance, PreferredUnits.distance),
        _fmt(self.angle, PreferredUnits.angular),
        f"{self.density_ratio:.5e}",
        f"{self.drag:.3e}",
        _fmt(self.energy, PreferredUnits.energy),
        _fmt(self.ogw, PreferredUnits.ogw),
        TrajFlag.name(self.flag),
    )

def in_def_units(self) -> tuple[float, ...]:
    """Return attributes as tuple of floats converting to PreferredUnits.

    Returns:
        Tuple of floats describing this point, in PreferredUnits.
    """
    return (
        self.time,
        self.distance >> PreferredUnits.distance,
        self.velocity >> PreferredUnits.velocity,
        self.mach,
        self.height >> PreferredUnits.drop,
        self.slant_height >> PreferredUnits.drop,
        self.drop_angle >> PreferredUnits.adjustment,
        self.windage >> PreferredUnits.drop,
        self.windage_angle >> PreferredUnits.adjustment,
        self.slant_distance >> PreferredUnits.distance,
        self.angle >> PreferredUnits.angular,
        self.density_ratio,
        self.drag,
        self.energy >> PreferredUnits.energy,
        self.ogw >> PreferredUnits.ogw,
        self.flag,
    )

@staticmethod
def get_correction(distance: float, offset: float) -> float:
    """Calculate the sight adjustment in radians.

    Args:
        distance: The distance to the target in feet.
        offset: The offset from the target in feet.

    Returns:
        The sight adjustment in radians.
    """
    if distance != 0:
        return math.atan(offset / distance)
    return 0  # None

@staticmethod
def calculate_energy(bullet_weight: float, velocity: float) -> float:
    """Calculate the kinetic energy of a projectile.

    Args:
        bullet_weight: Projectile weight in grains.
        velocity: Projectile velocity in feet per second.

    Returns:
        Kinetic energy in foot-pounds (ft·lbf).

    Notes:
        Uses the standard small-arms approximation:
        E(ft·lbf) = weight(grains) * v(fps)^2 / 450400.
    """
    return bullet_weight * math.pow(velocity, 2) / 450400

@staticmethod
def calculate_ogw(bullet_weight: float, velocity: float) -> float:
    """Calculate the optimal game weight for a projectile.

    Args:
        bullet_weight: Bullet weight in grains (per common OGW formula).
        velocity: Projectile velocity in feet per second.

    Returns:
        The optimal game weight in pounds.
    """
    return math.pow(bullet_weight, 2) * math.pow(velocity, 3) * 1.5e-12

@staticmethod
def from_base_data(props: ShotProps, data: BaseTrajData, flag: TrajFlag | int = TrajFlag.NONE) -> TrajectoryData:
    """Create a TrajectoryData object from BaseTrajData."""
    return TrajectoryData.from_props(props, data.time, data.position, data.velocity, data.mach, flag)

@staticmethod
def from_props(
    props: ShotProps,
    time: float,
    range_vector: Vector,
    velocity_vector: Vector,
    mach: float,
    flag: TrajFlag | int = TrajFlag.NONE,
) -> TrajectoryData:
    """Create a TrajectoryData object."""
    adjusted_range = props.adjust_range_for_coriolis(time, range_vector)
    spin_drift = props.spin_drift(time)
    velocity = velocity_vector.magnitude()
    windage = adjusted_range.z + spin_drift
    drop_angle = TrajectoryData.get_correction(adjusted_range.x, adjusted_range.y)
    windage_angle = TrajectoryData.get_correction(adjusted_range.x, windage)
    trajectory_angle = math.atan2(velocity_vector.y, velocity_vector.x)
    look_angle_cos = math.cos(props.look_angle_rad)
    look_angle_sin = math.sin(props.look_angle_rad)
    density_ratio, _ = props.get_density_and_mach_for_altitude(range_vector.y)
    drag = props.drag_by_mach(velocity / mach)
    return TrajectoryData(
        time=time,
        distance=TrajectoryData._new_feet(adjusted_range.x),
        velocity=TrajectoryData._new_fps(velocity),
        mach=velocity / mach,
        height=TrajectoryData._new_feet(adjusted_range.y),
        slant_height=TrajectoryData._new_feet(
            adjusted_range.y * look_angle_cos - adjusted_range.x * look_angle_sin
        ),
        drop_angle=TrajectoryData._new_rad(drop_angle - (props.look_angle_rad if adjusted_range.x else 0)),
        windage=TrajectoryData._new_feet(windage),
        windage_angle=TrajectoryData._new_rad(windage_angle),
        slant_distance=TrajectoryData._new_feet(
            adjusted_range.x * look_angle_cos + adjusted_range.y * look_angle_sin
        ),
        angle=TrajectoryData._new_rad(trajectory_angle),
        density_ratio=density_ratio,
        drag=drag,
        energy=TrajectoryData._new_ft_lb(TrajectoryData.calculate_energy(props.weight_grains, velocity)),
        ogw=TrajectoryData._new_lb(TrajectoryData.calculate_ogw(props.weight_grains, velocity)),
        flag=flag,
    )

@staticmethod
def interpolate(
    key_attribute: TrajectoryDataAttribute,
    value: float | GenericDimension,
    p0: TrajectoryData,
    p1: TrajectoryData,
    p2: TrajectoryData,
    flag: TrajFlag | int = TrajFlag.NONE,
    method: InterpolationMethod = "pchip",
) -> TrajectoryData:
    """
    Interpolate TrajectoryData where key_attribute==value using PCHIP (default) or linear.

    Args:
        key_attribute: Attribute to key on (e.g., 'time', 'distance').
        value: Target value for the key attribute. A bare float is treated as
            raw value for dimensioned fields.
        p0: First bracketing point.
        p1: Second (middle) bracketing point.
        p2: Third bracketing point.
        flag: Flag to assign to the new point.
        method: 'pchip' (monotone cubic Hermite) or 'linear'.

    Returns:
        Interpolated point with key_attribute==value.

    Raises:
        AttributeError: If TrajectoryData doesn't have the specified attribute.
        KeyError: If the key_attribute is 'flag'.
        ZeroDivisionError: If interpolation fails due to zero division.
        ValueError: If method is not one of 'pchip' or 'linear'.
    """
    key_attribute = TRAJECTORY_DATA_SYNONYMS.get(key_attribute, key_attribute)  # Resolve synonyms
    if not hasattr(TrajectoryData, key_attribute):
        raise AttributeError(f"TrajectoryData has no attribute '{key_attribute}'")
    if key_attribute == "flag":
        raise KeyError("Cannot interpolate based on 'flag' attribute")
    key_value = value.raw_value if isinstance(value, GenericDimension) else value

    def get_key_val(td):
        """Helper to get the raw value of the key attribute from a TrajectoryData point."""
        val = getattr(td, key_attribute)
        return val.raw_value if hasattr(val, "raw_value") else float(val)

    # The independent variable for interpolation (x-axis)
    x_val = key_value
    x0, x1, x2 = get_key_val(p0), get_key_val(p1), get_key_val(p2)

    # Use reflection to build the new TrajectoryData object
    interpolated_fields: dict[str, Any] = {}
    for field_name in TrajectoryData._fields:
        if field_name == "flag":
            continue

        p0_field = getattr(p0, field_name)

        if field_name == key_attribute:
            if isinstance(value, GenericDimension):
                interpolated_fields[field_name] = value
            else:  # value is a float, assume it's in the same unit as the original data
                if isinstance(p0_field, GenericDimension):
                    interpolated_fields[field_name] = type(p0_field).new_from_raw(float(value), p0_field.units)
                else:
                    interpolated_fields[field_name] = float(value)
            continue

        # Interpolate all other fields
        y0_val = p0_field
        y1_val = getattr(p1, field_name)
        y2_val = getattr(p2, field_name)

        if isinstance(y0_val, GenericDimension):
            y0, y1, y2 = y0_val.raw_value, y1_val.raw_value, y2_val.raw_value
            if method == "pchip":
                interpolated_raw = interpolate_3_pt(x_val, x0, y0, x1, y1, x2, y2)
            elif method == "linear":
                interpolated_raw = (
                    interpolate_2_pt(x_val, x0, y0, x1, y1)
                    if x_val <= x1
                    else interpolate_2_pt(x_val, x1, y1, x2, y2)
                )
            else:
                raise ValueError("method must be 'pchip' or 'linear'")
            interpolated_fields[field_name] = type(y0_val).new_from_raw(interpolated_raw, y0_val.units)
        elif isinstance(y0_val, float | int):
            fy0, fy1, fy2 = float(y0_val), float(y1_val), float(y2_val)
            if method == "pchip":
                interpolated_fields[field_name] = interpolate_3_pt(x_val, x0, fy0, x1, fy1, x2, fy2)
            elif method == "linear":
                interpolated_fields[field_name] = (
                    interpolate_2_pt(x_val, x0, fy0, x1, fy1)
                    if x_val <= x1
                    else interpolate_2_pt(x_val, x1, fy1, x2, fy2)
                )
            else:
                raise ValueError("method must be 'pchip' or 'linear'")
        else:
            raise TypeError(f"Cannot interpolate field '{field_name}' of type {type(y0_val)}")

    interpolated_fields["flag"] = flag
    return TrajectoryData(**interpolated_fields)

def record_initial(self, data: BaseTrajData) -> None:
    """Record the launch state before any accepted interval exists."""
    if self.prev_data is not None:
        raise RuntimeError("TrajectoryDataFilter was initialized twice")
    self.init(data)
    self._append(data, TrajFlag.RANGE if (self.range_step > 0 or self.time_step > 0) else TrajFlag.NONE)
    self.prev_data = data

def record_step(self, start: BaseTrajData, end: BaseTrajData) -> None:
    """Emit all scheduled samples and one-shot events between *start* and *end*."""
    if self.prev_data is None:
        self.record_initial(start)
    elif start != self.prev_data:
        raise ValueError("Trajectory steps must be contiguous")

    step = TrajectoryStep(start, end)
    rows: list[tuple[BaseTrajData, TrajFlag | int]] = []

    def add(data: BaseTrajData, flag: TrajFlag | int) -> None:
        rows.append((data, flag))

    if self.range_step > 0:
        while self.next_record_distance + self.range_step <= end.position.x:
            distance = self.next_record_distance + self.range_step
            if distance > self.range_limit + self.EPSILON:
                self.range_step = -1
                break
            if distance >= start.position.x - self.EPSILON:
                sample = step.at_x(distance)
                add(sample, TrajFlag.RANGE)
                # RANGE and TIME samples share one "last record" clock:
                # a time schedule starts from the most recently emitted
                # RANGE row, matching the long-standing filter contract.
                self.time_of_last_record = sample.time
            self.next_record_distance = distance

    if self.time_step > 0:
        while self.time_of_last_record + self.time_step <= end.time:
            self.time_of_last_record += self.time_step
            if self.time_of_last_record >= start.time:
                add(step.at_time(self.time_of_last_record), TrajFlag.RANGE)

    if self.filter & TrajFlag.APEX and start.velocity.y > 0.0 >= end.velocity.y:
        add(step.at_value(lambda data: data.velocity.y, 0.0), TrajFlag.APEX)
        self.filter &= ~TrajFlag.APEX

    mach_ratio = lambda data: data.velocity.magnitude() / data.mach
    if self.filter & TrajFlag.MACH and mach_ratio(start) > 1.0 > mach_ratio(end):
        add(step.at_value(mach_ratio, 1.0), TrajFlag.MACH)
        self.filter &= ~TrajFlag.MACH

    sight_height = lambda data: data.position.y - data.position.x * self.look_angle_tangent
    if self.filter & TrajFlag.ZERO_UP and sight_height(start) < 0.0 < sight_height(end):
        add(step.at_value(sight_height, 0.0), TrajFlag.ZERO_UP)
        self.filter &= ~TrajFlag.ZERO_UP
    elif self.filter & TrajFlag.ZERO_DOWN and sight_height(start) > 0.0 > sight_height(end):
        add(step.at_value(sight_height, 0.0), TrajFlag.ZERO_DOWN)
        self.filter &= ~TrajFlag.ZERO_DOWN

    for data, flag in sorted(rows, key=lambda row: row[0].time):
        self._append(data, flag)
    self.prev_data = end

def record(self, data: BaseTrajData) -> None:
    """Compatibility adapter for callers that still provide endpoints."""
    if self.prev_data is None:
        self.record_initial(data)
    else:
        self.record_step(self.prev_data, data)