@jjlmoya/utils-nautical 1.22.0 → 1.23.0

package/src/tool/hullSpeed/i18n/zh.ts

@@ -0,0 +1,199 @@
+import { bibliography } from '../bibliography';
+import type { HullSpeedLocaleContent, HullSpeedUI } from '../index';
+import type { FAQPage, HowTo, SoftwareApplication, WithContext } from 'schema-dts';
+
+const slug = 'sailboat-hull-speed-calculator';
+const title = '帆船船体速度计算器';
+const description =
+  '由水线长度求出理论船体速度，对照实测航程仪读数，并看排水型船体何时爬上自己的艏波。';
+
+const ui: HullSpeedUI = {
+  metric: '公制',
+  imperial: '英制',
+  unitGroup: '单位',
+  sceneLabel: '水线与艏波',
+  hullSpeedLabel: '船体速度',
+  knotsUnit: 'kn',
+  kmhUnit: 'km/h',
+  mphUnit: 'mph',
+  ratioLabel: 'S/L',
+  froudeLabel: 'Fr',
+  lwlLabelMetric: '水线长度',
+  lwlLabelImperial: '水线长度',
+  lwlUnitM: 'm',
+  lwlUnitFt: 'ft',
+  observedLabel: '航程仪速度',
+  observedHint: '留 0 以绘制理论波。输入航程仪读数，看你是否仍坐在波谷里。',
+  stretchHint: '拖动船体以拉长水线',
+  hullKindLabel: '船体形状',
+  displacement: '排水型',
+  semi: '半排水型',
+  planing: '滑行型',
+  boatsLabel: '水线示例',
+  dinghy: '小艇',
+  daysailer: '日航帆船',
+  cruiser: '巡航船',
+  bluewater: '远海',
+  workboat: '工作船',
+  bandBelow: '仍是短波',
+  bandNear: '接近波浪屏障',
+  bandAt: '骑在艏波上',
+  bandAbove: '正试图爬上波浪',
+  bandPlane: '已滑行，超过船体速度',
+  planingNote:
+    '滑行型船体可以把这道波甩在后面。船体速度是参照，不是墙。',
+  displacementNote:
+    '排水型追上自己的伴流时会付出陡峭代价。把它当成实用上限，不是 GPS 目标。',
+  semiNote:
+    '半排水型在功率足够时可以略微超过经典比值，但阻力会急剧上升。',
+  waveLegend: '艏波',
+  waterLegend: '水线',
+  markLegend: '船体速度',
+  faqTitle: '船体速度问题',
+  bibliographyTitle: '参考文献',
+};
+
+const faq: HullSpeedLocaleContent['faq'] = [
+  {
+    question: '帆船的船体速度是什么?',
+    answer:
+      '排水型船体带着大约与自身水线等长的艏波前进时的速度。航海单位里通常用 1.34 乘以英尺水线长度的平方根来估计。这是临界速度，不是硬性的物理停点。',
+  },
+  {
+    question: '如何计算船体速度?',
+    answer:
+      '把水线换成英尺，开平方，再乘 1.34 得到节。10 m 水线约 32.8 ft，所以大约 7.7 kn。同一点对应弗劳德数约 0.40。',
+  },
+  {
+    question: '滑行艇也适用船体速度吗?',
+    answer:
+      '公式仍描述船体若停留在排水模式会造出的波。滑行型和许多半排水型就是为了爬过那道波而设计的。把数字当参照，再读船体形状说明。',
+  },
+  {
+    question: '该用水线长还是总长?',
+    answer:
+      '用水线长 (LWL)，也就是真正造波的浸水长度。总长、艏斜桅和悬伸并不决定波长。在水里量 LWL，不要用量册上的 LOA。',
+  },
+];
+
+const howTo: HullSpeedLocaleContent['howTo'] = [
+  {
+    name: '拉长水线',
+    text: '拖动船体、移动水线滑轨，或从小艇选到工作船。船体速度是该长度(英尺)平方根的 1.34 倍。',
+  },
+  {
+    name: '选择船体形状',
+    text: '排水型、半排水型或滑行型会改变龙骨，以及船能否爬出自己的波。',
+  },
+  {
+    name: '读波谷',
+    text: '在船体速度时，艏波和艉波相隔一条水线，船坐在谷里。那就是屏障。',
+  },
+  {
+    name: '对照航程仪',
+    text: '输入对水速度。较短的波表示你仍推得便宜。较长的波表示你正在爬谷。',
+  },
+];
+
+const seo: HullSpeedLocaleContent['seo'] = [
+  {
+    type: 'title',
+    text: '船体速度真正在说什么',
+    level: 2,
+  },
+  {
+    type: 'paragraph',
+    html: '排水型船体从船首推一道波，从船尾再推一道。当这两道峰大约相隔一条水线时，船就带着自己的伴流走。多余功率这时主要把水堆起来，而不是买速度。水手把这种状态叫做船体速度。',
+  },
+  {
+    type: 'paragraph',
+    html: '本计算器使用常见的业余比值：每英尺水线平方根 1.34 节。细长船体可以略高，驳船更低。把结果当教学记号，再拿真实航程仪对照。',
+  },
+  {
+    type: 'title',
+    text: '算过的水线例子',
+    level: 2,
+  },
+  {
+    type: 'table',
+    headers: ['水线', '船体速度', '典型船只'],
+    rows: [
+      ['4.2 m / 13.8 ft', '5.0 kn', '小艇'],
+      ['6.5 m / 21.3 ft', '6.2 kn', '日航帆船'],
+      ['10 m / 32.8 ft', '7.7 kn', '家庭巡航船'],
+      ['13.5 m / 44.3 ft', '8.9 kn', '远海游艇'],
+      ['18 m / 59.1 ft', '10.3 kn', '小型工作船'],
+    ],
+  },
+  {
+    type: 'title',
+    text: '如何读艏波',
+    level: 2,
+  },
+  {
+    type: 'list',
+    items: [
+      '标记以下时波短，船仍便宜推动。',
+      '靠近标记时艏波变陡，燃油或帆买到的速度变少。',
+      '正好在标记上时波长等于 LWL。排水型处于经典屏障。',
+      '再往上，排水型爬自己的伴流。滑行型可能已经抬起来。',
+    ],
+  },
+  {
+    type: 'tip',
+    title: '量 LWL，不要量 LOA',
+    html: '宣传册长度包含悬伸。波浪在乎浸入的水线。若只有 LOA，算出的船体速度会偏乐观。',
+  },
+  {
+    type: 'title',
+    text: '一句话里的弗劳德数',
+    level: 2,
+  },
+  {
+    type: 'paragraph',
+    html: '船体速度是把弗劳德数约 0.40 包成好用的形式：速度除以重力乘长度的平方根。所以即使船体形状不变，更长的水线也更快。抬高排水极限的干净办法是拉长 LWL，不是加马力。',
+  },
+];
+
+const schemas: HullSpeedLocaleContent['schemas'] = [
+  {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareApplication',
+    name: title,
+    description,
+    applicationCategory: 'UtilityApplication',
+    operatingSystem: 'Web',
+    offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  } as WithContext<SoftwareApplication>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: faq.map((item) => ({
+      '@type': 'Question',
+      name: item.question,
+      acceptedAnswer: { '@type': 'Answer', text: item.answer },
+    })),
+  } as WithContext<FAQPage>,
+  {
+    '@context': 'https://schema.org',
+    '@type': 'HowTo',
+    name: `如何使用${title}`,
+    step: howTo.map((step) => ({
+      '@type': 'HowToStep',
+      name: step.name,
+      text: step.text,
+    })),
+  } as WithContext<HowTo>,
+];
+
+export const content: HullSpeedLocaleContent = {
+  slug,
+  title,
+  description,
+  ui,
+  seo,
+  faq,
+  bibliography,
+  howTo,
+  schemas,
+};

