@photivra/engine 0.1.0

package/docs/USAGE.md

@@ -0,0 +1,538 @@
+# Usage Guide
+
+This guide shows how to call the capabilities exported by the root `@photivra/engine` package.
+
+The package is ESM-only. Primitive scientific calculations generally return a `CalculationResult<T>`:
+
+```ts
+const result = calculateSomething(input);
+
+console.log(result.value);
+console.log(result.provenance);
+console.log(result.quality);
+```
+
+`quality` is optional and is omitted when the engine does not have defensible quantified uncertainty/accuracy metadata to report.
+
+## Field of view
+
+Use `calculateFieldOfView()` for one sensor dimension at a time.
+
+```ts
+import { calculateFieldOfView } from "@photivra/engine";
+
+const horizontal = calculateFieldOfView({
+  focalLengthMm: 50,
+  sensorDimensionMm: 36
+});
+
+console.log(horizontal.value.degrees);
+```
+
+To use the ideal thin-lens sensor plane at a selected focus distance, provide `focusDistanceM`:
+
+```ts
+const focused = calculateFieldOfView({
+  focalLengthMm: 200,
+  sensorDimensionMm: 36,
+  focusDistanceM: 22
+});
+
+console.log(focused.value.projectionDistanceMm);
+console.log(focused.value.degrees);
+```
+
+Without `focusDistanceM`, nominal focal length is used as the infinity-focus/pinhole projection distance. Neither mode models real-lens distortion or focus breathing.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#rectilinear-field-of-view).
+
+## Thin-lens image distance and magnification
+
+Use `calculateThinLensImageDistance()` to calculate ideal Gaussian thin-lens image distance for an object/focus plane.
+
+```ts
+import { calculateThinLensImageDistance } from "@photivra/engine";
+
+const projection = calculateThinLensImageDistance({
+  focalLengthMm: 200,
+  objectDistanceM: 22
+});
+
+console.log(projection.value.imageDistanceMm);
+console.log(projection.value.magnification);
+console.log(projection.value.infinityProjectionScale);
+```
+
+This is a paraxial ideal-lens model. It does not model real-lens focus breathing, pupil magnification, principal-plane movement, or aberrations.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#projection-focus-extension-object-size-and-motion).
+
+## Projected object size and sensor sampling
+
+Use `calculateProjectedObjectSize()` for a fronto-parallel object with known physical dimensions and distance.
+
+```ts
+import { calculateProjectedObjectSize } from "@photivra/engine";
+
+const subject = calculateProjectedObjectSize({
+  focalLengthMm: 200,
+  objectWidthM: 0.7,
+  objectHeightM: 1.8,
+  distanceM: 22,
+  focusDistanceM: 22,
+  pixelPitchMicrometers: 6
+});
+
+console.log(subject.value.widthMm);
+console.log(subject.value.heightMm);
+console.log(subject.value.widthPixels);
+console.log(subject.value.heightPixels);
+```
+
+Omit `pixelPitchMicrometers` when only physical image-plane dimensions are needed.
+
+The object plane is assumed to be fronto-parallel to the sensor.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#projection-focus-extension-object-size-and-motion).
+
+## Depth of field and defocus
+
+Use `calculateDepthOfField()` for conventional geometric near/far limits:
+
+```ts
+import { calculateDepthOfField } from "@photivra/engine";
+
+const dof = calculateDepthOfField({
+  focalLengthMm: 85,
+  aperture: 2.8,
+  focusDistanceM: 10,
+  circleOfConfusionMm: 0.03
+});
+
+console.log(dof.value.nearLimitM);
+console.log(dof.value.farLimitM); // null means infinity
+console.log(dof.value.totalDepthOfFieldM);
+```
+
+Use `calculateDefocusCircle()` when you need the geometric blur-circle diameter for a specific subject plane:
+
+```ts
+import { calculateDefocusCircle } from "@photivra/engine";
+
+const blur = calculateDefocusCircle({
+  focalLengthMm: 85,
+  aperture: 2.8,
+  focusDistanceM: 10,
+  subjectDistanceM: 20
+});
+
+console.log(blur.value.diameterMm);
+```
+
+The circle-of-confusion criterion used for depth-of-field is caller supplied. These are ideal geometric thin-lens models and do not incorporate diffraction or real-lens aberrations into the DOF criterion.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#thin-lens-focus-and-depth-of-field).
+
+## Circular-aperture diffraction
+
+Use `calculateAiryDisk()` for the ideal monochromatic circular-pupil first-zero Airy diameter:
+
+```ts
+import { calculateAiryDisk } from "@photivra/engine";
+
+const diffraction = calculateAiryDisk({
+  aperture: 8,
+  wavelengthNm: 550
+});
+
+console.log(diffraction.value.firstZeroDiameterMicrometers);
+```
+
+This calculation uses `d = 2.44 λ N`. It is not a polygon-aperture diffraction PSF.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#diffraction).
+
+## Aperture geometry and sunstar directions
+
+Use `calculateIdealApertureGeometry()` for a regular, straight-edged diaphragm:
+
+```ts
+import { calculateIdealApertureGeometry } from "@photivra/engine";
+
+const aperture = calculateIdealApertureGeometry({
+  bladeCount: 7,
+  firstBladeEdgeAngleDegrees: 15
+});
+
+console.log(aperture.value.normalizedVertices);
+console.log(aperture.value.sunstarRayCount);
+console.log(aperture.value.sunstarRayAnglesDegrees);
+```
+
+The output describes normalized aperture geometry and idealized ray-direction symmetry only. It does not calculate diffraction intensity, star length, flare, coatings, or a full PSF.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#ideal-diaphragm-geometry-and-sunstar-symmetry).
+
+## Pixel pitch
+
+Use `calculatePixelPitch()` with physical sensor width and horizontal active pixel count:
+
+```ts
+import { calculatePixelPitch } from "@photivra/engine";
+
+const pitch = calculatePixelPitch({
+  sensorWidthMm: 36,
+  pixelWidth: 6000
+});
+
+console.log(pitch.value.micrometers);
+console.log(pitch.value.millimeters);
+```
+
+The current primitive calculates horizontal pixel pitch. It assumes the supplied sensor width and pixel count describe the same active dimension.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#pixel-pitch-and-crop).
+
+## Centered crop and subject framing crop
+
+Use `calculateCenteredCrop()` for a same-aspect centered digital crop:
+
+```ts
+import { calculateCenteredCrop } from "@photivra/engine";
+
+const crop = calculateCenteredCrop({
+  pixelWidth: 6000,
+  pixelHeight: 4000,
+  cropFactor: 1.5
+});
+
+console.log(crop.value.pixelWidth);
+console.log(crop.value.pixelHeight);
+console.log(crop.value.megapixels);
+console.log(crop.value.retainedAreaFraction);
+```
+
+Use `calculateSubjectFramingCrop()` to calculate the additional crop needed for a projected subject to occupy a target fraction of frame height:
+
+```ts
+import { calculateSubjectFramingCrop } from "@photivra/engine";
+
+const framing = calculateSubjectFramingCrop({
+  pixelWidth: 6000,
+  pixelHeight: 4000,
+  subjectHeightPixels: 1200,
+  targetSubjectHeightFraction: 0.5
+});
+
+console.log(framing.value.cropFactor);
+console.log(framing.value.subjectHeightFraction);
+console.log(framing.value.subjectClipped);
+```
+
+Subject framing assumes the crop can be positioned around the subject; it does not check the subject's actual position against image edges.
+
+See [Physics Foundation](PHYSICS_FOUNDATION.md#pixel-pitch-and-crop).
+
+## Projected subject motion
+
+Use `calculateProjectedMotionBlur()` for representative-point image-plane displacement during an exposure:
+
+```ts
+import { calculateProjectedMotionBlur } from "@photivra/engine";
+
+const motion = calculateProjectedMotionBlur({
+  focalLengthMm: 200,
+  shutterSeconds: 1 / 500,
+  positionM: { x: 0.5, y: 1.2, z: 22 },
+  velocityMps: { x: 8, y: 0, z: 0 },
+  focusDistanceM: 22,
+  pixelPitchMicrometers: 6
+});
+
+console.log(motion.value.deltaXMm);
+console.log(motion.value.deltaYMm);
+console.log(motion.value.distanceMm);
+console.log(motion.value.distancePixels);
+```
+
+The model assumes constant world-space linear velocity. It tracks a representative point rather than extended-object scale blur, rotation, deformation, or acceleration.
+
+See [Motion and Signal Foundation](MOTION_AND_SIGNAL.md#projected-subject-motion).
+
+## Exposure and equivalent ISO
+
+Use `calculateExposureValue100()` for EV100:
+
+```ts
+import { calculateExposureValue100 } from "@photivra/engine";
+
+const ev = calculateExposureValue100({
+  aperture: 8,
+  shutterSeconds: 1 / 125
+});
+
+console.log(ev.value);
+```
+
+Use `calculateRelativeOpticalExposure()` to compare aperture/shutter combinations:
+
+```ts
+import { calculateRelativeOpticalExposure } from "@photivra/engine";
+
+const exposure = calculateRelativeOpticalExposure({
+  aperture: 4,
+  shutterSeconds: 1 / 250,
+  referenceAperture: 5.6,
+  referenceShutterSeconds: 1 / 125
+});
+
+console.log(exposure.value.factor);
+console.log(exposure.value.stops);
+```
+
+Use `calculateEquivalentIso()` to calculate the nominal ISO/gain compensation needed to preserve rendered exposure:
+
+```ts
+import { calculateEquivalentIso } from "@photivra/engine";
+
+const iso = calculateEquivalentIso({
+  baseIso: 400,
+  baseAperture: 4,
+  baseShutterSeconds: 1 / 500,
+  aperture: 5.6,
+  shutterSeconds: 1 / 500
+});
+
+console.log(iso.value);
+```
+
+These relations do not model scene radiance, lens T-stop/transmission, vignetting, or sensor-specific gain/noise behavior.
+
+See [Motion and Signal Foundation](MOTION_AND_SIGNAL.md#exposure-relations).
+
+## Camera shake and stabilization-equivalent approximation
+
+Use `estimateCameraShakeBlur()` with a controlled yaw/pitch angular-velocity profile:
+
+```ts
+import { estimateCameraShakeBlur } from "@photivra/engine";
+
+const shake = estimateCameraShakeBlur({
+  focalLengthMm: 200,
+  shutterSeconds: 1 / 60,
+  angularVelocityRadPerSec: {
+    yaw: 0.002,
+    pitch: 0.001
+  },
+  stabilizationStopsEquivalent: 3,
+  focusDistanceM: 22,
+  pixelPitchMicrometers: 6
+});
+
+console.log(shake.value.unstabilized.distancePixels);
+console.log(shake.value.stabilized.distancePixels);
+console.log(shake.value.residualMotionFactor);
+console.log(shake.provenance.kind); // "approximation"
+```
+
+The `2^-stops` attenuation is an educational approximation, not a real IBIS/OIS or CIPA rating. The current output is one global image-plane vector rather than spatially varying rotational optical flow.
+
+See [Camera Shake and Stabilization](STABILIZATION.md).
+
+## Photoelectron and SNR primitives
+
+Use `calculatePhotoelectrons()` only when you already have a defensible mean incident photon count and quantum efficiency:
+
+```ts
+import { calculatePhotoelectrons } from "@photivra/engine";
+
+const electrons = calculatePhotoelectrons({
+  incidentPhotons: 10_000,
+  quantumEfficiency: 0.7
+});
+
+console.log(electrons.value);
+```
+
+Use `calculateSignalToNoise()` for the basic Poisson-shot-noise plus independent RMS read-noise model:
+
+```ts
+import { calculateSignalToNoise } from "@photivra/engine";
+
+const snr = calculateSignalToNoise({
+  signalElectrons: 7000,
+  readNoiseElectrons: 3
+});
+
+console.log(snr.value.shotNoiseStdElectrons);
+console.log(snr.value.combinedNoiseStdElectrons);
+console.log(snr.value.snrLinear);
+console.log(snr.value.snrDb);
+```
+
+These primitives do not derive photons from scene imagery and do not model a complete commercial sensor pipeline.
+
+See [Motion and Signal Foundation](MOTION_AND_SIGNAL.md#signalnoise-primitives).
+
+## Camera and scene schema validation
+
+Use the runtime parsers when camera or scene data crosses an untrusted JSON boundary.
+
+```ts
+import {
+  parseCameraConfiguration,
+  parseSceneDefinition
+} from "@photivra/engine";
+
+const camera = parseCameraConfiguration(JSON.parse(cameraJson));
+const scene = parseSceneDefinition(JSON.parse(sceneJson));
+```
+
+The parsers throw `InvalidConfigurationError` when the supplied structure or supported values are invalid.
+
+Example camera shape:
+
+```ts
+const camera = parseCameraConfiguration({
+  sensor: {
+    widthMm: 36,
+    heightMm: 24,
+    pixelWidth: 6000,
+    pixelHeight: 4000
+  },
+  lens: {
+    focalLengthMm: 50,
+    aperture: 2.8
+  },
+  exposure: {
+    shutterSeconds: 1 / 250,
+    iso: 400
+  },
+  focus: {
+    focusDistanceM: 10
+  },
+  stabilization: {
+    bodyEnabled: true,
+    lensEnabled: false,
+    support: "handheld"
+  }
+});
+```
+
+See [Validation boundaries in the README](../README.md#validation-boundaries) and [Architecture](ARCHITECTURE.md).
+
+## Provenance, uncertainty, and quality metadata
+
+Primitive scientific calculations return model provenance alongside the value:
+
+```ts
+import { calculateFieldOfView } from "@photivra/engine";
+
+const result = calculateFieldOfView({
+  focalLengthMm: 50,
+  sensorDimensionMm: 36
+});
+
+console.log(result.provenance.kind);
+console.log(result.provenance.model);
+console.log(result.provenance.modelVersion);
+console.log(result.provenance.assumptions);
+```
+
+For code that defines a new scientific result, the package exports helpers such as `calculatedResult()`, `approximationResult()`, `estimatedResult()`, and `calibratedResult()`.
+
+```ts
+import { calculatedResult } from "@photivra/engine";
+
+const result = calculatedResult(
+  { distanceM: 10 },
+  "example-model",
+  "1.0.0",
+  ["Example assumption"],
+  {
+    uncertainty: [
+      {
+        kind: "absolute",
+        quantityPath: "value.distanceM",
+        source: "measurement",
+        plusMinus: 0.1,
+        unit: "m"
+      }
+    ]
+  }
+);
+```
+
+Do not invent uncertainty values. Quality metadata should only be supplied when the uncertainty, calibration, valid range, or quality note has a defensible basis.
+
+See [Scientific and Source Provenance](PROVENANCE.md) and [Public API Style](API_STYLE.md#result-metadata).
+
+## Composed POC simulation
+
+Use `simulatePocCamera()` when you want one composed response containing the current POC calculations.
+
+```ts
+import { simulatePocCamera } from "@photivra/engine";
+
+const simulation = simulatePocCamera({
+  sensor: {
+    widthMm: 36,
+    heightMm: 24,
+    pixelWidth: 6000,
+    pixelHeight: 4000
+  },
+  lens: {
+    focalLengthMm: 200,
+    aperture: 5.6
+  },
+  exposure: {
+    shutterSeconds: 1 / 1000,
+    iso: 800
+  },
+  focus: {
+    focusDistanceM: 22,
+    circleOfConfusionMm: 0.03
+  },
+  crop: {
+    factor: 1
+  },
+  diffraction: {
+    wavelengthNm: 550
+  },
+  motion: {
+    positionM: { x: 0.2, y: 1.2, z: 21.8 },
+    velocityMps: { x: 35, y: 0, z: 0 }
+  },
+  subject: {
+    widthM: 0.7,
+    heightM: 1.8,
+    distanceM: 22
+  },
+  subjectCrop: {
+    targetSubjectHeightFraction: 0.5
+  },
+  cameraShake: {
+    angularVelocityRadPerSec: {
+      yaw: 0.002,
+      pitch: 0.001
+    },
+    stabilizationStopsEquivalent: 2
+  },
+  apertureShape: {
+    bladeCount: 7,
+    firstBladeEdgeAngleDegrees: 0
+  }
+});
+
+console.log(simulation.apiVersion);
+console.log(simulation.fieldOfView);
+console.log(simulation.depthOfField);
+console.log(simulation.motion);
+console.log(simulation.provenance);
+```
+
+The focus request must supply exactly one circle-of-confusion criterion: either `circleOfConfusionMm` or `equivalentViewingCircleOfConfusion`.
+
+Additional named defocus, sampling, and motion samples can be supplied when a renderer or analysis client needs per-object outputs.
+
+See [Local POC Simulation API](POC_API.md#simulate) for the complete composed request/response semantics. That HTTP transport is repository-only contributor tooling and is not shipped as a package subpath; `simulatePocCamera()` itself is part of the browser-safe root package.

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@photivra/engine",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts",
+    "dist/index.d.ts.map",
+    "dist/camera",
+    "dist/core",
+    "dist/exposure",
+    "dist/motion",
+    "dist/optics",
+    "dist/output",
+    "dist/schema",
+    "dist/sensor",
+    "dist/simulation",
+    "dist/stabilization",
+    "README.md",
+    "CITATION.cff",
+    "LICENSE",
+    "NOTICE",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Photivra/photivra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/photivra/photivra/issues"
+  },
+  "homepage": "https://github.com/photivra/photivra#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "check": "eslint . && tsc --noEmit && vitest run && npm run check:licenses && npm run check:license-headers && npm run check:identity && npm run check:browser-surface",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "node scripts/check-package-surface.mjs",
+    "coverage": "vitest run --coverage",
+    "check:browser-surface": "node scripts/check-browser-surface.mjs",
+    "check:licenses": "node scripts/check-license-policy.mjs",
+    "check:license-headers": "node scripts/check-license-headers.mjs",
+    "check:identity": "node scripts/check-project-identity.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "eslint": "10.10.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.1",
+    "@types/node": "24.13.6",
+    "@vitest/coverage-v8": "5.0.1"
+  },
+  "keywords": [
+    "photography",
+    "camera",
+    "optics",
+    "digital-imaging",
+    "imaging-science",
+    "depth-of-field",
+    "exposure",
+    "motion-blur",
+    "diffraction",
+    "image-sensor",
+    "signal-to-noise",
+    "scientific-computing",
+    "typescript"
+  ]
+}