@photivra/engine 0.5.0 → 0.6.0

package/dist/sensor/color-sampling.d.ts

@@ -0,0 +1,133 @@
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+export type NativeColorSamplingSiteCoordinateSystem = "native-sensor-color-sampling-site-index";
+export type SensorColorSamplingProfileCoordinateSystem = NativeColorSamplingSiteCoordinateSystem | "native-sensor-layered-spatial-relationship-not-resolved";
+export interface NativeColorSamplingSiteIndex {
+    /**
+     * Zero-based integer site index from the native sensor's left edge.
+     *
+     * This is an abstract color-sampling-site lattice index. It is not a
+     * NativeImageRaster coordinate and does not assert one site = one physical
+     * photodiode.
+     */
+    x: number;
+    /**
+     * Zero-based integer site index from the native sensor's top edge.
+     *
+     * +Y points downward in native sensor-facing coordinates.
+     */
+    y: number;
+}
+export interface MonochromeColorSamplingLayout {
+    kind: "monochrome";
+    /**
+     * Semantic measurement-channel identifier only. It is not a spectral
+     * response curve, wavelength, colorimetric primary, or calibration.
+     */
+    channelId: string;
+}
+export interface PeriodicMosaicColorSamplingLayout {
+    kind: "periodic-mosaic";
+    /**
+     * Number of color-sampling sites in one horizontal repeat period.
+     */
+    repeatWidthSites: number;
+    /**
+     * Number of color-sampling sites in one vertical repeat period.
+     */
+    repeatHeightSites: number;
+    /**
+     * Row-major semantic channel IDs for one repeating tile.
+     *
+     * Length must equal repeatWidthSites × repeatHeightSites.
+     */
+    siteChannelIds: readonly string[];
+    /**
+     * The repeat tile is anchored at native sensor sampling-site index (0, 0).
+     *
+     * Active crops and physical orientation must not silently reset this phase.
+     */
+    anchor: "native-sensor-top-left-site";
+}
+export interface LayeredColorSamplingLayout {
+    kind: "layered";
+    /**
+     * Semantic layer/channel identifiers only. They do not define spectral
+     * response, depth ordering, spatial sampling density, or registration.
+     */
+    layerChannelIds: readonly string[];
+    /**
+     * The first layered representation is deliberately structural only because
+     * real layered sensors may use unequal per-layer spatial sampling.
+     */
+    spatialSamplingRelationship: "not-resolved";
+}
+export type SensorColorSamplingLayout = MonochromeColorSamplingLayout | PeriodicMosaicColorSamplingLayout | LayeredColorSamplingLayout;
+export interface SensorColorSamplingProfile {
+    schemaVersion: "0.1.0";
+    profileId: string;
+    /**
+     * Evidence supporting this exact topology declaration.
+     *
+     * Descriptive architecture-family metadata remains a separate contract.
+     */
+    evidence: readonly EvidenceProvenance[];
+    coordinateSystem: SensorColorSamplingProfileCoordinateSystem;
+    layout: SensorColorSamplingLayout;
+}
+export interface ResolveColorSamplingSiteInput {
+    profile: SensorColorSamplingProfile;
+    site: NativeColorSamplingSiteIndex;
+}
+export interface ResolvedColorSamplingSite {
+    profileId: string;
+    coordinateSystem: NativeColorSamplingSiteCoordinateSystem;
+    site: NativeColorSamplingSiteIndex;
+    mapping: {
+        kind: "monochrome";
+        channelId: string;
+    } | {
+        kind: "periodic-mosaic";
+        channelId: string;
+        repeatCoordinate: {
+            x: number;
+            y: number;
+        };
+        repeatWidthSites: number;
+        repeatHeightSites: number;
+    };
+    /**
+     * Explicit scientific boundaries for downstream consumers.
+     */
+    spectralResponseEstablished: false;
+    nativeImageRasterBindingEstablished: false;
+    physicalPhotodiodeBindingEstablished: false;
+}
+/**
+ * Parses an exact color-sampling topology declaration without binding it to
+ * NativeImageRaster, physical photodiodes, spectral response, or a
+ * manufacturer-specific family enum.
+ *
+ * Periodic mosaics use an abstract native sensor color-sampling-site lattice
+ * with zero-based integer indices, top-left origin, +X right and +Y down.
+ * The repeat phase is anchored to the sensor lattice, so later active crops or
+ * orientation transforms must preserve the original native site indices.
+ *
+ * Layered layouts are structural-only in this first contract because real
+ * layered sensors may use unequal spatial sampling density/registration across
+ * layers. No per-site layered resolver is exposed until that relationship is
+ * modeled explicitly.
+ */
+export declare function parseSensorColorSamplingProfile(value: unknown): SensorColorSamplingProfile;
+/**
+ * Resolves the semantic measurement-channel assignment at one abstract native
+ * sensor color-sampling-site index for monochrome or periodic-mosaic layouts.
+ *
+ * This API intentionally has no NativeImageRaster input. A later explicit
+ * binding must establish how a selected capture mode's effective raster maps
+ * to this color-sampling-site lattice before RAW/CFA sampling can be simulated.
+ *
+ * Layered layouts fail closed because their per-layer spatial relationship is
+ * not resolved by the first structural contract.
+ */
+export declare function resolveColorSamplingSite(input: ResolveColorSamplingSiteInput): ResolvedColorSamplingSite;
+//# sourceMappingURL=color-sampling.d.ts.map

