@jjlmoya/utils-drones 1.36.0 → 1.37.0

package/src/tool/drone-mission-battery-reserve-planner/logic.ts

@@ -0,0 +1,203 @@
+export type UnitSystem = 'metric' | 'imperial';
+export type WindDirection = 'headwind' | 'tailwind' | 'crosswind';
+export type MissionStatusKey = 'optimal' | 'tight' | 'critical' | 'exceeded';
+
+export interface MissionInputs {
+  unitSystem: UnitSystem;
+  batteryCapacityMah: number;
+  voltageNominal: number;
+  averageCurrentAmps: number;
+  cruiseSpeedKmh: number;
+  oneWayDistanceKm: number;
+  targetHoverTimeMin: number;
+  windSpeedKmh: number;
+  windDirection: WindDirection;
+  reservePolicyPercent: number;
+}
+
+export interface MissionResults {
+  totalEnergyWh: number;
+  usableEnergyWh: number;
+  reserveEnergyWh: number;
+  basePowerDrawWatts: number;
+  outboundPowerWatts: number;
+  returnPowerWatts: number;
+  totalAutonomyMinutes: number;
+  outboundSpeedKmh: number;
+  returnSpeedKmh: number;
+  outboundTimeMinutes: number;
+  targetHoverTimeMinutes: number;
+  returnTimeMinutes: number;
+  totalMissionTimeMinutes: number;
+  outboundEnergyWh: number;
+  targetHoverEnergyWh: number;
+  returnEnergyWh: number;
+  missionEnergyUsedWh: number;
+  remainingEnergyLandingWh: number;
+  remainingEnergyLandingPercent: number;
+  maxSafeRadiusKm: number;
+  voltageSagWhLoss: number;
+  statusKey: MissionStatusKey;
+}
+
+const KMH_TO_MPH = 0.621371;
+const KM_TO_MILES = 0.621371;
+
+export function clampValue(val: number, min: number, max: number): number {
+  return Math.min(Math.max(val, min), max);
+}
+
+export function computeEffectiveSpeeds(
+  cruiseKmh: number,
+  windKmh: number,
+  dir: WindDirection
+): { outbound: number; returnLeg: number } {
+  if (dir === 'headwind') {
+    return { outbound: Math.max(1, cruiseKmh - windKmh), returnLeg: cruiseKmh + windKmh * 0.85 };
+  }
+  if (dir === 'tailwind') {
+    return { outbound: cruiseKmh + windKmh * 0.85, returnLeg: Math.max(1, cruiseKmh - windKmh) };
+  }
+  const effective = Math.max(1, Math.sqrt(Math.max(0, cruiseKmh * cruiseKmh - windKmh * windKmh * 0.5)));
+  return { outbound: effective, returnLeg: effective };
+}
+
+export function calculateWindPowerPenalty(
+  basePowerWatts: number,
+  cruiseKmh: number,
+  windKmh: number,
+  dir: WindDirection
+): { outboundPower: number; returnPower: number } {
+  const windRatio = windKmh / Math.max(10, cruiseKmh);
+
+  if (dir === 'headwind') {
+    return {
+      outboundPower: basePowerWatts * Math.pow(1 + 0.65 * windRatio, 1.3),
+      returnPower: basePowerWatts * Math.max(0.75, 1 - 0.35 * windRatio),
+    };
+  }
+  if (dir === 'tailwind') {
+    return {
+      outboundPower: basePowerWatts * Math.max(0.75, 1 - 0.35 * windRatio),
+      returnPower: basePowerWatts * Math.pow(1 + 0.65 * windRatio, 1.3),
+    };
+  }
+  const crossPower = basePowerWatts * (1 + 0.25 * windRatio);
+  return { outboundPower: crossPower, returnPower: crossPower };
+}
+
+export function calculateEnergyMetrics(inputs: MissionInputs): {
+  totalEnergyWh: number;
+  usableEnergyWh: number;
+  reserveEnergyWh: number;
+  basePowerDrawWatts: number;
+  totalAutonomyMinutes: number;
+  voltageSagWhLoss: number;
+} {
+  const cap = Math.max(1, inputs.batteryCapacityMah);
+  const volt = Math.max(0.1, inputs.voltageNominal);
+  const current = Math.max(0.1, inputs.averageCurrentAmps);
+  const reservePct = clampValue(inputs.reservePolicyPercent, 5, 50) / 100;
+
+  const grossWh = (cap * volt) / 1000;
+  const sagLoss = grossWh * Math.min(0.12, 0.02 + 0.015 * (current / (cap / 1000)));
+  const totalWh = Math.max(0.1, grossWh - sagLoss);
+  const reserveWh = totalWh * reservePct;
+  const usableWh = totalWh - reserveWh;
+  const baseWatts = volt * current;
+
+  return {
+    totalEnergyWh: totalWh,
+    usableEnergyWh: usableWh,
+    reserveEnergyWh: reserveWh,
+    basePowerDrawWatts: baseWatts,
+    totalAutonomyMinutes: (usableWh / baseWatts) * 60,
+    voltageSagWhLoss: sagLoss,
+  };
+}
+
+export function determineMissionStatus(
+  remainingWh: number,
+  reserveWh: number,
+  _totalEnergyWh: number
+): MissionStatusKey {
+  if (remainingWh < 0) return 'exceeded';
+  if (remainingWh < reserveWh * 0.5) return 'critical';
+  if (remainingWh < reserveWh) return 'tight';
+  return 'optimal';
+}
+
+interface LegParams {
+  distKm: number;
+  hoverMin: number;
+  baseWatts: number;
+  outboundSpeed: number;
+  returnSpeed: number;
+  outboundPower: number;
+  returnPower: number;
+}
+
+function calculateTransitLegs(p: LegParams) {
+  const outboundTimeMin = (p.distKm / p.outboundSpeed) * 60;
+  const returnTimeMin = (p.distKm / p.returnSpeed) * 60;
+  const outboundEnergyWh = (outboundTimeMin / 60) * p.outboundPower;
+  const hoverEnergyWh = (p.hoverMin / 60) * p.baseWatts;
+  const returnEnergyWh = (returnTimeMin / 60) * p.returnPower;
+
+  return {
+    outboundTimeMin, returnTimeMin, hoverTimeMin: p.hoverMin,
+    totalMissionTimeMin: outboundTimeMin + p.hoverMin + returnTimeMin,
+    outboundEnergyWh, hoverEnergyWh, returnEnergyWh,
+    totalUsedWh: outboundEnergyWh + hoverEnergyWh + returnEnergyWh,
+  };
+}
+
+interface SafeRadiusParams {
+  usableWh: number;
+  hoverWh: number;
+  outboundPower: number;
+  returnPower: number;
+  outboundSpeed: number;
+  returnSpeed: number;
+}
+
+function calculateSafeRadius(p: SafeRadiusParams): number {
+  const transitWh = Math.max(0, p.usableWh - p.hoverWh);
+  const perKm = (p.outboundPower / p.outboundSpeed) + (p.returnPower / p.returnSpeed);
+  return perKm > 0 ? Math.max(0, transitWh / perKm) : 0;
+}
+
+export function calculateMissionReserve(inputs: MissionInputs): MissionResults {
+  const e = calculateEnergyMetrics(inputs);
+  const s = computeEffectiveSpeeds(Math.max(1, inputs.cruiseSpeedKmh), Math.max(0, inputs.windSpeedKmh), inputs.windDirection);
+  const p = calculateWindPowerPenalty(e.basePowerDrawWatts, Math.max(1, inputs.cruiseSpeedKmh), Math.max(0, inputs.windSpeedKmh), inputs.windDirection);
+  const legs = calculateTransitLegs({
+    distKm: Math.max(0, inputs.oneWayDistanceKm), hoverMin: Math.max(0, inputs.targetHoverTimeMin),
+    baseWatts: e.basePowerDrawWatts, outboundSpeed: s.outbound, returnSpeed: s.returnLeg,
+    outboundPower: p.outboundPower, returnPower: p.returnPower,
+  });
+  const maxSafeRadiusKm = calculateSafeRadius({
+    usableWh: e.usableEnergyWh, hoverWh: legs.hoverEnergyWh, outboundPower: p.outboundPower,
+    returnPower: p.returnPower, outboundSpeed: s.outbound, returnSpeed: s.returnLeg,
+  });
+
+  const remWh = e.totalEnergyWh - legs.totalUsedWh;
+  return {
+    totalEnergyWh: e.totalEnergyWh, usableEnergyWh: e.usableEnergyWh, reserveEnergyWh: e.reserveEnergyWh,
+    basePowerDrawWatts: e.basePowerDrawWatts, outboundPowerWatts: p.outboundPower, returnPowerWatts: p.returnPower,
+    totalAutonomyMinutes: e.totalAutonomyMinutes, outboundSpeedKmh: s.outbound, returnSpeedKmh: s.returnLeg,
+    outboundTimeMinutes: legs.outboundTimeMin, targetHoverTimeMinutes: legs.hoverTimeMin, returnTimeMinutes: legs.returnTimeMin,
+    totalMissionTimeMinutes: legs.totalMissionTimeMin, outboundEnergyWh: legs.outboundEnergyWh, targetHoverEnergyWh: legs.hoverEnergyWh,
+    returnEnergyWh: legs.returnEnergyWh, missionEnergyUsedWh: legs.totalUsedWh, remainingEnergyLandingWh: remWh,
+    remainingEnergyLandingPercent: (remWh / e.totalEnergyWh) * 100, maxSafeRadiusKm, voltageSagWhLoss: e.voltageSagWhLoss,
+    statusKey: determineMissionStatus(remWh, e.reserveEnergyWh, e.totalEnergyWh),
+  };
+}
+
+export function convertDistance(km: number, unit: UnitSystem): number {
+  return unit === 'imperial' ? km * KM_TO_MILES : km;
+}
+
+export function convertSpeed(kmh: number, unit: UnitSystem): number {
+  return unit === 'imperial' ? kmh * KMH_TO_MPH : kmh;
+}