package/src/tool/hullSpeed/index.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../../types';
+import { hullSpeed } from './entry';
+
+export * from './entry';
+
+export const HULL_SPEED_TOOL: ToolDefinition = {
+  entry: hullSpeed,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/hullSpeed/logic.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import {
+  bandFromRatio,
+  clampLwlMetres,
+  clampObservedKnots,
+  computeHullSpeed,
+  displayLength,
+  feetToMetres,
+  froudeNumber,
+  HULL_SPEED_FACTOR,
+  hullSpeedKnotsFromLwl,
+  knotsToKmh,
+  knotsToMph,
+  LWL_MAX_M,
+  LWL_MIN_M,
+  metresToFeet,
+  speedLengthRatio,
+  storeLength,
+} from './logic';
+
+describe('hull speed geometry', () => {
+  it('converts metres and feet without drift on a round trip', () => {
+    const metres = 10;
+    expect(feetToMetres(metresToFeet(metres))).toBeCloseTo(metres, 10);
+  });
+
+  it('uses 1.34 times sqrt of waterline in feet', () => {
+    const lwlM = 10;
+    const expected = HULL_SPEED_FACTOR * Math.sqrt(metresToFeet(lwlM));
+    expect(hullSpeedKnotsFromLwl(lwlM)).toBeCloseTo(expected, 8);
+    expect(hullSpeedKnotsFromLwl(lwlM)).toBeCloseTo(7.676, 2);
+  });
+
+  it('keeps speed-length ratio equal to the factor at hull speed', () => {
+    const lwlM = 12;
+    const hs = hullSpeedKnotsFromLwl(lwlM);
+    expect(speedLengthRatio(hs, lwlM)).toBeCloseTo(HULL_SPEED_FACTOR, 8);
+  });
+
+  it('returns a Froude number near 0.40 at hull speed', () => {
+    const lwlM = 10;
+    const hs = hullSpeedKnotsFromLwl(lwlM);
+    expect(froudeNumber(hs, lwlM)).toBeGreaterThan(0.39);
+    expect(froudeNumber(hs, lwlM)).toBeLessThan(0.41);
+  });
+});
+
+describe('units and clamps', () => {
+  it('displays feet in imperial and metres in metric', () => {
+    expect(displayLength(10, 'metric')).toBe(10);
+    expect(displayLength(10, 'imperial')).toBeCloseTo(metresToFeet(10), 8);
+    expect(storeLength(32.80839895013123, 'imperial')).toBeCloseTo(10, 6);
+    expect(storeLength(10, 'metric')).toBe(10);
+  });
+
+  it('clamps waterline and observed speed', () => {
+    expect(clampLwlMetres(Number.NaN)).toBe(LWL_MIN_M);
+    expect(clampLwlMetres(0)).toBe(LWL_MIN_M);
+    expect(clampLwlMetres(99)).toBe(LWL_MAX_M);
+    expect(clampObservedKnots(-4)).toBe(0);
+    expect(clampObservedKnots(Number.NaN)).toBe(0);
+    expect(clampObservedKnots(80)).toBe(40);
+  });
+
+  it('converts knots to km/h and mph', () => {
+    expect(knotsToKmh(10)).toBeCloseTo(18.52, 6);
+    expect(knotsToMph(10)).toBeCloseTo(11.5078, 3);
+  });
+});
+
+describe('bands', () => {
+  it('marks below, near, at and above the wave barrier', () => {
+    expect(bandFromRatio(0.9)).toBe('below');
+    expect(bandFromRatio(1.2)).toBe('near');
+    expect(bandFromRatio(1.34)).toBe('at');
+    expect(bandFromRatio(1.8)).toBe('above');
+  });
+});
+
+describe('computeHullSpeed', () => {
+  it('uses hull speed as the compared speed when observed is zero', () => {
+    const result = computeHullSpeed({
+      lwlMetres: 10,
+      hullKind: 'displacement',
+      observedKnots: 0,
+    });
+    expect(result.band).toBe('at');
+    expect(result.hullSpeedKnots).toBeCloseTo(7.676, 2);
+    expect(result.observedKnots).toBe(0);
+  });
+
+  it('classifies an observed speed above hull speed', () => {
+    const result = computeHullSpeed({
+      lwlMetres: 10,
+      hullKind: 'planing',
+      observedKnots: 18,
+    });
+    expect(result.band).toBe('above');
+    expect(result.speedLengthRatio).toBeGreaterThan(HULL_SPEED_FACTOR);
+  });
+
+  it('treats a ratio within 0.02 of 1.34 as at hull speed', () => {
+    expect(bandFromRatio(1.33)).toBe('at');
+  });
+});

package/src/tool/hullSpeed/logic.ts

@@ -0,0 +1,116 @@
+export type UnitSystem = 'metric' | 'imperial';
+export type HullKind = 'displacement' | 'semi' | 'planing';
+export type SpeedBand = 'below' | 'near' | 'at' | 'above';
+
+export interface HullSpeedInput {
+  lwlMetres: number;
+  hullKind: HullKind;
+  observedKnots: number;
+}
+
+export interface HullSpeedResult {
+  lwlMetres: number;
+  lwlFeet: number;
+  hullKind: HullKind;
+  hullSpeedKnots: number;
+  hullSpeedKmh: number;
+  hullSpeedMph: number;
+  speedLengthRatio: number;
+  froudeNumber: number;
+  band: SpeedBand;
+  observedKnots: number;
+}
+
+export const METRES_PER_FOOT = 0.3048;
+export const HULL_SPEED_FACTOR = 1.34;
+export const GRAVITY_MS2 = 9.80665;
+export const METRES_PER_NAUTICAL_MILE = 1852;
+export const LWL_MIN_M = 2.5;
+export const LWL_MAX_M = 40;
+export const OBSERVED_MAX_KN = 40;
+export const NEAR_RATIO = 1.1;
+
+export function metresToFeet(metres: number): number {
+  return metres / METRES_PER_FOOT;
+}
+
+export function feetToMetres(feet: number): number {
+  return feet * METRES_PER_FOOT;
+}
+
+export function knotsToMetresPerSecond(knots: number): number {
+  return (knots * METRES_PER_NAUTICAL_MILE) / 3600;
+}
+
+export function knotsToKmh(knots: number): number {
+  return knots * 1.852;
+}
+
+export function knotsToMph(knots: number): number {
+  return knotsToKmh(knots) / 1.609344;
+}
+
+export function clampLwlMetres(metres: number): number {
+  if (Number.isNaN(metres)) return LWL_MIN_M;
+  return Math.min(LWL_MAX_M, Math.max(LWL_MIN_M, metres));
+}
+
+export function clampObservedKnots(knots: number): number {
+  if (Number.isNaN(knots) || knots < 0) return 0;
+  return Math.min(OBSERVED_MAX_KN, knots);
+}
+
+export function displayLength(metres: number, unit: UnitSystem): number {
+  if (unit === 'imperial') return metresToFeet(metres);
+  return metres;
+}
+
+export function storeLength(displayed: number, unit: UnitSystem): number {
+  if (unit === 'imperial') return feetToMetres(displayed);
+  return displayed;
+}
+
+export function hullSpeedKnotsFromLwl(lwlMetres: number): number {
+  const feet = metresToFeet(clampLwlMetres(lwlMetres));
+  return HULL_SPEED_FACTOR * Math.sqrt(feet);
+}
+
+export function speedLengthRatio(speedKnots: number, lwlMetres: number): number {
+  const feet = metresToFeet(clampLwlMetres(lwlMetres));
+  const root = Math.sqrt(feet);
+  if (root === 0) return 0;
+  return speedKnots / root;
+}
+
+export function froudeNumber(speedKnots: number, lwlMetres: number): number {
+  const length = clampLwlMetres(lwlMetres);
+  const denom = Math.sqrt(GRAVITY_MS2 * length);
+  if (denom === 0) return 0;
+  return knotsToMetresPerSecond(speedKnots) / denom;
+}
+
+export function bandFromRatio(ratio: number): SpeedBand {
+  if (Math.abs(ratio - HULL_SPEED_FACTOR) < 0.02) return 'at';
+  if (ratio < NEAR_RATIO) return 'below';
+  if (ratio < HULL_SPEED_FACTOR) return 'near';
+  return 'above';
+}
+
+export function computeHullSpeed(input: HullSpeedInput): HullSpeedResult {
+  const lwlMetres = clampLwlMetres(input.lwlMetres);
+  const observedKnots = clampObservedKnots(input.observedKnots);
+  const hullSpeedKnots = hullSpeedKnotsFromLwl(lwlMetres);
+  const compareKnots = observedKnots > 0 ? observedKnots : hullSpeedKnots;
+  return {
+    lwlMetres,
+    lwlFeet: metresToFeet(lwlMetres),
+    hullKind: input.hullKind,
+    hullSpeedKnots,
+    hullSpeedKmh: knotsToKmh(hullSpeedKnots),
+    hullSpeedMph: knotsToMph(hullSpeedKnots),
+    speedLengthRatio: speedLengthRatio(compareKnots, lwlMetres),
+    froudeNumber: froudeNumber(compareKnots, lwlMetres),
+    band: bandFromRatio(speedLengthRatio(compareKnots, lwlMetres)),
+    observedKnots,
+  };
+}

package/src/tool/hullSpeed/presets.ts

@@ -0,0 +1,17 @@
+export interface BoatPreset {
+  id: string;
+  lwlMetres: number;
+}
+
+export const BOAT_PRESETS: BoatPreset[] = [
+  { id: 'dinghy', lwlMetres: 4.2 },
+  { id: 'daysailer', lwlMetres: 6.5 },
+  { id: 'cruiser', lwlMetres: 10 },
+  { id: 'bluewater', lwlMetres: 13.5 },
+  { id: 'workboat', lwlMetres: 18 },
+];
+
+export function presetIdForLwl(lwlMetres: number): string | null {
+  const found = BOAT_PRESETS.find((item) => Math.abs(item.lwlMetres - lwlMetres) < 0.05);
+  return found ? found.id : null;
+}