Display And Viewers

The provisional manual documents Kos.display2d and Kos.display3d as the primary display entry points for scripts. The current UI preserves those core ideas but routes user interaction through shared scene data.

2D display

The layout editor 2D view shows the optical layout, ray paths, folded previews, ray clipping, cardinal markers, physical-distance annotations, and plot-linked selection. The drawing path is unified around SceneBundle: YZ and XZ are section views of traced 3D data, while XY is the top-view footprint. The projection selector above the plot changes the view, not the underlying optical prescription.

Lens drawing PDF export

File -> Export Lens Drawing... opens a surface-properties dialog before it writes the ISO-style PDF. The dialog saves drawing-only metadata in each row’s DrawingProperties advanced attribute: clear aperture, form/power callout, scratch-dig, coating note, and surface note. Blank fields remain placeholders in the generated drawing. These fields are fabrication notes only; the ray tracer continues to use the native KrakenOS surface attributes such as Rc, Diameter, Glass, Coating, and Drawing.

3D display

The manual’s 3D viewer supports optical surfaces, rays, and STL-backed objects. Current UI coverage:

  • embedded 3D viewer

  • Open 3D top controls split into a View row and a Scene row, with dense CAD/target, placement, and orientation actions grouped into category menus so the controls remain reachable on narrower windows; the validate_open3d_toolbar_layout contract keeps the dense commands out of the direct toolbar rows

  • legacy 3D viewer compatibility

  • ray show/hide toggles

  • 3D ray click-to-inspect

  • plain left-click selection without camera motion; left hold-drag rotates around the current view focal point with fixed sensitivity, and Ctrl + left drag follows the same path for compatibility

  • Center Row->Ray click workflow for centering a selected surface or CAD/STL row on a traced ray

  • Snap Row->Target click workflow for moving a selected surface/CAD row or face onto another row or face

  • Orient Row->Target click workflow for rotating a selected surface/CAD row or face normal onto another row or face normal

  • Orient Row->Ray click workflow for rotating a selected surface/CAD row or face normal onto a clicked traced ray segment direction

  • Orient Row->Source command for rotating a selected surface/CAD row or face normal onto the Source panel aim vector

  • Orient Row->Path command for rotating a selected surface/CAD row or face normal onto the current Path-view frame

  • Orient Row->CAD Axis command for rotating a selected surface/CAD row or face normal onto the selected local +X/-X/+Y/-Y/+Z/-Z axis

  • Orient Row->Scene Source command for rotating a selected surface/CAD row or face normal onto an explicit Scene Source Manager source vector

  • named normal selector for Active target, Detector, and Object rows, with Preview Normal diagnostics and Orient Row->Normal apply

  • optical surface meshes and solid-body meshes in the shared scene bundle

  • row selection highlighting for surfaces and elements

  • escaped non-sequential rays projected to the configured detector/Image plane as explicit missed-detector terminal markers

  • dense 2D views suppress redundant detector-hit endpoint glyphs but keep missed detector, absorbed, escaped, and stopped terminal markers visible; missed detector/Image endpoints use a distinct orange marker in 2D and Open 3D

  • active detector/Image footprints are drawn from the scene target detector metadata in 2D, embedded 3D, and legacy 3D. A missed-detector terminal adds an orange crosshair at the projected detector-plane intercept, making the active aperture and miss point directly comparable.

  • 2D hover hints and 2D/3D ray selection messages show terminal diagnostics from the canonical ray event. For detector misses this includes detector surface, projected plane distance, radial miss, active half-aperture, local detector-plane X/Y, active detector width/height, and kernel terminal reason when available.

  • Actions -> Detector Aperture Report groups the same event-owned detector terminals by detector/Image surface. It reports ray/path count, detector hits, missed detector projections, stopped/other terminals, hit fraction, hit and miss power, worst miss margin, worst local X/Y, and the dominant terminal reason, with a matching CSV export.

  • the normal results panel includes detector aperture counts after each trace, and the status bar adds a compact detector-miss warning when a detector/Image aperture is clipped.

  • Ray Inspector top rows include a per-ray detector aperture status and miss margin, so a selected path can be classified as a detector hit, detector miss, or detector bypass without opening a separate report.

  • imported STEP axis centering: click Center STEP Axis and then click a planar/circular outer feature on any imported STEP component; the picked feature center moves onto the optical axis. If a STEP component is already selected, clicking a KrakenOS optical surface centers that STEP axis on the surface center.

  • long dotted optical-axis guide in 3D at X=0, Y=0