package/dist/sensor/color-sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-sampling.d.ts","sourceRoot":"","sources":["../../src/sensor/color-sampling.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AAKxC,MAAM,MAAM,uCAAuC,GACjD,yCAAyC,CAAC;AAE5C,MAAM,MAAM,0CAA0C,GAClD,uCAAuC,GACvC,yDAAyD,CAAC;AAE9D,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;;OAIG;IACH,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,YAAY,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,iBAAiB,CAAC;IACxB;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,MAAM,EAAE,6BAA6B,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,2BAA2B,EAAE,cAAc,CAAC;CAC7C;AAED,MAAM,MAAM,yBAAyB,GACjC,6BAA6B,GAC7B,iCAAiC,GACjC,0BAA0B,CAAC;AAE/B,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,gBAAgB,EAAE,0CAA0C,CAAC;IAC7D,MAAM,EAAE,yBAAyB,CAAC;CACnC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,0BAA0B,CAAC;IACpC,IAAI,EAAE,4BAA4B,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,uCAAuC,CAAC;IAC1D,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EACH;QACE,IAAI,EAAE,YAAY,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,GACD;QACE,IAAI,EAAE,iBAAiB,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE;YAChB,CAAC,EAAE,MAAM,CAAC;YACV,CAAC,EAAE,MAAM,CAAC;SACX,CAAC;QACF,gBAAgB,EAAE,MAAM,CAAC;QACzB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IACN;;OAEG;IACH,2BAA2B,EAAE,KAAK,CAAC;IACnC,mCAAmC,EAAE,KAAK,CAAC;IAC3C,oCAAoC,EAAE,KAAK,CAAC;CAC7C;AA2ND;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,0BAA0B,CA4C5B;AAmBD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,yBAAyB,CAwF3B"}

