scax-engine 0.1.7 → 0.2.0-beta.1

package/dist/types/index.d.ts

@@ -1,8 +1,4 @@
-export { default as SCAXEngine } from "./scax-engine";
-export { SCAXEngineCore } from "./scax-engine";
-export type { SturmProfileWorldZBounds } from "./sturm/sturm";
 export { default as Ray } from "./ray/ray";
-export type { RayProps } from "./ray/ray";
-export type { AffinePair } from "./affine/affine";
-export type { EyeModel, PupilType, LightSourceConfig, LensConfig, EyeConfig, EyePowerInput, SCAXEngineProps, SCAxPower, AstigmatismSummaryItem, PrismSummaryItem, SimulationResultInfo, SimulateResult, AffineAnalysisResult, } from "./scax-engine";
+export { default as SCAXEngine, SCAXEngineCore } from "./scax-engine";
+export type { MeridianInfo, PrismPower, SCAXEngineProps, SCAXPower, SimulateResult, } from "./scax-engine";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/light-sources/light-source.d.ts

@@ -6,13 +6,34 @@ export declare const CHROMATIC_RED_COLOR = 16281969;
 /** 프라우호퍼 e선 (초록) */
 export declare const CHROMATIC_GREEN_NM = 546.07;
 export declare const CHROMATIC_GREEN_COLOR = 4906624;