CAD/STL optical solids

The manual examples include STL solids, an image slicer, and solid object arrays. Vendor parts are more often supplied as STEP/IGES, so the UI accepts STL directly and meshes STEP/STP/IGES/IGS through gmsh into a cached STL for KrakenOS tracing. Current UI workflows:

  • File -> Import Optical CAD/STL Solid... for first-class optical-solid import; after the row is inserted the face-assignment dialog opens automatically

  • Actions -> 3D Place/Orient Selected CAD/STL Solid for in-view placement, axis alignment, and centring inside the existing 3D view

  • Actions -> Assign CAD/STL Optical Faces for recording face roles, with assigned roles shown as coloured normal markers in the 3D inspector and placement preview; the face preview uses the same click-select and left-drag fixed-speed rotate behaviour as Open 3D

  • Shape... path staging for Solid_3d_stl

  • row tilt/decenter alignment for the solid object

  • Actions -> Inspect Optical CAD/STL Solids topology and scale diagnostics

  • Non-Sequential Scene Graph inspection of CAD/STL rows

  • non-sequential tracing and trace-path diagnostics

An imported row stores the native KrakenOS Solid_3d_stl attribute in row advanced metadata. For CAD sources, OpticalSolidSourcePath records the original STEP/IGES file and Solid_3d_stl points to the cached mesh. The row material controls refraction, the mesh supplies only geometry, and dimensions are interpreted as millimetres. Auto scene trace resolves to Non-Sequential Preview for these rows so rays are traced with KrakenOS NsTraceLoop instead of the axial sequential special case. The 2D plot shows a projected mesh footprint outline for file-backed solids so the solid body remains visible even when rays pass through or overlap it.

For arbitrary prism shapes, use closed/manifold meshes with correct face normals. Start from KrakenOS/Examples/Examp_Phase6_Optical_STL_Prism.py and replace the mesh path, material, pose, and source bundle.

Arbitrary-prism workflow status: the current UI can import, diagnose, trace, and display a closed optical solid, but raw table pose editing is not the intended authoring experience. Treat TiltX/Y/Z and DespX/Y/Z as the saved KrakenOS execution representation. The practical workflow should be a face-role scene-object workflow:

  1. Import the STEP/STL/IGES file. The UI inserts the optical-solid row and immediately opens the CAD/STL face-assignment dialog.

  2. Select mesh/CAD faces and assign a 2D side label plus an optical function. Side labels are Left, Right, Up, Down, Front, and Back; the first four are referenced to the YZ 2D plot. Face interactions are Uncoated, Full Reflecting, Partial Reflecting / Transmitting, or Absorbing / Mechanical.

  3. Assign the solid material and face coatings. A beam-splitter face also needs split ratio, loss, phase, and later P/S/Jones behavior.

  4. Keep On Save: snap Input Port to traced ray enabled for the common prism convention. When roles are saved, the face marked Input Port is centered on the row plane or the selected traced input ray and its outward normal is aligned against the incoming direction. The Up/Down/Front/Back labels provide the roll constraint.

  5. If the input ray is not the row optical axis, select the layout ray/path that should enter the prism and snap the chosen face to that ray instead.

  6. Let the UI solve the object pose, then write only the solved transform back to the surface row.

  7. Validate with a live chief-ray and bundle trace: show hit sequence, face role, incident/outgoing medium, surface normal, Snell/Fresnel/reflection/split decision, and stop reason.

For the standard axial prism workflow, side labels plus port roles are enough to create an initial pose. Mark the entrance face as Input Port; the usual Left side label only tells the YZ plot which side that face represents. Leave the exit face on Auto for the common case, so downstream placement is derived from the traced physical exit. Mark a downstream exit face as Output Port only when you want to override that traced exit and force following elements to be placed from a specific face. Mark reflective, uncoated fold, beam-splitting, or absorbing faces as Interaction Surface so they affect the ray without being treated as entrance/exit ports. General off-axis placement still needs a ray/path target, face-normal flip controls, clear apertures, internal reflecting faces, material/dispersion, and optional virtual internal planes for vendor cube beam splitters whose CAD contains only the outer cube.