package/src/tool/drone-mission-battery-reserve-planner/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { droneMissionBatteryReservePlanner } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const content = await droneMissionBatteryReservePlanner.i18n[locale]?.();
+if (!content) return null;
+---
+
+{content.seo?.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/drone-mission-battery-reserve-planner/storage.ts

@@ -0,0 +1,59 @@
+import type { MissionInputs, UnitSystem, WindDirection } from './logic';
+
+const STORAGE_KEY = 'jjlmoya_drone_mission_battery_reserve_planner_state';
+
+export const DEFAULT_MISSION_INPUTS: MissionInputs = {
+  unitSystem: 'metric',
+  batteryCapacityMah: 10000,
+  voltageNominal: 22.2,
+  averageCurrentAmps: 18,
+  cruiseSpeedKmh: 45,
+  oneWayDistanceKm: 6,
+  targetHoverTimeMin: 5,
+  windSpeedKmh: 12,
+  windDirection: 'headwind',
+  reservePolicyPercent: 20,
+};
+
+function parseNumberField(val: unknown, fallback: number): number {
+  return typeof val === 'number' && !Number.isNaN(val) ? val : fallback;
+}
+
+function parseUnitSystem(val: unknown): UnitSystem {
+  return val === 'imperial' ? 'imperial' : 'metric';
+}
+
+function parseWindDirection(val: unknown): WindDirection {
+  if (val === 'tailwind' || val === 'crosswind') return val;
+  return 'headwind';
+}
+
+export function loadSavedInputs(): MissionInputs {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULT_MISSION_INPUTS;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return DEFAULT_MISSION_INPUTS;
+
+    return {
+      unitSystem: parseUnitSystem(parsed.unitSystem),
+      batteryCapacityMah: parseNumberField(parsed.batteryCapacityMah, DEFAULT_MISSION_INPUTS.batteryCapacityMah),
+      voltageNominal: parseNumberField(parsed.voltageNominal, DEFAULT_MISSION_INPUTS.voltageNominal),
+      averageCurrentAmps: parseNumberField(parsed.averageCurrentAmps, DEFAULT_MISSION_INPUTS.averageCurrentAmps),
+      cruiseSpeedKmh: parseNumberField(parsed.cruiseSpeedKmh, DEFAULT_MISSION_INPUTS.cruiseSpeedKmh),
+      oneWayDistanceKm: parseNumberField(parsed.oneWayDistanceKm, DEFAULT_MISSION_INPUTS.oneWayDistanceKm),
+      targetHoverTimeMin: parseNumberField(parsed.targetHoverTimeMin, DEFAULT_MISSION_INPUTS.targetHoverTimeMin),
+      windSpeedKmh: parseNumberField(parsed.windSpeedKmh, DEFAULT_MISSION_INPUTS.windSpeedKmh),
+      windDirection: parseWindDirection(parsed.windDirection),
+      reservePolicyPercent: parseNumberField(parsed.reservePolicyPercent, DEFAULT_MISSION_INPUTS.reservePolicyPercent),
+    };
+  } catch {
+    return DEFAULT_MISSION_INPUTS;
+  }
+}
+
+export function saveInputs(inputs: MissionInputs): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(inputs));
+  } catch {}
+}

