@photivra/engine 2.8.0 → 2.9.0

package/docs/QUICK_START.md

@@ -1151,6 +1151,65 @@ strips.forEach((strip, i) => stitched.set(strip.image.samples as Uint8Array, i *
 console.log(strips[0]!.region, stitched.length);
 ```
 
+### A whole-frame DNG from parts
+
+`serializeSimulatedCaptureDngFromParts(options, parts)` writes the whole-frame DNG of `options` (`output.format: "dng"`,
+no `output.region`) from region renders of the same request, so a large DNG's RAW can render in parallel like a JPEG or PNG.
+Each part is a region result's `raw` and `region` (any region format; `result.raw` holds the region's native sites,
+`result.region.nativeRect` where they lie). A region's sites are the whole render's sites, so the joined RAW is the whole
+render's RAW; the function then resolves the request and writes the DNG exactly as `simulateCapture` does, and the bytes
+are the same. The parts must cover the frame's native raster; where they overlap (the demosaic margin) their sites must
+agree, and a part from another request is refused. Render the parts with a fixed white balance and without `output.dng`
+(a region takes neither; the RAW codes do not depend on the white-balance intent): auto white balance and the capture time
+apply to the DNG options passed here, and auto white balance is measured over the joined frame.
+
+Tests compare the joined DNG byte for byte with the whole-frame DNG for bilinear and AHD, diffraction with the four-spot
+filter and the 2 × 2 box, auto white balance with a capture time, a reflectance-function scene and the environment path.
+On the Photivra app's 24 MP request (6000 × 4000 at 6 µm, 24 parts of about 1024 pixels; Node, one thread) the DNG was
+the same bytes both ways; the parts took 58.1 s of CPU against 50.6 s for one whole render (Quality options: 119.3 s against
+113.6 s) and the join 2.6 s, so on four workers the wall time is roughly a quarter of the whole render's.
+
+```ts
+import { serializeSimulatedCaptureDngFromParts, simulateCapture, type SimulateCaptureDngPart, type SimulateCaptureOptions } from "@photivra/engine";
+
+const dngFrame: SimulateCaptureOptions = { scene: { preset: "siemens-star" }, output: { width: 96, height: 64, format: "dng" } };
+// Two strips rendered as sRGB regions (in an application, in separate Web Workers), then one DNG of the whole frame.
+const parts: SimulateCaptureDngPart[] = await Promise.all([0, 32].map(async (y) => {
+  const part = await simulateCapture({ ...dngFrame, output: { width: 96, height: 64, region: { x: 0, y, width: 96, height: 32 } } });
+  return { raw: part.raw, region: part.region! };
+}));
+const dng = await serializeSimulatedCaptureDngFromParts(dngFrame, parts);
+console.log(dng.bytes.length);
+```
+
+### A Print JPEG written in strips
+
+At 1:1 (output size equal to the crop), a Print JPEG's rows can be coded on separate workers.
+`createPrintJpegStrip(input, { y, height, samples })` codes crop rows `y` to `y + height` (8-bit sRGB RGB, crop-wide;
+`y` a multiple of 8, and `height` too unless the strip ends at the image's bottom) apart from the rows before them.
+`composePrintJpegStrips(input, strips)` joins strips that cover the image, top to bottom, into the file
+`createPrintJpegTask` writes for the same plan and source pixels: the same bytes. Only the first block of each strip
+depends on the strip before it (its DC differences), so the join codes that block and copies the rest of the strip's
+bits. The output's `providerReads` is 0, because no source is read.
+
+Tests compare the joined file with the task's file byte for byte, for several splits, crops, quantization steps and a
+density. For a 24 MP file (Node, one thread), the whole task took 8.1 s; four strips took 1.9 s each, and the join took
+1.1 s (a 64 MB file). In the Photivra app (Chromium, four workers), writing a 24 MP JPEG takes about 3 s instead of 9–12 s.
+
+```ts
+import { composePrintJpegStrips, createPrintJpegStrip, type PrintJpegInput } from "@photivra/engine";
+
+const width = 64, height = 40, pixels = new Uint8Array(width * height * 3).fill(120);
+const jpegPlan: PrintJpegInput = {
+  source: { captureId: "capture", imageStateId: "sdr", artifactId: "pixels", sha256: "0".repeat(64), width, height, encoding: "encoded-srgb-8-rgb" },
+  crop: { x: 0, y: 0, width, height }, outputWidth: width, outputHeight: height, quantizationStep: 2, maximumEncodedBytes: 1_000_000, maximumProviderReads: 16
+};
+// Two strips (in an application, coded in separate Web Workers), then the file.
+const strips = [[0, 24], [24, 16]].map(([y, rows]) => createPrintJpegStrip(jpegPlan, { y: y!, height: rows!, samples: pixels.slice(y! * width * 3, (y! + rows!) * width * 3) }));
+const jpeg = composePrintJpegStrips(jpegPlan, strips);
+console.log(jpeg.bytes.length);
+```
+
 ## Ideal reference (2.3)
 
 `simulateIdealReference(options)` takes the same options as `simulateCapture` and returns what the camera

package/docs/api/capture-export-jpeg.md

@@ -14,3 +14,13 @@ was exactly a negative half-integer. The repository's test images are unchanged.
 ```ts
 EXPORT_JPEG_ENCODER_ID = "photivra-baseline-jpeg-444-v2" as const
 ```
+
+## JpegStripBits
+
+The entropy-coded bits of consecutive blocks of one image, coded apart from the blocks before them (`encodeJpegStrip`):
+the first block's quantized coefficients (3 × 64, natural order), whose DC differences need the block before; the other
+blocks' bits, unstuffed, most-significant first; and the last block's DC values, which the next strip's first block needs.
+
+```ts
+export interface JpegStripBits { first: Float64Array; bits: Uint8Array; bitLength: number; blockCount: number; lastDc: Float64Array }
+```

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.8.0" as const
+ENGINE_API_VERSION = "2.9.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.8.0",
-  "engineApiVersion": "2.8.0",
+  "packageVersion": "2.9.0",
+  "engineApiVersion": "2.9.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -2097,6 +2097,11 @@
       "source": "src/capture/native-environment-raw.ts",
       "kind": "runtime"
     },
+    {
+      "name": "composePrintJpegStrips",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "runtime"
+    },
     {
       "name": "composeRelativeErrorBounds",
       "source": "src/gpu/image-kernel-execution.ts",
@@ -2377,6 +2382,11 @@
       "source": "src/color/illuminants.ts",
       "kind": "runtime"
     },
+    {
+      "name": "createPrintJpegStrip",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "runtime"
+    },
     {
       "name": "createPrintJpegTask",
       "source": "src/output/print-jpeg.ts",
@@ -3882,6 +3892,11 @@
       "source": "src/equipment/iso-capabilities.ts",
       "kind": "type"
     },
+    {
+      "name": "JpegStripBits",
+      "source": "src/capture/export-jpeg.ts",
+      "kind": "type"
+    },
     {
       "name": "LateralCaLensCorrection",
       "source": "src/output/lens-corrections.ts",
@@ -5522,6 +5537,16 @@
       "source": "src/output/print-jpeg.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintJpegStrip",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "type"
+    },
+    {
+      "name": "PrintJpegStripInput",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintJpegTask",
       "source": "src/output/print-jpeg.ts",
@@ -7867,6 +7892,11 @@
       "source": "src/capture/simulated-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "serializeSimulatedCaptureDngFromParts",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "setExposureCompensationOnMeterTarget",
       "source": "src/exposure/metering-target.ts",
@@ -7977,6 +8007,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureDngPart",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureExposureMode",
       "source": "src/facade/simulate-capture.ts",

package/docs/api/facade-scene-radiance.md

@@ -175,7 +175,8 @@ export type SceneMaterialPoint = Omit<ScenePlanePoint, "wavelengthNanometers">;
 
 ## ScenePlanePoint
 
-A point of the scene plane passed to caller scene functions.
+A point of the scene plane passed to caller scene functions: a new object for every call, which the engine does not read
+after the call (not frozen: freezing cost about 40 % of a chart lookup).
 
 ```ts
 export interface ScenePlanePoint {

package/docs/api/facade-simulate-capture.md

@@ -62,6 +62,23 @@ export interface IdealReferenceResult {
 }
 ```
 
+## serializeSimulatedCaptureDngFromParts
+
+Writes the whole-frame DNG of `options` (`output.format: "dng"`, no `output.region`) from the packed RAW of region renders of
+the same request (#391), so the RAW can render in parallel. A region render's native sites are the same sites as the whole
+render's (each site's seeds come from its index in the whole raster), so the joined RAW is the whole render's RAW, and the
+request is resolved and written exactly as `simulateCapture` writes its DNG: the bytes are the same. The parts must cover
+every native site of the frame; where they overlap (each region carries the demosaic margin) their sites must agree. Region
+renders of the request with any format serve (a region's own `output.format` does not change its RAW). A region cannot take
+`output.whiteBalance: "auto"` or `output.dng`: render the parts with a fixed white balance (the RAW codes do not depend on the
+white-balance intent) and pass the DNG's own options here, where auto white balance is measured over the joined frame.
+
+```ts
+export async function serializeSimulatedCaptureDngFromParts(options: SimulateCaptureOptions, parts: readonly SimulateCaptureDngPart[]): Promise<NativeRawDng>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
 ## SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES
 
 Default midpoint samples per axis of `sensor.pixelAperture: "box"`.
@@ -176,6 +193,17 @@ edge-directed method that reduces zipper and false colour on sharp edges.
 export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
+## SimulateCaptureDngPart
+
+One part of a whole-frame DNG (#391): a region render's packed RAW and where its native sites lie (`result.raw`, `result.region`).
+
+```ts
+export interface SimulateCaptureDngPart {
+  raw: Pick<NativeRawOutput, "codes" | "blackLevels" | "digitalSaturationCodes" | "saturationFlags" | "effectiveSaturationCodes">;
+  region: { nativeRect: { x: number; y: number; width: number; height: number } };
+}
+```
+
 ## SimulateCaptureExposureMode
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/optics-diffraction-psf-profile.md

@@ -72,7 +72,7 @@ export interface DiffractionLimitedPsfProfile {
   /** Largest truncated energy over the wavelengths. */
   maximumTruncatedEnergyFraction: number;
   /**
-   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ 192 (cells far larger than the pattern) use the real-space
+   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ `AIRY_REAL_SPACE_MINIMUM_BETA` (192 in 2.5–2.8.1, then 32) use the real-space
    * encircled-energy method; `realSpaceWavelengthsNm` lists them, and `method` is `"frequency-domain-and-real-space"` when both ran.
    * `maximumRadialNodes` counts frequency-domain radial nodes (0 when only the real-space method ran); `maximumAngularNodes` the
    * angular nodes of either method (for the real-space method, all θ nodes of one wavelength).

package/docs/api/output-print-jpeg.md

@@ -2,6 +2,31 @@
 
 The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
+## composePrintJpegStrips
+
+Joins the strips of a 1:1 Print JPEG (`createPrintJpegStrip`), covering the image top to bottom in order, into its file:
+the same bytes `createPrintJpegTask` writes for the plan and the same source pixels. No source is read, so the output's
+`providerReads` is 0.
+
+```ts
+export function composePrintJpegStrips(input:PrintJpegInput,strips:readonly PrintJpegStrip[]):PrintJpegOutput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createPrintJpegStrip
+
+Codes rows of a 1:1 Print JPEG (output size equal to the crop) apart from the rows before them, so a large file's strips
+can be written on separate workers. `strip.y` is a multiple of 8 and `strip.height` a multiple of 8 unless the strip ends at
+the image's bottom; `strip.samples` are those crop rows' 8-bit sRGB RGB, crop-wide. `composePrintJpegStrips` joins strips that
+cover the image, in order, into the bytes `createPrintJpegTask` writes for the same plan and source pixels.
+
+```ts
+export function createPrintJpegStrip(input:PrintJpegInput,strip:PrintJpegStripInput):PrintJpegStrip;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## createPrintJpegTask
 
 Creates the export task. Filtering weights each source pixel by its exact area overlap, after decoding the declared 8-bit SDR source.
@@ -123,6 +148,22 @@ export interface PrintJpegSource {
 }
 ```
 
+## PrintJpegStrip
+
+A strip of a 1:1 Print JPEG's coded blocks (`createPrintJpegStrip`), for `composePrintJpegStrips`.
+
+```ts
+export interface PrintJpegStrip {readonly y:number;readonly height:number;readonly width:number;readonly quantizationStep:number;readonly bits:JpegStripBits}
+```
+
+## PrintJpegStripInput
+
+Rows of a 1:1 Print JPEG for `createPrintJpegStrip`: crop rows `y` to `y + height` (relative to the crop), crop-wide RGB.
+
+```ts
+export interface PrintJpegStripInput {y:number;height:number;samples:Uint8Array}
+```
+
 ## PrintJpegTask
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",