The implemented face-role slice is available through Actions -> Assign CAD/STL Optical Faces. The dialog renders the actual STL/CAD mesh at the current row pose and draws transparent selectable overlays plus outlines for the planar face candidates. Click a coloured face in the preview to select that candidate, then assign a 2D side and an Optical function with the quick buttons or the detailed form on the right. A plain click selects; left hold-drag rotates the preview around the current focal point with fixed sensitivity, matching Open 3D instead of VTK’s default accelerated trackball behaviour. Left/Right are along the 2D layout Z direction and Up/Down are along Y; Front/Back are available for full 3D orientation notes. By default, Save Roles also uses the Input Port face as the input-face convention, snaps that face to the current Path view or the outgoing traced segment after the previous table surface, and writes the solved TiltX/Y/Z and DespX/Y/Z pose back to the row. If those are unavailable it uses the nearest traced 3D ray; if no traced ray is available, it falls back to the old row-plane convention: outward normal -Z with incoming ray +Z. Save Roles first applies the currently selected face form, so a separate Apply Form to Selected click is optional for the active selection. For arbitrary prisms, use Fit ref normal on one nonparallel face to fix the remaining roll after the entrance face is aligned. For example, +Y normal means the selected face normal should point upward in the layout; changing it to -Y normal gives the corresponding Y-axis flip. 2D side remains the plot/path label, while Fit ref normal is the 3D orientation constraint. For vendor drawings with an off-center entrance point, use Input snap U/V [mm] on the chosen Input Port face. Save Roles snaps that in-face anchor point, not only the face centroid, to the active traced input ray. Use Pick In 3D to click the previewed face and back-fill those U/V values directly from the chosen world-space point. U prefers the face-plane projection of local +Z; V is the orthogonal in-plane axis. The face list remains available as a fallback and as a compact audit table. The face list emulates cell wrapping from the current column width because Tk’s native tree table does not wrap cell text by itself. Drag a column separator to reflow the visible cells, or double-click a column separator to auto-fit that column to its full content. The Uncoated face mode uses ordinary glass/air Snell-Fresnel physics; total internal reflection is then automatic when the incidence exceeds the critical angle. Split ratio is only shown and editable for faces whose function is Partial Reflecting / Transmitting; phase and loss are enabled only for face functions where those quantities are meaningful. Diffuse transmitting/reflecting behavior is not yet implemented on imported CAD/STL faces; use a Diffuse Object row when the required physics is Lambertian or BRDF-based scattering. If one physical optical interface appears as two CAD faces, such as a split cube-beam-splitter interface, select both face rows with Shift/Ctrl and press Splitter so the same function metadata is applied to both candidates.

For chained CAD/STL work, the UI uses one output-port pose resolver for all views. A downstream CAD solid is displayed and traced from the upstream output port pose, so 2D silhouettes, Open 3D meshes, face-role overlays, and Image planes should stay aligned. If a chained solid looks different in 2D and 3D, that is a resolver bug rather than a drawing preference.

If the installed VTK package does not ship libvtkRenderingTk.so, the dialog uses the Matplotlib/Tk 3D picker directly instead of first trying the broken VTK/Tk widget path. This is expected for the standard pip VTK wheels: they ship the Python vtkTkRenderWindowInteractor wrapper but not the native libvtkRenderingTk.so Tk widget library.

The same dialog now includes a Virtual Internal Plane workbench for cube-style beam-splitter CAD. After labeling the outer Left, Right, Up, and Down faces, use Auto Cube Splitter Plane to derive a saved 45-degree internal diagonal with split, loss, phase, and aperture metadata. The plane is previewed in 3D and stored alongside the face labels inside OpticalSolidFaces.

CAD/STL optical face-assignment dialog with face table, 3D preview, side labels, and optical functions

Actions -> Assign CAD/STL Optical Faces opens the face table, 3D face preview, side labels, and optical-function quick buttons for the selected optical solid row.

