@photivra/engine 0.1.0

package/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use Photivra in research or technical work, please cite it using the metadata below."
+title: "Photivra"
+type: software
+authors:
+  - family-names: "Shackelford"
+    given-names: "William"
+abstract: "An open TypeScript engine for the science and mathematics of photography and digital imaging."
+repository-code: "https://github.com/photivra/photivra"
+url: "https://photivra.com"
+license: "Apache-2.0"
+version: "0.1.0"
+keywords:
+  - photography
+  - camera optics
+  - digital imaging
+  - imaging science
+  - depth of field
+  - exposure
+  - motion blur
+  - diffraction
+  - sensor sampling
+  - signal-to-noise

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+Photivra
+Copyright 2026 William Shackelford
+
+This repository contains the Photivra scientific/business-logic engine.
+
+Source code in this repository is made available under the Apache License,
+Version 2.0. The Apache License does not grant permission to use Photivra
+trade names, trademarks, service marks, product names, logos, or branding
+except as allowed by applicable law and the license itself.

package/README.md

@@ -0,0 +1,235 @@
+# Photivra
+
+Photivra is an open TypeScript engine for the science and mathematics of photography and digital imaging.
+
+**Pronunciation (IPA):** /foʊˈtɪvɹə/
+
+Photivra provides a reusable, tested API for camera geometry, optics, focus and depth of field, exposure, subject and camera motion, sensor sampling, diffraction, cropping and framing, stabilization approximations, and signal/noise calculations.
+
+Its calculations use explicit units, documented assumptions, validation, provenance, and clearly labeled approximations so results are reproducible and their limitations are understandable.
+
+The source is licensed under Apache-2.0.
+
+## Quick start
+
+Install the ESM package:
+
+```sh
+npm install @photivra/engine
+```
+
+Calculate horizontal field of view for a 36 mm sensor dimension and 50 mm focal length:
+
+```ts
+import { calculateFieldOfView } from "@photivra/engine";
+
+const horizontal = calculateFieldOfView({
+  focalLengthMm: 50,
+  sensorDimensionMm: 36
+});
+
+console.log(horizontal.value.degrees);
+console.log(horizontal.provenance);
+```
+
+See the [Usage Guide](docs/USAGE.md) for the complete public API.
+
+## Documentation
+
+- [Usage Guide](docs/USAGE.md)
+- [Public API Style](docs/API_STYLE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Physics Foundation](docs/PHYSICS_FOUNDATION.md)
+- [Motion and Signal Foundation](docs/MOTION_AND_SIGNAL.md)
+- [Camera Shake and Stabilization](docs/STABILIZATION.md)
+- [Scientific and Source Provenance](docs/PROVENANCE.md)
+- [Local POC HTTP API](docs/POC_API.md)
+
+## Getting help
+
+Use [GitHub Issues](https://github.com/photivra/photivra/issues) for reproducible bugs, documentation problems, and feature discussions. For security vulnerabilities, follow [SECURITY.md](SECURITY.md).
+
+## What is implemented
+
+The root package exports deterministic or explicitly labeled approximate models across four areas.
+
+### Optics and geometry
+
+- [rectilinear field of view, with optional focus-aware thin-lens projection](docs/USAGE.md#field-of-view);
+- [Gaussian thin-lens image distance and magnification](docs/USAGE.md#thin-lens-image-distance-and-magnification);
+- [geometric depth of field and defocus-circle diameter](docs/USAGE.md#depth-of-field-and-defocus);
+- [ideal circular-aperture first-zero Airy diameter](docs/USAGE.md#circular-aperture-diffraction);
+- [ideal regular-polygon aperture geometry and sunstar direction symmetry](docs/USAGE.md#aperture-geometry-and-sunstar-directions).
+
+### Exposure and motion
+
+- [EV100, relative optical exposure, and equivalent ISO compensation](docs/USAGE.md#exposure-and-equivalent-iso);
+- [constant-velocity projected point motion](docs/USAGE.md#projected-subject-motion);
+- [a controlled yaw/pitch camera-shake and stabilization-equivalent approximation](docs/USAGE.md#camera-shake-and-stabilization-equivalent-approximation).
+
+### Sensor and output
+
+- [projected fronto-parallel object size and sensor-pixel sampling](docs/USAGE.md#projected-object-size-and-sensor-sampling);
+- [pixel pitch](docs/USAGE.md#pixel-pitch);
+- [centered crop and subject-height framing crop](docs/USAGE.md#centered-crop-and-subject-framing-crop);
+- [mean photoelectron conversion and basic shot-noise/read-noise SNR primitives](docs/USAGE.md#photoelectron-and-snr-primitives).
+
+### Data, validation, and composition
+
+- [camera/scene schemas and runtime validation](docs/USAGE.md#camera-and-scene-schema-validation);
+- [provenance plus optional uncertainty/quality metadata](docs/USAGE.md#provenance-uncertainty-and-quality-metadata);
+- [the composed `simulatePocCamera()` proof-of-concept calculation](docs/USAGE.md#composed-poc-simulation).
+
+The package has no runtime npm dependencies.
+
+## Sample use case
+
+A developer wants to model how a change in camera settings affects an image.
+
+Using Photivra, the application can provide camera and scene parameters—such as sensor dimensions, focal length, aperture, shutter speed, focus distance, subject distance, and motion—and receive structured scientific results describing effects such as:
+
+- field of view;
+- projected subject size;
+- depth of field and defocus;
+- diffraction;
+- subject-motion blur;
+- camera-shake blur;
+- pixel sampling;
+- crop and framing;
+- exposure relationships;
+- basic signal and noise behavior.
+
+Each result includes explicit units and model provenance, with approximations clearly identified rather than presented as exact physical measurements.
+
+```ts
+import {
+  calculateFieldOfView,
+  calculateDepthOfField,
+  calculateProjectedMotionBlur
+} from "@photivra/engine";
+
+const fieldOfView = calculateFieldOfView({
+  focalLengthMm: 200,
+  sensorDimensionMm: 36,
+  focusDistanceM: 22
+});
+
+const depthOfField = calculateDepthOfField({
+  focalLengthMm: 200,
+  aperture: 5.6,
+  focusDistanceM: 22,
+  circleOfConfusionMm: 0.03
+});
+
+const motion = calculateProjectedMotionBlur({
+  focalLengthMm: 200,
+  shutterSeconds: 1 / 1000,
+  positionM: { x: 0, y: 1, z: 22 },
+  velocityMps: { x: 10, y: 0, z: 0 },
+  focusDistanceM: 22,
+  pixelPitchMicrometers: 6
+});
+
+console.log(fieldOfView.value);
+console.log(depthOfField.value);
+console.log(motion.value);
+```
+
+The calling application can then use those results while keeping the underlying photography calculations centralized, tested, and reproducible.
+
+## Status
+
+- Package version: `0.1.0`
+- Engine API contract: `0.17.0`
+- Stability: pre-1.0 / proof of concept
+
+Package version and engine API version are intentionally separate. Public APIs may evolve before 1.0 while the scientific models and composition contracts are validated.
+
+Making this GitHub repository public and publishing `@photivra/engine` to a package registry are separate release actions.
+
+## Important scientific limits
+
+Photivra deliberately avoids claiming more than the current models support.
+
+- Focus-aware projection is ideal paraxial thin-lens geometry, not a real-lens focus-breathing or macro calibration model.
+- Projected subject motion follows a representative point under constant linear velocity. It does not yet model scale blur of an extended object moving substantially along the optical axis.
+- Camera shake is represented by one global yaw/pitch image-plane vector. Spatially varying rotational optical flow, roll, translation, and real IBIS/OIS behavior are not yet modeled.
+- The Airy diagnostic assumes an ideal circular pupil. Polygon aperture geometry does not produce a polygon diffraction PSF.
+- Signal/noise primitives require caller-supplied photon/electron quantities. The composed POC does not derive calibrated photon counts from scene imagery.
+- No named commercial camera or lens performance is claimed.
+
+See [Physics Foundation](docs/PHYSICS_FOUNDATION.md), [Motion and Signal Foundation](docs/MOTION_AND_SIGNAL.md), and [Camera Shake and Stabilization](docs/STABILIZATION.md) for details.
+
+## Principles
+
+- Independently implement established photography, optics, sensor, motion, and imaging mathematics.
+- Do not copy code, datasets, calibration tables, model weights, or protected technical expression unless reuse rights are explicit and compatible with Apache-2.0 distribution.
+- Treat publicly viewable material as reference material only; public availability is not permission to copy, and independent implementation does not by itself resolve third-party patent rights.
+- Keep calculations deterministic and testable where the model itself is deterministic.
+- Prefer explicit units, versioned schemas, consistent public APIs, and reproducible results.
+- Label results by provenance: calculated, calibrated, estimated, or approximation.
+- Report uncertainty/accuracy metadata only when it is defensible; never invent aggregate confidence or error bars.
+- Keep the repository focused on reusable scientific/business logic, validation, schemas, tests, documentation, and contributor tooling.
+
+## Runtime surfaces
+
+The package is ESM-only.
+
+The root export is the runtime-neutral scientific surface:
+
+```ts
+import {
+  calculateFieldOfView,
+  simulatePocCamera
+} from "@photivra/engine";
+```
+
+The root dependency graph is checked in CI so Node-only modules and the repository-local HTTP POC server cannot become reachable from that browser-facing surface.
+
+The open repository still contains a minimal Node HTTP POC server under `src/api` for contributor integration testing. It is deliberately **not** exported by `@photivra/engine` and is excluded from the published npm package. It is unauthenticated and is **not** a production hosting recommendation.
+
+When the package is installed directly from a Git repository using normal npm lifecycle scripts, `prepare` builds `dist` before consumption.
+
+## Development
+
+Development and Node-only tooling require Node.js 22.13 or newer. CI verifies Node.js 22.13 and Node.js 24; both are LTS release lines as of this documentation audit.
+
+The reproducible npm workflow uses the committed lockfile:
+
+```sh
+npm ci
+npm run check
+npm run coverage
+npm run build
+npm run pack:check
+```
+
+Coverage gates are currently:
+
+- 90% lines;
+- 90% statements;
+- 90% functions;
+- 80% branches.
+
+The deterministic fuzz/property suite uses fixed seeds so failures are reproducible.
+
+Yarn and pnpm may be used for development, but the repository's release/CI dependency resolution is defined by `package-lock.json` and `npm ci`.
+
+## Validation boundaries
+
+TypeScript types are not treated as validation for untrusted data.
+
+- Use `parseCameraConfiguration()` and `parseSceneDefinition()` for external camera/scene JSON.
+- The repository-local Node POC HTTP layer has its own structural request parser before invoking `simulatePocCamera()`.
+- Scientific range/domain validation remains in the calculation modules.
+- Public `CalculationResult<T>` envelopes reject non-finite numeric output.
+
+## Citation
+
+GitHub can generate citation text from [CITATION.cff](CITATION.cff). Use that metadata when citing Photivra in research, technical documentation, or reproducible analyses.
+
+## Licensing
+
+Source code in this repository is licensed under Apache-2.0 unless a file clearly states otherwise. See [LICENSE](LICENSE), [NOTICE](NOTICE), and [THIRD_PARTY.md](THIRD_PARTY.md).
+
+The Apache license does not grant trademark rights to the Photivra name, logos, or branding except as allowed by applicable law and the license itself.

package/dist/camera/field-of-view.d.ts

@@ -0,0 +1,37 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CalculateFieldOfViewInput {
+    /** Lens focal length in millimetres. */
+    focalLengthMm: number;
+    /** Sensor dimension corresponding to the requested field of view, in millimetres. */
+    sensorDimensionMm: number;
+    /**
+     * Optional focus distance in metres. When supplied, the ideal thin-lens
+     * image distance is used as the projection distance. Omit to preserve the
+     * infinity-focus/pinhole approximation.
+     */
+    focusDistanceM?: number;
+}
+export interface FieldOfView {
+    /** Angular field of view in degrees. */
+    degrees: number;
+    /** Angular field of view in radians. */
+    radians: number;
+    /** Projection/image-plane distance used by the geometry, in millimetres. */
+    projectionDistanceMm: number;
+}
+/**
+ * Calculates rectilinear angular field of view as
+ * 2 * atan(sensorDimension / (2 * projectionDistance)).
+ *
+ * Without focusDistanceM, projectionDistance is nominal focal length for
+ * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+ * projectionDistance is the ideal Gaussian thin-lens image distance for that
+ * focus plane.
+ *
+ * Neither mode models real-lens focus breathing or distortion.
+ *
+ * @param input Focal length, matching sensor dimension, and optional focus distance.
+ * @returns Angular field of view.
+ */
+export declare function calculateFieldOfView(input: CalculateFieldOfViewInput): CalculationResult<FieldOfView>;
+//# sourceMappingURL=field-of-view.d.ts.map

package/dist/camera/field-of-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-of-view.d.ts","sourceRoot":"","sources":["../../src/camera/field-of-view.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAIvC,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,iBAAiB,CAAC,WAAW,CAAC,CAqChC"}

package/dist/camera/field-of-view.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+import { calculatedResult } from "../core/calculation-result.js";
+import { requirePositiveFinite } from "../core/validation.js";
+import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+/**
+ * Calculates rectilinear angular field of view as
+ * 2 * atan(sensorDimension / (2 * projectionDistance)).
+ *
+ * Without focusDistanceM, projectionDistance is nominal focal length for
+ * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+ * projectionDistance is the ideal Gaussian thin-lens image distance for that
+ * focus plane.
+ *
+ * Neither mode models real-lens focus breathing or distortion.
+ *
+ * @param input Focal length, matching sensor dimension, and optional focus distance.
+ * @returns Angular field of view.
+ */
+export function calculateFieldOfView(input) {
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("sensorDimensionMm", input.sensorDimensionMm);
+    const focusProjection = input.focusDistanceM === undefined
+        ? undefined
+        : calculateThinLensImageDistance({
+            focalLengthMm: input.focalLengthMm,
+            objectDistanceM: input.focusDistanceM
+        });
+    const projectionDistanceMm = focusProjection?.value.imageDistanceMm ?? input.focalLengthMm;
+    const radians = 2 * Math.atan(input.sensorDimensionMm / (2 * projectionDistanceMm));
+    return calculatedResult({
+        radians,
+        degrees: (radians * 180) / Math.PI,
+        projectionDistanceMm
+    }, focusProjection === undefined
+        ? "rectilinear-field-of-view"
+        : "focus-aware-rectilinear-field-of-view", "1.0.0", focusProjection === undefined
+        ? [
+            "Ideal rectilinear/pinhole projection",
+            "Nominal focal length represents the infinity-focus projection distance"
+        ]
+        : [
+            "Ideal rectilinear paraxial thin-lens projection",
+            "Sensor plane uses the thin-lens image distance for the supplied focus distance",
+            "Real-lens focus breathing and distortion are not modeled"
+        ]);
+}
+//# sourceMappingURL=field-of-view.js.map

package/dist/camera/field-of-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-of-view.js","sourceRoot":"","sources":["../../src/camera/field-of-view.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAwBxE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAEpE,MAAM,eAAe,GACnB,KAAK,CAAC,cAAc,KAAK,SAAS;QAChC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,8BAA8B,CAAC;YAC7B,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,cAAc;SACtC,CAAC,CAAC;IACT,MAAM,oBAAoB,GACxB,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,aAAa,CAAC;IAChE,MAAM,OAAO,GACX,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC;IAEtE,OAAO,gBAAgB,CACrB;QACE,OAAO;QACP,OAAO,EAAE,CAAC,OAAO,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE;QAClC,oBAAoB;KACrB,EACD,eAAe,KAAK,SAAS;QAC3B,CAAC,CAAC,2BAA2B;QAC7B,CAAC,CAAC,uCAAuC,EAC3C,OAAO,EACP,eAAe,KAAK,SAAS;QAC3B,CAAC,CAAC;YACE,sCAAsC;YACtC,wEAAwE;SACzE;QACH,CAAC,CAAC;YACE,iDAAiD;YACjD,gFAAgF;YAChF,0DAA0D;SAC3D,CACN,CAAC;AACJ,CAAC"}

package/dist/camera/projected-object-size.d.ts

@@ -0,0 +1,34 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CalculateProjectedObjectSizeInput {
+    /** Lens focal length in millimetres. */
+    focalLengthMm: number;
+    /** Object width in metres. */
+    objectWidthM: number;
+    /** Object height in metres. */
+    objectHeightM: number;
+    /** Object-plane distance from the camera in metres. */
+    distanceM: number;
+    /** Optional focus distance in metres for focus-aware sensor-plane projection. */
+    focusDistanceM?: number;
+    /** Optional sensor pixel pitch in micrometres. */
+    pixelPitchMicrometers?: number;
+}
+export interface ProjectedObjectSize {
+    widthMm: number;
+    heightMm: number;
+    projectionDistanceMm: number;
+    widthPixels?: number;
+    heightPixels?: number;
+}
+/**
+ * Calculates the projected size of a fronto-parallel object plane.
+ *
+ * Without focusDistanceM, the function preserves ideal pinhole projection
+ * using nominal focal length. With focusDistanceM, it projects to the ideal
+ * thin-lens sensor plane selected by that focus distance.
+ *
+ * @param input Lens, object-size, distance, optional focus, and optional pixel-pitch inputs.
+ * @returns Projected object dimensions at the sensor plane.
+ */
+export declare function calculateProjectedObjectSize(input: CalculateProjectedObjectSizeInput): CalculationResult<ProjectedObjectSize>;
+//# sourceMappingURL=projected-object-size.d.ts.map

package/dist/camera/projected-object-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projected-object-size.d.ts","sourceRoot":"","sources":["../../src/camera/projected-object-size.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAIvC,MAAM,WAAW,iCAAiC;IAChD,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,iCAAiC,GACvC,iBAAiB,CAAC,mBAAmB,CAAC,CAgExC"}

package/dist/camera/projected-object-size.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+import { calculatedResult } from "../core/calculation-result.js";
+import { requirePositiveFinite } from "../core/validation.js";
+import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+/**
+ * Calculates the projected size of a fronto-parallel object plane.
+ *
+ * Without focusDistanceM, the function preserves ideal pinhole projection
+ * using nominal focal length. With focusDistanceM, it projects to the ideal
+ * thin-lens sensor plane selected by that focus distance.
+ *
+ * @param input Lens, object-size, distance, optional focus, and optional pixel-pitch inputs.
+ * @returns Projected object dimensions at the sensor plane.
+ */
+export function calculateProjectedObjectSize(input) {
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("objectWidthM", input.objectWidthM);
+    requirePositiveFinite("objectHeightM", input.objectHeightM);
+    requirePositiveFinite("distanceM", input.distanceM);
+    const focusProjection = input.focusDistanceM === undefined
+        ? undefined
+        : calculateThinLensImageDistance({
+            focalLengthMm: input.focalLengthMm,
+            objectDistanceM: input.focusDistanceM
+        });
+    const projectionDistanceMm = focusProjection?.value.imageDistanceMm ?? input.focalLengthMm;
+    const widthMm = projectionDistanceMm * (input.objectWidthM / input.distanceM);
+    const heightMm = projectionDistanceMm * (input.objectHeightM / input.distanceM);
+    const model = focusProjection === undefined
+        ? "fronto-parallel-pinhole-object-size"
+        : "focus-aware-thin-lens-object-size";
+    const assumptions = focusProjection === undefined
+        ? [
+            "Ideal pinhole projection",
+            "Object plane is fronto-parallel to the sensor",
+            "Physical object dimensions are supplied by the caller"
+        ]
+        : [
+            "Ideal paraxial thin-lens projection to the selected sensor plane",
+            "Object plane is fronto-parallel to the sensor",
+            "Physical object dimensions are supplied by the caller",
+            "Real-lens focus breathing and pupil magnification are not modeled"
+        ];
+    if (input.pixelPitchMicrometers === undefined) {
+        return calculatedResult({ widthMm, heightMm, projectionDistanceMm }, model, "1.0.0", assumptions);
+    }
+    requirePositiveFinite("pixelPitchMicrometers", input.pixelPitchMicrometers);
+    const pitchMm = input.pixelPitchMicrometers / 1000;
+    return calculatedResult({
+        widthMm,
+        heightMm,
+        projectionDistanceMm,
+        widthPixels: widthMm / pitchMm,
+        heightPixels: heightMm / pitchMm
+    }, model, "1.0.0", assumptions);
+}
+//# sourceMappingURL=projected-object-size.js.map

package/dist/camera/projected-object-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projected-object-size.js","sourceRoot":"","sources":["../../src/camera/projected-object-size.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAyBxE;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAwC;IAExC,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1D,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAEpD,MAAM,eAAe,GACnB,KAAK,CAAC,cAAc,KAAK,SAAS;QAChC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,8BAA8B,CAAC;YAC7B,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,cAAc;SACtC,CAAC,CAAC;IACT,MAAM,oBAAoB,GACxB,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,aAAa,CAAC;IAChE,MAAM,OAAO,GACX,oBAAoB,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,MAAM,QAAQ,GACZ,oBAAoB,GAAG,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IACjE,MAAM,KAAK,GACT,eAAe,KAAK,SAAS;QAC3B,CAAC,CAAC,qCAAqC;QACvC,CAAC,CAAC,mCAAmC,CAAC;IAC1C,MAAM,WAAW,GACf,eAAe,KAAK,SAAS;QAC3B,CAAC,CAAC;YACE,0BAA0B;YAC1B,+CAA+C;YAC/C,uDAAuD;SACxD;QACH,CAAC,CAAC;YACE,kEAAkE;YAClE,+CAA+C;YAC/C,uDAAuD;YACvD,mEAAmE;SACpE,CAAC;IAER,IAAI,KAAK,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,gBAAgB,CACrB,EAAE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,EAC3C,KAAK,EACL,OAAO,EACP,WAAW,CACZ,CAAC;IACJ,CAAC;IAED,qBAAqB,CACnB,uBAAuB,EACvB,KAAK,CAAC,qBAAqB,CAC5B,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAEnD,OAAO,gBAAgB,CACrB;QACE,OAAO;QACP,QAAQ;QACR,oBAAoB;QACpB,WAAW,EAAE,OAAO,GAAG,OAAO;QAC9B,YAAY,EAAE,QAAQ,GAAG,OAAO;KACjC,EACD,KAAK,EACL,OAAO,EACP,WAAW,CACZ,CAAC;AACJ,CAAC"}