scax-engine 0.1.0

package/dist/types/scax-engine.d.ts

@@ -0,0 +1,441 @@
+import Affine from "./affine/affine";
+import { GridLightSourceProps, GridRGLightSourceProps, LightSource, RadialLightSourceProps } from "./light-sources/light-source";
+import Ray from "./ray/ray";
+import Surface from "./surfaces/surface";
+export type EyeModel = "gullstrand" | "navarro";
+export type PupilType = "constricted" | "neutral" | "dilated" | "none";
+export type LightSourceTransform = {
+    position?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    tilt?: {
+        x?: number;
+        y?: number;
+    };
+};
+export type LightSourceConfig = ({
+    type: "radial";
+} & RadialLightSourceProps & LightSourceTransform) | ({
+    type: "grid";
+} & GridLightSourceProps & LightSourceTransform) | ({
+    type: "grid_rg";
+} & GridRGLightSourceProps & LightSourceTransform);
+export type LensConfig = {
+    s: number;
+    c: number;
+    ax: number;
+    p?: number;
+    p_ax?: number;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    tilt: {
+        x: number;
+        y: number;
+    };
+};
+export type EyeConfig = {
+    s: number;
+    c: number;
+    ax: number;
+    p?: number;
+    p_ax?: number;
+    tilt?: {
+        x?: number;
+        y?: number;
+    };
+};
+export type EyePowerInput = EyeConfig;
+export type SCAXEngineProps = {
+    eyeModel?: EyeModel;
+    eye?: EyeConfig;
+    lens?: LensConfig[];
+    light_source?: LightSourceConfig;
+    pupil_type?: PupilType;
+};
+export type SCAxPower = {
+    s: number;
+    c: number;
+    ax: number;
+};
+export type SimulateResult = {
+    traced_rays: Ray[];
+    info: SimulationResultInfo;
+};
+export type PrismVector = {
+    x: number;
+    y: number;
+    magnitude: number;
+    angle_deg: number;
+};
+export type EyeRotationForRender = {
+    x_deg: number;
+    y_deg: number;
+    magnitude_deg: number;
+};
+export type LightDeviation = {
+    eye_prism_effect: PrismVector;
+    lens_prism_total: PrismVector;
+    net_prism: PrismVector;
+    x_angle_deg: number;
+    y_angle_deg: number;
+    net_angle_deg: number;
+};
+export type AstigmatismSummaryItem = {
+    tabo: number;
+    d: number;
+}[];
+export type PrismSummaryItem = {
+    p_x: number;
+    p_y: number;
+    prism_angle: number;
+    magnitude: number | null;
+};
+export type SimulationResultInfo = {
+    astigmatism: {
+        eye: AstigmatismSummaryItem[];
+        lens: AstigmatismSummaryItem[];
+        combined: AstigmatismSummaryItem[];
+    };
+    prism: {
+        eye: PrismSummaryItem;
+        lens: PrismSummaryItem;
+        combined: PrismSummaryItem;
+    };
+};
+export type AffineAnalysisResult = ReturnType<Affine["estimate"]>;
+/**
+ * legacy simulator.js를 TypeScript로 옮긴 핵심 시뮬레이터입니다.
+ * - 광원 광선을 생성하고
+ * - 표면들을 순서대로 통과시키며 굴절을 계산한 뒤
+ * - 망막 대응쌍, Sturm 분석, 왜곡(affine) 분석까지 제공합니다.
+ */
+export declare class SCAXEngineCore {
+    private static readonly EYE_ROTATION_PIVOT_FROM_CORNEA_MM;
+    private eyeModel;
+    private surfaces;
+    private lens;
+    private light_source;
+    private eyeModelParameter;
+    private tracedRays;
+    private lastSourceRaysForSturm;
+    private sturm;
+    private affine;
+    private lastSturmGapAnalysis;
+    private lastAffineAnalysis;
+    private pupilDiameterMm;
+    private hasPupilStop;
+    private eyePower;
+    private lensConfigs;
+    private lensPowers;
+    private eyePrismEffectVector;
+    private lensPrismVector;
+    private eyePrismPrescription;
+    private eyeRotationQuaternion;
+    private eyeRotationQuaternionInverse;
+    private eyeRotationPivot;
+    private eyeTiltDeg;
+    private lightSourcePosition;
+    private lightSourceTiltDeg;
+    private lightSourceRotationQuaternion;
+    private lightSourceRotationPivot;
+    private sortedLensSurfaces;
+    private sortedEyeSurfaces;
+    private currentProps;
+    constructor(props?: SCAXEngineProps);
+    /**
+     * 생성자와 동일한 기본값 규칙으로 광학 설정을 다시 적용합니다.
+     * 생략한 최상위 필드는 매번 기본값으로 돌아갑니다(이전 값과 병합하지 않음).
+     */
+    update(props?: SCAXEngineProps): void;
+    dispose(): void;
+    private configure;
+    /**
+     * 기본 시뮬레이션 진입점입니다.
+     * includeSturmData 값과 무관하게 확장 분석(Sturm/retinaPairs)을 항상 포함합니다.
+     */
+    simulate(): SimulateResult;
+    /**
+     * eye.p / eye.p_ax(처방값)를 기준으로, 렌더링에서 바로 쓸 눈 회전량을 반환합니다.
+     * - x_deg/y_deg는 프리즘 회전량에 eye.tilt를 합산한 최종 렌더 회전량입니다.
+     */
+    getEyeRotation(): EyeRotationForRender;
+    /**
+     * 1) Ray tracing 전용 함수
+     * 광원에서 시작한 광선을 표면 순서대로 굴절시켜 최종 광선 집합을 반환합니다.
+     */
+    rayTracing(): Ray[];
+    /**
+     * 2) Sturm calculation 전용 함수
+     * traced ray 집합에서 z-scan 기반 Sturm 슬라이스/근사 중심을 계산합니다.
+     */
+    sturmCalculation(rays?: Ray[]): {
+        slices_info: {
+            count: number;
+            slices: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            }[];
+        };
+        sturm_info: {
+            has_astigmatism: boolean;
+            method: string;
+            anterior: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            };
+            posterior: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            } | null;
+            approx_center: {
+                x: number;
+                y: number;
+                z: number;
+                mode: string;
+            } | null;
+            line: "g" | "F" | "e" | "d" | "C" | "r";
+            wavelength_nm: number;
+            color: number | null;
+            ray_count: number;
+            analysis_axis: {
+                x: number;
+                y: number;
+                z: number;
+            };
+        }[];
+    };
+    /**
+     * 3) Affine 왜곡 추정 전용 함수
+     * 광선 대응쌍(sx,sy)->(tx,ty)에 대해 최소자승 2D affine을 적합합니다.
+     */
+    private estimateAffineDistortion;
+    /**
+     * 현재 eye+lens 설정 기준 affine 왜곡 결과를 반환합니다.
+     * traced ray/affine 결과는 기존 계산값을 우선 재사용합니다.
+     */
+    getAffineAnalysis(): AffineAnalysisResult;
+    private surfaceOrderZ;
+    private readSurfacePosition;
+    private getRayPoints;
+    private isRayInsidePupil;
+    private powerVectorFromCylinder;
+    private aggregatePowerVector;
+    private principalMeridiansFromVector;
+    private principalMeridiansFromPowers;
+    private normalizePrismAmount;
+    private normalizeAngle360;
+    private normalizeEyeTilt;
+    private normalizeLightSourcePose;
+    private toFiniteNumber;
+    private refreshSortedSurfaces;
+    private prismVectorFromBase;
+    private vectorToPrismInfo;
+    private toPrismSummaryItem;
+    private prismComponentToAngleDeg;
+    private prismMagnitudeToAngleDeg;
+    private applyPrismVectorToRay;
+    private rotatePointAroundPivot;
+    private translateRay;
+    private transformRayAroundPivot;
+    private applyLightSourceTransformToRay;
+    private calculateLightDeviation;
+    private effectiveCylinderFromOpticSurfaces;
+    private createAffinePairs;
+}
+/**
+ * 외부 공개 API 전용 Facade입니다.
+ * 내부 광학 상태/연산은 SCAXEngineCore에 위임합니다.
+ */
+export default class SCAXEngine {
+    private readonly core;
+    constructor(props?: SCAXEngineProps);
+    get lens(): Surface[];
+    get light_source(): LightSource;
+    get surfaces(): Surface[];
+    update(props?: SCAXEngineProps): void;
+    dispose(): void;
+    simulate(): SimulateResult;
+    getEyeRotation(): EyeRotationForRender;
+    rayTracing(): Ray[];
+    sturmCalculation(rays?: Ray[]): {
+        slices_info: {
+            count: number;
+            slices: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            }[];
+        };
+        sturm_info: {
+            has_astigmatism: boolean;
+            method: string;
+            anterior: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            };
+            posterior: {
+                z: number;
+                depth: number;
+                ratio: number;
+                size: number;
+                profile: {
+                    at: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    wMajor: number;
+                    wMinor: number;
+                    angleMajorDeg: number;
+                    angleMinorDeg: number;
+                    majorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                    minorDirection: {
+                        x: number;
+                        y: number;
+                        z: number;
+                    };
+                };
+            } | null;
+            approx_center: {
+                x: number;
+                y: number;
+                z: number;
+                mode: string;
+            } | null;
+            line: "g" | "F" | "e" | "d" | "C" | "r";
+            wavelength_nm: number;
+            color: number | null;
+            ray_count: number;
+            analysis_axis: {
+                x: number;
+                y: number;
+                z: number;
+            };
+        }[];
+    };
+    getAffineAnalysis(): AffineAnalysisResult;
+}
+//# sourceMappingURL=scax-engine.d.ts.map