The project devenv uses python313Packages.vtk from nixpkgs for the VTK Python module and sets KRAKEN_VTK_TK_LIB_DIR to the same package’s lib directory. kraken-install removes any pip-installed vtk wheel so the venv does not shadow the Nix VTK build. Use devenv shell kraken-vtk-tk-check to verify that the UI can see the native VTK/Tk widget.

For a non-devenv setup, install or build VTK with VTK_USE_TK=ON and make the directory containing libvtkRenderingTk.so visible to the UI. KrakenOS searches the VTK package directory, the Python lib directory, /usr/local/lib, TCLLIBPATH, LD_LIBRARY_PATH, and the explicit KRAKEN_VTK_TK_LIB_DIR or VTK_TK_LIB_DIR environment variables. Keep the Python vtk module and libvtkRenderingTk.so from the same VTK build to avoid ABI mismatches.

Assigned side/function labels are saved with the optical solid row as OpticalSolidFaces metadata and are drawn in the embedded 3D inspector and isolated placement preview as coloured face-centre/normal markers. Snap-to-ray pose solving remains the next scene-object workflow step.

The future prism workflow should validate these cases before it is considered complete:

  • BK7 wedge-prism deviation with the expected media transition

  • right-angle prism total internal reflection

  • classic prism dispersion pose, including visible output steering

  • missed-ray and clipped-ray diagnostics on the selected solid

  • agreement between 2D slice, 3D view, ray inspector, and STEP ray-envelope export

For finite detector apertures, a ray that exits the modeled optical geometry but intersects the detector plane outside the active aperture is drawn to that plane and marked as a missed detector. This is a diagnostic terminal event: the ray is not counted as a detector hit, and the event/analysis CSV records the detector surface, miss radius, active half-aperture, projected distance, normal residual, and original kernel terminal reason.

Use Actions -> Detector Aperture Report when the plot shows clipped or early-terminated rays near a detector. The report does not retrace rays and does not infer detector state from the 2D drawing; it summarizes the active SceneBundle ray-analysis records, so the numbers match Ray Inspector, Ray Events CSV, detector-miss crosshair overlays, and the detector aperture rows in the normal results panel. Ray Inspector CSV also includes normalized per-ray aperture status fields next to the raw detector-miss event metadata.

Vendor CAD caveat: a downloaded cube beam-splitter STEP is usually mechanical geometry, not a complete optical prescription. Import it for external cube boundaries/placement, then add a table Beam Splitter surface or use Insert Component Below -> Cube Beam Splitter for the internal 45 degree coating/path physics. The CAD mesh alone cannot infer coating ratio, phase, or cemented internal splitter behavior.

The new virtual internal plane metadata helps author that missing diagonal and keep it attached to the imported CAD row, but current tracing still follows the closed STL/CAD envelope. Treat the virtual plane as saved authoring intent and 3D preview data for now; use the validated cube primitive or a real Beam Splitter row when you need traced reflected/transmitted branches today.

Face roles do not move or center a CAD/STL solid. They say which imported faces are optically meaningful. To put the cube/prism on the beam, use Actions -> 3D Place/Orient Selected CAD/STL Solid and then Center Row->Ray in the 3D inspector, or edit row TiltX/Y/Z and DespX/Y/Z directly. A future snap solver should combine the selected input face, a clicked beam/path, and a roll/output constraint to solve this placement automatically.

The placement dialog now provides the first explicit anchor/roll slice of that future solver:

  • Anchor face chooses one assigned optical face or Auto.

  • Roll constraint can use the saved side labels as a simple roll guide.

  • Face -> +Z or Face -> -Z aligns the chosen face normal to the layout optical axis, then recenters that face on the row plane.

  • Face -> Ray or Face <- Ray aligns the chosen face to the currently selected traced ray and snaps the face anchor onto the nearest picked point on that ray.

  • Face -> Path or Face <- Path aligns the chosen face to the currently selected Path-view frame and snaps the face anchor onto the nearest point on that traced path axis.

  • Anchor X/Y and Anchor On Row shift the selected face centroid instead of the whole mesh bounding box.

The selected ray can come from the 2D plot, 3D view, or Ray Inspector. The current path frame comes from the top Path dropdown above the 2D plot. This is still not a full output-constrained prism solver, but it is now a real path-frame placement bridge between saved face metadata and traced scene data.

