@photivra/engine 1.4.0 → 2.0.0

package/dist/motion/video-sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-sequence.js","sourceRoot":"","sources":["../../src/motion/video-sequence.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Video frame sequences. Builds a deterministic sequence of frames from the \"video\" optical capture\n * state (frameRateHz) and a shutter angle.\n *\n * Each frame is an ordinary ResolvedReleaseFrame, so the production capture snapshot and\n * image-formation plan use it unchanged. An optional electronic rolling shutter gives every frame the\n * same line-by-line exposure offsets. Frame timing, seeds and schedules depend only on the inputs and\n * the absolute frame index. They never depend on how the sequence is split into chunks, or on\n * earlier frames.\n * @see docs/MOTION_AND_SIGNAL.md#video-frame-sequences for equations, conventions and limits.\n */\n\nimport { parseEvidenceList, type EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { rejectUnknownFields, requireInputObject, requirePublicOpaqueId, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport type { ReleaseAutomationState, ResolvedReleaseFrame } from \"../capture/release-sequence.js\";\nimport { parseFocusPlane, type FocusPlane } from \"../optics/focus-state.js\";\nimport { parseOpticalProfileState, type OpticalProfileState } from \"../optics/profile-contract.js\";\nimport {\n  resolveElectronicRollingShutterExposureSchedule,\n  ELECTRONIC_ROLLING_SHUTTER_MODEL,\n  createRollingShutterCaptureExposureSchedule,\n  type ElectronicRollingShutterExposureSchedule\n} from \"../sensor/readout-exposure-linkage.js\";\nimport type { RollingSensorReadoutTimingDeclaration } from \"../sensor/readout-timing.js\";\nimport { deriveNativeSiteStreamSeedUint32 } from \"../sensor/stochastic-seed.js\";\n\nexport const VIDEO_FRAME_SEQUENCE_VERSION = \"1.0.0\" as const;\n/** Stream identifier (\"VIDF\"). Keeps per-frame video seeds separate from per-site noise streams. */\nexport const VIDEO_FRAME_SEED_STREAM_ID = 0x56494446 as const;\n/** Maximum frames per call. Resolve longer clips in chunks using firstFrameIndex. */\nexport const VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES = 100_000 as const;\n\nfunction requireFrameRate(frameRateHz: number): number {\n  if (typeof frameRateHz !== \"number\" || !Number.isFinite(frameRateHz) || frameRateHz <= 0) {\n    throw new InvalidScientificInputError(\"frameRateHz must be a finite number greater than zero.\");\n  }\n  return frameRateHz;\n}\n\nfunction requireShutterAngle(shutterAngleDegrees: number): number {\n  if (typeof shutterAngleDegrees !== \"number\" || !Number.isFinite(shutterAngleDegrees) ||\n    shutterAngleDegrees <= 0 || shutterAngleDegrees > 360) {\n    throw new InvalidScientificInputError(\"shutterAngleDegrees must lie in (0, 360].\");\n  }\n  return shutterAngleDegrees;\n}\n\n/**\n * Exposure time for a shutter angle (as on a rotary film-camera shutter): t = (angle / 360) / frameRateHz.\n * A 180° angle exposes for half of each frame period.\n */\nexport function calculateShutterAngleExposureSeconds(frameRateHz: number, shutterAngleDegrees: number): number {\n  return requireShutterAngle(shutterAngleDegrees) / 360 / requireFrameRate(frameRateHz);\n}\n\n/** Inverse of {@link calculateShutterAngleExposureSeconds}: angle = 360 · frameRateHz · t. */\nexport function calculateShutterAngleFromExposureSeconds(frameRateHz: number, exposureSeconds: number): number {\n  if (typeof exposureSeconds !== \"number\" || !Number.isFinite(exposureSeconds) || exposureSeconds <= 0) {\n    throw new InvalidScientificInputError(\"exposureSeconds must be a finite number greater than zero.\");\n  }\n  const angle = 360 * requireFrameRate(frameRateHz) * exposureSeconds;\n  if (angle > 360 * (1 + 1e-12)) {\n    throw new InvalidScientificInputError(\"Exposure longer than one frame period has no shutter angle.\");\n  }\n  return Math.min(360, angle);\n}\n\nexport interface ShutterAngleRuleAssessment {\n  frameRateHz: number;\n  shutterAngleDegrees: number;\n  exposureSeconds: number;\n  /** 1 / (2 · frameRateHz): the 180° convention. */\n  conventionExposureSeconds: number;\n  /** log2(exposure / convention): negative is shorter (crisper, more staccato) motion. */\n  deviationStops: number;\n  classification: \"matches-180-degree-convention\" | \"shorter-than-convention\" | \"longer-than-convention\";\n  /** The 180° rule is a cinematographic convention for motion-blur appearance, not a physical law. */\n  conventionNotPhysics: true;\n}\n\n/**\n * Compares a shutter angle with the 180° cinematographic convention (exposure = half the frame\n * period). Within a relative 1e-9 the angle \"matches\". Otherwise the signed deviation is reported.\n */\nexport function assessShutterAngleRule(frameRateHz: number, shutterAngleDegrees: number): ShutterAngleRuleAssessment {\n  const exposureSeconds = calculateShutterAngleExposureSeconds(frameRateHz, shutterAngleDegrees);\n  const conventionExposureSeconds = 1 / (2 * frameRateHz);\n  const ratio = exposureSeconds / conventionExposureSeconds;\n  return {\n    frameRateHz, shutterAngleDegrees, exposureSeconds, conventionExposureSeconds,\n    deviationStops: Math.log2(ratio),\n    classification: Math.abs(ratio - 1) <= 1e-9 ? \"matches-180-degree-convention\"\n      : ratio < 1 ? \"shorter-than-convention\" : \"longer-than-convention\",\n    conventionNotPhysics: true\n  };\n}\n\nexport interface ResolveVideoFrameSequenceInput {\n  sequenceId: string;\n  /** Exact optical capture state. captureMode must be \"video\", with a positive frameRateHz. */\n  opticalState: OpticalProfileState;\n  /** Shutter angle in (0, 360]; exposure = angle / 360 / frameRateHz. */\n  shutterAngleDegrees: number;\n  /** Absolute index of the first frame to resolve (default 0). */\n  firstFrameIndex?: number;\n  frameCount: number;\n  sequenceSeedUint32: number;\n  iso: number;\n  /** Defaults to the optical state's finite focus distance. */\n  focus?: FocusPlane;\n  automation: { ae: ReleaseAutomationState; af: ReleaseAutomationState; awb: ReleaseAutomationState };\n  whiteBalanceStateId?: string;\n  /** Evidence for the commanded frame rate and shutter-angle timing. Used for the exposure fact. */\n  timingEvidence: readonly EvidenceProvenance[];\n  /** Optional electronic rolling shutter applied identically to every frame. */\n  rollingShutter?: {\n    readout: RollingSensorReadoutTimingDeclaration;\n    linkageEvidence: readonly EvidenceProvenance[];\n  };\n}\n\nexport interface VideoFrameSequence {\n  version: typeof VIDEO_FRAME_SEQUENCE_VERSION;\n  sequenceId: string;\n  frameRateHz: number;\n  framePeriodSeconds: number;\n  shutterAngleDegrees: number;\n  exposureSeconds: number;\n  shutterAngleRule: ShutterAngleRuleAssessment;\n  firstFrameIndex: number;\n  frameCount: number;\n  sequenceSeedUint32: number;\n  seedDerivation: \"murmur3-x86-32(sequenceSeed, absoluteFrameIndex, VIDEO_FRAME_SEED_STREAM_ID)\";\n  frameTimeDerivation: \"absoluteFrameIndex / frameRateHz\";\n  /**\n   * Exposure schedule for each frame. It is the same for every frame; times are relative to each\n   * frame's own first-opening phase. Null when no rolling shutter is declared; the caller then\n   * supplies the global schedule of its capture mode.\n   */\n  exposureSchedule: ReturnType<typeof createRollingShutterCaptureExposureSchedule> | null;\n  rollingShutter: Pick<ElectronicRollingShutterExposureSchedule, \"modelId\" | \"modelVersion\" | \"lineScanSkewSeconds\" | \"linkage\"> | null;\n  /** Ordinary release frames: pass each to createProductionCaptureSnapshotFromReleaseFrame. */\n  frames: readonly ResolvedReleaseFrame[];\n  limitations: readonly string[];\n}\n\n/**\n * Resolves `frameCount` consecutive video frames starting at `firstFrameIndex`.\n *\n * Frame k (absolute index) opens k / frameRateHz seconds after the sequence starts, and exposes for\n * (angle / 360) / frameRateHz. Its random seed is a MurmurHash3 of (sequence seed, k, stream id).\n *\n * Every value depends only on the inputs and k. So resolving frames 0–99 at once, or as 0–49 then\n * 50–99, gives identical frames.\n *\n * With a rolling shutter, the line at normalized scan position s in frame k integrates over\n * [k/f + s·τ, k/f + s·τ + T]. τ must not exceed the frame period, so each line is read once per\n * frame.\n */\nexport function resolveVideoFrameSequence(input: ResolveVideoFrameSequenceInput): VideoFrameSequence {\n  requireInputKeys(input, \"resolveVideoFrameSequence\", [\"sequenceId\", \"opticalState\", \"shutterAngleDegrees\", \"firstFrameIndex\", \"frameCount\", \"sequenceSeedUint32\", \"iso\", \"focus\", \"automation\", \"whiteBalanceStateId\", \"timingEvidence\", \"rollingShutter\"]);\n  requireInputObject(input.automation, \"resolveVideoFrameSequence automation\");\n  rejectUnknownFields(input.automation, [\"ae\", \"af\", \"awb\"], \"resolveVideoFrameSequence automation\");\n  if (input.rollingShutter !== undefined) {\n    requireInputObject(input.rollingShutter, \"resolveVideoFrameSequence rollingShutter\");\n    rejectUnknownFields(input.rollingShutter, [\"readout\", \"linkageEvidence\"], \"resolveVideoFrameSequence rollingShutter\");\n  }\n  const sequenceId = requirePublicOpaqueId(input.sequenceId, \"Invalid video sequence ID.\");\n  const optical = parseOpticalProfileState(input.opticalState);\n  if (optical.captureMode !== \"video\") {\n    throw new InvalidConfigurationError(\"Video frame sequences require an optical state with captureMode \\\"video\\\".\");\n  }\n  const frameRateHz = optical.frameRateHz;\n  const shutterAngleDegrees = requireShutterAngle(input.shutterAngleDegrees);\n  const exposureSeconds = calculateShutterAngleExposureSeconds(frameRateHz, shutterAngleDegrees);\n  const first = input.firstFrameIndex ?? 0;\n  if (!Number.isSafeInteger(first) || first < 0 || !Number.isSafeInteger(input.frameCount) || input.frameCount < 1 ||\n    input.frameCount > VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES || first + input.frameCount - 1 > 0xffffffff) {\n    throw new InvalidScientificInputError(\"Video frames need a non-negative first index, 1–100000 frames and uint32 frame indices.\");\n  }\n  const seed = input.sequenceSeedUint32;\n  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {\n    throw new InvalidScientificInputError(\"sequenceSeedUint32 must be a uint32 integer.\");\n  }\n  if (typeof input.iso !== \"number\" || !Number.isFinite(input.iso) || input.iso <= 0) {\n    throw new InvalidScientificInputError(\"iso must be a finite number greater than zero.\");\n  }\n  const timingEvidence = parseEvidenceList(input.timingEvidence, \"video.timingEvidence\");\n  const focus = parseFocusPlane(input.focus ?? { kind: \"finite\", distanceM: optical.focusDistanceM });\n  const automation = { ae: input.automation.ae, af: input.automation.af, awb: input.automation.awb };\n  for (const state of Object.values(automation)) {\n    if (state !== \"manual\" && state !== \"locked\" && state !== \"continuous\") {\n      throw new InvalidConfigurationError(\"Video automation states must be manual, locked or continuous.\");\n    }\n  }\n  const whiteBalanceStateId = input.whiteBalanceStateId === undefined ? undefined\n    : requirePublicOpaqueId(input.whiteBalanceStateId, \"Invalid white-balance state ID.\");\n  const framePeriodSeconds = 1 / frameRateHz;\n\n  let rolling: ElectronicRollingShutterExposureSchedule | null = null;\n  if (input.rollingShutter !== undefined) {\n    rolling = resolveElectronicRollingShutterExposureSchedule({ readout: input.rollingShutter.readout,\n      nominalExposureDurationSeconds: { value: exposureSeconds, unit: \"s\", evidence: timingEvidence },\n      linkageEvidence: input.rollingShutter.linkageEvidence });\n    if (rolling.lineScanSkewSeconds > framePeriodSeconds) {\n      throw new InvalidScientificInputError(\"Rolling-shutter line skew exceeds the video frame period; lines cannot be read once per frame.\");\n    }\n  }\n\n  const start = (index: number): number => index / frameRateHz;\n  const frames: ResolvedReleaseFrame[] = Array.from({ length: input.frameCount }, (_, offset) => {\n    const frameIndex = first + offset, exposureStartTimeSeconds = start(frameIndex);\n    return {\n      sequenceId,\n      frameIndex,\n      releaseFrameId: sequenceId + \":video:\" + frameIndex,\n      exposureStartTimeSeconds,\n      exposureEndTimeSeconds: exposureStartTimeSeconds + exposureSeconds,\n      sceneTimeSecondsFromSequenceStart: exposureStartTimeSeconds,\n      startIntervalFromPreviousSeconds: frameIndex === 0 ? null : exposureStartTimeSeconds - start(frameIndex - 1),\n      timingConstraints: [\"requested-cadence\"],\n      stochasticSeedUint32: deriveNativeSiteStreamSeedUint32(seed, frameIndex, VIDEO_FRAME_SEED_STREAM_ID),\n      exposure: { aperture: optical.aperture, shutterSeconds: exposureSeconds, iso: input.iso },\n      focus: { ...focus },\n      automation: { ...automation },\n      ...(whiteBalanceStateId === undefined ? {} : { whiteBalanceStateId })\n    };\n  });\n\n  return {\n    version: VIDEO_FRAME_SEQUENCE_VERSION,\n    sequenceId,\n    frameRateHz,\n    framePeriodSeconds,\n    shutterAngleDegrees,\n    exposureSeconds,\n    shutterAngleRule: assessShutterAngleRule(frameRateHz, shutterAngleDegrees),\n    firstFrameIndex: first,\n    frameCount: input.frameCount,\n    sequenceSeedUint32: seed,\n    seedDerivation: \"murmur3-x86-32(sequenceSeed, absoluteFrameIndex, VIDEO_FRAME_SEED_STREAM_ID)\",\n    frameTimeDerivation: \"absoluteFrameIndex / frameRateHz\",\n    exposureSchedule: rolling === null ? null : createRollingShutterCaptureExposureSchedule(rolling),\n    rollingShutter: rolling === null ? null : { modelId: ELECTRONIC_ROLLING_SHUTTER_MODEL.id,\n      modelVersion: ELECTRONIC_ROLLING_SHUTTER_MODEL.version, lineScanSkewSeconds: rolling.lineScanSkewSeconds,\n      linkage: rolling.linkage },\n    frames,\n    limitations: [\n      \"Frame timing is ideal: no frame-rate drift, dropped frames, variable frame rate or sensor-mode switching.\",\n      \"Exposure follows the shutter-angle relation t = angle/360/f; automatic exposure between frames is not modeled.\",\n      \"The 180-degree rule is reported as a cinematographic convention, not a physical requirement.\",\n      \"Video encoding, compression, temporal noise reduction and frame interpolation are not modeled.\"\n    ]\n  };\n}\n"]}