package/dist/sensor/color-sampling.js

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+function requireRecord(value, path) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty string.");
+    }
+    return value;
+}
+function requirePositiveSafeInteger(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value <= 0) {
+        throw new InvalidConfigurationError(path + " must be a positive safe integer.");
+    }
+    return value;
+}
+function parseChannelIds(value, path, options) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty array.");
+    }
+    if (options.exactLength !== undefined &&
+        value.length !== options.exactLength) {
+        throw new InvalidConfigurationError(path +
+            " length must equal the declared repeating-tile site count.");
+    }
+    const ids = value.map((entry, index) => requireNonEmptyString(entry, path + "[" + index + "]"));
+    if (!options.allowDuplicates &&
+        new Set(ids).size !== ids.length) {
+        throw new InvalidConfigurationError(path + " must not contain duplicate channel IDs.");
+    }
+    return ids;
+}
+function parseLayout(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "monochrome") {
+        if (record.repeatWidthSites !== undefined ||
+            record.repeatHeightSites !== undefined ||
+            record.siteChannelIds !== undefined ||
+            record.anchor !== undefined ||
+            record.layerChannelIds !== undefined ||
+            record.spatialSamplingRelationship !== undefined) {
+            throw new InvalidConfigurationError(path +
+                " monochrome layout must omit mosaic/layered fields.");
+        }
+        return {
+            kind: "monochrome",
+            channelId: requireNonEmptyString(record.channelId, path + ".channelId")
+        };
+    }
+    if (record.kind === "periodic-mosaic") {
+        if (record.channelId !== undefined ||
+            record.layerChannelIds !== undefined ||
+            record.spatialSamplingRelationship !== undefined) {
+            throw new InvalidConfigurationError(path +
+                " periodic-mosaic layout must omit monochrome/layered fields.");
+        }
+        const repeatWidthSites = requirePositiveSafeInteger(record.repeatWidthSites, path + ".repeatWidthSites");
+        const repeatHeightSites = requirePositiveSafeInteger(record.repeatHeightSites, path + ".repeatHeightSites");
+        const repeatSiteCount = repeatWidthSites * repeatHeightSites;
+        if (!Number.isSafeInteger(repeatSiteCount)) {
+            throw new InvalidConfigurationError(path +
+                " repeating-tile site count must be a safe integer.");
+        }
+        if (record.anchor !== "native-sensor-top-left-site") {
+            throw new InvalidConfigurationError(path +
+                '.anchor must be "native-sensor-top-left-site".');
+        }
+        return {
+            kind: "periodic-mosaic",
+            repeatWidthSites,
+            repeatHeightSites,
+            siteChannelIds: parseChannelIds(record.siteChannelIds, path + ".siteChannelIds", {
+                allowDuplicates: true,
+                exactLength: repeatSiteCount
+            }),
+            anchor: "native-sensor-top-left-site"
+        };
+    }
+    if (record.kind === "layered") {
+        if (record.channelId !== undefined ||
+            record.repeatWidthSites !== undefined ||
+            record.repeatHeightSites !== undefined ||
+            record.siteChannelIds !== undefined ||
+            record.anchor !== undefined) {
+            throw new InvalidConfigurationError(path +
+                " layered layout must omit monochrome/mosaic fields.");
+        }
+        if (record.spatialSamplingRelationship !==
+            "not-resolved") {
+            throw new InvalidConfigurationError(path +
+                '.spatialSamplingRelationship must be "not-resolved" for the first layered contract.');
+        }
+        return {
+            kind: "layered",
+            layerChannelIds: parseChannelIds(record.layerChannelIds, path + ".layerChannelIds", {
+                allowDuplicates: false
+            }),
+            spatialSamplingRelationship: "not-resolved"
+        };
+    }
+    throw new InvalidConfigurationError(path + ".kind is invalid.");
+}
+/**
+ * Parses an exact color-sampling topology declaration without binding it to
+ * NativeImageRaster, physical photodiodes, spectral response, or a
+ * manufacturer-specific family enum.
+ *
+ * Periodic mosaics use an abstract native sensor color-sampling-site lattice
+ * with zero-based integer indices, top-left origin, +X right and +Y down.
+ * The repeat phase is anchored to the sensor lattice, so later active crops or
+ * orientation transforms must preserve the original native site indices.
+ *
+ * Layered layouts are structural-only in this first contract because real
+ * layered sensors may use unequal spatial sampling density/registration across
+ * layers. No per-site layered resolver is exposed until that relationship is
+ * modeled explicitly.
+ */
+export function parseSensorColorSamplingProfile(value) {
+    const profile = requireRecord(value, "sensorColorSampling");
+    if (profile.schemaVersion !== "0.1.0") {
+        throw new InvalidConfigurationError('sensorColorSampling.schemaVersion must be "0.1.0".');
+    }
+    const layout = parseLayout(profile.layout, "sensorColorSampling.layout");
+    const expectedCoordinateSystem = layout.kind === "layered"
+        ? "native-sensor-layered-spatial-relationship-not-resolved"
+        : "native-sensor-color-sampling-site-index";
+    if (profile.coordinateSystem !==
+        expectedCoordinateSystem) {
+        throw new InvalidConfigurationError("sensorColorSampling.coordinateSystem does not match the declared layout kind.");
+    }
+    return {
+        schemaVersion: "0.1.0",
+        profileId: requireNonEmptyString(profile.profileId, "sensorColorSampling.profileId"),
+        evidence: parseEvidenceList(profile.evidence, "sensorColorSampling.evidence"),
+        coordinateSystem: expectedCoordinateSystem,
+        layout
+    };
+}
+function requireNativeSiteIndex(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a non-negative safe integer native color-sampling-site index.");
+    }
+    return value;
+}
+/**
+ * Resolves the semantic measurement-channel assignment at one abstract native
+ * sensor color-sampling-site index for monochrome or periodic-mosaic layouts.
+ *
+ * This API intentionally has no NativeImageRaster input. A later explicit
+ * binding must establish how a selected capture mode's effective raster maps
+ * to this color-sampling-site lattice before RAW/CFA sampling can be simulated.
+ *
+ * Layered layouts fail closed because their per-layer spatial relationship is
+ * not resolved by the first structural contract.
+ */
+export function resolveColorSamplingSite(input) {
+    const profile = parseSensorColorSamplingProfile(input.profile);
+    if (typeof input.site !== "object" ||
+        input.site === null) {
+        throw new InvalidScientificInputError("site must be an object.");
+    }
+    const x = requireNativeSiteIndex(input.site.x, "site.x");
+    const y = requireNativeSiteIndex(input.site.y, "site.y");
+    if (profile.layout.kind === "layered") {
+        throw new InvalidScientificInputError("Layered color sampling is structural-only in schema 0.1.0; per-site resolution requires an explicit per-layer spatial sampling relationship.");
+    }
+    if (profile.coordinateSystem !==
+        "native-sensor-color-sampling-site-index") {
+        throw new InvalidScientificInputError("Resolvable color sampling requires the native sensor color-sampling-site coordinate system.");
+    }
+    if (profile.layout.kind === "monochrome") {
+        return {
+            profileId: profile.profileId,
+            coordinateSystem: profile.coordinateSystem,
+            site: { x, y },
+            mapping: {
+                kind: "monochrome",
+                channelId: profile.layout.channelId
+            },
+            spectralResponseEstablished: false,
+            nativeImageRasterBindingEstablished: false,
+            physicalPhotodiodeBindingEstablished: false
+        };
+    }
+    const repeatX = x % profile.layout.repeatWidthSites;
+    const repeatY = y % profile.layout.repeatHeightSites;
+    const index = repeatY * profile.layout.repeatWidthSites +
+        repeatX;
+    const channelId = profile.layout.siteChannelIds[index];
+    if (channelId === undefined) {
+        throw new InvalidScientificInputError("Periodic color-sampling tile resolution failed.");
+    }
+    return {
+        profileId: profile.profileId,
+        coordinateSystem: profile.coordinateSystem,
+        site: { x, y },
+        mapping: {
+            kind: "periodic-mosaic",
+            channelId,
+            repeatCoordinate: {
+                x: repeatX,
+                y: repeatY
+            },
+            repeatWidthSites: profile.layout.repeatWidthSites,
+            repeatHeightSites: profile.layout.repeatHeightSites
+        },
+        spectralResponseEstablished: false,
+        nativeImageRasterBindingEstablished: false,
+        physicalPhotodiodeBindingEstablished: false
+    };
+}
+//# sourceMappingURL=color-sampling.js.map