package/src/tool/drone-mission-battery-reserve-planner/ui.ts

@@ -0,0 +1,78 @@
+export interface DroneMissionBatteryReservePlannerUI {
+  [key: string]: unknown;
+  title: string;
+  subtitle: string;
+  description: string;
+  sections: {
+    batteryPropulsion: string;
+    flightAtmosphere: string;
+  };
+  inputs: {
+    unitSystemLabel: string;
+    metricLabel: string;
+    imperialLabel: string;
+    presetLabel: string;
+    batteryCapacityLabel: string;
+    batteryVoltageLabel: string;
+    averageCurrentLabel: string;
+    cruiseSpeedLabel: string;
+    oneWayDistanceLabel: string;
+    targetHoverTimeLabel: string;
+    windSpeedLabel: string;
+    windDirectionLabel: string;
+    windHeadwindLabel: string;
+    windTailwindLabel: string;
+    windCrosswindLabel: string;
+    reservePolicyLabel: string;
+  };
+  presets: {
+    mappingSurvey: string;
+    fpvRecon: string;
+    cinematicInspection: string;
+    microRecon: string;
+    surveyMeta: string;
+    scoutMeta: string;
+    hoverMeta: string;
+  };
+  results: {
+    totalCapacityEnergy: string;
+    usableEnergy: string;
+    reserveEnergyBuffer: string;
+    totalAutonomyTime: string;
+    maxSafeMissionRadius: string;
+    outboundLegTime: string;
+    targetHoverTime: string;
+    returnLegTime: string;
+    totalMissionTime: string;
+    remainingEnergyLanding: string;
+    feasibilityStatus: string;
+    voltageSagSubLabel: string;
+    maxRadiusSubLabel: string;
+    powerSubLabel: string;
+  };
+  statusBadges: {
+    optimalTitle: string;
+    optimalSubtitle: string;
+    tightTitle: string;
+    tightSubtitle: string;
+    criticalTitle: string;
+    criticalSubtitle: string;
+    exceededTitle: string;
+    exceededSubtitle: string;
+  };
+  chart: {
+    batteryProfileTitle: string;
+    modelTitle: string;
+    windLabel: string;
+    homeNode: string;
+    targetNode: string;
+    landNode: string;
+    launchPadLabel: string;
+    surveyHoverLabel: string;
+    safeRadiusLabel: string;
+    outboundSegment: string;
+    targetSegment: string;
+    returnSegment: string;
+    reserveSegment: string;
+  };
+}