package/dist/optics/aperture.d.ts

@@ -1,11 +1,11 @@
 /**
- * Module boundary and integration notes.
- * Calculates ideal regular-polygon aperture geometry and the corresponding straight-edge
- * diffraction-ray directions. This models only geometry/symmetry. It does not calculate diffraction
- * intensity, wavelength-dependent star length, blade curvature, lens aberrations, coatings, or sensor
- * blooming.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Geometry of an ideal regular-polygon aperture, and the directions of the diffraction rays (the
+ * "sunstar" spikes) its straight edges produce.
+ *
+ * This models only geometry and symmetry. It does not calculate diffraction intensity,
+ * wavelength-dependent star length, blade curvature, lens aberrations, coatings or sensor blooming.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 export interface CalculateIdealApertureInput {
@@ -28,21 +28,20 @@ export interface IdealApertureGeometry {
     /**
      * Diffraction-ray directions in degrees, normalized to [0, 360).
      *
-     * Each ray is perpendicular to a blade edge. Parallel opposite edges overlap
-     * for even blade counts; odd blade counts therefore produce twice as many
-     * visible ray directions.
+     * Each ray is perpendicular to a blade edge. With an even blade count,
+     * opposite edges are parallel and their rays overlap. An odd blade count
+     * therefore gives twice as many visible ray directions.
      */
     sunstarRayAnglesDegrees: readonly number[];
     /** Unit-circumradius regular-polygon vertices. */
     normalizedVertices: readonly ApertureVertex[];
 }
 /**
- * Calculates ideal regular-polygon aperture geometry and the corresponding
- * straight-edge diffraction-ray directions.
+ * Calculates ideal regular-polygon aperture geometry and the directions of
+ * the diffraction rays from its straight edges.
  *
- * This models only geometry/symmetry. It does not calculate diffraction
+ * This models only geometry and symmetry. It does not calculate diffraction
  * intensity, wavelength-dependent star length, blade curvature, lens
- * aberrations, coatings, or sensor blooming.
+ * aberrations, coatings or sensor blooming.
  */
 export declare function calculateIdealApertureGeometry(input: CalculateIdealApertureInput): CalculationResult<IdealApertureGeometry>;
