Shot

@classmethod
def create(
    cls, latitude: Optional[float], azimuth: Optional[float], muzzle_velocity_fps: float
) -> Optional[Coriolis]:
    """Build a `Coriolis` helper for a shot when latitude is available.

    Args:
        latitude: Latitude of the shooting location in degrees [-90, 90].
        azimuth: Azimuth of the shooting direction in degrees [0, 360).
        muzzle_velocity_fps: Muzzle velocity in feet per second for the projectile.

    Returns:
        A populated `Coriolis` instance when the shot specifies a latitude, otherwise `None`.

    Notes:
        When azimuth is omitted we fall back to the *flat fire* approximation, which only corrects
        for the horizontal drift term that dominates short-range, low-arc engagements.
    """
    if latitude is None:
        return None

    lat_rad = math.radians(latitude)
    sin_lat = math.sin(lat_rad)
    cos_lat = math.cos(lat_rad)

    if azimuth is None:
        return cls(
            sin_lat=sin_lat,
            cos_lat=cos_lat,
            muzzle_velocity_fps=muzzle_velocity_fps,
            sin_az=None,
            cos_az=None,
            range_east=None,
            range_north=None,
            cross_east=None,
            cross_north=None,
            flat_fire_only=True,
        )

    azimuth_rad = math.radians(azimuth)

    return cls(
        sin_lat=sin_lat,
        cos_lat=cos_lat,
        muzzle_velocity_fps=muzzle_velocity_fps,
        sin_az=math.sin(azimuth_rad),
        cos_az=math.cos(azimuth_rad),
        range_east=math.sin(azimuth_rad),
        range_north=math.cos(azimuth_rad),
        cross_east=math.cos(azimuth_rad),
        cross_north=-math.sin(azimuth_rad),
        flat_fire_only=False,
    )

def coriolis_acceleration_local(self, velocity: Vector) -> Vector:
    """Compute the Coriolis acceleration for a velocity expressed in the local frame.

    Args:
        velocity: Projectile velocity vector in the local range/up/cross basis (feet per second).

    Returns:
        A `Vector` containing the Coriolis acceleration components in the same local basis.
        Returns the `ZERO_VECTOR` when only the flat-fire approximation is available.
    """
    if not self.full_3d:
        return ZERO_VECTOR

    assert self.range_east is not None and self.range_north is not None
    assert self.cross_east is not None and self.cross_north is not None

    vel_east = velocity.x * self.range_east + velocity.z * self.cross_east
    vel_north = velocity.x * self.range_north + velocity.z * self.cross_north
    vel_up = velocity.y

    factor = -2.0 * cEarthAngularVelocityRadS
    accel_east = factor * (self.cos_lat * vel_up - self.sin_lat * vel_north)
    accel_north = factor * (self.sin_lat * vel_east)
    accel_up = factor * (-self.cos_lat * vel_east)

    accel_range = accel_east * self.range_east + accel_north * self.range_north
    accel_cross = accel_east * self.cross_east + accel_north * self.cross_north
    return Vector(accel_range, accel_up, accel_cross)

def flat_fire_offsets(self, time: float, distance_ft: float, drop_ft: float) -> Tuple[float, float]:
    """Estimate flat-fire vertical and horizontal corrections.

    Args:
        time: Time of flight in seconds for the sample point.
        distance_ft: Down-range distance in feet at the sample point.
        drop_ft: Local vertical displacement in feet (positive is up).

    Returns:
        A tuple `(vertical_ft, horizontal_ft)` of offsets that should be applied to the range/up/cross vector.
        Both values are zero when `Shot` has both latitude and azimuth and so can compute a full 3D solution.
    """
    if not self.flat_fire_only:
        return 0.0, 0.0

    horizontal = cEarthAngularVelocityRadS * distance_ft * self.sin_lat * time
    vertical = 0.0
    if self.sin_az is not None:  # This should not happen if not full_3d, but approximation provided for reference
        vertical_factor = -2.0 * cEarthAngularVelocityRadS * self.muzzle_velocity_fps * self.cos_lat * self.sin_az
        vertical = drop_ft * (vertical_factor / cGravityImperial)
    return vertical, horizontal

def adjust_range(self, time: float, range_vector: Vector) -> Vector:
    """Apply the flat-fire offsets to a range vector when necessary.

    Args:
        time: Time of flight in seconds for the sample point.
        range_vector: Original range/up/cross vector (feet) produced by the integrator.

    Returns:
        Either the original vector (for full 3D solutions) or a new vector with the flat-fire offsets applied.
    """
    if not self.flat_fire_only:
        return range_vector

    delta_y, delta_z = self.flat_fire_offsets(time, range_vector.x, range_vector.y)
    if delta_y == 0.0 and delta_z == 0.0:
        return range_vector
    return Vector(range_vector.x, range_vector.y + delta_y, range_vector.z + delta_z)