Virtual internal planes are drawn in the embedded 3D inspector and CAD placement preview as translucent diagonal overlays with a normal arrow, so the stored cube-splitter authoring intent remains visible while you place the solid.

The mesh diagnostics report checks triangle count, bounds, open boundary edges, non-manifold edges, degenerate triangles, signed volume, and likely face winding. It cannot certify optical design intent; it only catches the common mesh defects that make a closed prism fail to steer rays according to Snell/reflection laws.

Placement workflow

After importing a CAD/STL solid, first complete the automatically opened face assignment dialog. If the saved Left input convention is not enough, select that row and open Actions -> 3D Place/Orient Selected CAD/STL Solid for manual pose controls. If embedded VTK/Tk is available, the embedded 3D inspector highlights the solid row and opens a CAD/STL placement handler right-side panel inside the 3D inspector. The panel stays visible when the main UI is tiled or fullscreen and does not cover the 3D scene. If only the legacy PyVista viewer is available, the bottom STL row contains the placement buttons. Both paths write the row TiltX, TiltY, TiltZ, DespX, DespY, and DespZ values while the 3D view refreshes.

For scene authoring, row pose is now accompanied by optional ScenePlacement metadata. This stores linear snap spacing, angular snap step, grid visibility, and the intended placement anchor on the surface row, then publishes the same data as ScenePlacement3D records in SceneBundle and the Non-Sequential Scene Graph. Open 3D draws a grid from the selected or first visible placement record and reports the active spacing, extent, snap state, and placement count in the viewer. Plain Object/Image reference targets stay target records and do not create default placement grids or rotation handles; stale ScenePlacement metadata on those reference rows is ignored, and the reference marker size follows the editable row diameter. The colored translation handles move the selected row along global X/Y/Z by ScenePlacement.snap_mm when snap is enabled, or by the placement grid spacing when snap is off. The rotation handles rotate the selected row around global X/Y/Z by ScenePlacement.snap_deg when snap is enabled, or by 15 degrees when snap is off. These actions write the normal row DespX/Y/Z and TiltX/Y/Z fields and record the last placement edit in ScenePlacement metadata. Dragging a placement handle accumulates screen motion and applies repeated snap steps through the same row-backed services; clicking without dragging remains the one-step precise fallback. Snap Row->Target adds the first target-surface constraint tool: click the button, choose the movable surface/CAD row or face, then click the target row or face. The editor solves the translation in world coordinates, writes the normal row DespX/Y/Z fields, and records the target_surface constraint in the row’s ScenePlacement metadata. Orient Row->Target follows the same two-click pattern but solves rotation: the selected row or face normal is aligned to the target row or face normal, the normal row TiltX/Y/Z fields are written, and the solved target_normal constraint is recorded in ScenePlacement metadata. Orient Row->Ray uses the same row-backed rotation service for traced data: click the button, choose the movable surface/CAD row or face, then click a traced ray. The selected row or face normal is aligned to the nearest segment direction of that ray, the normal row TiltX/Y/Z fields are written, and target_ray metadata records the ray index, target vector, nearest point, branch path, source id, and residual angle error. Orient Row->Source and Orient Row->Path are immediate commands for the currently selected or picked row/face. Orient Row->Source aligns the row or face normal to the Source panel aim vector and records source_vector metadata, including source origin, direction, model, and residual angle error. Orient Row->Path aligns the row or face normal to the current Path-view frame near the row/face and records path_frame metadata, including branch path, sample count, origin surface, nearest target point, target vector, and residual angle error. Orient Row->CAD Axis uses the toolbar +X/-X/+Y/-Y/+Z/-Z selector as a row-local axis target after the row’s current world transform is applied. It then writes the solved TiltX/Y/Z and records local_axis metadata, including the target axis row, axis label, axis vector, target vector, and residual angle error. Orient Row->Scene Source aligns the selected row or face normal to a Scene Source Manager source. If a source row is selected in the editable table, that source is used; otherwise the first enabled physical source is used. The command records scene_source_vector metadata, including source id/name, origin, direction, model, ray count, target vector, and residual angle error. The named normal selector uses the first matching scene target for Active target, Detector, or Object. Preview Normal reports the target row, role, normal vector, target point, and current angle error without changing the prescription. Orient Row->Normal applies the same row-backed rotation service and records active_target_normal, detector_normal, or object_normal metadata, including the target row/id/name/role, target point, target normal, and residual angle error. These diagnostics appear in the Non-Sequential Scene Graph and CSV export beside the row-backed ScenePlacement record.