+export type LightSourcePose = {
+    position?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    tilt?: {
+        x?: number;
+        y?: number;
+    };
+};
 export declare class LightSource {
     protected rays: Ray[];
+    private sourcePosition;
+    private sourceRotationQuaternion;
+    private sourceRotationPivot;
     constructor();
     protected directionFromVergence(origin: Vector3, z: number, vergence: number): Vector3;
     protected createRayFromPoint(origin: Vector3, z: number, vergence: number): void;
     protected createChromaticRayFromPoint(origin: Vector3, z: number, vergence: number, line: "e" | "C", chromaticVergenceOffset?: number): void;
     addRay(ray: Ray): void;
+    protected configurePose(pose: LightSourcePose | undefined, pivotZ?: number): void;
+    private toFiniteNumber;
+    private getRayPoints;
+    private rotatePointAroundPivot;
+    private transformRayAroundPivot;
+    private translateRay;
+    private applyPoseToRay;
     emitRays(): Ray[];
 }
 export type GridLightSourceProps = {
@@ -21,7 +42,7 @@ export type GridLightSourceProps = {
     division: number;
     z: number;
     vergence: number;
-};
+} & LightSourcePose;
 export declare class GridLightSource extends LightSource {
     private width;
     private height;
@@ -45,7 +66,7 @@ export type RadialLightSourceProps = {
     angle_division: number;
     z: number;
     vergence: number;
-};
+} & LightSourcePose;
 export declare class RadialLightSource extends LightSource {
     private radius;
     private division;

package/dist/types/optics/prism-on-ray.d.ts

@@ -0,0 +1,19 @@
+import Ray from "../ray/ray";
+export declare function normalizePrismDiopters(value: unknown): number;
+export declare function normalizeAngle360Degrees(value: unknown): number;
+/**
+ * 임상 프리즘 Base(Δ, 렌즈→각막 시점 °)를 내부 x/y 프리즘 벡터(Δ)로 변환합니다.
+ * `SCAXEngineCore`와 동일한 관례입니다.
+ */
+export declare function prismVectorFromClinicalBase(prismDiopter: unknown, baseAngleDeg: unknown): {
+    x: number;
+    y: number;
+};
+/**
+ * 굴절 직후 광선에 프리즘 편향(소각 근사)을 적용합니다.
+ */
+export declare function applyPrismVectorToRay(ray: Ray, prism: {
+    x: number;
+    y: number;
+}): Ray;
+//# sourceMappingURL=prism-on-ray.d.ts.map

package/dist/types/parameters/eye/eye-rigid-pose.d.ts

@@ -0,0 +1,32 @@
+import { Quaternion, Vector3 } from "three";
+import Surface from "../../surfaces/surface";
+/** 각막 기준 안구 회전점 z(mm). `SCAXEngineCore`와 동일. */
+export declare const EYE_ROTATION_PIVOT_FROM_CORNEA_MM = 13;
+/** eye 처방(Base) → 실제 안구 편향에 쓰는 역벡터(내부 x/y, Δ). */
+export declare function eyePrismEffectVectorFromPrescription(p: unknown, p_ax: unknown): {
+    x: number;
+    y: number;
+};
+/**
+ * eye.p / eye.p_ax(임상 Base) 및 eye.tilt(°)로부터
+ * 안구 강체 회전 쿼터니언(Euler XYZ, z=0). 기존 configure 광선 피벗 회전과 동일.
+ */
+export declare function eyePrismAndTiltToQuaternion(p: unknown, p_ax: unknown, tiltDeg: {
+    x: number;
+    y: number;
+}): Quaternion;
+export declare function eyeRotationPivot(): Vector3;
+/** eye prism/tilt를 반영한 렌더용 각도(°). */
+export declare function eyeRotationForRenderDegrees(p: unknown, p_ax: unknown, tiltDeg: {
+    x: number;
+    y: number;
+}): {
+    x_deg: number;
+    y_deg: number;
+    magnitude_deg: number;
+};
+/**
+ * 안구 회전점 기준 강체 회전을 각 표면의 world `position` / `tilt`에 반영합니다.
+ */
+export declare function applyRigidEyePoseToSurfaces(surfaces: Surface[], pivot: Vector3, rotation: Quaternion): void;
+//# sourceMappingURL=eye-rigid-pose.d.ts.map

package/dist/types/parameters/eye/eyemodel-parameter.d.ts

@@ -28,10 +28,33 @@ export interface EyeModelParameterConfig {
     origin?: string;
     surfaces: EyeSurfaceParameter[];
 }
+/**
+ * `SCAXEngineCore.configure`와 동일한 눈 처방 필드.
+ * - `s,c,ax`: auto refractor(굴절오차) 기준; ST 면에는 보정렌즈 관점으로 변환되어 들어갑니다.
+ * - `p,p_ax,tilt`: 안구 회전점 기준 강체 pose로 각 표면 `position`/`tilt`에 전개됩니다.
+ */
+export type EyeStackCreateInput = {
+    eyeModel: "gullstrand" | "navarro";
+    s: number;
+    c: number;
+    ax: number;
+    p?: number;
+    p_ax?: number;
+    tilt?: {
+        x?: number;
+        y?: number;
+    };
+    /** 0이면 동공 aperture 면을 넣지 않습니다. */
+    pupilDiameterMm: number;
+};
 export declare class EyeModelParameter {
     private readonly parameter;
     constructor(parameter: EyeModelParameterConfig);
-    createSurface(): Surface[];
+    /**
+     * 동공(선택) → eye_st(ST 복합면) → 안구 모델 해부면 순으로 생성한 뒤,
+     * `p`/`p_ax`/`tilt`를 안구 회전점 기준 강체 회전으로 반영합니다.
+     */
+    createSurface(eye: EyeStackCreateInput): Surface[];
 }
 export {};
 //# sourceMappingURL=eyemodel-parameter.d.ts.map

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

@@ -1,19 +1,27 @@
 import Affine from "./affine/affine";
 import { GridLightSourceProps, GridRGLightSourceProps, LightSource, RadialLightSourceProps } from "./light-sources/light-source";
+import { EyeModelParameter } from "./parameters/eye/eyemodel-parameter";
 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;
-    };
+type Position3D = {
+    x: number;
+    y: number;
+    z: number;
+};
+type Rotation2D = {
+    x: number;
+    y: number;
+};
+type PartialPosition3D = {
+    x?: number;
+    y?: number;
+    z?: number;
+};
+type PartialRotation2D = {
+    x?: number;
+    y?: number;
 };
 export type LightSourceConfig = ({
     type: "radial";
@@ -22,27 +30,26 @@ export type LightSourceConfig = ({
 } & GridLightSourceProps & LightSourceTransform) | ({
     type: "grid_rg";
 } & GridRGLightSourceProps & LightSourceTransform);
+export type LightSourceTransform = {
+    position?: PartialPosition3D;
+    tilt?: PartialRotation2D;
+};
+type NormalizedLightSourceConfig = LightSourceConfig & {
+    position: Position3D;
+    tilt: Rotation2D;
+};
 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;
-    };
-    /**
-     * false이면 `simulate().info.astigmatism`의 `lens`·`combined` 파워 벡터 합에서 이 항목을 빼고,
-     * 광선 추적·프리즘·Sturm 등은 그대로 적용합니다. (예: 시험용 JCC/크로스실린더)
-     * @default true
-     */
-    includeInAstigmatismSummary?: boolean;
+    position: Position3D;
+    tilt: Rotation2D;
+};
+type NormalizedLensConfig = LensConfig & {
+    p: number;
+    p_ax: number;
 };
 export type EyeConfig = {
     s: number;
@@ -50,12 +57,13 @@ export type EyeConfig = {
     ax: number;
     p?: number;
     p_ax?: number;
-    tilt?: {
-        x?: number;
-        y?: number;
-    };
+    tilt?: PartialRotation2D;
+};
+type NormalizedEyeConfig = EyeConfig & {
+    p: number;
+    p_ax: number;
+    tilt: Rotation2D;
 };
-export type EyePowerInput = EyeConfig;
 export type SCAXEngineProps = {
     eyeModel?: EyeModel;
     eye?: EyeConfig;
@@ -63,56 +71,30 @@ export type SCAXEngineProps = {
     light_source?: LightSourceConfig;
     pupil_type?: PupilType;
 };
-export type SCAxPower = {
-    s: number;
-    c: number;
-    ax: number;
+type NormalizedEngineConfig = {
+    eyeModel: EyeModel;
+    eye: NormalizedEyeConfig;
+    lens: NormalizedLensConfig[];
+    light_source: NormalizedLightSourceConfig;
+    pupil_type: PupilType;
 };
+export declare function normalizeEngineProps(props?: SCAXEngineProps): NormalizedEngineConfig;
 export type SimulateResult = {
     traced_rays: Ray[];
-    info: SimulationResultInfo;
 };
-export type PrismVector = {
-    x: number;
-    y: number;
-    magnitude: number;
-    angle_deg: number;
+export type PrismPower = {
+    p: number;
+    p_ax: 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 SCAXPower = {
+    s: number;
+    c: number;
+    ax: number;
 };
-export type AstigmatismSummaryItem = {
+export type MeridianInfo = {
     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로 옮긴 핵심 시뮬레이터입니다.
@@ -121,43 +103,25 @@ export type AffineAnalysisResult = ReturnType<Affine["estimate"]>;
  * - Sturm 분석까지 제공합니다.
  */
 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 _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);
+    get eyeModelParameter(): EyeModelParameter;
+    constructor(config?: SCAXEngineProps | NormalizedEngineConfig);
     /**
      * 생성자와 동일한 기본값 규칙으로 광학 설정을 다시 적용합니다.
      * 생략한 최상위 필드는 매번 기본값으로 돌아갑니다(이전 값과 병합하지 않음).
      */
-    update(props?: SCAXEngineProps): void;
+    update(config?: SCAXEngineProps | NormalizedEngineConfig): void;
     dispose(): void;
     private configure;
     /**
@@ -165,11 +129,6 @@ export declare class SCAXEngineCore {
      * includeSturmData 값과 무관하게 확장 분석(Sturm/retinaPairs)을 항상 포함합니다.
      */
     simulate(): SimulateResult;
-    /**
-     * eye.p / eye.p_ax(처방값)를 기준으로, 렌더링에서 바로 쓸 눈 회전량을 반환합니다.
-     * - x_deg/y_deg는 프리즘 회전량에 eye.tilt를 합산한 최종 렌더 회전량입니다.
-     */
-    getEyeRotation(): EyeRotationForRender;
     /**
      * 1) Ray tracing 전용 함수
      * 광원에서 시작한 광선을 표면 순서대로 굴절시켜 최종 광선 집합을 반환합니다.
@@ -299,31 +258,8 @@ export declare class SCAXEngineCore {
     private surfaceOrderZ;
     private readSurfacePosition;
     private getRayPoints;
-    private isRayInsidePupil;
     private powerVectorFromCylinder;
-    private aggregatePowerVector;
-    /** 난시 주경선 TABO 각도: 180° 동치이므로 표시·비교는 항상 [0, 180)으로 맞춘다. */
-    private normalizeTaboMeridian180;
-    private principalMeridiansFromVector;
-    private astigmatismSummaryLensPowers;
-    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 estimateAffineDistortion;
     private createAffinePairs;
@@ -334,6 +270,7 @@ export declare class SCAXEngineCore {
  */
 export default class SCAXEngine {
     private readonly core;
+    private normalizedConfig;
     constructor(props?: SCAXEngineProps);
     get lens(): Surface[];
     get light_source(): LightSource;
@@ -341,7 +278,6 @@ export default class SCAXEngine {
     update(props?: SCAXEngineProps): void;
     dispose(): void;
     simulate(): SimulateResult;
-    getEyeRotation(): EyeRotationForRender;
     rayTracing(): Ray[];
     sturmCalculation(rays?: Ray[]): {
         slices_info: {
@@ -454,6 +390,11 @@ export default class SCAXEngine {
             };
         }[];
     };
-    getAffineAnalysis(): AffineAnalysisResult;
+    calculateMeridians(scaxPowers: SCAXPower[]): MeridianInfo;
+    calculateEyeRotationByPrism(prism: PrismPower): {
+        x: number;
+        y: number;
+    };
 }
+export {};
 //# sourceMappingURL=scax-engine.d.ts.map

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

@@ -1,4 +1,4 @@
-import { Vector3 } from "three";
+import { Quaternion, Vector3 } from "three";
 import { RefractiveIndexSpec } from "../optics/refractive-index";
 import Ray from "../ray/ray";
 import Surface from "./surface";
@@ -28,6 +28,10 @@ export type STSurfaceProps = {
         z: number;
     };
     thickness?: number;
+    /** 임상 프리즘(Δ). 있으면 굴절 직후 광선에 적용합니다. */
+    p?: number;
+    /** 프리즘 Base 축(°, 렌즈→각막 시점). */
+    p_ax?: number;
 };
 export default class STSurface extends Surface {
     private static readonly POWER_EPS_D;
@@ -44,7 +48,9 @@ export default class STSurface extends Surface {
     private toricSurface;
     private sphericalRadiusMm;
     private toricRadiusPerpMm;
+    private readonly prismVector;
     constructor(props: STSurfaceProps);
+    private pushRefractedWithPrism;
     /**
      * 디옵터(D)로부터 반경(mm)을 계산합니다.
      *
@@ -88,5 +94,6 @@ export default class STSurface extends Surface {
     refract(ray: Ray): Ray | null;
     incident(ray: Ray): Vector3 | null;
     getOptimizedThicknessMm(): number;
+    applyRigidRotationAboutPivot(pivot: Vector3, rotation: Quaternion): void;
 }
 //# sourceMappingURL=st-surface.d.ts.map

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

@@ -1,4 +1,4 @@
-import { Vector2, Vector3 } from "three";
+import { Quaternion, Vector2, Vector3 } from "three";
 import Ray from "../ray/ray";
 export type SurfaceProps = {
     type: string;
@@ -28,5 +28,11 @@ export default abstract class Surface {
     abstract incident(ray: Ray): Vector3 | null;
     abstract refract(ray: Ray): Ray | null;
     clearTraceHistory(): void;
+    getWorldPosition(): Vector3;
+    setPositionAndTilt(position: Vector3, tiltXDeg: number, tiltYDeg: number): void;
+    /**
+     * 안질 tilt가 0인 표면을 전제로, pivot 기준 강체 회전 후 동일 Euler(XYZ) tilt를 부여합니다.
+     */
+    applyRigidRotationAboutPivot(pivot: Vector3, rotation: Quaternion): void;
 }
 //# sourceMappingURL=surface.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scax-engine",
-  "version": "0.1.7",
+  "version": "0.2.0-beta.1",
   "description": "Optical calculation engine for an eye model, with ESM, CJS, and UMD builds.",
   "main": "./dist/scax-engine.cjs",
   "module": "./dist/scax-engine.js",