@photivra/engine 1.5.0 → 2.1.0

package/docs/examples/simulate-capture.mjs

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import console from "node:console";
+
+// Node 22/24/26 executable example; simulateCapture itself is browser-safe.
+import { simulateCapture } from "@photivra/engine";
+const capture = await simulateCapture({
+  camera: "professional",
+  scene: { preset: "slanted-edge" },
+  output: { width: 32, height: 32, format: "jpeg" }
+});
+if (capture.image.jpeg[0] !== 0xff || capture.image.jpeg[1] !== 0xd8) throw new Error("JPEG output changed");
+console.log({ settings: capture.exposure.settings, jpegBytes: capture.image.jpeg.length,
+  assumptions: capture.assumptions.map((a) => a.id) });

package/llms.txt

@@ -0,0 +1,35 @@
+# Photivra (@photivra/engine)
+
+> Photivra is an Apache-2.0 TypeScript library for the science of photography: camera geometry, optics, focus and depth of field, exposure, motion, diffraction, sensor signal and noise, colour, RAW and image formation. It runs in browsers and Node 22.13 or later, makes no network calls and needs no API key. Most functions take one input object with units in the field names (`focalLengthMm`, `focusDistanceM`, `shutterSeconds`) and return `{ value, provenance }`. `provenance.kind` says whether a result is `calculated` or an `approximation`. The built-in camera tiers are synthetic educational designs, not real cameras.
+
+## Start here
+
+- [Agent guide](https://github.com/Photivra/photivra/blob/main/docs/AGENT_GUIDE.md): which function to call, units, reading results, errors and limits
+- [Quick start](https://github.com/Photivra/photivra/blob/main/docs/QUICK_START.md): `simulateCapture()` inputs, defaults, chart presets and output formats
+- [Usage guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md): worked examples for every public area
+- [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md): every root export, with a task-to-function index
+
+## One call: a full simulated photo
+
+- [simulateCapture()](https://github.com/Photivra/photivra/blob/main/docs/api/facade-simulate-capture.md#simulatecapture): async; camera tier, lens, exposure and chart scene in, developed image plus `assumptions` and `provenance` out
+
+## Single calculations by task
+
+- [calculateExposureValue100()](https://github.com/Photivra/photivra/blob/main/docs/api/exposure-exposure.md#calculateexposurevalue100): EV at ISO 100 from f-number and shutter seconds
+- [calculateEquivalentIso()](https://github.com/Photivra/photivra/blob/main/docs/api/exposure-exposure.md#calculateequivalentiso): ISO that keeps the same brightness after an aperture or shutter change
+- [calculateDepthOfField()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-depth-of-field.md#calculatedepthoffield): near and far limits and hyperfocal distance (thin lens)
+- [calculateDefocusCircle()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-depth-of-field.md#calculatedefocuscircle): blur-circle size for an out-of-focus subject
+- [calculateFieldOfView()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-field-of-view.md#calculatefieldofview): angle of view from focal length and sensor size
+- [calculateEquivalentFocalLength35Mm()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-equivalent-focal-length.md#calculateequivalentfocallength35mm): crop factor and 35 mm-equivalent focal length
+- [calculateCenteredCrop()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop.md#calculatecenteredcrop): pixels left after a centred crop
+- [calculateProjectedMotionBlur()](https://github.com/Photivra/photivra/blob/main/docs/api/motion-projected-motion.md#calculateprojectedmotionblur): how far a moving subject smears on the sensor during the shutter time
+- [calculateAiryDisk()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-diffraction.md#calculateairydisk): diffraction spot size from f-number and wavelength
+- [calculateSignalToNoise()](https://github.com/Photivra/photivra/blob/main/docs/api/sensor-signal-noise.md#calculatesignaltonoise): expected SNR from signal and read noise in electrons
+- [calculateChromaticityFromCorrelatedColorTemperature()](https://github.com/Photivra/photivra/blob/main/docs/api/color-illuminants.md#calculatechromaticityfromcorrelatedcolortemperature): white point for a colour temperature in kelvin
+- [resolveColorTemperatureWhiteBalance()](https://github.com/Photivra/photivra/blob/main/docs/api/color-white-balance.md#resolvecolortemperaturewhitebalance): Kelvin + tint white balance to camera channel gains
+
+## Reference
+
+- [Per-module API pages](https://github.com/Photivra/photivra/tree/main/docs/api): generated signatures and doc comments for each source module
+- [Error types](https://github.com/Photivra/photivra/blob/main/docs/api/core-validation.md#invalidscientificinputerror): `InvalidScientificInputError` (RangeError) and `InvalidConfigurationError` (TypeError)
+- [README](https://github.com/Photivra/photivra/blob/main/README.md): overview and "Important scientific limits"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "1.5.0",
+  "version": "2.1.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -11,21 +11,24 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist/index.js",
     "dist/index.js.map",
     "dist/index.d.ts",
-    "dist/index.d.ts.map",
     "dist/camera",
     "dist/capture",
     "dist/color",
     "dist/composition",
     "dist/core",
     "dist/equipment",
+    "dist/facade",
     "dist/exposure",
+    "dist/gpu",
     "dist/motion",
     "dist/optics",
     "dist/output",
@@ -33,18 +36,27 @@
     "dist/sensor",
     "dist/simulation",
     "dist/stabilization",
+    "dist/processing",
+    "!dist/capture/browser-native-reference-*",
+    "!dist/schema/camera.js",
+    "!dist/schema/camera.js.map",
+    "!dist/schema/scene.js",
+    "!dist/schema/scene.js.map",
     "CHANGELOG.md",
     "README.md",
     "CITATION.cff",
     "LICENSE",
     "NOTICE",
-    "docs",
-    "AGENTS.md",
-    "CONTRIBUTING.md",
     "SECURITY.md",
     "NODE_SUPPORT.md",
-    "DCO",
-    "THIRD_PARTY.md"
+    "THIRD_PARTY.md",
+    "llms.txt",
+    "docs/USAGE.md",
+    "docs/QUICK_START.md",
+    "docs/AGENT_GUIDE.md",
+    "docs/API_REFERENCE.md",
+    "docs/api",
+    "docs/examples"
   ],
   "repository": {
     "type": "git",
@@ -62,7 +74,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepare": "npm run build",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "prepush": "node scripts/prepush.mjs",
     "check:static": "eslint . && tsc --noEmit && npm run check:licenses && npm run check:license-headers && npm run check:identity && npm run check:browser-surface",
     "check": "npm run check:static && vitest run",
     "lint": "eslint .",
@@ -71,14 +84,22 @@
     "typecheck": "tsc --noEmit",
     "pack:check": "node scripts/check-package-surface.mjs",
     "coverage": "vitest run --coverage",
+    "test:webgpu": "vitest run --config vitest.webgpu.config.ts",
+    "bench:webgpu": "vitest run --config vitest.webgpu-timing.config.ts",
+    "test:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs test",
+    "bench:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs bench",
     "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",
     "bench:image-formation": "npm run build && npm run bench:image-formation:built",
     "bench:image-formation:built": "node --expose-gc scripts/benchmark-image-formation.mjs",
+    "profile:native-reference": "node --expose-gc scripts/profile-native-reference-path.mjs",
+    "assess:native-full-event": "node scripts/assess-browser-native-full-event.mjs",
+    "qualify:native-reference-progressive": "node --expose-gc scripts/qualify-browser-native-progressive.mjs",
     "docs:check": "node scripts/check-release-docs.mjs",
-    "release:consumer-check": "node scripts/check-release-consumer.mjs"
+    "release:consumer-check": "node scripts/check-release-consumer.mjs",
+    "release:prepare": "node scripts/release-prepare.mjs"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",