Use Fit+Z, Fit+X, or Fit+Y to state which STL-local axis should become the layout optical axis (layout +Z). For example, use Fit+Z when the prism was modeled along local Z, or Fit+X when the CAD model’s length is local X. Center translates the rotated mesh so its X/Y bounding-box centre lies on the optical axis. Front translates the rotated mesh so its minimum Z bound sits on the selected row plane.

The embedded handler also provides one-click X/Y/Z +/-90 rotations, Center X/Y, Front On Row, and Done -> 2D. Closing only the handler keeps the 3D view open; pressing Done -> 2D refreshes the 2D plot from the same row pose.

If OpticalSolidFaces metadata is present on the selected row, the 3D view draws assigned side/function labels as coloured markers:

  • grey: side-only or unassigned function

  • blue: Transmit/Port and legacy TIR metadata

  • silver: Mirror

  • red: Beam Splitter

  • black: Absorber/Mechanical

Use the Faces... button in the embedded 3D inspector, or Assign Optical Faces in the isolated placement preview, to reopen the role editor for the selected solid. After saving roles, press Refresh or Render to redraw the markers.

Use Center Row->Ray when manual CAD placement is hard to judge visually. Click the button, click the surface/CAD row to move, then click the target ray. For ordinary rows the editor computes the selected row’s surface plane, finds where the picked ray crosses that plane, and writes the row DespX/Y/Z values so the surface center moves onto the ray without changing the row orientation. For file-backed CAD/STL solids with saved OpticalSolidFaces metadata, the same action now prefers the best assigned optical-face anchor instead of the generic row center. That makes snap-to-ray placement more useful for prisms and vendor CAD where the meaningful optical entry face is not the mesh centroid. This is still an alignment aid; use Fit Axis and Min Z On Row first when the CAD solid also needs orientation or front-face placement.

KrakenOS placement semantics are important:

  • the previous row’s Thickness sets the selected CAD/STL row’s nominal Z station

  • TiltX/Y/Z rotate the STL mesh about the STL file origin

  • DespX/Y/Z translate the rotated STL mesh

  • AxisMove affects transform propagation to later rows, not the local STL orientation itself

STEP and CAD overlays

STEP support is beyond the 2021 manual but is available in the UI for real hardware context:

  • lens/camera/LED STEP import from the main File menu or directly from the Open 3D CAD / target -> Import STEP menu

  • imported STEP carry placement in Open 3D: after a 3D import, or after choosing CAD / target -> Carry Selected STEP, dragging inside the scene moves the selected lens/camera/LED STEP overlay by discrete steps on an automatically sized cube grid

  • CAD axis offset picking

  • selected STEP overlay rotation through in-scene coloured X/Y/Z rotation handles around the selected lens, camera, or LED STEP component; clicking a handle applies a persistent +/-90 degree step without opening a floating popup

  • selected CAD/STL row placement through a click-open CAD/STL placement handler with axis-fit, rotation, centering, front-plane, and Done -> 2D actions

  • active 3D workflow badges for Center STEP Axis, Obj->LED, Center Row->Ray, Snap Row->Target, Orient Row->Target, Orient Row->Ray, and Source Target pick modes

  • immediate selected-row orientation commands for Orient Row->Source, Orient Row->Path, Orient Row->CAD Axis, and Orient Row->Scene Source

  • STEP export

  • external camera overlay workflows

When imported vendor STEP CAD is present, Export 3D STEP preserves the original imported STEP BReps, applies the same placement transform used by the 3D view, and adds only the outer traced ray envelope as thin solid STEP tubes. The ray envelope is exported as renderable solid geometry because several CAD viewers import STEP wire curves but do not display them by default. This keeps mechanical review focused on clearance and beam footprint instead of every individual preview ray. File size is expected to be at least the sum of the imported vendor STEP files plus the ray envelope tubes and analytic optical surfaces.