@photivra/engine 0.1.0

package/dist/simulation/poc-simulation.d.ts

@@ -0,0 +1,264 @@
+import type { CalculationProvenance } from "../core/calculation-result.js";
+import type { Vector3 } from "../schema/scene.js";
+export interface PocSimulationRequest {
+    sensor: {
+        widthMm: number;
+        heightMm: number;
+        pixelWidth: number;
+        pixelHeight: number;
+    };
+    lens: {
+        focalLengthMm: number;
+        aperture: number;
+    };
+    exposure: {
+        shutterSeconds: number;
+        iso: number;
+    };
+    focus: {
+        focusDistanceM: number;
+        circleOfConfusionMm?: number;
+        equivalentViewingCircleOfConfusion?: {
+            referenceSensorWidthMm: number;
+            referenceSensorHeightMm: number;
+            referenceCircleOfConfusionMm: number;
+        };
+    };
+    crop: {
+        factor: number;
+    };
+    diffraction: {
+        wavelengthNm: number;
+    };
+    motion: {
+        positionM: Vector3;
+        velocityMps: Vector3;
+    };
+    subject?: {
+        widthM: number;
+        heightM: number;
+        distanceM: number;
+    };
+    defocusSamples?: readonly {
+        id: string;
+        distanceM: number;
+    }[];
+    samplingSamples?: readonly {
+        id: string;
+        widthM: number;
+        heightM: number;
+        distanceM: number;
+    }[];
+    motionSamples?: readonly {
+        id: string;
+        positionM: Vector3;
+        velocityMps: Vector3;
+    }[];
+    subjectCrop?: {
+        targetSubjectHeightFraction: number;
+    };
+    cameraShake?: {
+        angularVelocityRadPerSec: {
+            yaw: number;
+            pitch: number;
+        };
+        stabilizationStopsEquivalent: number;
+    };
+    apertureShape?: {
+        bladeCount: number;
+        firstBladeEdgeAngleDegrees?: number;
+    };
+    diagnostics?: {
+        subjectMotionSampleId?: string;
+    };
+}
+interface FieldOfViewSummary {
+    horizontalDegrees: number;
+    verticalDegrees: number;
+    diagonalDegrees: number;
+}
+export interface PocSimulationResponse {
+    apiVersion: "0.17.0";
+    projection: {
+        kind: "focus-aware-thin-lens";
+        focusDistanceM: number;
+        imageDistanceMm: number;
+        infinityProjectionScale: number;
+        provenance: CalculationProvenance;
+    };
+    /**
+     * Full-sensor optical field of view before any digital crop.
+     */
+    fieldOfView: {
+        horizontalDegrees: number;
+        verticalDegrees: number;
+        diagonalDegrees: number;
+    };
+    sensor: {
+        pixelPitchMicrometers: number;
+    };
+    crop: {
+        cropFactor: number;
+        pixelWidth: number;
+        pixelHeight: number;
+        megapixels: number;
+        retainedAreaFraction: number;
+        effectiveFieldOfView: FieldOfViewSummary;
+    };
+    focusCriterion: {
+        source: "explicit";
+        circleOfConfusionMm: number;
+    } | {
+        source: "equivalent-viewing-approximation";
+        circleOfConfusionMm: number;
+        scaleFactor: number;
+        provenance: {
+            kind: "approximation";
+            model: string;
+            modelVersion: string;
+            assumptions?: readonly string[];
+        };
+    };
+    depthOfField: {
+        hyperfocalDistanceM: number;
+        nearLimitM: number;
+        farLimitM: number | null;
+        totalDepthOfFieldM: number | null;
+    };
+    diffraction: {
+        firstZeroDiameterMicrometers: number;
+        airyDiameterPixels: number;
+        pupilModel: "ideal-circular";
+        provenance: CalculationProvenance;
+    };
+    motion: {
+        distanceMm: number;
+        distancePixels: number;
+        deltaXMm: number;
+        deltaYMm: number;
+        deltaXPixels: number;
+        deltaYPixels: number;
+    };
+    exposure: {
+        ev100: number;
+        iso: number;
+    };
+    subjectSampling?: {
+        widthMm: number;
+        heightMm: number;
+        widthPixels: number;
+        heightPixels: number;
+    };
+    defocusSamples?: readonly {
+        id: string;
+        distanceM: number;
+        diameterMm: number;
+        diameterPixels: number;
+    }[];
+    samplingSamples?: readonly {
+        id: string;
+        widthMm: number;
+        heightMm: number;
+        widthPixels: number;
+        heightPixels: number;
+    }[];
+    motionSamples?: readonly {
+        id: string;
+        distanceMm: number;
+        distancePixels: number;
+        deltaXMm: number;
+        deltaYMm: number;
+        deltaXPixels: number;
+        deltaYPixels: number;
+    }[];
+    subjectCrop?: {
+        /** Additional crop relative to the already-applied request crop. */
+        additionalCropFactor: number;
+        /** Total linear crop relative to the full sensor. */
+        totalCropFactor: number;
+        pixelWidth: number;
+        pixelHeight: number;
+        megapixels: number;
+        subjectHeightFraction: number;
+        subjectClipped: boolean;
+        additionalCropApplied: boolean;
+        effectiveFieldOfView: FieldOfViewSummary;
+    };
+    apertureShape?: {
+        bladeCount: number;
+        sunstarRayCount: number;
+        sunstarRayAnglesDegrees: readonly number[];
+        normalizedVertices: readonly {
+            x: number;
+            y: number;
+        }[];
+        provenance: CalculationProvenance;
+    };
+    primarySubjectDiagnostics?: {
+        subjectDistanceM: number;
+        samplingHeightPixels: number;
+        defocusDiameterPixels: number;
+        diffractionFirstZeroDiameterPixels: number;
+        diffractionModel: string;
+        subjectMotion?: {
+            id: string;
+            distancePixels: number;
+        };
+        cameraShake?: {
+            stabilizedDistancePixels: number;
+            provenanceKind: "approximation";
+        };
+        comparisonCaution: string;
+    };
+    cameraShake?: {
+        residualMotionFactor: number;
+        unstabilized: {
+            deltaXmm: number;
+            deltaYmm: number;
+            distanceMm: number;
+            distancePixels: number;
+            deltaXPixels: number;
+            deltaYPixels: number;
+        };
+        stabilized: {
+            deltaXmm: number;
+            deltaYmm: number;
+            distanceMm: number;
+            distancePixels: number;
+            deltaXPixels: number;
+            deltaYPixels: number;
+        };
+        provenance: {
+            kind: "approximation";
+            model: string;
+            modelVersion: string;
+            assumptions?: readonly string[];
+        };
+    };
+    provenance: {
+        kind: "calculated" | "mixed";
+        components: {
+            projection: "calculated";
+            fieldOfView: "calculated";
+            crop: "calculated";
+            focusCriterion: "calculated" | "approximation";
+            depthOfField: "calculated";
+            diffraction: "calculated";
+            motion: "calculated";
+            exposure: "calculated";
+            apertureShape?: "calculated";
+            cameraShake?: "approximation";
+        };
+        note: string;
+    };
+}
+/**
+ * Composes the validated POC calculations into a single renderer/agent-facing
+ * response without introducing any new photographic model.
+ *
+ * @param request Complete POC simulation request with explicit physical units.
+ * @returns Serializable POC metrics for one camera/scene configuration.
+ */
+export declare function simulatePocCamera(request: PocSimulationRequest): PocSimulationResponse;
+export {};
+//# sourceMappingURL=poc-simulation.d.ts.map

package/dist/simulation/poc-simulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poc-simulation.d.ts","sourceRoot":"","sources":["../../src/simulation/poc-simulation.ts"],"names":[],"mappings":"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"}