@photivra/engine 2.1.0 → 2.2.1

package/docs/api/output-native-capture-sdr.md

@@ -24,10 +24,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## NATIVE_CAPTURE_SDR_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumPixels` is the default pixel limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
-NATIVE_CAPTURE_SDR_LIMITS = Object.freeze({ maximumPixels: 24_000_000,
+NATIVE_CAPTURE_SDR_LIMITS = Object.freeze({ maximumPixels: 24_000_000, ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
   maximumDimension: 16_384, tileWidth: 256, tileHeight: 32, maximumTileStorageSamples: 32_768 })
 ```
 
@@ -51,6 +51,11 @@ export interface NativeCaptureSdrInput {
   profile: SdrRenderingProfile;
   /** Limit on the size of the integer output. Checked before anything is allocated or any tile is read. */
   maximumOutputBytes: number;
+  /**
+   * Optional opt-in pixel limit for large captures: an integer from 1 to `NATIVE_CAPTURE_SDR_LIMITS.ceilingPixels`.
+   * Default `NATIVE_CAPTURE_SDR_LIMITS.maximumPixels` (24 000 000). `maximumOutputBytes` still applies.
+   */
+  maximumPixels?: number;
 }
 ```
 

package/docs/api/output-png-encoder.md

@@ -13,9 +13,11 @@ PNG_ENCODER_ID = "photivra-png-rgb-v1" as const
 ## PNG_ENCODER_LIMITS
 
 Limits, checked before allocation. 100 MP (megapixels) of 16-bit RGB is about 600 MB of filtered scanlines.
+`maximumPixels` is the default; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
-PNG_ENCODER_LIMITS = Object.freeze({ maximumDimension: 65535, maximumPixels: 100_000_000, maximumIccProfileBytes: 4_000_000 })
+PNG_ENCODER_LIMITS = Object.freeze({ maximumDimension: 65535, maximumPixels: 100_000_000, ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
+  maximumIccProfileBytes: 4_000_000 })
 ```
 
 ## PngCicpPrimaries
@@ -74,6 +76,11 @@ export interface PngEncodeInput {
   compression?: "stored" | "fixed-huffman";
   /** PNG filter type 0..4 for every row, or the specification's minimum-sum-of-absolute-differences heuristic. Default "adaptive". */
   filter?: "none" | "sub" | "up" | "average" | "paeth" | "adaptive";
+  /**
+   * Optional opt-in pixel limit: an integer from 1 to `PNG_ENCODER_LIMITS.ceilingPixels`. Default
+   * `PNG_ENCODER_LIMITS.maximumPixels` (100 000 000). It does not change the encoded bytes.
+   */
+  maximumPixels?: number;
 }
 ```
 

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

@@ -22,6 +22,17 @@ export function parsePrintJpegInput(input:PrintJpegInput):PrintJpegInput;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PRINT_JPEG_LIMITS
+
+Admission limits. `maximumPixels` is the default source limit; a request may raise it with its own
+`maximumPixels`, up to `ceilingPixels`. A raised limit raises the `maximumEncodedBytes` ceiling in proportion
+(256 000 000 bytes per 24 000 000 source pixels).
+
+```ts
+PRINT_JPEG_LIMITS=Object.freeze({maximumPixels:24_000_000,ceilingPixels:FULL_RESOLUTION_CEILING_PIXELS,maximumDimension:16_384,
+  maximumEncodedBytes:256_000_000,maximumProviderReads:1_000_000})
+```
+
 ## PRINT_JPEG_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -57,6 +68,12 @@ export interface PrintJpegInput {
    * carries 72/1 with ResolutionUnit = 2; that is the standard's unknown-resolution marker, not a print size.
    */
   pixelsPerInch?:number;
+  /**
+   * Optional opt-in source pixel limit for large images: an integer from 1 to `PRINT_JPEG_LIMITS.ceilingPixels`.
+   * Default `PRINT_JPEG_LIMITS.maximumPixels` (24 000 000). When given it is recorded in the XMP export plan, like the
+   * other admission budgets; the image data are unchanged.
+   */
+  maximumPixels?:number;
 }
 ```
 

package/package.json

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