package/dist/sensor/color-sampling.js.map

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

package/dist/sensor/exposure-window.d.ts

@@ -0,0 +1,103 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type EvidenceBackedFact } from "../core/evidence-provenance.js";
+import type { RasterPoint, RasterRect, RasterVector } from "../output/capture-geometry.js";
+import type { NativeImageRaster } from "./sensor-geometry.js";
+import type { CaptureShutterMechanism, NativeSensorReadoutScanDirection, SourcedSensorTimingSeconds } from "./readout-timing.js";
+export type CaptureExposureBoundaryActuator = "mechanical" | "electronic";
+export type SourcedCaptureTimingSeconds = SourcedSensorTimingSeconds;
+export type SourcedCaptureBoundaryDirection = EvidenceBackedFact<NativeSensorReadoutScanDirection>;
+export interface SimultaneousExposureBoundarySchedule {
+    kind: "simultaneous";
+    directionNative?: never;
+    traversalDurationSeconds?: never;
+}
+export interface UniformLinearExposureBoundarySchedule {
+    kind: "uniform-linear-native-scan";
+    directionNative: SourcedCaptureBoundaryDirection;
+    traversalDurationSeconds: SourcedCaptureTimingSeconds;
+}
+export type ExposureBoundarySchedule = SimultaneousExposureBoundarySchedule | UniformLinearExposureBoundarySchedule;
+export interface CalculateCaptureExposureWindowsInput {
+    nativeRaster: NativeImageRaster;
+    /**
+     * Active capture rectangle in invariant native-raster coordinates.
+     *
+     * Defaults to the complete native raster. Boundary traversal timing is never
+     * inferred by scaling a full-frame timing value to this rectangle.
+     */
+    activeCaptureRect?: RasterRect;
+    shutterMechanism: CaptureShutterMechanism;
+    /**
+     * Nominal interval between the zero-phase opening and closing references.
+     *
+     * Local exposure duration may differ from this value when opening and closing
+     * boundary schedules have different spatial phase behavior.
+     */
+    nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+    opening: ExposureBoundarySchedule;
+    closing: ExposureBoundarySchedule;
+    /**
+     * Optional continuous native raster edge-coordinate points for diagnostics.
+     * Pixel centers may be represented with +0.5 offsets.
+     */
+    samplePointsNative?: readonly RasterPoint[];
+}
+export interface ResolvedCaptureExposureBoundary {
+    actuator: CaptureExposureBoundaryActuator;
+    schedule: {
+        kind: "simultaneous";
+    } | {
+        kind: "uniform-linear-native-scan";
+        directionNative: SourcedCaptureBoundaryDirection;
+        unitVectorNative: RasterVector;
+        traversalDurationSeconds: SourcedCaptureTimingSeconds;
+    };
+}
+export interface CaptureExposureWindowSample {
+    pointNative: RasterPoint;
+    openingNormalizedScanPosition: number | null;
+    closingNormalizedScanPosition: number | null;
+    /**
+     * Seconds from the first opening-boundary phase.
+     */
+    startOffsetSecondsFromOpeningReference: number;
+    /**
+     * Seconds from the first opening-boundary phase.
+     */
+    endOffsetSecondsFromOpeningReference: number;
+    localExposureDurationSeconds: number;
+}
+export interface CaptureExposureWindows {
+    shutterMechanism: CaptureShutterMechanism;
+    timeReference: "first-opening-boundary-phase";
+    nativeRaster: NativeImageRaster;
+    activeCaptureRect: RasterRect;
+    nominalExposureDurationSeconds: SourcedCaptureTimingSeconds;
+    opening: ResolvedCaptureExposureBoundary;
+    closing: ResolvedCaptureExposureBoundary;
+    localExposureDurationRangeSeconds: {
+        minimum: number;
+        maximum: number;
+    };
+    samples: readonly CaptureExposureWindowSample[];
+}
+/**
+ * Resolves local capture exposure windows from independent opening and closing
+ * boundary schedules.
+ *
+ * The returned time basis is seconds from the first opening-boundary phase.
+ * This is intentionally not the existing camera-rotation API's global
+ * "exposure start" semantic; a later integration layer must bind those time
+ * bases explicitly.
+ *
+ * The mechanism identifies whether each boundary is mechanical or electronic,
+ * but does not supply any traversal duration or direction. Every non-simultaneous
+ * timing value and direction is caller-declared with evidence.
+ *
+ * The first model supports simultaneous boundaries and uniform-linear
+ * single-axis native-sensor scans only. It does not model curtain acceleration,
+ * segmented/nonlinear electronic schedules, flash/flicker, rolling-shutter
+ * image distortion, shutter shock, or EFCS-specific pupil/bokeh behavior.
+ */
+export declare function calculateCaptureExposureWindows(input: CalculateCaptureExposureWindowsInput): CalculationResult<CaptureExposureWindows>;
+//# sourceMappingURL=exposure-window.d.ts.map

