@photivra/engine 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/CITATION.cff +1 -1
  3. package/README.md +4 -3
  4. package/dist/exposure/exposure.d.ts +31 -0
  5. package/dist/exposure/exposure.d.ts.map +1 -1
  6. package/dist/exposure/exposure.js +35 -0
  7. package/dist/exposure/exposure.js.map +1 -1
  8. package/dist/index.d.ts +1 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/docs/MOTION_AND_SIGNAL.md +2 -0
  13. package/docs/USAGE.md +23 -1
  14. package/package.json +2 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ Notable public changes to `@photivra/engine` are documented here.
4
+
5
+ ## 0.2.0 - 2026-09-21
6
+
7
+ ### Added
8
+
9
+ - `calculateRelativeRenderedExposure()`, a deterministic relative rendering relation that combines aperture/shutter optical exposure with nominal ISO gain relative to declared reference settings.
10
+ - Public input and result types for the relative rendered exposure calculation.
11
+
12
+ ### Documentation
13
+
14
+ - Added usage guidance and scientific limitations for relative rendered exposure.
15
+ - Synchronized package, lockfile, README, and citation version metadata for the release.
16
+
17
+ ## 0.1.0 - 2026-09-20
18
+
19
+ - Initial public release of the Photivra engine package.
package/CITATION.cff CHANGED
@@ -9,7 +9,7 @@ abstract: "An open TypeScript engine for the science and mathematics of photogra
9
9
  repository-code: "https://github.com/photivra/photivra"
10
10
  url: "https://photivra.com"
11
11
  license: "Apache-2.0"
12
- version: "0.1.0"
12
+ version: "0.2.0"
13
13
  keywords:
14
14
  - photography
15
15
  - camera optics
package/README.md CHANGED
@@ -37,6 +37,7 @@ See the [Usage Guide](docs/USAGE.md) for the complete public API.
37
37
  ## Documentation
38
38
 
39
39
  - [Usage Guide](docs/USAGE.md)
40
+ - [Changelog](CHANGELOG.md)
40
41
  - [Public API Style](docs/API_STYLE.md)
41
42
  - [Architecture](docs/ARCHITECTURE.md)
42
43
  - [Physics Foundation](docs/PHYSICS_FOUNDATION.md)
@@ -63,7 +64,7 @@ The root package exports deterministic or explicitly labeled approximate models
63
64
 
64
65
  ### Exposure and motion
65
66
 
