Core Model: Surfaces And Systems

The manual describes KrakenOS as two primary object types:

surf

One optical interface or object. It stores geometry, aperture, material, coating, drawing, and transform state.

system

An ordered list of surf objects plus the methods that trace rays and expose ray state.

Surface attributes

The provisional manual highlights these core surf fields. The current layout editor exposes the scalar fields directly in the table and the remaining fields through Advanced Surface, Shape Builder, grating additional settings, catalog import, or element grouping.

Attribute

Meaning

Current UI exposure

Name, Note

Human labels and per-surface comments.

Table name plus Advanced Surface notes.

Rc, k, AspherData, ZNK

Spherical, conic, aspheric, and Zernike surface shape.

Table Rc/k plus Shape... and Advanced Surface.

Cylinder_Rxy_Ratio, Axicon

Cylindrical/toroidal ratio and axicon angle.

Table/Advanced Surface.

Thickness, Diameter, InDiameter

Axial spacing and clear/inner apertures.

Table/Advanced Surface.

DespX, DespY, DespZ

Decenter in the surface coordinate system.

Table.

TiltX, TiltY, TiltZ

Surface rotations.

Table.

Order, AxisMove

Transformation order and optical-axis propagation.

Table/Advanced Surface.

Diff_Ord, Grating_D, Grating_Angle

Diffraction grating order, period, and orientation.

Row right-click Additional Settings for grating rows.

ShiftX, ShiftY

Surface-profile offset for off-axis shapes.

Advanced Surface.

Mask_Type, Mask_Shape, UDA

Aperture masks and user-defined apertures.

Shape... presets and Advanced Surface.

ExtraData

User-defined sag function plus coefficients.

Shape... safe presets; arbitrary Python is preserved on import.

Error_map

Measured surface error map [X, Y, Z, spacing].

Error Map workflow and Phase 2 reports.

Drawing, Color, Nm_Pos, NumLabel

Display behavior, color, and labels.

Advanced Surface and display code.

DrawingProperties UI metadata

Fabrication-drawing callouts such as clear aperture, form/power, scratch-dig, coating notes, and surface notes. This is UI metadata saved in row advanced attributes; it does not change ray physics.

File -> Lens Drawing Surface Properties... and File -> Export Lens Drawing... before PDF generation.

Solid_3d_stl

STL-backed optical solid.

Shape... path staging and Non-Sequential Scene Graph.

Coating, CoatingMet

Dielectric and metal coating data.

Coating/material workflow and polarization reports.

BeamSplitter

UI metadata for splitter mode, reflectance, loss, phase, and branch limits.

Beam Splitter row plus right-click settings; deterministic non-sequential tracing spawns transmitted/reflected child branches, with a generated coating table retained as a legacy fallback.

Object Target

Semantic UI surface type for a source/object split target.

Runtime maps to MIRROR as a specular proxy for fixtures that still need a single return ray.

DiffuseScatter

Diffuse/BRDF metadata for Diffuse Object rows.

Built-in Lambertian, Oren-Nayar, Cosine Lobe, and optional pySCATMECH rows spawn deterministic child branches in NsTrace.

System methods and state

The manual identifies system.Trace() for sequential tracing and system.NsTrace() for non-sequential tracing. The UI now exposes both modes through the trace-mode selector. Scene tracing adds NsLimit, target-surface selection, probabilistic coating splitting via energy_probability, and non-sequential scene/trace-path diagnostics. Beam-splitter rows add deterministic transmit/reflect child branches, and Diffuse Object rows add deterministic built-in scatter child branches, in NsTrace()/NsTraceLoop().

The manual also describes system ray arrays such as SURFACE, NAME, GLASS, XYZ, S_XYZ, T_XYZ, OST_XYZ, DISTANCE, OP, TOP, TOP_S, ALPHA, BULK_TRANS, S_LMN, LMN, R_LMN, N0, N1, WAV, G_LMN, ORDER, GRATING_D, RP, RS, TP, TS, TTBE, and TT. The UI also adds scene-source and branch metadata arrays such as SOURCE_ID, SOURCE_NAME, SOURCE_ROLE, SOURCE_MODEL, SOURCE_XYZ, SOURCE_LMN, SOURCE_POWER, SOURCE_WEIGHT, SOURCE_WAVELENGTH, LAUNCH_FIELD_REQUESTED, LAUNCH_FIELD_EFFECTIVE, LAUNCH_FIELD_BASIS, LAUNCH_FIELD_ACTIVE, LAUNCH_RAY_COUNT, LAUNCH_TRACE_INTENT, LAUNCH_SAMPLING_MODE, BRANCH_ID, BRANCH_PATH, BRANCH_POWER, and BRANCH_PHASE. These are collected through raykeeper and surfaced in the UI through canonical RayEvent3D records, the Ray Inspector, Trace Path Inspector, Non-Sequential Scene Graph, and CSV exports.

Glass catalogs

The manual describes Setup as the configuration object that loads glass catalogs from KrakenOS/Cat. The current UI exposes this through:

  • File -> Glass Catalog Browser

  • row material editing

  • stock lens import

  • enhanced Zemax text import with embedded n/V fallback glasses