-//# sourceMappingURL=aperture.d.ts.map

package/dist/optics/aperture.js

@@ -1,29 +1,31 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates ideal regular-polygon aperture geometry and the corresponding straight-edge
- * diffraction-ray directions. This models only geometry/symmetry. It does not calculate diffraction
- * intensity, wavelength-dependent star length, blade curvature, lens aberrations, coatings, or sensor
- * blooming.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Geometry of an ideal regular-polygon aperture, and the directions of the diffraction rays (the
+ * "sunstar" spikes) its straight edges produce.
+ *
+ * This models only geometry and symmetry. It does not calculate diffraction intensity,
+ * wavelength-dependent star length, blade curvature, lens aberrations, coatings or sensor blooming.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
 const MAX_IDEAL_APERTURE_BLADES = 1024;
 function normalizeDegrees(value) {
     const normalized = value % 360;
     return normalized < 0 ? normalized + 360 : normalized;
 }
 /**
- * Calculates ideal regular-polygon aperture geometry and the corresponding
- * straight-edge diffraction-ray directions.
+ * Calculates ideal regular-polygon aperture geometry and the directions of
+ * the diffraction rays from its straight edges.
  *
- * This models only geometry/symmetry. It does not calculate diffraction
+ * This models only geometry and symmetry. It does not calculate diffraction
  * intensity, wavelength-dependent star length, blade curvature, lens
- * aberrations, coatings, or sensor blooming.
+ * aberrations, coatings or sensor blooming.
  */
 export function calculateIdealApertureGeometry(input) {
+    requireInputKeys(input, "calculateIdealApertureGeometry", ["bladeCount", "firstBladeEdgeAngleDegrees"]);
     requirePositiveInteger("bladeCount", input.bladeCount);
     if (input.bladeCount < 3) {
         throw new InvalidScientificInputError("bladeCount must be greater than or equal to 3.");

package/dist/optics/aperture.js.map

@@ -1 +1 @@
-{"version":3,"file":"aperture.js","sourceRoot":"","sources":["../../src/optics/aperture.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"aperture.js","sourceRoot":"","sources":["../../src/optics/aperture.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Geometry of an ideal regular-polygon aperture, and the directions of the diffraction rays (the\n * \"sunstar\" spikes) its straight edges produce.\n *\n * This models only geometry and symmetry. It does not calculate diffraction intensity,\n * wavelength-dependent star length, blade curvature, lens aberrations, coatings or sensor blooming.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveInteger\n} from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nconst MAX_IDEAL_APERTURE_BLADES = 1024;\n\nexport interface CalculateIdealApertureInput {\n  /** Number of straight diaphragm blades/sides. Must be from 3 through 1024. */\n  bladeCount: number;\n  /**\n   * Rotation of the first blade edge in degrees, measured counter-clockwise\n   * in image coordinates before the diffraction-normal offset is applied.\n   */\n  firstBladeEdgeAngleDegrees?: number;\n}\n\nexport interface ApertureVertex {\n  x: number;\n  y: number;\n}\n\nexport interface IdealApertureGeometry {\n  bladeCount: number;\n  /** Number of diffraction ray directions for the ideal straight-edged polygon. */\n  sunstarRayCount: number;\n  /**\n   * Diffraction-ray directions in degrees, normalized to [0, 360).\n   *\n   * Each ray is perpendicular to a blade edge. With an even blade count,\n   * opposite edges are parallel and their rays overlap. An odd blade count\n   * therefore gives twice as many visible ray directions.\n   */\n  sunstarRayAnglesDegrees: readonly number[];\n  /** Unit-circumradius regular-polygon vertices. */\n  normalizedVertices: readonly ApertureVertex[];\n}\n\nfunction normalizeDegrees(value: number): number {\n  const normalized = value % 360;\n  return normalized < 0 ? normalized + 360 : normalized;\n}\n\n/**\n * Calculates ideal regular-polygon aperture geometry and the directions of\n * the diffraction rays from its straight edges.\n *\n * This models only geometry and symmetry. It does not calculate diffraction\n * intensity, wavelength-dependent star length, blade curvature, lens\n * aberrations, coatings or sensor blooming.\n */\nexport function calculateIdealApertureGeometry(\n  input: CalculateIdealApertureInput\n): CalculationResult<IdealApertureGeometry> {\n  requireInputKeys(input, \"calculateIdealApertureGeometry\", [\"bladeCount\", \"firstBladeEdgeAngleDegrees\"]);\n  requirePositiveInteger(\"bladeCount\", input.bladeCount);\n  if (input.bladeCount < 3) {\n    throw new InvalidScientificInputError(\n      \"bladeCount must be greater than or equal to 3.\"\n    );\n  }\n  if (input.bladeCount > MAX_IDEAL_APERTURE_BLADES) {\n    throw new InvalidScientificInputError(\n      `bladeCount must be less than or equal to ${MAX_IDEAL_APERTURE_BLADES}.`\n    );\n  }\n\n  const rawFirstBladeEdgeAngleDegrees =\n    input.firstBladeEdgeAngleDegrees ?? 0;\n  if (!Number.isFinite(rawFirstBladeEdgeAngleDegrees)) {\n    throw new InvalidScientificInputError(\n      \"firstBladeEdgeAngleDegrees must be finite.\"\n    );\n  }\n  const firstBladeEdgeAngleDegrees = normalizeDegrees(\n    rawFirstBladeEdgeAngleDegrees\n  );\n\n  const edgeStepDegrees = 360 / input.bladeCount;\n\n  const rayAngles: number[] = [];\n  for (let index = 0; index < input.bladeCount; index += 1) {\n    const bladeEdgeAngle =\n      firstBladeEdgeAngleDegrees + index * edgeStepDegrees;\n    const rayAngle = normalizeDegrees(bladeEdgeAngle + 90);\n    rayAngles.push(rayAngle);\n\n    if (input.bladeCount % 2 !== 0) {\n      rayAngles.push(normalizeDegrees(rayAngle + 180));\n    }\n  }\n\n  rayAngles.sort((left, right) => left - right);\n\n  const vertexRotationRadians =\n    ((firstBladeEdgeAngleDegrees - 90 + edgeStepDegrees / 2) * Math.PI) / 180;\n  const vertices = Array.from({ length: input.bladeCount }, (_, index) => {\n    const angle =\n      vertexRotationRadians + (index * 2 * Math.PI) / input.bladeCount;\n    return {\n      x: Math.cos(angle),\n      y: Math.sin(angle)\n    };\n  });\n\n  return calculatedResult(\n    {\n      bladeCount: input.bladeCount,\n      sunstarRayCount: rayAngles.length,\n      sunstarRayAnglesDegrees: rayAngles,\n      normalizedVertices: vertices\n    },\n    \"ideal-regular-polygon-aperture\",\n    \"1.0.0\",\n    [\n      \"Aperture opening is a regular polygon with straight edges\",\n      \"Each diffraction ray is perpendicular to a blade edge\",\n      \"Opposing parallel-edge diffraction overlaps for even blade counts\",\n      \"Ray intensity/length and blade curvature are not modeled\",\n      \"Blade count is computationally bounded to 1024\"\n    ]\n  );\n}\n"]}

package/dist/optics/atmospheric-haze.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Atmospheric haze as a scene-radiance modifier along a horizontal, homogeneous line of sight
+ * (Koschmieder 1924, Beitr. Phys. freien Atmos. 12:33; Middleton, Vision Through the Atmosphere,
+ * 1952; McCartney, Optics of the Atmosphere, 1976, ch. 1):
+ *   L(d, lambda) = L0(lambda) t + L_air(lambda) (1 - t),  t = exp(-beta(lambda) d)
+ * with extinction coefficient beta = beta_Rayleigh + beta_aerosol:
+ *   beta_Rayleigh(lambda) = beta_R,ref (lambda / lambda_ref)^(-rayleighExponent)  (Rayleigh: 4;
+ *     Bucholtz 1995, Appl. Opt. 34:2765, gives about 4.0-4.1 for air in the visible),
+ *   beta_aerosol(lambda) = beta_A,ref (lambda / lambda_ref)^(-alpha)  (Angstrom 1929, Geogr. Ann.
+ *     11:156; alpha typically about 0-2.5).
+ * L_air is the caller-supplied horizon (airlight) radiance at the same wavelength.
+ *
+ * This is an approximation. It assumes a uniform atmosphere and a single line of sight. It ignores
+ * the angular structure of multiple scattering and any gradient in sky luminance. The caller
+ * supplies the reference extinction values; none are built in.
+ *
+ * Meteorological visibility: Koschmieder's relation V = -ln(epsilon) / beta for a black target at
+ * contrast threshold epsilon (0.02 gives 3.912 / beta; the WMO meteorological optical range uses
+ * 0.05, about 3.0 / beta; WMO-No. 8, 2018, vol. I ch. 9).
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface AtmosphericExtinctionModel {
+    /** Wavelength at which the reference coefficients apply, nm. */
+    referenceWavelengthNm: number;
+    /** Molecular (Rayleigh) extinction coefficient at the reference wavelength, 1/m (>= 0). */
+    rayleighExtinctionPerMeter: number;
+    /** Aerosol extinction coefficient at the reference wavelength, 1/m (>= 0). */
+    aerosolExtinctionPerMeter: number;
+    /** Angstrom exponent alpha for the aerosol term (finite, typically 0-2.5). */
+    angstromExponent: number;
+    /** Rayleigh wavelength exponent; defaults to 4. */
+    rayleighExponent?: number;
+}
+export interface CalculateAtmosphericHazeInput {
+    /** Line-of-sight distance through the homogeneous haze, metres (>= 0). */
+    pathLengthM: number;
+    /** Wavelength, nm (same basis as the extinction data). */
+    wavelengthNm: number;
+    /** Scene (object) radiance at zero distance, any linear radiance unit (>= 0). */
+    sceneRadiance: number;
+    /** Horizon/airlight radiance in the same unit (>= 0). */
+    airlightRadiance: number;
+    extinction: AtmosphericExtinctionModel;
+}
+export interface AtmosphericHaze {
+    wavelengthNm: number;
+    pathLengthM: number;
+    rayleighExtinctionPerMeter: number;
+    aerosolExtinctionPerMeter: number;
+    extinctionPerMeter: number;
+    opticalDepth: number;
+    /** Direct transmittance t = exp(-beta d). */
+    transmittance: number;
+    /** L0 t. */
+    attenuatedSceneRadiance: number;
+    /** L_air (1 - t). */
+    airlightContribution: number;
+    /** L0 t + L_air (1 - t), in the input radiance unit. */
+    hazedRadiance: number;
+    /** Apparent contrast against the horizon divided by the intrinsic contrast: (L - L_air)/(L0 - L_air) = t. */
+    contrastTransmittance: number;
+}
+export interface CalculateExtinctionFromVisibilityInput {
+    /** Meteorological visibility, metres. */
+    visibilityM: number;
+    /** Contrast threshold epsilon in (0, 1); Koschmieder 0.02 by default, WMO MOR uses 0.05. */
+    contrastThreshold?: number;
+}
+/**
+ * Koschmieder haze at one wavelength: attenuated scene radiance plus airlight, with Rayleigh and
+ * Angstrom-law aerosol extinction.
+ */
+export declare function calculateAtmosphericHaze(input: CalculateAtmosphericHazeInput): CalculationResult<AtmosphericHaze>;
+/**
+ * Extinction coefficient from meteorological visibility with Koschmieder's relation
+ * beta = -ln(epsilon) / V.
+ */
+export declare function calculateExtinctionFromVisibility(input: CalculateExtinctionFromVisibilityInput): CalculationResult<{
+    extinctionPerMeter: number;
+    contrastThreshold: number;
+}>;

package/dist/optics/atmospheric-haze.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Atmospheric haze as a scene-radiance modifier along a horizontal, homogeneous line of sight
+ * (Koschmieder 1924, Beitr. Phys. freien Atmos. 12:33; Middleton, Vision Through the Atmosphere,
+ * 1952; McCartney, Optics of the Atmosphere, 1976, ch. 1):
+ *   L(d, lambda) = L0(lambda) t + L_air(lambda) (1 - t),  t = exp(-beta(lambda) d)
+ * with extinction coefficient beta = beta_Rayleigh + beta_aerosol:
+ *   beta_Rayleigh(lambda) = beta_R,ref (lambda / lambda_ref)^(-rayleighExponent)  (Rayleigh: 4;
+ *     Bucholtz 1995, Appl. Opt. 34:2765, gives about 4.0-4.1 for air in the visible),
+ *   beta_aerosol(lambda) = beta_A,ref (lambda / lambda_ref)^(-alpha)  (Angstrom 1929, Geogr. Ann.
+ *     11:156; alpha typically about 0-2.5).
+ * L_air is the caller-supplied horizon (airlight) radiance at the same wavelength.
+ *
+ * This is an approximation. It assumes a uniform atmosphere and a single line of sight. It ignores
+ * the angular structure of multiple scattering and any gradient in sky luminance. The caller
+ * supplies the reference extinction values; none are built in.
+ *
+ * Meteorological visibility: Koschmieder's relation V = -ln(epsilon) / beta for a black target at
+ * contrast threshold epsilon (0.02 gives 3.912 / beta; the WMO meteorological optical range uses
+ * 0.05, about 3.0 / beta; WMO-No. 8, 2018, vol. I ch. 9).
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { rejectUnknownFields, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+function requireNonNegativeFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new InvalidScientificInputError(`${name} must be finite and non-negative.`);
+    }
+    return value;
+}
+function requireFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+    return value;
+}
+/**
+ * Koschmieder haze at one wavelength: attenuated scene radiance plus airlight, with Rayleigh and
+ * Angstrom-law aerosol extinction.
+ */
+export function calculateAtmosphericHaze(input) {
+    requireInputKeys(input, "calculateAtmosphericHaze", ["pathLengthM", "wavelengthNm", "sceneRadiance", "airlightRadiance", "extinction"]);
+    const d = requireNonNegativeFinite("pathLengthM", input.pathLengthM);
+    requirePositiveFinite("wavelengthNm", input.wavelengthNm);
+    const l0 = requireNonNegativeFinite("sceneRadiance", input.sceneRadiance);
+    const lAir = requireNonNegativeFinite("airlightRadiance", input.airlightRadiance);
+    const model = input.extinction;
+    if (typeof model !== "object" || model === null) {
+        throw new InvalidConfigurationError("extinction must be an object.");
+    }
+    // A misspelt optional field (for example rayleighExponet) must not silently fall back to the default.
+    rejectUnknownFields(model, ["referenceWavelengthNm", "rayleighExtinctionPerMeter", "aerosolExtinctionPerMeter", "angstromExponent", "rayleighExponent"], "extinction");
+    requirePositiveFinite("extinction.referenceWavelengthNm", model.referenceWavelengthNm);
+    const betaR = requireNonNegativeFinite("extinction.rayleighExtinctionPerMeter", model.rayleighExtinctionPerMeter);
+    const betaA = requireNonNegativeFinite("extinction.aerosolExtinctionPerMeter", model.aerosolExtinctionPerMeter);
+    const alpha = requireFinite("extinction.angstromExponent", model.angstromExponent);
+    const rayleighExponent = model.rayleighExponent === undefined
+        ? 4
+        : requireFinite("extinction.rayleighExponent", model.rayleighExponent);
+    if (alpha < -1 || alpha > 4 || rayleighExponent < 3.5 || rayleighExponent > 4.5) {
+        throw new InvalidScientificInputError("extinction.angstromExponent must lie in [-1, 4] and rayleighExponent in [3.5, 4.5].");
+    }
+    const ratio = input.wavelengthNm / model.referenceWavelengthNm;
+    const rayleigh = betaR * ratio ** -rayleighExponent;
+    const aerosol = betaA * ratio ** -alpha;
+    const beta = rayleigh + aerosol;
+    const opticalDepth = beta * d;
+    const transmittance = Math.exp(-opticalDepth);
+    const attenuated = l0 * transmittance;
+    // -expm1(-tau) = 1 - t without cancellation for thin haze.
+    const airlight = lAir * -Math.expm1(-opticalDepth);
+    return approximationResult({
+        wavelengthNm: input.wavelengthNm,
+        pathLengthM: d,
+        rayleighExtinctionPerMeter: rayleigh,
+        aerosolExtinctionPerMeter: aerosol,
+        extinctionPerMeter: beta,
+        opticalDepth,
+        transmittance,
+        attenuatedSceneRadiance: attenuated,
+        airlightContribution: airlight,
+        hazedRadiance: attenuated + airlight,
+        contrastTransmittance: transmittance
+    }, "koschmieder-homogeneous-haze", "1.0.0", [
+        "Koschmieder model: L = L0 exp(-beta d) + L_air (1 - exp(-beta d)) along one homogeneous horizontal line of sight",
+        `Extinction = Rayleigh (lambda^-${rayleighExponent}) + aerosol Angstrom law (lambda^-${alpha}) scaled from caller reference coefficients`,
+        "Airlight radiance is caller-supplied; sky gradients, multiple-scattering angular structure, absorption bands and slant-path density changes are not modeled",
+        "Radiance unit is whatever the caller supplies; the model is linear in it"
+    ]);
+}
+/**
+ * Extinction coefficient from meteorological visibility with Koschmieder's relation
+ * beta = -ln(epsilon) / V.
+ */
+export function calculateExtinctionFromVisibility(input) {
+    requireInputKeys(input, "calculateExtinctionFromVisibility", ["visibilityM", "contrastThreshold"]);
+    requirePositiveFinite("visibilityM", input.visibilityM);
+    const epsilon = input.contrastThreshold ?? 0.02;
+    if (typeof epsilon !== "number" || !(epsilon > 0) || !(epsilon < 1)) {
+        throw new InvalidScientificInputError("contrastThreshold must lie in (0, 1).");
+    }
+    return calculatedResult({
+        extinctionPerMeter: -Math.log(epsilon) / input.visibilityM,
+        contrastThreshold: epsilon
+    }, "koschmieder-visibility-extinction", "1.0.0", [
+        "Koschmieder relation for a black target against the horizon in a homogeneous atmosphere",
+        "Threshold 0.02 is Koschmieder's; WMO meteorological optical range uses 0.05"
+    ]);
+}
+//# sourceMappingURL=atmospheric-haze.js.map

package/dist/optics/atmospheric-haze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atmospheric-haze.js","sourceRoot":"","sources":["../../src/optics/atmospheric-haze.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Atmospheric haze as a scene-radiance modifier along a horizontal, homogeneous line of sight\n * (Koschmieder 1924, Beitr. Phys. freien Atmos. 12:33; Middleton, Vision Through the Atmosphere,\n * 1952; McCartney, Optics of the Atmosphere, 1976, ch. 1):\n *   L(d, lambda) = L0(lambda) t + L_air(lambda) (1 - t),  t = exp(-beta(lambda) d)\n * with extinction coefficient beta = beta_Rayleigh + beta_aerosol:\n *   beta_Rayleigh(lambda) = beta_R,ref (lambda / lambda_ref)^(-rayleighExponent)  (Rayleigh: 4;\n *     Bucholtz 1995, Appl. Opt. 34:2765, gives about 4.0-4.1 for air in the visible),\n *   beta_aerosol(lambda) = beta_A,ref (lambda / lambda_ref)^(-alpha)  (Angstrom 1929, Geogr. Ann.\n *     11:156; alpha typically about 0-2.5).\n * L_air is the caller-supplied horizon (airlight) radiance at the same wavelength.\n *\n * This is an approximation. It assumes a uniform atmosphere and a single line of sight. It ignores\n * the angular structure of multiple scattering and any gradient in sky luminance. The caller\n * supplies the reference extinction values; none are built in.\n *\n * Meteorological visibility: Koschmieder's relation V = -ln(epsilon) / beta for a black target at\n * contrast threshold epsilon (0.02 gives 3.912 / beta; the WMO meteorological optical range uses\n * 0.05, about 3.0 / beta; WMO-No. 8, 2018, vol. I ch. 9).\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { rejectUnknownFields, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface AtmosphericExtinctionModel {\n  /** Wavelength at which the reference coefficients apply, nm. */\n  referenceWavelengthNm: number;\n  /** Molecular (Rayleigh) extinction coefficient at the reference wavelength, 1/m (>= 0). */\n  rayleighExtinctionPerMeter: number;\n  /** Aerosol extinction coefficient at the reference wavelength, 1/m (>= 0). */\n  aerosolExtinctionPerMeter: number;\n  /** Angstrom exponent alpha for the aerosol term (finite, typically 0-2.5). */\n  angstromExponent: number;\n  /** Rayleigh wavelength exponent; defaults to 4. */\n  rayleighExponent?: number;\n}\n\nexport interface CalculateAtmosphericHazeInput {\n  /** Line-of-sight distance through the homogeneous haze, metres (>= 0). */\n  pathLengthM: number;\n  /** Wavelength, nm (same basis as the extinction data). */\n  wavelengthNm: number;\n  /** Scene (object) radiance at zero distance, any linear radiance unit (>= 0). */\n  sceneRadiance: number;\n  /** Horizon/airlight radiance in the same unit (>= 0). */\n  airlightRadiance: number;\n  extinction: AtmosphericExtinctionModel;\n}\n\nexport interface AtmosphericHaze {\n  wavelengthNm: number;\n  pathLengthM: number;\n  rayleighExtinctionPerMeter: number;\n  aerosolExtinctionPerMeter: number;\n  extinctionPerMeter: number;\n  opticalDepth: number;\n  /** Direct transmittance t = exp(-beta d). */\n  transmittance: number;\n  /** L0 t. */\n  attenuatedSceneRadiance: number;\n  /** L_air (1 - t). */\n  airlightContribution: number;\n  /** L0 t + L_air (1 - t), in the input radiance unit. */\n  hazedRadiance: number;\n  /** Apparent contrast against the horizon divided by the intrinsic contrast: (L - L_air)/(L0 - L_air) = t. */\n  contrastTransmittance: number;\n}\n\nexport interface CalculateExtinctionFromVisibilityInput {\n  /** Meteorological visibility, metres. */\n  visibilityM: number;\n  /** Contrast threshold epsilon in (0, 1); Koschmieder 0.02 by default, WMO MOR uses 0.05. */\n  contrastThreshold?: number;\n}\n\nfunction requireNonNegativeFinite(name: string, value: unknown): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) {\n    throw new InvalidScientificInputError(`${name} must be finite and non-negative.`);\n  }\n  return value;\n}\n\nfunction requireFinite(name: string, value: unknown): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) {\n    throw new InvalidScientificInputError(`${name} must be finite.`);\n  }\n  return value;\n}\n\n/**\n * Koschmieder haze at one wavelength: attenuated scene radiance plus airlight, with Rayleigh and\n * Angstrom-law aerosol extinction.\n */\nexport function calculateAtmosphericHaze(\n  input: CalculateAtmosphericHazeInput\n): CalculationResult<AtmosphericHaze> {\n  requireInputKeys(input, \"calculateAtmosphericHaze\", [\"pathLengthM\", \"wavelengthNm\", \"sceneRadiance\", \"airlightRadiance\", \"extinction\"]);\n  const d = requireNonNegativeFinite(\"pathLengthM\", input.pathLengthM);\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n  const l0 = requireNonNegativeFinite(\"sceneRadiance\", input.sceneRadiance);\n  const lAir = requireNonNegativeFinite(\"airlightRadiance\", input.airlightRadiance);\n  const model = input.extinction;\n  if (typeof model !== \"object\" || model === null) {\n    throw new InvalidConfigurationError(\"extinction must be an object.\");\n  }\n  // A misspelt optional field (for example rayleighExponet) must not silently fall back to the default.\n  rejectUnknownFields(model, [\"referenceWavelengthNm\", \"rayleighExtinctionPerMeter\", \"aerosolExtinctionPerMeter\", \"angstromExponent\", \"rayleighExponent\"], \"extinction\");\n  requirePositiveFinite(\"extinction.referenceWavelengthNm\", model.referenceWavelengthNm);\n  const betaR = requireNonNegativeFinite(\n    \"extinction.rayleighExtinctionPerMeter\",\n    model.rayleighExtinctionPerMeter\n  );\n  const betaA = requireNonNegativeFinite(\n    \"extinction.aerosolExtinctionPerMeter\",\n    model.aerosolExtinctionPerMeter\n  );\n  const alpha = requireFinite(\"extinction.angstromExponent\", model.angstromExponent);\n  const rayleighExponent =\n    model.rayleighExponent === undefined\n      ? 4\n      : requireFinite(\"extinction.rayleighExponent\", model.rayleighExponent);\n  if (alpha < -1 || alpha > 4 || rayleighExponent < 3.5 || rayleighExponent > 4.5) {\n    throw new InvalidScientificInputError(\n      \"extinction.angstromExponent must lie in [-1, 4] and rayleighExponent in [3.5, 4.5].\"\n    );\n  }\n\n  const ratio = input.wavelengthNm / model.referenceWavelengthNm;\n  const rayleigh = betaR * ratio ** -rayleighExponent;\n  const aerosol = betaA * ratio ** -alpha;\n  const beta = rayleigh + aerosol;\n  const opticalDepth = beta * d;\n  const transmittance = Math.exp(-opticalDepth);\n  const attenuated = l0 * transmittance;\n  // -expm1(-tau) = 1 - t without cancellation for thin haze.\n  const airlight = lAir * -Math.expm1(-opticalDepth);\n  return approximationResult(\n    {\n      wavelengthNm: input.wavelengthNm,\n      pathLengthM: d,\n      rayleighExtinctionPerMeter: rayleigh,\n      aerosolExtinctionPerMeter: aerosol,\n      extinctionPerMeter: beta,\n      opticalDepth,\n      transmittance,\n      attenuatedSceneRadiance: attenuated,\n      airlightContribution: airlight,\n      hazedRadiance: attenuated + airlight,\n      contrastTransmittance: transmittance\n    },\n    \"koschmieder-homogeneous-haze\",\n    \"1.0.0\",\n    [\n      \"Koschmieder model: L = L0 exp(-beta d) + L_air (1 - exp(-beta d)) along one homogeneous horizontal line of sight\",\n      `Extinction = Rayleigh (lambda^-${rayleighExponent}) + aerosol Angstrom law (lambda^-${alpha}) scaled from caller reference coefficients`,\n      \"Airlight radiance is caller-supplied; sky gradients, multiple-scattering angular structure, absorption bands and slant-path density changes are not modeled\",\n      \"Radiance unit is whatever the caller supplies; the model is linear in it\"\n    ]\n  );\n}\n\n/**\n * Extinction coefficient from meteorological visibility with Koschmieder's relation\n * beta = -ln(epsilon) / V.\n */\nexport function calculateExtinctionFromVisibility(\n  input: CalculateExtinctionFromVisibilityInput\n): CalculationResult<{ extinctionPerMeter: number; contrastThreshold: number }> {\n  requireInputKeys(input, \"calculateExtinctionFromVisibility\", [\"visibilityM\", \"contrastThreshold\"]);\n  requirePositiveFinite(\"visibilityM\", input.visibilityM);\n  const epsilon = input.contrastThreshold ?? 0.02;\n  if (typeof epsilon !== \"number\" || !(epsilon > 0) || !(epsilon < 1)) {\n    throw new InvalidScientificInputError(\"contrastThreshold must lie in (0, 1).\");\n  }\n  return calculatedResult(\n    {\n      extinctionPerMeter: -Math.log(epsilon) / input.visibilityM,\n      contrastThreshold: epsilon\n    },\n    \"koschmieder-visibility-extinction\",\n    \"1.0.0\",\n    [\n      \"Koschmieder relation for a black target against the horizon in a homogeneous atmosphere\",\n      \"Threshold 0.02 is Koschmieder's; WMO meteorological optical range uses 0.05\"\n    ]\n  );\n}\n"]}

package/dist/optics/brown-conrady-distortion.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Generic Brown-Conrady lens distortion: radial (k1, k2, k3) plus tangential/decentering (p1, p2)
+ * terms on normalized image-plane coordinates (x, y) = point / normalizationRadiusMm, r^2 = x^2 + y^2:
+ *   x_d = x (1 + k1 r^2 + k2 r^4 + k3 r^6) + 2 p1 x y + p2 (r^2 + 2 x^2)
+ *   y_d = y (1 + k1 r^2 + k2 r^4 + k3 r^6) + p1 (r^2 + 2 y^2) + 2 p2 x y
+ * In vector form the tangential term is r^2 P + 2 (P . u) u with P = (p2, p1), so (p1, p2) rotate as
+ * a vector with the image.
+ *
+ * Sources: Conrady 1919 (MNRAS 79:384, decentred lens systems); Brown 1966
+ * (Photogrammetric Engineering 32:444, "Decentering distortion of lenses"); Brown 1971 (Photogramm.
+ * Eng. 37:855, close-range camera calibration). The coefficient layout follows the widely used
+ * Brown-Conrady convention (for example Heikkila & Silven 1997, CVPR). The coefficient names match
+ * that convention, but the values only mean something together with the declared normalization
+ * radius.
+ *
+ * Validity checks (matching the radial-distortion validator):
+ * - The radial part must be strictly monotonic over the envelope (the valid radius range).
+ * - The Jacobian determinant must stay positive at a dense, fixed polar grid of samples over the
+ *   envelope disk.
+ * - The mapped envelope boundary must have strictly increasing polar angle, so it is a simple
+ *   star-shaped curve.
+ * A smooth, locally invertible map of a closed disk that is one-to-one on its boundary is one-to-one
+ * everywhere. So these conditions make the inverse single-valued. Note that the Jacobian and boundary
+ * conditions are checked at samples, not proven between them.
+ *
+ * The inverse uses damped Newton iteration, starting from the radial-only inverse.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type LensFieldPointMm, type ValidatedRadialProfile } from "./radial-distortion.js";
+export interface BrownConradyDistortionCoefficients {
+    /** Radial r^2 coefficient. */
+    k1: number;
+    /** Radial r^4 coefficient. */
+    k2: number;
+    /** Radial r^6 coefficient. */
+    k3: number;
+    /** Tangential (decentering) coefficient p1 (couples to y; see module equation). */
+    p1: number;
+    /** Tangential (decentering) coefficient p2 (couples to x; see module equation). */
+    p2: number;
+}
+export interface BrownConradyDistortionProfile {
+    /** Physical image-plane radius used to normalize field position, in mm. */
+    normalizationRadiusMm: number;
+    /** Maximum undistorted normalized radius of the operating envelope. */
+    maximumNormalizedRadius: number;
+    coefficients: BrownConradyDistortionCoefficients;
+}
+export interface CalculateBrownConradyDistortionMappingInput {
+    /** Ideal/undistorted image-plane point, in mm. */
+    imagePointMm: LensFieldPointMm;
+    profile: BrownConradyDistortionProfile;
+}
+export interface CalculateInverseBrownConradyDistortionMappingInput {
+    /** Distorted image-plane point to map back to ideal coordinates, in mm. */
+    distortedImagePointMm: LensFieldPointMm;
+    profile: BrownConradyDistortionProfile;
+}
+export interface BrownConradyDistortionMapping {
+    direction: "undistorted-to-distorted";
+    sourceImagePointMm: LensFieldPointMm;
+    mappedImagePointMm: LensFieldPointMm;
+    sourceNormalizedRadius: number;
+    /** Determinant of d(mapped)/d(source) at the source point (dimensionless area scale). */
+    jacobianDeterminant: number;
+    deltaMm: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+    profileMinimumJacobianDeterminant: number;
+}
+export interface InverseBrownConradyDistortionMapping {
+    direction: "distorted-to-undistorted";
+    distortedImagePointMm: LensFieldPointMm;
+    sourceImagePointMm: LensFieldPointMm;
+    sourceNormalizedRadius: number;
+    jacobianDeterminantAtSource: number;
+    newtonIterations: number;
+    /** Forward-mapping residual of the solved source point, in mm. */
+    residualMm: number;
+    deltaMm: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+    profileMinimumJacobianDeterminant: number;
+}
+interface ValidatedBrownConradyProfile {
+    radial: ValidatedRadialProfile;
+    coefficients: BrownConradyDistortionCoefficients;
+    minimumJacobianDeterminant: number;
+}
+/** @internal Opaque validated profile for repeated in-package evaluation. */
+export type ValidatedBrownConradyDistortionProfile = ValidatedBrownConradyProfile;
+/** @internal Validates one profile for repeated evaluation (geometric mapping, ray queries). */
+export declare function validateBrownConradyDistortionProfile(profile: BrownConradyDistortionProfile): ValidatedBrownConradyDistortionProfile;
+/** @internal Forward map in mm with its Jacobian d(distorted)/d(ideal), row-major. */
+export declare function brownConradyForwardValue(profile: ValidatedBrownConradyDistortionProfile, point: LensFieldPointMm): {
+    mappedImagePointMm: LensFieldPointMm;
+    jacobian: readonly [number, number, number, number];
+};
+/** @internal Inverse map in mm (distorted to ideal). */
+export declare function brownConradyInverseValue(profile: ValidatedBrownConradyDistortionProfile, point: LensFieldPointMm): LensFieldPointMm;
+/** Applies the Brown-Conrady forward mapping to one ideal image-plane point. */
+export declare function calculateBrownConradyDistortionMapping(input: CalculateBrownConradyDistortionMappingInput): CalculationResult<BrownConradyDistortionMapping>;
+/**
+ * Inverse-maps one distorted image-plane point to its ideal source point, for destination-to-source
+ * resampling. Damped Newton iteration starts from the radial-only inverse. The solution must lie
+ * inside the declared envelope and must reproduce the distorted point within a relative tolerance of
+ * 1e-12.
+ */
+export declare function calculateInverseBrownConradyDistortionMapping(input: CalculateInverseBrownConradyDistortionMappingInput): CalculationResult<InverseBrownConradyDistortionMapping>;
+export {};