@photivra/engine 0.1.0 → 0.4.0

package/dist/output/capture-geometry.d.ts

@@ -0,0 +1,225 @@
+import { type CalculationProvenance, type CalculationResult } from "../core/calculation-result.js";
+import { type NativeImageRaster, type RasterDimensions, type SensorImagingArea } from "../sensor/sensor-geometry.js";
+export type CaptureOrientation = "landscape" | "portrait-clockwise" | "landscape-inverted" | "portrait-counter-clockwise";
+export interface RasterPoint {
+    x: number;
+    y: number;
+}
+export interface RasterVector {
+    x: number;
+    y: number;
+}
+/**
+ * Integer half-open rectangle in raster coordinates.
+ *
+ * Coordinates use a top-left origin with +X to the right and +Y downward.
+ * The covered extent is [x, x + width) × [y, y + height).
+ */
+export interface RasterRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PhysicalBoundsFromOpticalAxisMm {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface ResolveCaptureGeometryInput {
+    imagingArea: SensorImagingArea;
+    nativeRaster: NativeImageRaster;
+    orientation: CaptureOrientation;
+    /**
+     * Active capture rectangle in native sensor raster coordinates.
+     *
+     * Defaults to the full native raster.
+     */
+    activeCaptureRect?: RasterRect;
+    /**
+     * Final digital/output crop in oriented active-capture raster coordinates.
+     *
+     * Defaults to the full oriented active capture.
+     */
+    outputCropRect?: RasterRect;
+    /**
+     * Final output raster after optional digital crop/resampling.
+     *
+     * Defaults to the output-crop dimensions. The output raster must preserve
+     * the crop aspect ratio within a small integer-rounding tolerance.
+     */
+    outputRaster?: RasterDimensions;
+}
+export interface ResolvedCaptureGeometry {
+    native: {
+        imagingArea: SensorImagingArea;
+        raster: NativeImageRaster;
+    };
+    activeCapture: {
+        nativeRect: RasterRect;
+        imagingArea: SensorImagingArea;
+        /**
+         * Top-left active-area offset from the native imaging-area top-left.
+         */
+        physicalOffsetMm: {
+            x: number;
+            y: number;
+        };
+        /** Active-area center relative to the native optical axis. */
+        centerOffsetFromOpticalAxisMm: RasterVector;
+        /** Native physical bounds relative to the optical axis. */
+        physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+        /**
+         * Current generic model assumes native image samples uniformly span the
+         * declared physical imaging area.
+         */
+        imagingAreaDerivation: "uniform-native-raster";
+        raster: RasterDimensions;
+    };
+    orientedCapture: {
+        orientation: CaptureOrientation;
+        imagingArea: SensorImagingArea;
+        /** Oriented physical bounds relative to the optical axis. */
+        physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+        raster: RasterDimensions;
+    };
+    output: {
+        /**
+         * Digital/output crop expressed in oriented active-capture coordinates.
+         *
+         * This crop does not mutate physical sensor identity or active-capture
+         * geometry.
+         */
+        cropRect: RasterRect;
+        raster: RasterDimensions;
+        /** Physical region retained by the digital/output crop. */
+        imagingArea: SensorImagingArea;
+        physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+        centerOffsetFromOpticalAxisMm: RasterVector;
+        sourceRetainedAreaFraction: number;
+        /** Pixel-domain resampling from oriented active capture into output. */
+        orientedCaptureToOutputScale: {
+            x: number;
+            y: number;
+            axisRelativeDifference: number;
+        };
+    };
+}
+export interface TransformRasterPointInput {
+    point: RasterPoint;
+    nativeRaster: NativeImageRaster;
+    orientation: CaptureOrientation;
+}
+export interface TransformRasterVectorInput {
+    vector: RasterVector;
+    orientation: CaptureOrientation;
+}
+export interface TransformRasterRectInput {
+    rect: RasterRect;
+    nativeRaster: NativeImageRaster;
+    orientation: CaptureOrientation;
+}
+export interface CalculateActiveCaptureFieldOfViewInput {
+    imagingArea: SensorImagingArea;
+    nativeRaster: NativeImageRaster;
+    orientation: CaptureOrientation;
+    activeCaptureRect?: RasterRect;
+    focalLengthMm: number;
+    focusDistanceM?: number;
+}
+export interface CalculateOutputFieldOfViewInput {
+    imagingArea: SensorImagingArea;
+    nativeRaster: NativeImageRaster;
+    orientation: CaptureOrientation;
+    activeCaptureRect?: RasterRect;
+    outputCropRect?: RasterRect;
+    focalLengthMm: number;
+    focusDistanceM?: number;
+}
+export interface ActiveCaptureFieldOfView {
+    orientation: CaptureOrientation;
+    horizontalDegrees: number;
+    verticalDegrees: number;
+    /**
+     * Larger of the two opposite-corner diagonal angular spans. For centered
+     * crops both diagonal spans are equal.
+     */
+    diagonalDegrees: number;
+    horizontalBoundsDegrees: {
+        minimum: number;
+        maximum: number;
+    };
+    verticalBoundsDegrees: {
+        minimum: number;
+        maximum: number;
+    };
+    diagonalDegreesByCornerPair: {
+        topLeftToBottomRight: number;
+        topRightToBottomLeft: number;
+    };
+    activeImagingArea: SensorImagingArea;
+    centerOffsetFromOpticalAxisMm: RasterVector;
+    projection: {
+        projectionDistanceMm: number;
+        provenance: CalculationProvenance;
+    };
+}
+export interface OutputFieldOfView {
+    orientation: CaptureOrientation;
+    horizontalDegrees: number;
+    verticalDegrees: number;
+    diagonalDegrees: number;
+    horizontalBoundsDegrees: {
+        minimum: number;
+        maximum: number;
+    };
+    verticalBoundsDegrees: {
+        minimum: number;
+        maximum: number;
+    };
+    diagonalDegreesByCornerPair: {
+        topLeftToBottomRight: number;
+        topRightToBottomLeft: number;
+    };
+    outputImagingArea: SensorImagingArea;
+    centerOffsetFromOpticalAxisMm: RasterVector;
+    projection: {
+        projectionDistanceMm: number;
+        provenance: CalculationProvenance;
+    };
+}
+/**
+ * Transforms a continuous native raster edge-coordinate point into oriented
+ * capture coordinates. Pixel centers can be represented with +0.5 offsets.
+ */
+export declare function transformNativeRasterPointToOriented(input: TransformRasterPointInput): RasterPoint;
+/** Transforms an oriented raster edge-coordinate point back to native coordinates. */
+export declare function transformOrientedRasterPointToNative(input: TransformRasterPointInput): RasterPoint;
+/** Rotates a native raster vector into oriented coordinates. */
+export declare function transformNativeRasterVectorToOriented(input: TransformRasterVectorInput): RasterVector;
+/** Rotates an oriented raster vector back into native coordinates. */
+export declare function transformOrientedRasterVectorToNative(input: TransformRasterVectorInput): RasterVector;
+/** Transforms an integer half-open native raster rectangle into oriented coordinates. */
+export declare function transformNativeRasterRectToOriented(input: TransformRasterRectInput): RasterRect;
+/** Transforms an oriented integer half-open rectangle back to native coordinates. */
+export declare function transformOrientedRasterRectToNative(input: TransformRasterRectInput): RasterRect;
+/**
+ * Resolves native sensor geometry, active capture, physical camera orientation,
+ * and final digital/output geometry without conflating their identities.
+ */
+export declare function resolveCaptureGeometry(input: ResolveCaptureGeometryInput): CalculationResult<ResolvedCaptureGeometry>;
+/**
+ * Calculates asymmetric horizontal/vertical FOV plus opposite-corner diagonal
+ * spans for the active physical capture area after physical camera orientation.
+ *
+ * Final digital/output crop is intentionally excluded.
+ */
+export declare function calculateActiveCaptureFieldOfView(input: CalculateActiveCaptureFieldOfViewInput): CalculationResult<ActiveCaptureFieldOfView>;
+/**
+ * Calculates final visible field of view after physical active capture,
+ * orientation, and digital/output crop. Output raster resolution does not
+ * affect this optical/framing result.
+ */
+export declare function calculateOutputFieldOfView(input: CalculateOutputFieldOfViewInput): CalculationResult<OutputFieldOfView>;
+//# sourceMappingURL=capture-geometry.d.ts.map

package/dist/output/capture-geometry.d.ts.map

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