package/dist/sensor/exposure-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure-window.d.ts","sourceRoot":"","sources":["../../src/sensor/exposure-window.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AAKxC,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EACV,uBAAuB,EACvB,gCAAgC,EAChC,0BAA0B,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,+BAA+B,GAAG,YAAY,GAAG,YAAY,CAAC;AAE1E,MAAM,MAAM,2BAA2B,GAAG,0BAA0B,CAAC;AAErE,MAAM,MAAM,+BAA+B,GACzC,kBAAkB,CAAC,gCAAgC,CAAC,CAAC;AAEvD,MAAM,WAAW,oCAAoC;IACnD,IAAI,EAAE,cAAc,CAAC;IACrB,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB,wBAAwB,CAAC,EAAE,KAAK,CAAC;CAClC;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,4BAA4B,CAAC;IACnC,eAAe,EAAE,+BAA+B,CAAC;IACjD,wBAAwB,EAAE,2BAA2B,CAAC;CACvD;AAED,MAAM,MAAM,wBAAwB,GAChC,oCAAoC,GACpC,qCAAqC,CAAC;AAE1C,MAAM,WAAW,oCAAoC;IACnD,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C;;;;;OAKG;IACH,8BAA8B,EAAE,2BAA2B,CAAC;IAC5D,OAAO,EAAE,wBAAwB,CAAC;IAClC,OAAO,EAAE,wBAAwB,CAAC;IAClC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,EAAE,+BAA+B,CAAC;IAC1C,QAAQ,EACJ;QACE,IAAI,EAAE,cAAc,CAAC;KACtB,GACD;QACE,IAAI,EAAE,4BAA4B,CAAC;QACnC,eAAe,EAAE,+BAA+B,CAAC;QACjD,gBAAgB,EAAE,YAAY,CAAC;QAC/B,wBAAwB,EAAE,2BAA2B,CAAC;KACvD,CAAC;CACP;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,WAAW,CAAC;IACzB,6BAA6B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,6BAA6B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C;;OAEG;IACH,sCAAsC,EAAE,MAAM,CAAC;IAC/C;;OAEG;IACH,oCAAoC,EAAE,MAAM,CAAC;IAC7C,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,aAAa,EAAE,8BAA8B,CAAC;IAC9C,YAAY,EAAE,iBAAiB,CAAC;IAChC,iBAAiB,EAAE,UAAU,CAAC;IAC9B,8BAA8B,EAAE,2BAA2B,CAAC;IAC5D,OAAO,EAAE,+BAA+B,CAAC;IACzC,OAAO,EAAE,+BAA+B,CAAC;IACzC,iCAAiC,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;CACjD;AAoVD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,oCAAoC,GAC1C,iBAAiB,CAAC,sBAAsB,CAAC,CAkG3C"}