package/dist/types/sturm/sturm.d.ts

@@ -0,0 +1,81 @@
+import Ray from "../ray/ray";
+type FraunhoferLine = "g" | "F" | "e" | "d" | "C" | "r";
+type SturmSlice = {
+    z: number;
+    depth: number;
+    ratio: number;
+    size: number;
+    profile: {
+        at: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        wMajor: number;
+        wMinor: number;
+        angleMajorDeg: number;
+        angleMinorDeg: number;
+        majorDirection: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        minorDirection: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+};
+/**
+ * Sturm 계산 전용 클래스입니다.
+ * - traced ray 집합에서 z-scan slice를 생성하고
+ * - 평탄도/최소타원/근사중심을 계산해 분석 결과를 반환합니다.
+ */
+export default class Sturm {
+    private lastResult;
+    calculate(rays: Ray[], effectiveCylinderD: number, axisReferenceRays?: Ray[]): {
+        slices_info: {
+            count: number;
+            slices: SturmSlice[];
+        };
+        sturm_info: {
+            has_astigmatism: boolean;
+            method: string;
+            anterior: SturmSlice;
+            posterior: SturmSlice | null;
+            approx_center: {
+                x: number;
+                y: number;
+                z: number;
+                mode: string;
+            } | null;
+            line: FraunhoferLine;
+            wavelength_nm: number;
+            color: number | null;
+            ray_count: number;
+            analysis_axis: {
+                x: number;
+                y: number;
+                z: number;
+            };
+        }[];
+    };
+    /**
+     * 마지막 Sturm 계산 결과를 반환합니다.
+     */
+    getLastResult(): unknown;
+    private getRayPoints;
+    private readonly lineOrder;
+    private analysisFrameFromRays;
+    private sampleRayPointAtDepth;
+    private depthRangeFromRays;
+    private secondMomentProfileAtDepth;
+    private collectSturmSlices;
+    private axisDiffDeg;
+    private buildApproxCenter;
+    private groupByFraunhoferLine;
+    private analyzeSturmSlices;
+}
+export {};
+//# sourceMappingURL=sturm.d.ts.map

package/dist/types/surfaces/aperture-stop-surface.d.ts

@@ -0,0 +1,35 @@
+import { Vector3 } from "three";
+import Ray from "../ray/ray";
+import Surface from "./surface";
+export type ApertureStopSurfaceProps = {
+    type: "aperture_stop";
+    shape: "circle" | "rectangle";
+    radius?: number;
+    width?: number;
+    height?: number;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    tilt: {
+        x: number;
+        y: number;
+    };
+};
+export default class ApertureStopSurface extends Surface {
+    private shape;
+    private radius;
+    private width;
+    private height;
+    constructor(props: ApertureStopSurfaceProps);
+    private worldQuaternion;
+    private localPointFromWorld;
+    private surfaceNormalWorld;
+    private intersectForward;
+    private isInsideAperture;
+    incident(ray: Ray): Vector3 | null;
+    refract(ray: Ray): Ray | null;
+}
+//# sourceMappingURL=aperture-stop-surface.d.ts.map

package/dist/types/surfaces/aspherical-surface.d.ts

@@ -0,0 +1,70 @@
+import { Vector3 } from "three";
+import { RefractiveIndexSpec } from "../optics/refractive-index";
+import Ray from "../ray/ray";
+import Surface from "./surface";
+export type AsphericalSurfaceProps = {
+    type: "aspherical";
+    name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    tilt: {
+        x: number;
+        y: number;
+    };
+    r: number;
+    conic: number;
+    n_before: RefractiveIndexSpec;
+    n_after: RefractiveIndexSpec;
+};
+export default class AsphericalSurface extends Surface {
+    /**
+     * 수치 계산 상수들
+     * - MIN_T: 현재 시작점과의 자기 재교차를 피하기 위한 최소 진행 거리
+     * - MAX_ITERS: 뉴턴법 반복 횟수
+     * - BISECTION_ITERS: 이분법 반복 횟수
+     */
+    private static readonly MIN_T;
+    private static readonly MAX_ITERS;
+    private static readonly BISECTION_ITERS;
+    private static readonly BRACKET_SCAN_STEPS;
+    private static readonly MAX_BRACKET_T_MM;
+    private r;
+    private conic;
+    private n_before;
+    private n_after;
+    constructor(props: AsphericalSurfaceProps);
+    private refractiveIndicesForRay;
+    /**
+     * 비구면 사그(sag)와 그 기울기(미분)를 계산합니다.
+     *
+     * 회전대칭 비구면 식:
+     * z = c*rho^2 / (1 + sqrt(1 - (1+k)*c^2*rho^2))
+     * - c = 1 / R (곡률)
+     * - k = conic constant
+     * - rho^2 = x^2 + y^2
+     *
+     * 반환값:
+     * - sag: 꼭지점 기준 z 변위(mm)
+     * - dzdx, dzdy: 표면 기울기 (법선 계산과 뉴턴법 미분에 사용)
+     */
+    private geometryAtXY;
+    /**
+     * 광선 파라미터 t에서의 표면 방정식 값 f(t)를 계산합니다.
+     * f(t)=0 이면 교점입니다.
+     */
+    private surfaceEquationAtT;
+    /**
+     * 뉴턴법이 실패했을 때를 대비해, 일정 구간에서 부호가 바뀌는 브래킷을 찾습니다.
+     */
+    private scanBracketRange;
+    /**
+     * 브래킷 [a,b] 내부에서 이분법으로 f(t)=0의 근을 찾습니다.
+     */
+    private bisectionRoot;
+    incident(ray: Ray): Vector3 | null;
+    refract(ray: Ray): Ray | null;
+}
+//# sourceMappingURL=aspherical-surface.d.ts.map

package/dist/types/surfaces/paraxial-surface.d.ts

@@ -0,0 +1,61 @@
+import { Vector3 } from "three";
+import Ray from "../ray/ray";
+import Surface from "./surface";
+export type ParaxialSurfaceProps = {
+    type: "paraxial";
+    name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    tilt: {
+        x: number;
+        y: number;
+    };
+    s: number;
+    c: number;
+    ax: number;
+    n: number;
+};
+export default class ParaxialSurface extends Surface {
+    private s;
+    private c;
+    private ax;
+    private n;
+    constructor(props: ParaxialSurfaceProps);
+    /**
+     * 이 surface는 입력된 d선 기준 굴절률(n)만 사용한다.
+     * 파장(프라운호퍼 선) 변화에 따른 굴절률 업데이트는 클래스 외부에서 처리한다.
+     */
+    private lensN;
+    /**
+     * 난시 축(ax)과 구면/난시 도수(s, c)를 2x2 파워 행렬 형태로 만든다.
+     */
+    private basePowerMatrix;
+    /**
+     * 사입사(광선이 비스듬히 들어오는 경우)에서 생기는 유도 구면/난시를
+     * slope 기반 근사식으로 기본 파워 행렬에 반영한다.
+     */
+    private powerMatrixWithOblique;
+    /**
+     * surface 평면(법선은 로컬 +Z)을 따라 광선이 "앞으로" 만나는 교점을 찾는다.
+     */
+    private intersectForward;
+    private centerWorld;
+    /**
+     * 표면 회전은 tilt(x,y)만 반영한다.
+     * 주의: 축(ax)은 basePowerMatrix에서 이미 반영하므로 z회전을 여기서 더하지 않는다.
+     */
+    private worldQuaternion;
+    private worldToLocalPoint;
+    private worldDirToLocal;
+    private localDirToWorld;
+    incident(ray: Ray): Vector3 | null;
+    /**
+     * 박막(paraxial thin lens) 근사를 사용해 굴절 후 광선을 생성한다.
+     * 1) 입사점 계산 -> 2) 로컬 좌표에서 slope 갱신 -> 3) 월드 좌표로 되돌림
+     */
+    refract(ray: Ray): Ray | null;
+}
+//# sourceMappingURL=paraxial-surface.d.ts.map