Manual Example Inventory ======================== The appendix of the provisional manual demonstrates the breadth of KrakenOS. The table below maps the manual examples to current UI or repository coverage. The UI ``Examples`` menu intentionally lists only examples that can be expanded into table rows, traced, and rendered by the layout editor. Script-only tutorials remain documented and runnable from ``KrakenOS/Examples``, but they are not menu entries because importing them can execute reporting code instead of defining a UI-loadable optical system. Examples with file-write side effects at import time are also excluded from the UI menu. .. list-table:: :header-rows: 1 * - Manual example - Core feature - Current coverage * - Ray - Direct ``Trace`` with a single ray. - Sequential preview and Ray Inspector. * - Perfect Lens - Ideal lens behavior. - Thin Lens row and paraxial analysis. * - Doublet Lens 3D Color - Multi-surface refractive system and 3D display. - Common doublet layouts and embedded/legacy 3D viewers. * - Doublet Lens Tilt - Tilted surfaces and exact 3D transforms. - Table tilt/decenter columns and folded/non-sequential previews. * - Doublet Lens Paraxial Calculations - ``Parax`` and matrix outputs. - Paraxial Calculator, Paraxial Matrix Report, and Gaussian Beam Report. * - Doublet Lens Tilt Nulls - Null transformations and off-axis testing. - Transform columns and trace-mode controls. * - Doublet Lens NonSec - ``NsTrace``. - Non-Sequential Preview, Scene Graph, Ray Inspector, Trace Path Inspector. * - Doublet Lens Zernike - ``ZNK`` surface deformation. - Shape Builder and wavefront/Zernike analysis. * - Doublet Lens Tilt NonSec - Tilted non-sequential tracing. - Non-sequential trace controls and diagnostics examples. * - Doublet Lens Pupil - ``PupilCalc``. - Source/Pupil panel. * - Doublet Lens Commands System - System/ray arrays. - Ray Inspector and CSV export. * - Doublet Lens Pupil Seidel - Seidel sums. - Seidel analysis mode. * - Doublet Lens Cylinder - Cylindrical/toroidal surfaces. - Advanced Surface ``Cylinder_Rxy_Ratio``. * - Axicon - Axicon surface. - Table/Advanced Surface axicon field. * - Axicon And Cylinder - Combined non-spherical geometry. - Table and Shape Builder workflows. * - Flat Mirror 45 Deg - Mirror, fold, and ``AxisMove``. - Mirror rows, folded preview, non-sequential preview. * - Beam Splitter 50/50 Example - Deterministic finite-plate beam splitter. - ``Beam Splitter`` front face, BK7 substrate thickness, rear AIR face, detector path-placement helpers, ``Element`` path metadata, deterministic transmitted/reflected paths, scene/path diagnostics. * - Beam Splitter Coating Table Example - Deterministic branch powers from coating-table interpolation. - ``KrakenOS/Examples/Examp_Beam_Splitter_Coating_Table.py`` uses ``split_mode = "Deterministic coating table"`` and verifies angle/wavelength coating data drives reflected/transmitted child powers. * - Beam Splitter Fresnel Polarization Example - Deterministic branch powers from KrakenOS core P/S Fresnel coefficients. - ``KrakenOS/Examples/Examp_Beam_Splitter_Fresnel_Polarization.py`` uses ``split_mode = "Deterministic Fresnel P/S"`` and compares pure P, equal P/S, pure S, and reflected S-retardance cases plus ``BRANCH_JONES_P``/``BRANCH_JONES_S`` and ``BRANCH_POLARIZATION_XYZ`` on a finite BK7 splitter. * - Beam Splitter Two Path Doublets - Transmitted and reflected splitter paths, each with one doublet. - One canonical non-sequential surface table with transmit/reflect ``Element`` metadata, path labels, and per-path detectors. * - Diffuse Object Lambertian Scatter - Built-in diffuse surface branch spawning. - ``Layouts -> Diffuse Object Lambertian Scatter`` plus ``KrakenOS/Examples/Examp_Diffuse_Object_Lambertian_Scatter.py``. A collimated source hits a ``Diffuse Object`` row carrying ``DiffuseScatter`` metadata; ``NsTrace`` spawns deterministic ``scatterNN`` child branches with power set by the Lambertian reflectance and sample count. * - Diffuse Object Cosine Lobe Scatter - Built-in beyond-Lambertian glossy scatter branch spawning. - ``Layouts -> Diffuse Object Cosine Lobe Scatter`` plus ``KrakenOS/Examples/Examp_Diffuse_Object_Cosine_Lobe_Scatter.py``. A collimated source hits a ``Diffuse Object`` row with ``model='Cosine Lobe'`` and ``lobe_exponent=35``; ``NsTrace`` spawns deterministic ``scatterNN`` branches around the physical specular reflection direction. * - Diffuse Object Oren-Nayar Scatter - Built-in rough-diffuse BRDF branch spawning. - ``Layouts -> Diffuse Object Oren-Nayar Scatter`` plus ``KrakenOS/Examples/Examp_Diffuse_Object_Oren_Nayar_Scatter.py``. An oblique collimated source hits a ``Diffuse Object`` row with ``model='Oren-Nayar'`` and ``roughness_deg=35``; ``NsTrace`` spawns deterministic ``scatterNN`` branches with non-uniform rough-diffuse power weights. * - Diffuse Object pySCATMECH Microroughness - Optional SCATMECH BRDF weighting on deterministic scatter branches. - ``Layouts -> Diffuse Object pySCATMECH Microroughness`` plus ``KrakenOS/Examples/Examp_Diffuse_Object_pySCATMECH_Microroughness.py``. The ``Diffuse Object`` row requests ``backend='pySCATMECH'`` and ``backend_model='Microroughness_BRDF_Model'`` with Gaussian PSD parameters. If ``SCATPY`` is not installed, the trace records an explicit fallback interaction label. * - Right-Angle Beam-Splitter Illumination - Physical illumination source at 90 degrees to the object/reference axis. - ``Layouts -> Beam Splitters / Folds -> Right-Angle Beam-Splitter Illumination`` plus ``KrakenOS/Examples/Examp_Right_Angle_Beam_Splitter_Illumination.py``. Source 1 launches from ``(0, -80, 45) mm`` along ``+Y``; the splitter reflects illumination to a left-side ``Object Target`` on ``-Z``, then the object-return transmitted branch passes through a clear aperture to the right-side camera/Image row while the Object row remains reference geometry. ``Object Target`` is still the specular single-return proxy; use ``Diffuse Object`` for Lambertian scattering. The layout declares ``scene_row_order="before_object"`` for the future source-visible table. * - Zemax LED Beam-Splitter Imaging - Vendor Zemax LED rayfile source, top-port illumination, splitter/object return, imaging lens, and Image plane. - ``Layouts -> Beam Splitters / Folds -> Zemax LED Beam-Splitter Imaging`` plus ``KrakenOS/Examples/Examp_Zemax_LED_Beam_Splitter_Imaging.py``. The OSRAM ``.DAT`` source launches from ``(0, 45, 45) mm`` along ``-Y``; the Object row is reference only. The useful branch reflects from the 45 degree splitter to the left-side ``Diffuse Object``, then guided Lambertian scatter aims at the splitter return aperture so transmitted return rays pass through the simple BK7 imaging lens and Image plane. * - Multi-Source Illumination Example - Two independent layout-defined physical illumination sources. - ``Layouts -> Sources / Illumination -> Multi-Source Illumination Example`` plus ``KrakenOS/Examples/Examp_Multi_Source_Illumination.py``. The layout declares ``SETTINGS["scene_sources"]`` with ``source:left`` and ``source:right``; both trace to a shared detector while preserving per-ray ``SOURCE_ID`` metadata. * - Mixed Source/Object Imaging Template - Source-first layout template where illumination source, Object/reference row, and detector/Image row are separate entities. - ``Layouts -> Sources / Illumination -> Mixed Source/Object Imaging Template`` plus ``KrakenOS/Examples/Examp_Mixed_Source_Object_Imaging_Template.py``. The layout declares one physical ``SceneSource3D`` emitter in ``SETTINGS["scene_sources"]`` and uses ``scene_row_order="before_object"`` so the source appears before Object in the visible scene order without consuming a KrakenOS surface index. Use this as the clean starting point for side illumination, source-to-object setups, and adding lenses/stops between the object-side aperture and Image row. * - Scene Source Aim To Row - Headless example of the Scene Source Manager target-row aiming helper. - ``KrakenOS/Examples/Examp_Scene_Source_Aim_To_Row.py`` creates an off-axis aperture row, aims a physical source at that row center, and prints the normalized ``Source L/M/N`` values that the UI writes when ``Aim Direction At Row`` is clicked. It also demonstrates ``Place Origin At Standoff`` by placing ``Source X/Y/Z`` a fixed distance upstream along the current source direction. The second half shows the same helpers targeting an assigned CAD/STL optical face centroid. * - Galvo F-Theta Laser Scanner - Folded laser source path, beam expander, 45 degree scan mirror, F-theta lens, and scan plane. - ``Common Optical Layout -> Galvo F-Theta Laser Scanner`` plus ``KrakenOS/Examples/Examp_Galvo_FTheta_Laser_Scanner.py``. The scanner uses the 50 mm Figure 8 F-theta prescription extracted from ``attachment/F-theta.pdf``; ``K9`` is mapped to CDGM ``H-K9L``. Type ``40,45,50`` in the mirror ``TiltX`` cell to overlay a conservative ``-10,0,+10`` degree optical scan; ``35,45,55`` is the lens' nominal full ``-20,0,+20`` degree optical scan. Branch-local Gaussian frames and branch-carried q propagation are validated in Phase 7C; Gaussian-source interferograms can also use detector-bin Gaussian-q recombination. * - Branch Gaussian Q Propagation - Deterministic non-sequential branch records carrying tangential/sagittal Gaussian q state. - ``KrakenOS/Examples/Examp_Branch_Gaussian_Q_Propagation.py`` loads the Michelson preset, consumes Ray Inspector branch hit records with ``KrakenOS.propagate_branch_gaussian_q``, and prints final q/radius values for each deterministic splitter branch. * - F-Theta Lens 50mm Figure 8 - Standalone 0.65 um, 50 mm F-theta lens from ``attachment/F-theta.pdf`` Figure 8. - Includes the Zemax stop spacing, four refractive elements, and final scan plane. * - F-Theta Lens 50mm Wavefront 0 Deg - Pure sequential Wavefront Function validation for the Figure 8 F-theta lens at ``0.00 DEG`` field. - Use this layout when comparing against the on-axis Zemax screenshot in ``attachment/swappy*.png``. It intentionally excludes the Galvo scanner, beam expander, and folded mirror. * - Zemax Wavefront Map Import - External Zemax Wavefront Map text export validation. - ``File -> Import Zemax Wavefront Map...`` loads a Zemax text export as a numerical reference for ``WFront``. ``KrakenOS/Examples/Examp_Zemax_Wavefront_Map_Import.py`` demonstrates standalone loading and normalized-pupil sampling; ``python -m KrakenOS.UI.validate_zemax_wavefront_import`` validates parsing and residual comparison. * - Attachment Zemax Prescriptions - Recursive text ``.zmx`` prescription import examples. - ``Examples -> Zemax Prescriptions (attachment)`` lists text prescriptions found under ``attachment/zemax`` grouped by subfolder and loads them with the same converter as ``File -> Import Zemax File...``. ``python -m KrakenOS.UI.validate_testing_zemax_examples`` validates the scan and parser coverage. * - Michelson Interferometer (Interferogram) - Source/object split, return paths, detector path, second splitter encounter, and detector interferogram. - Independent physical source direction, Edmund Optics 68551 25 mm cube-beam-splitter primitive, internal 45 degree deterministic splitter, two return mirrors, four recombination-path branch records, and ``Interf`` analysis that promotes to detector-bin coherent accumulation when detector sampling is sufficient. * - Twyman-Green Interferometer (Interferogram) - Test/reference return paths and detector-port interferogram. - Common layout preset plus ``KrakenOS/Examples/Examp_Twyman_Green_Interferometer.py``; uses the tested deterministic return-path recombination workflow with Twyman-Green test optic/reference flat naming. * - Mach-Zehnder Interferometer (Interferogram) - Two splitters, two fold mirrors, cross/return output detector ports, and detector-bin coherent interferogram promotion with analytic fallback for sparse previews. - Common layout preset plus ``KrakenOS/Examples/Examp_Mach_Zehnder_Interferometer.py``; both paths reach the second splitter, the editable table exposes physical ``Path 1`` through ``Path 5`` assignment, and the trace path inspector records transmit-reflect, reflect-transmit, transmit-transmit, and reflect-reflect histories for the promoted detector-bin or fallback analytic interferogram diagnostic. * - Parabole Mirror Shift - Off-axis conic via shift. - ``k`` plus ``ShiftX``/``ShiftY`` in Advanced Surface. * - Diffraction Grating Transmission - Transmission grating. - Grating row plus Additional Settings. * - Diffraction Grating Reflection - Reflection grating. - Grating row plus Additional Settings. * - Tel 2M Spyder Spot Diagram - Mask/obstruction and spot diagram. - Shape Builder mask presets and spot analysis. * - Tel 2M Spyder Spot Tilt M2 - Tilted telescope mirrors and masks. - Element grouping, transform columns, spot analysis. * - Tel 2M Pupila - Telescope pupil generation. - Source/Pupil panel and pupil analysis. * - Tel 2M Error Map - Measured surface error map. - Error Map import/clear/validate workflow. * - Tel 2M Wavefront Fitting - Wavefront Function, phase maps, and Zernike fitting. - Wavefront/Zernike reports and CSV exports. * - Tel 2M STL ImageSlicer - STL-backed non-sequential assembly. - ``Solid_3d_stl`` staging, scene graph inspection, non-sequential tracing. * - Phase 6 Optical STL Prism - Arbitrary closed STL optical solid with material-driven refraction. - ``File -> Import Optical CAD/STL Solid...``, 3D inspector CAD/STL placement, and ``KrakenOS/Examples/Examp_Phase6_Optical_STL_Prism.py`` show the same native ``Solid_3d_stl`` workflow with ``NsTrace`` rays. STEP/IGES vendor CAD is meshed to cached STL first. * - Phase 6 Path Component Placement - Path-local component insertion from a beam splitter. - ``KrakenOS/Examples/Examp_Phase6_Path_Component_Placement.py`` demonstrates the same helper used by ``Add component to transmitted/reflected path...`` and prints native row Tilt/Decenter plus ``Element`` metadata for detector, aperture, thin lens, refractive surface, mirror rows, and a rigid stock-catalog lens block placed on a path. * - Lens Drawing PDF Export - Fabrication drawing output from a multi-element prescription. - ``KrakenOS/Examples/Examp_Lens_Drawing_PDF_Export.py`` builds a cemented triplet, attaches per-surface ``DrawingProperties`` metadata, writes a JSON sidecar, and exports the same ISO-style multi-page PDF drawing documented in :doc:`../tutorials/lens_drawing_pdf_export`. * - Tel 2M Atmospheric Refraction Corrector - Atmospheric refraction and correction. - Atmospheric dispersion/residual analysis. * - Extra Shape Micro Lens Array - Custom ``ExtraData`` sag. - Shape Builder safe custom-sag presets. * - Extra Shape Radial Sine - Custom radial surface. - Shape Builder radial sine preset. * - Extra Shape XY Cosines - Custom x/y cosine surface. - Shape Builder x/y cosine preset. * - Multicore - Parallel tracing. - Batch tracing and background analysis workers. * - Solid Objects STL Array - Multiple STL solids. - STL path staging and non-sequential diagnostics. * - Source Distribution Function - ``SourceRnd.fun`` angular weighting. - SourceRnd angular weight presets and source statistics. * - Beam Splitter 50/50 - Direct API deterministic finite-plate splitter. - ``KrakenOS/Examples/Examp_Beam_Splitter_50_50.py`` and the UI common layout.