66
- - [EV100, relative optical exposure, and equivalent ISO compensation](docs/USAGE.md#exposure-and-equivalent-iso);
67
+ - [EV100, relative optical exposure, relative rendered exposure, and equivalent ISO compensation](docs/USAGE.md#exposure-and-iso-relations);
67
68
  - [constant-velocity projected point motion](docs/USAGE.md#projected-subject-motion);
68
69
  - [a controlled yaw/pitch camera-shake and stabilization-equivalent approximation](docs/USAGE.md#camera-shake-and-stabilization-equivalent-approximation).
69
70
 
@@ -139,13 +140,13 @@ The calling application can then use those results while keeping the underlying
139
140
 
140
141
  ## Status
141
142
 
142
- - Package version: `0.1.0`
143
+ - Package version: `0.2.0`
143
144
  - Engine API contract: `0.17.0`
144
145
  - Stability: pre-1.0 / proof of concept
145
146
 
146
147
  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.
147
148
 
148
- Making this GitHub repository public and publishing `@photivra/engine` to a package registry are separate release actions.
149
+ Creating a GitHub release/tag and publishing `@photivra/engine` are separate release actions. The tag-triggered publish workflow verifies that the `vX.Y.Z` tag matches the package version before publishing.
149
150
 
150
151
  ## Important scientific limits
151
152
 
package/dist/exposure/exposure.d.ts CHANGED
@@ -32,6 +32,37 @@ export interface RelativeOpticalExposure {
32
32
  * response and therefore must not be interpreted as a photon-count result.
33
33
  */
34
34
  export declare function calculateRelativeOpticalExposure(input: CalculateRelativeOpticalExposureInput): CalculationResult<RelativeOpticalExposure>;
35
+ export interface CalculateRelativeRenderedExposureInput {
36
+ aperture: number;
37
+ shutterSeconds: number;
38
+ iso: number;
39
+ referenceAperture: number;
40
+ referenceShutterSeconds: number;
41
+ referenceIso: number;
42
+ }
43
+ export interface RelativeRenderedExposure {
44
+ /** Nominal linear rendering multiplier; 1 equals the reference settings. */
45
+ factor: number;
46
+ /** Difference from the reference in stops. Positive means a brighter rendering. */
47
+ stops: number;
48
+ /** Image-plane optical exposure ratio before nominal ISO gain. */
49
+ opticalFactor: number;
50
+ /** Nominal ISO gain ratio relative to the reference ISO. */
51
+ isoGainFactor: number;
52
+ }
53
+ /**
54
+ * Calculates a relative linear rendering exposure from aperture, shutter, and
55
+ * nominal ISO gain.
56
+ *
57
+ * This relation is intended for deterministic educational rendering relative to
58
+ * a declared reference exposure. ISO is treated as a brightness/gain control;
59
+ * it does not create photons and this function does not model sensor noise,
60
+ * clipping, tone mapping, lens transmission, or absolute scene luminance.
61
+ *
62
+ * @param input Current and reference aperture/shutter/ISO settings.
63
+ * @returns Relative rendering factor and stop difference.
64
+ */
65
+ export declare function calculateRelativeRenderedExposure(input: CalculateRelativeRenderedExposureInput): CalculationResult<RelativeRenderedExposure>;
35
66
  export interface CalculateEquivalentIsoInput {
36
67
  baseIso: number;
37
68
  baseAperture: number;
package/dist/exposure/exposure.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,CAAC,MAAM,CAAC,CAU3B;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CA6B5C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,MAAM,CAAC,CAuB3B"}
1
+ {"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,CAAC,MAAM,CAAC,CAU3B;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CA6B5C;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,sCAAsC,GAC5C,iBAAiB,CAAC,wBAAwB,CAAC,CA6B7C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,MAAM,CAAC,CAuB3B"}
package/dist/exposure/exposure.js CHANGED
@@ -37,6 +37,41 @@ export function calculateRelativeOpticalExposure(input) {
37
37
  "Sensor response is not modeled"
38
38
  ]);
39
39
  }
40
+ /**
41
+ * Calculates a relative linear rendering exposure from aperture, shutter, and
42
+ * nominal ISO gain.
43
+ *
44
+ * This relation is intended for deterministic educational rendering relative to
45
+ * a declared reference exposure. ISO is treated as a brightness/gain control;
46
+ * it does not create photons and this function does not model sensor noise,
47
+ * clipping, tone mapping, lens transmission, or absolute scene luminance.
48
+ *
49
+ * @param input Current and reference aperture/shutter/ISO settings.
50
+ * @returns Relative rendering factor and stop difference.
51
+ */
52
+ export function calculateRelativeRenderedExposure(input) {
53
+ requirePositiveFinite("iso", input.iso);
54
+ requirePositiveFinite("referenceIso", input.referenceIso);
55
+ const optical = calculateRelativeOpticalExposure({
56
+ aperture: input.aperture,
57
+ shutterSeconds: input.shutterSeconds,
58
+ referenceAperture: input.referenceAperture,
59
+ referenceShutterSeconds: input.referenceShutterSeconds
60
+ });
61
+ const isoGainFactor = input.iso / input.referenceIso;
62
+ const factor = optical.value.factor * isoGainFactor;
63
+ return calculatedResult({
64
+ factor,
65
+ stops: Math.log2(factor),
66
+ opticalFactor: optical.value.factor,
67
+ isoGainFactor
68
+ }, "relative-rendered-exposure", "1.0.0", [
69
+ "Constant scene illumination",
70
+ "ISO is treated as nominal rendering gain, not photon creation",
71
+ "Lens transmission and sensor-specific gain behavior are not modeled",
72
+ "Clipping and display tone mapping are not modeled"
73
+ ]);
74
+ }
40
75
  /**
41
76
  * Calculates the ISO/gain setting that preserves nominal rendered exposure
42
77
  * after changing aperture and/or shutter, assuming all other factors remain
package/dist/exposure/exposure.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"exposure.js","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAS9D;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAqC;IAErC,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9D,OAAO,gBAAgB,CACrB,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,EACnE,oBAAoB,EACpB,OAAO,EACP,CAAC,2CAA2C,CAAC,CAC9C,CAAC;AACJ,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAA4C;IAE5C,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACpE,qBAAqB,CACnB,yBAAyB,EACzB,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IAEF,MAAM,OAAO,GACX,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3D,MAAM,SAAS,GACb,KAAK,CAAC,uBAAuB;QAC7B,CAAC,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAEnC,OAAO,gBAAgB,CACrB;QACE,MAAM;QACN,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;KACzB,EACD,2BAA2B,EAC3B,OAAO,EACP;QACE,6BAA6B;QAC7B,kCAAkC;QAClC,gCAAgC;KACjC,CACF,CAAC;AACJ,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,qBAAqB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1D,qBAAqB,CAAC,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtE,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9D,MAAM,SAAS,GACb,KAAK,CAAC,kBAAkB;QACxB,CAAC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,QAAQ,GACZ,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAE3D,OAAO,gBAAgB,CACrB,KAAK,CAAC,OAAO,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,EACtC,6BAA6B,EAC7B,OAAO,EACP;QACE,6BAA6B;QAC7B,qEAAqE;QACrE,qEAAqE;KACtE,CACF,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"exposure.js","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -20,7 +20,7 @@ export { calculateDefocusCircle, calculateDepthOfField, type CalculateDefocusCir
20
20
  export type { CameraConfiguration, CameraSupport, ExposureConfiguration, FocusConfiguration, LensConfiguration, SensorConfiguration, StabilizationConfiguration } from "./schema/camera.js";
21
21
  export type { SceneCapability, SceneDefinition, SceneMotion, SceneObject, SceneRadiometry, Vector3 } from "./schema/scene.js";
22
22
  export { calculateProjectedMotionBlur, type CalculateProjectedMotionBlurInput, type ProjectedMotionBlur } from "./motion/projected-motion.js";
23
- export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure, type CalculateEquivalentIsoInput, type CalculateExposureValue100Input, type CalculateRelativeOpticalExposureInput, type RelativeOpticalExposure } from "./exposure/exposure.js";
23
+ export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure, calculateRelativeRenderedExposure, type CalculateEquivalentIsoInput, type CalculateExposureValue100Input, type CalculateRelativeOpticalExposureInput, type CalculateRelativeRenderedExposureInput, type RelativeOpticalExposure, type RelativeRenderedExposure } from "./exposure/exposure.js";
24
24
  export { estimateCameraShakeBlur, type CameraShakeBlurSample, type CameraShakeEstimate, type EstimateCameraShakeBlurInput } from "./stabilization/camera-shake.js";
25
25
  export { calculatePhotoelectrons, calculateSignalToNoise, type CalculatePhotoelectronsInput, type CalculateSignalToNoiseInput, type SignalToNoise } from "./sensor/signal-noise.js";
26
26
  export { simulatePocCamera, type PocSimulationRequest, type PocSimulationResponse } from "./simulation/poc-simulation.js";
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js CHANGED
@@ -19,7 +19,7 @@ export { estimateEquivalentViewingCircleOfConfusion } from "./optics/circle-of-c
19
19
  export { calculateThinLensImageDistance } from "./optics/thin-lens.js";
20
20
  export { calculateDefocusCircle, calculateDepthOfField } from "./optics/depth-of-field.js";
21
21
  export { calculateProjectedMotionBlur } from "./motion/projected-motion.js";
22
- export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure } from "./exposure/exposure.js";
22
+ export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure, calculateRelativeRenderedExposure } from "./exposure/exposure.js";
23
23
  export { estimateCameraShakeBlur } from "./stabilization/camera-shake.js";
24
24
  export { calculatePhotoelectrons, calculateSignalToNoise } from "./sensor/signal-noise.js";
25
25
  export { simulatePocCamera } from "./simulation/poc-simulation.js";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAW3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EAGrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,4BAA4B,EAG7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,2BAA2B,EAG5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EAGlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0CAA0C,EAG3C,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,8BAA8B,EAG/B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAsBpC,OAAO,EACL,4BAA4B,EAG7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAKjC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,uBAAuB,EAIxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAW3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EAGrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,4BAA4B,EAG7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,2BAA2B,EAG5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EAGlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0CAA0C,EAG3C,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,8BAA8B,EAG/B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACL,4BAA4B,EAG7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,iCAAiC,EAOlC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,uBAAuB,EAIxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC"}
package/docs/MOTION_AND_SIGNAL.md CHANGED
@@ -33,6 +33,8 @@ Camera motion is not folded into subject motion. Camera shake is modeled separat
33
33
 
34
34
  These calculations do not imply a photon count because they do not include scene radiance, lens transmission/T-stop, vignetting, spectral response, or sensor calibration.
35
35
 
36
+ `calculateRelativeRenderedExposure()` combines the relative optical exposure with the nominal ISO gain ratio (`iso / referenceIso`) and reports both the linear factor and stop difference. It is intended for deterministic relative rendering against a declared reference, not for radiometric calibration; it does not model photon creation, sensor noise, clipping, tone mapping, or lens transmission.
37
+
36
38
  `calculateEquivalentIso()` treats ISO as nominal gain/brightness compensation needed to preserve rendered exposure after an aperture/shutter change. It is not used as a shortcut for noise or photon creation.
37
39
 
38
40
  ## Signal/noise primitives
package/docs/USAGE.md CHANGED
@@ -259,7 +259,7 @@ The model assumes constant world-space linear velocity. It tracks a representati
259
259
 
260
260
  See [Motion and Signal Foundation](MOTION_AND_SIGNAL.md#projected-subject-motion).
261
261
 
262
- ## Exposure and equivalent ISO
262
+ ## Exposure and ISO relations
263
263
 
264
264
  Use `calculateExposureValue100()` for EV100:
265
265
 
@@ -290,6 +290,28 @@ console.log(exposure.value.factor);
290
290
  console.log(exposure.value.stops);
291
291
  ```
292
292
 
293
+ Use `calculateRelativeRenderedExposure()` when a renderer needs a nominal linear brightness multiplier that combines the aperture/shutter optical-exposure change with ISO gain relative to declared reference settings:
294
+
295
+ ```ts
296
+ import { calculateRelativeRenderedExposure } from "@photivra/engine";
297
+
298
+ const rendered = calculateRelativeRenderedExposure({
299
+ aperture: 5.6,
300
+ shutterSeconds: 1 / 2000,
301
+ iso: 1600,
302
+ referenceAperture: 5.6,
303
+ referenceShutterSeconds: 1 / 1000,
304
+ referenceIso: 800
305
+ });
306
+
307
+ console.log(rendered.value.factor); // 1
308
+ console.log(rendered.value.stops); // 0
309
+ console.log(rendered.value.opticalFactor); // 0.5
310
+ console.log(rendered.value.isoGainFactor); // 2
311
+ ```
312
+
313
+ This is a relative rendering relation, not a radiometric sensor model. ISO is treated as nominal rendering gain; it does not create photons, and the function does not model clipping, tone mapping, lens transmission, or sensor-specific noise behavior.
314
+
293
315
  Use `calculateEquivalentIso()` to calculate the nominal ISO/gain compensation needed to preserve rendered exposure:
294
316
 
295
317
  ```ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@photivra/engine",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
6
6
  "type": "module",
@@ -29,6 +29,7 @@
29
29
  "dist/sensor",
30
30
  "dist/simulation",
31
31
  "dist/stabilization",
32
+ "CHANGELOG.md",
32
33
  "README.md",
33
34
  "CITATION.cff",
34
35
  "LICENSE",