package/src/tools.ts

@@ -8,6 +8,7 @@ import { DRONE_BATTERY_C_RATING_CALCULATOR_TOOL } from './tool/drone-battery-c-r
 import { FPV_DRONE_THRUST_TO_WEIGHT_RATIO_TOOL } from './tool/fpv-drone-thrust-to-weight-ratio/index';
 import { DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL } from './tool/drone-motor-propeller-calculator/index';
 import { FPV_DRONE_SPEED_CALCULATOR_TOOL } from './tool/fpv-drone-speed-calculator/index';
+import { DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL } from './tool/drone-mission-battery-reserve-planner/index';
 import type { ToolDefinition } from './types';
 
 export const ALL_TOOLS: ToolDefinition[] = [
@@ -20,6 +21,7 @@ export const ALL_TOOLS: ToolDefinition[] = [
   FPV_DRONE_THRUST_TO_WEIGHT_RATIO_TOOL,
   DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL,
   FPV_DRONE_SPEED_CALCULATOR_TOOL,
+  DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL,
 ];
 
 export {
@@ -32,4 +34,6 @@ export {
   FPV_DRONE_THRUST_TO_WEIGHT_RATIO_TOOL,
   DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL,
   FPV_DRONE_SPEED_CALCULATOR_TOOL,
+  DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL,
 };
+