KrakenOS
Manual
Provisional Manual
Installation And Prerequisites
Basic installation paths
Running the layout editor
Manual source
Core Model: Surfaces And Systems
Surface attributes
System methods and state
Glass catalogs
Classes and Attributes
Table 1 —
surf
class attributes
Table 2 —
system
class implementations and attributes
Working with the KrakenOS Library
3.1 Ray generation
3.2 Extraction of ray information
3.3 Generation of the optical system graph
Raykeeper introspection
Parax Tool
PupilCalc Tool
Pupil parameters
Automatic ray generation
5.1 Atmospheric refraction in PupilCalc
Pupil Patterns (Source Model: Pupil / field)
2D Pattern Versus 3D Scene Launch
Meridional fan
Cross fan
Fan X
Fan Y
Hexapolar
Square
Random disk
Chief ray
R-theta
Summary
Analysis Tools (Layout Editor Toolbar)
Symbol conventions
Shared setup for the code examples
Using analyses as optimization targets
Why each analysis matters and when to target it
Conflicting objectives — what you give up
Worked case studies: from a poor start to best
Geometric image quality
Spot — Spot Diagram
RMS — RMS Spot Radius
PSF — Point Spread Function
MTF — Modulation Transfer Function
Pupil and wavefront
Pupil — Pupil Diagnostic
Seidel — Seidel Aberrations
WFront — Wavefront Analysis
Zernike — Zernike Polynomial Fit
Field-dependent metrics
FC/Dist — Field Curvature / Distortion
Illum — Relative Illumination
LatClr — Lateral Color
Pol — Polarization
Atmos — Atmospheric Dispersion
Map analyses on the detector / pupil
PSFMap — Point Spread Function Map
FldMap — Field Map
IllMap — Illumination Map
WfeMap — Wavefront Error Map
DetMap — Detector Power Map
CohDet — Coherent Detector Field Sum
BField — Branch Field
Diffr — Diffraction Detector
Comparative analyses
Interf — Interferogram
TolCmp — Tolerance Compare
Cross-reference table
Editable Table Workflow
Loading versus inserting
Insertion point
Surface and element clipboard
Surface right-click menu
Compact prescription columns
Optimization cell marker
Tolerance Monte Carlo report
Prisms and cube beam splitters
Tilt and decenter tolerance overlays
Validation
Non-Sequential-First Design Goals
Goal 1: non-sequential tracing is the native model
Goal 2: 3D tracing is authoritative; 2D is only a slice
Goal 3: object and illumination source are separate scene entities
Goal 4: every surface interaction obeys physics law
Implementation checklist
Tracing And Ray Data
Scene-first UI model
2D slices, 3D scenes, and CAD envelopes
Sequential tracing special case
Non-sequential tracing
Scene source records
Launch sampling metadata
Scene target records
Possible next scene workflows
Optical STL prism check
Face-role metadata check
Face-anchor snap-to-ray check
Face-fit placement check
Path-frame face-fit check
Virtual internal plane check
Optical-solid hit-sequence check
Raykeeper data
Inspect Ray / Surface Physics
Multicore and batch tracing
Zemax Rayfile Sources
Import workflow
Ray sampling
Example saved layout source record
Validation
Current limitations
Beam-splitter imaging example
Pupil, Paraxial, And Analysis Tools
Paraxial tool
PupilCalc
Atmospheric refraction
Wavefront and aberration tools
Zemax Wavefront Map comparison
Image-quality maps
Gaussian Beam Propagation
Beam fundamentals
Complex beam parameter and ABCD transformation
Input conventions
Datasheet diameter/divergence flow
Report columns
Astigmatic and elliptical beams
Phase 8 branch-field propagation
Phase 8B oblique astigmatic q baseline
Cavity eigenmode flow
UI workflow
Folded laser scanner example
Python example
Scope and limitations
Source-mode field relevance
Beam Splitters
Terminology
Current capability
Split modes
UI workflow
Path workflow tutorial
Two-path doublet example
Manual path assignment
Path Workbench workflow
Separate source and object status
Right-angle illumination example
Michelson detector/interferogram workflow
Twyman-Green example
Mach-Zehnder example
Automatic path graph
Saved metadata
Python example
Internal branch data
Path throughput report
Path-filtered detector analyses
Concrete DetMap examples
Path-analysis validation fixture
Phase 2 source and path workflow
Resizing a cube beam splitter (coupled cross-section)
Recovering the 45° coating as a selectable face
Future tilted/folded/non-sequential Gaussian optics
Diffuse And BRDF Scattering
Surface Type
Guided Target Sampling
Examples
pySCATMECH Optional Backend
Lens Fabrication Drawings
Surface Property Workflow
Supported Fields
Example In A Layout File
Reference Behaviour
Display And Viewers
2D display
Lens drawing PDF export
3D display
CAD/STL optical solids
Placement workflow
STEP and CAD overlays
Handling the 3D Viewer
Quick Estimation (object / image / FOV)
The design flow
Two readings of the same move
Right-click actions
Graphical FOV solve (double-click a plane)
Variable-thickness solve (Best Focus / Best Collimation)
Sensor coverage and recommended sensor
Forbidden values
Validation
Responsive STEP Handling Architecture
Problem Statement
Current Kraken Bottleneck
What CadQuery Shows
Target Architecture
Interaction Rules
Expected Improvement
Implementation Plan
Recommended Immediate Next Step
Manual Example Inventory
Appendix — Examples
7.1 Example — Ray
7.2 Example — Perfect Lens
7.3 Example — Doublet Lens 3D Color
7.4 Example — Doublet Lens Tilt
7.5 Example — Doublet Lens (Paraxial Calculations)
7.6 Example — Doublet Lens Tilt Nulls
7.7 Example — Doublet Lens NonSec
7.8 Example — Doublet Lens Zernike
7.9 Example — Doublet Lens Tilt NonSec
7.10 Example — Doublet Lens Pupil
7.11 Example — Doublet Lens Commands System
7.12 Example — Doublet Lens Pupil + Seidel
7.13 Example — Doublet Lens Cylinder
7.14 Example — Axicon
7.15 Example — Axicon and Cylinder
7.16 Example — Flat Mirror 45 Deg
7.17 Example — Parabolic Mirror Shift
7.18 Example — Diffraction Grating in Transmission
7.19 Example — Diffraction Grating in Reflection
7.20 Example — Tel 2M Spyder Spot Diagram
7.21 Example — Tel 2M Spyder Spot, M2 Tilt
7.22 Example — Tel 2M Pupila
7.23 Example — Tel 2M Error Map
7.24 Example — Tel 2M Wavefront Fitting
7.25 Example — Tel 2M STL Image Slicer
7.26 Example — Tel 2M Atmospheric-Refraction Corrector
7.27 Example — ExtraShape Micro Lens Array
7.28 Example — ExtraShape Radial Sine
7.29 Example — ExtraShape XY Cosines
7.30 Example — MultiCore
7.31 Example — Solid Objects STL Array
7.32 Example — Source Distribution Function
References
Tutorials
Tutorials And Case Studies
Case Study 1: Turn A Glass Plate Into A 100 mm PCX Lens
Goal
Build The Starting Plate
Make The Front Surface Variable
Set The EFFL Target
Place The Image Plane Correctly
Workflow A: solve image distance after EFFL
Workflow B: optimize EFFL and focus together
What The User Should See
Common Mistakes
Case Study 2: Focus A Finite Machine-Vision Lens
Goal
Load The Finite Lens
Make A Bad First Analysis
Choose The Right Variable
Run The Focus Solve
Workflow A: best-focus solve
Workflow B: general optimizer
Verify The Improvement
Check The Wide Field
What This Proves
Common Mistakes
Case Study 3: PYRITE 85 mm Machine-Vision Surrogate
What The Surrogate Is
Vendor STEP Overlay
Default UI Settings
How The Blackbox Is Built
Rendered Layout
Known Limits
Validation
Case Study 4: AZURE ELS-85 mm Machine-Vision Surrogate
What The Surrogate Is
Vendor STEP Overlay
Default UI Settings
How The Blackbox Is Built
Rendered Layout
Known Limits
Validation
Case Study 4b: AZURE ELS-85 mm On A Right-Angle Mirror
A Promoted STEP Mirror, Not A Sequential Mirror Row
The Conjugate And Prescription
What Is In The Layout
Rendered Layout
Validation
Case Study 4: PYRITE 120 mm Machine-Vision Surrogate
What The Surrogate Is
Vendor STEP Overlay
Default UI Settings
How The Blackbox Is Built
Rendered Layout
Known Limits
Validation
Case Study 5: Gaussian Laser Beam Expander
Goal
Load The Laser Line
Back-Calculated Waist
Insert A 3x Keplerian Expander
Verify The Expanded Beam
Run BField Analysis
What This Proves
Common Mistakes
Case Study 6: Michelson Beam Splitter And Interferogram
Goal
Load The Michelson Layout
Read The Path Labels
Use Path View
Run Detector Analyses
Show The Interferogram
Run Branch Field
What This Proves
Common Mistakes
Case Study 7: Mach-Zehnder Two-Output Interferometer
Goal
Load The Mach-Zehnder Layout
Read The Path Labels
Use Path View For Each Output
Run Detector Analyses
Show The Interferogram
Run Branch Field
Check The Return Output
What This Proves
Common Mistakes
Case Study 8: Source/Object Split Through A Beam Splitter
Goal
Load The Layout
Read The Physical Paths
Use Path View
Audit Source Illumination
Run The Camera Detector Map
Run The Python Example
What This Proves
Common Mistakes
Case Study 9: Zemax LED Source To Diffuse Object Imaging
Goal
Load The Layout
Read The Scatter Paths
Use Path View
Inspect Diffuse / BRDF Settings
Audit Source Illumination
Run Image-Plane Analyses
Run The Python Example
What This Proves
Common Mistakes
Case Study 10: Multi-Source Illumination
Goal
Load The Layout
Read The Layout
Inspect Scene Sources
Audit Per-Source Throughput
Run Detector Analyses
Run The Python Example
What This Proves
Common Mistakes
Case Study 11: Tolerance Monte Carlo And Compensators
Goal
Load The Native-Variable Layout
Choose Tolerance Roles
Run Monte Carlo
Compare The Worst Sample
Plot The Worst-Sample Spot Overlay
Read The Stack-Up Bars
Run Compensator Sweeps
Check MTF Impact
Run The Python Example
What This Proves
Common Mistakes
Case Study 12: Optical STL Prism And Face Roles
Goal
Load The Optical STL Prism
Read The 2D Trace
Assign Optical Faces
Inspect Mesh Readiness
Verify The Trace Sequence
Run The Python Examples And Validators
What This Proves
Common Mistakes
Case Study 13: Cube Beam Splitter CAD And Virtual Plane
Goal
Load Or Import The Cube Body
Observe The Passive CAD Trace
Assign External Faces And Build A Virtual Plane
Read The Virtual Plane Report
Use The Primitive For Splitter Physics Today
Check Mesh Readiness
Run The Validators
What This Proves
Common Mistakes
Case Study 14: Vendor Prism CAD Import And Face Placement
Goal
Bundled Vendor Files
Load The Vendor CAD Prism
Set Source Divergence
Inspect The Converted Mesh
Assign Optical Face Roles
Understand Side Labels, Axis Fits, And Optical Functions
Examples From
penta.py
Orient From The Input Face
Off-Center Entrance Points
Read The Fitted Layout
Chain Another Prism After A Folded Path
Roll Reference Faces
Single-Face Fold Mirrors
Run The Validators
What This Proves
Common Mistakes
Case Study 15: Multi-Element Lens PDF Drawing Export
Goal
Input The Surface Table
Input Drawing Properties
Export The PDF
Run The Validator
What This Proves
Important Limitation
Case Study 16: 3D Hardware Alignment Workflows
Goal
Open The 3D Inspector
Use The CAD/STL Placement Handler
Read Active-Mode Badges
Rotate Imported STEP Hardware
Carry Imported STEP Freely
Pick Source Targets From 3D
What This Proves
Common Mistakes
Case Study 17: Cooke Triplet Optimization From A Bad Start
Goal
Load The Poor Triplet
Make The Bad Analysis
Understand The Variables
Apply The Optimized Prescription
Verify The Improvement
What This Proves
Common Mistakes
Case Study 18: One Lens, Many Analyses
Goal
Load The Analysis Layout
Spot: Check Geometric Focus
PSF: Convert Samples Into Image Intensity
MTF: Read Contrast Versus Spatial Frequency
Wavefront: Inspect Pupil Phase
Zernike: Decompose The Wavefront
What This Proves
Case Study 19: Galvo F-Theta Laser Scanner
Goal
Load The Preset
Read The Rows
Use The Galvo Scan Overlay
Check The Scan Plane
Validate The F-Theta Lens Alone
Why This Is Non-Sequential-First
Common Checks
What This Proves
Optiland-Inspired Case Study Port Backlog
Purpose
Already Covered In Current KrakenOS UI Docs
High-Value Ports
Deferred Or Research-Oriented Ports
Recommended Next Port
Knowledge Base
Knowledge Base
Rules of Thumb — Optics, Imaging, Laser
How to use this page
Section 1 — Geometric / paraxial optics
1.1 Thin-lens imaging equation
1.2 f-number, aperture cone and diffraction limit
1.3 Working f-number for finite conjugates
1.4 Two thin lenses in series
1.5 Macro 2f rule (1:1 imaging)
1.6 Snell’s law and total internal reflection
Section 2 — Imaging system rules
2.1 Angle of view and sensor format
2.2 Depth of field
2.3 Hyperfocal distance
2.4 Diffraction & resolution
2.5 Pixel sampling and the Nyquist limit
Section 3 — Lasers and Gaussian beams
3.1 Waist, Rayleigh range, divergence
3.2 Focused spot of a Gaussian beam
3.3 Two-mirror cavity stability
3.4 Power density and damage
3.5 Coherence and bandwidth
Section 4 — Cross-cutting design heuristics
Section 5 — Where to go next
Finding the Cardinal Points and Pupils by Ray Tracing
Drawing conventions
1. The six cardinal points
2. Locating
\(F'\)
and
\(P'\)
3. Locating
\(F\)
and
\(P\)
4. Nodal points
\(N, N'\)
5. Aperture stop, EP and XP
6. Chief and marginal rays — the operational definition
7. Putting it all together
Pupil Sampling — A Lecture on Where the Rays Go
1. What makes a sampler “good”?
2. The equal-area mapping
3. Section fans — when one dimension is enough
4. Hexapolar — equal-area rings
5. Square grid — when the detector decides
6. Random disk — the Monte-Carlo baseline
7. The Vogel / golden-angle spiral
Definition
Why the golden angle?
Why optical designers care
8. From disk to hemisphere — Lambertian and lobe scattering
9. KrakenOS code map
10. Choosing in practice
Further reading
Introduction To Fundamental Lens Design
Why “Lens Families” Exist
Photographic Lens Families
The Double Gauss
Tessar
Sonnar
Cooke Triplet
Retrofocus (Inverted Telephoto)
Telephoto
Petzval
Modern Aspheric / Floating-Element Designs
Photographic Family Summary
Machine Vision Lens Families
Fixed-Focal-Length (FFL) Industrial Lenses
Retrofocus On Large Sensors
Telecentric Lenses
Fixed-Magnification Macro / Inspection Lenses
Line-Scan Lenses
Spectrally Specialized Lenses
Machine Vision Family Summary
Photography vs. Machine Vision: Side by Side
Reading A Prescription In KrakenOS
Further Reading
Sub-Pixel Hot-Spot Detection in IR Imaging
The mixing model
A worked numerical example
Why visible-light imaging cannot pull this trick
The PSF assist
What can break the claim
Bottom line: detection vs. characterization
STEP Overlay Promotion — Tiers and 2D/3D Parity
Why three tiers
Tier 1 — STEP overlay
Tier 2 — STL optical-solid row
Tier 3 — Native analytic rows
Saved Tier 2 rows with a source STEP path
Flipping a Tier-3 lens: why it’s not a rotation
2D ↔ 3D row-action parity
Handle eligibility — the predicate that gates the rotation rings
Validation contract
Slide along the optical axis
Resizing an imported solid (drag a face)
Off-beam promoted solids are display-only
Diagnosing “my promoted lens does not refract”
Known follow-ups
KrakenOS
Index
Index